From 1f10dc30d529fd1d796fb379654f4e3d905d749b Mon Sep 17 00:00:00 2001 From: Guillem Jover Date: Fri, 21 Dec 2018 20:16:35 +0100 Subject: [PATCH] TT#49106 Move the usage information into a new man page Change-Id: I837d65c624cf1cabad543236b0a4e36f57894bab --- README.md | 620 +------------------- daemon/.gitignore | 1 + daemon/Makefile | 3 + daemon/rtpengine.pod | 782 ++++++++++++++++++++++++++ debian/ngcp-rtpengine-daemon.manpages | 1 + lib/common.Makefile | 9 +- lib/lib.Makefile | 13 +- 7 files changed, 811 insertions(+), 618 deletions(-) create mode 100644 daemon/rtpengine.pod create mode 100644 debian/ngcp-rtpengine-daemon.manpages diff --git a/README.md b/README.md index 92db786ad..a47508f01 100644 --- a/README.md +++ b/README.md @@ -179,619 +179,7 @@ Usage Userspace Daemon ---------------- -The daemon supports a number of command-line options, which it will print if started with the `--help` -option and which are reproduced below: - - -v, --version Print build time and exit - -t, --table=INT Kernel table to use - -F, --no-fallback Only start when kernel module is available - -i, --interface=[NAME/]IP[!IP] Local interface for RTP - -l, --listen-tcp=[IP:]PORT TCP port to listen on - -u, --listen-udp=[IP46:]PORT UDP port to listen on - -n, --listen-ng=[IP46:]PORT UDP port to listen on, NG protocol - -c, --listen-cli=[IP46:]PORT TCP port to listen on, CLI (command line interface) - -g, --graphite=IP46:PORT TCP address of graphite statistics server - -G, --graphite-interval=INT Graphite data statistics send interval - --graphite-prefix=STRING Graphite prefix for every line - -T, --tos=INT TOS value to set on streams - --control-tos=INT TOS value to set on control-ng interface - -o, --timeout=SECS RTP timeout - -s, --silent-timeout=SECS RTP timeout for muted - -a, --final-timeout=SECS Call timeout - --offer-timeout=SECS Timeout for incomplete one-sided calls - -p, --pidfile=FILE Write PID to file - -f, --foreground Don't fork to background - -m, --port-min=INT Lowest port to use for RTP - -M, --port-max=INT Highest port to use for RTP - -r, --redis=[PW@]IP:PORT/INT Connect to Redis database - -w, --redis-write=[PW@]IP:PORT/INT Connect to Redis write database - -k, --subscribe-keyspace Subscription keyspace list - --redis-num-threads=INT Number of Redis restore threads - --redis-expires=INT Expire time in seconds for redis keys - --redis-multikey Use multiple redis keys for storing the call (old behaviour) DEPRECATED - -q, --no-redis-required Start even if can't connect to redis databases - --redis-allowed-errors Number of allowed errors before redis is temporarily disabled - --redis-disable-time Number of seconds redis communication is disabled because of errors - --redis-cmd-timeout Sets a timeout in milliseconds for redis commands - --redis-connect-timeout Sets a timeout in milliseconds for redis connections - -b, --b2b-url=STRING XMLRPC URL of B2B UA - -L, --log-level=INT Mask log priorities above this level - --log-facility=daemon|local0|... Syslog facility to use for logging - --log-facility-cdr=local0|... Syslog facility to use for logging CDRs - --log-facility-rtcp=local0|... Syslog facility to use for logging RTCP data (take care of traffic amount) - --log-facility-dtmf=local0|... Syslog facility to use for logging DTMF - --log-format=default|parsable Log prefix format - -E, --log-stderr Log on stderr instead of syslog - -x, --xmlrpc-format=INT XMLRPC timeout request format to use. 0: SEMS DI, 1: call-id only, 2: Kamailio - --num-threads=INT Number of worker threads to create - -d, --delete-delay Delay for deleting a session from memory. - --sip-source Use SIP source address by default - --dtls-passive Always prefer DTLS passive role - --max-sessions=INT Limit the number of maximum concurrent sessions - --max-load=FLOAT Reject new sessions if load averages exceeds this value - --max-cpu=FLOAT Reject new sessions if CPU usage (in percent) exceeds this value - --max-bandwidth=INT Reject new sessions if bandwidth usage (in bytes per second) exceeds this value - --homer=IP46:PORT Address of Homer server for RTCP stats - --homer-protocol=udp|tcp Transport protocol for Homer (default udp) - --homer-id=INT 'Capture ID' to use within the HEP protocol - --recording-dir=FILE Spool directory where PCAP call recording data goes - --recording-method=pcap|proc Strategy for call recording - --recording-format=raw|eth PCAP file format for recorded calls. - --iptables-chain=STRING Add explicit firewall rules to this iptables chain - --codecs Print a list of supported codecs and exit - --scheduling=default|... Thread scheduling policy - --priority=INT Thread scheduling priority - --idle-scheduling=default|... Idle thread scheduling policy - --idle-priority=INT Idle thread scheduling priority - --log-srtp-keys Write SRTP keys to error log instead of debug log - -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. - -The options are described in more detail below. - -* -v, --version - - If called with this option, the *rtpengine* daemon will simply print its version number - and exit. - -* --config-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 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 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 configuration* below for an example). - - As a special value, `none` can be passed here to suppress loading of the default config file. - -* --config-section - - 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`. - A config file section is started in the config file using square brackets (e.g. `[rtpengine]`). - -* -t, --table - - Takes an integer argument and specifies which kernel table to use for in-kernel packet forwarding. See - the section on in-kernel operation for more detail. Optional and defaults to zero. If in-kernel - operation is not desired, a negative number can be specified. - -* -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. - -* -i, --interface - - Specifies a local network interface for RTP. At least one must be given, but multiple can be specified. - See the section *Interfaces configuration* just below for details. - -* -l, --listen-tcp, -u, --listen-udp, -n, --listen-ng - - These options each enable one of the 3 available control protocols if given 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. - It's 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 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*. Several additional features are available with this protocol, such as - ICE handling, SRTP bridging, etc. - - It is recommended to specify not only a local port number, but also 127.0.0.1 as interface to bind to. - -* -c, --listen-cli - - TCP ip and port to listen for the CLI (command line interface). - -* -g, --graphite - - Address of the graphite statistics server. - -* -w, --graphite-interval - - Interval of the time when information is sent to the graphite server. - -* --graphite-prefix - - Add a prefix for every graphite line. - -* -t, --tos - - 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*). - -* --control-tos - - 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. - -* -o, --timeout - - 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. Defaults to 60 seconds. - -* -s, --silent-timeout - - Ditto as the `--timeout` option, but applies to muted or inactive media streams. Defaults to 3600 - (one hour). - -* -a, --final-timeout - - 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 - - This timeout (in seconds) is applied to calls which only had an `offer` but no `answer`. - Defaults to 3600 (one hour). - -* -p, --pidfile - - Specifies a path and file name to write the daemon's PID number to. - -* -f, --foreground - - If given, prevents the daemon from daemonizing, meaning it will stay in the foreground. - Useful for debugging. - -* -m, --port-min, -M, --port-max - - Both take an integer as argument and together define the local port range from which *rtpengine* - will allocate UDP ports for media traffic relay. Default to 30000 and 40000 respectively. - -* -L, --log-level - - 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) man page. 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-facilty=daemon|local0|...|local7|... - - The syslog facilty to use when sending log messages to the syslog daemon. Defaults to `daemon`. - -* --log-facilty-cdr=daemon|local0|...|local7|... - - Same as --log-facility with the difference that only CDRs are written to this log facility. - -* --log-facilty-rtcp=daemon|local0|...|local7|... - - 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|... - - 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 - - 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"]`. - -* -E, --log-stderr - - Log to stderr instead of syslog. Only useful in combination with `--foreground`. - -* --num-threads - - 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, the default is - four. - -* --sip-source - - The original *rtpproxy* as well as older version of *rtpengine* by default didn't 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 addresses given in the SDP body by default. This option restores the old behaviour. - -* --dtls-passive - - Enables the `DTLS=passive` flag for all calls unconditionally. - -* -d, --delete-delay - - Delete the call from memory after the specified delay from memory. Can be set to zero for - immediate call deletion. - -* -r, --redis - - 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 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`. 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`. - - On startup, *rtpengine* will read the contents of this database and restore all calls - stored therein. 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 Redis database adopts the - master role (but see below). - -* -w, --redis-write - - Configures a second Redis database for write operations. If this option is given in addition to the - first one, then the first database will be used for read operations (i.e. to restore calls from) while - the second one will be used for write operations (to update states in the database). - - For password protected Redis servers, the environment variable for the password is - `RTPENGINE_REDIS_WRITE_AUTH_PW`. - - 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 - - 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'. - This may lead to enabling/disabling of the redis keyspace notification feature. - -* --redis-num-threads - - How many redis restore threads to create. The default is four. - -* --redis-expires - - Expire time in seconds for redis keys. Default is 86400. - -* --redis-multikey - - Use multiple redis keys for storing the call (old behaviour) DEPRECATED - -* -q, --no-redis-required - When this parameter is present or NO_REDIS_REQUIRED='yes' or '1' in 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 can't be initially connected, sessions are not reloaded upon rtpengine startup, - even though rtpengine still starts. - -* --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 before the redis communication will be temporarily disabled for that - server. While the communcation 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. - -* --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. - -* --redis-cmd-timeout - 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 setting the parameter - to 0 will require a reconnect on all configured redis servers. - -* --redis-connect-timeout - 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 will also be added to the total waiting time. - 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. - -* -b, --b2b-url - - 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 source address - of the originating request (or alternatively the address specified using the - `xmlrpc-callback` *ng* protocol option) will be used. - -* -x, --xmlrpc-format - - Selects the internal format of the XMLRPC callback message for B2BUA call teardown. 0 is for SEMS, - 1 is for a generic format containing the call-ID only, 2 is for Kamailio. - -* --max-sessions - - 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 rtpengine sessions. - 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 - - 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 - - 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 - - If the current bandwidth usage (in bytes per second) exceeds the value given here, - reject new sessions until - the bandwidth usage drops below the threshold. Bandwidth usage is sampled in 1-second intervals - and is based on received packets, not sent packets. - -* --homer - - 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 - - Can be either "udp" or "tcp" with "udp" being the default. - -* --homer-id - - 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 - - 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. - - PCAP files will be stored within a "pcap" subdirectory and metadata - within a "metadata" subdirectory. - - The format for a metadata file is (with a trailing newline): - - /path/to/recording-pcap.pcap - - SDP mode: offer - SDP before RTP packet: 1 - - first SDP - - SDP mode: answer - SDP before RTP packet: 1 - - second SDP - - ... - - SDP mode: answer - SDP before RTP packet: 100 - - n-th and final SDP - - - start timestamp (YYYY-MM-DDThh:mm:ss) - end timestamp (YYYY-MM-DDThh:mm:ss) - - - generic metadata - - There are two empty lines between each logic block of metadata. - We write out all answer SDP, each separated from one another by one empty - line. The generic metadata at the end can be any length with any number of - lines. Metadata files will appear in the subdirectory when the call - completes. PCAP files will be written to the subdirectory as the call is - being recorded. - - Since call recording via this method happens entirely in userspace, 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 - - Multiple methods of call recording are supported and this option can be used to select one. - Currently supported are the method `pcap` and `proc`. - 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 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 component - (usually a daemon such as recording-daemon included in this repository). - - Packet data is held in kernel memory until retrieved by the userspace component, but only a limited - number of packets (default 10) per media stream. If packets are not retrieved in time, they will - be simply discarded. This makes it possible to flag all calls to be recorded and then leave it - to the userspace component to decided whether to use the packet data for any purpose or not. - - In-kernel packet forwarding is fully supported with this recording method even for calls being - recorded. - -* --recording-format - - 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 14 bytes larger. - -* --iptables-chain - - This option enables explicit management of an 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` - 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 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*. - - 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 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, --priority, --idle-scheduling, --idle-priority - - 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 applied to various lower priority threads, such as timer runs. - - 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 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 penalty. `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 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 the range of -20 (high) through 19 (low). 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.) - Refer to your system's `sched(7)` man page. - -A typical command line (enabling both UDP and NG protocols) thus may look like: - - /usr/sbin/rtpengine --table=0 --interface=10.64.73.31 --interface=2001:db8::4f3:3d \ - --listen-udp=127.0.0.1:22222 --listen-ng=127.0.0.1:2223 --tos=184 \ - --pidfile=/run/rtpengine.pid - - -Interfaces configuration ------------------------- - -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 either an IPv4 address, an IPv6 address, -or the name of a system network interface (such as `eth0`). - -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 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` 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 must be an actual network address and cannot be an interface name.) - -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, but specify -multiple values separated by semicolons (e.g. `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. - -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 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. Note that you may have to escape the exlamation -point from your shell 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. 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 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 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`). - -If multiple logical interfaces are configured, but the `direction` option isn't 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`. 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 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 purposes. Any additional addresses will be advertised as additional ICE -candidates with increasingly lower priority. This is useful on multi-homed systems and allows endpoints -to choose the 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`. 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`. 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`). 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. 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 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 -as additional ICE alternatives. 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. 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` is not given. 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. - -If you're 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 use network bridging in this mode. +The options are described in detail in the rtpengine(1) man page. In-kernel Packet Forwarding --------------------------- @@ -1637,7 +1025,7 @@ Example response: { "result": "ok", "sdp": "v=0\r\no=..." } `answer` Message ---------------- +---------------- The `answer` message is identical to the `offer` message, with the additional requirement that the dictionary must contain the key `to-tag` containing the SIP `To` tag. It doesn't make sense to include @@ -1670,7 +1058,7 @@ The reply message may contain additional keys with statistics about the deleted are the same as used in the `query` reply. `list` Message ----------------- +-------------- The `list` command retrieves the list of currently active call-ids. This list is limited to 32 elements by default. @@ -1977,6 +1365,7 @@ Disables call recording for the call. This can be sent during a call to imediatl `block DTMF` and `unblock DTMF` Messages ---------------------------------------- + These message types must include the key `call-id` in the message. They enable and disable blocking of DTMF events (RFC 4733 type packets), respectively. @@ -1997,6 +1386,7 @@ of DTMF events can be enabled and disabled at any time during call runtime. `block media` and `unblock media` Messages ------------------------------------------ + Analogous to `block DTMF` and `unblock DTMF` but blocks media packets instead of DTMF packets. DTMF packets can still pass through when media blocking is enabled. Media packets can be blocked for an entire call, or directionally for individual participants. See `block DTMF` above for details. diff --git a/daemon/.gitignore b/daemon/.gitignore index 4c555ee2f..2ee5f696c 100644 --- a/daemon/.gitignore +++ b/daemon/.gitignore @@ -1,4 +1,5 @@ .depend +*.8 *.o rtpengine core diff --git a/daemon/Makefile b/daemon/Makefile index cd53d0a81..4f1cd7ce1 100644 --- a/daemon/Makefile +++ b/daemon/Makefile @@ -130,6 +130,9 @@ LIBSRCS+= codeclib.c resample.c endif OBJS= $(SRCS:.c=.o) $(LIBSRCS:.c=.o) +PODS= rtpengine.pod +MANS= $(PODS:.pod=.8) + include ../lib/common.Makefile include .depend diff --git a/daemon/rtpengine.pod b/daemon/rtpengine.pod new file mode 100644 index 000000000..94ee62586 --- /dev/null +++ b/daemon/rtpengine.pod @@ -0,0 +1,782 @@ +=head1 NAME + +rtpengine - NGCP proxy for RTP and other UDP based media traffic + +=head1 SYNOPSIS + +B B<--interface>=I... B<--listen-tcp>|B<--listen-udp>|B<--listen-ng>=I... [I