sipwise
/
kamailio
mirror of https://github.com/sipwise/kamailio.git
1
0
Fork 0
Code Issues Releases Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '8a4d548034'
${ noResults }
kamailio/modules/rtpproxy-ng/README

626 lines
21 KiB
Raw Blame History

rtpproxy-ng Module
Maxim Sobolev
Sippy Software, Inc.
Juha Heinanen
TuTPro, Inc.
Edited by
Maxim Sobolev
Edited by
Bogdan-Andrei Iancu
Edited by
Juha Heinanen
Edited by
Sas Ovidiu
Edited by
Carsten Bock
ng-voice GmbH
Edited by
Richard Fuchs
Sipwise GmbH
Copyright © 2003-2008 Sippy Software, Inc.
Copyright © 2005 Voice Sistem SRL
Copyright © 2009-2012 TuTPro Inc.
Copyright © 2010 VoIPEmbedded Inc.
Copyright © 2013 Sipwise GmbH
__________________________________________________________________
Table of Contents
1. Admin Guide
1. Overview
2. Multiple RTPProxy usage
3. Dependencies
3.1. Kamailio Modules
3.2. External Libraries or Applications
4. Parameters
4.1. rtpproxy_sock (string)
4.2. rtpproxy_disable_tout (integer)
4.3. rtpproxy_tout (integer)
4.4. rtpproxy_retr (integer)
4.5. extra_id_pv (string)
5. Functions
5.1. set_rtp_proxy_set(setid)
5.2. rtpproxy_offer([flags [, ip_address]])
5.3. rtpproxy_answer([flags [, ip_address]])
5.4. rtpproxy_destroy([flags])
5.5. unforce_rtp_proxy()
5.6. rtpproxy_manage([flags [, ip_address]])
6. Exported Pseudo Variables
6.1. $rtpstart
7. MI Commands
7.1. nh_enable_rtpp
7.2. nh_show_rtpp
2. Frequently Asked Questions
List of Examples
1.1. Set rtpproxy_sock parameter
1.2. Set rtpproxy_disable_tout parameter
1.3. Set rtpproxy_tout parameter
1.4. Set rtpproxy_retr parameter
1.5. Set extra_id_pv parameter
1.6. set_rtp_proxy_set usage
1.7. rtpproxy_offer usage
1.8. rtpproxy_answer usage
1.9. rtpproxy_destroy usage
1.10. rtpproxy_manage usage
1.11. $rtpstat-Usage
1.12. nh_enable_rtpp usage
1.13. nh_show_rtpp usage
Chapter 1. Admin Guide
Table of Contents
1. Overview
2. Multiple RTPProxy usage
3. Dependencies
3.1. Kamailio Modules
3.2. External Libraries or Applications
4. Parameters
4.1. rtpproxy_sock (string)
4.2. rtpproxy_disable_tout (integer)
4.3. rtpproxy_tout (integer)
4.4. rtpproxy_retr (integer)
4.5. extra_id_pv (string)
5. Functions
5.1. set_rtp_proxy_set(setid)
5.2. rtpproxy_offer([flags [, ip_address]])
5.3. rtpproxy_answer([flags [, ip_address]])
5.4. rtpproxy_destroy([flags])
5.5. unforce_rtp_proxy()
5.6. rtpproxy_manage([flags [, ip_address]])
6. Exported Pseudo Variables
6.1. $rtpstart
7. MI Commands
7.1. nh_enable_rtpp
7.2. nh_show_rtpp
1. Overview
This is a module that enables media streams to be proxied via an RTP
proxy. The only RTP proxy currently known to work with this module is
the Sipwise ngcp-rtpproxy-ng https://github.com/sipwise/mediaproxy-ng.
The rtpproxy-ng module is a modified version of the original rtpproxy
module using a new control protocol. The module is designed to be a
drop-in replacement for the old module from a configuration file point
of view, however due to the incompatible control protocol, it only
works with RTP proxies which specifically support it.
2. Multiple RTPProxy usage
The rtpproxy-ng module can support multiple RTP proxies for
balancing/distribution and control/selection purposes.
The module allows definition of several sets of rtpproxies.
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 “rtpproxy_sock”
module parameter definition for syntax description.
The balancing inside a set is done automatically by the module based on
the weight of each rtpproxy from the set.
The selection of the set is done from script prior using
unforce_rtp_proxy(), rtpproxy_offer() or rtpproxy_answer() functions -
see the set_rtp_proxy_set() function.
For backward compatibility reasons, a set with no id take by default
the id 0. Also if no set is explicitly set before unforce_rtp_proxy(),
rtpproxy_offer() or rtpproxy_answer() the 0 id set will be used.
IMPORTANT: if you use multiple sets, take care and use the same set for
both rtpproxy_offer()/rtpproxy_answer() and unforce_rtpproxy()!!
3. Dependencies
3.1. Kamailio Modules
3.2. External Libraries or Applications
3.1. Kamailio Modules
The following modules must be loaded before this module:
* tm module - (optional) if you want to have rtpproxy_manage() fully
functional
3.2. External Libraries or Applications
The following libraries or applications must be installed before
running Kamailio with this module loaded:
* None.
4. Parameters
4.1. rtpproxy_sock (string)
4.2. rtpproxy_disable_tout (integer)
4.3. rtpproxy_tout (integer)
4.4. rtpproxy_retr (integer)
4.5. extra_id_pv (string)
4.1. rtpproxy_sock (string)
Definition of socket(s) used to connect to (a set) RTPProxy. It may
specify a UNIX socket or an IPv4/IPv6 UDP socket.
Default value is “NONE” (disabled).
Example 1.1. Set rtpproxy_sock parameter
...
# single rtproxy
modparam("rtpproxy-ng", "rtpproxy_sock", "udp:localhost:12221")
# multiple rtproxies for LB
modparam("rtpproxy-ng", "rtpproxy_sock",
"udp:localhost:12221 udp:localhost:12222")
# multiple sets of multiple rtproxies
modparam("rtpproxy-ng", "rtpproxy_sock",
"1 == udp:localhost:12221 udp:localhost:12222")
modparam("rtpproxy-ng", "rtpproxy_sock",
"2 == udp:localhost:12225")
...
4.2. rtpproxy_disable_tout (integer)
Once an RTP proxy was found unreachable and marked as disabled, the
rtpproxy-ng module will not attempt to establish communication to that
RTP proxy for rtpproxy_disable_tout seconds.
Default value is “60”.
Example 1.2. Set rtpproxy_disable_tout parameter
...
modparam("rtpproxy-ng", "rtpproxy_disable_tout", 20)
...
4.3. rtpproxy_tout (integer)
Timeout value in waiting for reply from RTP proxy.
Default value is “1”.
Example 1.3. Set rtpproxy_tout parameter
...
modparam("rtpproxy-ng", "rtpproxy_tout", 2)
...
4.4. rtpproxy_retr (integer)
How many times the module should retry to send and receive after
timeout was generated.
Default value is “5”.
Example 1.4. Set rtpproxy_retr parameter
...
modparam("rtpproxy-ng", "rtpproxy_retr", 2)
...
4.5. extra_id_pv (string)
The parameter sets the PV defination to use when the “b” parameter is
used on unforce_rtp_proxy(), rtpproxy_offer(), rtpproxy_answer() or
rtpproxy_manage() command.
Default is empty, the “b” parameter may not be used then.
Example 1.5. Set extra_id_pv parameter
...
modparam("rtpproxy-ng", "extra_id_pv", "$avp(extra_id)")
...
5. Functions
5.1. set_rtp_proxy_set(setid)
5.2. rtpproxy_offer([flags [, ip_address]])
5.3. rtpproxy_answer([flags [, ip_address]])
5.4. rtpproxy_destroy([flags])
5.5. unforce_rtp_proxy()
5.6. rtpproxy_manage([flags [, ip_address]])
5.1. set_rtp_proxy_set(setid)
Sets the Id of the rtpproxy set to be used for the next
unforce_rtp_proxy(), rtpproxy_offer(), rtpproxy_answer() or
rtpproxy_manage() command. The parameter can be an integer or a config
variable holding an integer.
This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
BRANCH_ROUTE.
Example 1.6. set_rtp_proxy_set usage
...
set_rtp_proxy_set("2");
rtpproxy_offer();
...
5.2. rtpproxy_offer([flags [, ip_address]])
Rewrites SDP body to ensure that media is passed through an RTP proxy.
To be invoked on INVITE for the cases the SDPs are in INVITE and 200 OK
and on 200 OK when SDPs are in 200 OK and ACK.
Meaning of the parameters is as follows:
* flags - flags to turn on some features.
+ 1 - append first Via branch to Call-ID when sending command to
rtpproxy. This can be used to create one media session per
branch on the rtpproxy. When sending a subsequent “delete”
command to the rtpproxy, you can then stop just the session
for a specific branch when passing the flag '1' or '2' in the
“unforce_rtpproxy”, 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
rtpproxy 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 new branch. This flag is only supported by
the ngcp-mediaproxy-ng rtpproxy at the moment!
+ 2 - append second Via branch to Call-ID when sending command
to rtpproxy. See flag '1' for its meaning.
+ 3 - behave like flag 1 is set for a request and like flag 2 is
set for a reply.
+ a - flags that UA from which message is received doesn't
support symmetric RTP. (automatically sets the 'r' flag)
+ b - append branch specific variable to Call-ID when sending
command to rtpproxy. This creates one rtpproxy session per
unique variable. Works similar to the 1, 2 and 3 parameter,
but is usefull when forking to multiple destinations on
different address families or network segments, requiring
different rtpproxy parameters. The variable value is taken
from the “extra_id_pv”. When used, it must be used in every
call to rtpproxy_manage(), rtpproxy_offer(), rtpproxy_answer()
and rtpproxy_destroy() with the same contents of the PV. The b
parameter may not be used in conjunction with the 1, 2 or 3
parameter to use the Via branch in the Call-ID.
+ l - force “lookup”, 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.
+ i, e - these flags specify the direction of the SIP message.
These flags only make sense when rtpproxy is running in bridge
mode. 'i' means internal network (LAN), 'e' means external
network (WAN). 'i' corresponds to rtpproxy's first interface,
'e' corresponds to rtpproxy's second interface. You always
have to specify two flags to define the incoming network and
the outgoing network. For example, 'ie' should be used for SIP
message received from the local interface and sent out on the
external interface, and 'ei' vice versa. Other options are
'ii' and 'ee'. So, for example if a SIP requests is processed
with 'ie' flags, the corresponding response must be processed
with 'ie' flags.
For ngcp-mediaproxy-ng, these flags are used to select between
IPv4 and IPv6 addresses, corresponding to 'i' and 'e'
respectively. For example, if the request is coming from an
IPv4 host and is going to an IPv6 host, the flags should be
specified as 'ie'.
Note: As rtpproxy in bridge mode s per default asymmetric, you
have to specify the 'w' flag for clients behind NAT! See also
above notes!
+ x - this flag an alternative to the 'ie' or 'ei'-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 particular
address family, the distinction is done by the given IP in the
SDP body by the RTP proxy itself. Not supported by
ngcp-mediaproxy-ng.
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 Dual-Stack
implementations). This short-cut will not work properly with
RFC4091 (ANAT) compatible clients, which suggests having
different m-lines with different IP-protocols grouped
together.
+ f - instructs rtpproxy to ignore marks inserted by another
rtpproxy in transit to indicate that the session is already
goes through another proxy. Allows creating a chain of
proxies.
+ r - flags that IP address in SDP should be trusted. Without
this flag, rtpproxy ignores address in the SDP and uses source
address of the SIP message as media address which is passed to
the RTP proxy.
+ o - flags that IP from the origin description (o=) should be
also changed.
+ c - flags to change the session-level SDP connection (c=) IP
if media-description also includes connection information.
+ w - flags that for the UA from which message is received,
support symmetric RTP must be forced.
+ zNN - requests the RTPproxy to perform re-packetization of RTP
traffic coming from the UA which has sent the current message
to increase or decrease payload size per each RTP packet
forwarded if possible. The NN is the target payload size in
ms, for the most codecs its value should be in 10ms
increments, however for some codecs the increment could differ
(e.g. 30ms for GSM or 20ms for G.723). The RTPproxy would
select the closest value supported by the codec. This feature
could be used for significantly reducing bandwith overhead for
low bitrate codecs, for example with G.729 going from 10ms to
100ms saves two thirds of the network bandwith.
+ + - instructs the RTP proxy to 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.
Without this flag, 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 candidate. Other
SDP substitutions (c=, m=, etc) are unaffected by this flag.
+ - - instructs the RTP proxy to discard any ICE attributes and
not insert any new ones into the SDP. Mutually exclusive with
the '+' flag.
* ip_address - new SDP IP address.
This function can be used from ANY_ROUTE.
Example 1.7. rtpproxy_offer usage
route {
...
if (is_method("INVITE")) {
if (has_sdp()) {
if (rtpproxy_offer())
t_on_reply("1");
} else {
t_on_reply("2");
}
}
if (is_method("ACK") && has_sdp())
rtpproxy_answer();
...
}
onreply_route[1]
{
...
if (has_sdp())
rtpproxy_answer();
...
}
onreply_route[2]
{
...
if (has_sdp())
rtpproxy_offer();
...
}
5.3. rtpproxy_answer([flags [, ip_address]])
Rewrites SDP body to ensure that media is passed through an RTP proxy.
To be invoked on 200 OK for the cases the SDPs are in INVITE and 200 OK
and on ACK when SDPs are in 200 OK and ACK.
See rtpproxy_answer() function description above for the meaning of the
parameters.
This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
FAILURE_ROUTE, BRANCH_ROUTE.
Example 1.8. rtpproxy_answer usage
See rtpproxy_offer() function example above for example.
5.4. rtpproxy_destroy([flags])
Tears down the RTPProxy session for the current call.
This function can be used from ANY_ROUTE.
Meaning of the parameters is as follows:
* flags - flags to turn on some features.
+ 1 - append first Via branch to Call-ID when sending command to
rtpproxy. This can be used to create one media session per
branch on the rtpproxy. When sending a subsequent “delete”
command to the rtpproxy, you can then stop just the session
for a specific branch when passing the flag '1' or '2' in the
“unforce_rtpproxy”, 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
rtpproxy gets an “update” command for a new branch, and then a
“delete” command for the previous branch, which would
otherwise delete the full call, breaking the subsequent
“lookup” for the new branch. This flag is only supported by
the ngcp-mediaproxy-ng rtpproxy at the moment!
+ 2 - append second Via branch to Call-ID when sending command
to rtpproxy. See flag '1' for its meaning.
+ b - append branch specific variable to Call-ID when sending
command to rtpproxy. See rtpproxy_offer() for details.
<listitem>
</listitem>
t - do not include To tag to “delete” command to rtpproxy thus
causing full call to be deleted. Useful for deleting unused
rtpproxy call when 200 OK is received on a branch, where
rtpproxy is not needed.
Example 1.9. rtpproxy_destroy usage
...
rtpproxy_destroy();
...
5.5. unforce_rtp_proxy()
Same as rtpproxy_destroy().
5.6. rtpproxy_manage([flags [, ip_address]])
Manage the RTPProxy session - it combines the functionality of
rtpproxy_offer(), rtpproxy_answer() and unforce_rtpproxy(), detecting
internally based on message type and method which one to execute.
It can take the same parameters as rtpproxy_offer(). The flags
parameter to rtpproxy_manage() can be a configuration variable
containing the flags as a string.
Functionality:
* If INVITE with SDP, then do rtpproxy_offer()
* If INVITE with SDP, when the tm module is loaded, mark transaction
with internal flag FL_SDP_BODY to know that the 1xx and 2xx are for
rtpproxy_answer()
* If ACK with SDP, then do rtpproxy_answer()
* If BYE or CANCEL, or called within a FAILURE_ROUTE[], then do
unforce_rtpproxy()
* If reply to INVITE with code >= 300 do unforce_rtpproxy()
* If reply with SDP to INVITE having code 1xx and 2xx, then do
rtpproxy_answer() if the request had SDP or tm is not loaded,
otherwise do rtpproxy_offer()
This function can be used from ANY_ROUTE.
Example 1.10. rtpproxy_manage usage
...
rtpproxy_manage();
...
6. Exported Pseudo Variables
6.1. $rtpstart
6.1. $rtpstart
Returns the RTP-Statistics from the RTP-Proxy. The RTP-Statistics from
the RTP-Proxy are provided as a string and it does contain several
packet-counters. The statistics must be retrieved before the session is
deleted (before unforce_rtpproxy()).
Example 1.11. $rtpstat-Usage
...
append_hf("X-RTP-Statistics: $rtpstat\r\n");
...
7. MI Commands
7.1. nh_enable_rtpp
7.2. nh_show_rtpp
7.1. nh_enable_rtpp
Enables a rtp proxy if parameter value is greater than 0. Disables it
if a zero value is given.
The first parameter is the rtp proxy url (exactly as defined in the
config file).
The second parameter value must be a number in decimal.
NOTE: if a rtpproxy is defined multiple times (in the same or diferente
sete), all of its instances will be enables/disabled.
Example 1.12. nh_enable_rtpp usage
...
$ kamctl fifo nh_enable_rtpp udp:192.168.2.133:8081 0
...
7.2. nh_show_rtpp
Displays all the rtp proxies and their information: set and status
(disabled or not, weight and recheck_ticks).
No parameter.
Example 1.13. nh_show_rtpp usage
...
$ kamctl fifo nh_show_rtpp
...
Chapter 2. Frequently Asked Questions
2.1. What happend with “rtpproxy_disable” parameter?
2.2. Where can I find more about Kamailio?
2.3. Where can I post a question about this module?
2.4. How can I report a bug?
2.1.
What happend with “rtpproxy_disable” parameter?
It was removed as it became obsolete - now “rtpproxy_sock” can take
empty value to disable the rtpproxy functionality.
2.2.
Where can I find more about Kamailio?
Take a look at http://www.kamailio.org/.
2.3.
Where can I post a question about this module?
First at all check if your question was already answered on one of our
mailing lists:
* User Mailing List -
http://lists.sip-router.org/cgi-bin/mailman/listinfo/sr-users
* Developer Mailing List -
http://lists.sip-router.org/cgi-bin/mailman/listinfo/sr-dev
E-mails regarding any stable Kamailio release should be sent to
<sr-users@lists.sip-router.org> and e-mails regarding development
versions should be sent to <sr-dev@lists.sip-router.org>.
If you want to keep the mail private, send it to
<sr-users@lists.sip-router.org>.
2.4.
How can I report a bug?
Please follow the guidelines provided at:
http://sip-router.org/tracker.
Reference in new issue View Git Blame Copy Permalink