Skip to content

Commit

Permalink
rtpengine: add loop-protect README
Browse files Browse the repository at this point in the history
  • Loading branch information
@razvancrainea
razvancrainea committed Apr 18, 2018
1 parent 1968810 commit e73bda6
Show file tree
Hide file tree
Showing 2 changed files with 80 additions and 74 deletions.
150 changes: 76 additions & 74 deletions modules/rtpengine/README
View file
Expand Up @@ -26,15 +26,15 @@ Richard Fuchs

Sipwise GmbH

Copyright © 2003-2008 Sippy Software, Inc.
Copyright � 2003-2008 Sippy Software, Inc.

Copyright © 2005 Voice Sistem SRL
Copyright � 2005 Voice Sistem SRL

Copyright © 2009-2014 TuTPro Inc.
Copyright � 2009-2014 TuTPro Inc.

Copyright © 2010 VoIPEmbedded Inc.
Copyright � 2010 VoIPEmbedded Inc.

Copyright © 2013-2014 Sipwise GmbH
Copyright � 2013-2014 Sipwise GmbH
__________________________________________________________

Table of Contents
Expand Down Expand Up @@ -143,7 +143,7 @@ Chapter 1. Admin Guide
Load-balancing will be performed over a set and the admin has
the ability to choose what set should be used. The set is
selected via its id - the id being defined with the set. Refer
to the “rtpengine_sock” module parameter definition for syntax
to the "rtpengine_sock" module parameter definition for syntax
description.

The balancing inside a set is done automatically by the module
Expand Down Expand Up @@ -192,7 +192,7 @@ Chapter 1. Admin Guide
Definition of socket(s) used to connect to (a set) RTP proxy.
It may specify a UNIX socket or an IPv4/IPv6 UDP socket.

Default value is “NONE” (disabled).
Default value is "NONE" (disabled).

