Configuration and Command Line Options
Configuring and running the server.
The cmaf-ingest server has both auto-configured and manually configured channels.
The channels are automatically configured by the server when the server receives
input streams and the channels name is not defined in the disabled channels list.
If a channel is auto-configured, it will use the default user and password settings.
The ew-cmaf-ingest manual configuration parameters can be specified in the following ways:
- On the command-line
- In the configuration file (when specified by the command-line)
- Via REST API
They take precedence in the above order, i.e. a command-line value will override
other values.
Command Line Options
All command line parameters and environment variables can be seen by running:
ew-cmaf-ingest -h
....
Run as: ew-cmaf-ingest options with options:
-certpath string
Path to TLS certificate file (for HTTPS). Use domains instead if possible
-config string
Config file with channel-specific settings
-configport int
Configuration port (default 5034)
-domains string
One or more DNS domains (comma-separated) for auto certificate from Let's Encrypt
-fileserverpath string
HTTP path for generated segments and manifests (for testing)
-keypath string
Path to TLS private key file (for HTTPS). Use domains instead if possible.
-logformat string
Format and type of log: [consolejson consolepretty journald discard] default=consolejson
-loglevel string
Initial logging level: debug, info, warn, error, fatal, panic (default "info")
-port int
HTTP receiver port (default 8080)
-porthttps int
CMAF HTTPS receiver port (default 443)
-prefix string
Prefix to remove from upload URLS (default "/upload")
-recRawNr uint
Default number of raw segments to receive and store (turns off all parsing)
-storage string
Storage root directory (default "./storage")
-tsbd uint
Default timeShiftBufferDepth in seconds (default 90)
-version
Get version
Integration with ew-cbm
ew-cmaf-ingest acts as the input source for ew-cbm (Catchup Buffer Manager, a part of SW Live Ingest), and ew-cbm,
in its turn, will be the backend of sw-repackager, from which the channels are streamed to CDN, and then, to
end user.
To make ew-cmaf-ingest channel visible with ew-cbm, -storage option in ew-cmaf-ingest configuration have to be
the same with the location that ew-cbm gets the input from. The service file of ew-cbm can be referred to get
that location (specified by argument --live-ingest-path), it is usually /mnt/ramdisk.
cat /usr/lib/systemd/system/ew-cmaf-ingest.service
...
ExecStart=/usr/bin/ew-cmaf-ingest -config /etc/edgeware/ew-cmaf-ingest/config.json -port 8080 -storage /mnt/ramdisk/
...
The next step is configuring the channel for ew-cbm to work with ew-cmaf-ingest buffer.
1 - CBM channel configuration
Setup channel configuration for ew-cbm
ew-cbm is a Catchup manager, copy segments from ramdisk to persistent storage and serve
incoming HTTP requests from Software Repackager.
confcli services.liveIngest.channels. -w
Running wizard for resource 'Channels'
<A list of channels>
Hint: Hitting return will set a value to its default.
Enter '?' to receive the help string
Running wizard for resource 'Channels'
<A list of channels>
Hint: Hitting return will set a value to its default.
Enter '?' to receive the help string
Channels <A list of channels>: [
Channel <Configuration for a single channel>: {
Channel Name (default: default): cmafingest-channel
Channel State (default: enabled): cbm-only
Catchup Location (default: ): cb1
Channel Name Alias (default: ):
Channel Template Name (default: default):
Config Id (default: 0):
Input Sources <A list of input sources>: [
Input Source <Input source configuration>: {
Backup IGMPv3 Source (default: ):
Error correction (default: off):
IGMPv3 Source (default: ):
Source (default: ):
Passphrase for SRT connection (default: ):
Tracks <A list of tracks from the channel template>: [
Track <Configuration for a single track>: {
Log Level (default: INHERIT):
Track Name (default: default):
Variant flags (default: -1):
}
Add another 'track' element to array 'tracks'? [y/N]:
]
Use As SCTE-35 Source (default: False):
}
Add another 'inputSource' element to array 'inputSources'? [y/N]:
]
Logging <Logging configuration>: {
General Log Level (default: INHERIT):
Track Log Level (default: INHERIT):
Source Log Level (default: INHERIT):
}
Nielsen Marker Tracking (default: off):
Segmentation Template Name (default: default):
}
Add another 'channel' element to array 'channels'? [y/N]:
]
Generated config:
{
"channels": [
{
"name": "cmafingest-channel",
"state": "cbm-only",
"catchupLocation": "cb1",
"alias": "",
"channelTemplate": "default",
"configId": 0,
"inputSources": [
{
"backupIgmpV3Source": "",
"errorCorrection": "off",
"igmpV3Source": "",
"source": "",
"srtPassphrase": "",
"tracks": [
{
"logLevel": "INHERIT",
"name": "default",
"variantFlags": -1
}
],
"useAsScte35Source": false
}
],
"logging": {
"general": "INHERIT",
"track": "INHERIT",
"source": "INHERIT"
},
"nielsenMarkerTracking": "off",
"segmentationTemplate": "default"
}
]
}
Merge and apply the config? [y/n]:
Only three configurations should be cared about: Channel Name (name), Channel State (state),
Catchup Location (catchupLocation), others are meaningful for ew-live-ingest, another part of SW Live Ingest,
so they should be left as default:
- Channel Name (name): have to be exactly the same with the channel
name configured in ew-hlsingest,
so that ew-cbm will know where to look for the input. - Channel State (state):
cbm-only is a must. - Catchup Location (catchupLocation) (optional): is the location that
ew-cbm will write the catch up buffer to,
please refer to ew-cbm documentation to know how to configure it.
After done configuring, this command, ew-cb-media, can be used to check for the running channel. If the
channel name appears in the output of that command and the duration of catchup buffer starts growing
(repeat the command the see if the channel is growing, or just use watch ew-cb-media), then the live content
can now be delivered through ew-cbm to repackager and beyond.
2 - Channel REST API v1
Reference for the channel schedule API
The following is a rendering of the OpenAPI for the channels and schedules
of ESB3034 using swagger. This page does not have
a backend server, so it cannot be run interactively.
However, an interactive Swagger API page is available
directly at the ew-cmaf-ingest server at <server>:<port>/swagger/.
If the -configport option is not specified, the default value 5034 is used.
3 - Configuration File
Startup configuration for configuring ew-cmaf-ingest
When starting the ew-cmaf-ingest service, a configuration file may be provided. This file enables
starting ew-cmaf-ingest service with predefined general configuration and channels information.
These items can also be added and updated via the manually configured REST API
when the service is running.
If a path to a configuration is set,
any change of the configuration, such as auto-configured channels or manual configuration changes,
results in the complete configuration information being written to a file at that path.
On the restart, an existing file at this path is used to restore the last dynamic configuration.
If a configuration file does not exist at the specified path, a new file with empty content will
be created. If the file is empty, the current configuration will be written to it.
JSON Schema for configuration file
The JSON schema below provides a description of the schema and the parameters
that applies to configuration file for ew-cmaf-ingest.
{
"defaultUser": {
"description": "Default username for all channels",
"type": "string"
},
"defaultPassword": {
"description": "Default password for all channels",
"type": "string"
},
"autoConfig": {
"description": "AutoConfig is a flag that enables or disables automatic configuration. Default is true",
"type": "boolean"
},
"Channels": {
"description": "Channels for ew-cmaf-ingest at startup",
"type": "array",
"items": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"description": "Unique channel name",
"type": "string"
},
"startNr": {
"description": "The start number for the first segment. Default is 0",
"type": "integer"
},
"authUser": {
"description": "The username for the channel to authenticate. If not set, the default username will be used",
"type": "string"
},
"authPassword": {
"description": "The password for the channel to authenticate. If not set, the default password will be used",
"type": "string"
},
"timeShiftBufferDepthS": {
"description": "The timeShiftBufferDepth in seconds for circularBuffer. Default is 90s",
"type": "integer"
},
"receiveNrRawSegments": {
"description": "The number of raw segments to receive before starting to process. Default is 0",
"type": "integer"
},
"reps": {
"description": "The Representations for the channel",
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"description": "Unique representation name",
"type": "string"
},
"language": {
"description": "The language for the representation",
"type": "string"
},
"role": {
"description": "The role for the representation",
"type": "string"
},
"displayName": {
"description": "The display name for the representation",
"type": "string"
},
"bitrate": {
"description": "The bitrate for the representation",
"type": "integer"
},
"ignore": {
"description": "The Ignore means that the representation should be ignored",
"type": "boolean"
}
}
}
},
"ignore": {
"description": "The Ignore means that the channel should be ignored",
"type": "boolean"
}
}
}
},
"DisabledChannels" {
"description": "DisabledChannels is a list of channel names that should be disabled or blocked",
"type": "array"
}
}
Example configuration
An example configuration file for two channels where all assets have relative
paths may look like:
{
"defaultUser": "admin",
"defaultPassword": "password123",
"autoConfig": true,
"Channels": [
{
"name": "channel_test_1",
"startNr": 0,
"authUser": "admin",
"authPassword": "password123",
"timeShiftBufferDepthS": 90,
"receiveNrRawSegments": 0,
"reps": [
{
"name": "track1",
"language": "en",
"role": "main",
"displayName": "track1",
"bitrate": 1000000,
"ignore": false
},
{
"name": "track2",
"language": "vie",
"role": "alternative",
"displayName": "track2",
"bitrate": 16000000,
"ignore": true
}
],
"ignore": false
},
{
"name": "channel_test_2",
"startNr": 1,
"authUser": "admin",
"authPassword": "password123",
"timeShiftBufferDepthS": 90,
"receiveNrRawSegments": 0,
"reps": [
{
"name": "track1",
"language": "swe",
"role": "description",
"displayName": "track1",
"bitrate": 8000000,
"ignore": false
}
],
"ignore": true
}
]
"DisabledChannels": [
"channel_test_2",
"channel_test_3"
]
}