Configuration of Mediaserver

The configuration methods

A configuration file.
http, https source of configuration.

RTSP configuration

dsn rtsp.listenREQUIRED = "*:554:/"

Network settings for incoming RTSP client connections in the <hostname>:<port>:<base-url> format, where:

hostname – refers to a local network name, at the IP address of which connections will be listened to. If * is specified, connections at all network addresses will be listened to, and the current hostname from hostname will be used.
port – refers to a port number that will be open for listening of connections. In specific operational systems, you should allow for not root users to use a port lower than 1024.
base-url – a base path address.

number rtsp.ip = 4

An IP protocol type for incoming connections:

4 – for IP4
6 – for IP6
46 – for dual stack IP4/IP6.

number rtsp.workers = 2

A number of system streams that serve the capture of camera streams. Adjust the value depending on the number of captured streams.

number rtsp.poll = 256

A value that defines the maximum number of processed network events. Increase the value depending on the number of served streams. The value is specified for each system stream rtsp.workers.

JSON

{
    "rtsp": {
        "listen": "*:554:/",
        "ip": 4,
        "workers": 2,
        "poll": 256
    }
}

For details, refer to the RTSP module documentation page.

ONVIF configuration

dsn onvif.listenREQUIRED = "*:554:/"

Network settings for incoming RTSP client connections in the <hostname>:<port>:<base-url> format, where:

hostname – refers to a local network name, at the IP address of which connections will be listened to. If * is specified, connections at all network addresses will be listened to, and the current hostname from hostname will be used.
port – refers to a port number that will be open for listening of connections. In specific operational systems, you should allow for not root users to use a port lower than 1024.
base-url – a base path address.

number onvif.ip = 4

An IP protocol type for incoming connections:

4 – for IP4
6 – for IP6
46 – for dual stack IP4/IP6.

number onvif.workers = 2

A number of system streams that serve the capture of camera streams. This value needs to be adjusted depending on the number of captured streams.

number onvif.poll = 256

The value that defines the maximum number of processed network events. Increase the value depending on the number of served streams. The value is specified for each system stream onvif.workers.

bool onvif.ssl = true

Specify whether to use SSL (HTTPS) for incoming connections. When false – SSL isn’t used.

JSON

{
    "onvif": {
        "listen": "*:554:/",
        "ip": 4,
        "workers": 2,
        "poll": 256,
        "ssl": true
    }
}

For details, refer to the ONVIF documentation page.

PROXY configuration

dsn proxy.listenREQUIRED = "*:554:/"

Network settings for incoming RTSP client connections in the <hostname>:<port>:<base-url> format, where:

hostname – refers to a local network name, at the IP address of which connections will be listened to. If * is specified, connections at all network addresses will be listened to, and the current hostname from hostname will be used.
port – refers to a port number that will be open for listening of connections. In specific operational systems, you should allow for not root users to use a port lower than 1024.
base-url – a base path address.

number proxy.ip = 4

An IP protocol type for incoming connections:

4 – for IP4
6 – for IP6
46 – for dual stack IP4/IP6.

number proxy.workers = 2

A number of system streams that serve the capture of camera streams. This value needs to be adjusted depending on the number of captured streams.

number proxy.poll = 256

The value that defines the maximum number of processed network events. Increase the value depending on the number of served streams. The value is specified for each system streamproxy.workers.

bool proxy.ssl = true

Specify whether to use SSL (HTTPS) for incoming connections. When false – SSL isn’t used.

JSON

{
    "proxy": {
        "listen": "*:554:/",
        "ip": 4,
        "workers": 2,
        "poll": 256,
        "ssl": true
    }
}

For details, refer to the Proxy module documentation page

Media configuration

dsn media.listenREQUIRED = "*:80:/"

Network settings for incoming HTTP/HTTPS to playback cameras in various media formats <hostname>:<port>:<base-url>, where:

hostname – refers to a local network name, at the IP address of which connections will be listened to. If * is specified, connections at all network addresses will be listened to, and the current hostname from hostname will be used.
port – refers to a port number that will be open for listening of connections. In specific operational systems, you should allow for not root users to use a port lower than 1024.
base-url – a base path address.

number media.ip = 4

An IP protocol type for incoming connections:

4 – for IP4,
6 – for IP6,
46 – for dual stack IP4/IP6.

number media.workers = 2

A number of system streams used to serve incoming connections from clients. The specified value depends on the planned load and the number of clients.

number media.poll = 64

Specify the value that defines the maximum number of processed network events.

bool media.ssl = true

Specify whether to use SSL (HTTPS) for incoming connections. When false – SSL isn’t used.

JSON

{
    "media": {
        "listen": "*:80:/",
        "ip": 4,
        "workers": 2,
        "poll": 64,
        "ssl": true
    }
}

