Initial Homegate 0.4.0 with web UI, Compose and Gitea Actions
This commit is contained in:
175
SSH.md
Normal file
175
SSH.md
Normal file
@@ -0,0 +1,175 @@
|
||||
# Общий 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.
|
||||
Reference in New Issue
Block a user