EMS Configuration File

config.lua

The EMS configuration file, config.lua, is a hierarchical data structure of assignments (key names with values). It is sent as a parameter when running the EvoStream server. The format is as follows:

<keyname>= <value>

where <value> could be any of the following types:

• string = series of alpha numeric characters enclosed in double quotes
• number = digits (without double quotes around it)
• array = list of values separated by comma and is grouped by braces {}
• aliases = {“flvplayback1”, “vod1”, “live”}

Example:

aliases = {“flvplayback1”, “vod1”, “live”}

object = list of assignments enclosed by braces {}

Example:

configurations =
{
    daemon = "true",
    pathSeparator = "/",
    logAppenders = {...},
    applications = {...}
}

In the example above, configurations has a value of type object. An object is a group of data inside braces ({ }) which may contains several assignments (<keynames> = <values>) separated by commas (,) and in turn could be another object. The assignments in the example above are daemon, pathSeparator, logAppenders, and applications. Notice that the values of logAppenders and applications could be another object or array recursively.

Contents

configuration = 
{
	daemon = false,
	pathSeparator = “/”,
	logAppenders = 
	{
		-- content removed for clarity
	},
	applications = 
	{
		-- content removed for clarity
	}
}}

configuration – This is the entire structure for all configuration needed by the EMS Server.

Configuration Structure Table:

When the server starts, the following sequence of operations is performed:

The configuration file is loaded. Part of the loading process, is the verification,. If if something is wrong with the syntax, please try this:

• For Linux Package:

     /usr/bin/evostreamms –use-implicit-console-appender /etc/evostreamms/config.lua
  

• For Linux Archive:

     cd EMS_INSTALL_DIRECTORY
     ./evostreamms --use-implicit-console-appender ../config/config.lua
  

• For Windows:

     cd EMS_INSTALL_DIRECTORY
     evostreamms --use-implicit-console-appender config\config.lua
  

Note: EMS_INSTALL_DIRECTORY is the bin directory within the EvoStream Media Server Archive directory.

1. The “daemon” value is read. The server now will either fork to become daemon or continue as is in console mode.
2. The “logAppenders” value is read. This is where all log appenders are configured and brought up to running state. Depending on the collection of your log appenders, you may (not) see further log messages.
3. The “applications” value is taken into consideration. Up until now, the server doesn’t do much. After this stage completes, all the applications are fully functional and the server is online and ready to do stuff.

logAppenders

logAppenders =
{
    {
        name="console appender",
        type="coloredConsole",
        level=6
    },
    {
        name="file appender",
        type="file",
        level=6,
        fileName="../logs/evostream",
    }
}

This section contains a list of log appenders. The entire collection of appenders listed in this section is loaded inside the logger at config-time. All log messages will be than passed to all these log appenders. Depending on the log level, an appender may (or may not) log the message. “Logging” a message means “saving” it on the specified “media” (in the example below we have a console appender and a file).

logAppenders Structure Table:

Note: When daemon mode is set to true, all console appenders will be ignored. (Read the explanation for daemon setting above).

applications

applications =
{
    rootDirectory = "./",
    {
        name="evostreamms",
        -- settings for evostreamms
    },
    {
        name="anotherApplication",
        -- settings for anotherApplication
    },
}

This section is where all the applications inside the server are placed. It holds the attributes of each application that the server will use to launch them. Each application may have specific attributes that it requires to execute its own functionality.

application Structure Table:

Following the rootDirectory, there is a collection of applications. Each application has its properties contained in an object. See details below.

application Definition

