plane.toml — все параметры

Полный справочник конфигурации контрол-плейна: каждый параметр, значение по умолчанию, что ломается при ошибке.

Файл /etc/hastreamer-cctv/plane.toml — единственный конфигурационный файл контрол-плейна. Его читает бинарь /usr/local/bin/hastreamer-plane, запускаемый юнитом hastreamer-cctv-plane.service.

В файле хранится только инфраструктура: на каком сокете слушать, по какому адресу Plane доступен снаружи, какая база PostgreSQL используется, чем шифруется его собственный слушатель, где лежат материалы событий, какими ключами подписываются сессии и насколько подробен журнал. Всего 30 параметров.

Три правила, которые действуют на весь файл#

1. Неизвестный ключ верхнего уровня — фатальная ошибка. Модель конфигурации объявлена с deny_unknown_fields, поэтому опечатка (lissten = …) не игнорируется молча, а останавливает запуск. То же строгое поведение действует внутри таблиц [tls], [event_storage_policy], [keys] и [jwks].

2. Файл читается ровно один раз — при старте процесса. Горячей перечитки нет ни у одного параметра. Любая правка вступает в силу только после:

sudo systemctl restart hastreamer-cctv-plane

Единственное частичное исключение — log_level, изменённый через админку: он применяется к живому фильтру журнала сразу и одновременно записывается в файл. Правка log_level руками всё равно требует перезапуска.

3. Валидация громкая. Любое отвергнутое значение прерывает запуск сообщением в stderr (то есть в журнале systemd):

hastreamer-plane: fatal: invalid plane network configuration: <причина>

Юнит объявлен как Restart=on-failure с RestartSec=3s, поэтому ошибочная правка даёт не «частично работающий» Plane, а цикл перезапусков. Причина всегда в строке fatal::

sudo journalctl -u hastreamer-cctv-plane -n 50 --no-pager | grep -i fatal

Как бинарь читает файл#

hastreamer-plane [<путь-к-конфигу>] [--reset-superadmin]

Первый аргумент без дефисов — путь к конфигу; если его не передать, берётся plane.toml в текущем каталоге. Штатный юнит всегда передаёт /etc/hastreamer-cctv/plane.toml явно. Флаг --reset-superadmin выпускает и печатает новый пароль суперадминистратора, записывает это в аудит и завершает процесс — это разовая команда восстановления доступа, а не режим работы.

Что меняется из админки, а что только руками#

Суперадминистратор может переписать часть этого файла из админки: Настройки → параметры Plane (PATCH /api/v1/settings/plane). Разделение жёсткое:

Логика разделения простая: строка подключения к базе и пути к приватным ключам никогда не проходят через API — их нельзя ни прочитать, ни записать снаружи.

Ещё три особенности записи из админки, о которых полезно знать:

• Неприменимые ключи выбрасываются. Таблица формируется заново из типизированной модели, поэтому cert и key остаются только при mode = "pem", hosts — только если список непустой, store_dir — только если задан явно, а три ключа acme_* — только при mode = "acme".
• Файл проверяется дважды — сначала в памяти, затем повторным разбором ровно тех байтов, которые будут записаны. Через админку нельзя оставить незапускаемый конфиг.
• Защита от одновременной правки. Если файл изменился после того, как форма настроек была загружена, сохранение отклоняется с сообщением "/etc/hastreamer-cctv/plane.toml changed after the settings form was loaded" — ваша ручная правка не будет затёрта молча, админка попросит перезагрузить форму. Одновременные сохранения из админки выстраиваются в очередь на внутренней блокировке и через 10 секунд ожидания возвращают 409 settings_busy.

Полный перечень параметров#

Обязательных без значения по умолчанию — ровно два: database_url и public_url. Отсутствие любого из них — ошибка разбора файла, Plane не стартует вообще. Остальные «обязательные» в таблице обязательны условно: только если выбран соответствующий режим хранилища или TLS.

Параметры верхнего уровня#

listen#

TCP-сокет, который Plane открывает для собственного /api/v1, админки, мобильного интерфейса и плеера. Это адрес привязки, а не адрес, который набирают пользователи — последний задаётся в public_url. Процесс работает от root, поэтому привилегированные порты 80 и 443 доступны.

Имя хоста не принимается — только IP-адрес. Иначе запуск прерывается:

invalid plane network configuration: listen must be an IP socket address (hostnames are not bind addresses)

В режиме acme действует дополнительное правило: listen обязан отличаться от [tls] acme_listen — см. acme_listen.

Значение не является секретом. Привязка к 0.0.0.0 открывает админку на всех интерфейсах; если TLS терминирует реверс-прокси на том же хосте, привязывайтесь к 127.0.0.1.

