mirror of https://github.com/sipwise/rtpengine.git
Change-Id: I837d65c624cf1cabad543236b0a4e36f57894babchanges/36/25936/3
Guillem Jover
7 years ago
parent
1129676528
commit
1f10dc30d5
@ -0,0 +1,782 @@
|
||||
=head1 NAME
|
||||
|
||||
rtpengine - NGCP proxy for RTP and other UDP based media traffic
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
B<rtpengine> B<--interface>=I<addr>... B<--listen-tcp>|B<--listen-udp>|B<--listen-ng>=I<addr>... [I<option>...]
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
The Sipwise NGCP rtpengine is a proxy for RTP traffic and other UDP based
|
||||
media traffic.
|
||||
It is meant to be used with the Kamailio SIP proxy and forms a drop-in
|
||||
replacement for any of the other available RTP and media proxies.
|
||||
|
||||
=head1 OPTIONS
|
||||
|
||||
Most of these options are indeed optional, with two exceptions. It's
|
||||
mandatory to specify at least one local IP address through B<--interface>,
|
||||
and at least one of the B<--listen->I<...> options must be given.
|
||||
|
||||
=over 4
|
||||
|
||||
=item B<--help>
|
||||
|
||||
Print the usage information.
|
||||
|
||||
=item B<-v>, B<--version>
|
||||
|
||||
If called with this option, the B<rtpengine> daemon will simply print its
|
||||
version number and exit.
|
||||
|
||||
=item B<--codecs>
|
||||
|
||||
Print a list of supported codecs and exit.
|
||||
|
||||
=item B<--config-file>
|
||||
|
||||
Specifies the location of a config file to be used. The config file is an
|
||||
I<.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. B<table> instead of just B<t>) must be
|
||||
used in the config file.
|
||||
For boolean options that are either present or not (e.g. B<no-fallback>), a
|
||||
boolean value (either B<true> or B<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 L<INTERFACES> below for an example).
|
||||
|
||||
As a special value, B<none> can be passed here to suppress loading of the
|
||||
default config file.
|
||||
|
||||
=item B<--config-section>
|
||||
|
||||
Specifies the I<.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 B<rtpengine>.
|
||||
A config file section is started in the config file using square brackets
|
||||
(e.g. B<[rtpengine]>).
|
||||
|
||||
=item B<-t>, B<--table=>I<INT>
|
||||
|
||||
Takes an integer argument and specifies which kernel table to use for
|
||||
in-kernel packet forwarding.
|
||||
See the section on in-kernel operation in the F<README.md> for more detail.
|
||||
Optional and defaults to zero.
|
||||
If in-kernel operation is not desired, a negative number can be specified.
|
||||
|
||||
=item B<-F>, B<--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.
|
||||
|
||||
=item B<-i>, B<--interface=>[I<NAME>B</>]I<IP>[B<!>I<IP>]
|
||||
|
||||
Specifies a local network interface for RTP.
|
||||
At least one must be given, but multiple can be specified.
|
||||
See the section L<INTERFACES> just below for details.
|
||||
|
||||
=item B<-l>, B<--listen-tcp=>[I<IP>B<:>]I<PORT>
|
||||
|
||||
=item B<-u>, B<--listen-udp=>[I<IP46>B<:>]I<PORT>
|
||||
|
||||
=item B<-n>, B<--listen-ng=>[I<IP46>B<:>]I<PORT>
|
||||
|
||||
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 I<address:port>
|
||||
pair, separated by colon.
|
||||
At least one of these 3 options must be given.
|
||||
|
||||
The B<tcp> protocol is obsolete.
|
||||
It was used by old versions of B<OpenSER> and its B<mediaproxy> module.
|
||||
It is provided for backwards compatibility.
|
||||
|
||||
The B<udp> protocol is used by B<Kamailio>'s B<rtpproxy> module.
|
||||
In this mode, B<rtpengine> can be used as a drop-in replacement for any
|
||||
other compatible RTP proxy.
|
||||
|
||||
The B<ng> protocol is an advanced control protocol and can be used with
|
||||
B<Kamailio>'s B<rtpengine> module.
|
||||
With this protocol, the complete SDP body is passed to B<rtpengine>,
|
||||
rewritten and passed back to B<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
|
||||
B<127.0.0.1> as interface to bind to.
|
||||
|
||||
=item B<-c>, B<--listen-cli=>[I<IP46>:]I<PORT>
|
||||
|
||||
TCP ip and port to listen for the CLI (command line interface).
|
||||
|
||||
=item B<-g>, B<--graphite=>I<IP46>:I<PORT>
|
||||
|
||||
Address of the graphite statistics server.
|
||||
|
||||
=item B<-w>, B<--graphite-interval=>I<INT>
|
||||
|
||||
Interval of the time when information is sent to the graphite server.
|
||||
|
||||
=item B<--graphite-prefix=>I<STRING>
|
||||
|
||||
Add a prefix for every graphite line.
|
||||
|
||||
=item B<-t>, B<--tos=>I<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 (B<Expedited Forwarding>).
|
||||
|
||||
=item B<--control-tos=>I<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 B<rtpengine-ctl>.
|
||||
|
||||
=item B<-o>, B<--timeout=>I<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 B<rtpengine>'s internal state table.
|
||||
Defaults to 60 seconds.
|
||||
|
||||
=item B<-s>, B<--silent-timeout=>I<SECS>
|
||||
|
||||
Ditto as the B<--timeout> option, but applies to muted or inactive media
|
||||
streams.
|
||||
Defaults to 3600 (one hour).
|
||||
|
||||
=item B<-a>, B<--final-timeout=>I<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.
|
||||
|
||||
=item B<--offer-timeout=>I<SECS>
|
||||
|
||||
This timeout (in seconds) is applied to calls which only had an B<offer>
|
||||
but no B<answer>.
|
||||
Defaults to 3600 (one hour).
|
||||
|
||||
=item B<-p>, B<--pidfile=>I<FILE>
|
||||
|
||||
Specifies a path and file name to write the daemon's PID number to.
|
||||
|
||||
=item B<-f>, B<--foreground>
|
||||
|
||||
If given, prevents the daemon from daemonizing, meaning it will stay in
|
||||
the foreground.
|
||||
Useful for debugging.
|
||||
|
||||
=item B<-m>, B<--port-min=>I<INT>
|
||||
|
||||
=item B<-M>, B<--port-max=>I<INT>
|
||||
|
||||
Both take an integer as argument and together define the local port range
|
||||
from which B<rtpengine> will allocate UDP ports for media traffic relay.
|
||||
Default to 30000 and 40000 respectively.
|
||||
|
||||
=item B<-L>, B<--log-level=>I<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) 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.
|
||||
|
||||
=item B<--log-facilty=>B<daemon>|B<local0>|...|B<local7>|...
|
||||
|
||||
The syslog facilty to use when sending log messages to the syslog daemon.
|
||||
Defaults to B<daemon>.
|
||||
|
||||
=item B<--log-facilty-cdr=>B<daemon>|B<local0>|...|B<local7>|...
|
||||
|
||||
Same as B<--log-facility> with the difference that only CDRs are written
|
||||
to this log facility.
|
||||
|
||||
=item B<--log-facilty-rtcp=>B<daemon>|B<local0>|...|B<local7>|...
|
||||
|
||||
Same as B<--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.
|
||||
|
||||
=item B<--log-facilty-dtmf=>B<daemon>|B<local0>|...|B<local7>|...
|
||||
|
||||
Same as B<--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.
|
||||
|
||||
=item B<--log-format=>B<default>|B<parsable>
|
||||
|
||||
Selects between multiple log output styles.
|
||||
The default is to prefix log lines with a description of the relevant
|
||||
entity, such as B<[CALLID]> or B<[CALLID port 12345]>.
|
||||
The B<parsable> output style is similar, but makes the ID easier to
|
||||
parse by enclosing it in quotes, such as B<[ID="CALLID"]>
|
||||
or B<[ID="CALLID" port="12345"]>.
|
||||
|
||||
=item B<--log-srtp-keys>
|
||||
|
||||
Write SRTP keys to error log instead of debug log.
|
||||
|
||||
=item B<-E>, B<--log-stderr>
|
||||
|
||||
Log to stderr instead of syslog.
|
||||
Only useful in combination with B<--foreground>.
|
||||
|
||||
=item B<--num-threads=>I<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, the default is four.
|
||||
|
||||
=item B<--sip-source>
|
||||
|
||||
The original B<rtpproxy> as well as older version of B<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 B<rtpengine> reverse this behaviour and honour the
|
||||
addresses given in the SDP body by default. This option restores the
|
||||
old behaviour.
|
||||
|
||||
=item B<--dtls-passive>
|
||||
|
||||
Enables the B<DTLS=passive> flag for all calls unconditionally.
|
||||
|
||||
=item B<-d>, B<--delete-delay>
|
||||
|
||||
Delete the call from memory after the specified delay from memory.
|
||||
Can be set to zero for immediate call deletion.
|
||||
|
||||
=item B<-r>, B<--redis=>[I<PW>B<@>]I<IP>B<:>I<PORT>B</>I<INT>
|
||||
|
||||
Connect to specified Redis database (with the given database number) and
|
||||
use it for persistence storage.
|
||||
The format of this option is I<ADDRESS>:I<PORT>/I<DBNUM>, for example
|
||||
I<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 B<@> symbol, for example I<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 B<RTPENGINE_REDIS_AUTH_PW>.
|
||||
|
||||
On startup, B<rtpengine> will read the contents of this database and
|
||||
restore all calls stored therein.
|
||||
During runtime operation, B<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, B<rtpengine> will delay startup until the
|
||||
Redis database adopts the master role (but see below).
|
||||
|
||||
=item B<-w>, B<--redis-write=>[I<PW>B<@>]I<IP>B<:>I<PORT>B</>I<INT>
|
||||
|
||||
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 B<RTPENGINE_REDIS_WRITE_AUTH_PW>.
|
||||
|
||||
When both options are given, B<rtpengine> will start and use the Redis
|
||||
database regardless of the database's role (master or slave).
|
||||
|
||||
=item B<-k>, B<--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 B<rtpengine-ctl ksadd/ksrm>.
|
||||
This may lead to enabling/disabling of the redis keyspace notification feature.
|
||||
|
||||
=item B<--redis-num-threads=>I<INT>
|
||||
|
||||
How many redis restore threads to create.
|
||||
The default is 4.
|
||||
|
||||
=item B<--redis-expires=>I<INT>
|
||||
|
||||
Expire time in seconds for redis keys.
|
||||
Default is 86400.
|
||||
|
||||
=item B<--redis-multikey>
|
||||
|
||||
Use multiple redis keys for storing the call (old behaviour). B<DEPRECATED>.
|
||||
|
||||
=item B<-q>, B<--no-redis-required>
|
||||
|
||||
When this parameter is present or B<NO_REDIS_REQUIRED='yes'> or B<'1'> in
|
||||
the config file, B<rtpengine> starts even if there is no initial connection
|
||||
to redis databases (either to B<-r> or to B<-w> or to both redis).
|
||||
|
||||
Be aware that if the B<-r> redis cannot be initially connected, sessions
|
||||
are not reloaded upon rtpengine startup, even though rtpengine still starts.
|
||||
|
||||
=item B<--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 B<rtpengine-ctl>.
|
||||
|
||||
=item B<--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 B<rtpengine-ctl>.
|
||||
|
||||
=item B<--redis-cmd-timeout=>I<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 B<rtpengine-ctl>; note that
|
||||
setting the parameter to 0 will require a reconnect on all configured
|
||||
redis servers.
|
||||
|
||||
=item B<--redis-connect-timeout=>I<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 B<PING> command
|
||||
is issued before attempting to connect so the B<--redis-cmd-timeout> value
|
||||
will also be added to the total waiting time.
|
||||
This is useful if using B<--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 B<rtpengine-ctl>.
|
||||
|
||||
=item B<-b>, B<--b2b-url=>I<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 B<%%> 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 B<xmlrpc-callback> B<ng> protocol option) will be used.
|
||||
|
||||
=item B<-x>, B<--xmlrpc-format=>I<INT>
|
||||
|
||||
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.
|
||||
|
||||
=item B<--max-sessions=>I<INT>
|
||||
|
||||
Limit the number of maximum concurrent sessions.
|
||||
Set at startup via B<MAX_SESSIONS> in config file.
|
||||
Set at runtime via B<rtpengine-ctl> util.
|
||||
Setting the B<rtpengine-ctl set maxsessions 0> can be used in draining
|
||||
rtpengine sessions.
|
||||
Enable feature: B<MAX_SESSIONS=1000>
|
||||
Enable feature: B<rtpengine-ctl set maxsessions> >= 0
|
||||
Disable feature: B<rtpengine-ctl set maxsessions -1>
|
||||
By default, the feature is disabled (i.e. maxsessions == -1).
|
||||
|
||||
=item B<--max-load=>I<FLOAT>
|
||||
|
||||
If the current 1-minute load average exceeds the value given here,
|
||||
reject new sessions until the load average drops below the threshold.
|
||||
|
||||
=item B<--max-cpu=>I<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 F</proc/stat>.
|
||||
|
||||
=item B<--max-bandwidth=>I<INT>
|
||||
|
||||
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.
|
||||
|
||||
=item B<--homer=>I<IP46>B<:>I<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.
|
||||
|
||||
=item B<--homer-protocol=>B<udp>|B<tcp>
|
||||
|
||||
Can be either B<udp> or B<tcp> with B<udp> being the default.
|
||||
|
||||
=item B<--homer-id=>I<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.
|
||||
|
||||
=item B<--recording-dir=>I<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.
|
||||
|
||||
B<rtpengine> supports multiple mechanisms for recording calls.
|
||||
See B<recording-method> below for a list.
|
||||
The default recording method B<pcap> is described in this section.
|
||||
|
||||
PCAP files will be stored within a F<pcap> subdirectory and metadata
|
||||
within a F<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.
|
||||
|
||||
=item B<--recording-method=>B<pcap>|B<proc>
|
||||
|
||||
Multiple methods of call recording are supported and this option can be
|
||||
used to select one.
|
||||
Currently supported are the method B<pcap> and B<proc>.
|
||||
The default method is B<pcap> and is the one described above.
|
||||
|
||||
The recording method B<proc> works by writing metadata files directly into
|
||||
the B<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 F</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.
|
||||
|
||||
=item B<--recording-format=>B<raw>|B<eth>
|
||||
|
||||
When recording to pcap file in B<raw> (default) format, there is no
|
||||
ethernet header.
|
||||
When set to B<eth>, a fake ethernet header is added, making each package
|
||||
14 bytes larger.
|
||||
|
||||
=item B<--iptables-chain=>I<STRING>
|
||||
|
||||
This option enables explicit management of an iptables chain.
|
||||
When enabled, B<rtpengine> takes control of the given iptables chain,
|
||||
which must exist already prior to starting the daemon.
|
||||
Upon startup, B<rtpengine> will flush the chain, and then add one B<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 B<DROP> policy for
|
||||
the entire port range used by B<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 B<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 B<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.
|
||||
|
||||
=item B<--scheduling=>B<default>|...
|
||||
|
||||
=item B<--priority=>I<INT>
|
||||
|
||||
=item B<--idle-scheduling=>B<default>|...
|
||||
|
||||
=item B<--idle-priority=>I<INT>
|
||||
|
||||
These options control various thread scheduling parameters.
|
||||
The B<scheduling> and B<priority> settings are applied to the main
|
||||
worker threads, while the B<idle-> versions of these settings are
|
||||
applied to various lower priority threads, such as timer runs.
|
||||
|
||||
The B<scheduling> settings take the name of one of the supported
|
||||
scheduler policies.
|
||||
Setting it to B<default> or B<none> is equivalent to not setting the
|
||||
option at all and leaves the system default in place.
|
||||
The strings B<fifo> and B<rr> refer to realtime scheduling policies.
|
||||
B<other> is the Linux default scheduling policy.
|
||||
B<batch> is similar to B<other> except for a small wake-up scheduling
|
||||
penalty.
|
||||
B<idle> is an extremely low priority scheduling policy.
|
||||
The Linux-specific B<deadline> policy is not supported by B<rtpengine>.
|
||||
Not all systems necessarily supports all scheduling policies; refer to
|
||||
your system's sched(7) man page for details.
|
||||
|
||||
The B<priority> settings correspond to the scheduling priority for
|
||||
realtime (B<fifo> or B<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
|
||||
B<priority> settings correspond to the B<nice> value and should be in
|
||||
the range of -20 (high) through 19 (low).
|
||||
Not all systems support thread-specific B<nice> values; on such a system,
|
||||
using these settings might have unexpected results.
|
||||
(Linux does support thread-specific B<nice> values.)
|
||||
Refer to your system's sched(7) man page.
|
||||
|
||||
=back
|
||||
|
||||
=head1 INTERFACES
|
||||
|
||||
The command-line options B<-i> or B<--interface>, or equivalently the
|
||||
B<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 [I<NAME>B</>]I<IP>[!I<IP>] with I<IP> being
|
||||
either an IPv4 address, an IPv6 address, or the name of a system network
|
||||
interface (such as I<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 B<rtpengine> (as described below).
|
||||
The I<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 I<IP> token in the syntax above.
|
||||
For example, to configure a logical network interface called I<int>
|
||||
using all the addresses from the existing system network interface
|
||||
I<eth0>, you would use the syntax I<int/eth0>.
|
||||
(Unless omitted, the second I<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 B<-i> or B<--interface> options.
|
||||
When using the config file, only use a single B<interface> line,
|
||||
but specify multiple values separated by semicolons (e.g.
|
||||
I<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 B<rtpengine> behaves as
|
||||
if multiple B<--interface> options had been specified.
|
||||
For example, if interface I<eth0> exists with both addresses
|
||||
I<192.168.1.120> and I<2001:db8:85a3::7334> configured on it, and if
|
||||
the option I<--interface=ext/eth0> is given, then B<rtpengine> would
|
||||
behave as if both options I<--interface=ext/192.168.1.120> and
|
||||
I<--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, I<--interface=10.65.76.2!192.0.2.4> means that I<10.65.76.2>
|
||||
is the actual local address on the server, but outgoing SDP bodies should
|
||||
advertise I<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 I<\!>.
|
||||
|
||||
Giving an interface a name (separated from the address by a slash) is
|
||||
optional; if omitted, the name B<default> is used.
|
||||
Names are useful to create logical interfaces which consist of one or
|
||||
more local addresses.
|
||||
It is then possible to instruct B<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 I<10.35.2.75>, while clients coming from
|
||||
the public internet must communicate with your other local address
|
||||
I<192.0.2.67>, you could create one logical interface I<pub> and a second
|
||||
one I<priv> by using I<--interface=pub/192.0.2.67 --interface=priv/10.35.2.75>.
|
||||
You can then use the B<direction> option to tell B<rtpengine> which local
|
||||
address to use for which endpoints (either I<pub> or I<priv>).
|
||||
|
||||
If multiple logical interfaces are configured, but the B<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: I<--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 B<default>.
|
||||
You would use the B<address family> option to tell B<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 B<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 I<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:
|
||||
I<--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.
|
||||
I<direction=pub:1>), but it is now also possible to reference only
|
||||
the base name (i.e. I<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 I<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 I<direction=pub> is IPv4 is needed as a primary
|
||||
address, either I<pub:1>, I<pub:2>, or I<pub:4> might be selected.
|
||||
When I<pub:1> is selected, one IPv4 and one IPv6 address will be used
|
||||
as additional ICE alternatives.
|
||||
For I<pub:2>, only one IPv6 is used as ICE alternative, and for I<pub:4>
|
||||
no alternatives would be used.
|
||||
When IPv6 is needed as a primary address, either I<pub:1>, I<pub:2>, or
|
||||
I<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 B<direction>
|
||||
is not given.
|
||||
If the first given interface has the I<BASE:SUFFIX> format then the
|
||||
round-robin algorithm is used and will select interfaces with the
|
||||
same I<BASE> name.
|
||||
|
||||
If you are not using the NG protocol but rather the legacy UDP protocol
|
||||
used by the B<rtpproxy> module, the interfaces must be named B<internal>
|
||||
and B<external> corresponding to the B<i> and B<e> flags if you wish to
|
||||
use network bridging in this mode.
|
||||
|
||||
=head1 EXIT STATUS
|
||||
|
||||
=over
|
||||
|
||||
=item B<0>
|
||||
|
||||
Successful termination.
|
||||
|
||||
=item B<1>
|
||||
|
||||
An error ocurred.
|
||||
|
||||
=back
|
||||
|
||||
=head1 ENVIRONMENT
|
||||
|
||||
=over
|
||||
|
||||
=item B<RTPENGINE_REDIS_AUTH_PW>
|
||||
|
||||
Redis server password for persistent state storage.
|
||||
|
||||
=item B<RTPENGINE_REDIS_WRITE_AUTH_PW>
|
||||
|
||||
Redis server password for write operations, if B<--redis> has been
|
||||
specified, in which case the one specified in B<--redis> will be used for
|
||||
read operations only.
|
||||
|
||||
=back
|
||||
|
||||
=head1 FILES
|
||||
|
||||
=over
|
||||
|
||||
=item F</etc/rtpengine/rtpengine.conf>
|
||||
|
||||
Configuration file.
|
||||
|
||||
=back
|
||||
|
||||
=head1 EXAMPLES
|
||||
|
||||
A typical command line (enabling both UDP and NG protocols) may look like:
|
||||
|
||||
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
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<kamailio(8)>.
|
||||
@ -0,0 +1 @@
|
||||
daemon/rtpengine.8
|
||||
Loading…
Reference in new issue