diff --git a/daemon/rtpengine.8.ronn b/daemon/rtpengine.8.ronn deleted file mode 120000 index 281c18e44..000000000 --- a/daemon/rtpengine.8.ronn +++ /dev/null @@ -1 +0,0 @@ -../docs/rtpengine.md \ No newline at end of file diff --git a/debian/control b/debian/control index 50ce11c1e..f3b78c3ed 100644 --- a/debian/control +++ b/debian/control @@ -44,10 +44,9 @@ Build-Depends: libxmlrpc-core-c3-dev (>= 1.16.07), libxtables-dev (>= 1.4) | iptables-dev (>= 1.4), markdown, + pandoc, python3, python3-websockets, - ronn, - ruby-ronn, zlib1g-dev, Testsuite: autopkgtest-pkg-dkms diff --git a/docs/index.rst b/docs/index.rst index ded18d34f..076c01300 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -14,8 +14,8 @@ Currently the only supported platform is GNU/Linux. :maxdepth: 4 overview - rtpengine man - rtpengine-recording man + rtpengine + rtpengine-recording architecture tests troubleshooting diff --git a/docs/rtpengine-recording.md b/docs/rtpengine-recording.md index 43d29687c..2d25a7799 100644 --- a/docs/rtpengine-recording.md +++ b/docs/rtpengine-recording.md @@ -1,9 +1,18 @@ -rtpengine-recording(8) - media recording daemon for Sipwise rtpengine -========================================== +--- +title: rtpengine-recording +section: 8 +header: NGCP rtpengine-recording +--- + +# rtpengine-recording(8) manual page + +## NAME + +rtpengine-recording - media recording daemon for Sipwise rtpengine ## SYNOPSIS -**rtpengine-recording** \[_option_...\] +__rtpengine-recording__ \[*option*...\] ## DESCRIPTION @@ -14,318 +23,318 @@ packets and decodes them into an audio format that can be listened to. ## OPTIONS All options can (and should) be provided in a config file instead of -at the command line. See the **--config-file** option below for details. +at the command line. See the __\-\-config-file__ option below for details. If no options are given, then default values are assumed, which should be sufficient for a standard installation of rtpengine. -- **--help** +- __\-\-help__ Print the usage information. -- **-v**, **--version** +- __-v__, __\-\-version__ - If called with this option, the **rtpengine-recording** daemon will simply print + If called with this option, the __rtpengine-recording__ daemon will simply print its version number and exit. -- **--config-file=**_FILE_ +- __\-\-config-file=__*FILE* Specifies the location of a config file to be used. The config file is an - _.ini_ style config file, with all command-line options listed here also + *.ini* style config file, with all command-line options listed here also being valid options in the config file. For all command-line options, the long name version instead of the - single-character version (e.g. **table** instead of just **t**) must be + single-character version (e.g. __table__ instead of just __t__) must be used in the config file. - For boolean options that are either present or not (e.g. **output-mixed**), a - boolean value (either **true** or **false**) must be used in the config file. + For boolean options that are either present or not (e.g. __output-mixed__), a + boolean value (either __true__ or __false__) must be used in the config file. If an option is given in both the config file and at the command line, the command-line value overrides the value from the config file. - As a special value, **none** can be passed here to suppress loading of the + As a special value, __none__ can be passed here to suppress loading of the default config file. -- **--config-section=**_STRING_ +- __\-\-config-section=__*STRING* - Specifies the _.ini_ style section to be used in the config file. + Specifies the *.ini* style section to be used in the config file. Multiple sections can be present in the config file, but only one can be used at a time. - The default value is **rtpengine-recording**. + The default value is __rtpengine-recording__. A config file section is started in the config file using square brackets - (e.g. **\[rtpengine-recording\]**). + (e.g. __\[rtpengine-recording\]__). -- **-L**, **--log-level=**_INT_ +- __-L__, __\-\-log-level=__*INT* Takes an integer as argument and controls the highest log level which will be sent to syslog. The log levels correspond to the ones found in the [syslog(3)](http://man.he.net/man3/syslog) man page. - The default value is **6**, equivalent to LOG\_INFO. - The highest possible value is **7** (LOG\_DEBUG) which will log everything. + The default value is __6__, equivalent to LOG\_INFO. + The highest possible value is __7__ (LOG\_DEBUG) which will log everything. -- **--log-facilty=****daemon**\|**local0**\|...\|**local7**\|... +- __\-\-log-facilty=daemon__\|__local0__\|...\|__local7__\|... The syslog facilty to use when sending log messages to the syslog daemon. - Defaults to **daemon**. + Defaults to __daemon__. -- **-E**, **--log-stderr** +- __-E__, __\-\-log-stderr__ Log to stderr instead of syslog. - Only useful in combination with **--foreground**. + Only useful in combination with __\-\-foreground__. -- **--split-logs** +- __\-\-split-logs__ Split multi-line log messages into individual log messages so that each line receives its own log line prefix. -- **--no-log-timestamps** +- __\-\-no-log-timestamps__ Don't add timestamps to log lines written to stderr. - Only useful in combination with **--log-stderr**. + Only useful in combination with __\-\-log-stderr__. -- **--log-mark-prefix=**_STRING_ +- __\-\-log-mark-prefix=__*STRING* Prefix to be added to particular data fields in log files that are deemed sensitive and/or private information. Defaults to an empty string. -- **--log-mark-suffix=**_STRING_ +- __\-\-log-mark-suffix=__*STRING* Suffix to be added to particular data fields in log files that are deemed sensitive and/or private information. Defaults to an empty string. -- **-p**, **--pidfile=**_FILE_ +- __-p__, __\-\-pidfile=__*FILE* Specifies a path and file name to write the daemon's PID number to. -- **-f**, **--foreground** +- __-f__, __\-\-foreground__ If given, prevents the daemon from daemonizing, meaning it will stay in the foreground. Useful for debugging. -- **-t**, **--table=**_INT_ +- __-t__, __\-\-table=__*INT* - Takes an integer argument. The value must match the **table** option given to - the **rtpengine** media proxy to use for in-kernel packet forwarding. - Defaults to **0** if not specified. + Takes an integer argument. The value must match the __table__ option given to + the __rtpengine__ media proxy to use for in-kernel packet forwarding. + Defaults to __0__ if not specified. -- **--spool-dir=**_PATH_ +- __\-\-spool-dir=__*PATH* - The path given here must match the **recording-dir** path given to the - **rtpengine** media proxy. Defaults to `/var/spool/rtpengine`. The path must - reside on a file system that supports the **inotify** mechanism. + The path given here must match the __recording-dir__ path given to the + __rtpengine__ media proxy. Defaults to `/var/spool/rtpengine`. The path must + reside on a file system that supports the __inotify__ mechanism. -- **--num-threads=**_INT_ +- __\-\-num-threads=__*INT* How many worker threads to launch. Defaults to the number of CPU cores - available, or **8** if there are fewer than that or if the number is not + available, or __8__ if there are fewer than that or if the number is not known. -- **--thread-stack=**_INT_ +- __\-\-thread-stack=__*INT* Set the stack size of each thread to the value given in kB. Defaults to 2048 kB. Can be set to -1 to leave the default provided by the OS unchanged. -- **--evs-lib-path=**_FILE_ +- __\-\-evs-lib-path=__*FILE* - Points to the shared object file (**.so**) containing the reference + Points to the shared object file (__.so__) containing the reference implementation for the EVS codec. See the `README` for more details. -- **--output-storage=****file**\|**db**\|**both** +- __\-\-output-storage=file__\|__db__\|__both__ Where to store media files. By default, media files are written directly to the - file system (see **output-dir**). They can also be stored as a **BLOB** in a + file system (see __output-dir__). They can also be stored as a __BLOB__ in a MySQL database, either instead of, or in addition to, being written to the file system. -- **--output-dir=**_PATH_ +- __\-\-output-dir=__*PATH* Path for media files to be written to if file output is enabled. Defaults to `/var/lib/rtpengine-recording`. The path must not be the same as used for the - **spool-dir**. + __spool-dir__. -- **--output-pattern=**_STRING_ +- __\-\-output-pattern=__*STRING* File name pattern to be used for recording files. The pattern can reference sub-directories. Parent directories will be created on demand. The default - setting is **%c-%t**. + setting is __%c-%t__. - The pattern must include **printf**-style format sequences. Supported format + The pattern must include __printf__-style format sequences. Supported format sequences are: - - **%%** + - __%%__ A literal percent sign. - - **%c** + - __%c__ The call ID. It is mandatory for the output pattern to include this format sequence. - - **%t** + - __%t__ - The stream type. For **single** streams this is the SSRC written as hexadecimal; - for **mix** stream this is the string **mix**. It is mandatory for the output + The stream type. For __single__ streams this is the SSRC written as hexadecimal; + for __mix__ stream this is the string __mix__. It is mandatory for the output pattern to include this format sequence. - - **%l** + - __%l__ The label for the participating party as communicated from the controlling daemon. - - **%Y** - - **%m** - - **%d** - - **%H** - - **%M** - - **%S** + - __%Y__ + - __%m__ + - __%d__ + - __%H__ + - __%M__ + - __%S__ These format sequence reference the current system time (when the output file was created) and are the same as the format sequences supported by [date(1)](http://man.he.net/man1/date) or [strftime(3)](http://man.he.net/man3/strftime) (year, month, day, hours, minutes, and seconds, respectively). - - **%u** + - __%u__ - Microseconds, expanded to 6 digits (**000000** through **999999**). + Microseconds, expanded to 6 digits (__000000__ through __999999__). - - **%**_INT_ + - __%__*INT* References a prefix from the call ID of the given length. If this format sequence is present more than once, then the prefixes are cumulative. For - example, if the call ID is **abcdefgh** and the output pattern is configured as - **%2/%3/%c**, then the resulting output file name would be **ab/cde/abcdefgh**. + example, if the call ID is __abcdefgh__ and the output pattern is configured as + __%2/%3/%c__, then the resulting output file name would be __ab/cde/abcdefgh__. -- **--output-format=****wav**\|**mp3**\|**none** +- __\-\-output-format=wav__\|__mp3__\|__none__ File format to be used for media files that are produced. Defaults to PCM WAV (RIFF) files. Applicable for both files stored on the file system and in a - database. If **none** is selected then file output is disabled. + database. If __none__ is selected then file output is disabled. -- **--resample-to=**_INT_ +- __\-\-resample-to=__*INT* - Resample all audio to the given sample rate (e.g. **48000**). Resampling is + Resample all audio to the given sample rate (e.g. __48000__). Resampling is disabled by default, meaning that files will be written with the same sample rate as the source media. -- **--mp3-bitrate=**_INT_ +- __\-\-mp3-bitrate=__*INT* If MP3 output is selected, use the given bitrate for the MP3 encoder (e.g. - **64000**). There is no default value, so this option must be given if MP3 + __64000__). There is no default value, so this option must be given if MP3 output is selected. Note that not all bitrates are valid in combinations with all sample rates. For MP3 output it's therefore recommended to also set - **resample-to**. + __resample-to__. -- **--output-mixed** -- **--output-single** +- __\-\-output-mixed__ +- __\-\-output-single__ - Whether to produce **mixed** audio files, or **single** audio files, or both. If + Whether to produce __mixed__ audio files, or __single__ audio files, or both. If neither option is given, then by default both are enabled. If no file output is - desired, set **output-format** to **none**. + desired, set __output-format__ to __none__. - A **single** audio file contains the audio for a single RTP SSRC, which usually + A __single__ audio file contains the audio for a single RTP SSRC, which usually means an unidirectional audio stream. These are decoded directly from an RTP stream and do not take timestamping into account, meaning that gaps or pauses in the RTP stream are not reflected in the output audio file. - A **mixed** audio file consists of the first four RTP SSRC seen, mixed together + A __mixed__ audio file consists of the first four RTP SSRC seen, mixed together into a single output file, which usually means that a bidirectional audio stream is produced. Audio mixing takes RTP timestamping into account, so gaps and pauses in the RTP media are reflected in the output audio to keep the multiple audio sources in sync. -- **--mix-method=****direct**\|**channels** +- __\-\-mix-method=direct__\|__channels__ Selects a method to mix multiple audio inputs into a single output file for - **mixed** output. The default is **direct** which directly mixes all audio inputs + __mixed__ output. The default is __direct__ which directly mixes all audio inputs together, producing a mixed output file with the same format as an audio file - from a single input (**output-single**) would be. + from a single input (__output-single__) would be. - The **channels** mixing method puts each audio input into its own audio channel + The __channels__ mixing method puts each audio input into its own audio channel in the output file, therefore producing a multi-channel output file. Up to four separate RTP SSRCs are supported for a mixed output, which means that if each input is mono audio, then the mixed output file would contain 4 audio channels. This mixing method requires an output file format which supports these kinds of - multi-channel audio formats (e.g. **wav**). + multi-channel audio formats (e.g. __wav__). -- **--mix-num-inputs=**_INT_ +- __\-\-mix-num-inputs=__*INT* - Change the number of recording channel in the output file. The value is between 1 to 4 (e.g. **4**, which is also the default value). + Change the number of recording channel in the output file. The value is between 1 to 4 (e.g. __4__, which is also the default value). -- **--output-chmod=**_INT_ +- __\-\-output-chmod=__*INT* Change the file permissions of recording files to the given mode. Must be given - as an octal integer, for example **0660**. + as an octal integer, for example __0660__. -- **--output-chmod-dir=**_INT_ +- __\-\-output-chmod-dir=__*INT* Change the file permissions of recording files to the given mode. Must be given - as an octal integer, for example **0700** (which is also the default value). + as an octal integer, for example __0700__ (which is also the default value). -- **--output-chown=**_USER_\|_UID_ -- **--output-chgrp=**_GROUP_\|_GID_ +- __\-\-output-chown=__*USER*\|*UID* +- __\-\-output-chgrp=__*GROUP*\|*GID* Change the ownership of recording files. Either user/group names or numeric IDs - are supported. If the value is blank or given as **-1** then the user/group is + are supported. If the value is blank or given as __-1__ then the user/group is left unchanged. -- **--mysql-host=**_HOST_\|_IP_ -- **--mysql-port=**_INT_ -- **--mysql-user=**_USERNAME_ -- **--mysql-pass=**_PASSWORD_ -- **--mysql-db=**_STRING_ +- __\-\-mysql-host=__*HOST*\|*IP* +- __\-\-mysql-port=__*INT* +- __\-\-mysql-user=__*USERNAME* +- __\-\-mysql-pass=__*PASSWORD* +- __\-\-mysql-db=__*STRING* Configuration for a MySQL storage backend. Details about calls and media files that are produced are stored into the database. Optionally the media files - themselves can be stored as well (see **output-storage**). + themselves can be stored as well (see __output-storage__). -- **--forward-to=**_PATH_ +- __\-\-forward-to=__*PATH* Forward raw RTP packets to a Unix socket. Disabled by default. -- **--tls-send-to=**_IP_**:**_PORT_ -- **--tls-resample=**_INT_ +- __\-\-tls-send-to=__*IP*:*PORT* +- __\-\-tls-resample=__*INT* Send decoded audio over a TCP TLS connection to the specified destination. Audio is sent as raw mono 16-bit PCM in the given sample rate. -- **--notify-uri=**_URI_ +- __\-\-notify-uri=__*URI* Enable HTTP notification about finished recordings to the specified URI, which must be an HTTP or HTTPS URI. Information about the finished recording is - provided via custom HTTP headers, all of which use a prefix of **X-Recording-**. + provided via custom HTTP headers, all of which use a prefix of __X-Recording-__. -- **--notify-post** +- __\-\-notify-post__ Use HTTP POST instead of GET for the HTTP notification requests. The request body is empty even if POST is used. -- **--notify-no-verify** +- __\-\-notify-no-verify__ Disable TLS peer certificate verification for HTTPS requests. -- **--notify-concurrency=**_INT_ +- __\-\-notify-concurrency=__*INT* The maximum number of HTTP requests to perform simultaneously. -- **--notify-retries=**_INT_ +- __\-\-notify-retries=__*INT* How many times to retry a failed HTTP notification before giving up. An exponential falloff time is used for each subsequent attempt, starting with 5 seconds. -- **--notify-record** +- __\-\-notify-record__ Attach recorded file to HTTP notification request. If enabled, notification - request behaves as HTTP POST (ignoring **--notify-post**). Note that this option + request behaves as HTTP POST (ignoring __\-\-notify-post__). Note that this option is incompatible with DB-only storage as no recording file exists on storage - (see **output-storage**). + (see __output-storage__). ## EXIT STATUS -- **0** +- __0__ Successful termination. -- **1** +- __1__ An error occurred. diff --git a/docs/rtpengine.md b/docs/rtpengine.md index d5f8c0f1f..e1fa9a175 100644 --- a/docs/rtpengine.md +++ b/docs/rtpengine.md @@ -1,9 +1,18 @@ -rtpengine(8) - NGCP proxy for RTP and other UDP based media traffic -========================================== +--- +title: rtpengine +section: 8 +header: NGCP rtpengine +--- + +# rtpengine(8) manual page + +## NAME + +rtpengine - NGCP proxy for RTP and other UDP based media traffic ## SYNOPSIS -**rtpengine** **--interface**=_addr_... **--listen-tcp**\|**--listen-udp**\|**--listen-ng**\|**--listen-tcp-ng**\|**--listen-http**\|**--listen-https**=_addr_... \[_option_...\] +__rtpengine__ __\-\-interface__=*addr*... __\-\-listen-tcp__\|__\-\-listen-udp__\|__\-\-listen-ng__\|__\-\-listen-tcp-ng__\|__\-\-listen-http__\|__\-\-listen-https__=*addr*... \[*option*...\] ## DESCRIPTION @@ -15,54 +24,54 @@ replacement for any of the other available RTP and media proxies. ## OPTIONS Most of these options are indeed optional, with two exceptions. It's -mandatory to specify at least one local IP address through **--interface**, -and at least one of the **--listen-**_..._ options must be given. +mandatory to specify at least one local IP address through __\-\-interface__, +and at least one of the __\-\-listen-__*...* options must be given. All options can (and should) be provided in a config file instead of -at the command line. See the **--config-file** option below for details. +at the command line. See the __\-\-config-file__ option below for details. -- **--help** +- __\-\-help__ Print the usage information. -- **-v**, **--version** +- __-v__, __\-\-version__ - If called with this option, the **rtpengine** daemon will simply print its + If called with this option, the __rtpengine__ daemon will simply print its version number and exit. -- **--codecs** +- __\-\-codecs__ Print a list of supported codecs and exit. -- **--config-file=**_FILE_ +- __\-\-config-file=__*FILE* Specifies the location of a config file to be used. The config file is an - _.ini_ style config file, with all command-line options listed here also + *.ini* style config file, with all command-line options listed here also being valid options in the config file. For all command-line options, the long name version instead of the - single-character version (e.g. **table** instead of just **t**) must be + single-character version (e.g. __table__ instead of just __t__) must be used in the config file. - For boolean options that are either present or not (e.g. **no-fallback**), a - boolean value (either **true** or **false**) must be used in the config file. + For boolean options that are either present or not (e.g. __no-fallback__), a + boolean value (either __true__ or __false__) must be used in the config file. If an option is given in both the config file and at the command line, the command-line value overrides the value from the config file. Options that can be specified multiple times on the command line must be given only once in the config file, with the multiple values separated by semicolons (see section [INTERFACES](https://metacpan.org/pod/INTERFACES) below for an example). - As a special value, **none** can be passed here to suppress loading of the + As a special value, __none__ can be passed here to suppress loading of the default config file `/etc/rtpengine/rtpengine.conf`. -- **--config-section=**_STRING_ +- __\-\-config-section=__*STRING* - Specifies the _.ini_ style section to be used in the config file. + Specifies the *.ini* style section to be used in the config file. Multiple sections can be present in the config file, but only one can be used at a time. - The default value is **rtpengine**. + The default value is __rtpengine__. A config file section is started in the config file using square brackets - (e.g. **\[rtpengine\]**). + (e.g. __\[rtpengine\]__). -- **-t**, **--table=**_INT_ +- __-t__, __\-\-table=__*INT* Takes an integer argument and specifies which kernel table to use for in-kernel packet forwarding. @@ -70,14 +79,14 @@ at the command line. See the **--config-file** option below for details. Optional and defaults to zero. If in-kernel operation is not desired, a negative number can be specified. -- **-F**, **--no-fallback** +- __-F__, __\-\-no-fallback__ Will prevent fallback to userspace-only operation if the kernel module is unavailable. In this case, startup of the daemon will fail with an error if this option is given. -- **-S**, **--save-interface-ports** +- __-S__, __\-\-save-interface-ports__ Will bind ports only on the first available local interface, of desired family, of logical interface. If no ports available on any local interface @@ -85,136 +94,136 @@ at the command line. See the **--config-file** option below for details. In this case, ICE will be broken. -- **-i**, **--interface=**\[_NAME_**/**\]_IP_\[**!**_IP_\] +- __-i__, __\-\-interface=__\[*NAME*/\]*IP*\[!*IP*\] Specifies a local network interface for RTP. At least one must be given, but multiple can be specified. See the section [INTERFACES](https://metacpan.org/pod/INTERFACES) just below for details. -- **-l**, **--listen-tcp=**\[_IP_**:**\]_PORT_ -- **-u**, **--listen-udp=**\[_IP46_**:**\]_PORT_ -- **-n**, **--listen-ng=**\[_IP46_**:**\]_PORT_ -- **-n**, **--listen-tcp-ng=**\[_IP46_**:**\]_PORT_ +- __-l__, __\-\-listen-tcp=__\[*IP*:\]*PORT* +- __-u__, __\-\-listen-udp=__\[*IP46*:\]*PORT* +- __-n__, __\-\-listen-ng=__\[*IP46*:\]*PORT* +- __-n__, __\-\-listen-tcp-ng=__\[*IP46*:\]*PORT* These options each enable one of the 4 available control protocols if given - and each take either just a port number as argument, or an _address:port_ + and each take either just a port number as argument, or an *address:port* pair, separated by colon. At least one of these 3 options must be given. - The **tcp** protocol is obsolete. - It was used by old versions of **OpenSER** and its **mediaproxy** module. + The __tcp__ protocol is obsolete. + It was used by old versions of __OpenSER__ and its __mediaproxy__ module. It is provided for backwards compatibility. - The **udp** protocol is used by **Kamailio**'s **rtpproxy** module. - In this mode, **rtpengine** can be used as a drop-in replacement for any + The __udp__ protocol is used by __Kamailio__'s __rtpproxy__ module. + In this mode, __rtpengine__ can be used as a drop-in replacement for any other compatible RTP proxy. - The **ng** protocol is an advanced control protocol and can be used with - **Kamailio**'s **rtpengine** module. - With this protocol, the complete SDP body is passed to **rtpengine**, - rewritten and passed back to **Kamailio**. + The __ng__ protocol is an advanced control protocol and can be used with + __Kamailio__'s __rtpengine__ module. + With this protocol, the complete SDP body is passed to __rtpengine__, + rewritten and passed back to __Kamailio__. Several additional features are available with this protocol, such as ICE handling, SRTP bridging, etc. - The **tcp-ng** protocol is in fact the **ng** protocol but transported over TCP. + The __tcp-ng__ protocol is in fact the __ng__ protocol but transported over TCP. It is recommended to specify not only a local port number, but also - **127.0.0.1** as interface to bind to. + __127.0.0.1__ as interface to bind to. -- **-c**, **--listen-cli=**\[_IP46_:\]_PORT_ +- __-c__, __\-\-listen-cli=__\[*IP46*:\]*PORT* TCP ip and port to listen for the CLI (command line interface). -- **-g**, **--graphite=**_IP46_:_PORT_ +- __-g__, __\-\-graphite=__*IP46*:*PORT* Address of the graphite statistics server. -- **-w**, **--graphite-interval=**_INT_ +- __-w__, __\-\-graphite-interval=__*INT* Interval of the time when information is sent to the graphite server. -- **--graphite-prefix=**_STRING_ +- __\-\-graphite-prefix=__*STRING* Add a prefix for every graphite line. -- **--graphite-timeout=**_INT_ +- __\-\-graphite-timeout=__*INT* Sets after how much time (seconds) to force fail graphite socket connection, when graphite server is filtered out. If set to 0, there are no changes. -- **-t**, **--tos=**_INT_ +- __-t__, __\-\-tos=__*INT* Takes an integer as argument and if given, specifies the TOS value that should be set in outgoing packets. The default is to leave the TOS field untouched. - A typical value is 184 (**Expedited Forwarding**). + A typical value is 184 (__Expedited Forwarding__). -- **--control-tos=**_INT_ +- __\-\-control-tos=__*INT* Takes an integer as argument and if given, specifies the TOS value that should be set in the control-ng interface packets. The default is to leave the TOS field untouched. - This parameter can also be set or listed via **rtpengine-ctl**. + This parameter can also be set or listed via __rtpengine-ctl__. -- **--control-pmtu=****want**\|**dont** +- __\-\-control-pmtu=want__\|__dont__ Forces a specific PMTU discovery behaviour on IPv4 UDP control sockets, - overriding the system-wide default. If set to **want** then path MTU discovery + overriding the system-wide default. If set to __want__ then path MTU discovery is performed, initially enabling the DF (don't fragment) bit on outgoing IPv4 packets until the path MTU has been discovered through reception of a - "fragmentation needed" ICMP packet. If set to **dont** then path MTU discovery + "fragmentation needed" ICMP packet. If set to __dont__ then path MTU discovery is disabled, leaving the DF bit unset, and relying on the routers within the network path to perform any necessary fragmentation. - The setting of **dont** is useful in broken IPv4 environments without + The setting of __dont__ is useful in broken IPv4 environments without functioning PMTU discovery, for example in networks which unconditionally block all ICMP. -- **-o**, **--timeout=**_SECS_ +- __-o__, __\-\-timeout=__*SECS* Takes the number of seconds as argument after which a media stream should be considered dead if no media traffic has been received. If all media streams belonging to a particular call go dead, then the call - is removed from **rtpengine**'s internal state table. + is removed from __rtpengine__'s internal state table. Defaults to 60 seconds. -- **-s**, **--silent-timeout=**_SECS_ +- __-s__, __\-\-silent-timeout=__*SECS* - Ditto as the **--timeout** option, but applies to muted or inactive media + Ditto as the __\-\-timeout__ option, but applies to muted or inactive media streams. Defaults to 3600 (one hour). -- **-a**, **--final-timeout=**_SECS_ +- __-a__, __\-\-final-timeout=__*SECS* The number of seconds since call creation, after call is deleted. Useful for limiting the lifetime of a call. This feature can be disabled by setting the parameter to 0. By default this timeout is disabled. -- **--offer-timeout=**_SECS_ +- __\-\-offer-timeout=__*SECS* - This timeout (in seconds) is applied to calls which only had an **offer** - but no **answer**. + This timeout (in seconds) is applied to calls which only had an __offer__ + but no __answer__. Defaults to 3600 (one hour). -- **-p**, **--pidfile=**_FILE_ +- __-p__, __\-\-pidfile=__*FILE* Specifies a path and file name to write the daemon's PID number to. -- **-f**, **--foreground** +- __-f__, __\-\-foreground__ If given, prevents the daemon from daemonizing, meaning it will stay in the foreground. Useful for debugging. -- **-m**, **--port-min=**_INT_ -- **-M**, **--port-max=**_INT_ +- __-m__, __\-\-port-min=__*INT* +- __-M__, __\-\-port-max=__*INT* Both take an integer as argument and together define the local port range - from which **rtpengine** will allocate UDP ports for media traffic relay. + from which __rtpengine__ will allocate UDP ports for media traffic relay. Default to 30000 and 40000 respectively. -- **-L**, **--log-level=**_INT_ +- __-L__, __\-\-log-level=__*INT* Takes an integer as argument and controls the highest log level which will be sent to syslog. This is merely the default log level used for logging @@ -222,138 +231,138 @@ at the command line. See the **--config-file** option below for details. configured. The log levels correspond to the ones found in the [syslog(3)](http://man.he.net/man3/syslog) man page. - The default value is **6**, equivalent to LOG\_INFO. - The highest possible value is **7** (LOG\_DEBUG) which will log everything. + The default value is __6__, equivalent to LOG\_INFO. + The highest possible value is __7__ (LOG\_DEBUG) which will log everything. During runtime, the log level can be decreased by sending the signal SIGURS1 to the daemon and can be increased with the signal SIGUSR2. -- **--log-level-**_subsystem_**=**_INT_ +- __\-\-log-level-__*subsystem*=*INT* Configures a log level for one of the logging subsystems. A logging subsystem which doesn't have a log level configured explicitly takes its default value - from the **log-level** setting described above, with the exception of the - **internals** subsystem which by default has all logging disabled. + from the __log-level__ setting described above, with the exception of the + __internals__ subsystem which by default has all logging disabled. - The full list of logging subsystems can be viewed by pulling up the **--help** - online help. Some (if not all) subsystems are: **core**, **spandsp** (messages - generated by SpanDSP itself), **ffmpeg** (messages generated by ffmpeg libraries - themselves), **transcoding** (messages related to RTP/media transcoding), - **codec** (messages related to codec negotiation), **rtcp**, **ice**, **crypto** - (messages related to crypto/SRTP/SDES/DTLS negotiation), **srtp** (messages - related to RTP/SRTP en/decryption), **internals** (disabled by default), **http** - (includes WebSocket), **control** (messages related to control protocols, - including SDP exchanges), **dtx**. + The full list of logging subsystems can be viewed by pulling up the __\-\-help__ + online help. Some (if not all) subsystems are: __core__, __spandsp__ (messages + generated by SpanDSP itself), __ffmpeg__ (messages generated by ffmpeg libraries + themselves), __transcoding__ (messages related to RTP/media transcoding), + __codec__ (messages related to codec negotiation), __rtcp__, __ice__, __crypto__ + (messages related to crypto/SRTP/SDES/DTLS negotiation), __srtp__ (messages + related to RTP/SRTP en/decryption), __internals__ (disabled by default), __http__ + (includes WebSocket), __control__ (messages related to control protocols, + including SDP exchanges), __dtx__. -- **--log-facilty=****daemon**\|**local0**\|...\|**local7**\|... +- __\-\-log-facilty=daemon__\|__local0__\|...\|__local7__\|... The syslog facilty to use when sending log messages to the syslog daemon. - Defaults to **daemon**. + Defaults to __daemon__. -- **--log-facilty-cdr=****daemon**\|**local0**\|...\|**local7**\|... +- __\-\-log-facilty-cdr=daemon__\|__local0__\|...\|__local7__\|... - Same as **--log-facility** with the difference that only CDRs are written + Same as __\-\-log-facility__ with the difference that only CDRs are written to this log facility. -- **--log-facilty-rtcp=****daemon**\|**local0**\|...\|**local7**\|... +- __\-\-log-facilty-rtcp=daemon__\|__local0__\|...\|__local7__\|... - Same as **--log-facility** with the difference that only RTCP data is + Same as __\-\-log-facility__ with the difference that only RTCP data is written to this log facility. Be careful with this parameter since there may be a lot of information written to it. -- **--log-facilty-dtmf=****daemon**\|**local0**\|...\|**local7**\|... +- __\-\-log-facilty-dtmf=daemon__\|__local0__\|...\|__local7__\|... - Same as **--log-facility** with the difference that only DTMF events are + Same as __\-\-log-facility__ with the difference that only DTMF events are written to this log facility. DTMF events are extracted from RTP packets conforming to RFC 4733, are encoded in JSON format, and written as soon as the end of an event is detected. -- **--log-format=****default**\|**parsable** +- __\-\-log-format=default__\|__parsable__ Selects between multiple log output styles. The default is to prefix log lines with a description of the relevant - entity, such as **\[CALLID\]** or **\[CALLID port 12345\]**. - The **parsable** output style is similar, but makes the ID easier to - parse by enclosing it in quotes, such as **\[ID="CALLID"\]** - or **\[ID="CALLID" port="12345"\]**. + entity, such as __\[CALLID\]__ or __\[CALLID port 12345\]__. + The __parsable__ output style is similar, but makes the ID easier to + parse by enclosing it in quotes, such as __\[ID="CALLID"\]__ + or __\[ID="CALLID" port="12345"\]__. -- **--dtmf-log-dest=**_IP46_:_PORT_ +- __\-\-dtmf-log-dest=__*IP46*:*PORT* Configures a target address for logging detected DTMF event. Similar - to the feature enabled by **--log-facilty-dtmf**, but instead of writing + to the feature enabled by __\-\-log-facilty-dtmf__, but instead of writing detected DTMF events to syslog, this sends the JSON payload to the given address as UDP packets. -- **--dtmf-log-ng-tcp** +- __\-\-dtmf-log-ng-tcp__ - If **--listen-tcp-ng** is enabled, this will send DTMF events to all + If __\-\-listen-tcp-ng__ is enabled, this will send DTMF events to all connected clients encoded in bencode format. -- **--dtmf-no-log-injects** -If **--dtmf-no-log-injects** is enabled, DTMF events resulting from a -call to inject-DTMF won't be sent to **--dtmf-log-dest=** or **--listen-tcp-ng** -- **--dtmf-no-suppress** +- __\-\-dtmf-no-log-injects__ +If __\-\-dtmf-no-log-injects__ is enabled, DTMF events resulting from a +call to inject-DTMF won't be sent to __\-\-dtmf-log-dest=__ or __\-\-listen-tcp-ng__ +- __\-\-dtmf-no-suppress__ Some RTP clients continue to send audio RTP packets during a DTMF event, resulting in both audio packets and DTMF packets appearing simultaneously. By - default, when transcoding, **rtpengine** suppresses audio packets during a DTMF + default, when transcoding, __rtpengine__ suppresses audio packets during a DTMF event and will only send DTMF packets until the DTMF event is over. Setting this option disables this feature. -- **--log-srtp-keys** +- __\-\-log-srtp-keys__ Write SRTP keys to error log instead of debug log. -- **-E**, **--log-stderr** +- __-E__, __\-\-log-stderr__ Log to stderr instead of syslog. - Only useful in combination with **--foreground**. + Only useful in combination with __\-\-foreground__. -- **--split-logs** +- __\-\-split-logs__ Split multi-line log messages into individual log messages so that each line receives its own log line prefix. -- **--max-log-line-length=**_INT_ +- __\-\-max-log-line-length=__*INT* Split log lines into multiple lines when they exceed the character count given here. Can be set to a negative value to allow unlimited length log lines. Set to zero for the default value, which is unlimited if logging to stderr, or 500 if logging to syslog. -- **--no-log-timestamps** +- __\-\-no-log-timestamps__ Don't add timestamps to log lines written to stderr. - Only useful in combination with **--log-stderr**. + Only useful in combination with __\-\-log-stderr__. -- **--log-name=**_STRING_ +- __\-\-log-name=__*STRING* Set the id to be printed in syslog. - Defaults to **rtpengine**. + Defaults to __rtpengine__. -- **--log-mark-prefix=**_STRING_ +- __\-\-log-mark-prefix=__*STRING* Prefix to be added to particular data fields in log files that are deemed sensitive and/or private information. Defaults to an empty string. -- **--log-mark-suffix=**_STRING_ +- __\-\-log-mark-suffix=__*STRING* Suffix to be added to particular data fields in log files that are deemed sensitive and/or private information. Defaults to an empty string. -- **--num-threads=**_INT_ +- __\-\-num-threads=__*INT* How many worker threads to create, must be at least one. The default is to create as many threads as there are CPU cores available. If the number of CPU cores cannot be determined or if it is less than four, then the default is four. -- **--media-num-threads=**_INT_ +- __\-\-media-num-threads=__*INT* Number of threads to launch for media playback. Defaults to the same - number as **num-threads**. This can be set to zero if no media playback + number as __num-threads__. This can be set to zero if no media playback functionality is desired. Media playback is actually handled by two threads: One for reading and @@ -361,60 +370,60 @@ call to inject-DTMF won't be sent to **--dtmf-log-dest=** or **--listen-tcp-ng** So for example, if this option is set to 4, in total 8 threads will be launched. -- **--thread-stack=**_INT_ +- __\-\-thread-stack=__*INT* Set the stack size of each thread to the value given in kB. Defaults to 2048 kB. Can be set to -1 to leave the default provided by the OS unchanged. -- **--evs-lib-path=**_FILE_ +- __\-\-evs-lib-path=__*FILE* - Points to the shared object file (**.so**) containing the reference + Points to the shared object file (__.so__) containing the reference implementation for the EVS codec. See the `README` for more details. -- **--sip-source** +- __\-\-sip-source__ - The original **rtpproxy** as well as older version of **rtpengine** by default + The original __rtpproxy__ as well as older version of __rtpengine__ by default did not honour IP addresses given in the SDP body, and instead used the source address of the received SIP message as default endpoint address. - Newer versions of **rtpengine** reverse this behaviour and honour the + Newer versions of __rtpengine__ reverse this behaviour and honour the addresses given in the SDP body by default. This option restores the old behaviour. -- **--dtls-passive** +- __\-\-dtls-passive__ - Enables the **DTLS=passive** flag for all calls unconditionally. + Enables the __DTLS=passive__ flag for all calls unconditionally. -- **-d**, **--delete-delay=**_INT_ +- __-d__, __\-\-delete-delay=__*INT* Delete the call after the specified delay from memory. Can be set to zero for immediate call deletion. -- **-r**, **--redis=**\[_PW_**@**\]_IP_**:**_PORT_**/**_INT_ +- __-r__, __\-\-redis=__\[*PW*@\]*IP*:*PORT*/*INT* Connect to specified Redis database (with the given database number) and use it for persistence storage. - The format of this option is _ADDRESS_:_PORT_/_DBNUM_, for example - _127.0.0.1:6379/12_ to connect to the Redis DB number 12 running on + The format of this option is *ADDRESS*:*PORT*/*DBNUM*, for example + *127.0.0.1:6379/12* to connect to the Redis DB number 12 running on localhost on the default Redis port. If the Redis database is protected with an authentication password, the password can be supplied by prefixing the argument value with the password, - separated by an **@** symbol, for example _foobar@127.0.0.1:6379/12_. + separated by an `@` symbol, for example *foobar@127.0.0.1:6379/12*. Note that this leaves the password visible in the process list, posing a security risk if untrusted users access the same system. As an alternative, the password can also be supplied in the shell - environment through the environment variable **RTPENGINE\_REDIS\_AUTH\_PW**. + environment through the environment variable __RTPENGINE\*REDIS\*AUTH\*PW__. - On startup, **rtpengine** will read the contents of this database and + On startup, __rtpengine__ will read the contents of this database and restore all calls stored therein. - During runtime operation, **rtpengine** will continually update the + During runtime operation, __rtpengine__ will continually update the database's contents to keep it current, so that in case of a service disruption, the last state can be restored upon a restart. - When this option is given, **rtpengine** will delay startup until the + When this option is given, __rtpengine__ will delay startup until the Redis database adopts the master role (but see below). -- **-w**, **--redis-write=**\[_PW_**@**\]_IP_**:**_PORT_**/**_INT_ +- __-w__, __\-\-redis-write=__\[*PW*@\]*IP*:*PORT*/*INT* Configures a second Redis database for write operations. If this option is given in addition to the first one, then the first @@ -423,45 +432,45 @@ call to inject-DTMF won't be sent to **--dtmf-log-dest=** or **--listen-tcp-ng** in the database). For password protected Redis servers, the environment variable for the - password is **RTPENGINE\_REDIS\_WRITE\_AUTH\_PW**. + password is __RTPENGINE\*REDIS\*WRITE\*AUTH\*PW__. - When both options are given, **rtpengine** will start and use the Redis + When both options are given, __rtpengine__ will start and use the Redis database regardless of the database's role (master or slave). -- **-k**, **--subscribe-keyspace=**_INT_ +- __-k__, __\-\-subscribe-keyspace=__*INT* List of redis keyspaces to subscribe. If this is not present, no keyspaces are subscribed (default behaviour). - Further subscriptions could be added/removed via **rtpengine-ctl ksadd/ksrm**. + Further subscriptions could be added/removed via __rtpengine-ctl ksadd/ksrm__. This may lead to enabling/disabling of the redis keyspace notification feature. -- **--redis-num-threads=**_INT_ +- __\-\-redis-num-threads=__*INT* How many redis restore threads to create. The default is 4. -- **--redis-expires=**_INT_ +- __\-\-redis-expires=__*INT* Expire time in seconds for redis keys. Default is 86400. -- **--active-switchover** +- __\-\-active-switchover__ With this option enabled, any activity (such as signalling or media) on a call - that was created through a Redis keyspace notification will make **rtpengine** + that was created through a Redis keyspace notification will make __rtpengine__ take control of that call. Without this option, an explicit command is required - for **rtpengine** to take (or relinquish) control of a call. + for __rtpengine__ to take (or relinquish) control of a call. -- **-q**, **--no-redis-required** +- __-q__, __\-\-no-redis-required__ - When this parameter is present or **NO\_REDIS\_REQUIRED='yes'** or **'1'** in - the config file, **rtpengine** starts even if there is no initial connection - to redis databases (either to **-r** or to **-w** or to both redis). + When this parameter is present or __NO\*REDIS\*REQUIRED='yes'__ or __'1'__ in + the config file, __rtpengine__ starts even if there is no initial connection + to redis databases (either to __-r__ or to __-w__ or to both redis). - Be aware that if the **-r** redis cannot be initially connected, sessions + Be aware that if the __-r__ redis cannot be initially connected, sessions are not reloaded upon rtpengine startup, even though rtpengine still starts. -- **--redis-allowed-errors** +- __\-\-redis-allowed-errors__ If this parameter is present and has a value >= 0, it will configure how many consecutive errors are allowed when communicating with a redis server @@ -469,50 +478,50 @@ call to inject-DTMF won't be sent to **--dtmf-log-dest=** or **--listen-tcp-ng** While the communication is disabled there will be no attempts to reconnect to redis or send commands to that server. Default value is -1, meaning that this feature is disabled. - This parameter can also be set or listed via **rtpengine-ctl**. + This parameter can also be set or listed via __rtpengine-ctl__. -- **--redis-disable-time** +- __\-\-redis-disable-time__ This parameter configures the number of seconds redis communication is disabled because of errors. This works together with redis-allowed-errors parameter. The default value is 10. - This parameter can also be set or listed via **rtpengine-ctl**. + This parameter can also be set or listed via __rtpengine-ctl__. -- **--redis-cmd-timeout=**_INT_ +- __\-\-redis-cmd-timeout=__*INT* If this parameter is set to a non-zero value it will set the timeout, in milliseconds, for each command to the redis server. If redis does not reply within the specified timeout the command will fail. The default value is 0, meaning that the commands will be blocking without timeout. - This parameter can also be set or listed via **rtpengine-ctl**; note that + This parameter can also be set or listed via __rtpengine-ctl__; note that setting the parameter to 0 will require a reconnect on all configured redis servers. -- **--redis-connect-timeout=**_INT_ +- __\-\-redis-connect-timeout=__*INT* This parameter sets the timeout value, in milliseconds, when connecting to a redis server. If the connection cannot be made within the specified timeout the connection will fail. - Note that in case of failure, when reconnecting to redis, a **PING** command - is issued before attempting to connect so the **--redis-cmd-timeout** value + Note that in case of failure, when reconnecting to redis, a __PING__ command + is issued before attempting to connect so the __\-\-redis-cmd-timeout__ value will also be added to the total waiting time. - This is useful if using **--redis-allowed-errors**, when attempting to + This is useful if using __\-\-redis-allowed-errors__, when attempting to estimate the total lost time in case of redis failures. The default value for the connection timeout is 1000ms. - This parameter can also be set or listed via **rtpengine-ctl**. + This parameter can also be set or listed via __rtpengine-ctl__. -- **-b**, **--b2b-url=**_STRING_ +- __-b__, __\-\-b2b-url=__*STRING* Enables and sets the URI for an XMLRPC callback to be made when a call is torn down due to packet timeout. - The special code **%%** can be used in place of an IP address, in which case + The special code __%%__ can be used in place of an IP address, in which case the source address of the originating request (or alternatively the address - specified using the **xmlrpc-callback** **ng** protocol option) will be used. + specified using the __xmlrpc-callback__ __ng__ protocol option) will be used. -- **-x**, **--xmlrpc-format=**_INT_ +- __-x__, __\-\-xmlrpc-format=__*INT* Selects the internal format of the XMLRPC callback message for B2BUA call teardown. @@ -520,31 +529,31 @@ call to inject-DTMF won't be sent to **--dtmf-log-dest=** or **--listen-tcp-ng** 1 is for a generic format containing the call-ID only, 2 is for Kamailio. -- **--max-sessions=**_INT_ +- __\-\-max-sessions=__*INT* Limit the number of maximum concurrent sessions. - Set at startup via **max-sessions** in config file. - Set at runtime via **rtpengine-ctl** util. - Setting the **rtpengine-ctl set maxsessions 0** can be used in draining + Set at startup via __max-sessions__ in config file. + Set at runtime via __rtpengine-ctl__ util. + Setting the __rtpengine-ctl set maxsessions 0__ can be used in draining rtpengine sessions. - Enable feature: **max-sessions=1000** - Enable feature: **rtpengine-ctl set maxsessions** >= 0 - Disable feature: **rtpengine-ctl set maxsessions -1** + Enable feature: __max-sessions=1000__ + Enable feature: __rtpengine-ctl set maxsessions__ >= 0 + Disable feature: __rtpengine-ctl set maxsessions -1__ By default, the feature is disabled (i.e. maxsessions == -1). -- **--max-load=**_FLOAT_ +- __\-\-max-load=__*FLOAT* If the current 1-minute load average exceeds the value given here, reject new sessions until the load average drops below the threshold. -- **--max-cpu=**_FLOAT_ +- __\-\-max-cpu=__*FLOAT* If the current CPU usage (in percent) exceeds the value given here, reject new sessions until the CPU usage drops below the threshold. CPU usage is sampled in 0.5-second intervals. Only supported on systems providing a Linux-style `/proc/stat`. -- **--max-bandwidth=**_INT_ +- __\-\-max-bandwidth=__*INT* If the current bandwidth usage (in bytes per second) exceeds the value given here, reject new sessions until the bandwidth usage drops below @@ -552,32 +561,32 @@ call to inject-DTMF won't be sent to **--dtmf-log-dest=** or **--listen-tcp-ng** Bandwidth usage is sampled in 1-second intervals and is based on received packets, not sent packets. -- **--homer=**_IP46_**:**_PORT_ +- __\-\-homer=__*IP46*:*PORT* Enables sending the decoded contents of RTCP packets to a Homer SIP capture server. The transport is HEP version 3 and payload format is JSON. This argument takes an IP address and a port number as value. -- **--homer-protocol=****udp**\|**tcp** +- __\-\-homer-protocol=udp__\|__tcp__ - Can be either **udp** or **tcp** with **udp** being the default. + Can be either __udp__ or __tcp__ with __udp__ being the default. -- **--homer-id=**_INT_ +- __\-\-homer-id=__*INT* The HEP protocol used by Homer contains a "capture ID" used to distinguish different sources of capture data. This ID can be specified using this argument. -- **--recording-dir=**_FILE_ +- __\-\-recording-dir=__*FILE* An optional argument to specify a path to a directory where PCAP recording files and recording metadata files should be stored. If not specified, support for call recording will be disabled. - **rtpengine** supports multiple mechanisms for recording calls. - See **recording-method** below for a list. - The default recording method **pcap** is described in this section. + __rtpengine__ supports multiple mechanisms for recording calls. + See __recording-method__ below for a list. + The default recording method __pcap__ is described in this section. PCAP files will be stored within a `pcap` subdirectory and metadata within a `metadata` subdirectory. @@ -623,15 +632,15 @@ call to inject-DTMF won't be sent to **--dtmf-log-dest=** or **--listen-tcp-ng** in-kernel packet forwarding cannot be used for calls that are currently being recorded and packet forwarding will thus be done in userspace only. -- **--recording-method=****pcap**\|**proc**\|**all** +- __\-\-recording-method=pcap__\|__proc__\|__all__ Multiple methods of call recording are supported and this option can be used to select one. - Currently supported are the method **pcap**, **proc** and **all**. - The default method is **pcap** and is the one described above. + Currently supported are the method __pcap__, __proc__ and __all__. + The default method is __pcap__ and is the one described above. - The recording method **proc** works by writing metadata files directly into - the **recording-dir** (i.e. not into a subdirectory) and instead of recording + The recording method __proc__ works by writing metadata files directly into + the __recording-dir__ (i.e. not into a subdirectory) and instead of recording RTP packet data into pcap files, the packet data is exposed via a special interface in the `/proc` filesystem. Packets must then be retrieved from this interface by a dedicated userspace @@ -649,116 +658,116 @@ call to inject-DTMF won't be sent to **--dtmf-log-dest=** or **--listen-tcp-ng** In-kernel packet forwarding is fully supported with this recording method even for calls being recorded. - The recording method **all** will enable both **pcap** and **proc** + The recording method __all__ will enable both __pcap__ and __proc__ at the same time. -- **--recording-format=****raw**\|**eth** +- __\-\-recording-format=raw__\|__eth__ - When recording to pcap file in **raw** (default) format, there is no + When recording to pcap file in __raw__ (default) format, there is no ethernet header. - When set to **eth**, a fake ethernet header is added, making each package + When set to __eth__, a fake ethernet header is added, making each package 14 bytes larger. -- **--record-egress** +- __\-\-record-egress__ Apply media recording to egress media streams (as they are sent by - **rtpengine**) instead of media streams as they are received. This makes it - possible to include manipulated and generated media (such as from the **play - media** command) in the recordings. + __rtpengine__) instead of media streams as they are received. This makes it + possible to include manipulated and generated media (such as from the __play + media__ command) in the recordings. -- **--iptables-chain=**_STRING_ +- __\-\-iptables-chain=__*STRING* This option enables explicit management of an iptables chain. - When enabled, **rtpengine** takes control of the given iptables chain, + When enabled, __rtpengine__ takes control of the given iptables chain, which must exist already prior to starting the daemon. - Upon startup, **rtpengine** will flush the chain, and then add one **ACCEPT** + Upon startup, __rtpengine__ will flush the chain, and then add one __ACCEPT__ rule for each media port (RTP/RTCP) opened. Each rule will exactly match the individual port and destination IP address, and will be created with the call ID as iptables comment. The rule will be deleted when the port is closed. - This option allows creating a firewall with a default **DROP** policy for - the entire port range used by **rtpengine** and then referencing the given + This option allows creating a firewall with a default __DROP__ policy for + the entire port range used by __rtpengine__ and then referencing the given iptables chain to only selectively allow the ports actually in use. Note that this applies only to media ports, and does not apply to any other - ports (such as the control ports) used by **rtpengine**. + ports (such as the control ports) used by __rtpengine__. Also note that the iptables API is not the most efficient one around and does not lend itself to fast dynamic creation and deletion of rules. If you have a high call volume, and especially many call attempts per second, you might experience significant performance impact. - This is not a shortcoming of **rtpengine** but rather of iptables and its + This is not a shortcoming of __rtpengine__ but rather of iptables and its API implementation in the Linux kernel. In such a case, it is recommended to add a static iptables rule for the entire media port range instead, and not use this option. -- **--scheduling=****default**\|... -- **--priority=**_INT_ -- **--idle-scheduling=****default**\|... -- **--idle-priority=**_INT_ +- __\-\-scheduling=default__\|... +- __\-\-priority=__*INT* +- __\-\-idle-scheduling=default__\|... +- __\-\-idle-priority=__*INT* These options control various thread scheduling parameters. - The **scheduling** and **priority** settings are applied to the main - worker threads, while the **idle-** versions of these settings are + The __scheduling__ and __priority__ settings are applied to the main + worker threads, while the __idle-__ versions of these settings are applied to various lower priority threads, such as timer runs. - The **scheduling** settings take the name of one of the supported + The __scheduling__ settings take the name of one of the supported scheduler policies. - Setting it to **default** or **none** is equivalent to not setting the + Setting it to __default__ or __none__ is equivalent to not setting the option at all and leaves the system default in place. - The strings **fifo** and **rr** refer to realtime scheduling policies. - **other** is the Linux default scheduling policy. - **batch** is similar to **other** except for a small wake-up scheduling + The strings __fifo__ and __rr__ refer to realtime scheduling policies. + __other__ is the Linux default scheduling policy. + __batch__ is similar to __other__ except for a small wake-up scheduling penalty. - **idle** is an extremely low priority scheduling policy. - The Linux-specific **deadline** policy is not supported by **rtpengine**. + __idle__ is an extremely low priority scheduling policy. + The Linux-specific __deadline__ policy is not supported by __rtpengine__. Not all systems necessarily supports all scheduling policies; refer to your system's sched(7) man page for details. - The **priority** settings correspond to the scheduling priority for - realtime (**fifo** or **rr**) scheduling policies and must be in the range + The __priority__ settings correspond to the scheduling priority for + realtime (__fifo__ or __rr__) scheduling policies and must be in the range of 1 (low) through 99 (high). For all other scheduling policies (including no policy specified), the - **priority** settings correspond to the **nice** value and should be in + __priority__ settings correspond to the __nice__ value and should be in the range of -20 (high) through 19 (low). - Not all systems support thread-specific **nice** values; on such a system, + Not all systems support thread-specific __nice__ values; on such a system, using these settings might have unexpected results. - (Linux does support thread-specific **nice** values.) + (Linux does support thread-specific __nice__ values.) Refer to your system's sched(7) man page. -- **--mysql-host=**_HOST_\|_IP_ -- **--mysql-port=**_INT_ -- **--mysql-user=**_USERNAME_ -- **--mysql-pass=**_PASSWORD_ +- __\-\-mysql-host=__*HOST*\|*IP* +- __\-\-mysql-port=__*INT* +- __\-\-mysql-user=__*USERNAME* +- __\-\-mysql-pass=__*PASSWORD* Configuration for playing back media files that are stored in a - **MySQL** (or **MariaDB**) database. At least **mysql-host** must be configured + __MySQL__ (or __MariaDB__) database. At least __mysql-host__ must be configured for this to work. The others are optional and default to their respective - values from the **MySQL**/**MariaDB** client library. + values from the __MySQL__/__MariaDB__ client library. -- **--mysql-query=**_STRING_ +- __\-\-mysql-query=__*STRING* Query to be used for retrieving media files from the database. No default exist, therefore this is a mandatory configuration for media playback from database. The provided query string must contain the single format placeholder - **%llu** and must not contain any other format placeholders. The ID value - passed to **rtpengine** in the **db-id** key of the **play media** message will + __%llu__ and must not contain any other format placeholders. The ID value + passed to __rtpengine__ in the __db-id__ key of the __play media__ message will be used in place of the placeholder when querying the database. An example configuration might look like this: mysql-query = select data from voip.files where id = %llu -- **--endpoint-learning=****delayed**\|**immediate**\|**off**\|**heuristic** +- __\-\-endpoint-learning=delayed__\|__immediate__\|__off__\|__heuristic__ Chooses one of the available algorithms to learn RTP endpoint addresses. The - legacy setting is **delayed** which waits 3 seconds before committing to an + legacy setting is __delayed__ which waits 3 seconds before committing to an endpoint address, which is then learned from the first incoming RTP packet seen - after this delay. The setting **immediate** learns the endpoint address from the - first incoming packet seen without the 3-second delay. Using **off** disables + after this delay. The setting __immediate__ learns the endpoint address from the + first incoming packet seen without the 3-second delay. Using __off__ disables endpoint learning altogether, likely breaking clients behind NAT. The setting - **heuristic** includes the 3-second delay, but source addresses seen from + __heuristic__ includes the 3-second delay, but source addresses seen from incoming RTP packets are ranked according to preference: If a packet with a source address and port matching the SDP address is seen, this address is used. Otherwise, if a packet with a matching source address (but a different port) is @@ -766,17 +775,17 @@ call to inject-DTMF won't be sent to **--dtmf-log-dest=** or **--listen-tcp-ng** (but different address) is seen, that address is used. Otherwise, the source address of any incoming packet seen is used. -- **--jitter-buffer=**_INT_ +- __\-\-jitter-buffer=__*INT* Size of (incoming) jitter buffer in packets. A value of zero (the default) disables the jitter buffer. The jitter buffer is currently only implemented for userspace operation. -- **--jb-clock-drift** +- __\-\-jb-clock-drift__ Enable clock drift compensation for the jitter buffer. -- **--debug-srtp** +- __\-\-debug-srtp__ Enable extra log messages to help debug SRTP issues. Per-packet details such as sequence numbers, ROC, payloads (plain text and encrypted), authentication @@ -784,15 +793,15 @@ call to inject-DTMF won't be sent to **--dtmf-log-dest=** or **--listen-tcp-ng** while every 512th RTP packet is logged. Only applies to packets forwarded/processed in userspace. -- **--reject-invalid-sdp** +- __\-\-reject-invalid-sdp__ With this option set, refuse to process SDP bodies that could not be cleanly parsed, instead of skipping over the parsing error and processing the SDP anyway. Currently this only affects the processing of SDP bodies that end in a blank line. -- **--listen-http=**\[_IP_\|_HOSTNAME_**:**\]_PORT_ -- **--listen-https=**\[_IP_\|_HOSTNAME_**:**\]_PORT_ +- __\-\-listen-http=__\[*IP*\|*HOSTNAME*:\]*PORT* +- __\-\-listen-https=__\[*IP*\|*HOSTNAME*:\]*PORT* Enable listening for HTTP or WebSocket connections, or their TLS-secured counterparts HTTPS and WSS. If no interface is specified, then the listening @@ -804,26 +813,26 @@ call to inject-DTMF won't be sent to **--dtmf-log-dest=** or **--listen-tcp-ng** If HTTPS/WSS is enabled, a certificate must also be provided using the options below. -- **--https-cert=**_FILE_ -- **--https-key=**_FILE_ +- __\-\-https-cert=__*FILE* +- __\-\-https-key=__*FILE* Provide a server certificate and corresponding private key for the HTTPS/WSS listener, in PEM format. -- **--http-threads=**_INT_ +- __\-\-http-threads=__*INT* Number of worker threads for HTTP/HTTPS/WS/WSS. If not specified, then the same - number as given under **num-threads** will be used. If no HTTP listeners are + number as given under __num-threads__ will be used. If no HTTP listeners are enabled, then no threads are created. -- **--software-id=**_STRING_ +- __\-\-software-id=__*STRING* Sets a free-form string that is used to identify this software towards external systems with, for example in outgoing ICE/STUN requests. Defaults to - **rtpengine-**_VERSION_. The string is sanitised to replace all + __rtpengine-__*VERSION*. The string is sanitised to replace all non-alphanumeric characters with a dash to make it universally usable. -- **--dtx-delay=**_INT_ +- __\-\-dtx-delay=__*INT* Processing delay in milliseconds to handle discontinuous transmission (DTX) or other transmission gaps. Defaults to zero (disabled) and is applicable to @@ -834,26 +843,26 @@ call to inject-DTMF won't be sent to **--dtmf-log-dest=** or **--listen-tcp-ng** comfort noise. The delay should be configured to be higher than the expected incoming jitter. -- **--max-dtx=**_INT_ +- __\-\-max-dtx=__*INT* Maximum duration for DTX handling in seconds. If no further RTP media is received within this time frame, then DTX processing will stop. Can be set to zero or negative to disable and keep DTX processing on indefinitely. Defaults to 30 seconds. -- **--dtx-buffer=**_INT_ -- **--dtx-lag=**_INT_ +- __\-\-dtx-buffer=__*INT* +- __\-\-dtx-lag=__*INT* These two options together control the maximum number of packets and amount of - audio that is allowed to be held in the DTX buffer. The **dtx-buffer** option - limits the number of packets held in the DTX buffer, while the **dtx-lag** + audio that is allowed to be held in the DTX buffer. The __dtx-buffer__ option + limits the number of packets held in the DTX buffer, while the __dtx-lag__ option limits the amount of audio (in milliseconds) to be held in the DTX buffer. A DTX buffer overflow is declared when both limits are exceeded, in - which case DTX processing is sped up by **dtx-shift** milliseconds. + which case DTX processing is sped up by __dtx-shift__ milliseconds. The defaults are 10 packets and 100 milliseconds. -- **--dtx-shift=**_INT_ +- __\-\-dtx-shift=__*INT* Amount of time in milliseconds that DTX processing is shifted forward (sped up) or backwards (delayed) in case of a DTX buffer overflow or underflow. An @@ -864,10 +873,10 @@ call to inject-DTMF won't be sent to **--dtmf-log-dest=** or **--listen-tcp-ng** Instead, in order to keep up with the flow of received RTP packets, packets will be dropped or additional DTX audio will be generated as needed. -- **--dtx-cn-params=**_INT_ +- __\-\-dtx-cn-params=__*INT* Specify one comfort noise parameter. This option follows the same format as - **cn-payload** described below. + __cn-payload__ described below. This option is applicable to audio generated to fill in transmission gaps during a DTX event. The default setting is no value, which means silence will @@ -877,19 +886,19 @@ call to inject-DTMF won't be sent to **--dtmf-log-dest=** or **--listen-tcp-ng** 3389 CN decoder, and the generated comfort noise will be used to fill in DTX gaps. -- **--amr-dtx=****native**\|**CN** +- __\-\-amr-dtx=native__\|__CN__ Select the DTX behaviour for AMR codecs. The default is use the codec's internal processing: during a DTX event, a "no data" frame is passed to the decoder and the output is used as audio data. - If **CN** is selected here, the same DTX mechanism as other codecs use is used + If __CN__ is selected here, the same DTX mechanism as other codecs use is used for AMR, which is to fill in DTX gaps with either silence or RFC 3389 comfort - noise (see **dtx-cn-params**). This also affects processing of received SID + noise (see __dtx-cn-params__). This also affects processing of received SID frames: SID frames would not be passed to the codec but instead be replaced by generated silence or comfort noise. -- **--silence-detect=**_FLOAT_ +- __\-\-silence-detect=__*FLOAT* Enable silence detection and specify threshold in percent. This option is applicable to transcoded stream only and defaults to zero (disabled). @@ -908,18 +917,18 @@ call to inject-DTMF won't be sent to **--dtmf-log-dest=** or **--listen-tcp-ng** but instead have a residual DC offset. For PCMA the minimum value is 0.013.) Audio that is detected as silence will be replaced by comfort noise as - specified by the **cn-payload** option (see below). Currently this is applicable - only to RTP peers that have advertised support for the **CN** RTP payload type, - in which case the silence audio frames will be replaced by **CN** RTP frames. + specified by the __cn-payload__ option (see below). Currently this is applicable + only to RTP peers that have advertised support for the __CN__ RTP payload type, + in which case the silence audio frames will be replaced by __CN__ RTP frames. -- **--cn-payload=**_INT_ +- __\-\-cn-payload=__*INT* Specify one comfort noise parameter. This option can be given multiple times and the format follows RFC 3389. When specified at the command line, list the - **--cn-payload=** option multiple times, each one specifying a single CN + __\-\-cn-payload=__ option multiple times, each one specifying a single CN parameter. When used in the config file, list the option only a single time and list multiple CN parameters separated by semicolons (e.g. - _cn-payload = 20;40;60_). + *cn-payload = 20;40;60*). The first CN payload value given is the noise level, specified as -dBov as per RFC 3389. This means that a noise level of zero corresponds to maximum volume, @@ -931,18 +940,18 @@ call to inject-DTMF won't be sent to **--dtmf-log-dest=** or **--listen-tcp-ng** between 0 and 254. Specifying spectral information is optional and the number of coefficients listed (model order) is variable. - This option is applicable only to **CN** packets generated from the silence + This option is applicable only to __CN__ packets generated from the silence detection mechanism described above. The configured CN parameters are used - directly as payload of **CN** packets sent by **rtpengine**. + directly as payload of __CN__ packets sent by __rtpengine__. The default values are 32 (-32 dBov) for the noise level and no spectral information. -- **--player-cache** +- __\-\-player-cache__ Enable caching of encoded media packets for media player. This is applicable - for media playback initiated through the _play media_ command. When enabled - **rtpengine** will not simply decode given media files and then encode the media + for media playback initiated through the *play media* command. When enabled + __rtpengine__ will not simply decode given media files and then encode the media to RTP on demand and on the fly, but will rather decode and encode each media file in full the first time playback is requested, and then cache the resulting RTP packets in memory. This is done once for each media file and for each @@ -951,29 +960,29 @@ call to inject-DTMF won't be sent to **--dtmf-log-dest=** or **--listen-tcp-ng** Caching is done based on unique file name (with no consideration given to different file names that may point to the same file), or integer index for media files played from database. No verification of changing content of files - or database entries is done. Media files provided as binary _blob_ are also + or database entries is done. Media files provided as binary *blob* are also cached, although in this case a hash over the entire media file must be performed, therefore this usage is not recommended. - It's not possible to choose a different _start-pos_ for playback with this + It's not possible to choose a different *start-pos* for playback with this option enabled. RTP data is cached and retained in memory for the lifetime of the process. -- **audio-buffer-length=**_INT_ +- __audio-buffer-length=__*INT* Set the buffer length used by the audio player (see below) in milliseconds. The default is 500 milliseconds. The buffer must be long enough to accommodate at least two frames of audio from all contributing sources, which means at least 40 ms or 60 ms for most cases. - If media playback (via the **play media**) command is desired, then the buffer + If media playback (via the __play media__) command is desired, then the buffer must be able to accommodate at least one full frame from the source media file, whose length can vary depending on the format of the source media file. For 8 - kHz **.wav** files this is 256 ms (2048 samples). Therefore 500 ms is the + kHz __.wav__ files this is 256 ms (2048 samples). Therefore 500 ms is the recommended value. -- **audio-buffer-delay=**_INT_ +- __audio-buffer-delay=__*INT* Initial delay for new sources contributing to an audio buffer (used by the audio player, see below) in milliseconds. The default is 5 ms. @@ -983,78 +992,78 @@ call to inject-DTMF won't be sent to **--dtmf-log-dest=** or **--listen-tcp-ng** gaps in the output audio. If set too high, output audio will have an unnecessary latency added to it. -- **audio-player=****on-demand**\|**play-media**\|**transcoding**\|**always** +- __audio-player=on-demand__\|__play-media__\|__transcoding__\|__always__ Define when to enable the audio player if not explicitly instructed otherwise. - The default setting is **on-demand**. + The default setting is __on-demand__. - Enabling the audio player for a party to a call makes **rtpengine** produce its + Enabling the audio player for a party to a call makes __rtpengine__ produce its own audio RTP stream (instead of just forwarding an audio stream received from elsewhere). The audio is generated from a circular audio buffer (see above) and all contributing audio sources are mixed into that one audio buffer. Contributing audio sources are audio streams received from elsewhere (that - would otherwise simply be forwarded) and audio produced by the **play media** + would otherwise simply be forwarded) and audio produced by the __play media__ command. - With this set to **on-demand**, the audio player is enabled only if explicitly - requested by the user for a particular call via the **audio-player=** option + With this set to __on-demand__, the audio player is enabled only if explicitly + requested by the user for a particular call via the __audio-player=__ option used in a signalling message. - When set to **play-media**, the audio player is enabled only while media - playback via the **play media** command is active. After media playback is + When set to __play-media__, the audio player is enabled only while media + playback via the __play media__ command is active. After media playback is finished, the audio player is again disabled and audio goes back to simply being forwarded. - Setting this option to **transcoding** leaves the audio player disabled unless + Setting this option to __transcoding__ leaves the audio player disabled unless any sort of transcoding is required for a call. - With a setting of **always**, the audio player is enabled for all calls, unless - explicitly disabled via the **audio-player=** option used in a signalling + With a setting of __always__, the audio player is enabled for all calls, unless + explicitly disabled via the __audio-player=__ option used in a signalling message. This forces all audio through the transcoding engine, even if input and output codecs are the same. Audio player usage can be changed on a call-by-call basis by including the - **audio-player=** option in a signalling message. This option supports the - values **transcoding** and **always**, which result in the behaviour described - just above, and **off** which forces the audio player to be disabled regardless + __audio-player=__ option in a signalling message. This option supports the + values __transcoding__ and __always__, which result in the behaviour described + just above, and __off__ which forces the audio player to be disabled regardless of this setting. -- **--poller-per-thread** +- __\-\-poller-per-thread__ Enable 'poller per thread' functionality: for every worker thread (see the - \--num-threads option) a poller will be created. With this option on, it is + \\-\-num-threads option) a poller will be created. With this option on, it is guaranteed that only a single thread will ever read from a particular socket, thus maintaining the order of the packets. Might help when having issues with DTMF packets (RFC 2833). -- **--dtls-cert-cipher=****prime256v1**\|**RSA** +- __\-\-dtls-cert-cipher=prime256v1__\|__RSA__ Choose the type of key to use for the signature used by the self-signed - certificate used for DTLS. The previous default was **RSA**. The current default - and the only other option is **prime256v1** which is a 256-bit elliptic-curve + certificate used for DTLS. The previous default was __RSA__. The current default + and the only other option is __prime256v1__ which is a 256-bit elliptic-curve key. -- **--dtls-signature=****SHA-256**\|**SHA-1** +- __\-\-dtls-signature=SHA-256__\|__SHA-1__ Choose the hash algorithm to use for the signature used by the self-signed - certificate used for DTLS. The default is **SHA-256**. Not to be confused with + certificate used for DTLS. The default is __SHA-256__. Not to be confused with the hash algorithm used for the certificate fingerprint inserted into the SDP - (**a=fingerprint:**), which is independent of the certificate's signature and + (__a=fingerprint:__), which is independent of the certificate's signature and can be selected during runtime. -- **--dtls-rsa-key-size=**_INT_ +- __\-\-dtls-rsa-key-size=__*INT* Size in bits of the RSA key used by the DTLS certificate, if RSA is in use. Default is 2048 bits. -- **--dtls-ciphers=**_STRING_ +- __\-\-dtls-ciphers=__*STRING* Ciphers allowed during the DTLS key exchange (not to be confused with the cipher used by the DTLS certificate). The format of this string is an OpenSSL cipher list. The default is - **DEFAULT:!NULL:!aNULL:!SHA256:!SHA384:!aECDH:!AESGCM+AES256:!aPSK** + __DEFAULT:!NULL:!aNULL:!SHA256:!SHA384:!aECDH:!AESGCM+AES256:!aPSK__ -- **--dtls-mtu=**_INT_ +- __\-\-dtls-mtu=__*INT* Set DTLS MTU to enable fragmenting of large DTLS packets. Defaults to 1200. Minimum value is 576 as the internet protocol requires that hosts must be able to @@ -1062,180 +1071,180 @@ call to inject-DTMF won't be sent to **--dtmf-log-dest=** or **--listen-tcp-ng** This does not preclude link layers with an MTU smaller than this minimum MTU from conveying IP data. Internet IPv4 path MTU is 68 bytes. -- **--mqtt-host=**_HOST_\|_IP_ +- __\-\-mqtt-host=__*HOST*\|*IP* Host or IP address of the Mosquitto broker to connect to. Must be set to enable exporting stats to Mosquitto. -- **--mqtt-port=**_INT_ +- __\-\-mqtt-port=__*INT* Port of the Mosquitto broker. Defaults to 1883. -- **--mqtt-id=**_STRING_ +- __\-\-mqtt-id=__*STRING* Client ID to use for Mosquitto. Default is a generated random string. -- **--mqtt-keepalive=**_INT_ +- __\-\-mqtt-keepalive=__*INT* Keepalive interval in seconds. Defaults to 30. -- **--mqtt-user=**_USERNAME_ -- **--mqtt-pass=**_PASSWORD_ +- __\-\-mqtt-user=__*USERNAME* +- __\-\-mqtt-pass=__*PASSWORD* Credentials to connect to Mosquitto broker. At least a username must be given to enable authentication. -- **--mqtt-cafile=**_FILE_ -- **--mqtt-capath=**_PATH_ -- **--mqtt-certfile=**_FILE_ -- **--mqtt-keyfile=**_FILE_ -- **--mqtt-tls-alpn=**_STRING_ +- __\-\-mqtt-cafile=__*FILE* +- __\-\-mqtt-capath=__*PATH* +- __\-\-mqtt-certfile=__*FILE* +- __\-\-mqtt-keyfile=__*FILE* +- __\-\-mqtt-tls-alpn=__*STRING* Enable TLS to connect to Mosquitto broker, optionally with client certificate - authentication. At least **cafile** or **capath** must be given to enable TLS. To - enable client certificate authentication, both **certfile** and **keyfile** must + authentication. At least __cafile__ or __capath__ must be given to enable TLS. To + enable client certificate authentication, both __certfile__ and __keyfile__ must be set. All files must be in PEM format. Password-proteted files are not - supported. The **tls-alpn** can be set (e.g. mqtt) if a service like AWS IoT + supported. The __tls-alpn__ can be set (e.g. mqtt) if a service like AWS IoT Core shares the same TLS port for two different network protocols. -- **--mqtt-publish-qos=****0**\|**1**\|**2** +- __\-\-mqtt-publish-qos=0__\|__1__\|__2__ QoS value to use for publishing to Mosquitto. See Mosquitto docs for details. -- **--mqtt-publish-topic=**_STRING_ +- __\-\-mqtt-publish-topic=__*STRING* Topic string to use for publishing to Mosquitto. Must be set to a non-empty string. -- **--mqtt-publish-interval=**_MILLISECONDS_ +- __\-\-mqtt-publish-interval=__*MILLISECONDS* Interval in milliseconds to publish to Mosquitto. Defaults to 5000 (5 seconds). -- **--mqtt-publish-scope=****global**\|**summary**\|**call**\|**media** +- __\-\-mqtt-publish-scope=global__\|__summary__\|__call__\|__media__ - When set to **summary**, one message will be published to Mosquitto every - _interval_ milliseconds containing all global stats. A setting of **global** - has the same effect as **summary** but will also contain a list of all running - calls with stats for each call. When set to **call**, one message per call will - be published to Mosquitto with stats for that call every _interval_ - milliseconds, plus one message every _interval_ milliseconds with global - stats. When set to **media**, one message per call media (usually one media per + When set to __summary__, one message will be published to Mosquitto every + *interval* milliseconds containing all global stats. A setting of __global__ + has the same effect as __summary__ but will also contain a list of all running + calls with stats for each call. When set to __call__, one message per call will + be published to Mosquitto with stats for that call every *interval* + milliseconds, plus one message every *interval* milliseconds with global + stats. When set to __media__, one message per call media (usually one media per call participant, so usually 2 media per call) will be published to Mosquitto - with stats for that call media every _interval_ milliseconds, plus one message - every _interval_ milliseconds with global stats. + with stats for that call media every *interval* milliseconds, plus one message + every *interval* milliseconds with global stats. -- **--mos=****CQ**\|**LQ** +- __\-\-mos=CQ__\|__LQ__ - MOS (Mean Opinion Score) calculation formula. Defaults to **CQ** (conversational + MOS (Mean Opinion Score) calculation formula. Defaults to __CQ__ (conversational quality) which takes RTT into account and therefore requires peers to correctly - send RTCP. If set to **LQ** (listening quality) RTT is ignored, allowing a MOS to + send RTCP. If set to __LQ__ (listening quality) RTT is ignored, allowing a MOS to be calculated in the absence of RTCP. -- **--measure-rtp** +- __\-\-measure-rtp__ Enable measuring RTP metrics even for plain RTP passthrough scenarios. Without that option, RTP metrics are measured only in transcoding scenarios. -- **--socket-cpu-affinity=**_INT_ +- __\-\-socket-cpu-affinity=__*INT* - Enables setting the socket CPU affinity via the **SO\_INCOMING\_CPU** socket + Enables setting the socket CPU affinity via the __SO\*INCOMING\*CPU__ socket option if available. The default value is zero which disables this feature. If set to a positive number then the CPU affinity for all sockets belonging to the same call will be set to the same value. The number specifies the upper limit of the affinity to be set, and values will be used in a round-robin fashion - (e.g. if set to **8** then the values **0** through **7** will be used to set the + (e.g. if set to __8__ then the values __0__ through __7__ will be used to set the affinity). If this option is set to a negative number, then the number of available CPU cores will be used. ## INTERFACES -The command-line options **-i** or **--interface**, or equivalently the -**interface** config file option, specify local network interfaces for RTP. +The command-line options __-i__ or __\-\-interface__, or equivalently the +__interface__ config file option, specify local network interfaces for RTP. At least one must be given, but multiple can be specified. -The format of the value is \[_NAME_**/**\]_IP_\[!_IP_\] with _IP_ being +The format of the value is \[*NAME*/\]*IP*\[!*IP*\] with *IP* being either an IPv4 address, an IPv6 address, the name of a system network interface -(such as _eth0_), a DNS host name (such as _test.example.com_), or **any**. +(such as *eth0*), a DNS host name (such as *test.example.com*), or __any__. The possibility of configuring a network interface by name rather than by address should not be confused with the logical interface name used -internally by **rtpengine** (as described below). -The _NAME_ token in the syntax above refers to the internal logical +internally by __rtpengine__ (as described below). +The *NAME* token in the syntax above refers to the internal logical interface name, while the name of a system network interface is used -in place of the first _IP_ token in the syntax above. -For example, to configure a logical network interface called _int_ +in place of the first *IP* token in the syntax above. +For example, to configure a logical network interface called *int* using all the addresses from the existing system network interface -_eth0_, you would use the syntax _int/eth0_. -(Unless omitted, the second _IP_ token used for the advertised address +*eth0*, you would use the syntax *int/eth0*. +(Unless omitted, the second *IP* token used for the advertised address must be an actual network address and cannot be an interface name.) If DNS host names are used instead of addresses or interface names, the lookup will be done only once during daemon start-up. -The special keyword **any** can be used to listen on any and all available local +The special keyword __any__ can be used to listen on any and all available local interface addresses except from loopback devices. This keyword should only be given once in place of a more explicit interface configuration. To configure multiple interfaces using the command-line options, -simply present multiple **-i** or **--interface** options. -When using the config file, only use a single **interface** line, +simply present multiple __-i__ or __\-\-interface__ options. +When using the config file, only use a single __interface__ line, but specify multiple values separated by semicolons (e.g. -_interface = internal/12.23.34.45;external/23.34.45.54_). +*interface = internal/12.23.34.45;external/23.34.45.54*). If an interface option is given using a system interface name in place of a network address, and if multiple network address are found -configured on that network interface, then **rtpengine** behaves as -if multiple **--interface** options had been specified. -For example, if interface _eth0_ exists with both addresses -_192.168.1.120_ and _2001:db8:85a3::7334_ configured on it, and if -the option _--interface=ext/eth0_ is given, then **rtpengine** would -behave as if both options _--interface=ext/192.168.1.120_ and -_--interface=ext/2001:db8:85a3::7334_ had been specified. +configured on that network interface, then __rtpengine__ behaves as +if multiple __\-\-interface__ options had been specified. +For example, if interface *eth0* exists with both addresses +*192.168.1.120* and *2001:db8:85a3::7334* configured on it, and if +the option *\-\-interface=ext/eth0* is given, then __rtpengine__ would +behave as if both options *\-\-interface=ext/192.168.1.120* and +*\-\-interface=ext/2001:db8:85a3::7334* had been specified. The second IP address after the exclamation point is optional and can be used if the address to advertise in outgoing SDP bodies should be different from the actual local address. This can be useful in certain cases, such as your SIP proxy being behind NAT. -For example, _--interface=10.65.76.2!192.0.2.4_ means that _10.65.76.2_ +For example, *\-\-interface=10.65.76.2!192.0.2.4* means that *10.65.76.2* is the actual local address on the server, but outgoing SDP bodies should -advertise _192.0.2.4_ as the address that endpoints should talk to. +advertise *192.0.2.4* as the address that endpoints should talk to. Note that you may have to escape the exclamation point from your shell -when using command-line options, e.g. using _\\!_. +when using command-line options, e.g. using *\\!*. Giving an interface a name (separated from the address by a slash) is -optional; if omitted, the name **default** is used. +optional; if omitted, the name __default__ is used. Names are useful to create logical interfaces which consist of one or more local addresses. -It is then possible to instruct **rtpengine** to use particular interfaces +It is then possible to instruct __rtpengine__ to use particular interfaces when processing an SDP message, to use different local addresses when talking to different endpoints. The most common use case for this is to bridge between one or more private IP networks and the public internet. For example, if clients coming from a private IP network must communicate -their RTP with the local address _10.35.2.75_, while clients coming from +their RTP with the local address *10.35.2.75*, while clients coming from the public internet must communicate with your other local address -_192.0.2.67_, you could create one logical interface _pub_ and a second -one _priv_ by using _--interface=pub/192.0.2.67 --interface=priv/10.35.2.75_. -You can then use the **direction** option to tell **rtpengine** which local -address to use for which endpoints (either _pub_ or _priv_). +*192.0.2.67*, you could create one logical interface *pub* and a second +one *priv* by using *\-\-interface=pub/192.0.2.67 \-\-interface=priv/10.35.2.75*. +You can then use the __direction__ option to tell __rtpengine__ which local +address to use for which endpoints (either *pub* or *priv*). -If multiple logical interfaces are configured, but the **direction** +If multiple logical interfaces are configured, but the __direction__ option is not given in a particular call, then the first interface given on the command line will be used. It is possible to specify multiple addresses for the same logical interface (the same name). Most commonly this would be one IPv4 addrsess and one IPv6 address, -for example: _--interface=192.168.63.1 --interface=fe80::800:27ff:fe00:0_. +for example: *\-\-interface=192.168.63.1 \-\-interface=fe80::800:27ff:fe00:0*. In this example, no interface name is given, therefore both addresses -will be added to a logical interface named **default**. -You would use the **address family** option to tell **rtpengine** which +will be added to a logical interface named __default__. +You would use the __address family__ option to tell __rtpengine__ which address to use in a particular case. It is also possible to have multiple addresses of the same family in a logical network interface. In this case, the first address (of a particular family) given for an -interface will be the primary address used by **rtpengine** for most +interface will be the primary address used by __rtpengine__ for most purposes. Any additional addresses will be advertised as additional ICE candidates with increasingly lower priority. @@ -1244,14 +1253,14 @@ best possible path to reach the RTP proxy. If ICE is not being used, then additional addresses will go unused, even though ports would still get allocated on those interfaces. -Another option is to give interface names in the format _BASE:SUFFIX_. +Another option is to give interface names in the format *BASE:SUFFIX*. This allows interfaces to be used in a round-robin fashion, useful for load-balancing the port ranges of multiple interfaces. For example, consider the following configuration: -_--interface=pub:1/192.0.2.67 --interface=pub:2/10.35.2.75_. +*\-\-interface=pub:1/192.0.2.67 \-\-interface=pub:2/10.35.2.75*. These two interfaces can still be referenced directly by name (e.g. -_direction=pub:1_), but it is now also possible to reference only -the base name (i.e. _direction=pub_). +*direction=pub:1*), but it is now also possible to reference only +the base name (i.e. *direction=pub*). If the base name is used, one of the two interfaces is selected in a round-robin fashion, and only if the interface actually has enough open ports available. @@ -1259,55 +1268,55 @@ This makes it possible to effectively increase the number of available media ports across multiple IP addresses. There is no limit on how many interfaces can share the same base name. -It is possible to combine the _BASE:SUFFIX_ notation with specifying +It is possible to combine the *BASE:SUFFIX* notation with specifying multiple addresses for the same interface name. An advanced example could be (using config file notation, and omitting actual network addresses): interface = pub:1/IPv4 pub:1/IPv4 pub:1/IPv6 pub:2/IPv4 pub:2/IPv6 pub:3/IPv6 pub:4/IPv4 -In this example, when _direction=pub_ is IPv4 is needed as a primary -address, either _pub:1_, _pub:2_, or _pub:4_ might be selected. -When _pub:1_ is selected, one IPv4 and one IPv6 address will be used +In this example, when *direction=pub* is IPv4 is needed as a primary +address, either *pub:1*, *pub:2*, or *pub:4* might be selected. +When *pub:1* is selected, one IPv4 and one IPv6 address will be used as additional ICE alternatives. -For _pub:2_, only one IPv6 is used as ICE alternative, and for _pub:4_ +For *pub:2*, only one IPv6 is used as ICE alternative, and for *pub:4* no alternatives would be used. -When IPv6 is needed as a primary address, either _pub:1_, _pub:2_, or -_pub:3_ might be selected. +When IPv6 is needed as a primary address, either *pub:1*, *pub:2*, or +*pub:3* might be selected. If at any given time not enough ports are available on any interface, it will not be selected by the round-robin algorithm. -It is possible to use the round-robin algorithm even if the **direction** +It is possible to use the round-robin algorithm even if the __direction__ is not given. -If the first given interface has the _BASE:SUFFIX_ format then the +If the first given interface has the *BASE:SUFFIX* format then the round-robin algorithm is used and will select interfaces with the -same _BASE_ name. +same *BASE* name. If you are not using the NG protocol but rather the legacy UDP protocol -used by the **rtpproxy** module, the interfaces must be named **internal** -and **external** corresponding to the **i** and **e** flags if you wish to +used by the __rtpproxy__ module, the interfaces must be named __internal__ +and __external__ corresponding to the __i__ and __e__ flags if you wish to use network bridging in this mode. ## EXIT STATUS -- **0** +- __0__ Successful termination. -- **1** +- __1__ An error occurred. ## ENVIRONMENT -- **RTPENGINE\_REDIS\_AUTH\_PW** +- __RTPENGINE\*REDIS\*AUTH\*PW__ Redis server password for persistent state storage. -- **RTPENGINE\_REDIS\_WRITE\_AUTH\_PW** +- __RTPENGINE\*REDIS\*WRITE\*AUTH\*PW__ - Redis server password for write operations, if **--redis** has been - specified, in which case the one specified in **--redis** will be used for + Redis server password for write operations, if __\-\-redis__ has been + specified, in which case the one specified in __\-\-redis__ will be used for read operations only. ## FILES diff --git a/lib/common.Makefile b/lib/common.Makefile index c9947dd65..1dea55701 100644 --- a/lib/common.Makefile +++ b/lib/common.Makefile @@ -34,11 +34,12 @@ $(DAEMONSRCS) $(HASHSRCS): $(patsubst %,../daemon/%,$(DAEMONSRCS)) $(patsubst %, echo '#line 1' && \ cat ../daemon/"$@" ) > "$@" -%.8: %.8.ronn - ronn -r \ - --organization="NGCP rtpengine" \ - --date="$(RELEASE_DATE)" \ - "$<" +%.8: ../docs/%.md + cat "$<" | sed '/^# /d; s/^##/#/' | \ + pandoc -s -t man \ + -M "footer:$(RTPENGINE_VERSION)" \ + -M "date:$(shell date -I)" \ + -o "$@" resample.c codeclib.strhash.c mix.c: fix_frame_channel_layout.h diff --git a/recording-daemon/rtpengine-recording.8.ronn b/recording-daemon/rtpengine-recording.8.ronn deleted file mode 120000 index 1dcc4538b..000000000 --- a/recording-daemon/rtpengine-recording.8.ronn +++ /dev/null @@ -1 +0,0 @@ -../docs/rtpengine-recording.md \ No newline at end of file