database_url — обязателен, значения по умолчанию нет#

Строка подключения к PostgreSQL. Plane владеет этой схемой: при старте применяет свои миграции, создаёт организацию по умолчанию, суперадминистратора и системные шаблоны, а дальше хранит там все камеры, ноды, пользователей, гранты, события, записи аудита и продуктовые настройки. Подключения помечаются как application_name=hastreamer-plane.

Синтаксис строки при разборе конфигурации не проверяется — она передаётся драйверу как есть. Ошибочный или недоступный адрес фатален при старте и, с учётом Restart=on-failure, даёт цикл перезапусков с интервалом 3 секунды, пока PostgreSQL не станет доступен. Если ключ вообще отсутствует, файл не разбирается:

parsing /etc/hastreamer-cctv/plane.toml: missing field `database_url`

Сколько подключений планировать. Пул ограничен параметром db_pool_max. Дополнительно Plane держит одно отдельное подключение вне пула для своей аренды-одиночки (application_name=hastreamer-plane-singleton) — это рекомендательная блокировка, гарантирующая ровно один процесс Plane на одну базу. Закладывайте db_pool_max + 1 подключений PostgreSQL на каждый Plane. Потеря этой аренды намеренно завершает процесс.

log_level#

Минимальный уровень сообщений, попадающих в stderr (то есть в журнал systemd) и в ограниченное по объёму кольцо оперативного журнала в памяти, которое показывает админка. Кольцо вычищает учётные данные из сообщений.

Это закрытое перечисление, а не выражение RUST_LOG. Значения "trace", "verbose" или "cctv_plane=debug" отвергаются при разборе файла:

parsing /etc/hastreamer-cctv/plane.toml: unknown variant `verbose`, expected one of `debug`, `info`, `warn`, `error`

Пофильтровать журнал по конкретным подсистемам можно только переменной окружения RUST_LOG — см. Переменные окружения. Пока RUST_LOG задана и непуста, она полностью замещает log_level и блокирует соответствующий элемент управления в админке: попытка сохранить уровень журнала вернёт 409 rust_log_override.

Это единственный параметр, изменение которого из админки применяется немедленно, без перезапуска. Уровень debug безопасно включить ненадолго для диагностики (учётные данные вычищаются), но он многословен — не оставляйте его включённым постоянно.

db_pool_max#

Максимальное число подключений PostgreSQL в пуле. Оно ограничивает параллелизм всех API-запросов, транзакций приёма событий и фоновых задач.

Нижняя граница не случайна: короткие транзакции приёма событий должны сосуществовать с трафиком авторизации и чтения, с обслуживанием жизненного цикла и восстановлением, поэтому бюджет приёма резервирует четыре подключения под пути контрол-плейна. Значение меньше 5 прерывает запуск:

invalid plane network configuration: db_pool_max must be at least 5 so short event-ingest transactions leave four database connections available

Реальный потолок сверху задаёт max_connections самого PostgreSQL; не забудьте про +1 подключение аренды-одиночки. Сопутствующие тайм-ауты пула зашиты и параметрами не настраиваются: ожидание подключения — 10 секунд, простой — 2 минуты, предельное время жизни подключения — 30 минут.

Из админки не меняется — только правкой файла.

public_url — обязателен, значения по умолчанию нет#

Канонический внешний адрес Plane — то, по чему до него достучатся браузеры и ноды. Из него собираются ссылки, перенаправления, публичные ссылки на фрагменты и адрес обратного вызова, который сообщается нодам. Он законно может отличаться от listen: реверс-прокси, NAT, проброс портов контейнера, внешний терминатор TLS. Завершающий / нормализуется при старте.

Ошибочное значение прерывает запуск одним из двух сообщений:

invalid plane network configuration: public_url must be an HTTP(S) origin
invalid plane network configuration: public_url must be an HTTP(S) origin without credentials, path, query or fragment

Отсутствие ключа — такая же ошибка разбора, как и у database_url:

parsing /etc/hastreamer-cctv/plane.toml: missing field `public_url`

Перекрёстная проверка с [tls] mode — самая частая причина невзлетевшего Plane:

Дополнительно для режимов self_signed и acme хост из public_url обязан присутствовать в списке tls.hosts, иначе:

invalid plane network configuration: tls.hosts must include the public_url hostname "cctv.example.com"

Сравнение регистронезависимое, скобки IPv6 снимаются перед сравнением.

Ошибка в public_url не ломает собственный слушатель Plane — сервис поднимется и будет отвечать. Ломаются обратные вызовы нод, публичные ссылки и перенаправления в браузере, поэтому симптом выглядит как «всё запустилось, но ничего не работает».

Хранилище материалов событий#

