Валидация конфига¶

Flussonic выполняет валидацию конфигурационного файла по тем же правилам, что и валидацию API вызовов: по одной и той же OpenAPI схеме. По умолчанию мы предоставляем человекочитаемый формат конфигурационного файла, ориентируясь на тех системных администраторов, которые привыкли редактировать текстовые конфигурационные файлы руками.

При каждом запуске, а также при изменении конфигурационного файла Flussonic выполняет проверку конфигурации на наличие проблем. Если при сохранении конфигурационного файла произошла ошибка или какая-то опция стала неподдерживаемой после обновления версии ПО, то Flussonic все равно запустится, но перейдет в аварийный режим. О работе в аварийном режиме свидетельствует то, что в UI доступно только страницы Config и Support. Кроме того, о состоянии конфига можно судить по параметрам streamer_status (код ошибки) и text_alerts (текстовое описание ошибки) в ответе на запрос Flussonic-API: GET /streamer/api/v3/config/stats.

Валидация до старта сервера не имеет смысла, поскольку система управления сервисами systemd не поддерживает ситуацию при которой сервис не может работать из-за невалидного конфига и никак не сигнализирует оператору системы об этой ситуации. Т.е. у вас просто будет рестартиться сервис без какой-либо внятной индикации.

В случае, когда конфигурация Flussonic происходит не руками человека, а генерируется из внешней системы, задача валидации конфига стоит очень остро, ведь надо как-то проверить корректность работы генератора и получается, что при генерации текстового формата единственный способ — сгенерировать, перезапустить сервер и выяснить, что конфиг был невалидный.

Это решение, конечно, не подходит для работы, поэтому мы рекомендуем использование JSON формата для конфига при генерации сторонними средствами.

Т.е. суть подхода:

формируете конфиг по указанной нами OpenAPI схеме (формат, совместимый с JSON schema);
генерируете его JSON-представление;
валидируете любым внешним валидатором по схеме;
пишете результирующий конфиг в /etc/flussonic/flussonic.conf;
запускаете сервер.

Схема конфига JSON¶

Вы можете взять актуальную OpenAPI схему для Flussonic в одном из следующих мест:

на нашем сайте;
в файле /opt/flussonic/lib/web/priv/schema-v3-public.json.

В схеме определен тип #/components/schemas/server_config, именно по нему валидируется конфиг при чтении.

Текстовый формат сначала транслируется в JSON, а потом валидируется по этой схеме. Вам же мы рекомендуем сразу записывать конфиг в JSON формате.

Для того, чтобы подсмотреть, как выглядит JSON-представление конфига, можно воспользоваться имеющейся утилитой:

# /opt/flussonic/bin/validate_config -j
{"listeners":{"http":[{"port":80}]}}

Для работы с JSON рекомендуем использовать утилиту jq:

# /opt/flussonic/bin/validate_config -j | jq
{
  "listeners": {
    "http": [
      {
        "port": 80
      }
    ]
  }
}

Выше вы видите представление простейшего конфига:

http 80;

Валидация конфига JSON¶

Валидация конфига происходит в два этапа:

формальная проверка по JSON Schema;
проверка внешних условий и тех, которые нельзя выразить в схеме, например целостность сертификатов.

Для валидации целостности конфига можно воспользоваться внешней утилитой для валидации по схеме, а можно той, которую мы предлагаем:

# cat /etc/flussonic/flussonic.conf
htp 80;
# /opt/flussonic/bin/validate_config -j
{"col":1,"config":{},"detail":"htp","error":"unknown_command","line":1,"path":[]}

Аналогично будет с JSON-конфигом:

# cat /etc/flussonic/flussonic.conf
{"listeners":{"http":[{"port":80,"flag":true}]}}
# /opt/flussonic/bin/validate_config -j
{"error":"unknown_key","path":["server_config","listeners","http",0,"flag"]}