Skip to content

Config validation

Flussonic uses an OpenAPI scheme to validate its configuration file, utilizing the same rules as those applied to API calls. The configuration file is presented in a clear, human-readable format to facilitate manual editing by system administrators.

Flussonic checks the configuration file for any issues at the start-up and every time you change the config. If the format is invalid, for example an error occurs while saving or an option becomes unsupported after a software update, Flussonic will start anyway but will engage the crash mode to prevent disruptions to the system. In the crash mode, only Config and Support pages are available in the UI. You may also refer to the streamer_status (error code) and text_alerts (error description) parameters in the response to Flussonic-API: GET /streamer/api/v3/config/stats to check the config status.

It is not practical for Flussonic to validate the configuration file before starting the server, as the systemd service management system does not have a way to handle a service that is unable to function due to an invalid configuration file. This means that the service would simply restart without any clear indication about the issue, as systemd does not have a mechanism for signaling about this situation.

If the Flussonic configuration is generated by an external system rather than being manually edited, it is essential to validate the accuracy of the configuration file. The traditional method of generating the config, restarting the server, and checking for invalidity is not a practical solution for regular use.

Instead, we recommend using the JSON format for config generation by external tools to ensure proper functioning and avoid any issues.

To summarize this approach:

  1. Create the config using the specified OpenAPI scheme (a format compatible with JSON schema).
  2. Generate its JSON representation.
  3. Validate it using any external validator according to the schema.
  4. Write the resulting config to /etc/flussonic/flussonic.conf.
  5. Start the server.

The JSON config Schema

You can get the current OpenAPI schema for Flussonic either:

  • on our website
  • or in the file /opt/flussonic/lib/web/priv/schema-v3-public.json, which is located on a server with the Flussonic package installed.

The schema defines the #/components/schemas/server_config type, which is used to validate the config when it is read. The text format is first translated into JSON and then validated using this schema. We recommend writing the config directly in the JSON format.

To examine the JSON representation of the config, you can use the utility provided with the Flussonic package:

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

We recommend using the jq utility for working with JSON:

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

The above example shows the JSON representation of the simplest possible config:

http 80;

JSON config validation

Config validation occurs in two stages:

  1. Formal validation using the JSON Schema
  2. Checking external conditions and those that cannot be expressed in the schema, such as the integrity of certificates

To validate the integrity of the config, you have two options: using an external utility for schema validation or using the /opt/flussonic/bin/validate_config utility provided with the Flussonic package:

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

Similarly, with a JSON config:

# 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"]}