Таблицы [attachment_storage] и [event_storage_policy] настраивают материалы событий, принадлежащие Plane: кадры по детекции движения и ONVIF, загруженные вложения к событиям и маленькие генерируемые превью (<ключ>.preview).

Обе таблицы можно не писать вообще: по умолчанию используется локальный каталог /var/lib/hastreamer-cctv/attachments, стандартные пороги заполнения и отсутствие байтового бюджета.

[attachment_storage] backend#

Это ключ-тег перечисления: если таблица присутствует, backend в ней обязателен. Неизвестное значение — ошибка разбора:

parsing /etc/hastreamer-cctv/plane.toml: unknown variant `obj-store`, expected `local` or `s3`

Смена бэкенда меняет то, куда пишутся новые материалы. Прежде чем менять её на работающей установке, прочитайте Перенос хранилища — это самое неочевидное поведение во всём файле.

[attachment_storage] dir — локальный бэкенд#

Каталог, где физически лежат блобы материалов. Именно он растёт со временем — размещайте его на просторном диске. При первой активации Plane размечает каталог (создаёт в нём файл-маркер принадлежности), а при обычном перезапуске просто открывает его. Благодаря этому непримонтированный диск обнаруживается как ошибка, а не подменяется молча созданным пустым каталогом.

Недопустимый путь прерывает запуск:

invalid plane network configuration: local event storage directory must be a dedicated absolute path below the filesystem root

Содержимое каталога — доказательная база по событиям; установщик создаёт его с правами 0750 root:root.

[attachment_storage] — бэкенд S3#

[attachment_storage]
backend     = "s3"
endpoint    = "s3.example.com"       # без схемы: host[:port]
bucket      = "cctv-evidence"
region      = "us-east-1"
https       = true
access_key  = "ЗАМЕНИТЕ"
secret_key  = "ЗАМЕНИТЕ"
addressing  = "path"                 # или "virtual_host"

Все проверки фатальны при старте и возвращаются кодом 400 при сохранении из админки:

S3 event storage endpoint must be schemeless host[:port]
invalid S3 event storage endpoint
S3 event storage endpoint must be schemeless host[:port] without credentials or path
S3 event storage bucket must be a non-empty bucket name without path separators
S3 event storage region must not be empty
S3 event storage credentials must not be empty
virtual-host S3 addressing requires a DNS hostname endpoint and a DNS-compatible bucket name

Последняя проверка требует одновременно DNS-имени в endpoint (не IP) и совместимого с DNS имени бакета: от 3 до 63 символов, только строчные буквы, цифры, - и ., каждая метка между точками начинается и заканчивается буквой или цифрой, и само имя не является IP-адресом.

У https и addressing отдельных сообщений нет: неверный тип (https = "true" вместо https = true) или неизвестное значение addressing останавливают уже разбор файла — parsing /etc/hastreamer-cctv/plane.toml: <ошибка toml>. Помните также, что опечатка в имени ключа именно в этой таблице не диагностируется вообще, а молча заменяется значением по умолчанию.

invalid plane network configuration: S3 event storage requires an explicit max_bytes budget

Отдельного переключателя проверки сертификатов (tls_verify и подобных) у этого бэкенда нет — единственный транспортный переключатель — https.

S3 access and secret keys must be supplied together
S3 event storage credentials are required when selecting the backend

Перенос хранилища#

Прочитайте этот раздел перед тем, как менять dir или backend на работающей установке.

• Запуск не ломается никогда. Настроенный бэкенд применяется при старте всегда; смена каталога не приводит к циклу перезапусков. Если в прежнем хранилище остались блобы, которых новое не видит, Plane пишет об этом в журнал и поднимает постоянное оповещение — «материалы событий лежат в ПРЕДЫДУЩЕМ каталоге, они не потеряны, верните прежний каталог в plane.toml, чтобы восстановить доступ», — продолжая работать с новым каталогом. В журнале это сообщение вида:

  Копировать

  event-storage evidence in bucket … is in the PREVIOUS directory … It is not lost — revert the directory in plane.toml to recover it
  

  Возврат прежнего значения восстанавливает доступ. Пустое прежнее хранилище не помечается.

• Через админку правило строже, чем при правке файла. Смена каталога или бэкенда из админки отклоняется с 409 event_storage_rotation_blocked, пока хоть в одном незакрытом хранилище ещё лежат физические блобы. Дополнительно выполняется живая проверка нового бэкенда: если он недоступен или недоступен на запись, возвращается 502 с сообщением самого бэкенда.

• Переезжают только материалы событий Plane. Видеоархив нод это не затрагивает.

[event_storage_policy] — политика заполнения#

max_bytes — это учётный потолок для материалов событий, а не квота организации. Для локального бэкенда его можно не задавать: ёмкость берётся из файловой системы. Для S3 он обязателен.

