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

176 lines
10 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Общий SSH-конфиг в локальной сети
Добавьте секцию `ssh` к нужному веб-сервису. SSH-адрес по умолчанию берётся из IP
его `upstream`; при необходимости задайте другой `ssh.host`:
```yaml
services:
- hostname: pve.home
upstream: https://192.168.0.137:8006
upstream_tls_verify: false
ssh:
alias: pve
user: root
port: 22
```
Выгрузка содержит:
```sshconfig
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 для них не создаётся:
```yaml
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:
```dotenv
SSH_BIND_IP=192.168.0.10
SSH_PORT=8099
```
В `config/services.yaml` задайте свою подсеть:
```yaml
allowed_networks:
- 192.168.0.0/24
```
После `docker compose up -d --build` файл доступен по адресу:
```text
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](https://docs.docker.com/engine/network/port-publishing/).
Не пробрасывайте этот порт из WAN и не включайте для него UPnP. Привязка IP и ACL
не заменяют firewall, если перед сервером стоит NAT, подменяющий внешний IP разрешённым
LAN-адресом. На Docker Desktop источник может выглядеть иначе, чем на Linux;
эта конфигурация рассчитана на Linux-хост с сохранением исходного IP клиента.
## Подключение на ПК
Скопируйте `sync_ssh.py` из проекта на ПК. Нужны Python 3.9+ и OpenSSH;
дополнительные Python-пакеты не требуются. Первый запуск на Linux/macOS:
```sh
python3 sync_ssh.py http://192.168.0.10:8099/ssh-config --install
ssh pve
```
На Windows с Python и OpenSSH Client:
```powershell
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` задавайте в личном конфиге:
```sshconfig
Host pve
IdentityFile ~/.ssh/id_ed25519_homelab
IdentitiesOnly yes
```
Этот блок разместите **до** Homegate Include. Если прежде был `Host *` с `User` или
`Port`, он также имеет приоритет перед загруженными значениями. При необходимости
переместите весь блок Homegate Include выше общих настроек, сохранив его маркеры.
Проверить результат без подключения: `ssh -G pve`.
OpenSSH описывает [порядок применения и Include](https://man.openbsd.org/ssh_config#Include).
Скрипт не меняет NTFS ACL на Windows: используйте обычный приватный каталог профиля,
не общую сетевую папку. Windows-вариант написан на стандартной библиотеке Python,
но отдельно на Windows не запускался. Symlink основного конфига автоматически не
перезаписывается: в таком случае добавьте Include вручную и запускайте скрипт без `--install`.
## Обновление
Для последующих обновлений достаточно той же команды без `--install`:
```sh
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`:
```yaml
- hostname: config.home
upstream: http://192.168.0.10:8099
```
Тогда на ПК:
```sh
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.