Skip to content

Changing the server configuration by passing JSON objects

You can modify the Flussonic settings by sending JSON objects in HTTP API calls.

Modifying the Flussonic configuration by passing JSON objects (modify_config)

The modify_config command is a part of the HTTP API and it allows you to edit fragments of the Flussonic configuration file and save the changes on disk.

Request's URL: /flussonic/api/modify_config

Parameters:

  • HTTP request payload (required parameter) — a JSON object that contains the part of configuration with which you want to replace an existing part or which you want to add to the configuration.

  • async=true — the parameter is useful if the command 'modify_config' takes a long time to complete.

    Executing a command involves two steps — saving the configuration file and applying the new configuration to the Flussonic server. Application of the configuration can take a long time in case of network installation of Flussonic or a large number of streams on the server. Therefore, we added the option to choose between a synchronous and asynchronous way to execute modify_config.

    By default, the command returns the response only after the new configuration applied to the Flussonic server (synchronous way).

    To make 'modify_config' respond quicker, add the query string parameter '?async=true'. When executed asynchronously, modify_config will return OK as soon as the configuration file is saved, and then once more when the new configuration is applied in Flussonic. This will provide a quicker response letting you know that the new configuration is valid and accepted.

    Example: /flussonic/api/modify_config?async=true.

Response: Entire updated configuration in the JSON format.

You pass a configuration in the form of JSON to the API. The passed configuration is merged with the working one on the server, and the result is saved to the configuration file /etc/flussonic/flussonic.conf.

Note that only the difference between the old configuration and the new one is passed.

The fields in the JSON object correspond to the parameters specified in the text file with the configuration. Groups of objects, such as streams and publication prefixes, are grouped within the streams and lives fields. Some parameters have values that are objects, not strings.

To delete a configuration parameter, set it to null.

How to specify parameters in JSON correctly

To know how a certain configuration parameter is written in the JSON format, you can get Flussonic configuration by using read_config and examine the response.

Example. Authorization

Suppose the global authorization is turned on in Flussonic, we have an HTTP backend with a passed parameter secret=xyz:

auth http://localhost:4567/auth secret=xyz;

We want to use the script myscript.lua instead, and to pass another parameter mykey=123 in addition to secret=xyz. To modify the configuration accordingly, use this JSON object in a call:

{"auth": {"url": "myscript.lua", "extra": {"mykey": "123"}}}

As a result, the configuration file will have this line:

auth myscript.lua mykey=123 secret=xyz;

To turn off authorization, pass {"auth": null}.

Example. Actions with streams

You can access a sream settings via the field "streams", to which you pass an object that contains stream infromation. The stream name acts as the key.

For example, let's turn off authorization for the stream channel_01. To do so, specify false for URL:

'{"streams": {"channel_01": {"auth": {"url": false}}}}'

Flussonic will write the value false for the auth directive in the configuration file:

stream channel_01 {
   url hls://myvideo.com/mylive;
   auth false;
   ...
}

A stream can have several sources. Several sources are specified by using the array urls:

{"streams":
  {"channel_01":
    {"urls": [{"url": "tshttp://example.com/mystream"},
              {"url": "udp://239.1.1.1:1234"}
   ]}}}

How to delete a stream:

'{"streams" : {"channel_01" : null}}'

And this is the example of the same request to delete a stream, posted by using curl :

curl -d '{"streams" : {"test1" : null}}' http://ADMIN:PASSWORD@FLUSSONIC:80/flussonic/api/modify_config

--