Пороги задаются в процентах от ёмкости, и порядок строгий — равные значения отвергаются, зазор между ними является преднамеренным гистерезисом:

event storage watermarks must satisfy 1 <= low < high < critical <= 99
event storage max_bytes must be at least 64 MiB
event storage max_bytes must fit the PostgreSQL bigint accounting domain
S3 event storage requires an explicit max_bytes budget

Ключи подписи и время жизни сессии#

[keys] session_key_pem#

Ключ, которым подписываются JWT сессий браузера и API. Его открытая половина публикуется по адресу /.well-known/jwks.json, и ноды проверяют билеты сессий по ней автономно — именно поэтому недоступность Plane не прерывает уже идущее видео. Обратная сторона: замена этого ключа обесценивает все выданные сессии и заставляет ноды обновить закешированный JWKS.

Установщик записывает ключ явно в plane-session.pem, поэтому имя по умолчанию signing.pem встречается только в конфигурациях, написанных вручную.

Поведение при старте:

Файл-спутник. Рядом с ключом Plane ведёт эпоху идентификатора ключа: тот же путь с расширением, заменённым на .kid (/etc/hastreamer-cctv/plane-session.kid). В нём целое число (1 при первом запуске), а публикуемый идентификатор имеет вид k<эпоха>. Копируйте его вместе с ключом.

Ротация — это действие API, а не параметр конфигурации. Запрос POST /api/v1/admin/keys/rotate (суперадминистратор) либо увеличивает эпоху — старый идентификатор исчезает из публикуемого JWKS, и выданные ранее токены перестают проходить выбор ключа, — либо, в форме восстановления после компрометации, заменяет сам ключевой материал (новая пара ключей с правами 0600 плюс увеличение эпохи). Ключи управления нодами при этом не затрагиваются.

Через API этот параметр не редактируется: приватный ключевой материал не ездит по настройкам. Файл обязан быть 0600 root:root — тот, кто может его прочитать, может выпустить действительную сессию от имени любого пользователя.

[keys] tunnel_control_key_pem#

Отдельная личность ES256 для управления ретрансляторами и агентами со стороны Plane. Она намеренно независима от сессий браузера: ротация ключа сессий не должна отрезать ретрансляторы, изолированные по входящему трафику. Файл создаётся автоматически с правами 0600 при первом запуске — это одна из причин, по которым сервис работает от root в своём каталоге конфигурации.

Правила старта те же, что и у ключа сессий: нет файла — сгенерируется, повреждён — запуск прерывается, права шире 0600 — запуск прерывается.

some tunnel configs cannot be reproduced with the current provisioning root; affected instances remain isolated

[jwks] session_ttl_secs#

Срок жизни выданного JWT сессии — фактически то, сколько времени вход остаётся действительным до повторной аутентификации.

Индивидуального отзыва сессий на сервере нет: список выданных токенов не хранится. Если нужно сократить окно для украденного токена, есть два рычага — уменьшить это значение либо провести ротацию ключа сессий (POST /api/v1/admin/keys/rotate). Из админки параметр не меняется.

TLS собственного слушателя Plane#

[tls] mode — пять режимов доступа#

Неизвестное значение — ошибка разбора файла. Несовпадение схемы public_url разобрано в public_url.

[tls] cert и [tls] key — режим pem#

[tls]
mode = "pem"
cert = "/etc/hastreamer-cctv/plane-cert.pem"
key  = "/etc/hastreamer-cctv/plane-key.pem"

Plane читает оба файла один раз при старте, каждый — с ограничением 1 МиБ. При mode = "pem" оба ключа обязательны и не должны быть пустыми:

invalid plane network configuration: tls.mode=pem requires cert and key paths

Отсутствующий файл или несоответствие сертификата ключу — фатальная ошибка старта. Параметр hosts в этом режиме не требуется и не проверяется: имена берутся из SAN вашего сертификата.

sudo chown root:root /etc/hastreamer-cctv/plane-key.pem
sudo chmod 0600 /etc/hastreamer-cctv/plane-key.pem

Из админки редактируются только пути, но не содержимое файлов.

[tls] hosts#

Набор имён, под которыми Plane выпускает сертификат: SAN для self_signed и список доменов, запрашиваемых у удостоверяющего центра, для acme.

hosts = ["cctv.example.com", "cctv-alt.example.com"]

Проверки действуют только в режимах self_signed и acme:

tls.mode=self_signed requires at least one hostname
tls.hosts must include the public_url hostname "cctv.example.com"
invalid TLS DNS hostname "cctv_example.com"
ACME HTTP-01 requires DNS hostnames, not IP literals

