Files
homegate/SSH.md
DizelBadCoder 357daa8915
Some checks failed
Test and publish Homegate / checks (push) Has been cancelled
Test and publish Homegate / publish (push) Has been cancelled
Initial Homegate 0.4.0 with web UI, Compose and Gitea Actions
2026-10-14 01:40:14 +03:00

10 KiB
Raw Permalink Blame History

Общий SSH-конфиг в локальной сети

Добавьте секцию ssh к нужному веб-сервису. SSH-адрес по умолчанию берётся из IP его upstream; при необходимости задайте другой ssh.host:

services:
  - hostname: pve.home
    upstream: https://192.168.0.137:8006
    upstream_tls_verify: false
    ssh:
      alias: pve
      user: root
      port: 22

Выгрузка содержит:

Host pve pve.home
    HostName 192.168.0.137
    Port 22
    User root
    StrictHostKeyChecking ask

ssh pve и ssh pve.home подключаются напрямую к VM, а не к NPM. Без этого Include обычное DNS-разрешение pve.home возвращает NPM, предназначенный для HTTPS. Это не SSH-прокси и не SSH-сервер: на целевой машине должен уже работать sshd, а ключи авторизации и доступ из LAN на нужный порт настраиваются отдельно.

Для машин без веб-сервиса есть независимый список. DNS/Proxy Host для них не создаётся:

ssh_hosts:
  - aliases: [backup, backup.lab.internal]
    host: 192.168.0.150
    port: 2222
    user: admin

Секция ssh необязательна. Если её нет, сервис не включается в выгрузку. user тоже необязателен: тогда применяется личный SSH-конфиг/имя пользователя ПК. Для отключения экспорта одного сервиса используйте ssh.enabled: false; enabled: false у веб-сервиса также исключает его из SSH-конфига. Записи ssh_hosts поддерживают собственный enabled. Алиасы должны быть уникальными, без wildcard, пробелов и управляющих конструкций. SSH HostName может быть RFC1918 IPv4 или ULA IPv6.

Адрес выгрузки

В .env укажите IP Docker-хоста Homegate, который может отличаться от IP NPM:

SSH_BIND_IP=192.168.0.10
SSH_PORT=8099

В config/services.yaml задайте свою подсеть:

allowed_networks:
  - 192.168.0.0/24

После docker compose up -d --build файл доступен по адресу:

http://192.168.0.10:8099/ssh-config

Замените .10 своим адресом. Список генерируется при каждом запросе из текущего YAML, поэтому изменение адреса/порта или удаление SSH-записи отражается сразу и не требует доступных Pi-hole/NPM. При невалидной конфигурации сервер возвращает HTTP 503. Для просмотра без HTTP можно выполнить docker compose run --rm homegate ssh-config; эта команда не использует API и не блокирует работающий контроллер.

Выгрузка открыта без логина только разрешённым IP. Она содержит топологию сети и имена пользователей, но не приватные ключи, пароли, CA или SSH host keys. Сервер не раздаёт каталоги и игнорирует X-Forwarded-For при проверке клиента. В контейнер ssh-export вообще не монтируются ключ CA и пароли управления.

Docker публикует порт на конкретном адресе хоста; это описано в документации Docker. Не пробрасывайте этот порт из WAN и не включайте для него UPnP. Привязка IP и ACL не заменяют firewall, если перед сервером стоит NAT, подменяющий внешний IP разрешённым LAN-адресом. На Docker Desktop источник может выглядеть иначе, чем на Linux; эта конфигурация рассчитана на Linux-хост с сохранением исходного IP клиента.

Подключение на ПК

Скопируйте sync_ssh.py из проекта на ПК. Нужны Python 3.9+ и OpenSSH; дополнительные Python-пакеты не требуются. Первый запуск на Linux/macOS:

python3 sync_ssh.py http://192.168.0.10:8099/ssh-config --install
ssh pve

На Windows с Python и OpenSSH Client:

py -3 sync_ssh.py http://192.168.0.10:8099/ssh-config --install
ssh pve

Скрипт сохраняет отдельный файл ~/.ssh/config.d/homegate.conf. Флаг --install один раз добавляет в конец основного ~/.ssh/config блок Host * с Include на абсолютный путь этого файла. Перед изменением основной файл копируется в config.before-homegate-*. Повторный запуск не дублирует Include. На Windows используется .ssh в профиле пользователя. Другой каталог можно задать через --ssh-dir; OpenSSH сам должен быть настроен читать находящийся там основной конфиг, например через ssh -F /path/config pve.

Существующие настройки имеют приоритет по правилу первого значения OpenSSH. Приватные ключи и IdentityFile задавайте в личном конфиге:

Host pve
    IdentityFile ~/.ssh/id_ed25519_homelab
    IdentitiesOnly yes

Этот блок разместите до Homegate Include. Если прежде был Host * с User или Port, он также имеет приоритет перед загруженными значениями. При необходимости переместите весь блок Homegate Include выше общих настроек, сохранив его маркеры. Проверить результат без подключения: ssh -G pve. OpenSSH описывает порядок применения и Include.

Скрипт не меняет NTFS ACL на Windows: используйте обычный приватный каталог профиля, не общую сетевую папку. Windows-вариант написан на стандартной библиотеке Python, но отдельно на Windows не запускался. Symlink основного конфига автоматически не перезаписывается: в таком случае добавьте Include вручную и запускайте скрипт без --install.

Обновление

Для последующих обновлений достаточно той же команды без --install:

python3 sync_ssh.py http://192.168.0.10:8099/ssh-config

Обновление атомарное: при ошибке сети или проверок старый файл сохраняется. Удалённые SSH-записи исчезают из дополнительного файла при следующем успешном обновлении. Основной конфиг и known_hosts при обновлении не меняются. Файл на ПК обновляется только при запуске скрипта; автоматическое расписание не создаётся. На Linux/macOS файл получает права 0600, каталог — 0700.

Скрипт принимает только Host, HostName, Port, User и StrictHostKeyChecking ask, проверяет значения и заново собирает текст перед записью. Скачанные ProxyCommand, Match exec, вложенные Include, глобальные wildcard-настройки и выключение проверки SSH host key отклоняются. Первый SSH-вход требует проверки отпечатка ключа сервера обычным способом. Скрипт не выполняет скачанный код, не следует HTTP-редиректам и не использует прокси из переменных окружения.

HTTPS для загрузки

HTTP не защищает список адресов от подмены внутри LAN. Для аутентифицированной загрузки добавьте HTTPS Proxy Host через существующий NPM на exporter, включив в services:

- hostname: config.home
  upstream: http://192.168.0.10:8099

Тогда на ПК:

python3 sync_ssh.py https://config.home/ssh-config --ca-file root-ca.crt --install

Это опциональный маршрут; домен должен входить в domain_zones. NPM применяет LAN ACL к клиенту; exporter должен видеть разрешённый LAN-IP NPM. Если Docker NAT показывает другой адрес, настройте сетевой путь или узкое правило для этого конкретного адреса, не разрешайте весь Docker subnet без необходимости. Проверка HTTPS у скрипта всегда включена. Корневой сертификат берите по доверенному каналу из state/root-ca.crt. Ни HTTP-, ни HTTPS-вариант не требует логина для скачивания из LAN.