Initial Homegate 0.4.0 with web UI, Compose and Gitea Actions
Some checks failed
Test and publish Homegate / checks (push) Has been cancelled
Test and publish Homegate / publish (push) Has been cancelled

This commit is contained in:
2026-10-14 01:40:14 +03:00
commit 357daa8915
33 changed files with 4032 additions and 0 deletions

11
.dockerignore Normal file
View File

@@ -0,0 +1,11 @@
*
!Dockerfile
!requirements.txt
!homegate.py
!sync_ssh.py
!homegate_ui.py
!ui/
!ui/dist/
!ui/dist/**
!bootstrap.py
!VERSION

19
.env.example Normal file
View File

@@ -0,0 +1,19 @@
# IP/port of EXISTING Nginx Proxy Manager management UI, without /api.
NPM_URL=http://192.168.0.10:81
NPM_IDENTITY=admin@example.com
# Pi-hole 6 web interface, without /admin or /api; not DNS port 53.
PIHOLE_URL=http://192.168.0.2
# LAN IP of the Docker HOST running Homegate (may differ from proxy_ip/NPM).
# SSH export is anonymous within allowed_networks; never use 0.0.0.0 here.
SSH_BIND_IP=192.168.0.10
SSH_PORT=8099
# Management panel: password protected and LAN-only. Must match the browser URL.
UI_BIND_IP=192.168.0.10
UI_PORT=8098
UI_ORIGIN=http://192.168.0.10:8098
# For HTTPS management APIs with a private CA, copy its PEM bundle into config/
# and set API_CA_BUNDLE=/config/management-ca.pem
API_CA_BUNDLE=
# Written by setup.sh to match ownership of secrets/ and state/ on Linux.
LOCAL_UID=1000
LOCAL_GID=1000

View File

@@ -0,0 +1,105 @@
name: Test and publish Homegate
"on":
push:
branches: ['**']
tags: ['v*']
pull_request:
# Use a dedicated Linux runner labelled homegate:host; see REGISTRY.md.
permissions:
contents: read
jobs:
checks:
runs-on: homegate
steps:
- name: Checkout
uses: https://github.com/actions/checkout@v4
with:
github-server-url: ${{ gitea.server_url }}
token: ${{ secrets.GITEA_TOKEN }}
persist-credentials: false
- name: Python environment
shell: bash
run: |
set -euo pipefail
test_env="$(mktemp -d "$RUNNER_TEMP/homegate-python.XXXXXX")"
printf 'TEST_PYTHON=%s/bin/python\n' "$test_env" >> "$GITHUB_ENV"
printf 'TEST_ENV=%s\n' "$test_env" >> "$GITHUB_ENV"
python3 -m venv "$test_env"
"$test_env/bin/python" -m pip install -r requirements.txt
- name: Unit and HTTP tests
run: '"$TEST_PYTHON" -m unittest discover -s tests -v'
- name: JavaScript and shell syntax
run: |
node --check ui/dist/app.js
for script in setup.sh run-local.sh ci/smoke_image.sh; do sh -n "$script"; done
- name: Compose contracts
env:
PYTHONPATH: .
run: '"$TEST_PYTHON" ci/check_compose.py'
- name: Build and smoke-test runtime image
env:
CI_REVISION: ${{ gitea.sha }}
run: |
set -eu
test_image="homegate-ci:$CI_REVISION-$$"
trap 'docker image rm "$test_image" >/dev/null 2>&1 || true' EXIT
docker build --build-arg VERSION="$(cat VERSION)" --tag "$test_image" .
sh ci/smoke_image.sh "$test_image"
- name: Clean Python environment
if: always()
shell: bash
run: |
if [ -n "${TEST_ENV:-}" ]; then rm -rf -- "$TEST_ENV"; fi
publish:
needs: checks
if: gitea.event_name == 'push' && startsWith(gitea.ref, 'refs/tags/v')
runs-on: homegate
env:
DOCKER_BUILD_SUMMARY: "false"
DOCKER_BUILD_RECORD_UPLOAD: "false"
steps:
- name: Checkout release
uses: https://github.com/actions/checkout@v4
with:
github-server-url: ${{ gitea.server_url }}
token: ${{ secrets.GITEA_TOKEN }}
persist-credentials: false
- name: Validate release identity
id: image
env:
CI_SERVER_URL: ${{ gitea.server_url }}
CI_REPOSITORY: ${{ gitea.repository }}
CI_REF: ${{ gitea.ref }}
CI_REVISION: ${{ gitea.sha }}
REGISTRY: ${{ vars.REGISTRY }}
run: python3 ci/image_metadata.py
- name: Configure cross-platform emulation
uses: https://github.com/docker/setup-qemu-action@v3
with:
platforms: amd64,arm64
- name: Configure Buildx
uses: https://github.com/docker/setup-buildx-action@v3
- name: Log in to Gitea Container Registry
uses: https://github.com/docker/login-action@v3
with:
registry: ${{ steps.image.outputs.registry }}
username: ${{ secrets.REGISTRY_USERNAME }}
password: ${{ secrets.REGISTRY_TOKEN }}
- name: Publish AMD64 and ARM64 image
uses: https://github.com/docker/build-push-action@v6
with:
context: .
platforms: linux/amd64,linux/arm64
push: true
build-args: |
VERSION=${{ steps.image.outputs.version }}
tags: |
${{ steps.image.outputs.image }}:${{ steps.image.outputs.version }}
${{ steps.image.outputs.image }}:sha-${{ steps.image.outputs.revision }}
labels: |
org.opencontainers.image.source=${{ steps.image.outputs.source }}
org.opencontainers.image.revision=${{ steps.image.outputs.revision }}
provenance: false

10
.gitignore vendored Normal file
View File

@@ -0,0 +1,10 @@
.env
state/
secrets/
control/
config/backups/
config/.ui-config.lock
__pycache__/
*.pyc
.venv/
.local/

81
DOMAINS.md Normal file
View File

@@ -0,0 +1,81 @@
# Кастомные доменные зоны
До первого запуска задайте все нужные зоны в `config/services.yaml`:
```yaml
domain_zones:
- home
- home.arpa
- lab.internal
- dev.example.net
```
После этого допустимы, например, `pve.home`, `nas.home.arpa`, `grafana.lab.internal`
и `git.dev.example.net`. Поддерживаются поддомены любой глубины и apex зоны с точкой,
например `dev.example.net`. Wildcard-сертификаты и wildcard DNS не создаются;
каждый веб-сервис имеет отдельное имя, DNS-запись и сертификат.
Если `domain_zones` отсутствует в старом конфиге, сохраняются прежние `home` и `home.arpa`.
Начальная/конечная точка зоны и регистр нормализуются; имена самих сервисов должны быть
в нижнем регистре. IDN задавайте в ASCII/punycode. Проверяются границы DNS-меток:
зона `home` не разрешает `pve.evilhome`.
При использовании реального домена выбирайте принадлежащую вам зону. Записи остаются
локальными в Pi-hole; регистрации домена или публикации публичного DNS Homegate не делает.
Публичный сертификат автоматически не появляется: все зоны обслуживает локальный CA.
Для домашнего использования предпочтительна `home.arpa` по
[RFC 8375](https://www.rfc-editor.org/rfc/rfc8375.html).
Избегайте `.local`, зарезервированной для [mDNS](https://www.rfc-editor.org/rfc/rfc6762.html#section-3)
и обрабатываемой клиентами иначе, чем обычный DNS.
Новый корневой CA содержит ограничения `NameConstraints` для зон первого запуска.
Добавление нового хоста или дочерней зоны внутри уже разрешённого суффикса не меняет CA.
Удаление зоны сужает политику выпуска Homegate, но не отзывает старые сертификаты и
не меняет доверие уже установленного корня. Удаляемые из зоны маршруты нужно также
убрать из YAML; правила сохранения/ручного удаления NPM-объектов описаны в README.
## Добавление зоны за пределами существующего CA
Если CA уже создан и новая зона **вне его ограничений**, Homegate не выпускает для неё
заведомо недоверенный сертификат. Смена корневого сертификата никогда не запускается
автоматически. Для расширения выполните явную миграцию:
```sh
# Сначала измените domain_zones и маршруты в config/services.yaml.
docker compose stop homegate
docker compose run --rm homegate rotate-ca
# Скопируйте новый state/root-ca.crt на клиенты и установите доверие.
docker compose up -d homegate
```
`rotate-ca` сохраняет прежние `ca.json` и `root-ca.crt` в `state/ca-history/`, создаёт
новый ключ/корень и сохраняет `registry.json`, поэтому объекты NPM остаются теми же.
При следующем запуске сертификаты активных маршрутов перевыпускаются под новым корнем
и nginx перечитывает их. Установите новый корень на клиенты перед возобновлением контроллера;
до этого NPM продолжает отдавать прежние сертификаты. После перехода удалите доверие к
старому CA. Для удалённых из YAML маршрутов сертификаты не перевыпускаются автоматически.
Резервная копия CA содержит приватный ключ и должна оставаться защищённой.
Для установки, которая ещё не запускалась, достаточно изменить `domain_zones` до
первого `docker compose up`: менять CA и устанавливать его второй раз не потребуется.
## Обновление с 0.1
Замените исходники, Dockerfile и Compose. Сохраните свои `.env`, `config/`, `state/`
и `secrets/`; не заменяйте настроенный YAML примером из архива. Добавьте в `.env`:
```dotenv
SSH_BIND_IP=192.168.0.10
SSH_PORT=8099
```
Замените IP на LAN-IP Docker-хоста Homegate и выполните:
```sh
docker compose up -d --build
```
Новые зоны добавляйте намеренно. Старый конфиг без `domain_zones` продолжает работать.
Существующий CA 0.1 разрешает `home` и `home.arpa`; для `lab.internal` или иной новой
зоны примените миграцию выше. Настройки SSH в существующих сервисах добавляются отдельно
по [инструкции](SSH.md).

13
Dockerfile Normal file
View File

@@ -0,0 +1,13 @@
FROM python:3.13-slim-bookworm
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY homegate.py sync_ssh.py homegate_ui.py bootstrap.py VERSION .
COPY ui/dist ./ui/dist
ARG VERSION=0.4.0
LABEL org.opencontainers.image.title="Homegate" \
org.opencontainers.image.description="LAN DNS, HTTPS and SSH management for Pi-hole and NPM" \
org.opencontainers.image.version=$VERSION
USER 1000:1000
ENTRYPOINT ["python", "/app/homegate.py"]
CMD ["run"]

341
README.md Normal file
View File

@@ -0,0 +1,341 @@
# Homegate 0.4
Дополнение к **существующим Pi-hole и Nginx Proxy Manager** для домашней сети:
```text
https://pve.home → NPM:443 → https://192.168.0.137:8006
```
Вы описываете сервисы в `config/services.yaml`. Homegate создаёт локальные DNS-записи,
сертификаты и Proxy Hosts, затем поддерживает их актуальными. Развёртывание — Docker Compose.
Веб-панель Homegate управляет сервисами, доменными зонами, SSH и настройками сети.
Отдельный контейнер публикует SSH-конфиг без авторизации для устройств домашней подсети.
Новое в 0.4: [один Compose-файл, готовый образ и Gitea Actions](REGISTRY.md).
Также доступны: [веб-панель и локальный запуск](WEB.md), [SSH-конфиг и скрипт для ПК](SSH.md), [кастомные доменные зоны и миграция CA](DOMAINS.md).
**Для HTTPS без предупреждений нужно один раз установить `root-ca.crt` на каждое
клиентское устройство.** Для внутренних имён `.home` публичный сертификат Let's Encrypt
не подходит. Установка корневого сертификата на сервер не устанавливает доверие на
телефонах и компьютерах. Доверие к локальному CA описано в
[документации Let's Encrypt](https://letsencrypt.org/docs/certificates-for-localhost/).
Зоны настраиваются списком `domain_zones`: например `home`, `home.arpa`, `lab.internal`,
`lab.example.net`. Поддерживаются несколько зон одновременно и несколько уровней
поддоменов; каждому имени выпускается отдельный сертификат. В примере сохранено `pve.home`.
Для новой домашней зоны стандарт рекомендует `home.arpa`:
[RFC 8375](https://www.rfc-editor.org/rfc/rfc8375.html).
## Как это работает
```mermaid
flowchart LR
Browser[Браузер с доверенным Root CA] -->|DNS: pve.home| PiHole[Pi-hole]
PiHole -->|192.168.0.10 — адрес NPM| Browser
Browser -->|HTTPS :443| NPM[Nginx Proxy Manager]
NPM -->|HTTPS :8006| PVE[Proxmox 192.168.0.137]
Controller[Homegate] -->|DNS API| PiHole
Controller -->|Сертификаты и Proxy Hosts| NPM
```
DNS указывает на **NPM**, а не на Proxmox. Порт и протокол целевой VM выбирает NPM
по имени из запроса. Это обратный прокси, адрес в браузере остаётся `https://pve.home`.
Контроллер Homegate не публикует портов, не требует Docker socket и не запускает второй DNS или nginx.
Сервис `ssh-export` публикует HTTP-порт `8099` на явно заданном LAN-IP и проверяет
клиента по `allowed_networks`. Он не имеет доступа к `state/` и паролям API.
Он может работать на отдельной Linux VM с доступом к API вашего Pi-hole и NPM.
Образ пока не опубликован. `compose.yaml` собирает его из исходников;
`compose.registry.yaml` скачивает готовый образ после публикации через Gitea Actions.
Для запуска только по одному файлу, без исходников и setup.sh, см. [REGISTRY.md](REGISTRY.md).
## Требования и границы проверки
- Linux-хост с Docker Engine и Docker Compose v2+; архитектура amd64 или arm64.
- Существующий NPM 2.x; интеграция сверена с исходниками **2.16.0**. Для других версий
сначала проверьте запуск на одном имени. API NPM может меняться.
- **Pi-hole 6** для автоматического DNS. Для Pi-hole 5 или неподдерживаемого API
используйте `dns_mode: manual` и добавьте записи через интерфейс Pi-hole.
- Стабильные адреса Pi-hole, NPM и VM; NPM должен принимать HTTPS на LAN-порту 443.
- Все клиенты используют Pi-hole как DNS. Публичный «резервный DNS», browser DoH,
Android Private DNS и VPN могут обходить локальный DNS. В IPv6 настройте DNS через
RA/DHCPv6 тоже. Используйте второй локальный Pi-hole для резервирования.
- Если Pi-hole и NPM на одном IP, их web-порты должны различаться: например NPM
`80/81/443`, Pi-hole web `8080`, DNS `53`. Homegate этот конфликт автоматически не исправляет.
Проверены Compose-конфигурация, shell-синтаксис и 55 тестов: сертификаты, настоящее TLS-рукопожатие
в стандартных и кастомных зонах, продление, повторный запуск, конфликты, ошибки API,
смена CA, HTTP-обработчик выгрузки, LAN ACL и отказ опасных SSH-директив.
Подключение дополнительного файла также проверено настоящим `ssh -G` с сохранением личных настроек.
HTTP API в тестах имитируются по официальным контрактам. **Запуск образа, реальные API NPM/Pi-hole,
HTTPS-сервисы и noVNC на вашем сервере ещё не проверены:** локальная служба Docker при подготовке не работала.
## Быстрый запуск из исходников
Запуск готового образа описан отдельно в [REGISTRY.md](REGISTRY.md).
Распакуйте каталог `homegate` на сервере и перейдите в него. Команды ниже выполняются из этого каталога.
### 1. Подготовьте конфигурацию и пароли
```sh
sh setup.sh
```
Скрипт создаёт `.env`, `secrets/`, `state/` и `control/`, запрашивает пароли скрытым вводом,
записывает UID/GID текущего пользователя. Он не подключается к вашему homelab.
Для NPM используйте учётную запись с правами управления Proxy Hosts и сертификатами;
администратор имеет нужные права. В `NPM_IDENTITY` укажите её email.
Измените `.env`; адреса `.10` и `.2` ниже — **примеры**, замените их своими:
```dotenv
NPM_URL=http://192.168.0.10:81
NPM_IDENTITY=admin@example.com
PIHOLE_URL=http://192.168.0.2
SSH_BIND_IP=192.168.0.10
SSH_PORT=8099
UI_BIND_IP=192.168.0.10
UI_PORT=8098
UI_ORIGIN=http://192.168.0.10:8098
```
`SSH_BIND_IP` — LAN-IP Docker-хоста Homegate, который может отличаться от IP NPM.
`NPM_URL` и `PIHOLE_URL` — адреса административных интерфейсов, **без `/api` и `/admin`**. Если Pi-hole web
на порту 8080, укажите `http://192.168.0.2:8080`. `localhost` внутри контейнера означает
сам Homegate. Для управления через HTTPS скопируйте доверенный PEM CA bundle в `config/`
и задайте `API_CA_BUNDLE=/config/management-ca.pem`. Проверка TLS у API всегда включена.
HTTP передаёт пароли и сертификаты без шифрования; используйте его только внутри доверенной
сети управления или общей закрытой Docker-сети. Для изолированной Docker-сети добавьте её
как external network в Compose и используйте имена контейнеров.
Для **Pi-hole application password** нужно разрешение на изменение конфигурации.
В существующий Compose Pi-hole добавьте:
```yaml
environment:
FTLCONF_webserver_api_app_sudo: "true"
```
Затем пересоздайте только сервис Pi-hole из его собственного Compose-проекта.
Альтернатива — обычный пароль администратора без 2FA. При 2FA нужен application password.
`app_sudo` даёт приложению широкие права изменения настроек, а не только DNS;
это свойство [API Pi-hole](https://docs.pi-hole.net/ftldns/configfile/#app_sudo).
Не задавайте `FTLCONF_dns_hosts` через environment Pi-hole при автоматическом управлении:
такая настройка становится read-only для API.
### 2. Опишите маршруты
В `config/services.yaml` замените `proxy_ip` на LAN-IP NPM и `allowed_networks` на вашу подсеть:
```yaml
proxy_ip: 192.168.0.10
domain_zones: [home, home.arpa, lab.internal]
allowed_networks:
- 192.168.0.0/24
dns_mode: pihole6
interval_seconds: 60
services:
- hostname: pve.home
upstream: https://192.168.0.137:8006
upstream_tls_verify: false
websocket: true
timeout_seconds: 3600
max_body_mb: 10240
ssh:
alias: pve
user: root
port: 22
- hostname: grafana.home
upstream: http://192.168.0.120:3000
```
VM-адреса в этой версии — **IPv4**, RFC1918. Upstream должен быть веб-сервисом HTTP(S),
без пути, query и встроенного пароля. Для SSH, базы данных и произвольного TCP такая
конфигурация не подходит. Локальные IPv6 ULA можно использовать в `proxy_ip` и списке
допустимых сетей; для dual-stack DNS дополнительные записи задаются вручную в manual-режиме.
### 3. Соберите и запустите
```sh
docker compose build
docker compose run --rm homegate validate
docker compose up -d
docker compose logs -f --tail=100 homegate
```
`validate` проверяет только файл и ничего не меняет в Pi-hole/NPM.
Панель открывается по `UI_ORIGIN`, вход — паролем панели, заданным в `setup.sh`.
Подробнее: [веб-панель, резервные копии и HTTPS](WEB.md).
После старта ожидаются сообщения `Created local root CA`, `Configured https://pve.home ...`
и `DNS: pve.home -> ...`. Сертификат для клиентов появится в `state/root-ca.crt`.
`healthy` означает успешную синхронизацию API, а не доступность целевой VM.
Первичная сборка скачивает базовый образ и Python-зависимости из интернета. После сборки
работа и продление сертификатов не требуют интернета, публичного DNS или публичного ACME.
Для полностью офлайн-сервера предварительно соберите образ на машине той же архитектуры
и перенесите через `docker save homegate:0.4.0` / `docker load`, затем используйте
`docker compose up -d --no-build`.
### 4. Установите корневой сертификат на клиенты
Копируйте на устройства **только `state/root-ca.crt`** через доверенный канал, например SCP.
Сверьте SHA-256 с сервером:
```sh
docker compose exec homegate python /app/homegate.py fingerprint
```
Публичный корень также можно скачать в панели на странице «Сертификаты».
Сверяйте его отпечаток с сервером. Никогда не передавайте клиентам `ca.json`,
`issued/`, `registry.json` или весь `state/`: там находятся закрытые ключи.
| Клиент | Установка доверия |
|---|---|
| Windows | Импорт `root-ca.crt` в «Доверенные корневые центры сертификации» для нужного пользователя или компьютера. Перезапустите браузер. |
| macOS | «Связка ключей» → System → импорт сертификата → Trust → SSL: Always Trust. Потребуются права администратора. |
| Debian / Ubuntu | `sudo cp root-ca.crt /usr/local/share/ca-certificates/homegate.crt` и `sudo update-ca-certificates`. |
| iPhone / iPad | Установите профиль сертификата; затем Settings → General → About → Certificate Trust Settings → Enable Full Trust для Homegate. |
| Android | Настройки безопасности → установка сертификата CA; путь зависит от производителя. Некоторые приложения не доверяют пользовательским CA. |
| Firefox / отдельные приложения | Если системное доверие не подхватилось, импортируйте CA в собственное хранилище Authorities приложения с доверием для сайтов. |
На iOS одного импорта недостаточно: [Apple описывает отдельное включение SSL-доверия](https://support.apple.com/en-gb/102390).
Результат зависит от хранилища доверия конкретного браузера/приложения; некоторые устройства
не позволяют добавлять CA. В этом случае вариант — принадлежащий вам публичный домен
и DNS-01 сертификат с локальными DNS-записями; такое имя будет, например,
`pve.lab.your-domain.example`, а не `pve.home`. DNS-01 не требует публикации самого сервиса
в интернет: [Let's Encrypt](https://letsencrypt.org/docs/challenge-types/#dns-01-challenge).
### 5. Проверьте маршрут
На клиенте, заменив адреса Pi-hole и NPM на реальные:
```sh
nslookup pve.home 192.168.0.2
curl --cacert root-ca.crt --resolve pve.home:443:192.168.0.10 https://pve.home/ -I
curl --cacert root-ca.crt https://pve.home/ -I
```
DNS должен вернуть IP NPM. Первая команда `curl` проверяет HTTPS независимо от DNS;
вторая — вместе с DNS. Не используйте `-k`: он скрывает ошибки доверия.
Откройте **`https://pve.home`**, выполните вход в Proxmox и проверьте noVNC/Shell.
## Особенности Proxmox и TLS
WebSocket, часовые proxy-timeouts, отключение буферизации и лимит тела 10 GiB уже
заданы в примере. Лимит можно увеличить через `max_body_mb`. NPM передаёт имя запроса
и заголовки прокси штатным шаблоном. При необходимости доверенных прокси или корректного
внешнего URL в других приложениях настройте эти приложения отдельно.
У HTTPS есть два участка:
1. **Браузер → NPM:** сертификат `pve.home`, подписанный Homegate CA; клиент проверяет
имя и цепочку после установки CA.
2. **NPM → Proxmox:** TLS со штатным сертификатом Proxmox. В примере проверка этого
сертификата явно выключена через `upstream_tls_verify: false`. Шифрование есть,
но подлинность upstream не проверяется. Это не меняет доверие браузера к NPM.
Для проверки обоих участков скопируйте **публичный CA Proxmox** из
`/etc/pve/pve-root-ca.pem` в постоянный каталог NPM, например
`/data/custom-trust/pve-root-ca.pem` внутри контейнера. Проверьте SAN серверного сертификата
Proxmox и укажите соответствующее имя:
```yaml
- hostname: pve.home
upstream: https://192.168.0.137:8006
upstream_tls_verify: true
upstream_tls_name: pve.your-existing-lan-domain
upstream_ca_file: /data/custom-trust/pve-root-ca.pem
```
Здесь `upstream_tls_name` — существующее имя из сертификата Proxmox, оно не обязано быть
`pve.home`. Путь читается **NPM**, не Homegate. При собственном сертификате Proxmox
используйте его издателя. Для остальных HTTPS upstream проверка по умолчанию включена.
## Доступ только из домашней сети
Homegate добавляет в каждый свой Proxy Host `allow <ваши подсети>; deny all;`.
ACL применяется к IP, который видит NPM. Никаких правил проброса портов на роутере не нужно.
Оставьте WAN-вход закрытым для `80`, `443`, `81`, `53`, порта web Pi-hole и `SSH_PORT` (8099),
включая IPv6 и автоматические пробросы UPnP. При Docker применяйте firewall-правила
с учётом Docker forwarding; одного обычного UFW INPUT-правила может быть недостаточно.
Если перед NPM стоит другой прокси/NAT, который заменяет адрес источника на разрешённый
LAN-IP, ACL уже не различает внешних и домашних клиентов. Ограничение на роутере/межсетевом
экране остаётся необходимым. Не включайте доверие произвольным `X-Forwarded-For`.
DNS-имя `.home` само по себе не является ограничением доступа.
## Изменения, продление и восстановление
- Новый сервис: добавьте блок в `config/services.yaml`; изменения подхватятся за 60 секунд.
Контейнер перечитывает каталог конфигурации, в том числе после атомарного сохранения редактором.
- Сертификат выдаётся на 90 дней и заменяется, когда осталось менее 30. Homegate загружает
его в NPM и обновляет Proxy Host, чтобы nginx перечитал сертификат. Перезапуск контейнера
сохраняет CA и идентификатор владельца.
- Если Pi-hole недоступен, Homegate продолжает обслуживание сертификатов/прокси и показывает
нездоровый статус синхронизации. Каждый цикл повторяет неуспешные операции. При отказе NPM
DNS-запись нового сервиса не публикуется.
- Отключение: задайте `enabled: false`; NPM выключит соответствующий Proxy Host, DNS останется.
- Удаление записи из файла **не удаляет** ресурсы. Для окончательного удаления сначала уберите
блок из файла, затем удалите Proxy Host, его сертификат и DNS в интерфейсах NPM/Pi-hole.
До ручного удаления прежний маршрут продолжает работать; продление удалённого из файла
сервиса прекращается. Это также относится к переименованию сервиса.
- Уже существующий чужой Proxy Host с тем же именем или конфликтующий DNS-адрес не
перезаписывается. Используйте новое имя или заранее перенесите старую запись вручную.
NPM-хосты этого проекта редактируйте через YAML: ручные изменения управляемых полей
будут восстановлены. Не удаляйте строку `# homegate:...` из Advanced.
- При смене LAN-IP NPM поправьте `proxy_ip`, затем вручную удалите/исправьте прежние
конфликтующие DNS-записи. Homegate добавляет записи по одной, не заменяет весь DNS-список.
- Для Pi-hole 5 выберите `dns_mode: manual`, в его Local DNS добавьте
`pve.home → IP_NPM`. Сертификаты и NPM остаются автоматическими.
- Держите только один экземпляр контроллера на `state/`. Файловая блокировка не даёт
одновременно запускать `run` и `once`. Для ручного прохода остановите сервис и выполните
`docker compose run --rm homegate once`, затем `docker compose up -d`.
Для резервной копии остановите Homegate, сохраните **`.env`, `config/`, `secrets/`, `state/`**
в защищённом хранилище и запустите снова. Отдельно резервируйте NPM (его `/data` и
`/etc/letsencrypt`) и Pi-hole. Закрытый ключ CA хранится в `state/ca.json` без шифрования
с правами `0600`, каталог `state/` — `0700`; используйте шифрование диска/backup.
Это простой онлайн-CA для homelab, без офлайн-корня, CRL и OCSP. При компрометации CA
нужно удалить доверие к старому корню на всех клиентах и развернуть новый CA.
Корень действует 10 лет; за 91 день до истечения выпуск блокируется и требуется миграция доверия.
Потеря всего `state/` означает потерю CA и владельца объектов. Восстанавливайте backup:
новый CA потребует повторной установки доверия, а старые NPM-объекты не будут присвоены
новому контроллеру автоматически. Ключ CA никогда не импортируется в NPM: туда попадают
только сертификаты отдельных сервисов и их ключи.
## Диагностика
| Симптом | Что проверить |
|---|---|
| `NXDOMAIN` | Клиент использует Pi-hole; запись указывает на NPM; отключён обход DNS через DoH/VPN; очистите DNS-кэш. |
| Сертификат не доверен | CA установлен именно на клиенте и в хранилище этого браузера; на iOS включён Full Trust; дата/время верны. |
| Ошибка имени сертификата | Открывайте `https://pve.home`, не IP NPM; проверьте SNI и привязанный в NPM сертификат. |
| HTTP 403 от NPM | IP клиента, видимый NPM, должен входить в `allowed_networks`; проверьте VLAN, IPv6 и наличие внешнего NAT. |
| HTTP 502 | NPM достигает IP:port VM; выбран HTTPS для Proxmox; при `upstream_tls_verify: true` корректны CA и SAN. |
| Pi-hole API HTTP 401/403 | Версия 6, правильный пароль; application password с `app_sudo`; для 2FA — application password. |
| Pi-hole API HTTP 400 | Проверьте `/api/docs` вашей версии и что `dns.hosts` не задан read-only через `FTLCONF_dns_hosts`. |
| NPM API HTTP 401/403 | Email, пароль и разрешения учётной записи; URL содержит административный порт 81. |
| `nginx configuration` | Посмотрите статус хоста и ошибку в NPM; проверьте наличие `upstream_ca_file` внутри NPM. |
| `conflicting Pi-hole record` | DNS для этого имени уже ведёт на другой IP; исправьте его вручную. |
| `not managed by this instance` | Имя занято в NPM или потерян `registry.json`; восстановите state либо выберите другое имя. |
| Сервис `unhealthy` | `docker compose logs --tail=100 homegate`; Docker healthcheck показывает отказ, но сам по себе не перезапускает контейнер. |
## Проверки разработчика
```sh
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/python -m unittest discover -s tests -v
docker compose --env-file .env.example config --quiet
```
Протоколы интеграции: [Pi-hole API](https://docs.pi-hole.net/api/),
[Pi-hole authentication](https://docs.pi-hole.net/api/auth/),
[NPM certificates API 2.16.0](https://github.com/NginxProxyManager/nginx-proxy-manager/blob/v2.16.0/backend/routes/nginx/certificates.js),
[NPM certificate upload implementation](https://github.com/NginxProxyManager/nginx-proxy-manager/blob/v2.16.0/backend/internal/certificate.js),
[NPM Proxy Hosts API 2.16.0](https://github.com/NginxProxyManager/nginx-proxy-manager/blob/v2.16.0/backend/routes/nginx/proxy_hosts.js).

246
REGISTRY.md Normal file
View File

@@ -0,0 +1,246 @@
# Один Compose-файл и Gitea Container Registry
Homegate 0.4 поддерживает два способа установки:
| Файл | Назначение |
| --- | --- |
| `compose.registry.yaml` | Готовый образ из Gitea; именованные volumes, автоматическая первичная настройка |
| `compose.yaml` | Прежний запуск из исходников с `build`, `setup.sh` и каталогами на хосте |
Gitea здесь ещё не подключена, образ не опубликован. Workflow готов к запуску в вашем
репозитории. Имена `git.example.home` и `your-user` ниже — примеры.
## 1. Настройте репозиторий и runner один раз
Загрузите содержимое каталога проекта в корень репозитория Gitea, включая скрытую папку
`.gitea/workflows/`. Включите **Enable Repository Actions** в настройках репозитория.
В Gitea должен быть включён Package Registry.
Workflow использует выделенный **Linux runner** с меткой `homegate:host`:
- Python 3.11+ с `venv` и pip, Git, OpenSSH client, Bash, Node.js 20+;
- Docker Engine, Buildx и Docker Compose **2.30.0+**;
- права на использование Docker и установку QEMU/binfmt через `setup-qemu-action`;
- доступ к Gitea/registry, GitHub для загрузки actions, Docker Hub и PyPI при сборке.
Метка в workflow — `runs-on: homegate`; если у вашего runner другое имя метки, замените
его в обоих jobs. Для runner с контейнерными jobs нужна специально подготовленная среда,
включающая эти инструменты и доступ к Docker daemon. Шаблон рассчитан на `homegate:host`.
Используйте отдельную VM для сборок: job исполняет код репозитория и имеет доступ к Docker.
Внешние PR запускайте только после проверки авторства и содержимого либо на изолированном
одноразовом runner. Registry secrets используются только в job публикации Git-тега.
В **Repository Settings → Actions → Secrets** добавьте:
| Secret | Значение |
| --- | --- |
| `REGISTRY_USERNAME` | Пользователь Gitea, которому разрешено публиковать пакеты владельца репозитория |
| `REGISTRY_TOKEN` | Personal access token этого пользователя с правом `write:package` |
Для репозитория организации учётная запись должна иметь право записи её пакетов.
Встроенный `GITEA_TOKEN` используется только для checkout; отдельный registry token
обеспечивает совместимость с инсталляциями, где job token не может публиковать пакеты.
Не добавляйте сюда пароли NPM, Pi-hole или панели — они нужны только при развёртывании.
По умолчанию registry берётся из адреса Gitea, image — из `owner/repository` в нижнем регистре:
```text
git.example.home/your-user/homegate:0.4.0
```
Если registry доступен по другому имени/порту, задайте Actions **variable** `REGISTRY`,
например `registry.example.home:5000`, без `https://` и без пути. Этот адрес должен действительно
обслуживать Gitea Container Registry. Для имён владельца/репозитория используйте латинские
буквы, цифры и разделители, допустимые в Docker image names.
Для Gitea с локальным CA настройте доверие к CA у runner, Docker daemon и BuildKit builder.
В workflow не отключается TLS-проверка. Если используете отдельный builder, его настройка
доверия независима от системного хранилища сертификатов.
## 2. Выпустите образ
Файл `VERSION` сейчас содержит `0.4.0`. После загрузки проверенного кода в Gitea:
```sh
git tag v0.4.0
git push origin v0.4.0
```
При следующем выпуске измените `VERSION`, закоммитьте его вместе с изменениями и создайте
соответствующий тег. Тег должен совпасть с файлом `VERSION`: например `v0.4.1` и `0.4.1`.
Предварительные версии вида `v0.4.1-rc.1` также поддерживаются. Полный номер задаётся
в `VERSION`; примеры в Compose, Dockerfile и документации при выпуске также обновите.
Workflow `.gitea/workflows/release.yaml` выполняет:
1. На push в ветку, тег или PR — Python/HTTP-тесты, проверку JavaScript и shell,
проверку обоих Compose-файлов.
2. Сборку образа для архитектуры runner и пробный запуск изолированного стека без
портов хоста и доступа к NPM/Pi-hole. Проверяются вход по паролю, сохранение
настроек, права volumes, отсутствие чужих secrets в UI и сохранность CA после повторной инициализации.
3. Только для push тега `v*`, после успешных проверок — проверку `VERSION`, сборку
`linux/amd64` + `linux/arm64` и публикацию в Gitea Container Registry.
Образ получает два тега: `0.4.0` и `sha-<полный SHA коммита>`. Тег `latest` не создаётся.
`org.opencontainers.image.source` связывает метаданные образа с URL исходников.
Права на просмотр/скачивание пакета проверьте в Gitea Packages отдельно от доступа к коду.
Workflow не меняет видимость пакетов и не развёртывает Homegate на домашнем сервере.
Для runtime-тестов локально, если Docker запущен:
```sh
docker build --build-arg VERSION="$(cat VERSION)" -t homegate:test .
sh ci/smoke_image.sh homegate:test
```
Тест создаёт временный Compose-проект со случайным именем `homegate-smoke-*` и удаляет
только его контейнеры и volumes при завершении. Образ не публикуется.
## 3. Разверните, скачав только Compose
Скопируйте **только `compose.registry.yaml`** на Linux Docker-хост и переименуйте
в `compose.yaml`. Клонировать проект, устанавливать Python и запускать `setup.sh` не нужно.
В Bash укажите свои адреса. Здесь `.10`, `.11` и `.2` — примеры:
```bash
export HOMEGATE_IMAGE=git.example.home/your-user/homegate:0.4.0
export HOMEGATE_LAN_IP=192.168.0.10
export HOMEGATE_PROXY_IP=192.168.0.11
export HOMEGATE_ALLOWED_NETWORKS='[192.168.0.0/24]'
export HOMEGATE_ZONES='[home, home.arpa, lab.internal]'
export UI_ORIGIN=http://192.168.0.10:8098
export NPM_URL=http://192.168.0.11:81
export NPM_IDENTITY=admin@example.com
export PIHOLE_URL=http://192.168.0.2
read -rsp 'Пароль панели (от 12 символов): ' UI_PASSWORD; printf '\n'
read -rsp 'Пароль NPM: ' NPM_PASSWORD; printf '\n'
read -rsp 'Пароль Pi-hole: ' PIHOLE_PASSWORD; printf '\n'
export UI_PASSWORD NPM_PASSWORD PIHOLE_PASSWORD
```
Пароли вводятся скрыто, не записываются в Compose и не передаются как environment контейнера:
Compose монтирует их отдельными secret-файлами только в нужные сервисы. Имена параметров,
которые заканчиваются на `_IP`, принимают приватные IP. `HOMEGATE_LAN_IP` — IPv4 Docker-хоста,
`HOMEGATE_PROXY_IP` — адрес NPM. Это могут быть разные машины.
Для Pi-hole 5 или ручного DNS вместо автоматического режима:
```bash
export HOMEGATE_DNS_MODE=manual
export PIHOLE_PASSWORD=not-used
```
Для приватного образа войдите в registry, указав свой Gitea username и token вместо пароля:
```sh
docker login git.example.home
docker compose pull
docker compose up -d
```
Для общедоступного образа `docker login` не нужен. Остальные команды одинаковы.
Не публикуйте порты через NAT роутера или внешние туннели.
Откройте `UI_ORIGIN`. Вход — паролем панели. Начальный список сервисов пуст:
добавьте нужные VM в интерфейсе. Контроллер получает конфигурацию из того же volume.
Защищённый HTTPS сервисов потребует установки корневого CA на клиентские устройства.
О настройке HTTPS самой панели см. [WEB.md](WEB.md#https-самой-панели).
`HOMEGATE_ZONES`, `HOMEGATE_PROXY_IP`, `HOMEGATE_ALLOWED_NETWORKS`, `HOMEGATE_DNS_MODE`
используются для начального YAML **только один раз**. После первого запуска изменяйте
эти настройки в панели. Изменение seed в Compose при обновлении не затирает ваши настройки.
Зоны лучше определить до первого запуска CA; расширение списка позже может потребовать
явной смены CA по [DOMAINS.md](DOMAINS.md).
Переменные нужны Compose и при последующих `up`, `pull`, `run` и `exec`; после закрытия
терминала задайте их снова. По желанию можно сохранить их в локальном `.env` с правами `600`
и исключить его из Git. Дополнительный файл не является обязательным.
Если административные API используют локальный HTTPS CA, его PEM bundle можно скопировать
в volume конфигурации по примеру импорта ниже и указать `API_CA_BUNDLE=/config/management-ca.pem`.
CA самой VM для `upstream_ca_file` по-прежнему устанавливается отдельно внутри NPM.
## Хранение, обновление и восстановление
Создаются volumes `homegate_config`, `homegate_state`, `homegate_control` (префикс зависит
от имени Compose-проекта). Не меняйте имя проекта при обычном обновлении, иначе Docker
создаст другой набор volumes и новый CA.
| Volume | Содержимое | У кого есть доступ |
| --- | --- | --- |
| config | YAML, его резервные копии, необязательный management CA | UI — запись; контроллер и SSH-export — чтение |
| state | Закрытый ключ CA, выданные сертификаты, реестр NPM | Только контроллер |
| control | Публичное состояние и запросы синхронизации | UI и контроллер |
Инициализатор однократно запускается от root без сети, портов и паролей: готовит права
каталогов для UID/GID `1000:1000`, создаёт YAML только при отсутствии, затем завершается.
При новом запуске он проверяет существующий файл и сохраняет его. Остальные сервисы
всегда работают от UID/GID `1000:1000`. Инициализатор не выпускает и не заменяет CA.
Обновление до уже опубликованной версии:
```sh
export HOMEGATE_IMAGE=git.example.home/your-user/homegate:0.4.1
docker compose pull
docker compose up -d
```
Обычные `up`, `restart` и `down` сохраняют volumes. **`docker compose down -v` удалит данные,
включая доверенный CA.** Сделайте резервную копию перед обновлением. Удаление state при
сохранённых настройках в NPM означает потерю ключа и связей с ранее созданными объектами.
Экспорт YAML и публичного CA:
```sh
docker compose cp ui:/config/services.yaml ./services.backup.yaml
docker compose cp homegate:/data/root-ca.crt ./root-ca.crt
```
Для полной резервной копии остановите три долгоживущих сервиса, чтобы YAML и реестр
не менялись во время копирования. Архив state содержит приватные ключи:
```sh
umask 077
mkdir -p backup/config backup/state backup/control
docker compose stop homegate ui ssh-export
docker compose cp ui:/config/. ./backup/config/
docker compose cp homegate:/data/. ./backup/state/
docker compose cp ui:/control/. ./backup/control/
docker compose start homegate ui ssh-export
```
При восстановлении используйте тот же Compose project name, сначала запустите только
`initialize`, затем импортируйте файлы через одноразовый контейнер `initialize`
(`docker compose run --rm --no-deps -T --entrypoint python initialize -c ...`).
Он видит все три volumes и имеет права выставить владельца восстановленных файлов `1000:1000`.
Не запускайте контроллер с пустым state до импорта резервной копии CA и реестра.
Для разового импорта YAML без копирования закрытых ключей:
```sh
docker compose stop homegate ui ssh-export
docker compose run --rm --no-deps -T --entrypoint python ui -c \
'import sys; from pathlib import Path; Path("/config/services.yaml").write_bytes(sys.stdin.buffer.read())' \
< services.backup.yaml
docker compose run --rm --no-deps homegate validate
docker compose start homegate ui ssh-export
```
Команды предполагают, что volumes уже инициализированы. Миграцию существующей установки
на bind mounts выполняйте через резервное копирование: автоматический перенос старого `state/`
в новые volumes не выполняется. Используйте новое имя Compose-проекта во время подготовки
миграции; старый стек остановите перед запуском нового на тех же портах/API.
## Что проверено
Локально проходят 55 тестов, включая первый запуск, сохранение пользовательских изменений
и CA, отказ от повреждённого конфига и проверку адреса/версии публикуемого образа.
Оба Compose-файла проверяются установленным Docker Compose. Синтаксис shell, JavaScript
и YAML workflow проверен. Docker daemon при подготовке выключен, поэтому сборка образа,
контейнерный smoke-test и исполнение самого workflow должны впервые пройти на вашем runner.
Официальные контракты: [Gitea Container Registry](https://docs.gitea.com/usage/packages/container/),
[Gitea Actions](https://docs.gitea.com/usage/actions/quickstart/),
[Compose secrets из environment](https://docs.docker.com/reference/compose-file/secrets/),
[Compose configs с content](https://docs.docker.com/reference/compose-file/configs/).

175
SSH.md Normal file
View 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.

1
VERSION Normal file
View File

@@ -0,0 +1 @@
0.4.0

157
WEB.md Normal file
View File

@@ -0,0 +1,157 @@
# Веб-панель Homegate 0.4
Панель включена в проект и Docker Compose. Она редактирует настоящий YAML, проверяет
настройки на сервере и показывает результат синхронизации контроллера с Pi-hole/NPM.
Интерфейс на русском, адаптируется к узким экранам и работает без внешних шрифтов,
аналитики, CDN или интернет-сервисов.
## Что доступно
- **Сервисы:** поиск, добавление, редактирование, включение/выключение; адрес VM, домен,
WebSocket, проверка TLS upstream, тайм-аут и размер загрузки, SSH-доступ.
Поле «Название» сохраняется как `display_name` и используется в каталоге, поиске
и схеме соединения. Оно необязательное, до 100 символов; без него подпись определяется по домену.
- **Доменные зоны:** несколько зон одновременно; добавление и удаление с проверкой
привязанных сервисов. Расширение ограничений уже созданного CA требует его явной смены.
- **SSH:** предпросмотр и скачивание конфига, скрипт для ПК, команда подключения,
отдельные SSH-хосты без веб-сервиса. Открытая LAN-выгрузка работает через `ssh-export`.
- **Сертификаты:** публичный корневой сертификат, SHA-256, сроки и список выданных
сертификатов. Смена CA выполняется на сервере по инструкции из панели.
- **Настройки:** IP NPM, разрешённые подсети, режим DNS, интервал синхронизации,
журнал сохранений и скачивание текущего YAML.
## Локальный запуск через Sites
Использован локальный режим Sites: исходники и работающий сервер остаются на компьютере.
Регистрация в облаке и публикация в интернете для этого проекта не выполняются.
На macOS/Linux с Python 3.11+ из каталога проекта:
```sh
sh run-local.sh
```
Откройте **http://127.0.0.1:8787**. При первом запуске скрипт создаёт отдельную среду Python
и устанавливает зависимости. Рабочая копия YAML, резервные копии и данные интерфейса
хранятся в `.local/`; образец `config/services.yaml` остаётся исходным шаблоном.
Чтобы изменить порт, используйте `HOMEGATE_LOCAL_PORT=8788 sh run-local.sh`.
Остановка — Ctrl+C в терминале; повторный запуск сохраняет внесённые настройки.
Локальный режим доступен только через `127.0.0.1`, вход в нём не требуется.
Он не запускает контроллер и не изменяет Pi-hole/NPM. Кнопка «Применить» сохраняет запрос;
без контроллера панель прямо сообщает, что применения пока нет. Скачайте подготовленный
YAML через кнопку в панели и перенесите в `config/services.yaml` на Docker-хосте.
В экземпляре, запущенном при подготовке проекта, рабочая копия находится отдельно
в `work/local-ui/config/services.yaml` относительно папки задачи. Для её повторного запуска
из исходной папки задачи без повторной установки зависимостей:
```sh
HOMEGATE_LOCAL_DIR="$PWD/work/local-ui" \
HOMEGATE_PYTHON="$PWD/work/venv/bin/python" \
sh outputs/homegate/run-local.sh
```
## Панель для домашней сети через Docker
Для готового образа и автоматического создания volumes используйте [один Compose-файл](REGISTRY.md).
Ниже — вариант сборки из исходников.
```sh
sh setup.sh
# Замените примеры адресов в .env и config/services.yaml своими.
docker compose build
docker compose run --rm homegate validate
docker compose up -d
```
`setup.sh` отдельно запрашивает пароль панели длиной от 12 символов.
В `.env` задайте:
```dotenv
UI_BIND_IP=192.168.0.10
UI_PORT=8098
UI_ORIGIN=http://192.168.0.10:8098
SSH_BIND_IP=192.168.0.10
SSH_PORT=8099
```
Адрес `.10` — пример LAN-IP **хоста Homegate**; он может отличаться от IP NPM.
Откройте точный `UI_ORIGIN`, войдите с паролем из `secrets/ui_password`.
Настройки сохраняются непосредственно в `config/services.yaml`, контроллер применяет их
каждые `interval_seconds`. «Применить» будит контроллер обычно в пределах двух секунд,
после чего ему требуется время на обращения к API. Статус не равнозначен доступности VM:
он сообщает об успешной настройке NPM/Pi-hole, а не о проверке приложения за прокси.
Сохранение создаёт резервную копию в `config/backups/` (последние 20 файлов).
При одновременном редактировании в двух вкладках устаревшая версия не перезаписывает новую.
Форматирование и комментарии YAML при сохранении через панель заменяются сериализованным YAML.
Для восстановления скопируйте нужный файл из `config/backups/` в `config/services.yaml`.
В панели отображаются последние восемь из двадцати сохранений, с временем без персонального аудита.
Выключение сервиса передаёт `enabled: false` в NPM. Удаление из списка прекращает управление,
но уже созданные Proxy Host и DNS-запись сохраняются: удалите их отдельно в NPM/Pi-hole.
Это поведение явно описано в диалоге удаления. Переименование домена эквивалентно созданию
нового имени и прекращению управления старым; старые объекты также остаются.
## HTTPS самой панели
Исходный порт `8098` работает по HTTP. Для HTTPS добавьте в Homegate сервис, например:
```yaml
- hostname: homegate.home
upstream: http://192.168.0.10:8098
```
После применения и установки `root-ca.crt` на клиенте измените `.env`:
```dotenv
UI_ORIGIN=https://homegate.home
```
Пересоздайте панель:
```sh
docker compose up -d --force-recreate ui
```
Теперь вход выполняется по **https://homegate.home**. Старый URL по IP намеренно перестанет
проходить проверку Host. В NPM нужно сохранять исходный Host (обычное поведение Proxy Host).
Для прямого отката измените `UI_ORIGIN` обратно и пересоздайте `ui`.
Сервис панели должен разрешать подсеть NPM в `allowed_networks`; NPM проверяет исходный
клиентский IP по тому же списку. Панель сама не доверяет `X-Forwarded-For`.
Не перенаправляйте порты через роутер и не публикуйте их через внешние туннели.
HTTP-вход используйте только в доверенной сети при первоначальной настройке;
постоянный доступ к панели лучше проводить через описанный HTTPS-маршрут.
## Изоляция компонентов
| Компонент | Доступ |
| --- | --- |
| `homegate` | YAML только для чтения, CA и реестр в `state/`, API-пароли, `control/` |
| `ui` | YAML и резервные копии, `control/`, только пароль панели |
| `ssh-export` | Только YAML для чтения; без паролей и `state/` |
`control/status.json` содержит публичные сертификаты и состояние последней синхронизации.
`control/sync-request.json` — запрос на очередной цикл. CA-ключи не попадают в эти файлы.
Контейнер панели не имеет доступа к `state/`, паролям интеграций или Docker socket.
Сессии хранятся в памяти 12 часов, после рестарта нужно войти снова. Включены проверка
Origin, CSRF-токен, HttpOnly/SameSite cookie, защита от перебора и список допустимых Host.
При HTTPS cookie также получает Secure. После смены пароля перезапустите `ui`, чтобы сбросить сессии.
Ограничение подсетей основано на видимом контейнеру адресе клиента. Рекомендуется Linux Docker
Engine; Docker Desktop или дополнительный reverse proxy могут менять этот адрес.
Проверяйте доступ с разрешённого и постороннего сегмента после установки, включая правила
хостового firewall и Docker. Публикация на конкретном LAN-IP сама по себе не отменяет NAT роутера.
## Проверки
55 тестов проходят локально: прежняя логика DNS/TLS/SSH, HTTP-вход и сессии, Origin/CSRF,
LAN ACL, скачивание, проверка YAML, резервные копии, конфликт изменений, свежесть статуса
и передача в панель только публичных данных. JavaScript и Compose проходят проверку синтаксиса.
В браузере проверены добавление сервиса, поиск, навигация, SSH-предпросмотр и адаптивная компоновка.
Реальные API вашего homelab и запуск Docker-образа на сервере пока не проверены.
```sh
python -m unittest discover -s tests -v
```

58
bootstrap.py Normal file
View File

@@ -0,0 +1,58 @@
"""Initialize named volumes once; never replace an existing Homegate configuration."""
import fcntl
import os
from pathlib import Path
import stat
import sys
import yaml
import homegate as h
def initialize(seed, config, state, control, uid=1000, gid=1000):
config, state, control = map(Path, (config, state, control))
seed = Path(seed)
for directory in (config.parent, state, control):
h.require(not directory.is_symlink(), f"Volume must not be a symlink: {directory}")
directory.mkdir(parents=True, exist_ok=True, mode=0o700)
h.require(directory.is_dir(), f"Expected a directory: {directory}")
# The short-lived initializer is the only root container. No recursive chown:
# existing CA material and backups must not be traversed or replaced.
if os.geteuid() == 0:
os.chown(directory, uid, gid)
os.chmod(directory, 0o700)
lock_path = config.parent / '.bootstrap.lock'
h.require(not lock_path.is_symlink(), 'Bootstrap lock must not be a symlink')
with lock_path.open('a') as lock:
fcntl.flock(lock, fcntl.LOCK_EX)
h.require(not config.is_symlink(), 'services.yaml must not be a symlink')
if config.exists():
h.require(stat.S_ISREG(config.stat().st_mode), 'services.yaml must be a regular file')
h.load_config(config)
created = False
else:
h.load_config(seed) # Reject invalid seed before touching the live config.
h.atomic(config, seed.read_bytes(), 0o600)
created = True
if os.geteuid() == 0:
os.chown(config, uid, gid)
return created
def main():
os.umask(0o077)
created = initialize(os.environ.get('HOMEGATE_SEED', '/run/configs/homegate-seed.yaml'),
os.environ.get('HOMEGATE_CONFIG', '/config/services.yaml'),
os.environ.get('HOMEGATE_STATE', '/data'),
os.environ.get('HOMEGATE_CONTROL', '/control'))
print('Created initial configuration' if created else 'Existing configuration retained')
return 0
if __name__ == '__main__':
try:
sys.exit(main())
except (h.Error, ValueError, KeyError, TypeError, OSError, yaml.YAMLError) as exc:
print(f'Initialization failed: {exc}', file=sys.stderr)
sys.exit(1)

53
ci/check_compose.py Normal file
View File

@@ -0,0 +1,53 @@
"""Validate both deployment models without a running Docker daemon or real credentials."""
import json
import os
from pathlib import Path
import subprocess
import yaml
import homegate as h
def main():
env = dict(os.environ, HOMEGATE_IMAGE='registry.example/homegate/homegate:0.4.0',
HOMEGATE_LAN_IP='192.168.0.10', HOMEGATE_PROXY_IP='192.168.0.10',
HOMEGATE_ALLOWED_NETWORKS='[192.168.0.0/24]', HOMEGATE_ZONES='[home, home.arpa]',
HOMEGATE_DNS_MODE='manual', UI_ORIGIN='http://192.168.0.10:8098',
NPM_URL='http://192.168.0.10:81', NPM_IDENTITY='test@example.invalid',
UI_PASSWORD='test-only-panel-password', NPM_PASSWORD='test-only-npm',
PIHOLE_PASSWORD='not-used', PIHOLE_URL='', UI_PORT='8098', SSH_PORT='8099')
model = json.loads(subprocess.check_output(
['docker', 'compose', '--env-file', os.devnull, '-f', 'compose.registry.yaml',
'config', '--format', 'json'], env=env))
assert set(model['services']) == {'initialize', 'homegate', 'ssh-export', 'ui'}
for name, service in model['services'].items():
assert 'build' not in service, name
assert service['image'] == env['HOMEGATE_IMAGE']
assert all(v['type'] == 'volume' for v in service.get('volumes', [])), name
if name != 'initialize':
assert service['user'] == '1000:1000'
assert service['depends_on']['initialize']['condition'] == 'service_completed_successfully'
for port in service.get('ports', []):
assert port['host_ip'] == env['HOMEGATE_LAN_IP']
assert model['services']['initialize']['network_mode'] == 'none'
assert not model['services']['initialize'].get('secrets')
assert not model['services']['ssh-export'].get('secrets')
assert [v['source'] for v in model['services']['ui']['secrets']] == ['ui_password']
for name in ('ui', 'ssh-export'):
assert all(v['target'] != '/data' for v in model['services'][name]['volumes'])
assert set(model['secrets']) == {'ui_password', 'npm_password', 'pihole_password'}
assert all('environment' in s and 'file' not in s for s in model['secrets'].values())
seed = h.validate_config(yaml.safe_load(model['configs']['initial-config']['content']))
assert seed['services'] == [] and seed['ssh_hosts'] == []
subprocess.run(['docker', 'compose', '--env-file', '.env.example', '-f', 'compose.yaml',
'config', '--quiet'], check=True, env=env)
# The one-file deployment cannot accidentally fall back to all host interfaces.
del env['HOMEGATE_LAN_IP']
missing = subprocess.run(['docker', 'compose', '--env-file', os.devnull,
'-f', 'compose.registry.yaml', 'config', '--quiet'],
env=env, capture_output=True)
assert missing.returncode != 0
print('Build and registry Compose models validated; isolation and first-run defaults verified.')
if __name__ == '__main__':
main()

49
ci/image_metadata.py Normal file
View File

@@ -0,0 +1,49 @@
"""Validate release identity before registry credentials are used."""
import os
from pathlib import Path
import re
from urllib.parse import urlsplit
VERSION_PATTERN = r'(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)(?:-[0-9A-Za-z][0-9A-Za-z.-]*)?'
COMPONENT = r'[a-z0-9]+(?:(?:[._]|__|-+)[a-z0-9]+)*'
def metadata(server_url, repository, ref, revision, version_file, registry_override=''):
server = urlsplit(server_url)
if server.scheme not in ('http', 'https') or not server.hostname or server.username or server.query or server.fragment:
raise ValueError('Invalid Gitea server URL')
registry = (registry_override or server.netloc).lower()
parsed = urlsplit('https://' + registry)
if (not re.fullmatch(r'[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?(?::[0-9]{1,5})?', registry)
or parsed.port is not None and not 1 <= parsed.port <= 65535):
raise ValueError('REGISTRY must be a hostname[:port], without scheme or path')
if '.' not in registry and ':' not in registry and registry != 'localhost':
raise ValueError('Use a registry FQDN or explicit port; a bare name is a Docker Hub namespace')
repository = repository.lower()
if not re.fullmatch(COMPONENT + '/' + COMPONENT, repository):
raise ValueError('Repository must be owner/name with a Docker-compatible lowercase name')
if not ref.startswith('refs/tags/v'):
raise ValueError('Images are published only for vVERSION tags')
version = ref.removeprefix('refs/tags/v')
if not re.fullmatch(VERSION_PATTERN, version) or len(version) > 100:
raise ValueError('Use a tag such as v0.4.0 or v0.4.0-rc.1')
if version != version_file.strip():
raise ValueError('Release tag must match VERSION in the checked-out commit')
if not re.fullmatch(r'[a-fA-F0-9]{40}|[a-fA-F0-9]{64}', revision):
raise ValueError('Invalid commit SHA')
return {'registry': registry, 'image': registry + '/' + repository,
'version': version, 'revision': revision.lower(),
'source': server_url.rstrip('/') + '/' + repository}
if __name__ == '__main__':
values = metadata(os.environ['CI_SERVER_URL'], os.environ['CI_REPOSITORY'],
os.environ['CI_REF'], os.environ['CI_REVISION'],
Path('VERSION').read_text(), os.environ.get('REGISTRY', ''))
with open(os.environ['GITHUB_OUTPUT'], 'a') as output:
for key, value in values.items():
if '\n' in value or '\r' in value:
raise ValueError('Invalid multiline output')
output.write(f'{key}={value}\n')
print('Validated release:', values['image'] + ':' + values['version'])

56
ci/smoke_image.sh Executable file
View File

@@ -0,0 +1,56 @@
#!/bin/sh
# Disposable CI deployment. No host ports and no access to NPM/Pi-hole.
set -eu
cd "$(dirname "$0")/.."
: "${1:?Pass a locally built image}"
export HOMEGATE_IMAGE=$1
export HOMEGATE_LAN_IP=192.168.42.10
export HOMEGATE_PROXY_IP=192.168.42.11
export HOMEGATE_ALLOWED_NETWORKS='[192.168.42.0/24]'
export HOMEGATE_ZONES='[home]'
export HOMEGATE_DNS_MODE=manual
export UI_ORIGIN=http://192.168.42.10:8098
export NPM_URL=http://192.168.42.11:81
export NPM_IDENTITY=smoke@example.invalid
export PIHOLE_URL=
export API_CA_BUNDLE=
export UI_PASSWORD=disposable-smoke-password
export NPM_PASSWORD=disposable-smoke-npm
export PIHOLE_PASSWORD=not-used
smoke_dir=$(mktemp -d)
project="homegate-smoke-$(python3 -c 'import secrets; print(secrets.token_hex(6))')"
cat > "$smoke_dir/override.yaml" <<'YAML'
services:
ui:
ports: !reset []
network_mode: none
ssh-export:
ports: !reset []
network_mode: none
homegate:
network_mode: none
YAML
compose() {
docker compose --env-file /dev/null -p "$project" -f compose.registry.yaml -f "$smoke_dir/override.yaml" "$@"
}
cleanup() {
compose down --volumes --remove-orphans >/dev/null 2>&1 || true
rm -rf -- "$smoke_dir"
}
trap cleanup EXIT
trap 'exit 1' HUP INT TERM
compose up -d --wait --wait-timeout 60 --pull never ui ssh-export
compose run --rm --no-deps homegate validate
compose exec -T ui python - write < ci/smoke_ui.py
compose exec -T ssh-export python -c "from pathlib import Path; import os,urllib.request; assert os.getuid()==1000; assert not Path('/run/secrets/ui_password').exists(); assert not Path('/data').exists(); urllib.request.urlopen('http://127.0.0.1:8080/healthz',timeout=3).read()"
ca_check="from pathlib import Path; import hashlib,os,homegate as h; assert os.getuid()==1000; c=h.load_config('/config/services.yaml'); h.Authority(Path('/data'),c['domain_zones']); print(hashlib.sha256(Path('/data/root-ca.crt').read_bytes()).hexdigest())"
ca_before=$(compose run --rm --no-deps --entrypoint python homegate -c "$ca_check")
# Changing a first-run seed must not replace live settings or the established CA.
export HOMEGATE_PROXY_IP=192.168.42.99
export HOMEGATE_ZONES='[changed.internal]'
compose run --rm --no-deps initialize
compose restart ui ssh-export
compose exec -T ui python - verify < ci/smoke_ui.py
ca_after=$(compose run --rm --no-deps --entrypoint python homegate -c "$ca_check")
[ "$ca_before" = "$ca_after" ]
printf 'Runtime smoke test passed: bootstrap, permissions, secrets, config and CA persistence.\n'

61
ci/smoke_ui.py Normal file
View File

@@ -0,0 +1,61 @@
"""Executed inside the UI container of ci/smoke_image.sh; no external networking."""
import http.cookiejar
import json
import os
from pathlib import Path
import sys
import time
import urllib.error
import urllib.request
from urllib.parse import urlsplit
origin = os.environ['UI_ORIGIN']
authority = urlsplit(origin).netloc
opener = urllib.request.build_opener(urllib.request.HTTPCookieProcessor(http.cookiejar.CookieJar()))
csrf = ''
def request(path, data=None):
headers = {'Host': authority}
if data is not None:
headers.update({'Origin': origin, 'Content-Type': 'application/json', 'X-Homegate-CSRF': csrf})
payload = None if data is None else json.dumps(data).encode()
with opener.open(urllib.request.Request('http://127.0.0.1:8081' + path, payload, headers), timeout=2) as r:
body = r.read()
return json.loads(body) if 'application/json' in r.headers.get('Content-Type', '') else body
assert os.getuid() == 1000
assert not Path('/run/secrets/npm_password').exists()
assert not Path('/run/secrets/pihole_password').exists()
assert not Path('/data').exists()
assert Path('/app/VERSION').read_text().strip()
for attempt in range(30):
try:
session = request('/api/session')
break
except urllib.error.URLError:
if attempt == 29:
raise
time.sleep(1)
assert session['authenticated'] is False
try:
request('/api/state')
except urllib.error.HTTPError as error:
assert error.code == 401
else:
raise AssertionError('Unauthenticated state is exposed')
csrf = request('/api/login', {'password': Path('/run/secrets/ui_password').read_text()})['csrf']
state = request('/api/state')
if sys.argv[-1] == 'write':
assert state['config']['services'] == []
state['config']['services'] = [{'hostname': 'smoke.home', 'display_name': 'Сохранённый сервис',
'upstream': 'http://192.168.42.137:8000',
'ssh': {'alias': 'smoke', 'user': 'admin'}}]
state = request('/api/config', {'config': state['config'], 'revision': state['revision']})
assert state['config']['proxy_ip'] == '192.168.42.11'
assert state['config']['domain_zones'] == ['home']
assert state['config']['services'][0]['display_name'] == 'Сохранённый сервис'
assert b'Host smoke smoke.home' in request('/api/ssh-config')
assert len(list(Path('/config/backups').glob('*.yaml'))) >= 1
print('UI: non-root login, secret isolation, saved configuration and SSH export verified')

150
compose.registry.yaml Normal file
View File

@@ -0,0 +1,150 @@
# Download this file only. Supply settings/passwords via the shell or an optional .env.
# Docker Compose >= 2.30.0 (not docker stack deploy). See REGISTRY.md.
# Example image: git.example.home/your-user/homegate:0.4.0
name: homegate
x-runtime: &runtime
image: "${HOMEGATE_IMAGE:?Set the full registry/owner/homegate:version image name}"
restart: unless-stopped
init: true
user: "1000:1000"
read_only: true
tmpfs:
- /tmp:rw,noexec,nosuid,size=16m
cap_drop: [ALL]
security_opt:
- no-new-privileges:true
pids_limit: 64
mem_limit: 256m
cpus: 0.5
logging:
driver: json-file
options:
max-size: 5m
max-file: "3"
x-environment: &environment
PYTHONDONTWRITEBYTECODE: "1"
PYTHONUNBUFFERED: "1"
HOMEGATE_CONFIG: /config/services.yaml
services:
initialize:
<<: *runtime
entrypoint: [python, /app/bootstrap.py]
command: []
user: "0:0"
restart: "no"
network_mode: none
# Only prepares permissions/configuration, then exits. No secrets or API calls.
cap_add: [CHOWN, DAC_OVERRIDE, FOWNER]
environment:
<<: *environment
HOMEGATE_STATE: /data
HOMEGATE_CONTROL: /control
volumes:
- config:/config
- state:/data
- control:/control
configs:
- source: initial-config
target: /run/configs/homegate-seed.yaml
homegate:
<<: *runtime
depends_on:
initialize:
condition: service_completed_successfully
environment:
<<: *environment
HOMEGATE_STATE: /data
HOMEGATE_CONTROL: /control
NPM_URL: "${NPM_URL:?Set the NPM management URL without /api}"
NPM_IDENTITY: "${NPM_IDENTITY:?Set the NPM login email}"
NPM_PASSWORD_FILE: /run/secrets/npm_password
PIHOLE_URL: "${PIHOLE_URL:-}"
PIHOLE_PASSWORD_FILE: /run/secrets/pihole_password
API_CA_BUNDLE: "${API_CA_BUNDLE:-}"
volumes:
- config:/config:ro
- state:/data
- control:/control
secrets: [npm_password, pihole_password]
healthcheck:
test: [CMD, python, /app/homegate.py, health]
interval: 30s
timeout: 5s
start_period: 120s
retries: 3
ssh-export:
<<: *runtime
command: [serve]
depends_on:
initialize:
condition: service_completed_successfully
environment:
<<: *environment
SSH_BIND_IP: "${HOMEGATE_LAN_IP:?Set the Docker host private IPv4 address}"
ports:
- "${HOMEGATE_LAN_IP:?Set HOMEGATE_LAN_IP}:${SSH_PORT:-8099}:8080"
volumes:
- config:/config:ro
healthcheck:
test: [CMD, python, -c, "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/healthz', timeout=3).read()"]
interval: 30s
timeout: 5s
retries: 3
ui:
<<: *runtime
entrypoint: [python, /app/homegate_ui.py]
command: []
depends_on:
initialize:
condition: service_completed_successfully
environment:
<<: *environment
HOMEGATE_CONTROL: /control
UI_BIND_IP: "${HOMEGATE_LAN_IP:?Set HOMEGATE_LAN_IP}"
UI_ORIGIN: "${UI_ORIGIN:?Set the exact panel URL, for example http://192.168.0.10:8098}"
UI_PASSWORD_FILE: /run/secrets/ui_password
SSH_PUBLIC_URL: "http://${HOMEGATE_LAN_IP}:${SSH_PORT:-8099}/ssh-config"
ports:
- "${HOMEGATE_LAN_IP:?Set HOMEGATE_LAN_IP}:${UI_PORT:-8098}:8081"
volumes:
- config:/config
- control:/control
secrets: [ui_password]
healthcheck:
test: [CMD, python, -c, "import os,urllib.request,urllib.parse; r=urllib.request.Request('http://127.0.0.1:8081/',headers={'Host':urllib.parse.urlsplit(os.environ['UI_ORIGIN']).netloc}); urllib.request.urlopen(r,timeout=3).read()"]
interval: 30s
timeout: 5s
retries: 3
# Seed is copied only when config/services.yaml does not exist in the volume.
# After the first start edit settings in the UI; this seed never overwrites them.
configs:
initial-config:
content: |
proxy_ip: ${HOMEGATE_PROXY_IP:?Set the private IP of NPM}
allowed_networks: ${HOMEGATE_ALLOWED_NETWORKS:?Set a YAML list of allowed LAN subnets}
domain_zones: ${HOMEGATE_ZONES:-[home, home.arpa, lab.internal]}
dns_mode: ${HOMEGATE_DNS_MODE:-pihole6}
interval_seconds: 60
services: []
ssh_hosts: []
# Compose creates secret files. Passwords are not container environment variables.
secrets:
npm_password:
environment: NPM_PASSWORD
pihole_password:
environment: PIHOLE_PASSWORD
ui_password:
environment: UI_PASSWORD
volumes:
config:
state:
control:

139
compose.yaml Normal file
View File

@@ -0,0 +1,139 @@
name: homegate
services:
homegate:
build: .
image: homegate:0.4.0
restart: unless-stopped
init: true
user: "${LOCAL_UID:-1000}:${LOCAL_GID:-1000}"
environment:
PYTHONDONTWRITEBYTECODE: "1"
PYTHONUNBUFFERED: "1"
HOMEGATE_CONFIG: /config/services.yaml
HOMEGATE_STATE: /data
HOMEGATE_CONTROL: /control
NPM_URL: "${NPM_URL:?Set NPM_URL in .env}"
NPM_IDENTITY: "${NPM_IDENTITY:?Set NPM_IDENTITY in .env}"
NPM_PASSWORD_FILE: /run/secrets/npm_password
PIHOLE_URL: "${PIHOLE_URL:-}"
PIHOLE_PASSWORD_FILE: /run/secrets/pihole_password
# Optional PEM bundle for HTTPS management APIs; never disable verification.
API_CA_BUNDLE: "${API_CA_BUNDLE:-}"
volumes:
- ./config:/config:ro
- ./state:/data
- ./control:/control
secrets:
- npm_password
- pihole_password
read_only: true
tmpfs:
- /tmp:rw,noexec,nosuid,size=16m
cap_drop: [ALL]
security_opt:
- no-new-privileges:true
pids_limit: 64
mem_limit: 256m
cpus: 0.5
healthcheck:
test: [CMD, python, /app/homegate.py, health]
interval: 30s
timeout: 5s
start_period: 120s
retries: 3
logging:
driver: json-file
options:
max-size: 5m
max-file: "3"
# No ports, Docker socket or host networking required.
ssh-export:
build: .
image: homegate:0.4.0
command: [serve]
restart: unless-stopped
init: true
user: "${LOCAL_UID:-1000}:${LOCAL_GID:-1000}"
environment:
PYTHONDONTWRITEBYTECODE: "1"
PYTHONUNBUFFERED: "1"
HOMEGATE_CONFIG: /config/services.yaml
SSH_BIND_IP: "${SSH_BIND_IP:?Set the Homegate host LAN IP in .env}"
ports:
- "${SSH_BIND_IP:?Set SSH_BIND_IP}:${SSH_PORT:-8099}:8080"
volumes:
- ./config:/config:ro
# This service has NO CA state, API passwords or Docker socket.
read_only: true
tmpfs:
- /tmp:rw,noexec,nosuid,size=16m
cap_drop: [ALL]
security_opt:
- no-new-privileges:true
pids_limit: 64
mem_limit: 128m
cpus: 0.5
healthcheck:
test: [CMD, python, -c, "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/healthz', timeout=3).read()"]
interval: 30s
timeout: 5s
retries: 3
logging:
driver: json-file
options:
max-size: 5m
max-file: "3"
ui:
build: .
image: homegate:0.4.0
entrypoint: [python, /app/homegate_ui.py]
command: []
restart: unless-stopped
init: true
user: "${LOCAL_UID:-1000}:${LOCAL_GID:-1000}"
environment:
PYTHONDONTWRITEBYTECODE: "1"
PYTHONUNBUFFERED: "1"
HOMEGATE_CONFIG: /config/services.yaml
HOMEGATE_CONTROL: /control
UI_BIND_IP: "${UI_BIND_IP:?Set the Homegate host LAN IP}"
UI_ORIGIN: "${UI_ORIGIN:?Set the exact panel URL in .env}"
UI_PASSWORD_FILE: /run/secrets/ui_password
SSH_PUBLIC_URL: "http://${SSH_BIND_IP}:${SSH_PORT:-8099}/ssh-config"
ports:
- "${UI_BIND_IP:?Set UI_BIND_IP}:${UI_PORT:-8098}:8081"
volumes:
- ./config:/config
- ./control:/control
secrets:
- ui_password
# No CA private keys, NPM/Pi-hole passwords or Docker socket in the UI.
read_only: true
tmpfs:
- /tmp:rw,noexec,nosuid,size=16m
cap_drop: [ALL]
security_opt:
- no-new-privileges:true
pids_limit: 64
mem_limit: 128m
cpus: 0.5
healthcheck:
test: [CMD, python, -c, "import os,urllib.request,urllib.parse; r=urllib.request.Request('http://127.0.0.1:8081/',headers={'Host':urllib.parse.urlsplit(os.environ['UI_ORIGIN']).netloc}); urllib.request.urlopen(r,timeout=3).read()"]
interval: 30s
timeout: 5s
retries: 3
logging:
driver: json-file
options:
max-size: 5m
max-file: "3"
secrets:
ui_password:
file: ./secrets/ui_password
npm_password:
file: ./secrets/npm_password
pihole_password:
file: ./secrets/pihole_password

50
config/services.yaml Normal file
View File

@@ -0,0 +1,50 @@
# LAN address where NPM accepts connections on 443 (NOT the upstream VM).
proxy_ip: 192.168.0.10
# DNS suffixes allowed for web services and certificates. ASCII/punycode.
# Add custom zones before first startup; expanding an existing CA needs rotate-ca.
domain_zones:
- home
- home.arpa
- lab.internal
# Requests from other source addresses receive 403. Use your actual subnet.
allowed_networks:
- 192.168.0.0/24
# pihole6 = automatic local DNS through Pi-hole API.
# manual = configure DNS in Pi-hole yourself; also works with Pi-hole 5.
dns_mode: pihole6
interval_seconds: 60
services:
- hostname: pve.home
# Optional label shown in the UI; domain and SSH aliases stay independent.
# display_name: Proxmox
upstream: https://192.168.0.137:8006
# Explicit exception for the default self-signed Proxmox certificate.
# Browser -> NPM is still verified HTTPS after installing Homegate's root CA.
upstream_tls_verify: false
websocket: true
timeout_seconds: 3600
max_body_mb: 10240
ssh:
alias: pve
user: root
port: 22
# host defaults to 192.168.0.137 from upstream (NOT the NPM address).
# - hostname: grafana.home
# upstream: http://192.168.0.120:3000
# - hostname: nas.home.arpa
# upstream: https://192.168.0.130:443
# upstream_tls_name: nas.home.arpa
# upstream_ca_file: /data/custom-trust/nas-ca.pem # path INSIDE NPM
# upstream_tls_verify: true
# enabled: true
# Optional SSH-only machines. No DNS or NPM objects are created for these.
ssh_hosts: []
# ssh_hosts:
# - aliases: [backup, backup.lab.internal]
# host: 192.168.0.150
# port: 2222
# user: admin

692
homegate.py Normal file
View File

@@ -0,0 +1,692 @@
"""Local DNS/NPM controller and a separate read-only LAN SSH config exporter."""
from __future__ import annotations
import argparse
import copy
import fcntl
import hashlib
import ipaddress
import json
import logging
import os
from pathlib import Path
import re
import signal
import shutil
import sys
import tempfile
import threading
import time
from datetime import datetime, timedelta, timezone
from urllib.parse import quote, urlsplit
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
import uuid
import requests
import yaml
from cryptography import x509
from cryptography.exceptions import InvalidSignature
from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import ec
from cryptography.x509.oid import ExtendedKeyUsageOID, NameOID
from sync_ssh import render_ssh, validate_entry
LOG = logging.getLogger("homegate")
STOP = threading.Event()
PRIVATE = tuple(ipaddress.ip_network(n) for n in
("10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16", "fc00::/7"))
LABEL = r"[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?"
DOMAIN = re.compile(r"(?=.{1,253}$)" + LABEL + r"(?:\." + LABEL + r")+$")
ZONE = re.compile(r"(?=.{1,253}$)" + LABEL + r"(?:\." + LABEL + r")*$")
DEFAULT_ZONES = ["home", "home.arpa"]
class Error(RuntimeError):
pass
def require(ok, message):
if not ok:
raise Error(message)
def private_address(value):
address = ipaddress.ip_address(value)
require(any(address.version == n.version and address in n for n in PRIVATE),
f"Expected RFC1918 or ULA address: {value}")
return str(address)
def number(value, minimum, maximum, name):
require(type(value) is int and minimum <= value <= maximum,
f"{name} must be an integer between {minimum} and {maximum}")
return value
def boolean(value, name):
require(type(value) is bool, f"{name} must be true or false")
return value
def in_zones(hostname, zones):
return any(hostname == zone or hostname.endswith("." + zone) for zone in zones)
def normalize_zones(value):
require(isinstance(value, list) and 0 < len(value) <= 64, "domain_zones must contain 1–64 zones")
zones = []
for zone in value:
require(isinstance(zone, str), "Domain zones must be strings")
zone = zone.strip(".").lower()
require(ZONE.fullmatch(zone) is not None, "Invalid domain zone; use ASCII/punycode without wildcards")
require(zone not in zones, "Duplicate domain zone: " + zone)
zones.append(zone)
return zones
def load_config(path):
return validate_config(yaml.safe_load(Path(path).read_text()))
def validate_config(value):
c = copy.deepcopy(value)
require(isinstance(c, dict), "Config must be a YAML mapping")
require(not set(c) - {"proxy_ip", "allowed_networks", "dns_mode", "interval_seconds", "services",
"domain_zones", "ssh_hosts"},
"Unknown top-level config key")
c["domain_zones"] = normalize_zones(c.get("domain_zones", DEFAULT_ZONES))
c["proxy_ip"] = private_address(c["proxy_ip"])
require(isinstance(c.get("allowed_networks"), list) and c["allowed_networks"],
"allowed_networks must be a non-empty list")
nets = []
for raw in c["allowed_networks"]:
net = ipaddress.ip_network(raw, strict=True)
require(any(net.version == n.version and net.subnet_of(n) for n in PRIVATE),
"allowed_networks must be RFC1918 or ULA subnets")
nets.append(str(net))
c["allowed_networks"] = nets
c.setdefault("dns_mode", "pihole6")
require(c["dns_mode"] in ("pihole6", "manual"), "dns_mode must be pihole6 or manual")
c["interval_seconds"] = number(c.get("interval_seconds", 60), 30, 3600, "interval_seconds")
require(isinstance(c.get("services"), list), "services must be a list")
seen = set()
for r in c["services"]:
require(isinstance(r, dict), "Each service must be a mapping")
require(not set(r) - {"hostname", "display_name", "upstream", "upstream_tls_verify", "upstream_tls_name",
"upstream_ca_file", "websocket", "timeout_seconds", "max_body_mb", "enabled", "ssh"},
"Unknown service config key")
if "display_name" in r:
name = r["display_name"]
require(isinstance(name, str) and bool(name.strip()) and len(name) <= 100
and not any(ord(ch) < 32 or ord(ch) == 127 for ch in name),
"display_name must be a non-empty single-line string of at most 100 characters")
host = r["hostname"]
require(isinstance(host, str) and DOMAIN.fullmatch(host) and
in_zones(host, c["domain_zones"]),
"hostname must be a lowercase DNS name in domain_zones")
require(host not in seen, f"Duplicate hostname: {host}")
seen.add(host)
u = urlsplit(r["upstream"])
require(u.scheme in ("http", "https") and not u.username and not u.password
and u.path in ("", "/") and not u.query and not u.fragment,
f"{host}: upstream must be http(s)://private-IP:port without path or credentials")
r["forward_host"] = private_address(u.hostname)
require(":" not in r["forward_host"], "This release supports IPv4 upstream VMs only")
r["forward_scheme"] = u.scheme
r["forward_port"] = number(u.port or (443 if u.scheme == "https" else 80), 1, 65535, "port")
for k, default in (("enabled", True), ("websocket", True), ("upstream_tls_verify", True)):
r[k] = boolean(r.get(k, default), k)
r["timeout_seconds"] = number(r.get("timeout_seconds", 3600), 1, 86400, "timeout_seconds")
r["max_body_mb"] = number(r.get("max_body_mb", 1024), 1, 102400, "max_body_mb")
if "upstream_tls_name" in r:
require(isinstance(r["upstream_tls_name"], str) and DOMAIN.fullmatch(r["upstream_tls_name"]),
"Invalid upstream_tls_name")
if "upstream_ca_file" in r:
p = r["upstream_ca_file"]
require(isinstance(p, str) and re.fullmatch(r"/[a-zA-Z0-9_./-]+", p)
and ".." not in Path(p).parts, "Unsafe upstream_ca_file path")
if "ssh" in r:
s = r["ssh"]
require(isinstance(s, dict) and not set(s) - {"alias", "host", "port", "user", "enabled"},
"service.ssh accepts alias, host, port, user and enabled")
boolean(s.get("enabled", True), "ssh.enabled")
require(isinstance(c.get("ssh_hosts", []), list), "ssh_hosts must be a list")
# Validate the complete inventory (including duplicate aliases) before any side effects.
ssh_entries(c)
return c
def ssh_entries(config):
entries = []
for route in config["services"]:
s = route.get("ssh")
if s is None:
continue
aliases = [route["hostname"]]
if s.get("alias") and s["alias"] not in aliases:
aliases.insert(0, s["alias"])
entry = {"aliases": aliases, "host": s.get("host", route["forward_host"]),
"port": s.get("port", 22)}
if "user" in s:
entry["user"] = s["user"]
validate_entry(entry)
if route["enabled"] and s.get("enabled", True):
entries.append(entry)
for item in config.get("ssh_hosts", []):
require(isinstance(item, dict) and not set(item) - {"aliases", "host", "port", "user", "enabled"},
"ssh_hosts entries accept aliases, host, port, user and enabled")
enabled = boolean(item.get("enabled", True), "ssh_hosts.enabled")
entry = {k: v for k, v in item.items() if k != "enabled"}
entry.setdefault("port", 22)
validate_entry(entry)
if enabled:
entries.append(entry)
render_ssh(entries) # Also rejects aliases shared by two different entries.
return entries
def atomic(path, data, mode=0o600):
path = Path(path)
path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
temporary = path.with_name(path.name + ".tmp")
fd = os.open(temporary, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, mode)
with os.fdopen(fd, "wb") as f:
f.write(data if isinstance(data, bytes) else data.encode())
f.flush()
os.fsync(f.fileno())
os.chmod(temporary, mode)
os.replace(temporary, path)
def save_json(path, value):
atomic(path, json.dumps(value, indent=2))
def read_json(path, default=None):
return json.loads(path.read_text()) if path.exists() else default
def now():
return datetime.now(timezone.utc)
def pem_key(key):
return key.private_bytes(serialization.Encoding.PEM, serialization.PrivateFormat.PKCS8,
serialization.NoEncryption()).decode()
class Authority:
def __init__(self, state, zones=None):
self.state = state
self.zones = normalize_zones(zones if zones is not None else DEFAULT_ZONES)
bundle_path = state / "ca.json"
bundle = read_json(bundle_path)
if bundle is None:
require(not (state / "registry.json").exists(), "CA missing from existing state; restore backup")
key = ec.generate_private_key(ec.SECP384R1())
subject = x509.Name([x509.NameAttribute(NameOID.COMMON_NAME, "Homegate Local Root CA")])
cert = (x509.CertificateBuilder().subject_name(subject).issuer_name(subject)
.public_key(key.public_key()).serial_number(x509.random_serial_number())
.not_valid_before(now() - timedelta(minutes=5))
.not_valid_after(now() + timedelta(days=3650))
.add_extension(x509.BasicConstraints(ca=True, path_length=0), critical=True)
.add_extension(x509.KeyUsage(False, False, False, False, False, True, True, False, False), True)
.add_extension(x509.SubjectKeyIdentifier.from_public_key(key.public_key()), False)
.add_extension(x509.NameConstraints([x509.DNSName(z) for z in self.zones], None), True)
.sign(key, hashes.SHA384()))
bundle = {"key": pem_key(key), "cert": cert.public_bytes(serialization.Encoding.PEM).decode()}
save_json(bundle_path, bundle)
LOG.info("Created local root CA; install root-ca.crt on client devices")
self.key = serialization.load_pem_private_key(bundle["key"].encode(), password=None)
self.cert = x509.load_pem_x509_certificate(bundle["cert"].encode())
constraints = self.cert.extensions.get_extension_for_class(x509.NameConstraints).value
self.permitted_zones = [n.value for n in constraints.permitted_subtrees if isinstance(n, x509.DNSName)]
require(self.key.public_key().public_numbers() == self.cert.public_key().public_numbers(),
"CA key does not match certificate")
require(self.cert.not_valid_after_utc > now() + timedelta(days=91),
"Root CA expires in under 91 days; migrate client trust to a new CA")
atomic(state / "root-ca.crt", bundle["cert"], 0o644)
def leaf(self, hostname):
require(self.cert.not_valid_after_utc > now() + timedelta(days=91),
"Root CA expires in under 91 days; migrate client trust to a new CA")
require(DOMAIN.fullmatch(hostname) and in_zones(hostname, self.zones),
"Refusing to issue outside configured domain_zones")
require(in_zones(hostname, self.permitted_zones),
"Existing root CA does not permit this zone; stop controller and run rotate-ca, then install new root on clients")
path = self.state / "issued" / f"{hostname}.json"
bundle = read_json(path)
if bundle:
cert = x509.load_pem_x509_certificate(bundle["cert"].encode())
same_issuer = True
try:
cert.verify_directly_issued_by(self.cert)
except (InvalidSignature, ValueError):
same_issuer = False # A deliberate CA rotation requires new leaves.
if same_issuer and cert.not_valid_after_utc > now() + timedelta(days=30):
key = serialization.load_pem_private_key(bundle["key"].encode(), password=None)
require(key.public_key().public_numbers() == cert.public_key().public_numbers(),
"Leaf private key does not match certificate")
require(cert.extensions.get_extension_for_class(x509.SubjectAlternativeName).value
.get_values_for_type(x509.DNSName) == [hostname], "Leaf SAN mismatch")
return bundle
key = ec.generate_private_key(ec.SECP256R1())
subject = x509.Name([x509.NameAttribute(NameOID.COMMON_NAME, hostname[:64])])
cert = (x509.CertificateBuilder().subject_name(subject).issuer_name(self.cert.subject)
.public_key(key.public_key()).serial_number(x509.random_serial_number())
.not_valid_before(now() - timedelta(minutes=5)).not_valid_after(now() + timedelta(days=90))
.add_extension(x509.BasicConstraints(ca=False, path_length=None), True)
.add_extension(x509.KeyUsage(True, False, False, False, False, False, False, False, False), True)
.add_extension(x509.ExtendedKeyUsage([ExtendedKeyUsageOID.SERVER_AUTH]), False)
.add_extension(x509.SubjectAlternativeName([x509.DNSName(hostname)]), False)
.add_extension(x509.SubjectKeyIdentifier.from_public_key(key.public_key()), False)
.add_extension(x509.AuthorityKeyIdentifier.from_issuer_public_key(self.key.public_key()), False)
.sign(self.key, hashes.SHA384()))
bundle = {"key": pem_key(key), "cert": cert.public_bytes(serialization.Encoding.PEM).decode()}
save_json(path, bundle)
LOG.info("Issued 90-day certificate for %s", hostname)
return bundle
def rotate_ca(state, zones):
"""Explicit trust migration; preserve instance/route IDs and old CA for recovery."""
require((state / "ca.json").exists(), "No existing CA; run once/run to initialize it")
history = state / "ca-history" / (datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ-") + uuid.uuid4().hex[:8])
history.mkdir(parents=True, mode=0o700)
# Stage the new CA before changing the active one. ca.json is the source of truth.
with tempfile.TemporaryDirectory(dir=state, prefix="ca-next-") as temp:
prepared = Path(temp)
Authority(prepared, zones)
for name in ("ca.json", "root-ca.crt"):
if (state / name).exists():
shutil.copy2(state / name, history / name)
atomic(state / "ca.json", (prepared / "ca.json").read_bytes())
atomic(state / "root-ca.crt", (prepared / "root-ca.crt").read_bytes(), 0o644)
LOG.warning("CA rotated. Install state/root-ca.crt on clients before restarting. Previous CA: %s", history)
return history
def export_response(path, peer, config_path):
"""No directory serving. Only a validated SSH inventory can leave this process."""
config = load_config(config_path)
address = ipaddress.ip_address(peer)
if address.version == 6 and address.ipv4_mapped:
address = address.ipv4_mapped
local_health = path == "/healthz" and address.is_loopback
allowed = any(address.version == n.version and address in n for n in
(ipaddress.ip_network(raw) for raw in config["allowed_networks"]))
if not allowed and not local_health:
return 403, b"Forbidden\n", "text/plain; charset=utf-8"
if path == "/healthz":
return 200, b"ok\n", "text/plain; charset=utf-8"
if path == "/ssh-config":
return 200, render_ssh(ssh_entries(config)).encode(), "text/plain; charset=utf-8"
return 404, b"Not found\n", "text/plain; charset=utf-8"
def export_handler(config_path):
class Handler(BaseHTTPRequestHandler):
server_version = "Homegate"
sys_version = ""
def setup(self):
super().setup()
self.connection.settimeout(10)
def do_GET(self):
try:
status, body, content_type = export_response(self.path, self.client_address[0], config_path)
except (Error, ValueError, KeyError, TypeError, OSError, yaml.YAMLError):
status, body, content_type = 503, b"Invalid or unavailable configuration\n", "text/plain"
self.send_response(status)
self.send_header("Content-Type", content_type)
self.send_header("Content-Length", str(len(body)))
self.send_header("Cache-Control", "no-store")
self.send_header("X-Content-Type-Options", "nosniff")
if status == 200 and self.path == "/ssh-config":
self.send_header("Content-Disposition", 'attachment; filename="homegate.conf"')
self.end_headers()
if self.command != "HEAD":
self.wfile.write(body)
do_HEAD = do_GET
def log_message(self, fmt, *args):
LOG.info("SSH export: peer=%s status=%s", self.client_address[0], args[1] if len(args) > 1 else "-")
return Handler
def serve_export(config_path):
load_config(config_path)
# Compose requires an explicit private host IP; never publish on every host interface.
bind_ip = private_address(os.environ.get("SSH_BIND_IP", ""))
require(ipaddress.ip_address(bind_ip).version == 4, "SSH_BIND_IP must be a private IPv4 address")
with ThreadingHTTPServer(("0.0.0.0", 8080), export_handler(config_path)) as server:
LOG.info("SSH export available through Docker binding %s; path /ssh-config", bind_ip)
server.serve_forever()
class API:
def __init__(self, url, label, verify=True):
u = urlsplit(url)
require(u.scheme in ("http", "https") and u.hostname and not u.username and not u.password
and u.path in ("", "/") and not u.query and not u.fragment,
f"{label}_URL must be http(s)://host:port without /api, /admin or credentials")
self.base = url.rstrip("/") + "/api"
self.label = label
self.session = requests.Session()
self.session.trust_env = False # Keep LAN credentials out of environment HTTP proxies.
self.session.verify = verify
def call(self, method, path, **kwargs):
try:
response = self.session.request(method, self.base + path, timeout=(5, 30),
allow_redirects=False, **kwargs)
except requests.RequestException:
raise Error(f"{self.label}: connection or TLS error at {path}") from None
require(200 <= response.status_code < 300,
f"{self.label}: HTTP {response.status_code} at {path}; check credentials, version and permissions")
# Do not log response bodies: NPM upload responses contain the private key.
if not response.content:
return None
try:
return response.json()
except ValueError:
raise Error(f"{self.label}: non-JSON response at {path}; check management URL") from None
def close(self):
self.session.close()
class NPM(API):
def login(self, identity, password):
token = self.call("POST", "/tokens", json={"identity": identity, "secret": password})
self.session.headers["Authorization"] = "Bearer " + token["token"]
def inventory(self):
self.hosts = self.call("GET", "/nginx/proxy-hosts")
self.certs = self.call("GET", "/nginx/certificates")
def find_host(self, hostname, marker):
matches = [h for h in self.hosts if hostname in h["domain_names"]]
require(len(matches) <= 1, f"Multiple NPM hosts for {hostname}")
if not matches:
return None
host = matches[0]
require(host["domain_names"] == [hostname] and
host.get("advanced_config", "").splitlines()[:1] == [marker],
f"{hostname}: NPM host already exists and is not managed by this instance")
return host
def certificate(self, name, bundle, uploaded):
matches = [c for c in self.certs if c.get("nice_name") == name]
require(len(matches) <= 1, f"Duplicate managed certificate: {name}")
cert = matches[0] if matches else self.call("POST", "/nginx/certificates",
json={"provider": "other", "nice_name": name})
require(cert["provider"] == "other", "Expected a custom NPM certificate")
if not matches:
self.certs.append(cert)
digest = hashlib.sha256(bundle["cert"].encode()).hexdigest()
signature = {"id": cert["id"], "sha256": digest}
changed = signature != uploaded or not cert.get("meta", {}).get("certificate")
if changed:
self.call("POST", f'/nginx/certificates/{cert["id"]}/upload', files={
"certificate": ("certificate.pem", bundle["cert"], "application/x-pem-file"),
"certificate_key": ("key.pem", bundle["key"], "application/x-pem-file"),
})
return cert["id"], changed, signature
def host(self, existing, payload, force_reload=False):
if existing:
unhealthy = payload["enabled"] and existing.get("meta", {}).get("nginx_online") is not True
if force_reload or unhealthy or any(existing.get(k) != v for k, v in payload.items()):
result = self.call("PUT", f'/nginx/proxy-hosts/{existing["id"]}', json=payload)
else:
result = existing
else:
result = self.call("POST", "/nginx/proxy-hosts", json=payload)
self.hosts.append(result)
if payload["enabled"]:
require(result.get("meta", {}).get("nginx_online") is True,
"NPM could not activate nginx configuration; inspect the host in NPM")
return result
class PiHole(API):
def login(self, password):
session = self.call("POST", "/auth", json={"password": password})["session"]
require(session.get("valid") and session.get("sid"), "Pi-hole authentication failed")
self.session.headers["X-FTL-SID"] = session["sid"]
self.session.headers["X-FTL-CSRF"] = session["csrf"]
def records(self):
dns = self.call("GET", "/config/dns")["config"]["dns"]
self.hosts = dns["hosts"]
self.cnames = dns.get("cnameRecords", [])
def check(self, hostname, address):
for entry in self.hosts:
fields = entry.split("#", 1)[0].split()
if len(fields) > 1 and hostname in [s.lower().rstrip(".") for s in fields[1:]]:
require(fields[0] == address, f"{hostname}: conflicting Pi-hole record: {entry}")
for entry in self.cnames:
require(entry.split(",")[0].strip().lower().rstrip(".") != hostname,
f"{hostname}: existing Pi-hole CNAME; remove it or use manual DNS")
def ensure(self, hostname, address):
self.check(hostname, address)
if any(hostname in [s.lower().rstrip(".") for s in e.split("#", 1)[0].split()[1:]] for e in self.hosts):
return
entry = f"{address} {hostname}"
self.call("PUT", "/config/dns/hosts/" + quote(entry, safe=""))
self.hosts.append(entry)
LOG.info("DNS: %s -> %s", hostname, address)
def close(self):
try:
if "X-FTL-SID" in self.session.headers:
self.call("DELETE", "/auth")
except Error:
LOG.warning("Pi-hole logout failed; session will expire")
finally:
super().close()
def payload(config, route, cert_id, marker):
advanced = [marker]
advanced += [f"allow {net};" for net in config["allowed_networks"]] + ["deny all;"]
advanced += [f'client_max_body_size {route["max_body_mb"]}m;', "proxy_buffering off;",
"proxy_request_buffering off;", f'proxy_read_timeout {route["timeout_seconds"]}s;',
f'proxy_send_timeout {route["timeout_seconds"]}s;', "proxy_connect_timeout 10s;"]
if route["forward_scheme"] == "https":
advanced += ["proxy_ssl_server_name on;",
f'proxy_ssl_name {route.get("upstream_tls_name", route["forward_host"])};',
"proxy_ssl_verify " + ("on;" if route["upstream_tls_verify"] else "off;")]
if route["upstream_tls_verify"]:
advanced += ["proxy_ssl_verify_depth 3;", "proxy_ssl_trusted_certificate " +
route.get("upstream_ca_file", "/etc/ssl/certs/ca-certificates.crt") + ";"]
return {"domain_names": [route["hostname"]], "forward_scheme": route["forward_scheme"],
"forward_host": route["forward_host"], "forward_port": route["forward_port"],
"certificate_id": cert_id, "ssl_forced": True, "http2_support": True,
"hsts_enabled": False, "hsts_subdomains": False, "block_exploits": False,
"caching_enabled": False, "allow_websocket_upgrade": route["websocket"],
"access_list_id": 0, "advanced_config": "\n".join(advanced),
"locations": [], "enabled": route["enabled"]}
def reconcile(config, state, ca, registry, npm, dns):
npm.inventory()
dns_error = False
if dns:
try:
dns.records()
except Error as exc:
LOG.error("DNS unavailable; continuing certificate/proxy maintenance: %s", exc)
dns = None
dns_error = True
failures = []
current = {r["hostname"] for r in config["services"]}
for stale in set(registry["routes"]) - current:
LOG.warning("%s removed from file; NPM host and DNS retained. Disable/delete explicitly in their UIs.", stale)
for route in config["services"]:
host = route["hostname"]
name = f'homegate:{registry["instance"]}:{host}'
marker = "# " + name
try:
existing = npm.find_host(host, marker)
if dns and route["enabled"]:
dns.check(host, config["proxy_ip"])
bundle = ca.leaf(host)
previous = registry["routes"].get(host, {})
cert_id, changed, signature = npm.certificate(name, bundle, previous.get("uploaded"))
result = npm.host(existing, payload(config, route, cert_id, marker), force_reload=changed)
# Save only AFTER nginx accepts the host/reload. Failed upload/reload is retried.
registry["routes"][host] = {"host_id": result["id"], "uploaded": signature}
save_json(state / "registry.json", registry)
# Publish DNS only once proxy and TLS are configured.
if dns and route["enabled"]:
dns.ensure(host, config["proxy_ip"])
if changed or not existing:
LOG.info("Configured https://%s -> %s", host, route["upstream"])
except (Error, ValueError, KeyError, OSError) as exc:
failures.append(host)
LOG.error("%s: %s", host, exc)
require(not failures, "Routes failed: " + ", ".join(failures))
require(not dns_error, "DNS sync failed; proxy/certificate maintenance completed")
def secret(name):
p = os.environ.get(name + "_PASSWORD_FILE", f"/run/secrets/{name.lower()}_password")
value = Path(p).read_text().rstrip("\r\n")
require(bool(value), f"Empty {name} password file")
return value
def cycle(config, state, ca, registry):
verify = os.environ.get("API_CA_BUNDLE") or True
npm = NPM(os.environ.get("NPM_URL", ""), "NPM", verify)
dns = None
dns_error = False
try:
npm.login(os.environ.get("NPM_IDENTITY", ""), secret("NPM"))
if config["dns_mode"] == "pihole6":
dns = PiHole(os.environ.get("PIHOLE_URL", ""), "PIHOLE", verify)
try:
dns.login(secret("PIHOLE"))
except (Error, OSError) as exc:
LOG.error("Pi-hole login unavailable; continuing proxy maintenance: %s", exc)
dns.close()
dns = None
dns_error = True
reconcile(config, state, ca, registry, npm, dns)
require(not dns_error, "Pi-hole login failed; proxy/certificate maintenance completed")
finally:
npm.close()
if dns:
dns.close()
def publish_panel_status(control, revision, config, state, ca, ok, error):
"""Export only public certificate/status information to the UI's separate volume."""
control.mkdir(parents=True, exist_ok=True, mode=0o700)
previous = read_json(control / "status.json", {})
certs = []
for route in config["services"]:
path = state / "issued" / (route["hostname"] + ".json")
if path.exists():
cert = x509.load_pem_x509_certificate(read_json(path)["cert"].encode())
certs.append({"hostname": route["hostname"], "expires": cert.not_valid_after_utc.isoformat()})
save_json(control / "status.json", {
"ok": ok, "time": time.time(), "max_age": max(180, config["interval_seconds"] * 3),
"error": error, "applied_revision": revision if ok else previous.get("applied_revision"),
"root": {"pem": ca.cert.public_bytes(serialization.Encoding.PEM).decode(),
"fingerprint": ca.cert.fingerprint(hashes.SHA256()).hex(":"),
"expires": ca.cert.not_valid_after_utc.isoformat(), "zones": ca.permitted_zones},
"certificates": certs,
})
def main():
os.umask(0o077)
logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("command", choices=("run", "once", "validate", "health", "fingerprint", "rotate-ca", "serve", "ssh-config"), default="run", nargs="?")
args = parser.parse_args()
state = Path(os.environ.get("HOMEGATE_STATE", "/data"))
path = Path(os.environ.get("HOMEGATE_CONFIG", "/config/services.yaml"))
control = Path(os.environ.get("HOMEGATE_CONTROL", "/control"))
if args.command == "serve":
serve_export(path)
return 0
if args.command == "health":
status = read_json(state / "status.json", {})
return 0 if status.get("ok") and time.time() - status.get("time", 0) < status.get("max_age", 180) else 1
if args.command == "fingerprint":
cert = x509.load_pem_x509_certificate((state / "root-ca.crt").read_bytes())
print("SHA256:", cert.fingerprint(hashes.SHA256()).hex(":"))
return 0
config = load_config(path)
if args.command == "ssh-config":
print(render_ssh(ssh_entries(config)), end="")
return 0
if args.command == "validate":
for route in config["services"]:
print(f'{route["hostname"]} -> {config["proxy_ip"]}:443 -> {route["upstream"]}')
print(f'Config valid; DNS mode: {config["dns_mode"]}. No API calls were made.')
print(f'Domain zones: {", ".join(config["domain_zones"])}; SSH hosts: {len(ssh_entries(config))}')
return 0
state.mkdir(parents=True, exist_ok=True, mode=0o700)
with (state / "controller.lock").open("a") as lock:
try:
fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
except BlockingIOError:
raise Error("Another Homegate controller is already using this state") from None
if args.command == "rotate-ca":
rotate_ca(state, config["domain_zones"])
return 0
ca = Authority(state, config["domain_zones"])
registry = read_json(state / "registry.json", {"instance": str(uuid.uuid4()), "routes": {}})
save_json(state / "registry.json", registry)
for sig in (signal.SIGTERM, signal.SIGINT):
signal.signal(sig, lambda *_: STOP.set())
while not STOP.is_set():
ok = False
sync_error = None
revision = None
request_path = control / "sync-request.json"
request_before = request_path.read_bytes() if request_path.exists() else None
try:
# Hash the same bytes we apply, even when the UI saves during a slow API call.
raw = path.read_bytes()
revision = hashlib.sha256(raw).hexdigest()
config = validate_config(yaml.safe_load(raw))
ca.zones = config["domain_zones"]
cycle(config, state, ca, registry)
ok = True
except (Error, ValueError, KeyError, TypeError, OSError, yaml.YAMLError) as exc:
sync_error = str(exc)
LOG.error("Sync failed: %s", exc)
save_json(state / "status.json", {"ok": ok, "time": time.time(),
"max_age": max(180, config["interval_seconds"] * 3)})
try:
publish_panel_status(control, revision, config, state, ca, ok, sync_error)
except (ValueError, KeyError, OSError) as exc:
LOG.warning("Could not export panel status: %s", exc)
if args.command == "once":
return 0 if ok else 1
deadline = time.monotonic() + config["interval_seconds"]
while not STOP.is_set() and time.monotonic() < deadline:
current_request = request_path.read_bytes() if request_path.exists() else None
if current_request != request_before:
break
STOP.wait(min(2, max(0, deadline - time.monotonic())))
return 0
if __name__ == "__main__":
try:
sys.exit(main())
except (Error, ValueError, KeyError, TypeError, OSError, yaml.YAMLError) as exc:
LOG.error("%s", exc)
sys.exit(1)

275
homegate_ui.py Normal file
View File

@@ -0,0 +1,275 @@
"""Homegate local management UI. Config writes + public controller status only."""
import argparse
from collections import defaultdict
import fcntl
import hashlib
import hmac
from http.cookies import SimpleCookie
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
import ipaddress
import json
import logging
import os
from pathlib import Path
import secrets
import threading
import time
from urllib.parse import urlsplit
import yaml
import homegate as h
LOG = logging.getLogger("homegate.ui")
BASE = Path(__file__).resolve().parent
MAX_BODY = 1024 * 1024
class UIError(Exception):
def __init__(self, message, status=400):
self.status = status
super().__init__(message)
class Panel:
def __init__(self, config, control, origin, local=False, password_file=None, ssh_url=""):
self.config = Path(config)
self.control = Path(control)
self.origin = origin.rstrip("/")
self.authority = urlsplit(self.origin).netloc
parsed_origin = urlsplit(self.origin)
if (parsed_origin.scheme not in ("http", "https") or not self.authority
or parsed_origin.path or parsed_origin.query or parsed_origin.fragment or parsed_origin.username):
raise UIError("UI_ORIGIN must be the exact http(s)://host:port of the panel")
self.local = local
self.password_file = password_file
self.ssh_url = ssh_url
self.sessions = {}
self.attempts = defaultdict(list)
self.mutex = threading.RLock()
if not local and (not password_file or len(Path(password_file).read_text().strip()) < 12):
raise UIError("UI password must contain at least 12 characters; run setup.sh")
h.load_config(self.config)
def config_data(self):
raw = self.config.read_bytes()
value = yaml.safe_load(raw)
h.validate_config(value)
return value, hashlib.sha256(raw).hexdigest()
def allowed(self, peer):
address = ipaddress.ip_address(peer)
if address.version == 6 and address.ipv4_mapped:
address = address.ipv4_mapped
if address.is_loopback:
return True
if self.local:
return False
c = h.load_config(self.config)
return any(address.version == net.version and address in net for net in
(ipaddress.ip_network(n) for n in c["allowed_networks"]))
def session(self, cookie):
jar = SimpleCookie()
try:
jar.load(cookie or "")
token = jar["homegate_session"].value if "homegate_session" in jar else ""
except Exception:
token = ""
with self.mutex:
self.sessions = {k: v for k, v in self.sessions.items() if v["expires"] > time.time()}
return token, self.sessions.get(token)
def new_session(self):
with self.mutex:
if len(self.sessions) >= 128:
self.sessions.pop(next(iter(self.sessions)))
token = secrets.token_urlsafe(32)
entry = {"csrf": secrets.token_urlsafe(32), "expires": time.time() + 12 * 3600}
self.sessions[token] = entry
return token, entry
def login(self, password, peer):
with self.mutex:
self.attempts = defaultdict(list, {k: [t for t in v if time.time() - t < 60]
for k, v in self.attempts.items() if any(time.time() - t < 60 for t in v)})
attempts = self.attempts[peer]
if len(attempts) >= 5:
raise UIError("Слишком много попыток. Подождите минуту.", 429)
attempts.append(time.time())
expected = Path(self.password_file).read_text().rstrip("\r\n")
if not isinstance(password, str) or not hmac.compare_digest(password.encode(), expected.encode()):
raise UIError("Неверный пароль", 401)
self.attempts.pop(peer, None)
return self.new_session()
def status(self):
value, revision = self.config_data()
snapshot = h.read_json(self.control / "status.json", {})
fresh = bool(snapshot) and time.time() - snapshot.get("time", 0) < snapshot.get("max_age", 180)
history = h.read_json(self.control / "ui-history.json", [])
return {"config": value, "revision": revision, "mode": "local" if self.local else "lan",
"ssh_url": self.ssh_url, "controller": {**snapshot, "fresh": fresh}, "history": history[:8]}
def save(self, value, revision):
h.validate_config(value)
data = yaml.safe_dump(value, sort_keys=False, allow_unicode=True).encode()
with self.mutex:
lock_path = self.config.parent / ".ui-config.lock"
with lock_path.open("a") as lock:
fcntl.flock(lock, fcntl.LOCK_EX)
original = self.config.read_bytes()
if hashlib.sha256(original).hexdigest() != revision:
raise UIError("Настройки уже изменились. Обновите страницу и повторите сохранение.", 409)
backup = self.config.parent / "backups" / f"services-{time.time_ns()}.yaml"
h.atomic(backup, original)
# Preserve readability for the export container running under the same UID.
h.atomic(self.config, data, 0o644)
backups = sorted(backup.parent.glob("services-*.yaml"))
for stale in backups[:-20]:
stale.unlink()
self.control.mkdir(parents=True, exist_ok=True, mode=0o700)
history = h.read_json(self.control / "ui-history.json", [])
h.save_json(self.control / "ui-history.json", [{"time": time.time(), "text": "Настройки сохранены"}] + history[:19])
return self.status()
def request_sync(self):
self.control.mkdir(parents=True, exist_ok=True, mode=0o700)
h.save_json(self.control / "sync-request.json", {"id": secrets.token_hex(16), "time": time.time()})
return {"queued": True, "fresh": self.status()["controller"]["fresh"]}
def handler_for(panel):
class Handler(BaseHTTPRequestHandler):
server_version = "Homegate"
sys_version = ""
def setup(self):
super().setup()
self.connection.settimeout(15)
def respond(self, status, body, content_type="application/json; charset=utf-8", cookie=None, filename=None):
if not isinstance(body, bytes):
body = json.dumps(body, ensure_ascii=False).encode()
self.send_response(status)
self.send_header("Content-Type", content_type)
self.send_header("Content-Length", str(len(body)))
self.send_header("Cache-Control", "no-store")
self.send_header("X-Content-Type-Options", "nosniff")
self.send_header("Referrer-Policy", "no-referrer")
self.send_header("X-Frame-Options", "DENY")
self.send_header("Content-Security-Policy", "default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; connect-src 'self'; frame-ancestors 'none'; base-uri 'none'; form-action 'self'")
if cookie is not None:
secure = "; Secure" if panel.origin.startswith("https:") else ""
self.send_header("Set-Cookie", f"homegate_session={cookie}; Path=/; HttpOnly; SameSite=Strict; Max-Age=43200{secure}")
if filename:
self.send_header("Content-Disposition", f'attachment; filename="{filename}"')
self.end_headers()
self.wfile.write(body)
def dispatch(self):
if self.headers.get("Host", "") != panel.authority:
raise UIError("Unexpected Host", 403)
if not panel.allowed(self.client_address[0]):
raise UIError("Доступ разрешён только из домашней сети", 403)
path = urlsplit(self.path).path
if self.command == "GET" and path in ("/", "/app.js", "/style.css", "/favicon.svg"):
name = {"/": "index.html", "/app.js": "app.js", "/style.css": "style.css", "/favicon.svg": "favicon.svg"}[path]
content_type = {"index.html": "text/html; charset=utf-8", "app.js": "text/javascript; charset=utf-8",
"style.css": "text/css; charset=utf-8", "favicon.svg": "image/svg+xml"}[name]
return self.respond(200, (BASE / "ui" / "dist" / name).read_bytes(), content_type)
token, session = panel.session(self.headers.get("Cookie"))
if self.command == "GET" and path == "/api/session":
if panel.local and session is None:
token, session = panel.new_session()
return self.respond(200, {"authenticated": bool(session), "local": panel.local,
"csrf": session["csrf"] if session else None}, cookie=token if session else None)
if self.command == "POST":
if self.headers.get("Origin") != panel.origin:
raise UIError("Invalid request origin", 403)
if self.headers.get("Content-Type", "").split(";")[0] != "application/json":
raise UIError("JSON required", 415)
size = int(self.headers.get("Content-Length", "0"))
if size < 1 or size > MAX_BODY:
raise UIError("Неверный размер запроса", 413)
body = json.loads(self.rfile.read(size))
if not isinstance(body, dict):
raise UIError("JSON object required")
if path == "/api/login" and not panel.local:
token, session = panel.login(body.get("password"), self.client_address[0])
return self.respond(200, {"csrf": session["csrf"]}, cookie=token)
if session is None:
raise UIError("Войдите в панель", 401)
if self.command == "GET":
if path == "/api/state":
return self.respond(200, panel.status())
if path == "/api/ssh-config":
text = h.render_ssh(h.ssh_entries(h.load_config(panel.config)))
return self.respond(200, text.encode(), "text/plain; charset=utf-8")
if path == "/downloads/ssh-config":
text = h.render_ssh(h.ssh_entries(h.load_config(panel.config)))
return self.respond(200, text.encode(), "text/plain; charset=utf-8", filename="homegate.conf")
if path == "/downloads/sync_ssh.py":
return self.respond(200, (BASE / "sync_ssh.py").read_bytes(), "text/plain", filename="sync_ssh.py")
if path == "/downloads/services.yaml":
return self.respond(200, panel.config.read_bytes(), "text/yaml", filename="services.yaml")
if path == "/downloads/root-ca.crt":
pem = panel.status()["controller"].get("root", {}).get("pem")
if not pem:
raise UIError("Корневой сертификат ещё не создан контроллером", 404)
return self.respond(200, pem.encode(), "application/x-pem-file", filename="root-ca.crt")
if self.command == "POST":
if not hmac.compare_digest(self.headers.get("X-Homegate-CSRF", ""), session["csrf"]):
raise UIError("Invalid session token", 403)
if path == "/api/config":
return self.respond(200, panel.save(body["config"], body["revision"]))
if path == "/api/sync":
return self.respond(202, panel.request_sync())
if path == "/api/logout":
panel.sessions.pop(token, None)
return self.respond(200, {"ok": True}, cookie="")
raise UIError("Not found", 404)
def do_GET(self):
try:
self.dispatch()
except UIError as exc:
self.respond(exc.status, {"error": str(exc)})
except (h.Error, ValueError, KeyError, TypeError, yaml.YAMLError) as exc:
self.respond(400, {"error": str(exc)})
except OSError:
self.respond(503, {"error": "Не удалось прочитать или сохранить настройки"})
do_POST = do_GET
def log_message(self, fmt, *args):
LOG.info("UI peer=%s status=%s", self.client_address[0], args[1] if len(args) > 1 else "-")
return Handler
def main():
os.umask(0o077)
logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
p = argparse.ArgumentParser(description=__doc__)
p.add_argument("--host", default=os.environ.get("UI_LISTEN_HOST", "0.0.0.0"))
p.add_argument("--port", type=int, default=int(os.environ.get("UI_LISTEN_PORT", "8081")))
p.add_argument("--local", action="store_true", help="Loopback-only local Sites mode, no login")
args = p.parse_args()
if args.local and args.host != "127.0.0.1":
raise UIError("Local no-login mode must bind to loopback")
if not args.local:
bind_ip = os.environ.get("UI_BIND_IP", "")
h.private_address(bind_ip)
h.require(ipaddress.ip_address(bind_ip).version == 4, "UI_BIND_IP must be a private IPv4 address")
origin = os.environ.get("UI_ORIGIN", f"http://{args.host}:{args.port}")
panel = Panel(os.environ.get("HOMEGATE_CONFIG", "/config/services.yaml"),
os.environ.get("HOMEGATE_CONTROL", "/control"), origin, args.local,
os.environ.get("UI_PASSWORD_FILE", "/run/secrets/ui_password"),
os.environ.get("SSH_PUBLIC_URL", ""))
with ThreadingHTTPServer((args.host, args.port), handler_for(panel)) as server:
print(f"Homegate Local: {origin}", flush=True)
server.serve_forever()
if __name__ == "__main__":
main()

9
requirements.txt Normal file
View File

@@ -0,0 +1,9 @@
cryptography==46.0.7
PyYAML==6.0.3
requests==2.34.2
cffi==2.1.1
pycparser==3.11
certifi==2026.7.22
charset-normalizer==3.5.2
idna==3.20
urllib3==2.8.0

25
run-local.sh Executable file
View File

@@ -0,0 +1,25 @@
#!/bin/sh
# Local-only Sites preview; never starts the controller or connects to homelab APIs.
set -eu
cd "$(dirname "$0")"
umask 077
local_dir=${HOMEGATE_LOCAL_DIR:-"$PWD/.local"}
mkdir -p "$local_dir/config" "$local_dir/control"
if [ ! -f "$local_dir/config/services.yaml" ]; then
cp config/services.yaml "$local_dir/config/services.yaml"
fi
if [ -n "${HOMEGATE_PYTHON:-}" ]; then
panel_python=$HOMEGATE_PYTHON
else
if [ ! -x "$local_dir/venv/bin/python" ]; then
python3 -m venv "$local_dir/venv"
"$local_dir/venv/bin/python" -m pip install -r requirements.txt
fi
panel_python=$local_dir/venv/bin/python
fi
panel_port=${HOMEGATE_LOCAL_PORT:-8787}
export HOMEGATE_CONFIG="$local_dir/config/services.yaml"
export HOMEGATE_CONTROL="$local_dir/control"
export UI_ORIGIN="http://127.0.0.1:$panel_port"
export PYTHONDONTWRITEBYTECODE=1
exec "$panel_python" homegate_ui.py --local --host 127.0.0.1 --port "$panel_port"

47
setup.sh Executable file
View File

@@ -0,0 +1,47 @@
#!/bin/sh
set -eu
cd "$(dirname "$0")"
umask 077
mkdir -p state secrets control
chmod 700 state secrets control
if [ ! -f .env ]; then
sed -e "s/^LOCAL_UID=.*/LOCAL_UID=$(id -u)/" \
-e "s/^LOCAL_GID=.*/LOCAL_GID=$(id -g)/" .env.example > .env
fi
read_secret() {
target=$1
label=$2
minimum=${3:-1}
if [ -s "$target" ]; then return; fi
printf '%s: ' "$label"
previous_tty=$(stty -g)
trap 'stty "$previous_tty"' EXIT HUP INT TERM
stty -echo
IFS= read -r value
stty "$previous_tty"
trap - EXIT HUP INT TERM
printf '\n'
if [ "${#value}" -lt "$minimum" ]; then
printf 'Password must contain at least %s characters. Run setup.sh again.\n' "$minimum" >&2
exit 1
fi
printf '%s' "$value" > "$target"
unset value
}
read_secret secrets/ui_password 'Homegate panel password (at least 12 characters)' 12
read_secret secrets/npm_password 'NPM password'
printf 'Automatic DNS requires Pi-hole 6. Manual DNS works with any version.\n'
printf 'Configure automatic Pi-hole DNS? [Y/n]: '
IFS= read -r automatic
case "$automatic" in
n|N|no|NO)
if [ ! -f secrets/pihole_password ]; then : > secrets/pihole_password; fi
printf 'Set dns_mode: manual in config/services.yaml.\n'
;;
*) read_secret secrets/pihole_password 'Pi-hole password (app password requires app_sudo)' ;;
esac
chmod 600 .env secrets/*
printf '\nEdit .env and config/services.yaml, then run:\n'
printf ' docker compose build\n'
printf ' docker compose run --rm homegate validate\n'
printf ' docker compose up -d\n'

222
sync_ssh.py Normal file
View File

@@ -0,0 +1,222 @@
#!/usr/bin/env python3
"""Download a restricted Homegate SSH config. Requires Python 3.9+, no packages."""
import argparse
import ipaddress
import os
from pathlib import Path
import re
import ssl
import sys
import tempfile
import time
from urllib.parse import urlsplit
from urllib.request import build_opener, ProxyHandler, HTTPSHandler, HTTPRedirectHandler
MAX_BYTES = 512 * 1024
HEADER = "# Homegate SSH config v1"
BEGIN = "# BEGIN HOMEGATE INCLUDE"
END = "# END HOMEGATE INCLUDE"
ALIAS = re.compile(r"[a-z0-9][a-z0-9_.-]{0,252}$")
USER = re.compile(r"[A-Za-z0-9_][A-Za-z0-9_.@-]{0,63}$")
PRIVATE = [ipaddress.ip_network(n) for n in
("10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16", "fc00::/7")]
def check(ok, message):
if not ok:
raise ValueError(message)
def validate_entry(entry):
check(isinstance(entry, dict) and not set(entry) - {"aliases", "host", "port", "user"},
"Unknown SSH field")
aliases = entry.get("aliases")
check(isinstance(aliases, list) and 0 < len(aliases) <= 16, "SSH aliases must contain 1–16 names")
for alias in aliases:
check(isinstance(alias, str) and ALIAS.fullmatch(alias), "SSH aliases must be literal names; no patterns or tokens")
try:
ipaddress.ip_address(alias)
except ValueError:
pass
else:
raise ValueError("Use an SSH alias, not an IP address, in Host")
check(len(set(aliases)) == len(aliases), "Duplicate SSH alias")
check(isinstance(entry.get("host"), str), "SSH HostName must be an IP string")
address = ipaddress.ip_address(entry["host"])
check(address.version != 6 or address.scope_id is None, "Scoped IPv6 and SSH percent tokens are not allowed")
check(any(address.version == net.version and address in net for net in PRIVATE),
"SSH HostName must be an RFC1918 or ULA address")
check(type(entry.get("port")) is int and 1 <= entry["port"] <= 65535, "Invalid SSH port")
if "user" in entry:
check(isinstance(entry["user"], str) and USER.fullmatch(entry["user"]), "Invalid SSH user")
return entry
def render_ssh(entries):
check(isinstance(entries, list) and len(entries) <= 1024, "Too many SSH hosts")
lines = [HEADER, "# Public connection metadata only. Private keys stay on this computer.", ""]
seen = set()
for entry in entries:
validate_entry(entry)
check(not seen.intersection(entry["aliases"]), "SSH aliases must be unique across all hosts")
seen.update(entry["aliases"])
lines += ["Host " + " ".join(entry["aliases"]), " HostName " + entry["host"],
" Port " + str(entry["port"])]
if "user" in entry:
lines.append(" User " + entry["user"])
lines += [" StrictHostKeyChecking ask", ""]
# Do not leave an included file in its final host's conditional scope.
lines += ["Host *", ""]
result = "\n".join(lines)
check(len(result.encode()) <= MAX_BYTES, "SSH config exceeds size limit")
return result
def validate_download(raw):
"""Never pass arbitrary downloaded SSH directives to ssh (Match exec can execute)."""
check(len(raw) <= MAX_BYTES, "SSH config exceeds size limit")
text = raw.decode("ascii").replace("\r\n", "\n")
check(all(c == "\n" or c == "\t" or 32 <= ord(c) < 127 for c in text), "Control characters in SSH config")
check(text.splitlines()[:1] == [HEADER], "Not a Homegate SSH config")
entries, current, fields = [], None, set()
finished = False
def flush():
if current is not None:
check({"hostname", "port", "stricthostkeychecking"}.issubset(fields), "Incomplete SSH host")
validate_entry(current)
entries.append(current)
for line in text.splitlines()[1:]:
line = line.strip()
if not line or line.startswith("#"):
continue
check(not finished, "Directives after final Host * are forbidden")
parts = line.split()
directive, values = parts[0].lower(), parts[1:]
if directive == "host":
flush()
current, fields = None, set()
if values == ["*"]:
finished = True
else:
current = {"aliases": values}
continue
check(current is not None, "Global directives are forbidden")
check(directive in {"hostname", "port", "user", "stricthostkeychecking"},
"Forbidden SSH directive: " + directive)
check(directive not in fields and len(values) == 1, "Duplicate directive or unexpected arguments")
fields.add(directive)
value = values[0]
if directive == "hostname":
current["host"] = value
elif directive == "port":
check(value.isascii() and value.isdecimal(), "Invalid SSH port")
current["port"] = int(value)
elif directive == "user":
current["user"] = value
else:
check(value == "ask", "Host key verification must remain enabled")
check(finished, "Missing final Host *")
# Rebuild from validated values; don't install source text from the network.
return render_ssh(entries)
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
raise ValueError("Redirects are refused; provide the final /ssh-config URL")
def download(url, ca_file=None):
parsed = urlsplit(url)
check(parsed.scheme in ("http", "https") and parsed.hostname and not parsed.username
and not parsed.password and not parsed.fragment, "Use an HTTP(S) URL without credentials")
context = ssl.create_default_context(cafile=ca_file)
# Ignore HTTP(S)_PROXY for LAN fetches. HTTPS verification cannot be disabled.
opener = build_opener(ProxyHandler({}), HTTPSHandler(context=context), NoRedirect())
with opener.open(url, timeout=15) as response:
check(response.status == 200, "Server did not return HTTP 200")
raw = response.read(MAX_BYTES + 1)
return validate_download(raw)
def atomic_write(path, data):
check(not path.is_symlink(), "Refusing to overwrite a symlink: " + str(path))
fd, temporary = tempfile.mkstemp(dir=path.parent, prefix=".homegate-")
try:
with os.fdopen(fd, "wb") as stream:
stream.write(data)
stream.flush()
os.fsync(stream.fileno())
os.chmod(temporary, 0o600)
os.replace(temporary, path)
finally:
if os.path.exists(temporary):
os.unlink(temporary)
def include_update(original, include_path="config.d/homegate.conf"):
text = original.decode("utf-8")
expected = BEGIN + '\nHost *\n Include "' + include_path + '"\n' + END
check((BEGIN in text) == (END in text), "Incomplete Homegate Include block; repair it manually")
if BEGIN in text:
check(text.count(BEGIN) == 1 and text.count(END) == 1, "Duplicate Homegate Include block")
check(expected in text.replace("\r\n", "\n"), "Homegate Include block was edited; inspect it manually")
return original
suffix = ("\n" if original and not original.endswith(b"\n") else "")
suffix += "\n" + expected + "\n"
return original + suffix.encode()
def install_config(text, ssh_dir, add_include=False):
# Validate before creating directories or changing any existing files.
text = validate_download(text.encode())
check(not ssh_dir.is_symlink(), "SSH directory is a symlink; use its real path with --ssh-dir")
target_dir = ssh_dir / "config.d"
target = target_dir / "homegate.conf"
main = ssh_dir / "config"
check(not target_dir.is_symlink() and not target.is_symlink(), "Generated config path must not be a symlink")
original, updated = b"", b""
if add_include:
check(not main.is_symlink(), "Main config is a symlink; add Include manually")
original = main.read_bytes() if main.exists() else b""
include_path = target.resolve().as_posix()
check(not any(c in include_path for c in '\r\n\x00"$%*?[]'), "SSH directory contains unsupported Include path characters")
updated = include_update(original, include_path)
ssh_dir.mkdir(parents=True, exist_ok=True, mode=0o700)
target_dir.mkdir(exist_ok=True, mode=0o700)
os.chmod(ssh_dir, 0o700)
os.chmod(target_dir, 0o700)
if not target.exists() or target.read_bytes() != text.encode():
atomic_write(target, text.encode())
else:
os.chmod(target, 0o600)
if add_include and updated != original:
if main.exists():
atomic_write(ssh_dir / ("config.before-homegate-" + str(time.time_ns())), original)
atomic_write(main, updated)
return target
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("url", help="e.g. http://192.168.0.10:8099/ssh-config")
parser.add_argument("--install", action="store_true", help="Also append one Include block; back up existing config")
parser.add_argument("--ssh-dir", type=Path, default=Path.home() / ".ssh")
parser.add_argument("--ca-file", help="Trusted PEM CA file for HTTPS")
args = parser.parse_args()
text = download(args.url, args.ca_file)
target = install_config(text, args.ssh_dir.expanduser(), args.install)
print("Updated:", target)
if args.install:
print("Include installed. Existing settings take precedence; check an alias with: ssh -G ALIAS")
else:
print("To add the Include on first use, run again with --install.")
if __name__ == "__main__":
try:
main()
except Exception as exc:
print("Homegate SSH sync failed:", exc, file=sys.stderr)
sys.exit(1)

112
tests/test_distribution.py Normal file
View File

@@ -0,0 +1,112 @@
"""First-install/update safety and release destination validation."""
import os
from pathlib import Path
import tempfile
import unittest
import yaml
import homegate as h
from bootstrap import initialize
from ci.image_metadata import metadata
BASE = Path(__file__).resolve().parents[1]
class BootstrapTests(unittest.TestCase):
def setUp(self):
temp = tempfile.TemporaryDirectory()
self.addCleanup(temp.cleanup)
self.root = Path(temp.name)
self.seed = self.root / 'seed.yaml'
value = yaml.safe_load((BASE / 'config/services.yaml').read_bytes())
value['services'] = []
self.seed.write_text(yaml.safe_dump(value))
self.config = self.root / 'config/services.yaml'
self.state = self.root / 'state'
self.control = self.root / 'control'
def run_init(self):
return initialize(self.seed, self.config, self.state, self.control, os.getuid(), os.getgid())
def test_empty_volume_creates_valid_config_with_private_permissions(self):
self.assertTrue(self.run_init())
self.assertEqual(h.load_config(self.config)['services'], [])
self.assertEqual(self.config.stat().st_mode & 0o777, 0o600)
for directory in (self.config.parent, self.state, self.control):
self.assertEqual(directory.stat().st_mode & 0o777, 0o700)
self.assertFalse((self.state / 'ca.json').exists())
def test_upgrade_preserves_edits_and_ca_even_with_changed_seed(self):
self.run_init()
config = yaml.safe_load(self.config.read_bytes())
config['services'] = [{'hostname': 'notes.home', 'display_name': 'Мои заметки',
'upstream': 'http://192.168.0.150:3000'}]
self.config.write_text(yaml.safe_dump(config, allow_unicode=True))
ca = h.Authority(self.state, config['domain_zones'])
before = self.config.read_bytes()
ca_before = (self.state / 'ca.json').read_bytes()
self.seed.write_text('invalid: new seed must not overwrite config')
self.assertFalse(self.run_init())
self.assertEqual(self.config.read_bytes(), before)
self.assertEqual((self.state / 'ca.json').read_bytes(), ca_before)
self.assertEqual(ca.cert.subject, h.Authority(self.state, config['domain_zones']).cert.subject)
def test_invalid_first_seed_does_not_install_configuration(self):
self.seed.write_text('proxy_ip: 8.8.8.8')
with self.assertRaises((h.Error, KeyError)):
self.run_init()
self.assertFalse(self.config.exists())
def test_invalid_existing_file_is_not_replaced(self):
self.run_init()
self.config.write_text('do not erase this file')
with self.assertRaises(h.Error):
self.run_init()
self.assertEqual(self.config.read_text(), 'do not erase this file')
def test_symlink_config_and_volume_are_refused(self):
self.config.parent.mkdir()
self.config.symlink_to(self.seed)
with self.assertRaises(h.Error):
self.run_init()
self.assertEqual(self.config.resolve(), self.seed.resolve())
self.config.unlink()
self.state.rmdir()
self.state.symlink_to(self.config.parent, target_is_directory=True)
with self.assertRaises(h.Error):
self.run_init()
class ReleaseMetadataTests(unittest.TestCase):
def values(self, **overrides):
fields = {'server_url': 'https://git.example.home:3000', 'repository': 'HomeLab/Homegate',
'ref': 'refs/tags/v0.4.0', 'revision': 'a' * 40, 'version_file': '0.4.0\n'}
fields.update(overrides)
return metadata(**fields)
def test_registry_and_owner_come_from_gitea_repository(self):
value = self.values()
self.assertEqual(value['registry'], 'git.example.home:3000')
self.assertEqual(value['image'], 'git.example.home:3000/homelab/homegate')
self.assertEqual(value['version'], '0.4.0')
def test_registry_override_and_prerelease(self):
value = self.values(registry_override='registry.example.home', ref='refs/tags/v0.4.0-rc.1',
version_file='0.4.0-rc.1')
self.assertEqual(value['image'], 'registry.example.home/homelab/homegate')
self.assertEqual(value['source'], 'https://git.example.home:3000/homelab/homegate')
def test_wrong_tag_commit_or_destination_is_rejected(self):
for change in ({'ref': 'refs/heads/main'}, {'ref': 'refs/tags/v0.5.0'},
{'ref': 'refs/tags/v0.4.0;bad'}, {'revision': 'bad\nvalue'},
{'repository': 'owner/repo\nnew-output=x'}, {'repository': '../repo'},
{'registry_override': 'https://registry.example.home'},
{'registry_override': 'gitea'},
{'registry_override': 'registry.example.home:99999'},
{'registry_override': 'registry.example.home/path'}):
with self.subTest(change=change), self.assertRaises(ValueError):
self.values(**change)
if __name__ == '__main__':
unittest.main()

295
tests/test_homegate.py Normal file
View File

@@ -0,0 +1,295 @@
"""Behavior tests using real X.509/TLS and a simulated NPM/Pi-hole HTTP transport."""
import copy
from datetime import timedelta
from email.parser import BytesParser
from email.policy import default
import json
from pathlib import Path
import ssl
import tempfile
import unittest
from unittest.mock import patch
from urllib.parse import unquote, urlsplit
import requests
import yaml
from cryptography import x509
import homegate as h
BASE = Path(__file__).resolve().parents[1]
class Transport:
def __init__(self):
self.hosts = []
self.certs = []
self.records = ["192.168.0.9 unrelated.home"]
self.cnames = []
self.writes = []
self.fail_upload = False
self.fail_nginx = False
self.fail_dns = False
self.uploads = {}
def send(self, session, request, **kwargs):
path = unquote(urlsplit(request.url).path.removeprefix("/api"))
method = request.method
data = json.loads(request.body) if request.body and "application/json" in request.headers.get("Content-Type", "") else None
body, status = None, 200
if method != "GET":
self.writes.append((method, path))
if path == "/tokens":
body = {"token": "TEST_TOKEN"}
elif path == "/auth":
if method == "POST":
body = {"session": {"valid": True, "sid": "TEST_SID", "csrf": "TEST_CSRF"}}
else:
status = 204
elif path.startswith("/nginx/"):
assert request.headers["Authorization"] == "Bearer TEST_TOKEN"
if path == "/nginx/proxy-hosts":
if method == "GET":
body = self.hosts
else:
assert self.uploads[data["certificate_id"]]
body = dict(data, id=len(self.hosts) + 1, meta={"nginx_online": not self.fail_nginx})
self.hosts.append(body)
elif path.startswith("/nginx/proxy-hosts/"):
index = int(path.split("/")[-1]) - 1
body = dict(data, id=index + 1, meta={"nginx_online": not self.fail_nginx})
self.hosts[index] = body
elif path == "/nginx/certificates":
if method == "GET":
body = self.certs
else:
body = dict(data, id=len(self.certs) + 1, meta={})
self.certs.append(body)
elif path.endswith("/upload"):
cert_id = int(path.split("/")[-2])
if self.fail_upload:
status = 500
else:
raw = ("Content-Type: " + request.headers["Content-Type"] + "\r\n\r\n").encode() + request.body
message = BytesParser(policy=default).parsebytes(raw)
fields = {p.get_param("name", header="content-disposition"): p.get_payload(decode=True)
for p in message.iter_parts()}
assert set(fields) == {"certificate", "certificate_key"}
x509.load_pem_x509_certificate(fields["certificate"])
self.uploads[cert_id] = fields
self.certs[cert_id - 1]["meta"] = {"certificate": True, "certificate_key": True}
body = {"certificate_key": "SECRET_NOT_TO_LOG"}
else:
raise AssertionError(path)
elif path == "/config/dns":
assert request.headers["X-FTL-SID"] == "TEST_SID"
if self.fail_dns:
status = 503
else:
body = {"config": {"dns": {"hosts": self.records, "cnameRecords": self.cnames}}}
elif path.startswith("/config/dns/hosts/"):
assert method == "PUT"
assert request.headers["X-FTL-SID"] == "TEST_SID"
entry = path.removeprefix("/config/dns/hosts/")
assert entry not in self.records
assert self.hosts[0]["meta"]["nginx_online"]
self.records.append(entry)
status = 201
else:
raise AssertionError((method, path))
response = requests.Response()
response.status_code = status
response._content = json.dumps(body).encode() if body is not None else b""
return response
class HomegateTests(unittest.TestCase):
def setUp(self):
self.tmp = tempfile.TemporaryDirectory()
self.addCleanup(self.tmp.cleanup)
self.state = Path(self.tmp.name)
self.ca = h.Authority(self.state)
self.config = h.load_config(BASE / "config/services.yaml")
self.registry = {"instance": "test-instance", "routes": {}}
self.transport = Transport()
transport = self.transport
self.patch = patch.object(requests.Session, "send", lambda session, request, **kw: transport.send(session, request, **kw))
self.patch.start()
self.addCleanup(self.patch.stop)
self.npm = h.NPM("http://npm:81", "NPM")
self.npm.login("test@example.com", "password")
self.dns = h.PiHole("http://pihole", "PIHOLE")
self.dns.login("password")
self.addCleanup(self.npm.close)
self.addCleanup(self.dns.close)
self.transport.writes.clear()
def sync(self):
h.reconcile(self.config, self.state, self.ca, self.registry, self.npm, self.dns)
def test_first_sync_and_idempotent_second_sync(self):
self.sync()
self.assertIn("192.168.0.10 pve.home", self.transport.records)
self.assertIn("192.168.0.9 unrelated.home", self.transport.records)
host = self.transport.hosts[0]
self.assertTrue(host["ssl_forced"])
self.assertTrue(host["allow_websocket_upgrade"])
self.assertIn("allow 192.168.0.0/24;\ndeny all;", host["advanced_config"])
self.assertIn("proxy_ssl_verify off;", host["advanced_config"])
self.transport.writes.clear()
self.sync()
self.assertEqual([], self.transport.writes)
def test_renewal_uploads_and_reloads_existing_host(self):
self.sync()
old = self.transport.uploads[1]["certificate"]
future = h.now() + timedelta(days=61)
self.transport.writes.clear()
with patch.object(h, "now", return_value=future):
self.sync()
self.assertNotEqual(old, self.transport.uploads[1]["certificate"])
self.assertEqual([("POST", "/nginx/certificates/1/upload"), ("PUT", "/nginx/proxy-hosts/1")], self.transport.writes)
self.assertEqual(1, len(self.transport.certs))
def test_failed_upload_retries_without_duplicate_certificate(self):
self.transport.fail_upload = True
with self.assertRaises(h.Error):
self.sync()
self.assertEqual({}, self.registry["routes"])
self.assertEqual([], self.transport.hosts)
self.transport.fail_upload = False
self.sync()
self.assertEqual(1, len(self.transport.certs))
def test_failed_reload_is_retried_and_does_not_publish_dns(self):
self.transport.fail_nginx = True
with self.assertRaises(h.Error):
self.sync()
self.assertNotIn("192.168.0.10 pve.home", self.transport.records)
self.assertEqual({}, self.registry["routes"])
self.transport.fail_nginx = False
self.sync()
self.assertIn("192.168.0.10 pve.home", self.transport.records)
def test_unmanaged_proxy_is_not_overwritten(self):
self.transport.hosts.append({"id": 1, "domain_names": ["pve.home"], "advanced_config": "# existing"})
with self.assertRaises(h.Error):
self.sync()
self.assertEqual([], self.transport.writes)
def test_conflicting_dns_is_not_overwritten(self):
self.transport.records.append("192.168.0.137 pve.home alias.home")
with self.assertRaises(h.Error):
self.sync()
self.assertEqual([], self.transport.writes)
def test_cname_conflict_is_not_overwritten(self):
self.transport.cnames.append("pve.home,other.home")
with self.assertRaises(h.Error):
self.sync()
self.assertEqual([], self.transport.writes)
def test_dns_outage_does_not_stop_certificate_renewal(self):
self.sync()
self.transport.fail_dns = True
future = h.now() + timedelta(days=61)
with patch.object(h, "now", return_value=future), self.assertRaises(h.Error):
self.sync()
self.assertEqual(1, len(self.transport.certs))
self.assertIn(("PUT", "/nginx/proxy-hosts/1"), self.transport.writes)
def test_removed_service_is_not_deleted(self):
self.sync()
self.config["services"] = []
self.transport.writes.clear()
self.sync()
self.assertEqual([], self.transport.writes)
self.assertEqual(1, len(self.transport.hosts))
def test_disabled_service_disables_proxy(self):
self.sync()
self.config["services"][0]["enabled"] = False
self.sync()
self.assertFalse(self.transport.hosts[0]["enabled"])
def test_invalid_input_cannot_inject_nginx_or_expand_access(self):
base = yaml.safe_load((BASE / "config/services.yaml").read_text())
for field, value in [("hostname", "pve.home;return 200;"), ("upstream", "http://8.8.8.8:80"),
("upstream", "https://192.168.0.137:8006/path"), ("websocket", "false"),
("upstream_ca_file", "/tmp/ca;return 200;"), ("upstream_tls_name", "pve;#")]:
c = copy.deepcopy(base)
c["services"][0][field] = value
p = self.state / "invalid.yaml"
p.write_text(yaml.safe_dump(c))
with self.subTest(field=field, value=value), self.assertRaises((h.Error, ValueError)):
h.load_config(p)
base["allowed_networks"] = ["0.0.0.0/0"]
p.write_text(yaml.safe_dump(base))
with self.assertRaises(h.Error):
h.load_config(p)
def test_ca_survives_restart_and_private_files_are_restricted(self):
original = (self.state / "root-ca.crt").read_bytes()
h.Authority(self.state)
self.assertEqual(original, (self.state / "root-ca.crt").read_bytes())
self.assertEqual(0o600, (self.state / "ca.json").stat().st_mode & 0o777)
with self.assertRaises(h.Error):
self.ca.leaf("example.com")
def test_missing_ca_does_not_silently_replace_trust(self):
(self.state / "registry.json").write_text("{}")
(self.state / "ca.json").unlink()
with self.assertRaises(h.Error):
h.Authority(self.state)
def tls_handshake(self, hostname, trust=True):
bundle = self.ca.leaf("pve.home")
certpath, keypath = self.state / "tls.pem", self.state / "tls.key"
certpath.write_text(bundle["cert"])
keypath.write_text(bundle["key"])
server_ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
server_ctx.load_cert_chain(certpath, keypath)
client_ctx = ssl.create_default_context(cafile=str(self.state / "root-ca.crt") if trust else None)
ci, co, si, so = ssl.MemoryBIO(), ssl.MemoryBIO(), ssl.MemoryBIO(), ssl.MemoryBIO()
client = client_ctx.wrap_bio(ci, co, server_hostname=hostname)
server = server_ctx.wrap_bio(si, so, server_side=True)
finished = set()
for _ in range(20):
for name, obj in (("client", client), ("server", server)):
try:
obj.do_handshake()
finished.add(name)
except ssl.SSLWantReadError:
pass
if co.pending:
si.write(co.read())
if so.pending:
ci.write(so.read())
if len(finished) == 2:
return client.getpeercert()
self.fail("TLS handshake did not complete")
def test_real_tls_accepts_correct_hostname_and_trusted_ca(self):
cert = self.tls_handshake("pve.home")
self.assertIn(("DNS", "pve.home"), cert["subjectAltName"])
def test_real_tls_rejects_wrong_hostname(self):
with self.assertRaises(ssl.SSLCertVerificationError):
self.tls_handshake("wrong.home")
def test_real_tls_rejects_untrusted_ca(self):
with self.assertRaises(ssl.SSLCertVerificationError):
self.tls_handshake("pve.home", trust=False)
def test_upstream_verification_is_default_for_other_https_services(self):
c = yaml.safe_load((BASE / "config/services.yaml").read_text())
c["services"] = [{"hostname": "nas.home.arpa", "upstream": "https://192.168.0.130"}]
p = self.state / "config.yaml"
p.write_text(yaml.safe_dump(c))
config = h.load_config(p)
result = h.payload(config, config["services"][0], 1, "# test")
self.assertIn("proxy_ssl_verify on;", result["advanced_config"])
if __name__ == "__main__":
unittest.main()

258
tests/test_ssh_and_zones.py Normal file
View File

@@ -0,0 +1,258 @@
import io
from pathlib import Path
import shutil
import ssl
import subprocess
import tempfile
import unittest
from unittest.mock import patch
from cryptography import x509
import yaml
import homegate as h
import sync_ssh as s
BASE = Path(__file__).resolve().parents[1]
class MemorySocket:
"""Feed an actual BaseHTTPRequestHandler without binding a network port."""
def __init__(self, data):
self.input = io.BytesIO(data)
self.output = b""
def makefile(self, *args):
return self.input
def sendall(self, data):
self.output += data
def settimeout(self, value):
pass
class SSHAndZonesTests(unittest.TestCase):
def setUp(self):
self.temp = tempfile.TemporaryDirectory(prefix="homegate test ")
self.addCleanup(self.temp.cleanup)
self.root = Path(self.temp.name)
self.path = self.root / "services.yaml"
self.raw = yaml.safe_load((BASE / "config/services.yaml").read_text())
self.write()
def write(self):
self.path.write_text(yaml.safe_dump(self.raw))
def config(self):
return h.load_config(self.path)
def rendered(self):
return s.render_ssh(h.ssh_entries(self.config()))
def test_service_ssh_uses_vm_address_and_fqdn_alias(self):
rendered = self.rendered()
self.assertIn("Host pve pve.home\n HostName 192.168.0.137\n Port 22\n User root", rendered)
self.assertNotIn("192.168.0.10", rendered)
self.assertEqual(rendered, s.validate_download(rendered.encode()))
def test_separate_ssh_hosts_and_custom_ports(self):
self.raw["ssh_hosts"] = [{"aliases": ["backup", "backup.lab.internal"], "host": "192.168.0.150",
"port": 2222, "user": "admin"}]
self.write()
self.assertIn("Host backup backup.lab.internal\n HostName 192.168.0.150\n Port 2222", self.rendered())
def test_disabled_entries_disappear_and_empty_inventory_is_valid(self):
self.raw["services"][0]["ssh"]["enabled"] = False
self.write()
self.assertNotIn("Host pve", self.rendered())
self.assertEqual(self.rendered(), s.validate_download(self.rendered().encode()))
def test_duplicate_alias_and_malicious_user_are_rejected(self):
self.raw["ssh_hosts"] = [{"aliases": ["pve"], "host": "192.168.0.150", "port": 22}]
self.write()
with self.assertRaises(ValueError):
self.config()
self.raw.pop("ssh_hosts")
self.raw["services"][0]["ssh"]["user"] = "root\nProxyCommand touch /tmp/not-allowed"
self.write()
with self.assertRaises(ValueError):
self.config()
def test_ssh_ipv6_accepts_ula_without_scope_or_tokens(self):
entry = {"aliases": ["ipv6-vm"], "host": "fd12:3456::1", "port": 22}
self.assertIn("HostName fd12:3456::1", s.render_ssh([entry]))
for host in ("fd12:3456::1%h", "fd12:3456::1%eth0\nProxyCommand bad", "fe80::1"):
with self.subTest(host=host), self.assertRaises(ValueError):
s.render_ssh([dict(entry, host=host)])
def test_export_acl_and_no_arbitrary_files(self):
for peer, code in [("192.168.0.20", 200), ("192.168.1.20", 403), ("8.8.8.8", 403),
("::ffff:192.168.0.20", 200), ("127.0.0.1", 403)]:
with self.subTest(peer=peer):
self.assertEqual(code, h.export_response("/ssh-config", peer, self.path)[0])
for path in ("/ca.json", "/root-ca.crt", "/../state/ca.json", "/ssh-config?file=ca.json", "/"):
self.assertEqual(404, h.export_response(path, "192.168.0.20", self.path)[0])
self.assertEqual(200, h.export_response("/healthz", "127.0.0.1", self.path)[0])
def request(self, target="/ssh-config", peer="192.168.0.20", headers=""):
sock = MemorySocket((f"GET {target} HTTP/1.1\r\nHost: test\r\n{headers}\r\n").encode())
h.export_handler(self.path)(sock, (peer, 5000), None)
return sock.output
def test_http_handler_download_and_forwarded_header_cannot_bypass_acl(self):
response = self.request()
self.assertIn(b"200 OK", response)
self.assertEqual(self.rendered(), s.validate_download(response.split(b"\r\n\r\n", 1)[1]))
denied = self.request(peer="8.8.8.8", headers="X-Forwarded-For: 192.168.0.20\r\n")
self.assertIn(b"403 Forbidden", denied)
self.assertNotIn(b"192.168.0.137", denied)
def test_http_export_fails_closed_on_invalid_config(self):
self.path.write_text("invalid: [\n")
self.assertIn(b"503 Service Unavailable", self.request())
def test_dangerous_downloaded_directives_are_rejected(self):
original = self.rendered()
candidates = [original.replace(" Port 22", " ProxyCommand touch /tmp/forbidden\n Port 22"),
original.replace(" Port 22", " Include /tmp/other\n Port 22"),
original.replace(" Port 22", "Match exec echo bad\n Port 22"),
original.replace("Host pve pve.home", "Host *"),
original.replace(" StrictHostKeyChecking ask", " StrictHostKeyChecking no"),
original.replace("192.168.0.137", "8.8.8.8"),
original + " ProxyCommand bad\n",
original.replace(" Port 22", " Port 22\x00"),
"<html>not a config</html>", original * 10000]
for text in candidates:
with self.subTest(text=text[:40]), self.assertRaises(ValueError):
s.validate_download(text.encode())
def test_install_preserves_existing_config_and_is_idempotent(self):
sshdir = self.root / ".ssh"
sshdir.mkdir()
original = b"Host work\n HostName 10.1.2.3\nHost pve\n User operator\n"
(sshdir / "config").write_bytes(original)
target = s.install_config(self.rendered(), sshdir, add_include=True)
installed = (sshdir / "config").read_bytes()
self.assertTrue(installed.startswith(original))
self.assertEqual(1, installed.count(s.BEGIN.encode()))
backups = list(sshdir.glob("config.before-homegate-*"))
self.assertEqual(1, len(backups))
self.assertEqual(original, backups[0].read_bytes())
s.install_config(self.rendered(), sshdir, add_include=True)
self.assertEqual(installed, (sshdir / "config").read_bytes())
self.assertEqual(1, len(list(sshdir.glob("config.before-homegate-*"))))
self.assertEqual(0o600, target.stat().st_mode & 0o777)
if shutil.which("ssh"):
result = subprocess.run(["ssh", "-G", "-F", str(sshdir / "config"), "pve"],
capture_output=True, text=True, check=True)
self.assertIn("hostname 192.168.0.137\n", result.stdout)
self.assertIn("user operator\n", result.stdout)
self.assertIn("port 22\n", result.stdout)
def test_invalid_download_never_replaces_local_files(self):
sshdir = self.root / ".ssh"
target = s.install_config(self.rendered(), sshdir, add_include=True)
previous = target.read_bytes()
with self.assertRaises(ValueError):
s.install_config("Match exec evil\n", sshdir, add_include=True)
self.assertEqual(previous, target.read_bytes())
def test_download_failure_leaves_file_unchanged_and_no_redirects(self):
sshdir = self.root / ".ssh"
target = s.install_config(self.rendered(), sshdir)
previous = target.read_bytes()
with patch.object(s, "build_opener") as build:
build.return_value.open.side_effect = OSError("offline")
with self.assertRaises(OSError):
s.download("http://192.168.0.10:8099/ssh-config")
self.assertEqual(previous, target.read_bytes())
with self.assertRaises(ValueError):
s.NoRedirect().redirect_request(None, None, 302, "", {}, "http://other")
def test_symlink_target_is_not_overwritten(self):
sshdir = self.root / ".ssh"
target = s.install_config(self.rendered(), sshdir)
elsewhere = self.root / "elsewhere"
elsewhere.write_text("preserved")
target.unlink()
target.symlink_to(elsewhere)
with self.assertRaises(ValueError):
s.install_config(self.rendered(), sshdir)
self.assertEqual("preserved", elsewhere.read_text())
def test_multiple_custom_zones_and_label_boundaries(self):
self.raw["domain_zones"] = [".LAB.Internal.", "example.test", "home"]
self.raw["services"][0]["hostname"] = "pve.lab.internal"
self.write()
self.assertEqual(["lab.internal", "example.test", "home"], self.config()["domain_zones"])
self.raw["services"][0]["hostname"] = "evilhome"
self.write()
with self.assertRaises(h.Error):
self.config()
self.raw["services"][0]["hostname"] = "pve.evilhome"
self.write()
with self.assertRaises(h.Error):
self.config()
def test_old_config_without_domain_zones_still_loads(self):
self.raw.pop("domain_zones")
self.write()
self.assertEqual(h.DEFAULT_ZONES, self.config()["domain_zones"])
def test_ca_zone_expansion_requires_explicit_rotation(self):
state = self.root / "state"
state.mkdir()
ca = h.Authority(state)
original = (state / "ca.json").read_bytes()
original_leaf = ca.leaf("pve.home")["cert"]
registry = {"instance": "keep-me", "routes": {"pve.home": {"host_id": 1}}}
h.save_json(state / "registry.json", registry)
ca = h.Authority(state, ["home", "lab.internal"])
with self.assertRaises(h.Error):
ca.leaf("pve.lab.internal")
self.assertEqual(original, (state / "ca.json").read_bytes())
history = h.rotate_ca(state, ["home", "lab.internal"])
self.assertEqual(original, (history / "ca.json").read_bytes())
self.assertEqual(registry, h.read_json(state / "registry.json"))
ca = h.Authority(state, ["home", "lab.internal"])
self.assertNotEqual(original_leaf, ca.leaf("pve.home")["cert"])
ca.leaf("pve.lab.internal")
with self.assertRaises(h.Error):
ca.leaf("pve.home.arpa")
def test_real_tls_with_custom_zone_certificate(self):
state = self.root / "state"
state.mkdir()
ca = h.Authority(state, ["lab.internal", "example.test"])
bundle = ca.leaf("pve.lab.internal")
certpath, keypath = state / "leaf.crt", state / "leaf.key"
certpath.write_text(bundle["cert"])
keypath.write_text(bundle["key"])
cert = x509.load_pem_x509_certificate(bundle["cert"].encode())
self.assertIn("pve.lab.internal", cert.extensions.get_extension_for_class(x509.SubjectAlternativeName).value
.get_values_for_type(x509.DNSName))
serverctx = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
serverctx.load_cert_chain(certpath, keypath)
clientctx = ssl.create_default_context(cafile=str(state / "root-ca.crt"))
ci, co, si, so = ssl.MemoryBIO(), ssl.MemoryBIO(), ssl.MemoryBIO(), ssl.MemoryBIO()
client = clientctx.wrap_bio(ci, co, server_hostname="pve.lab.internal")
server = serverctx.wrap_bio(si, so, server_side=True)
done = set()
for _ in range(20):
for name, obj in (("client", client), ("server", server)):
try:
obj.do_handshake()
done.add(name)
except ssl.SSLWantReadError:
pass
if co.pending:
si.write(co.read())
if so.pending:
ci.write(so.read())
if len(done) == 2:
break
self.assertEqual({"client", "server"}, done)
if __name__ == "__main__":
unittest.main()

182
tests/test_ui.py Normal file
View File

@@ -0,0 +1,182 @@
"""HTTP/session/config integration tests without external APIs or listening ports."""
import copy
import hashlib
import json
from pathlib import Path
import tempfile
import time
import unittest
from unittest.mock import patch
import yaml
import homegate as h
import homegate_ui as ui
from test_ssh_and_zones import MemorySocket
BASE = Path(__file__).resolve().parents[1]
class PanelTests(unittest.TestCase):
def setUp(self):
temp = tempfile.TemporaryDirectory()
self.addCleanup(temp.cleanup)
self.root = Path(temp.name)
self.config = self.root / 'config/services.yaml'
self.config.parent.mkdir()
self.config.write_bytes((BASE / 'config/services.yaml').read_bytes())
self.control = self.root / 'control'
self.password = self.root / 'password'
self.password.write_text('local-test-password')
self.panel = ui.Panel(self.config, self.control, 'http://192.168.0.10:8098',
password_file=self.password)
self.cookie = ''
self.csrf = ''
def request(self, path='/api/state', body=None, peer='192.168.0.20', headers=None):
method = 'GET' if body is None else 'POST'
payload = b'' if body is None else json.dumps(body).encode()
heads = {'Host': self.panel.authority, 'Cookie': self.cookie}
if body is not None:
heads.update({'Origin': self.panel.origin, 'Content-Type': 'application/json',
'Content-Length': str(len(payload)), 'X-Homegate-CSRF': self.csrf})
heads.update(headers or {})
raw = f'{method} {path} HTTP/1.1\r\n' + ''.join(f'{k}: {v}\r\n' for k, v in heads.items()) + '\r\n'
sock = MemorySocket(raw.encode() + payload)
ui.handler_for(self.panel)(sock, (peer, 5000), None)
header, data = sock.output.split(b'\r\n\r\n', 1)
status = int(header.split()[1])
response_headers = dict(line.decode().split(': ', 1) for line in header.split(b'\r\n')[1:])
if 'application/json' in response_headers.get('Content-Type', ''):
data = json.loads(data)
return status, data, response_headers
def login(self):
code, body, headers = self.request('/api/login', {'password': 'local-test-password'})
self.assertEqual(code, 200)
self.cookie = headers['Set-Cookie'].split(';')[0]
self.csrf = body['csrf']
return headers
def test_login_cookie_and_logout(self):
self.assertEqual(self.request()[0], 401)
headers = self.login()
self.assertIn('HttpOnly; SameSite=Strict', headers['Set-Cookie'])
self.assertEqual(self.request()[0], 200)
self.assertEqual(self.request('/api/logout', {})[0], 200)
self.assertEqual(self.request()[0], 401)
def test_wrong_password_rate_limited(self):
for _ in range(5):
self.assertEqual(self.request('/api/login', {'password': 'incorrect'})[0], 401)
self.assertEqual(self.request('/api/login', {'password': 'incorrect'})[0], 429)
def test_origin_csrf_and_host_required(self):
self.login()
for headers in ({'Origin': 'https://attacker.example'}, {'X-Homegate-CSRF': ''}, {'Host': 'attacker.example'}):
with self.subTest(headers=headers):
self.assertEqual(self.request('/api/sync', {}, headers=headers)[0], 403)
self.assertFalse((self.control / 'sync-request.json').exists())
self.assertEqual(self.request('/api/sync', {})[0], 202)
self.assertTrue((self.control / 'sync-request.json').exists())
def test_lan_acl_and_local_mode(self):
for peer in ('8.8.8.8', '192.168.1.5'):
self.assertEqual(self.request('/', peer=peer)[0], 403)
self.assertEqual(self.request('/', peer='::ffff:192.168.0.20')[0], 200)
self.panel = ui.Panel(self.config, self.control, 'http://127.0.0.1:8787', local=True)
self.assertEqual(self.request('/api/session', peer='192.168.0.20')[0], 403)
code, body, _ = self.request('/api/session', peer='127.0.0.1')
self.assertEqual(code, 200)
self.assertTrue(body['authenticated'])
def test_config_write_backups_and_conflicts(self):
self.login()
original = self.config.read_bytes()
_, data, _ = self.request()
new = copy.deepcopy(data['config'])
new['domain_zones'].append('test.internal')
code, saved, _ = self.request('/api/config', {'config': new, 'revision': data['revision']})
self.assertEqual(code, 200)
self.assertNotEqual(saved['revision'], data['revision'])
self.assertIn('test.internal', h.load_config(self.config)['domain_zones'])
backup = list((self.config.parent / 'backups').glob('*.yaml'))
self.assertEqual(len(backup), 1)
self.assertEqual(backup[0].read_bytes(), original)
self.assertEqual(self.request('/api/config', {'config': new, 'revision': data['revision']})[0], 409)
def test_invalid_config_is_not_written(self):
self.login()
before = self.config.read_bytes()
data = self.panel.status()
data['config']['services'][0]['hostname'] = 'outside.example'
code, _, _ = self.request('/api/config', {'config': data['config'], 'revision': data['revision']})
self.assertEqual(code, 400)
self.assertEqual(self.config.read_bytes(), before)
def test_malformed_json_and_missing_fields_return_400(self):
self.login()
for body in ([], None, 'string', {'revision': 'x'}):
if body is not None:
self.assertEqual(self.request('/api/config', body)[0], 400)
def test_downloads_require_login_and_no_private_files(self):
for name in ('services.yaml', 'root-ca.crt', 'ssh-config'):
self.assertEqual(self.request('/downloads/' + name)[0], 401)
self.login()
self.assertEqual(self.request('/downloads/root-ca.crt')[0], 404)
self.assertIn(b'Host pve pve.home', self.request('/downloads/ssh-config')[1])
for path in ('/downloads/../state/ca.json', '/state/ca.json', '/downloads/ui_password'):
self.assertEqual(self.request(path)[0], 404)
def test_secure_cookie_expiry_and_static_csp(self):
self.panel.origin = 'https://panel.home'
self.panel.authority = 'panel.home'
headers = self.login()
self.assertIn('; Secure', headers['Set-Cookie'])
self.assertIn("frame-ancestors 'none'", self.request('/')[2]['Content-Security-Policy'])
with patch.object(ui.time, 'time', return_value=time.time() + 13 * 3600):
self.assertEqual(self.request()[0], 401)
def test_freshness_reflects_controller_heartbeat(self):
h.save_json(self.control / 'status.json', {'time': time.time()-200, 'max_age': 180, 'ok': True})
self.assertFalse(self.panel.status()['controller']['fresh'])
h.save_json(self.control / 'status.json', {'time': time.time(), 'max_age': 180, 'ok': False})
self.assertTrue(self.panel.status()['controller']['fresh'])
self.assertFalse(self.panel.status()['controller']['ok'])
def test_config_validation_does_not_mutate_ui_input(self):
original, _ = self.panel.config_data()
other = copy.deepcopy(original)
h.validate_config(other)
self.assertEqual(other, original)
self.panel.save(other, self.panel.status()['revision'])
self.assertNotIn('forward_host', yaml.safe_load(self.config.read_bytes())['services'][0])
def test_public_status_uses_applied_revision_without_keys(self):
state = self.root / 'state'
state.mkdir()
config = h.load_config(self.config)
ca = h.Authority(state, config['domain_zones'])
ca.leaf('pve.home')
applied = hashlib.sha256(self.config.read_bytes()).hexdigest()
self.config.write_bytes(self.config.read_bytes() + b'\n# Edited while syncing\n')
h.publish_panel_status(self.control, applied, config, state, ca, True, None)
status = h.read_json(self.control / 'status.json')
self.assertEqual(status['applied_revision'], applied)
self.assertNotEqual(status['applied_revision'], self.panel.status()['revision'])
self.assertIn('BEGIN CERTIFICATE', status['root']['pem'])
self.assertEqual(status['certificates'][0]['hostname'], 'pve.home')
self.assertNotIn('PRIVATE KEY', json.dumps(status))
h.publish_panel_status(self.control, 'failed-revision', config, state, ca, False, 'API unavailable')
self.assertEqual(h.read_json(self.control / 'status.json')['applied_revision'], applied)
def test_weak_password_or_invalid_origin_refused(self):
self.password.write_text('short')
with self.assertRaises(ui.UIError):
ui.Panel(self.config, self.control, 'http://panel.home', password_file=self.password)
with self.assertRaises(ui.UIError):
ui.Panel(self.config, self.control, 'http://panel.home/path', local=True)
if __name__ == '__main__':
unittest.main()

104
ui/dist/app.js vendored Normal file
View File

@@ -0,0 +1,104 @@
'use strict';
const $ = (s, root=document) => root.querySelector(s);
const esc = v => String(v ?? '').replace(/[&<>"']/g, c => ({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;'}[c]));
const paths = {
grid:'<rect x="3" y="3" width="7" height="7" rx="1.5"/><rect x="14" y="3" width="7" height="7" rx="1.5"/><rect x="3" y="14" width="7" height="7" rx="1.5"/><rect x="14" y="14" width="7" height="7" rx="1.5"/>',
globe:'<circle cx="12" cy="12" r="9"/><path d="M3 12h18M12 3c5 5 5 13 0 18-5-5-5-13 0-18Z"/>',
terminal:'<rect x="3" y="4" width="18" height="16" rx="3"/><path d="m7 9 3 3-3 3m6 0h4"/>',
shield:'<path d="m12 3 8 3v6c0 4-4 7-8 9-4-2-8-5-8-9V6Z"/><path d="m8 12 3 3 5-6"/>',
sliders:'<path d="M4 7h7m6 0h3M4 17h3m6 0h7"/><circle cx="14" cy="7" r="3"/><circle cx="10" cy="17" r="3"/>',
plus:'<path d="M12 5v14M5 12h14"/>', search:'<circle cx="10.5" cy="10.5" r="6.5"/><path d="m16 16 5 5"/>',
refresh:'<path d="M20 7v5h-5M4 17v-5h5"/><path d="M5.4 8a7 7 0 0 1 11.8-3L20 8M4 16l2.8 3A7 7 0 0 0 18.6 16"/>',
download:'<path d="M12 3v12m-5-5 5 5 5-5M4 15v5h16v-5"/>',
arrow:'<path d="M5 12h14m-5-5 5 5-5 5"/>', external:'<path d="M14 3h7v7M10 14 21 3M10 3H4v17h17v-6"/>',
edit:'<path d="m15 4 5 5M4 20l4-1L21 6l-4-4L4 15Z"/>', trash:'<path d="M3 6h18M9 6V3h6v3M5 6l1 15h12l1-15M10 10v7m4-7v7"/>',
monitor:'<rect x="2" y="3" width="20" height="14" rx="2"/><path d="M8 21h8m-4-4v4"/>',
server:'<rect x="3" y="3" width="18" height="7" rx="2"/><rect x="3" y="14" width="18" height="7" rx="2"/><path d="M7 6.5h.01M7 17.5h.01m4-11h6m-6 11h6"/>',
route:'<circle cx="5" cy="5" r="2"/><circle cx="19" cy="19" r="2"/><path d="M5 7v9a3 3 0 0 0 3 3h9M7 5h9a3 3 0 0 1 3 3v3m-3-3 3 3 3-3"/>',
copy:'<rect x="8" y="8" width="12" height="13" rx="2"/><path d="M15 8V3H3v13h5"/>',
check:'<path d="m5 12 4 4L19 6"/>', info:'<circle cx="12" cy="12" r="9"/><path d="M12 11v6m0-10h.01"/>',
clock:'<circle cx="12" cy="12" r="9"/><path d="M12 7v5l3 2"/>', close:'<path d="m6 6 12 12M6 18 18 6"/>',
key:'<circle cx="8" cy="9" r="5"/><path d="m12 13 8 8m-4-4 3-3m-6 0 3-3"/>', lock:'<rect x="5" y="10" width="14" height="11" rx="2"/><path d="M8 10V7a4 4 0 0 1 8 0v3m-4 5v2"/>',
};
const icon = (name,size=17) => `<svg width="${size}" height="${size}" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">${paths[name]||paths.grid}</svg>`;
let data, csrf='', tab='services', search='', filter='all', busy=false, settingsDirty=false;
const pages = [['services','Сервисы','grid'],['domains','Доменные зоны','globe'],['ssh','SSH-доступ','terminal'],['certificates','Сертификаты','shield'],['settings','Настройки','sliders']];
const clone = v => JSON.parse(JSON.stringify(v));
const date = v => v ? new Date(typeof v==='number'?v*1000:v).toLocaleDateString('ru-RU',{day:'numeric',month:'short',year:'numeric'}) : '—';
const time = v => new Date(v*1000).toLocaleTimeString('ru-RU',{hour:'2-digit',minute:'2-digit'});
const zones = () => data.config.domain_zones || ['home','home.arpa'];
const services = () => data.config.services || [];
const sshEntries = () => [...services().filter(r=>r.enabled!==false&&r.ssh&&r.ssh.enabled!==false).map(r=>({aliases:[...(r.ssh.alias?[r.ssh.alias]:[]),r.hostname].filter((x,i,a)=>a.indexOf(x)===i),host:r.ssh.host||new URL(r.upstream).hostname,port:r.ssh.port||22,user:r.ssh.user})),...(data.config.ssh_hosts||[]).filter(r=>r.enabled!==false)];
const controller = () => data.controller || {};
const isApplied = () => controller().fresh && controller().ok && controller().applied_revision===data.revision;
const sshUrl = () => data.ssh_url || `http://${data.config.proxy_ip}:8099/ssh-config`;
async function api(path, body) {
const options = {credentials:'same-origin',headers:{}};
if(body!==undefined){options.method='POST';options.headers={'Content-Type':'application/json','X-Homegate-CSRF':csrf};options.body=JSON.stringify(body);}
const r=await fetch(path,options);
const value=(r.headers.get('content-type')||'').includes('application/json')?await r.json():await r.text();
if(!r.ok) {if(r.status===401&&path!=='/api/login')showLogin();throw new Error(value.error||`Ошибка ${r.status}`);}
return value;
}
function toast(text,error=false){const region=$('#toast-region');region.innerHTML=`<div class="toast ${error?'error':''}">${icon(error?'info':'check',19)}<span>${esc(text)}</span></div>`;setTimeout(()=>{region.innerHTML='';},6500);}
async function copy(text){try{await navigator.clipboard.writeText(text);toast('Скопировано');}catch{toast('Буфер обмена недоступен. Выделите текст и скопируйте вручную.',true);}}
function friendlyError(e){const s=e.message;return s.includes('display_name')?'Название должно быть в одну строку, не длиннее 100 символов.':s.includes('domain_zones')?'Имя сервиса должно принадлежать одной из ваших доменных зон.':s.includes('Duplicate hostname')?'Сервис с таким доменом уже есть.':s.includes('SSH aliases must be unique')?'SSH-псевдоним уже используется другим сервером.':s.includes('RFC1918')?'Укажите адрес или подсеть вашей локальной сети.':s;}
function heading(title,subtitle,actions=''){return `<div class="heading"><div><div class="eyebrow">ВАШЕ ЛОКАЛЬНОЕ ПРОСТРАНСТВО</div><h1>${title}</h1><p class="subtitle">${subtitle}</p></div><div class="button-row">${actions}</div></div>`;}
function badge(text,kind=''){return `<span class="badge ${kind}"><span class="online-dot"></span>${text}</span>`;}
function nav(){
$('#navigation').innerHTML=pages.map(([id,label,i])=>`<a class="nav-item ${tab===id?'active':''}" href="#${id}" ${tab===id?'aria-current="page"':''}>${icon(i,18)}<span>${label}</span>${id==='services'?`<span class="nav-count">${services().length}</span>`:''}</a>`).join('');
$('#crumb').textContent=pages.find(p=>p[0]===tab)[1];
}
function statusStrip(){const c=controller();if(!c.fresh)return `<div class="status-strip">${icon('info',15)}<span><strong>Контроллер пока не подключён.</strong> Настройки сохраняются здесь. Для применения запустите Homegate в Docker.</span><button class="btn link" data-action="guide">Подключить ${icon('arrow',12)}</button></div>`;
if(!c.ok)return `<div class="status-strip bad">${icon('info',15)}<span><strong>Не удалось применить настройки.</strong> ${esc(c.error||'Проверьте подключение к Pi-hole и NPM.')}</span><button class="btn link" data-action="sync">Повторить</button></div>`;
if(!isApplied())return `<div class="status-strip">${icon('clock',15)}<span><strong>Есть новые настройки.</strong> Контроллер применит их в следующем цикле.</span><button class="btn link" data-action="sync">Применить сейчас</button></div>`;
return `<div class="status-strip good">${icon('check',15)}<span>Конфигурация применена <strong>в ${time(c.time)}</strong>. Доступность самих VM проверяется отдельно.</span><button class="btn link" data-action="sync">Обновить ${icon('refresh',12)}</button></div>`;
}
function serviceName(r){if(r.display_name?.trim())return r.display_name.trim();const n=r.hostname.split('.')[0];return ({pve:'Proxmox',nas:'Хранилище',grafana:'Grafana',git:'Git',config:'Конфигурация',portainer:'Portainer',ha:'Home Assistant'})[n]||n;}
function serviceRows(){
const rows=services().map((r,i)=>({r,i})).filter(({r})=>(`${r.hostname} ${r.upstream} ${serviceName(r)}`.toLowerCase().includes(search.toLowerCase()))&&(filter==='all'||(filter==='enabled'?r.enabled!==false:r.enabled===false)));
if(!rows.length)return `<tr><td colspan="5"><div class="empty">${icon('search',26)}<h3>Сервисы не найдены</h3><p>${services().length?'Измените запрос или фильтр.':'Добавьте первый сервис, чтобы дать ему понятный адрес.'}</p></div></td></tr>`;
return rows.map(({r,i})=>`<tr><td><div class="service-name"><span class="service-icon ${i%3===1?'teal':i%3===2?'blue':''}">${esc(Array.from(serviceName(r))[0].toUpperCase())}</span><div><strong>${esc(serviceName(r))}</strong><small>${r.ssh&&r.ssh.enabled!==false?'SSH-доступ настроен':'Веб-сервис'}</small></div></div></td><td><a href="https://${esc(r.hostname)}" target="_blank" rel="noopener noreferrer" class="domain-link">${icon('lock',12)} ${esc(r.hostname)} ${icon('external',11)}</a></td><td><span class="mono">${esc(r.upstream)}</span></td><td>${r.enabled===false?badge('Выключен','muted'):isApplied()?badge('Настроен','success'):badge('Ожидает применения')}</td><td><div class="row-actions"><button class="switch ${r.enabled!==false?'on':''}" role="switch" aria-checked="${r.enabled!==false}" aria-label="${r.enabled!==false?'Выключить':'Включить'} ${esc(r.hostname)}" data-action="toggle-service" data-index="${i}"></button><button class="icon-button" aria-label="Изменить ${esc(r.hostname)}" data-action="edit-service" data-index="${i}">${icon('edit',14)}</button><button class="icon-button danger" aria-label="Убрать ${esc(r.hostname)}" data-action="remove-service" data-index="${i}">${icon('trash',14)}</button></div></td></tr>`).join('');
}
function renderServices(){const c=controller();const first=services().find(r=>r.enabled!==false);const ssh=sshEntries();return heading('Ваши сервисы','Понятные адреса для всего, что работает дома.',`<button class="btn" data-action="sync">${icon('refresh',14)} Применить</button><button class="btn primary" data-action="add-service">${icon('plus',15)} Добавить сервис</button>`)+statusStrip()+`
<section class="stats" aria-label="Сводка"><div class="stat"><div class="stat-top">Сервисы ${icon('grid')}</div><div class="stat-value">${services().length}<span class="mini-pill">${services().filter(r=>r.enabled!==false).length} включено</span></div><div class="stat-note">в вашей конфигурации</div></div><div class="stat"><div class="stat-top">Доменные зоны ${icon('globe')}</div><div class="stat-value">${zones().length}</div><div class="stat-note">${esc(zones().slice(0,3).map(x=>'.'+x).join(' · '))}</div></div><div class="stat"><div class="stat-top">SSH-подключения ${icon('terminal')}</div><div class="stat-value">${ssh.length}</div><div class="stat-note">один конфиг для всех машин</div></div><div class="stat"><div class="stat-top">Локальный HTTPS ${icon('shield')}</div><div class="stat-value text-value">${c.root?'CA настроен':'Ожидает CA'}</div><div class="stat-note">${c.root?'доверие на ваших устройствах':'создаётся при запуске контроллера'}</div></div></section>
<div class="section-heading"><h2>Каталог сервисов <span class="count-label">${services().length}</span></h2><span class="section-kicker">Прокси <span class="mono">${esc(data.config.proxy_ip)}</span></span></div>
<section class="panel"><div class="toolbar"><label class="search-box">${icon('search',16)}<input id="service-search" placeholder="Найти сервис, домен или IP…" value="${esc(search)}" aria-label="Поиск сервисов"></label><div class="filters" aria-label="Фильтр сервисов">${[['all','Все сервисы'],['enabled','Включены'],['disabled','Выключены']].map(([v,l])=>`<button class="filter ${filter===v?'active':''}" data-action="filter" data-filter="${v}">${l}</button>`).join('')}</div></div><div class="table-scroll"><table><thead><tr><th>Сервис</th><th>Локальный адрес</th><th>Куда направлять</th><th>Состояние</th><th></th></tr></thead><tbody id="service-rows">${serviceRows()}</tbody></table></div><button class="add-row" data-action="add-service">${icon('plus',14)} Подключить ещё один сервис</button><div class="table-end"><span>Изменения сохраняются в services.yaml</span><span>Обновление каждые ${data.config.interval_seconds||60} сек.</span></div></section>
<div class="below-grid"><section class="panel panel-pad"><div class="panel-heading">Как проходит соединение <span class="badge muted">Локальная сеть</span></div><p class="panel-description">${first?`Маршрут для ${esc(first.hostname)}`:'Добавьте сервис, чтобы настроить первый маршрут'}</p><div class="flow"><div class="flow-node"><span class="node-symbol">${icon('monitor',19)}</span><strong>Браузер</strong><small>ваше устройство</small></div><span class="flow-line"></span><div class="flow-node"><span class="node-symbol">${icon('globe',19)}</span><strong>Pi-hole</strong><small>имя → IP</small></div><span class="flow-line"></span><div class="flow-node"><span class="node-symbol">${icon('route',19)}</span><strong>NPM</strong><small>HTTPS · 443</small></div><span class="flow-line"></span><div class="flow-node"><span class="node-symbol">${icon('server',19)}</span><strong>${first?esc(serviceName(first)):'Ваша VM'}</strong><small>${first?esc(new URL(first.upstream).hostname):'IP:порт'}</small></div></div><div class="flow-foot">${icon('shield',12)} Корневой сертификат устанавливается на каждое устройство</div></section><section class="panel panel-pad ssh-card"><div class="panel-heading">Серверы на расстоянии команды ${icon('terminal',20)}</div><p class="panel-description">Подключите общий SSH-конфиг на компьютере.<br>IP и порты больше не нужно держать в памяти.</p><div class="command-small"><span><span class="dollar">$</span>ssh ${esc(ssh[0]?.aliases[0]||'имя-сервера')}</span><button class="icon-button" data-action="copy-ssh-command" aria-label="Скопировать SSH-команду">${icon('copy',13)}</button></div><button class="btn" data-action="go-ssh">Настроить SSH-доступ ${icon('arrow',13)}</button></section></div>`;}
function renderDomains(){const root=controller().root;return heading('Доменные зоны','Свои имена для разных частей вашей домашней сети.',`<button class="btn primary" data-action="add-zone">${icon('plus',15)} Добавить зону</button>`)+`<div class="zones-grid">${zones().map((z,i)=>{const count=services().filter(r=>r.hostname===z||r.hostname.endsWith('.'+z)).length;const covered=root&&root.zones.some(p=>z===p||z.endsWith('.'+p));return `<article class="panel zone-card"><div class="zone-top"><span class="zone-symbol">${icon('globe',21)}</span><button class="icon-button danger" data-action="remove-zone" data-index="${i}" aria-label="Удалить зону ${esc(z)}">${icon('trash',14)}</button></div><div class="zone-name">.${esc(z)}</div><p class="zone-caption">${count} ${count===1?'сервис':'сервисов'} в этой зоне</p><div class="zone-foot">${root?(covered?badge('Разрешена CA','success'):badge('Нужна смена CA')):badge('CA ещё не создан','muted')}<span class="mono">DNS / TLS</span></div></article>`;}).join('')}</div><div class="info-box">${icon('info',19)}<p><strong>Домены работают внутри вашей сети.</strong><br>Pi-hole направляет имена на NPM. Для домашних сетей подходит <span class="mono">home.arpa</span>; можно использовать и собственные зоны.</p></div>${root?`<div class="info-box warning">${icon('shield',19)}<p><strong>Новая зона может потребовать нового корневого сертификата.</strong><br>Если зона вне ограничений текущего CA, выполните миграцию и установите новый корень на устройства. <button class="btn link" data-action="ca-guide">Инструкция ${icon('arrow',12)}</button></p></div>`:''}`;}
function renderSSH(){const entries=sshEntries();return heading('SSH-доступ','Один дополнительный конфиг для всех ваших компьютеров.',`<a class="btn" href="/downloads/sync_ssh.py">${icon('download',14)} Скрипт для ПК</a><a class="btn primary" href="/downloads/ssh-config">${icon('download',14)} Скачать конфиг</a>`)+`<div class="two-col"><section class="code-panel"><div class="code-top"><span>~/.ssh/config.d/homegate.conf</span><button class="icon-button" data-action="copy-ssh-config" aria-label="Скопировать SSH-конфиг">${icon('copy',15)}</button></div><pre id="ssh-preview">Загружаем конфиг…</pre></section><section class="panel panel-pad"><div class="panel-heading">Подключите за пару минут</div><div class="step"><span class="step-number">1</span><div><strong>Скачайте скрипт на компьютер</strong><p>Python 3.9+ и OpenSSH. Приватные ключи остаются у вас.</p><a class="btn small" href="/downloads/sync_ssh.py">${icon('download',12)} sync_ssh.py</a></div></div><div class="step"><span class="step-number">2</span><div><strong>Подключите дополнительный файл</strong><p>Основной SSH-конфиг сохраняется. Для Windows используйте <span class="mono">py -3</span>.</p><div class="command-line"><code>python3 sync_ssh.py ${esc(sshUrl())} --install</code><button class="icon-button" data-action="copy-install" aria-label="Скопировать команду установки">${icon('copy',13)}</button></div></div></div><div class="step"><span class="step-number">3</span><div><strong>Подключайтесь по имени</strong><p>При следующих обновлениях запустите скрипт без <span class="mono">--install</span>.</p><div class="command-line"><code>ssh ${esc(entries[0]?.aliases[0]||'имя-сервера')}</code><button class="icon-button" data-action="copy-ssh-command" aria-label="Скопировать SSH-команду">${icon('copy',13)}</button></div></div></div></section></div><div class="info-box">${icon('lock',18)}<p><strong>Открытая выгрузка только для вашей LAN.</strong><br><span class="mono">${esc(sshUrl())}</span><br>${data.mode==='local'?'Этот адрес заработает после запуска ssh-export в Docker. Сейчас конфиг можно скачать кнопкой выше.':'Доступ ограничен разрешёнными подсетями. Пароль панели для этой выгрузки не нужен.'}</p></div><div class="section-heading"><h2>Серверы без веб-интерфейса <span class="count-label">${(data.config.ssh_hosts||[]).length}</span></h2><button class="btn small" data-action="add-ssh">${icon('plus',13)} Добавить SSH-хост</button></div><section class="panel"><div class="table-scroll"><table><thead><tr><th>Псевдонимы</th><th>Адрес</th><th>Пользователь</th><th></th></tr></thead><tbody>${(data.config.ssh_hosts||[]).map((r,i)=>`<tr><td><strong>${esc(r.aliases.join(', '))}</strong> ${r.enabled===false?badge('Выключен','muted'):''}</td><td class="mono">${esc(r.host)}:${r.port||22}</td><td>${esc(r.user||'Из личного конфига')}</td><td><div class="row-actions"><button class="icon-button" data-action="edit-ssh" data-index="${i}" aria-label="Изменить SSH-хост">${icon('edit',14)}</button><button class="icon-button danger" data-action="remove-ssh" data-index="${i}" aria-label="Удалить SSH-хост">${icon('trash',14)}</button></div></td></tr>`).join('')||`<tr><td colspan="4"><div class="empty">${icon('server',25)}<p>Здесь можно добавить NAS, backup-сервер или любую машину с SSH.<br>SSH веб-сервисов настраивается в карточке сервиса.</p></div></td></tr>`}</tbody></table></div></section>`;}
function renderCertificates(){const root=controller().root;const certs=controller().certificates||[];return heading('Сертификаты','Доверенный HTTPS для локальных адресов.',`<button class="btn" data-action="ca-guide">${icon('refresh',14)} Смена CA</button>${root?`<a class="btn primary" href="/downloads/root-ca.crt">${icon('download',14)} Скачать корневой CA</a>`:''}`)+`<div class="two-col"><section class="panel certificate-card"><div class="certificate-art">${icon('shield',29)}</div><h2>Homegate Local Root CA</h2><p class="panel-description">Ваш центр сертификации внутри домашней сети.</p><div class="key-details"><div class="detail-line"><span>Состояние</span>${root?badge('Создан','success'):badge('Ожидает запуска','muted')}</div><div class="detail-line"><span>Действует до</span><strong>${date(root?.expires)}</strong></div><div class="detail-line"><span>Зоны в сертификате</span><strong>${esc(root?.zones.join(', ')||'Определятся при первом запуске')}</strong></div><div class="detail-line"><span>Срок сертификата сервиса</span><strong>90 дней</strong></div><div class="detail-line"><span>Продление</span><strong>Когда осталось менее 30 дней</strong></div></div>${root?`<span class="note">Отпечаток SHA-256</span><div class="fingerprint">${esc(root.fingerprint)}</div>`:`<div class="info-box">${icon('info',17)}<p>Корень создаётся контроллером. Сейчас панель не видит его данные.</p></div>`}</section><div class="stack"><section class="panel panel-pad"><div class="panel-heading">Установите доверие на устройства</div><p class="panel-description">Сертификат на сервере не добавляет доверие на компьютере или телефоне.</p><div class="step"><span class="step-number">1</span><div><strong>Скачайте только root-ca.crt</strong><p>Сверьте отпечаток с сервером. Приватный ключ CA никогда не публикуется в панели.</p></div></div><div class="step"><span class="step-number">2</span><div><strong>Импортируйте как доверенный корневой CA</strong><p>Windows — доверенные корневые центры.<br>macOS — Связка ключей → System → Always Trust.<br>iOS — включите Full Trust после установки.</p></div></div><div class="step"><span class="step-number">3</span><div><strong>Откройте сервис по доменному имени</strong><p>Например, https://${esc(services()[0]?.hostname||'service.home')}. Проверка сертификата по IP — другой запрос.</p></div></div></section><div class="info-box warning">${icon('shield',17)}<p>Проверка TLS между NPM и самой VM настраивается отдельно для каждого сервиса.</p></div></div></div><div class="section-heading"><h2>Сертификаты сервисов</h2><span class="section-kicker">Данные контроллера</span></div><section class="panel"><table><thead><tr><th>Домен</th><th>Действует до</th></tr></thead><tbody>${certs.map(c=>`<tr><td class="domain-link">${icon('lock',12)} ${esc(c.hostname)}</td><td>${date(c.expires)}</td></tr>`).join('')||'<tr><td colspan="2"><div class="empty"><p>После первого применения здесь появятся выданные сертификаты.</p></div></td></tr>'}</tbody></table></section>`;}
function renderSettings(){const c=data.config;return heading('Настройки сети','Адрес прокси, разрешённые подсети и частота обновления.')+`<div class="settings-grid"><form id="settings-form" class="panel"><section class="form-section"><h2>Ваша локальная сеть</h2><p>Доменные имена сервисов будут указывать на адрес NPM.</p><div class="form-grid"><label class="field">IP Nginx Proxy Manager<input name="proxy_ip" value="${esc(c.proxy_ip)}" required><small>Например, 192.168.0.10</small></label><label class="field">Обновление, секунд<input name="interval_seconds" type="number" min="30" max="3600" value="${c.interval_seconds||60}" required></label><label class="field full">Разрешённые подсети<textarea name="allowed_networks" rows="3" required>${esc(c.allowed_networks.join('\n'))}</textarea><small>По одной подсети в строке. Например, 192.168.0.0/24. Влияет на веб-сервисы и доступ к панели/SSH-выгрузке.</small></label></div></section><section class="form-section"><h2>Локальный DNS</h2><p>Выберите, кто создаёт записи для сервисов.</p><label class="field">Управление записями<select name="dns_mode"><option value="pihole6" ${c.dns_mode!=='manual'?'selected':''}>Автоматически — Pi-hole 6</option><option value="manual" ${c.dns_mode==='manual'?'selected':''}>Вручную — Pi-hole 5 или другой DNS</option></select></label><div id="settings-error" class="form-error" hidden></div></section><div class="form-footer"><button class="btn primary" type="submit">${icon('check',14)} Сохранить настройки</button></div></form><div class="stack"><section class="panel panel-pad"><div class="panel-heading">Подключения</div><p class="panel-description">Пароли остаются в Docker secrets на сервере.</p><div class="integration"><span class="integration-icon">${icon('globe',19)}</span><div><strong>Pi-hole</strong><small>${c.dns_mode==='manual'?'Ручное управление DNS':'DNS-записи через API'}</small></div>${badge(controller().fresh&&controller().ok?'Синхронизирован':'Нет данных',controller().fresh&&controller().ok?'success':'muted')}</div><div class="integration"><span class="integration-icon">${icon('route',19)}</span><div><strong>Nginx Proxy Manager</strong><small>Прокси и HTTPS</small></div>${badge(controller().fresh&&controller().ok?'Синхронизирован':'Нет данных',controller().fresh&&controller().ok?'success':'muted')}</div><p class="note">Адреса API и учётные данные задаются в .env и secrets/ при установке.</p><button class="btn small" data-action="guide" type="button">Как подключить ${icon('arrow',12)}</button></section><section class="panel panel-pad"><div class="panel-heading">Последние изменения</div>${data.history.length?data.history.map(item=>`<div class="history-item">${icon('check',13)}<p>${esc(item.text)}</p><time>${time(item.time)}</time></div>`).join(''):'<p class="panel-description">Здесь появятся сохранения из панели.</p>'}</section><a class="btn" href="/downloads/services.yaml">${icon('download',14)} Скачать текущий YAML</a></div></div>`;}
function render(){if(!data)return;tab=pages.some(p=>p[0]===location.hash.slice(1))?location.hash.slice(1):'services';nav();$('#content').innerHTML=({services:renderServices,domains:renderDomains,ssh:renderSSH,certificates:renderCertificates,settings:renderSettings})[tab]();$('#yaml-download').innerHTML=icon('download',16);$('#logout').hidden=data.mode==='local';$('#service-search')?.addEventListener('input',e=>{search=e.target.value;$('#service-rows').innerHTML=serviceRows();});if(tab==='ssh')api('/api/ssh-config').then(text=>{if($('#ssh-preview'))$('#ssh-preview').textContent=text;}).catch(e=>toast(e.message,true));if(tab==='settings'){const form=$('#settings-form');form.addEventListener('input',()=>settingsDirty=true);form.addEventListener('submit',saveSettings);}}
async function refresh(){data=await api('/api/state');render();}
async function saveConfig(config){if(busy)throw new Error('Подождите завершения сохранения');busy=true;try{data=await api('/api/config',{config,revision:data.revision});settingsDirty=false;render();toast(controller().fresh?'Настройки сохранены. Контроллер применит их в следующем цикле.':'Настройки сохранены локально. Для применения подключите контроллер.');}finally{busy=false;}}
function showModal(title,subtitle,body,footer){$('#modal-content').innerHTML=`<div class="modal-header"><div><h2 id="modal-title">${title}</h2><p>${subtitle}</p></div><button class="icon-button" data-action="close-modal" aria-label="Закрыть">${icon('close',18)}</button></div>${body}${footer||''}`;$('#modal').showModal();}
const modalFooter=(label='Сохранить')=>`<div class="form-footer"><button type="button" class="btn" data-action="close-modal">Отмена</button><button type="submit" form="modal-form" class="btn primary">${icon('check',14)} ${label}</button></div>`;
function serviceModal(index=-1){const r=index<0?{}:services()[index];showModal(index<0?'Новый сервис':'Настройки сервиса','Домен, адрес VM и параметры подключения.',`<form id="modal-form"><div class="modal-body"><div class="form-grid"><label class="field full">Название<input name="display_name" value="${esc(r.display_name||'')}" maxlength="100" placeholder="Например, Proxmox" autocomplete="off"><small>Название в каталоге. Если не указано, определяется по домену.</small></label><label class="field full">Локальный домен<input name="hostname" value="${esc(r.hostname||'')}" placeholder="service.${esc(zones()[0])}" required autocomplete="off"><small>Доступные зоны: ${esc(zones().join(', '))}</small></label><label class="field full">Адрес сервиса на VM<input name="upstream" type="url" value="${esc(r.upstream||'')}" placeholder="https://192.168.0.137:8006" required><small>HTTP или HTTPS, приватный IP и порт. Без пути.</small></label><label class="check-line"><input name="websocket" type="checkbox" ${r.websocket!==false?'checked':''}> WebSocket / веб-консоль</label><label class="check-line"><input name="upstream_tls_verify" type="checkbox" ${r.upstream_tls_verify!==false?'checked':''}> Проверять TLS самой VM</label></div><h3 class="modal-subtitle">SSH-доступ к этой машине</h3><label class="check-line"><input name="ssh_enabled" type="checkbox" ${r.ssh&&r.ssh.enabled!==false?'checked':''}> Добавить в общий SSH-конфиг</label><div class="form-grid ssh-fields"><label class="field">Псевдоним<input name="ssh_alias" value="${esc(r.ssh?.alias||'')}" placeholder="pve"></label><label class="field">Пользователь<input name="ssh_user" value="${esc(r.ssh?.user||'')}" placeholder="root"></label><label class="field">SSH-порт<input name="ssh_port" type="number" min="1" max="65535" value="${r.ssh?.port||22}"></label><label class="field">Другой IP для SSH<input name="ssh_host" value="${esc(r.ssh?.host||'')}" placeholder="IP из адреса сервиса"></label></div><details class="advanced"><summary>Дополнительные параметры</summary><div class="form-grid"><label class="field">Тайм-аут, секунд<input name="timeout_seconds" type="number" min="1" max="86400" value="${r.timeout_seconds||3600}"></label><label class="field">Загрузка файла, МБ<input name="max_body_mb" type="number" min="1" max="102400" value="${r.max_body_mb||1024}"></label><label class="field full">Имя в TLS-сертификате VM<input name="upstream_tls_name" value="${esc(r.upstream_tls_name||'')}" placeholder="pve.internal.example"></label><label class="field full">CA самой VM внутри NPM<input name="upstream_ca_file" value="${esc(r.upstream_ca_file||'')}" placeholder="/data/custom-trust/pve-root-ca.pem"></label></div></details><div class="form-error" id="modal-error" hidden></div></div></form>`,modalFooter(index<0?'Добавить сервис':'Сохранить'));
const form=$('#modal-form');const check=$('[name=ssh_enabled]',form);const fields=$('.ssh-fields',form);fields.hidden=!check.checked;check.addEventListener('change',()=>fields.hidden=!check.checked);
form.addEventListener('submit',async e=>{e.preventDefault();const f=new FormData(form);const item={...clone(r),hostname:f.get('hostname').trim().toLowerCase(),upstream:f.get('upstream').trim(),websocket:f.has('websocket'),upstream_tls_verify:f.has('upstream_tls_verify'),timeout_seconds:Number(f.get('timeout_seconds')),max_body_mb:Number(f.get('max_body_mb'))};if(f.get('display_name').trim())item.display_name=f.get('display_name').trim();else delete item.display_name;for(const k of ['upstream_tls_name','upstream_ca_file']){if(f.get(k).trim())item[k]=f.get(k).trim();else delete item[k];}if(f.has('ssh_enabled')){item.ssh={port:Number(f.get('ssh_port'))};for(const [a,b] of [['alias','ssh_alias'],['user','ssh_user'],['host','ssh_host']])if(f.get(b).trim())item.ssh[a]=f.get(b).trim();}else delete item.ssh;const c=clone(data.config);if(index<0)c.services.push(item);else c.services[index]=item;await modalSave(c);});
}
async function modalSave(config){try{await saveConfig(config);$('#modal').close();}catch(e){const error=$('#modal-error');if(error){error.hidden=false;error.textContent=friendlyError(e);}else toast(friendlyError(e),true);}}
function zoneModal(){showModal('Новая доменная зона','Все сервисы этой зоны будут доступны через локальный DNS.',`<form id="modal-form"><div class="modal-body"><label class="field">Доменная зона<input name="zone" placeholder="lab.internal" required autocomplete="off"><small>Без *. Поддомены сервисов добавляются отдельно.</small></label>${controller().root?'<div class="info-box warning"><p>Для зоны вне ограничений текущего корня потребуется смена CA и установка нового сертификата на устройства.</p></div>':''}<div class="form-error" id="modal-error" hidden></div></div></form>`,modalFooter('Добавить зону'));$('#modal-form').addEventListener('submit',async e=>{e.preventDefault();const z=new FormData(e.target).get('zone').trim().toLowerCase().replace(/^\.+|\.+$/g,'');const c=clone(data.config);c.domain_zones=[...zones(),z];await modalSave(c);});}
function sshModal(index=-1){const r=index<0?{}:data.config.ssh_hosts[index];showModal(index<0?'Новый SSH-хост':'Настройки SSH-хоста','Прямое подключение к машине без создания веб-прокси.',`<form id="modal-form"><div class="modal-body"><div class="form-grid"><label class="field full">Псевдонимы через запятую<input name="aliases" value="${esc(r.aliases?.join(', ')||'')}" placeholder="backup, backup.lab.internal" required></label><label class="field">IP сервера<input name="host" value="${esc(r.host||'')}" placeholder="192.168.0.150" required></label><label class="field">Порт<input name="port" type="number" min="1" max="65535" value="${r.port||22}" required></label><label class="field full">Пользователь<input name="user" value="${esc(r.user||'')}" placeholder="Из личного SSH-конфига"></label><label class="check-line"><input name="enabled" type="checkbox" ${r.enabled!==false?'checked':''}> Включить в выгрузку</label></div><div class="form-error" id="modal-error" hidden></div></div></form>`,modalFooter());$('#modal-form').addEventListener('submit',async e=>{e.preventDefault();const f=new FormData(e.target);const item={aliases:f.get('aliases').split(',').map(x=>x.trim().toLowerCase()).filter(Boolean),host:f.get('host').trim(),port:Number(f.get('port')),enabled:f.has('enabled')};if(f.get('user').trim())item.user=f.get('user').trim();const c=clone(data.config);c.ssh_hosts||=[];if(index<0)c.ssh_hosts.push(item);else c.ssh_hosts[index]=item;await modalSave(c);});}
function confirmModal(title,text,action){showModal(title,'',`<div class="modal-body"><p class="note">${text}</p><div class="form-error" id="modal-error" hidden></div></div>`,`<div class="form-footer"><button class="btn" data-action="close-modal">Отмена</button><button class="btn danger" id="confirm-action">Подтвердить</button></div>`);$('#confirm-action').addEventListener('click',action);}
function guide(ca=false){const command=ca?'docker compose stop homegate\ndocker compose run --rm homegate rotate-ca\n# Установите новый state/root-ca.crt на устройства\ndocker compose up -d homegate':'sh setup.sh\n# Укажите адреса и пароли в .env / secrets\ndocker compose up -d --build';showModal(ca?'Смена корневого сертификата':'Подключите Homegate к вашей сети',ca?'Выполните на Docker-хосте после добавления новых зон.':'Панель готовит конфигурацию. Контроллер применяет её к Pi-hole и NPM.',`<div class="modal-body"><div class="code-panel"><div class="code-top"><span>На вашем сервере</span><button class="icon-button" id="copy-guide" aria-label="Скопировать команды">${icon('copy',15)}</button></div><pre>${esc(command)}</pre></div><p class="note">${ca?'Старый CA будет сохранён в state/ca-history. Новый корень нужно установить на все устройства до перезапуска контроллера. Эта операция не выполняется нажатием кнопки в панели.':'В .env задайте NPM_URL, NPM_IDENTITY, PIHOLE_URL и LAN-адреса панели/SSH. Пароли хранятся отдельно. В настройках панели проверьте IP NPM и разрешённые подсети.'}</p>${!ca?'<div class="info-box"><p>Для HTTPS без предупреждений установите root-ca.crt на клиентские устройства. Панель никогда не подменяет отсутствующие данные статусом «работает».</p></div>':''}</div>`,`<div class="form-footer"><button class="btn primary" data-action="close-modal">Понятно</button></div>`);$('#copy-guide').addEventListener('click',()=>copy(command));}
async function saveSettings(e){e.preventDefault();const f=new FormData(e.target);const c=clone(data.config);c.proxy_ip=f.get('proxy_ip').trim();c.allowed_networks=f.get('allowed_networks').split(/\n|,/).map(x=>x.trim()).filter(Boolean);c.dns_mode=f.get('dns_mode');c.interval_seconds=Number(f.get('interval_seconds'));try{await saveConfig(c);}catch(err){$('#settings-error').hidden=false;$('#settings-error').textContent=friendlyError(err);}}
document.addEventListener('click',async e=>{const button=e.target.closest('[data-action]');if(!button)return;const i=Number(button.dataset.index);const a=button.dataset.action;try{
if(a==='add-service')serviceModal();else if(a==='edit-service')serviceModal(i);else if(a==='add-zone')zoneModal();else if(a==='add-ssh')sshModal();else if(a==='edit-ssh')sshModal(i);else if(a==='close-modal')$('#modal').close();else if(a==='guide')guide();else if(a==='ca-guide')guide(true);else if(a==='go-ssh')location.hash='ssh';
else if(a==='filter'){filter=button.dataset.filter;render();}
else if(a==='sync'){button.disabled=true;const r=await api('/api/sync',{});toast(r.fresh?'Применение запрошено. Дождитесь обновления состояния.':'Запрос сохранён. Контроллер пока не отвечает.');button.disabled=false;}
else if(a==='toggle-service'){const c=clone(data.config);c.services[i].enabled=c.services[i].enabled===false;await saveConfig(c);}
else if(a==='remove-service')confirmModal('Убрать сервис из Homegate?',`<strong>${esc(services()[i].hostname)}</strong> исчезнет из конфигурации и SSH-выгрузки. Уже созданные объекты NPM и DNS останутся — удалите их отдельно в интерфейсах этих сервисов.`,async()=>{const c=clone(data.config);c.services.splice(i,1);await modalSave(c);});
else if(a==='remove-zone')confirmModal('Удалить доменную зону?',`Зона <strong>.${esc(zones()[i])}</strong> будет убрана из списка. Сначала перенесите или удалите использующие её сервисы.`,async()=>{const c=clone(data.config);c.domain_zones=zones().filter((_,j)=>j!==i);await modalSave(c);});
else if(a==='remove-ssh')confirmModal('Удалить SSH-хост?',`Он исчезнет из общего SSH-конфига при следующем обновлении на ПК.`,async()=>{const c=clone(data.config);c.ssh_hosts.splice(i,1);await modalSave(c);});
else if(a==='copy-install')await copy(`python3 sync_ssh.py ${sshUrl()} --install`);else if(a==='copy-ssh-command')await copy(`ssh ${sshEntries()[0]?.aliases[0]||'имя-сервера'}`);else if(a==='copy-ssh-config')await copy(await api('/api/ssh-config'));
}catch(err){button.disabled=false;toast(friendlyError(err),true);}});
function showLogin(){const box=$('#login-screen');box.hidden=false;box.innerHTML=`<form class="login-card" id="login-form"><img src="/favicon.svg" width="45" height="45" alt="Homegate"><h1>Добро пожаловать домой.</h1><p>Войдите в панель управления вашей локальной сетью.</p><label class="field">Пароль панели<input name="password" type="password" autocomplete="current-password" required autofocus></label><div class="form-error" id="login-error" hidden></div><button class="btn primary" type="submit">Войти в Homegate ${icon('arrow',15)}</button></form>`;$('#login-form').addEventListener('submit',async e=>{e.preventDefault();try{const r=await api('/api/login',{password:new FormData(e.target).get('password')});csrf=r.csrf;box.hidden=true;await refresh();}catch(err){$('#login-error').hidden=false;$('#login-error').textContent=err.message;}});}
$('#guide-button').addEventListener('click',()=>guide());$('#menu-button').addEventListener('click',()=>document.body.classList.toggle('menu-open'));$('#sidebar-shade').addEventListener('click',()=>document.body.classList.remove('menu-open'));$('#logout').addEventListener('click',async()=>{await api('/api/logout',{});showLogin();});window.addEventListener('hashchange',()=>{settingsDirty=false;document.body.classList.remove('menu-open');render();});
async function boot(){try{const session=await api('/api/session');if(!session.authenticated)return showLogin();csrf=session.csrf;await refresh();}catch(e){$('#content').innerHTML=`<div class="empty"><h3>Не удалось загрузить панель</h3><p>${esc(e.message)}</p><button class="btn" id="retry-load">Повторить</button></div>`;$('#retry-load').onclick=boot;}}
boot();setInterval(()=>{if(data&&!busy&&!settingsDirty&&!document.body.classList.contains('menu-open')&&!document.activeElement?.matches('input,textarea,select')&&!$('#modal').open&&$('#login-screen').hidden)refresh().catch(()=>{});},15000);

1
ui/dist/favicon.svg vendored Normal file
View File

@@ -0,0 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" width="40" height="40" viewBox="0 0 40 40"><rect width="40" height="40" rx="11" fill="#94e4b7"/><path d="M11 29V18a9 9 0 0 1 18 0v11h-6V18a3 3 0 0 0-6 0v11z" fill="#17352c"/><path d="M17 29v-6h6v6" fill="#eff9f1"/></svg>

After

Width:  |  Height:  |  Size: 261 B

34
ui/dist/index.html vendored Normal file
View File

@@ -0,0 +1,34 @@
<!doctype html>
<html lang="ru">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="theme-color" content="#12252c">
<title>Homegate — домашняя сеть</title>
<meta name="description" content="Управление локальными сервисами, доменными зонами, HTTPS и SSH-доступом.">
<link rel="icon" href="/favicon.svg" type="image/svg+xml">
<link rel="stylesheet" href="/style.css">
<script src="/app.js" defer></script>
</head>
<body>
<div id="app">
<aside class="sidebar" id="sidebar">
<a href="#services" class="brand"><img src="/favicon.svg" alt="" width="36" height="36"><span>homegate<span class="brand-dot">.</span></span></a>
<div class="workspace"><span class="workspace-icon">H</span><div><strong>Мой homelab</strong><span>Личное пространство</span></div><span class="workspace-dots">···</span></div>
<div class="nav-label">УПРАВЛЕНИЕ</div>
<nav id="navigation" aria-label="Разделы"></nav>
<div class="sidebar-guide"><span class="guide-orbit">↗</span><strong>Всё остаётся дома</strong><p>Ваши сервисы и настройки — внутри локальной сети.</p><button class="text-link" id="guide-button">Как это работает <span>→</span></button></div>
<div class="sidebar-bottom"><span class="online-dot"></span><div><strong>Локальная панель</strong><span>Homegate <span class="version">0.4</span></span></div><button id="logout" class="icon-button" aria-label="Выйти" hidden>↪</button></div>
</aside>
<div class="sidebar-shade" id="sidebar-shade"></div>
<div class="workspace-main">
<header class="topbar"><div class="breadcrumb"><button id="menu-button" class="icon-button mobile-only" aria-label="Открыть меню">☰</button><span>Мой homelab</span><span class="crumb-slash">/</span><strong id="crumb">Сервисы</strong></div><div class="topbar-right"><span class="local-chip"><span class="online-dot"></span> Только локально</span><a href="/downloads/services.yaml" class="icon-button" title="Скачать YAML" aria-label="Скачать настройки" id="yaml-download"></a><span class="avatar" aria-label="Локальный пользователь">H</span></div></header>
<main id="content" tabindex="-1"><div class="loading-state"><div class="spinner"></div><p>Загружаем вашу сеть…</p></div></main>
<footer class="page-footer"><span>Создано для вашей домашней сети</span><span>Pi-hole <span class="footer-dot">·</span> Nginx Proxy Manager <span class="footer-dot">·</span> Homegate</span></footer>
</div>
</div>
<div id="login-screen" class="login-screen" hidden></div>
<dialog id="modal" aria-labelledby="modal-title"><div id="modal-content"></div></dialog>
<div id="toast-region" class="toast-region" aria-live="polite" aria-atomic="true"></div>
</body>
</html>

1
ui/dist/style.css vendored Normal file

File diff suppressed because one or more lines are too long