CLI (Command Line Interface)

Using the CLI

Each binary within MistServer has its dedicated task, which you can usually guess once you understand the naming scheme.

• MistController: The main controlling binary that can open/close the other ones.
• MistIn*: Stream/file inputs for creating streams within MistServer, file and pull input.
• MistOut*: Streams with outgoing connections, this means viewers and live inputs.
• MistProc*: Process binaries made to manipulate/change streaming data.
• MistUtil*: Utility processes, helps with setup or debugging.
• MistAnalyser*: Analysers, analyse stream validity or reconstruct live streams to easier to use files.
• MistSession: Starts a session within MistServer, generally ran by other processes to keep an accurate count of inputs, outputs and viewers.

With the exception of MistSession you can run any of these binaries in the cli to perform their corresponding task. Typically users will have an easier time allowing MistController to spawn every binary, however running one yourself can prove invaluable when debugging issues.

What are Commandline parameters?

Commandline parameters allow you to change defaults for MistServer such as which port should be used for the API and interface, but also setting up the default log level and specific log locations. In general all options that can only be set up when booting MistServer go here.

Environment variables

These are variables that impact the inner workings of MistServer and can be set to specify certain behaviours. For example disabling "angel processes" who handle crash recovery for processes or disabling the session system while debugging to prevent time-outs.

List of Environment variables

Variable	Information
ATHEIST	Do not spawn angel processes if this environment variable exists.
NOFORK	equivalent to ATHEIST, but only works for MistIn— processes (still works for backward compatibility reasons)
MIST_CONTROL	Set by the controller to indicate that the logs are being handled by the parent process. All non-controller processes obey this variable and will spawn a log parser process if unset.
NOSESS	Do not spawn a session for connections made.
MIST_COLOR	If set forces color to be enabled in log output (enabled by default if standard output is a terminal, disabled otherwise).
MIST_LOG_SYSTEMD	If set log output is in systemd compatible format.
MIST_COLOR_STREAM	Sets the color code for stream names in logs, defaults to CSI 2m
MIST_COLOR_TIME	Sets the color code for date in logs, defaults to CSI 0;1;37m
MIST_COLOR_CONF	Sets the color code for log lines in the CONF category, defaults to CSI 0;1;37m
MIST_COLOR_FAIL	Sets the color code for log lines in the FAIL category, defaults to CSI 0;1;31m
MIST_COLOR_ERROR	Sets the color code for log lines in the ERROR category, defaults to CSI 0;31m
MIST_COLOR_WARN	Sets the color code for log lines in the WARN category, defaults to CSI 0;1;33m
MIST_COLOR_INFO	Sets the color code for log lines in the INFO category, defaults to CSI 0;36m
MIST_COLOR_END	Sets the color code for ending a log line, resetting the color for the next line, defaults to CSI 0m
TMP, TEMP, TMPDIR	These are checked in order, the first that is set will be used as temporary directory for MistServer.
S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY	These can be set to S3 credentials and will be used if no credentials are provided in the URL itself.
http_proxy	Proxy server used for outgoing HTTP requests

List of commandline options

For an up to date list we recommend running the binary you plan to use with the --help flag, as that will always give you the most up to date information.

MistController cli options	Information
--accesslog, -A	(string) Where to write the access log. If set to 'LOG' (the default), writes to wherever the log is written to. If empty, access logging is turned off. Otherwise, writes to the given filename.
--account, -a	(string) A username:password string to create a new account or overwrite an existing one.
--config, -c	(string) Specify a config file other than default.
--configrw, -C	(string) If 'r', read config changes from disk. If 'w', writes them to disk after 60 seconds of no changes. If 'rw', does both (default). In all other cases does neither.
--debug, -g	(integer) The debug level at which messages need to be printed, 0-10.
--help, -h	Display usage and version information, then exit.
--interface, -i	(string) Interface address to listen on, or 0.0.0.0 for all available interfaces.
--logfile, -L	(string) Redirect all standard output to a log file, provided with an argument.
--port, -p	(integer) TCP port to listen on.
--prometheus, -S	(string) If set, allows collecting of Prometheus-style stats on the given path over the API port.
--update, -D	Check for and install updates before starting.
--uplink, -U	Depricated option: (string) MistSteward uplink host and port.
--uplink-name, -N	Depricated option: (string) MistSteward uplink username.
--uplink-pass, -P	Depricated option: (string) MistSteward uplink password.
--username, -u	(string) Username to transfer privileges to, default is root.
--version, -v	Display library and application version, then exit.

Example cli usages

Below are various examples of running MistServer binaries in the cli. More detailed explanations are planned in Chapter 03 Core concepts. Which will be added at a later date.

MistController

There's a few reasons to boot the MistController manually, one would be to try out MistServer without doing a full install. Others would be to temporary boot MistServer in a diferent mode to allow a change. When debugging certain issues it might be a good idea to close down the MistServer service and boot up a MistController manually with a higher debug level, for example:

MistController -c /etc/mistserver.conf -g 4

Other reasons could be resetting the login information by re-creating the account through the -a parameter:

MistController -c /etc/mistserver.conf -a account:password

MistIn*

Almost every MistIn* would allow you to create a temporary input through:

MistIn* -s streamname url

For example, setting up an SRT caller to pull in a stream:

MistInTSSRT -s example srt://example:9876

Streams without any configuration will appear highlighted with blue within your interface & show up in the active_streams api call.

MistOut*

MistOut* can be used to start an output/push or to set up a listening socket for certain protocols such as RTMP, RTSP, WebRTC, SRT, HTTP, HTTPS and RIST. Starting a push can be quite easy:

MistOutRTMP -s example rtmp://example/live/example

The above would take the stream example and push it towards rtmp://example/live/example. While you could also open up a listening socket through:

MistOutRTMP --port 9876 -g 4

Which will allow users to push RTMP towards port 9876 with more detailed debugging information than default while this is active.

MistProc*

MistProcesses can be ran by hand as long as you pass the configuration and don't forget to add a sink and a source stream, however these are generally easier ran through the API. For example:

'{"codec":"PCM","exit_unmask":0,"inconsequential":0,"process":"AV","restart_type":"fixed","source":"example","tags_inhibit":null,"sink":"example"}'

The above would grab the audio from stream "example", pass it to the MistProcAV, generate PCM audio and put it back in the stream "example".

MistUtil*

These perform several side or debug tasks. So they're harder to define through a single definition. Three important ones are:

• MistUtilNuke: Forcefully close all connections & reset the status of the given stream name
• MistUtilRAX: Allows for debugging & analysing shared memory
• MistUtilCertbot: Set up HTTPS through Certbot if installed on the system (Linux only).

Forcefully closing stream "example":

MistUtilNuke example

Viewing stream "example" metadata information:

MistUtilRAX MstMetaexample

MistAnalyser*

These allow you to analyse the stream data of many of the inputs of MistServer or in some cases such as for HLS or RTMP convert a (live) stream into an easier to use on demand file. Many of these are quite specific so we recommend reading up on their specific pages.

Analysing an MP4:

MistAnalyserMP4 /media/example.mp4

Combining an HLS segmented playlist into one file:

MistAnalyserHLS http://example/index.m3u8 -R example.ts