В режиме self_signed сохранённая личность, набор SAN которой перестал соответствовать hosts, перевыпускается при следующем запуске. Так же перевыпускается сертификат, оставшийся от предыдущей работы в режиме acme. В админке список задаётся через запятую.

[tls] store_dir#

Каталог используется только в режимах self_signed и acme, в off, external и pem он не задействован. Внутри:

• identity.pem — обслуживаемая сейчас пара «сертификат + приватный ключ», права 0600;
• account.pem — ключ учётной записи ACME, только в режиме acme, права 0600.

Каталог создаётся при отсутствии и принудительно приводится к правам 0700. Он содержит живой приватный ключ TLS — не делайте его доступным для чтения всем.

[tls] acme_listen#

Отдельный нешифрованный слушатель, единственная задача которого — отвечать на проверку ACME HTTP-01 по адресу /.well-known/acme-challenge/<токен>. Удостоверяющий центр обращается за этим URL строго по порту 80: для HTTP-01 это не опция, и именно поэтому Plane работает от root.

tls.acme_listen must be an IP socket address
tls.acme_listen and the main listen address must be different

[tls] acme_directory#

Адрес каталога ACME, в котором Plane регистрируется и заказывает сертификаты.

ACME directory must use HTTPS (loopback HTTP is test-only)

[tls] acme_contact#

Контакт, регистрируемый в удостоверяющем центре для уведомлений об истечении срока и проблемах; отправляется только если строка непуста. Пустое значение допустимо, но тогда вы не получите предупреждений об истечении сертификата. Некорректный адрес может отвергнуть сам центр при создании учётной записи.

Что в режиме ACME не настраивается#

Эти величины зашиты в код, параметров для них нет:

Чего в этом файле НЕТ#

Ни одного из перечисленных ниже параметров в plane.toml не существует. Добавление любого из них — не «неподдерживаемая настройка», а остановка запуска из-за неизвестного ключа.

Продуктовые настройки, которые живут в базе#

Эти значения создаются при первом запуске, правятся из админки и в plane.toml не выносятся:

Переменные окружения#

Переменные установщика#

Установщик задаёт вопросы интерактивно; заданная переменная окружения снимает соответствующий вопрос, поэтому тот же скрипт выполняет установку без участия оператора.

Значения, которые установщик пишет всегда и переменной не переопределяются: database_url (собирается из сгенерированного пароля), log_level = "info", db_pool_max = 16, [keys] session_key_pem, [jwks] session_ttl_secs = 3600, [tls] acme_listen = "0.0.0.0:80".

Установка без вопросов:

HASTREAMER_PLANE_TLS_MODE=acme \
HASTREAMER_PLANE_HOSTNAME=cctv.example.com \
HASTREAMER_PLANE_ACME_EMAIL=admin@example.com \
HASTREAMER_PLANE_EVIDENCE_DIR=/srv/cctv-evidence \
sudo -E installers/hastreamer-cctv-plane/install.sh

Переменные, читаемые работающим сервисом#

Задаётся дополнением к юниту:

sudo systemctl edit hastreamer-cctv-plane
# в открывшемся редакторе:
#   [Service]
#   Environment=RUST_LOG=info,cctv_plane::tls=debug
sudo systemctl restart hastreamer-cctv-plane

Файлы и каталоги, которыми владеет Plane#

Права 0600 Plane проверяет сам — на обоих файлах из [keys] и на tunnel-control.provisioning.key; при более широких правах запуск прерывается сообщением private key <путь> must have mode 0600. Своё хранилище TLS он создаёт сам с правами 0700 и 0600. За остальные файлы — plane.toml, .dbpass и ваши собственные сертификат с ключом в режиме pem — отвечает оператор.

sudo find /etc/hastreamer-cctv -type f \( -perm /o+rwx -o -perm /g+w \) -ls

Что обязательно бэкапить#

Минимальный набор, которого достаточно, чтобы восстановить работающий Plane. Полная процедура — в разделе Резервное копирование.

Копия каталога конфигурации целиком закрывает пункты 2, 3 и 4 сразу:

sudo tar czf /root/cctv-etc-$(date +%F).tgz -C / etc/hastreamer-cctv
sudo chmod 0600 /root/cctv-etc-*.tgz     # в архиве приватные ключи и пароли

Настоятельно рекомендуется добавить:

• /etc/hastreamer-cctv/.dbpass;
• /etc/hastreamer-cctv/plane-tls/account.pem — восстановим сам, но повторное использование учётной записи ACME экономит лимиты на создание новых;
• ваши plane-cert.pem и plane-key.pem в режиме pem — Plane их не воспроизведёт;
• юнит /etc/systemd/system/hastreamer-cctv-plane.service или его дополнение, если вы его правили.