For details, refer to the Media module documentation page.

API configuration

A token is required to access API. Tokens can be generated on a local level.

For detailed steps about how to generate a token, see the Create an access token to API documentation page.

dsn api.listenREQUIRED = "*:8554:/"

Network settings for incoming HTTP/HTTPS to call out the API methods.

<hostname>:<port>:<base-url>, where:

hostname – refers to a local network name, at the IP address of which connections will be listened to. If * is specified, connections at all network addresses will be listened to, and the current hostname from hostname will be used.

port – refers to a port number that will be open for listening of connections. In specific operational systems, you should allow for not root users to use a port lower than 1024.
base-url – a base path address.

number api.ip = 4

An IP protocol type for incoming connections:

4 – for IP4,
6 – for IP6,
46 – for dual stack IP4/IP6.

number api.workers = 2

A number of system streams that serve API requests.

number api.poll = 64

The value that defines a maximum number of processed network connections.

bool api.ssl = true

Specify whether to use SSL (HTTPS) for incoming connections. When false – SSL isn’t used.

JSON

{
    "api": {
        "listen": "*:8554:/",
        "ip": 4,
        "workers": 2,
        "poll": 64,
        "ssl": true
    }
}

For details, refer to the Mediaserver API documentation page.

Cluster configuration

dsn cluster.webhook = "http://localhost:8080/event/"

A server URL that will receive events. If it’s not specified or wrong< the webhook functionality won’t be available.

array cluster.events = ["service:up","service:down"]

An array of event identifiers that can be sent. If not specified or empty, all events are sent.The following are the event types:

Event types

service:up – indicates that the service configuration has been successfully accepted and that all services are functioning correctly.
service:down – signifies that the service has received a shutdown signal and is in the process of attempting to cease operations properly, although this event may not always be issued.
service:pulse – the service is currently operational. The event is sent every 60 seconds.
service:emergency – a critical event related to the failure of one of the services or the runtime environment occurred.
stream:create – Mediaserver created a stream. The event takes place when a stream is added.
stream:pulse – a stream is successfully captured. The event is sent with the frequency of sending the PINGcommand to the camera.
stream:reconnect – Mediaserver is attempting to reconnect to a stream.
stream:state – an event occurs when a stream status is updated.
stream:delete – an event occurs when a stream is deleted.
stream:dvr – an event with regard to ranges of a DVR stream. An event occurs when a new range appears.
stream:dvr:delete – an event on deleted DVR ranges of the stream. An event occurs when an old range is deleted.
server:capture – an event of captured server streams.
server:release – an event that signals about the end of the secondary streams capturing.
camera:create – an event on a new camera instance creation.
camera:delete – an event that occurs when a camera instance is deleted.
camera:event – an event that is generated by a camera. Foe example, an event was received via ONVIF or it was placed via Server.PostEvent.
onvif:create – an event that occurs when the ONVIF instance is created on the camera.
onvif:delete – an event that occurs when the ONVIF instance is deleted from the camera.

For details on the Weebhook mechanism, refer to the Configuration of Webhook and notification events documentation page.

JSON

{
    "cluster": {
        "webhook": "http://localhost:8080/event/",
        "events": [
            "service:up",
            "service:down"
        ]
    }
}

SSL configuration

string ssl.key = "string" – a path to the SSL key file.

string ssl.cert = "string" – a path to the SSL certificate file.

JSON

{
    "ssl": {
        "key": "string",
        "cert": "string"
    }
}

Logging configuration

The Mediaserver supports various logging options: stdout, syslog, logging to the file, remote logging.

The log section must be defined for logging configuration. If the section isn’t specified, default settings are applied – logging to stdout with the default pattern.

The following flags are supported for formatting:

%Timestamp – the message timestamp
AppId – the component identifier
Tag – the instance identifier of the component.
%Verbose – the logging level.
%Message – the message itself.
%EscMessage – the escaped message with escape characters, used for JSON patterns.

object log.stdout = {}– Configuration for logging to stdout (to screen).

object log.stdout

number log.stdout.verbose = 3

This sets the logging level for the server status. Logging levels are defined from 0 to 7.

Level 7 outputs detailed information, but it can consume more logging space and potentially slow down performance.

string log.stdout.tag = "media-server"

The global tag for logging.

string log.stdout.pattern = "[%Timestamp] %Message"

The logging pattern.

object log.file = {}– the configuration for logging to a file

object log.file

number log.file.verbose = 3

The logging level for the server status

string log.file.tag = "media-server"

The global tag for logging.

string log.file.pattern = "[%Timestamp] %Message"

The logging pattern.

string log.file.path = "/tmp/test.log"

The path to the log file.

