Initial Homegate 0.4.0 with web UI, Compose and Gitea Actions
This commit is contained in:
11
.dockerignore
Normal file
11
.dockerignore
Normal 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
19
.env.example
Normal 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
|
||||
105
.gitea/workflows/release.yaml
Normal file
105
.gitea/workflows/release.yaml
Normal 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
10
.gitignore
vendored
Normal file
@@ -0,0 +1,10 @@
|
||||
.env
|
||||
state/
|
||||
secrets/
|
||||
control/
|
||||
config/backups/
|
||||
config/.ui-config.lock
|
||||
__pycache__/
|
||||
*.pyc
|
||||
.venv/
|
||||
.local/
|
||||
81
DOMAINS.md
Normal file
81
DOMAINS.md
Normal 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
13
Dockerfile
Normal 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
341
README.md
Normal 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
246
REGISTRY.md
Normal 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
175
SSH.md
Normal file
@@ -0,0 +1,175 @@
|
||||
# Общий SSH-конфиг в локальной сети
|
||||
|
||||
Добавьте секцию `ssh` к нужному веб-сервису. SSH-адрес по умолчанию берётся из IP
|
||||
его `upstream`; при необходимости задайте другой `ssh.host`:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
- hostname: pve.home
|
||||
upstream: https://192.168.0.137:8006
|
||||
upstream_tls_verify: false
|
||||
ssh:
|
||||
alias: pve
|
||||
user: root
|
||||
port: 22
|
||||
```
|
||||
|
||||
Выгрузка содержит:
|
||||
|
||||
```sshconfig
|
||||
Host pve pve.home
|
||||
HostName 192.168.0.137
|
||||
Port 22
|
||||
User root
|
||||
StrictHostKeyChecking ask
|
||||
```
|
||||
|
||||
`ssh pve` и `ssh pve.home` подключаются **напрямую к VM**, а не к NPM.
|
||||
Без этого Include обычное DNS-разрешение `pve.home` возвращает NPM, предназначенный для HTTPS.
|
||||
Это не SSH-прокси и не SSH-сервер: на целевой машине должен уже работать `sshd`, а ключи
|
||||
авторизации и доступ из LAN на нужный порт настраиваются отдельно.
|
||||
|
||||
Для машин без веб-сервиса есть независимый список. DNS/Proxy Host для них не создаётся:
|
||||
|
||||
```yaml
|
||||
ssh_hosts:
|
||||
- aliases: [backup, backup.lab.internal]
|
||||
host: 192.168.0.150
|
||||
port: 2222
|
||||
user: admin
|
||||
```
|
||||
|
||||
Секция `ssh` необязательна. Если её нет, сервис не включается в выгрузку. `user` тоже
|
||||
необязателен: тогда применяется личный SSH-конфиг/имя пользователя ПК. Для отключения
|
||||
экспорта одного сервиса используйте `ssh.enabled: false`; `enabled: false` у веб-сервиса
|
||||
также исключает его из SSH-конфига. Записи `ssh_hosts` поддерживают собственный `enabled`.
|
||||
Алиасы должны быть уникальными, без wildcard, пробелов и управляющих конструкций.
|
||||
SSH HostName может быть RFC1918 IPv4 или ULA IPv6.
|
||||
|
||||
## Адрес выгрузки
|
||||
|
||||
В `.env` укажите IP **Docker-хоста Homegate**, который может отличаться от IP NPM:
|
||||
|
||||
```dotenv
|
||||
SSH_BIND_IP=192.168.0.10
|
||||
SSH_PORT=8099
|
||||
```
|
||||
|
||||
В `config/services.yaml` задайте свою подсеть:
|
||||
|
||||
```yaml
|
||||
allowed_networks:
|
||||
- 192.168.0.0/24
|
||||
```
|
||||
|
||||
После `docker compose up -d --build` файл доступен по адресу:
|
||||
|
||||
```text
|
||||
http://192.168.0.10:8099/ssh-config
|
||||
```
|
||||
|
||||
Замените `.10` своим адресом. Список генерируется при каждом запросе из текущего YAML,
|
||||
поэтому изменение адреса/порта или удаление SSH-записи отражается сразу и не требует
|
||||
доступных Pi-hole/NPM. При невалидной конфигурации сервер возвращает HTTP 503.
|
||||
Для просмотра без HTTP можно выполнить `docker compose run --rm homegate ssh-config`;
|
||||
эта команда не использует API и не блокирует работающий контроллер.
|
||||
|
||||
Выгрузка открыта без логина **только разрешённым IP**. Она содержит топологию сети и
|
||||
имена пользователей, но не приватные ключи, пароли, CA или SSH host keys.
|
||||
Сервер не раздаёт каталоги и игнорирует `X-Forwarded-For` при проверке клиента.
|
||||
В контейнер `ssh-export` вообще не монтируются ключ CA и пароли управления.
|
||||
|
||||
Docker публикует порт на конкретном адресе хоста; это описано в
|
||||
[документации Docker](https://docs.docker.com/engine/network/port-publishing/).
|
||||
Не пробрасывайте этот порт из WAN и не включайте для него UPnP. Привязка IP и ACL
|
||||
не заменяют firewall, если перед сервером стоит NAT, подменяющий внешний IP разрешённым
|
||||
LAN-адресом. На Docker Desktop источник может выглядеть иначе, чем на Linux;
|
||||
эта конфигурация рассчитана на Linux-хост с сохранением исходного IP клиента.
|
||||
|
||||
## Подключение на ПК
|
||||
|
||||
Скопируйте `sync_ssh.py` из проекта на ПК. Нужны Python 3.9+ и OpenSSH;
|
||||
дополнительные Python-пакеты не требуются. Первый запуск на Linux/macOS:
|
||||
|
||||
```sh
|
||||
python3 sync_ssh.py http://192.168.0.10:8099/ssh-config --install
|
||||
ssh pve
|
||||
```
|
||||
|
||||
На Windows с Python и OpenSSH Client:
|
||||
|
||||
```powershell
|
||||
py -3 sync_ssh.py http://192.168.0.10:8099/ssh-config --install
|
||||
ssh pve
|
||||
```
|
||||
|
||||
Скрипт сохраняет отдельный файл `~/.ssh/config.d/homegate.conf`. Флаг `--install` один раз
|
||||
добавляет в конец основного `~/.ssh/config` блок `Host *` с `Include` на абсолютный путь
|
||||
этого файла. Перед изменением основной файл копируется в `config.before-homegate-*`.
|
||||
Повторный запуск не дублирует Include. На Windows используется `.ssh` в профиле пользователя.
|
||||
Другой каталог можно задать через `--ssh-dir`; OpenSSH сам должен быть настроен читать
|
||||
находящийся там основной конфиг, например через `ssh -F /path/config pve`.
|
||||
|
||||
Существующие настройки имеют приоритет по правилу первого значения OpenSSH.
|
||||
Приватные ключи и `IdentityFile` задавайте в личном конфиге:
|
||||
|
||||
```sshconfig
|
||||
Host pve
|
||||
IdentityFile ~/.ssh/id_ed25519_homelab
|
||||
IdentitiesOnly yes
|
||||
```
|
||||
|
||||
Этот блок разместите **до** Homegate Include. Если прежде был `Host *` с `User` или
|
||||
`Port`, он также имеет приоритет перед загруженными значениями. При необходимости
|
||||
переместите весь блок Homegate Include выше общих настроек, сохранив его маркеры.
|
||||
Проверить результат без подключения: `ssh -G pve`.
|
||||
OpenSSH описывает [порядок применения и Include](https://man.openbsd.org/ssh_config#Include).
|
||||
|
||||
Скрипт не меняет NTFS ACL на Windows: используйте обычный приватный каталог профиля,
|
||||
не общую сетевую папку. Windows-вариант написан на стандартной библиотеке Python,
|
||||
но отдельно на Windows не запускался. Symlink основного конфига автоматически не
|
||||
перезаписывается: в таком случае добавьте Include вручную и запускайте скрипт без `--install`.
|
||||
|
||||
## Обновление
|
||||
|
||||
Для последующих обновлений достаточно той же команды без `--install`:
|
||||
|
||||
```sh
|
||||
python3 sync_ssh.py http://192.168.0.10:8099/ssh-config
|
||||
```
|
||||
|
||||
Обновление атомарное: при ошибке сети или проверок старый файл сохраняется. Удалённые
|
||||
SSH-записи исчезают из дополнительного файла при следующем успешном обновлении.
|
||||
Основной конфиг и `known_hosts` при обновлении не меняются. Файл на ПК обновляется
|
||||
только при запуске скрипта; автоматическое расписание не создаётся.
|
||||
На Linux/macOS файл получает права `0600`, каталог — `0700`.
|
||||
|
||||
Скрипт принимает только `Host`, `HostName`, `Port`, `User` и `StrictHostKeyChecking ask`,
|
||||
проверяет значения и заново собирает текст перед записью. Скачанные `ProxyCommand`,
|
||||
`Match exec`, вложенные `Include`, глобальные wildcard-настройки и выключение проверки
|
||||
SSH host key отклоняются. Первый SSH-вход требует проверки отпечатка ключа
|
||||
сервера обычным способом. Скрипт не выполняет скачанный код, не следует HTTP-редиректам
|
||||
и не использует прокси из переменных окружения.
|
||||
|
||||
## HTTPS для загрузки
|
||||
|
||||
HTTP не защищает список адресов от подмены внутри LAN. Для аутентифицированной загрузки
|
||||
добавьте HTTPS Proxy Host через существующий NPM на exporter, включив в `services`:
|
||||
|
||||
```yaml
|
||||
- hostname: config.home
|
||||
upstream: http://192.168.0.10:8099
|
||||
```
|
||||
|
||||
Тогда на ПК:
|
||||
|
||||
```sh
|
||||
python3 sync_ssh.py https://config.home/ssh-config --ca-file root-ca.crt --install
|
||||
```
|
||||
|
||||
Это опциональный маршрут; домен должен входить в `domain_zones`.
|
||||
NPM применяет LAN ACL к клиенту; exporter должен видеть разрешённый LAN-IP NPM.
|
||||
Если Docker NAT показывает другой адрес, настройте сетевой путь или узкое правило
|
||||
для этого конкретного адреса, не разрешайте весь Docker subnet без необходимости.
|
||||
Проверка HTTPS у скрипта всегда включена. Корневой сертификат берите по доверенному
|
||||
каналу из `state/root-ca.crt`. Ни HTTP-, ни HTTPS-вариант не требует логина для скачивания из LAN.
|
||||
157
WEB.md
Normal file
157
WEB.md
Normal 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
58
bootstrap.py
Normal 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
53
ci/check_compose.py
Normal 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
49
ci/image_metadata.py
Normal 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
56
ci/smoke_image.sh
Executable 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
61
ci/smoke_ui.py
Normal 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
150
compose.registry.yaml
Normal 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
139
compose.yaml
Normal 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
50
config/services.yaml
Normal 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
692
homegate.py
Normal 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
275
homegate_ui.py
Normal 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
9
requirements.txt
Normal 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
25
run-local.sh
Executable 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
47
setup.sh
Executable 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
222
sync_ssh.py
Normal 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
112
tests/test_distribution.py
Normal 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
295
tests/test_homegate.py
Normal 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
258
tests/test_ssh_and_zones.py
Normal 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
182
tests/test_ui.py
Normal 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
104
ui/dist/app.js
vendored
Normal file
@@ -0,0 +1,104 @@
|
||||
'use strict';
|
||||
const $ = (s, root=document) => root.querySelector(s);
|
||||
const esc = v => String(v ?? '').replace(/[&<>"']/g, c => ({'&':'&','<':'<','>':'>','"':'"',"'":'''}[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
1
ui/dist/favicon.svg
vendored
Normal 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
34
ui/dist/index.html
vendored
Normal 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
1
ui/dist/style.css
vendored
Normal file
File diff suppressed because one or more lines are too long
Reference in New Issue
Block a user