{
    appDir="./",
    name="evostreamms",
    description="EVOSTREAM MEDIA SERVER",
    protocol="dynamiclinklibrary",
    default=true,
    pushPullPersistenceFile="..\\config\\pushPullSetup.xml",
    authPersistenceFile="..\\config\\auth.xml",
    connectionsLimitPersistenceFile="..\\config\\connlimits.xml",
    bandwidthLimitPersistenceFile="..\\config\\bandwidthlimits.xml",
    ingestPointsPersistenceFile="..\\config\\ingestpoints.xml",
    streamsExpireTimer=10,
    rtcpDetectionInterval=15,
    hasStreamAliases=false,
    hasIngestPoints=false,
    validateHandshake=false,
    aliases={"er", "live", "vod"},
    maxRtmpOutBuffer=512*1024,
    hlsVersion=3,
    useSourcePts=false,
    enableCheckBandwidth=true,
    vodRedirectRtmpIp="",

This is where the settings of an application are defined. We will present only the settings common to all applications. Later on, we will also explain the settings particular to certain applications.

application Definition Table:

media

{
mediaStorage = {
	recordedStreamsStorage="../media",
	{
	description="Default media storage",
	mediaFolder="../media",
	},

This is where the settings of media folder defined. There are several uses of the media folder:

• Storage of vod file that is used for pullStream
• Location of the created file using generateLazyPull command
• Storage of recorded streams using record command

media Structure Table:

acceptors

The “acceptors” block is found within the “applications” section named “evostreamms” in the configuration file. Each acceptor protocol used by applications is defined here. Some protocols may require additional parameters.

acceptor Structure Table:

The following acceptor types are supported by EMS:

acceptor Protocol Table:

Protocol Group Table:

autoHLS/HDS/DASH/MSS

Within the “evostreamms” application section of the config.lua file, you will need to uncomment out the autoHLS group. (To uncomment it remove the “–[[” and “]]–” strings).

autoDASH=
    targetFolder= "..\\evo-webroot",
},
autoHLS=
{
    targetFolder= "..\\evo-webroot",
},
autoHDS=
{
    targetFolder= "..\\evo-webroot",
},
autoMSS=
{
    targetFolder= "..\\evo-webroot",
},

The autoHLS/HDS/DASH/MSS configuration group defines the parameter settings that will be used when the createHLS/HDS/DASH/MSSStream is automatically called on stream creation. Since targetFolder is the only mandatory field in create stream, that value MUST be specified in the autoHLS section. All other parameters can be specified if you want to override the default values.

authentication

The “authentication” block is found within the “applications” section named “evostreamms” in the configuration file. Authentication settings for RTMP and RTSP protocols are defined separately. For RTMP, another file, auth.xml, is required to enable authentication. In addition, a users file, typically named users.lua, provides the user names and passwords.

authentication Structure Table:

authentication=
{
    rtmp=
    {
        type="adobe",
        encoderAgents=
        {
            "FMLE/3.0 (compatible; FMSc/1.0)",
            "Wirecast/FM 1.0 (compatible; FMSc/1.0)",
            "EvoStream Media Server (www.evostream.com)"
        },
        usersFile="..\\config\\users.lua"
    },
    rtsp=
    {
        usersFile="..\\config\\users.lua",
        --authenticatePlay=false,
    }
},

Notes:

1. Authentication is disabled if the “authentication” block in the “config.lua” file is missing or incomplete. For RTMP protocol, authentication is disabled if the “auth.xml” file is missing or contains a “false” setting. For RTSP protocol, authentication is disabled if “authenticatePlay” in the “rtsp” block is omitted or set to “false”.

2. Scripts are available for creating certificates and keys for EMS. Please refer to our GitHub files here for details.

eventLogger

To enable Event Notifications you will need to enable/uncomment the eventLogger section of the config.lua file. Comments in LUA are specified by either a “–” for a single line, or denoted by a “–[[” to start a comment block and a “]]–” to end a comment block. By default the eventLogger section is commented out using the block style comments, so you will need to remove both the –[[and]]–strings.

The configuration entry must be constructed as follows:

eventLogger=
{
    sinks=
    {
        type="sink1_type",
        -- property1 of sink1
        -- property2 of sink1
    },
    enabledEvents=
    {
        "inStreamCreated",
        "inStreamClosed",
    }
},

The enabledEvents parameter is optional and allows you to specify only the events which you wish to receive. If the enabledEvents section is not specified, all events will be generated.

All event types are listed below.

Stream Events Table:

Adaptive Streaming/File-based Streaming Events Table:

API Based Events Table

Connection Based Events Table

Application Based Events Table

Web Server Events Table

Event Sinks

There are two main types of event sinks:

1. File Event Sink – Event details are written to a log file located relative to the current directory. The log file is overwritten each time the EMS starts up.

type="file",
filename="log.txt",
format="text",
customData="my custom data"

File sink configuration:

The format can be one of the following types:

• “text” (plain text)

• “xml”

• “json”

• “w3c”

  A typical configuration of a file sink follows:

    eventLogger=
    {
        sinks=
        {
            {
                type="file",
                filename="../logs/events.txt",
                --format="text",
                --format="xml",
                --format="json",
                format="w3c",
                timestamp=true,
                appendTimestamp=true,
                appendInstance=true,
                fileChunkLength=43200, -- 12 hours (in seconds)
                fileChunkTime="18:00:00",
                enabledEvents=
                {
                    "inStreamCreated",
                    "outStreamCreated",
                    "streamCreated",
                    -- content removed for clarity
                },
                {
                    -- content removed for clarity
                },
            },
        },
    },
  

File Sink Structure Table:

As indicated above, the name of the file can be set using a number of options. For example,

filename = "/var/evostreamms/logs/streams"
appendTimestamp = true
appendInstance = true

The log file would be /var/evostreamms/logs/streams_0237_20140311_183046.txt.

2. RPC (Remote Procedure Calls) Event Sink – Event details are transmitted to a remote host via HTTP POST. The EMS will ignore any response from the remote host.

RPC sink configuration:

type="RPC",
url="http://192.168.1.5:5555/something/service",
serializerType="JSON",
customData="my custom data"

The url field specifies the destination which will be accepting the HTTP POST event notifications..

The serializer type can be one of the following formats:

• JSON

Format of JSON POST:

{"payload":{"creationTimestamp":1349335053486.4370,"name":"","queryTimestamp":1349335053487.4370,"type":"NR","uniqueId":1,"upTime":1.0000},"type":"streamCreated"}

• XML

Format of XML POST:

<?xml version="1.0" ?>
<MAP isArray="false" name="">
    <MAP isArray="false" name="payload">
        <DOUBLE name="creationTimestamp">1349335287346.813</DOUBLE>
        <STR name="name"></STR>
        <DOUBLE name="queryTimestamp">1349335287346.813</DOUBLE>
        <STR name="type">NR</STR>
        <UINT64 name="uniqueId">1</UINT64>
        <DOUBLE name="upTime">0.000</DOUBLE>
    </MAP>
<STR name="type">streamCreated</STR>
</MAP>

• XMLRPC

Format of XMLRPC POST: (indented for clarity)

<?xml version="1.0"?>
<methodCall>
    <methodName>event.Log</methodName>
    <params>
        <param>
            <value>
                <struct>
                    <member>
                        <name>payload</name>
                        <value>
                            <struct>
                            <member>
                                <name>creationTimestamp</name>
                                <value><double>0.000000</double></value>
                            </member>
                            <!-- contents removed for clarity -->
                            </struct>
                        </value>
                    </member>
                    <member>
                        <name>type</name>
                        <value><string>streamCreated</string></value>
                    </member>
                </struct>
            </value>
        </param>
    </params>
</methodCall>

The customData parameter for both File and RPC Event Sinks can be optionally used to extra data to each event for that sink. This could be used to identify the particular EMS instance which is generating the event, return a particular ID or Key which is pertinent to your handling of the event, or anything really! A customData parameter can be a simple sting value or a complex LUA object.

If a customData parameter is not specified for a node, the value of the parent eventLogger customData node will be used. If that is also not specified, the value will be V_NULL.

Transcoder

Within the application section you can find the configuration for the EvoStream Transcoder. The default settings are generally going to be fine for all applications, but under certain circumstances they may need to be adjusted. The transcoder section looks like the following:

transcoder = {
    scriptPath="..\\emsTranscoder.bat",
    srcUriPrefix="rtsp://localhost:5544/",
    dstUriPrefix="-f flv tcp://localhost:6666/"
},

The srcUriPrefix tells the transcoder how to get the stream from the EMS. The dstUriPrefix tells the transcoder how to push the stream back to the EMS. The ports used in these two values must match the acceptors the EMS is actively listening on. By default this is i5544 for RTSP and 6666 for liveFLV.

Transcoder Structure Table:

drm

Also in the application section of the config.lua file, the DRM section provides the configuration values for any DRM that needs to be activated. This section is commented out by default (wrapped in “–[[” and “]]–”). It must be un-commented-out before DRM will be activated.

drm={
    type="verimatrix",
    requestTimer=1,
    reserveKeys=10,
    reserveIds=10,
    -- urlPrefix="http://server1.evostream1.com:12684/CAB/keyfile"
    urlPrefix="http://vcas3multicas1.verimatrix.com:12684/CAB/keyfile"
},

drm Structure Table: