82 lines
5.7 KiB
Markdown
82 lines
5.7 KiB
Markdown
# Кастомные доменные зоны
|
||
|
||
До первого запуска задайте все нужные зоны в `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).
|