Example 1.1. Set rtpengine_sock parameter
...
Expand All @@ -215,7 +215,7 @@ modparam("rtpengine", "rtpengine_sock",
communication to that RTP proxy for rtpengine_disable_tout
seconds.

Default value is “60”.
Default value is "60".

Example 1.2. Set rtpengine_disable_tout parameter
...
Expand All @@ -226,7 +226,7 @@ modparam("rtpengine", "rtpengine_disable_tout", 20)

Timeout value in waiting for reply from RTP proxy.

Default value is “1”.
Default value is "1".

Example 1.3. Set rtpengine_tout parameter
...
Expand All @@ -238,7 +238,7 @@ modparam("rtpengine", "rtpengine_tout", 2)
How many times the module should retry to send and receive
after timeout was generated.

Default value is “5”.
Default value is "5".

Example 1.4. Set rtpengine_retr parameter
...
Expand All @@ -247,11 +247,11 @@ modparam("rtpengine", "rtpengine_retr", 2)

1.4.5. extra_id_pv (string)

The parameter sets the PV defination to use when the “b”
The parameter sets the PV defination to use when the "b"
parameter is used on rtpengine_delete(), rtpengine_offer(),
rtpengine_answer() or rtpengine_manage() command.

Default is empty, the “b” parameter may not be used then.
Default is empty, the "b" parameter may not be used then.

Example 1.5. Set extra_id_pv parameter
...
Expand All @@ -277,7 +277,7 @@ modparam("rtpengine", "setid_avp", "$avp(setid)")
of specifying them in the script (rtpengine_sock module
parameter).

Default value is “NULL”, no database is used.
Default value is "NULL", no database is used.

Example 1.7. Set db_url parameter
...
Expand All @@ -290,7 +290,7 @@ modparam("rtpengine", "db_url",
The table where the RTPEngines sockets are stored. Used when
Database URL is provisioned.

Default value is “rtpengines”.
Default value is "rtpengines".

Example 1.8. Set db_table parameter
...
Expand All @@ -301,7 +301,7 @@ modparam("rtpengine", "db_table", "rtpengine_new")

The name of the rtpengine socket column in the database table.

Default value is “socket”.
Default value is "socket".

Example 1.9. Set socket_column parameter
...
Expand All @@ -312,7 +312,7 @@ modparam("rtpengine", "socket_column", "sock")

The name of the rtpengine set column in the database table.

Default value is “set_id”.
Default value is "set_id".

Example 1.10. Set set_column parameter
...
Expand Down Expand Up @@ -346,58 +346,58 @@ rtpengine_offer();

Meaning of the parameters is as follows:
* flags(optional) - flags to turn on some features.
The “flags” string is a list of space-separated items. Each
The "flags" string is a list of space-separated items. Each
item is either an individual token, or a token in
“key=value” format. The possible tokens are described
"key=value" format. The possible tokens are described
below.
When passing an option that OpenSIPS is not aware of, it
will be blindly sent to the rtpengine daemon to be
processed.
+ via-branch=... - Include the “branch” value of one of
the “Via” headers in the request to the RTP proxy.
Possible values are: “1” - use the first “Via” header;
“2” - use the second “Via” header; “auto” - use the
first “Via” header if this is a request, or the second
one if this is a reply; “extra” - don't take the value
+ via-branch=... - Include the "branch" value of one of
the "Via" headers in the request to the RTP proxy.
Possible values are: "1" - use the first "Via" header;
"2" - use the second "Via" header; "auto" - use the
first "Via" header if this is a request, or the second
one if this is a reply; "extra" - don't take the value
from a header, but instead use the value of the
“extra_id_pv” variable. This can be used to create one
"extra_id_pv" variable. This can be used to create one
media session per branch on the RTP proxy. When
sending a subsequent “delete” command to the RTP
sending a subsequent "delete" command to the RTP
proxy, you can then stop just the session for a
specific branch when passing the flag '1' or '2' in
the “rtpengine_delete”, or stop all sessions for a
the "rtpengine_delete", or stop all sessions for a
call when not passing one of those two flags there.
This is especially useful if you have serially forked
call scenarios where the RTP proxy gets an “offer”
command for a new branch, and then a “delete” command
call scenarios where the RTP proxy gets an "offer"
command for a new branch, and then a "delete" command
for the previous branch, which would otherwise delete
the full call, breaking the subsequent “answer” for
the full call, breaking the subsequent "answer" for
the new branch. This flag is only supported by the
Sipwise rtpengine RTP proxy at the moment!
+ asymmetric - flags that UA from which message is
received doesn't support symmetric RTP. (automatically
sets the 'r' flag)
+ force-answer - force “answer”, that is, only rewrite
+ force-answer - force "answer", that is, only rewrite
SDP when corresponding session already exists in the
RTP proxy. By default is on when the session is to be
completed.
+ in-iface=..., out-iface=... - these flags specify the
direction the SIP message. These flags only make sense
when the RTP proxy is running in bridge mode.
“in-iface” should indicate the proxy's inbound
interface, and “out-iface” corresponds to the RTP
"in-iface" should indicate the proxy's inbound
interface, and "out-iface" corresponds to the RTP
proxy's outbound interface. You always have to specify
two flags to define the incoming network and the
outgoing network. For example, “in-iface=internal
out-iface=external” should be used for SIP message
outgoing network. For example, "in-iface=internal
out-iface=external" should be used for SIP message
received from the local interface and sent out on the
external interface.
+ internal, external - these the old flags used to
specify the direction of call. They are now obsolate,
being replaced by the “in-iface=internal
out-iface=external” configuration.
being replaced by the "in-iface=internal
out-iface=external" configuration.
+ auto-bridge - this flag an alternative to the
“internal” and “external” flags in order to do
"internal" and "external" flags in order to do
automatic bridging between IPv4 on the "internal
network" and IPv6 on the "external network". Instead
of explicitly instructing the RTP proxy to select a
Expand All @@ -406,16 +406,16 @@ rtpengine_offer();
Not supported by Sipwise rtpengine.
+ address-family=... - instructs the RTP proxy that the
recipient of this SDP body expects to see addresses of
a particular family. Possible values are “IP4” and
“IP6”. For example, if the SDP body contains IPv4
a particular family. Possible values are "IP4" and
"IP6". For example, if the SDP body contains IPv4
addresses but the recipient only speaks IPv6, you
would use “address-family=IP6” to bridge between the
would use "address-family=IP6" to bridge between the
two address families.
Sipwise rtpengine remembers the address family
preference of each party after it has seen an SDP body
from them. This means that normally it is only
necessary to explicitly specify the address family in
the “offer”, but not in the “answer”.
the "offer", but not in the "answer".
Note: Please note, that this will only work properly
with non-dual-stack user-agents or with dual-stack
clients according to RFC6157 (which suggest ICE for
Expand Down Expand Up @@ -454,14 +454,16 @@ rtpengine_offer();
bitrate codecs, for example with G.729 going from 10ms
to 100ms saves two thirds of the network bandwith. Not
supported by Sipwise rtpengine.
+ loop-protect - flag that instructs RTP to avoid
rewriting the SDP when looping the same message.
+ ICE=... - controls the RTP proxy's behaviour regarding
ICE attributes within the SDP body. Possible values
are: “force” - discard any ICE attributes already
are: "force" - discard any ICE attributes already
present in the SDP body and then generate and insert
new ICE data, leaving itself as the only ICE
candidates; “remove” instructs the RTP proxy to
candidates; "remove" instructs the RTP proxy to
discard any ICE attributes and not insert any new ones
into the SDP. The default (if no “ICE=...” is given at
into the SDP. The default (if no "ICE=..." is given at
all), new ICE data will only be generated if no ICE
was present in the SDP originally; otherwise the RTP
proxy will only insert itself as an additional ICE
Expand All @@ -471,45 +473,45 @@ rtpengine_offer();
transport protocol that should be used towards the
recipient of the SDP. If none of them are specified,
the protocol given in the SDP is left untouched.
Otherwise, the “SRTP” flag indicates that SRTP should
be used, while “RTP” indicates that SRTP should not be
used. “AVPF” indicates that the advanced RTCP profile
with feedback messages should be used, and “AVP”
Otherwise, the "SRTP" flag indicates that SRTP should
be used, while "RTP" indicates that SRTP should not be
used. "AVPF" indicates that the advanced RTCP profile
with feedback messages should be used, and "AVP"
indicates that the regular RTCP profile should be
used. See also the next set of flags below.
+ RTP/AVP, RTP/SAVP, RTP/AVPF, RTP/SAVPF - these serve
as an alternative, more explicit way to select between
the different RTP protocols and profiles supported by
the RTP proxy. For example, giving the flag
“RTP/SAVPF” has the same effect as giving the two
flags “SRTP AVPF”.
+ to-tag - force inclusion of the “To” tag. Normally,
the “To” tag is always included when present, except
for “delete” messages. Including the “To” tag in a
“delete” messages allows you to be more selective
"RTP/SAVPF" has the same effect as giving the two
flags "SRTP AVPF".
+ to-tag - force inclusion of the "To" tag. Normally,
the "To" tag is always included when present, except
for "delete" messages. Including the "To" tag in a
"delete" messages allows you to be more selective
about which dialogues within a call are being torn
down.
+ rtcp-mux-demux - if rtcp-mux (RFC 5761) was offered,
make the RTP proxy accept the offer, but not offer it
to the recipient of this message.
+ rtcp-mux-reject - if rtcp-mux was offered, make the
RTP proxy reject the offer, but still offer it to the
recipient. Can be combined with “rtcp-mux-offer” to
recipient. Can be combined with "rtcp-mux-offer" to
always offer it.
+ rtcp-mux-offer - make the RTP proxy offer rtcp-mux to
the recipient of this message, regardless of whether
it was offered originally or not.
+ rtcp-mux-accept - if rtcp-mux was offered, make the
RTP proxy accept the offer and also offer it to the
recipient of this message. Can be combined with
“rtcp-mux-offer” to always offer it.
"rtcp-mux-offer" to always offer it.
+ media-address=... - force a particular media address
to be used in the SDP body. Address family is detected
automatically.
+ record-call=yes/no - indicates whether rtpengine
should record the call or not. When using this
parameter, you may pass further information in the
“metadata”.
"metadata".
+ transcode-CODEC - used only for offer, indicates that
rtpengine should transcode the CODEC towards the
B-side. Example: transcode-PCMA will present to the
Expand Down Expand Up @@ -625,7 +627,7 @@ rtpengine_offer("... codec-mask-PCMA codec-strip-opus transcode-opus ...

See rtpengine_offer() function description above for the
meaning of the parameters. Note that not all flags make sense
for a “delete”.
for a "delete".

This function can be used from ANY_ROUTE.

Expand Down Expand Up @@ -790,7 +792,7 @@ $ opensipsctl fifo rtpengine_show
1.7.3. rtpengine_reload

Reloads all rtpengine sets from the database. Used only when
the “db_url” parameter is set.
the "db_url" parameter is set.

No parameter.

Expand All @@ -804,8 +806,8 @@ $ opensipsctl fifo rtpengine_reload
Terminates the SIP dialog by the SIP Call-ID given as
parameter.

Note this is a just a wrapper function over the “dlg_end_dlg”
MI function provided by the “dialog” module. This wrapping is
Note this is a just a wrapper function over the "dlg_end_dlg"
MI function provided by the "dialog" module. This wrapping is
done just to make rtpengine happy when trying to terminate SIP
calls based on RTP timeouts.

Expand All @@ -818,32 +820,32 @@ Chapter 2. Frequently Asked Questions

2.1.

How do I migrate from “rtpproxy” or “rtpproxy-ng” to
“rtpengine”?
How do I migrate from "rtpproxy" or "rtpproxy-ng" to
"rtpengine"?

For the most part, only the names of the functions have
changed, with “rtpproxy” in each name replaced with
“rtpengine”. For example, “rtpproxy_manage()” has become
“rtpengine_manage()”. A few name duplications have also been
changed, with "rtpproxy" in each name replaced with
"rtpengine". For example, "rtpproxy_manage()" has become
"rtpengine_manage()". A few name duplications have also been
resolved, for example there is now a single
“rtpengine_delete()” instead of “unforce_rtp_proxy()” and the
identical “rtpproxy_destroy()”.
"rtpengine_delete()" instead of "unforce_rtp_proxy()" and the
identical "rtpproxy_destroy()".

The largest difference to the old module is how flags are
passed to “rtpengine_offer()”, “rtpengine_answer()”,
“rtpengine_manage()” and “rtpengine_delete()”. Instead of
passed to "rtpengine_offer()", "rtpengine_answer()",
"rtpengine_manage()" and "rtpengine_delete()". Instead of
having a string of single-letter flags, they now take a string
of space-separated items, with each item being either a single
token (word) or a “key=value” pair.
token (word) or a "key=value" pair.

For example, if you had a call “rtpproxy_offer("FRWOC+PS");”,
For example, if you had a call "rtpproxy_offer("FRWOC+PS");",
this would then become:
rtpengine_offer("force trust-address symmetric replace-origin replace-se
ssion-connection ICE=force RTP/SAVPF");

Finally, if you were using the second parameter (explicit media
address) to any of these functions, this has been replaced by
the “media-address=...” option within the first string of
the "media-address=..." option within the first string of
flags.

2.2.
Expand Down
4 changes: 4 additions & 0 deletions modules/rtpengine/doc/rtpengine_admin.xml
View file
Expand Up @@ -472,6 +472,10 @@ rtpengine_offer();
Not supported by Sipwise rtpengine.
</para></listitem>
<listitem><para>
<emphasis>loop-protect</emphasis> - flag that instructs &rtp; to
avoid rewriting the SDP when looping the same message.
</para></listitem>
<listitem><para>
<emphasis>ICE=...</emphasis> - controls the &rtp; proxy's behaviour
regarding ICE attributes within the &sdp; body. Possible values
are: <quote>force</quote> -
Expand Down

0 comments on commit e73bda6

Please sign in to comment.