number log.file.rotate = 8192

The bytes to trigger the file rotation.

number log.file.number = 3

A number of log files.

object log.remote = {}– the configuration for remote logging

object log.remote

string log.remote.tag = "media-server"

The global tag for logging.

number log.remote.verbose = 3

The logging level.

string log.remote.pattern = "{\"tag\":\"%Tag\",\"verbose\":\"%Verbose\",\"timestamp\":\"%Timestamp\",\"app_id\":\"%AppId\",\"message\":\"%EscMessage\"}"

The pattern for logging.

url log.remote.path = "udp://localhost:8109"

The address of the remote logger for sending messages.

object log.syslog = {}– the configuration for logging to syslog (the system log)

object log.syslog

number log.syslog.verbose = 3

The logging level for the server status.

string log.syslog.tag = "media-server"

The global tag for logging.

string log.syslog.pattern = "[%Timestamp] %Message"

The pattern for logging.

string log.syslog.facility = "local0"

JSON

{
    "log": {
        "stdout": {
            "verbose": 3,
            "tag": "media-server",
            "pattern": "[%Timestamp] %Message"
        },
        "file": {
            "verbose": 3,
            "tag": "media-server",
            "pattern": "[%Timestamp] %Message",
            "path": "/tmp/test.log",
            "rotate": 8192,
            "number": 3
        },
        "remote": {
            "tag": "media-server",
            "verbose": 3,
            "pattern": "{\"tag\":\"%Tag\",\"verbose\":\"%Verbose\",\"timestamp\":\"%Timestamp\",\"app_id\":\"%AppId\",\"message\":\"%EscMessage\"}",
            "path": "udp://localhost:8109"
        },
        "syslog": {
            "verbose": 3,
            "tag": "media-server",
            "pattern": "[%Timestamp] %Message",
            "facility": "local0"
        }
    }
}

Additional parameters for configuration

url streams = "./cameras.json"

The path to the file location that contains the configurations of the captured streams. This parameter overrides the -s parameter of the service startup command line. The source can be designated as either a local file path or a URL, which is expected to return the list of streams along with their respective configurations.

url licenseREQUIRED = "url"

Specifies the location of the license file: URL or a local file.

string secretREQUIRED = "string"

A secret value that is used to generate authorization tokens to view and access API. Tokens generated with the same secret will be accepted on all servers.

JSON

{
    "streams": "./cameras.json",
    "license": "url",
    "secret": "string"
}

Configuration of a virtual storage device

Mediaserver supports virtual storage devices for DVR. To configure a virtual device, define a storage section in your Mediaserver configuration file. Once defined, you can specify this section in the recording and storage path for your DVR. If no storage section is specified, the path defined in the stream configuration will be used as the recording directory. If no storage section is defined, a default virtual storage device with the local driver type will be created.

enum storage.driverREQUIRED = "local"

The driver for the virtual storage device:

dvrfs – a type of the storage device.
local – use directories for storing and recording the archive.

object storage.volume = {}

Is used when driver dvrfs is specified

object storage.volume

string storage.volume.name = "string"

A virtual mount point for the file system (neither devices nor a directory are created). The name can be arbitrary (no spaces, special characters (a-z, A-Z, 0-9,-_.). The name must be specified as a parameter in dvr.location. For details, refer to the Add a stream documentation section.

string storage.volume.option = "string"

Additional option dvrfs. disable-root-write – this option indicates that the root file system cannot be used for DVR recording. If the physical device is unmounted, this option will prevent the root file system from running out of space.

object storage.volume.bucket = {}

An object that contains a mount point of a physical device as a key and the mount point parameters as a value.

mixed storage.volume.bucket.mountpoint

Specifies the mount point.

bytes storage.volume.bucket.mountpoint.capacity = "bytes"

Defines the maximum storage space used. It is used in a special edition, with role determining the purpose of this disk.

enum storage.volume.bucket.mountpoint.role = "data"

A type that defines the purpose of the disk usage. By default, set as data and will be used for DVR storage. recovery – for storing archive recovery information in case of physical media failure.

JSON

{
    "storage": {
        "driver": "local",
        "volume": {
            "name": "string",
            "option": "string",
            "bucket": {
                "mountpoint": {
                    "capacity": "bytes",
                    "role": "data"
                }
            }
        }
    }
}

Each mount point is checked for existence. If the mount point (directory) doesn’t exist, it won't be created – this prevents accidental writing to the root file system.

For each mount point, the writing capability is determined (filesystem status: rw, ro), as well as the sufficiency of permissions for writing and reading. If writing is not possible, the mount point is marked as "read-only" but is not excluded from the bucket.

After configuration, the storage device for the DVR of each stream can be specified using a device like /bucket0.