Settings API

Esta página aún no está disponible en tu idioma.

The settings methods read and replace the whole configuration and set its top-level sections: the general settings, the HTTP authentication settings, the log settings, the server list, or any other key. See How to call API methods for the entry points, authentication and roles. Every method on this page answers 200 with a JSON body once the request passed authentication and the role gate; a command that modifies the configuration answers {"<cmd>": "ok"}.

The configuration is the JSON file given with the -c command line option. A modifying command changes the running configuration in memory and saves the file: most commands save it one second after the change, so that a burst of changes is written once; upload, set-settings and set-config with restart write it immediately. One hour after the last change a copy is written to <config>.backup. Without -c nothing is saved, upload and the observer form of load are answered 404, and every other change lives in memory until the instance stops. Every command that changes the running configuration pushes a WebSocket message with the same scope as the command name (set-log pushes log_event), see Events.

A field marked required below is read without a check: a command sent without it raises an error inside the instance, which terminates the process without a reply. Send every required field.

Download configuration

Request: GET /api/config or POST /control/. Control on the path entry point; control and observer on the command entry point. An observer calling GET /api/config receives 404.

{
    "cmd": "load"
}

Response: the configuration object itself, not wrapped in a key. Its top-level keys are the configuration sections, for example:

{
    "gid": 466561,
    "settings": { "control_port": "8000", "instance_name": "streamer-1" },
    "users": { "admin": { "type": 1, "enable": true, "cipher": "..." } },
    "auth": { "enable": true },
    "log": { "api_access": true },
    "servers": [ { "type": "streamer", "name": "Second", "host": "10.0.0.2", "port": 8000 } ],
    "dvb_tune": [ { "id": "a002", "adapter": 0 } ],
    "make_stream": [ { "id": "a001", "name": "Channel 1", "type": "spts", "input": [ "..." ] } ]
}

gid - number, the counter from which the object ids (a001, …) are generated.
settings - object, the general settings, see Set general settings.
users - object keyed by login, see Users API.
auth - object, see Set HTTP authentication.
log - object, see Set log settings.
servers - array, see Set server.
dvb_tune - array of adapters, see DVB Adapters API.
make_stream - array of streams, see Streams API.

A control user receives the running configuration as held in memory, including the cipher of every user. An observer receives the configuration file read from disk with two reductions: every softcam entry keeps only its id and name, and the cipher field of every user is removed.

Example:

curl --user login:password http://server:8000/api/config > config.json

Upload configuration

Request: POST /control/. Control only.

{
    "cmd": "upload",
    "config": { "settings": { "control_port": "8000" }, "make_stream": [] }
}

config - object, required. The whole configuration in the form returned by Download configuration.

Response:

{ "upload": "ok" }

The object is written to the configuration file immediately and without validation, replacing the file. The running configuration is not changed: the uploaded configuration takes effect after Restart, when the file is read again. Until then the API keeps serving and modifying the running configuration, and a modifying command saves the running configuration over the uploaded file again. The backup written an hour later contains the running configuration, not the uploaded one, unless the instance was restarted in between. No WebSocket message is pushed. The reply is 404 when the instance runs without a configuration file.

Example:

curl \
    -X POST \
    --user login:password \
    -d @- \
    http://server:8000/control/ <<END
{ "cmd": "upload", "config": $(cat config.json) }
END

Set general settings

Request: POST /control/. Control only.

{
    "cmd": "set-settings",
    "settings": {
        "control_port": "8000",
        "control_path": "",
        "instance_name": "streamer-1",
        "allow_real_ip": false,
        "tsdb_interval": 60
    },
    "gid": 466561
}

settings - object, required. Replaces the settings section of the configuration as sent; keys that are not sent are removed. An empty object removes the section. The keys are the general settings of the instance described in General settings; the keys read by the methods in this section are:
- control_port - string, the control server port as "8000" or "address:port" (see Control path). It replaces the -p command line value. A number is not accepted: the instance aborts while starting with it and has to be fixed in the configuration file.
- control_path - string, the prefix of the entry points.
- allow_real_ip - boolean, trust the X-Real-IP header for the client address (see Authentication).
- instance_name - string, the instance name reported as hostname by Get status and as instance by System status.
- tsdb_interval - number, seconds, the statistics interval of System status.
gid - number, optional. Sets the object id counter; left unchanged when absent.

Response:

{ "set-settings": "ok" }

The configuration is saved immediately, the WebSocket message set-settings is pushed, and one second after the reply the instance restarts as with Restart: the new settings take effect through the restart.

Example:

curl \
    -X POST \
    --user login:password \
    -d '{"cmd":"set-settings","settings":{"control_port":"8000","instance_name":"streamer-1"}}' \
    http://server:8000/control/

Set configuration key

Request: POST /control/. Control only.

{
    "cmd": "set-config",
    "key": "servers",
    "data": [ { "type": "streamer", "name": "Second", "host": "10.0.0.2", "port": 8000 } ],
    "restart": false
}

key - string, required. The top-level configuration key to set; any key, including one no other method knows.
data - any JSON value, optional. Stored under key as sent. When absent the key is removed from the configuration.
restart - boolean, optional, default false. true saves the configuration immediately and restarts the instance one second after the reply, as with Restart.