Не нужны: plane-tls/identity.pem (самоподписанный перевыпустится, ACME закажет заново), исполняемый файл и превью (они выводятся заново из сохранённых блобов).

sudo -u postgres psql -c "ALTER ROLE hastreamer_cctv LOGIN PASSWORD 'пароль-из-plane.toml'"

Полный пример: боевая установка с ACME на публичном домене#

Локальное хранилище материалов, PostgreSQL на том же сервере, сертификаты Let's Encrypt. Прокомментирована каждая строка. Все секреты — заглушки: замените их и никогда не коммитьте этот файл.

# /etc/hastreamer-cctv/plane.toml — контрол-плейн SirinVideo CCTV, боевой пример.
# Владелец root:root, права 0640. Содержит пароль базы: не давать доступ на чтение всем.
# Читается ОДИН раз при старте — после любой правки: systemctl restart hastreamer-cctv-plane

# ── Слушатель ───────────────────────────────────────────────────────────────────────────────
# Сокет, который открывает Plane. Только IP:порт (имя хоста отвергается). 0.0.0.0 — все
# интерфейсы; 127.0.0.1 — только если впереди локальный реверс-прокси. Если удалить строку,
# действует зашитое 127.0.0.1:8080 (петля), а НЕ 0.0.0.0.
listen = "0.0.0.0:443"

# Канонический адрес для браузеров и нод. Только origin — без пути, параметров запроса и
# учётных данных. Обязан быть https://, потому что ниже включён режим TLS, и его хост обязан
# присутствовать в tls.hosts. Отсюда строятся ссылки, перенаправления и обратные вызовы нод.
public_url = "https://cctv.example.com"

# ── База данных (обязательно, значения по умолчанию нет) ────────────────────────────────────
# Plane владеет этой схемой и применяет к ней миграции при старте. Пароль лежит здесь открытым
# текстом — из-за этого права 0640. Помимо пула Plane открывает ОДНО дополнительное соединение
# для аренды-одиночки, поэтому max_connections в PostgreSQL считайте как db_pool_max + 1.
database_url = "postgres://hastreamer_cctv:ЗАМЕНИТЕ-ПАРОЛЬ@127.0.0.1:5432/cctv"

# Предельный размер пула подключений. Минимум 5: четыре подключения резервируются под пути
# контрол-плейна, пока идёт приём событий. По умолчанию 16. Из админки не меняется.
db_pool_max = 16

# ── Журнал ──────────────────────────────────────────────────────────────────────────────────
# Одно из debug | info | warn | error — закрытый набор, а не выражение RUST_LOG. Уходит в
# stderr → journald и в ограниченное кольцо в памяти, которое показывает админка. Заданная
# переменная RUST_LOG замещает этот параметр И блокирует управление уровнем в админке.
log_level = "info"

# ── Материалы событий (принадлежат Plane; видеоархив принадлежит ноде и настраивается во Fleet)
# Сюда попадают кадры по движению и ONVIF, вложения к событиям и их превью. Разместите на
# просторном диске. Путь обязан быть абсолютным и выделенным (без "." и "..", никогда не "/").
# Перенести каталог позже можно, но сначала прочитайте правила переноса: админка откажет,
# пока в текущем каталоге лежат блобы, а правка файла руками стартует на новом каталоге и
# поднимет оповещение об оставшихся в старом материалах (обратимо).
[attachment_storage]
backend = "local"
dir = "/var/lib/hastreamer-cctv/attachments"

# Политика заполнения для каталога выше. Пороги — проценты от ёмкости, обязателен строгий
# порядок 1 <= low < high < critical <= 99 (зазор между ними — намеренный гистерезис).
[event_storage_policy]
# Необязательный жёсткий потолок в байтах. Для локального бэкенда можно не задавать — тогда
# берётся ёмкость файловой системы; если задан, то не меньше 64 МиБ. Для S3 обязателен.
# Здесь показано 200 ГиБ:
max_bytes = 214748364800
# "disabled" — давление никогда не удаляет историю (безопасное значение по умолчанию).
# "oldest_purge_day" — РАЗРУШИТЕЛЬНО: при цикле давления «высокий → низкий» списывается целиком
# самое старое поколение суток очистки. Байтовый бюджет сам по себе удалять не разрешает.
volume_retention = "disabled"
low_watermark_percent = 75        # ниже этого порога давление снимается
high_watermark_percent = 85       # на этом пороге и выше давление включается
critical_watermark_percent = 95   # жёсткое давление

