Flussonic Media Server documentation

Managing Flussonic configuration via the HTTP API

About using the HTTP API to configure Flussonic Anchor Anchor x2

You can manage the Flussonic configuration by using the HTTP API. The configuration parameters are sent and get in the JSON format.

Flussonic saves the parameters by updating its configuration file /etc/flussonic/flussonic.conf.

The HTTP API allows you to:

  • Read the existing configuration, and optionally get runtime statistics about Flussonic's work. See read_config.

  • Modify a part of the configuration file and save it on disk in /etc/flussonic/flussonic.conf. See modify_config.

  • Apply the entire configuration to a running Flussonic without saving the new configuration on disk in /etc/flussonic/flussonic.conf. See update_config.

  • Apply the entire configuration to a running Flussonic and save the new configuration on disk in /etc/flussonic/flussonic.conf. See save_config.

When you post requests to Flussonic via HTTP/HTTPS, the basic authentication is used, with credentials specified in the edit_auth option of Flussonic configuration file.

Getting Flussonic configuration (read_config) Anchor Anchor x2

Flussonic can provide the information about its configuration in the JSON format via the HTTP API.

The request URL: /flussonic/api/read_config

Parameters:

  • skip_streams=true (optional). This parameter removes static streams from the output.

  • runtime=true (optional). This parameter fills the output configuration structure with runtime statistics for Flussonic, streams, archives, and so on.

Request example:

In the browser:

http://FLUSSONIC-IP:8080/flussonic/api/read_config

By using curl:

curl http://ADMIN:PASSWORD@FLUSSONIC:8080/flussonic/api/read_config

Response example:

{
    "auth": {
        "url": "http://localhost:3456"
    },
    "cluster_key": "xxxyyy123",
    "edit_auth": {
        "login": "flussonic",
        "password": "mypass123"
    },
    "http": [
        8080
    ],
    "lives": {
        "mylive": {
            "auth": {
                "url": "http://localhost:3456",
                "url_global": "http://localhost:3456"
            },
            "cluster_key": "xxxyyy123",
            "cluster_key_global": "xxxyyy123",
            "position": 1,
            "prefix": "mylive",
            "publish_enabled": true,
            "static": false
        }
    },
    "log_requests": true,
    "loglevel": "debug",
    "mysql": 3307,
    "plugins": {
        "vsaas": {
            "database": "sqlite:///opt/flussonic/priv/vsaas.db",
            "name": "vsaas",
            "position": 1
        }
    },
    "pulsedb": "/var/lib/pulse",
    "root": "wwwroot",
    "rtmp": 1935,
    "rtsp": 8554,
    "snmp": 3000,
    "streams": {
        "ort": {
            "auth": {
                "url": "http://localhost:3456",
                "url_global": "http://localhost:3456"
            },
            "cluster_key": "xxxyyy123",
            "cluster_key_global": "xxxyyy123",
            "name": "ort",
            "position": 1,
            "prepush": 10,
            "static": true,
            "transcoder": [
                [
                    "video_bitrate",
                    1024000
                ],
                [
                    "audio_bitrate",
                    100000
                ]
            ],
            "urls": [
                {
                    "url": "udp://239.1.2.3:1234"
                },
                {
                    "url": "hls://example.com/stream/index.m3u8"
                }
            ]
        }
    },
    "view_auth": {
        "login": "flussonic",
        "password": "viewpass"
    }
}

A request example with the parameter skip_streams:

http://FLUSSONIC-IP:8080/flussonic/api/read_config?skip_streams=true

or

curl http://ADMIN:PASSWORD@FLUSSONIC:8080/flussonic/api/read_config?skip_streams=true

A request example with the parameter runtime:

http://FLUSSONIC-IP:8080/flussonic/api/read_config?runtime=true

or

curl http://ADMIN:PASSWORD@FLUSSONIC:8080/flussonic/api/read_config?runtime=true

Modifying the Flussonic configuration by passing JSON objects (modify_config) Anchor Anchor x2

The modify_config command is a part of the HTTP API and it allows you to edit fragments of the Fussonic 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.

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 config and the new one is transmitted.

The fields in the transmitted 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 also objects, not strings.

To delete a 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 in JSON by using this API. Learn more in read_config.

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:8080/flussonic/api/modify_config

Update configuration file (update_config) Anchor Anchor x2

To update the Flussonic configuration, you need to pass the text of the new configuration file as a POST request body.

An important difference from save_config is that the new configuration is applied to a running server, but the configuration file on disk does not change.

URL: /flussonic/api/update_config

Parameters:

  • HTTP request payload — the text of a new configuration file (required)
    For example, for curl, this parameter is --data-binary:
    curl ... --data-binary '# Global settings:\nhttp 80;\nrtsp 554;\nrtmp 1935;\npulsedb /var/run/flussonic;'

Response: true if the request was processed successfully


Save a new configuration file (save_config) Anchor Anchor x2

To update the Flussonic configuration, you need to pass the text of the new configuration file as a POST request body.

An important difference from update_config is that the new configuration is not only applied to a running server, but also replaces the existing configuration file /etc/flussonic/flussonic.conf.

URL: /flussonic/api/save_config

Parameters:

  • HTTP request payload — the text of the new configuration file (required).
    For example, for curl, this parameter is --data-binary:
    curl ... --data-binary '# Global settings:\nhttp 80;\nrtsp 554;\nrtmp 1935;\npulsedb /var/run/flussonic;'

Response: true if the request was processed successfully