Response:

{ "set-config": "ok" }

The value is stored in the running configuration and saved. Only the key users is applied to the running instance by this command: the control API user registry is rebuilt from it at once. Every other key is stored only and takes effect when its consumer reads the configuration, that is after a restart. The WebSocket message set-config with key and data is pushed; data is absent when the key was removed.

Example:

curl \
    -X POST \
    --user login:password \
    -d '{"cmd":"set-config","key":"servers","data":[]}' \
    http://server:8000/control/

Set HTTP authentication

Request: POST /control/. Control only.

{
    "cmd": "set-auth",
    "auth": {
        "enable": true,
        "http_ip_allow": [ "192.168.1.0/24", "10.0.0.5" ],
        "http_ip_deny": [ "192.168.1.200" ],
        "http_token_deny": [ "revoked-token" ],
        "securetoken": "secret",
        "backend": "http://middleware.example.com/auth",
        "promo": "http://example.com/subscribe",
        "x_real_ip": false
    }
}

The authorization of streaming clients (HTTP MPEG-TS, HLS) is described in Authorization. This method stores its settings.

auth - object, optional. Replaces the auth section of the configuration as sent. When absent the section is removed and authorization is switched off. The keys read by the instance:
- enable - boolean. Without true authorization is switched off whatever else is set.
- http_ip_allow, http_ip_deny - arrays of strings, optional. Each entry is an IPv4 or IPv6 address, or an address with a prefix length (192.168.1.0/24). The lists are stored sorted by prefix length, longest prefix first. An entry that is not a valid address is skipped with a log line when the settings are applied.
- http_token_deny - array of strings, optional. Tokens that are always rejected.
- securetoken - string or number, optional. The secret of the secure token check (see Secure token).
- backend - string or object, optional. The URL of the authorization backend (see Backend); as an object {"format": "http", "host": "...", "port": 80} it is joined to format://host:port. The URL must contain ://, otherwise the backend is skipped with a log line.
- iptvportal, smarty, ministra - string, optional. The base URL of the middleware; used when backend is absent, with the middleware’s check path appended.
- promo - string, optional. The URL a rejected client is redirected to instead of being denied.
- x_real_ip - boolean, optional. Trust the X-Real-IP header for the client address.

Response:

{ "set-auth": "ok" }

The settings are applied to the running instance at once, without a restart. When the authorization engine rejects the settings the error is logged and the settings active before the call stay in force; the reply is still ok. The configuration is saved and the WebSocket message set-auth with the stored object is pushed; auth is absent when the section was removed. Every request field not listed above is stored with the object but not read.

Example:

curl \
    -X POST \
    --user login:password \
    -d '{"cmd":"set-auth","auth":{"enable":true,"securetoken":"secret"}}' \
    http://server:8000/control/

Set log settings

Request: POST /control/. Control only.

{
    "cmd": "set-log",
    "set": {
        "debug": false,
        "stdout": true,
        "filename": "/var/log/astra.log",
        "max_file_size": 100,
        "syslog": "",
        "api_access": true
    }
}

set - object, required. Replaces the log section of the configuration as sent:
- debug - boolean. Enables debug log lines.
- stdout - boolean. Write the log to the standard output.
- filename - string. Path of the log file; an empty string turns file logging off.
- max_file_size - number, MiB. The size at which the log file is rotated into numbered archives; 0 disables rotation.
- syslog - string. The syslog identifier; an empty string turns syslog off.
- api_access - boolean. Write every API call to the log with the login and the client address (see Access log).

Every key that is left out reverts to the value given on the command line at start, not to the value set by a previous call: send the complete object every time. An empty object resets every key and is stored and pushed as [].

Response:

{ "set-log": "ok" }

The log settings are applied at once, the configuration is saved and the WebSocket message log_event with the stored object under set is pushed.

Example:

curl \
    -X POST \
    --user login:password \
    -d '{"cmd":"set-log","set":{"stdout":true,"api_access":true}}' \
    http://server:8000/control/

Set server

Request: POST /control/. Control only.

{
    "cmd": "set-server",
    "id": 0,
    "server": {
        "type": "streamer",
        "enable": true,
        "name": "Second",
        "host": "10.0.0.2",
        "port": 8000,
        "user": "admin",
        "pass": "secret"
    }
}

The servers list holds other Astra instances the web interface connects to, so that several instances are managed from one interface. The instance itself does not connect to them: the entries are stored for the interface only.

id - number, optional. The zero-based position of the entry in the servers list. With id the entry at that position is replaced; without id the object is appended.
server - object, required. Stored as sent. The built-in web interface stores type (always streamer), enable, name, host, port, user and pass, and connects to every entry with type streamer whose enable is not false.
server.remove - boolean. true removes the entry at id; id is then required. The list is removed from the configuration when its last entry is removed.

Response:

{ "set-server": "ok" }

The configuration is saved and the WebSocket message set-server with id and server is pushed; for a removal server is {"remove": true}.

Example:

curl \
    -X POST \
    --user login:password \
    -d '{"cmd":"set-server","server":{"type":"streamer","enable":true,"name":"Second","host":"10.0.0.2","port":8000}}' \
    http://server:8000/control/