# ── Личности подписи (файлы приватных ключей; через API не передаются никогда) ───────────────
[keys]
# Ключ ES256 в PKCS#8 PEM, которым подписываются JWT сессий; ноды проверяют билеты по его
# открытой половине через /.well-known/jwks.json. Если файла нет — будет создан с правами 0600,
# но ПОТЕРЯННЫЙ файл означает НОВУЮ личность (все пользователи разлогинены), поэтому его надо
# бэкапить. При правах шире 0600 Plane откажется стартовать.
# По умолчанию, если строку убрать: <каталог конфига>/signing.pem
session_key_pem = "/etc/hastreamer-cctv/plane-session.pem"
# Отдельная личность ES256 для управления ретрансляторами и агентами, чтобы ротация ключа
# сессий не отрезала ретрансляторы. Создаётся автоматически с правами 0600 рядом с plane.toml
# вместе с 32-байтным tunnel-control.provisioning.key, из которого выводятся ВСЕ конфигурации
# туннелей — бэкапьте оба файла.
# По умолчанию, если строку убрать: <каталог конфига>/tunnel-control.pem
tunnel_control_key_pem = "/etc/hastreamer-cctv/tunnel-control.pem"

# ── Время жизни сессии ──────────────────────────────────────────────────────────────────────
[jwks]
# Срок жизни выданного JWT сессии в секундах. По умолчанию 3600 (1 час). Диапазон не
# проверяется — 0 просрочит каждый токен немедленно. Индивидуального отзыва сессий нет:
# сокращайте это значение либо делайте ротацию ключа (POST /api/v1/admin/keys/rotate).
session_ttl_secs = 3600

# ── TLS собственного слушателя API и админки ────────────────────────────────────────────────
# Режимы: off (открытый HTTP, public_url http://) · external (открытый HTTP, но public_url
# https:// — для терминирующего TLS реверс-прокси) · pem (свои сертификат и ключ) ·
# self_signed (самоподписанный, браузер предупреждает) · acme (автоматический Let's Encrypt).
# Любой режим, кроме off, требует https:// в public_url.
[tls]
mode = "acme"
# Набор имён сертификата. Для acme это ОБЯЗАТЕЛЬНО публичные DNS-имена, указывающие на ЭТОТ
# сервер (IP-литералы и маски отвергаются), и хост из public_url обязан быть в списке.
hosts = ["cctv.example.com"]
# Куда Plane складывает выпущенный им TLS-материал: identity.pem (обслуживаемая пара
# «сертификат + ключ») и account.pem (ключ учётной записи ACME). Каталог приводится к 0700,
# файлы — к 0600. По умолчанию, если строку убрать: <каталог конфига>/plane-tls
store_dir = "/etc/hastreamer-cctv/plane-tls"
# Контакт для уведомлений удостоверяющего центра об истечении срока. Пустая строка допустима,
# но тогда предупреждений не будет.
acme_contact = "admin@example.com"
# ОТДЕЛЬНЫЙ нешифрованный слушатель, отвечающий на проверку HTTP-01 по адресу
# /.well-known/acme-challenge/<токен>. Порт 80 должен быть доступен из интернета и свободен от
# любого другого веб-сервера. Обязан отличаться от listen. По умолчанию "0.0.0.0:80".
acme_listen = "0.0.0.0:80"
# Каталог ACME. Только https:// (исключение — http://127.0.0.1 для тестовых центров). Для
# пробного прогона укажите здесь staging-каталог, чтобы не расходовать боевые лимиты.
# По умолчанию — боевой каталог Let's Encrypt, показанный ниже.
acme_directory = "https://acme-v02.api.letsencrypt.org/directory"
# Продление автоматическое и НЕ настраивается: обновление при остатке менее 30 суток, проверка
# каждые 12 часов, повтор раз в час после неудачи. Если сертификат не удалось получить при
# старте, Plane отдаёт ВРЕМЕННЫЙ самоподписанный сертификат из памяти и продолжает попытки.

Минимальный пример: за реверс-прокси, режим external#

Прокси терминирует TLS на https://cctv.example.com и передаёт запросы в Plane по петлевому интерфейсу. Все не указанные параметры берут значения по умолчанию.

# /etc/hastreamer-cctv/plane.toml — минимальная внутренняя установка (TLS терминирует прокси).
# Права 0640 root:root — пароль базы лежит здесь так же, как и в боевом примере.

# Привязка только к петле: напрямую до Plane не должен доставать никто, кроме локального
# прокси. Это важно ещё и потому, что Plane принимает ПЕРВЫЙ переход X-Forwarded-For как адрес
# клиента для аудита и ограничения частоты — настройте прокси на ПЕРЕЗАПИСЬ этого заголовка.
listen = "127.0.0.1:8080"

# Адрес, который набирают пользователи, — адрес ПРОКСИ, https, хотя сам Plane говорит по HTTP.
public_url = "https://cctv.example.com"

# Обязательно. Значения по умолчанию нет.
database_url = "postgres://hastreamer_cctv:ЗАМЕНИТЕ-ПАРОЛЬ@127.0.0.1:5432/cctv"

[tls]
# "external": Plane отдаёт открытый HTTP, объявляя при этом https:// в public_url, потому что
# шифрует прокси впереди. За терминирующим TLS прокси нужен именно этот режим, а НЕ "off":
# "off" отверг бы https://-адрес сообщением "tls.mode=off requires an http:// public_url".
mode = "external"

# Всё остальное — по умолчанию:
#   log_level    = "info"
#   db_pool_max  = 16
#   [attachment_storage] backend = "local", dir = "/var/lib/hastreamer-cctv/attachments"
#   [event_storage_policy] пороги 75/85/95, max_bytes не задан, volume_retention = "disabled"
#   [keys] session_key_pem        = "/etc/hastreamer-cctv/signing.pem"        (создастся 0600)
#          tunnel_control_key_pem = "/etc/hastreamer-cctv/tunnel-control.pem" (создастся 0600)
#   [jwks] session_ttl_secs = 3600

Если прокси нет вообще и установка живёт в изолированной локальной сети по открытому HTTP, уберите таблицу [tls] целиком и используйте http:// в public_url:

listen       = "0.0.0.0:8080"
public_url   = "http://10.0.0.10:8080"   # http://, потому что tls.mode по умолчанию "off"
database_url = "postgres://hastreamer_cctv:ЗАМЕНИТЕ-ПАРОЛЬ@127.0.0.1:5432/cctv"

Справочник сообщений об ошибках#

Каждое сообщение из списка ниже печатается в виде hastreamer-plane: fatal: invalid plane network configuration: <сообщение> и видно в journalctl -u hastreamer-cctv-plane. Те же строки возвращаются с кодом 400 при сохранении из админки.

db_pool_max must be at least 5 so short event-ingest transactions leave four database connections available
listen must be an IP socket address (hostnames are not bind addresses)
public_url must be an HTTP(S) origin
public_url must be an HTTP(S) origin without credentials, path, query or fragment
tls.mode=off requires an http:// public_url
tls.mode=<mode> requires an https:// public_url
tls.mode=pem requires cert and key paths
tls.mode=<mode> requires at least one hostname
tls.hosts must include the public_url hostname "<host>"
invalid TLS DNS hostname "<host>"
tls.acme_listen must be an IP socket address
tls.acme_listen and the main listen address must be different
ACME HTTP-01 requires DNS hostnames, not IP literals
ACME directory must use HTTPS (loopback HTTP is test-only)
local event storage directory must be a dedicated absolute path below the filesystem root
S3 event storage endpoint must be schemeless host[:port]
S3 event storage endpoint must be schemeless host[:port] without credentials or path
invalid S3 event storage endpoint
S3 event storage bucket must be a non-empty bucket name without path separators
S3 event storage region must not be empty
S3 event storage credentials must not be empty
virtual-host S3 addressing requires a DNS hostname endpoint and a DNS-compatible bucket name
event storage watermarks must satisfy 1 <= low < high < critical <= 99
event storage max_bytes must be at least 64 MiB
event storage max_bytes must fit the PostgreSQL bigint accounting domain
S3 event storage requires an explicit max_bytes budget

Остальные фатальные ошибки старта:

reading /etc/hastreamer-cctv/plane.toml: <ошибка ввода-вывода>   # файла нет или он нечитаем
parsing /etc/hastreamer-cctv/plane.toml: <ошибка toml>           # синтаксис, неизвестный ключ,
                                                                 # отсутствующий database_url или
                                                                 # public_url, неверное значение
                                                                 # перечисления
private key /etc/hastreamer-cctv/plane-session.pem must have mode 0600

Ошибки, возможные только при сохранении из админки (PATCH /api/v1/settings/plane) и никогда не встречающиеся при старте:

400 no_settings_supplied                                    400 invalid_public_url
400 dvr_export_max_secs_out_of_range                        409 settings_busy
409 rust_log_override                                       409 event_storage_rotation_blocked
400 destructive_volume_retention_acknowledgement_required   502 <детали проверки бэкенда>
500 plane_config_unreadable:<ошибка>
"/etc/hastreamer-cctv/plane.toml changed after the settings form was loaded"
S3 access and secret keys must be supplied together
S3 event storage credentials are required when selecting the backend

После правки — проверка#

sudo systemctl restart hastreamer-cctv-plane
systemctl is-active hastreamer-cctv-plane                # ожидается: active
sudo journalctl -u hastreamer-cctv-plane -n 80 --no-pager

INFO hastreamer_plane: serving listen=0.0.0.0:443 tls_mode="acme"

Смежные разделы: Установка с нуля: Plane, Резервное копирование.