Browse code

modules/rtpproxy: some README improvements

Juha Heinanen authored on 21/10/2012 14:29:44
Showing 2 changed files
... ...
@@ -30,13 +30,13 @@ Carsten Bock
30 30
 
31 31
    ng-voice GmbH
32 32
 
33
-   Copyright � 2003-2008 Sippy Software, Inc.
33
+   Copyright © 2003-2008 Sippy Software, Inc.
34 34
 
35
-   Copyright � 2005 Voice Sistem SRL
35
+   Copyright © 2005 Voice Sistem SRL
36 36
 
37
-   Copyright � 2009 TuTPro Inc.
37
+   Copyright © 2009 TuTPro Inc.
38 38
 
39
-   Copyright � 2010 VoIPEmbedded Inc.
39
+   Copyright © 2010 VoIPEmbedded Inc.
40 40
      __________________________________________________________________
41 41
 
42 42
    Table of Contents
... ...
@@ -152,12 +152,10 @@ Chapter 1. Admin Guide
152 152
 1. Overview
153 153
 
154 154
    This is a module that enables media streams to be proxied via an
155
-   rtpproxy.
156
-
157
-   Known devices that get along over NATs with rtpproxy are ATAs (as
158
-   clients) and Cisco Gateways (since 12.2(T)) as servers. See
159
-   http://www.cisco.com/en/US/products/sw/iosswrel/ps1839/products_feature
160
-   _guide09186a0080110bf9.html">
155
+   rtpproxy. Rtpproxies know to work with this module are Sippy RTPproxy
156
+   http://www.rtpproxy.org and ngcp-rtpproxy-ng
157
+   http://deb.sipwise.com/spce/2.6/pool/main/n/ngcp-mediaproxy-ng. Some
158
+   features of rtpproxy module apply only one of the two rtpproxies.
161 159
 
162 160
 2. Multiple RTPProxy usage
163 161
 
... ...
@@ -168,7 +166,7 @@ Chapter 1. Admin Guide
168 166
    load-balancing will be performed over a set and the user has the
169 167
    ability to choose what set should be used. The set is selected via its
170 168
    id - the id being defined along with the set. Refer to the
171
-   "rtpproxy_sock" module parameter definition for syntax description.
169
+   “rtpproxy_sock” module parameter definition for syntax description.
172 170
 
173 171
    The balancing inside a set is done automatically by the module based on
174 172
    the weight of each rtpproxy from the set.
... ...
@@ -216,7 +214,7 @@ Chapter 1. Admin Guide
216 214
    Definition of socket(s) used to connect to (a set) RTPProxy. It may
217 215
    specify a UNIX socket or an IPv4/IPv6 UDP socket.
218 216
 
219
-   Default value is "NONE" (disabled).
217
+   Default value is “NONE” (disabled).
220 218
 
221 219
    Example 1.1. Set rtpproxy_sock parameter
222 220
 ...
... ...
@@ -238,7 +236,7 @@ modparam("rtpproxy", "rtpproxy_sock",
238 236
    will not attempt to establish communication to RTPProxy for
239 237
    rtpproxy_disable_tout seconds.
240 238
 
241
-   Default value is "60".
239
+   Default value is “60”.
242 240
 
243 241
    Example 1.2. Set rtpproxy_disable_tout parameter
244 242
 ...
... ...
@@ -249,7 +247,7 @@ modparam("rtpproxy", "rtpproxy_disable_tout", 20)
249 247
 
250 248
    Timeout value in waiting for reply from RTPProxy.
251 249
 
252
-   Default value is "1".
250
+   Default value is “1”.
253 251
 
254 252
    Example 1.3. Set rtpproxy_tout parameter
255 253
 ...
... ...
@@ -261,7 +259,7 @@ modparam("rtpproxy", "rtpproxy_tout", 2)
261 259
    How many times rtpproxy should retry to send and receive after timeout
262 260
    was generated.
263 261
 
264
-   Default value is "5".
262
+   Default value is “5”.
265 263
 
266 264
    Example 1.4. Set rtpproxy_retr parameter
267 265
 ...
... ...
@@ -273,7 +271,7 @@ modparam("rtpproxy", "rtpproxy_retr", 2)
273 271
    Socket to be forced in communicating to RTPProxy. It makes sense only
274 272
    for UDP communication. If no one specified, the OS will choose.
275 273
 
276
-   Default value is "NULL".
274
+   Default value is “NULL”.
277 275
 
278 276
    Example 1.5. Set force_socket parameter
279 277
 ...
... ...
@@ -291,7 +289,7 @@ Note
291 289
 
292 290
    The string must be a complete SDP line, including the EOH (\r\n).
293 291
 
294
-   Default value is "a=nortpproxy:yes\r\n".
292
+   Default value is “a=nortpproxy:yes\r\n”.
295 293
 
296 294
    Example 1.6. Set nortpproxy_str parameter
297 295
 ...
... ...
@@ -306,7 +304,7 @@ modparam("rtpproxy", "nortpproxy_str", "a=sdpmangled:yes\r\n")
306 304
    If it is an empty string, no timeout socket will be transmitted to the
307 305
    RTP-Proxy.
308 306
 
309
-   Default value is "" (nothing).
307
+   Default value is “” (nothing).
310 308
 
311 309
    Example 1.7. Set timeout_socket parameter
312 310
 ...
... ...
@@ -327,7 +325,7 @@ modparam("nathelper", "timeout_socket", "xmlrpc:http://127.0.0.1:8000/RPC2")
327 325
    5.10. start_recording()
328 326
    5.11. rtpproxy_stop_stream2uas(prompt_name, count)
329 327
 
330
-5.1. set_rtp_proxy_set(setid)
328
+5.1.  set_rtp_proxy_set(setid)
331 329
 
332 330
    Sets the Id of the rtpproxy set to be used for the next
333 331
    unforce_rtp_proxy(), rtpproxy_offer(), rtpproxy_answer() or
... ...
@@ -343,7 +341,7 @@ set_rtp_proxy_set("2");
343 341
 rtpproxy_offer();
344 342
 ...
345 343
 
346
-5.2. rtpproxy_offer([flags [, ip_address]])
344
+5.2.  rtpproxy_offer([flags [, ip_address]])
347 345
 
348 346
    Rewrites SDP body to ensure that media is passed through an RTP proxy.
349 347
    To be invoked on INVITE for the cases the SDPs are in INVITE and 200 OK
... ...
@@ -353,16 +351,16 @@ rtpproxy_offer();
353 351
      * flags - flags to turn on some features.
354 352
           + 1 - append first Via branch to Call-ID when sending command to
355 353
             rtpproxy. This can be used to create one media session per
356
-            branch on the rtpproxy. When sending a subsequent "delete"
354
+            branch on the rtpproxy. When sending a subsequent “delete”
357 355
             command to the rtpproxy, you can then stop just the session
358 356
             for a specific branch when passing the flag '1' or '2' in the
359
-            "unforce_rtpproxy", or stop all sessions for a call when not
357
+            “unforce_rtpproxy”, or stop all sessions for a call when not
360 358
             passing one of those two flags there. This is especially
361 359
             useful if you have serially forked call scenarios where
362
-            rtpproxy gets an "update" command for a new branch, and then a
363
-            "delete" command for the previous branch, which would
360
+            rtpproxy gets an “update” command for a new branch, and then a
361
+            “delete” command for the previous branch, which would
364 362
             otherwise delete the full call, breaking the subsequent
365
-            "lookup" for the new branch. This flag is only supported by
363
+            “lookup” for the new branch. This flag is only supported by
366 364
             the ngcp-mediaproxy-ng rtpproxy at the moment!
367 365
           + 2 - append second Via branch to Call-ID when sending command
368 366
             to rtpproxy. See flag '1' for its meaning.
... ...
@@ -370,7 +368,7 @@ rtpproxy_offer();
370 368
             set for a reply.
371 369
           + a - flags that UA from which message is received doesn't
372 370
             support symmetric RTP. (automatically sets the 'r' flag)
373
-          + l - force "lookup", that is, only rewrite SDP when
371
+          + l - force “lookup”, that is, only rewrite SDP when
374 372
             corresponding session is already exists in the RTP proxy. By
375 373
             default is on when the session is to be completed.
376 374
           + i, e - these flags specify the direction of the SIP message.
... ...
@@ -454,7 +452,7 @@ onreply_route[2]
454 452
 ...
455 453
 }
456 454
 
457
-5.3. rtpproxy_answer([flags [, ip_address]])
455
+5.3.  rtpproxy_answer([flags [, ip_address]])
458 456
 
459 457
    Rewrites SDP body to ensure that media is passed through an RTP proxy.
460 458
    To be invoked on 200 OK for the cases the SDPs are in INVITE and 200 OK
... ...
@@ -470,7 +468,7 @@ onreply_route[2]
470 468
 
471 469
    See rtpproxy_offer() function example above for example.
472 470
 
473
-5.4. rtpproxy_destroy([flags])
471
+5.4.  rtpproxy_destroy([flags])
474 472
 
475 473
    Tears down the RTPProxy session for the current call.
476 474
 
... ...
@@ -480,16 +478,16 @@ onreply_route[2]
480 478
      * flags - flags to turn on some features.
481 479
           + 1 - append first Via branch to Call-ID when sending command to
482 480
             rtpproxy. This can be used to create one media session per
483
-            branch on the rtpproxy. When sending a subsequent "delete"
481
+            branch on the rtpproxy. When sending a subsequent “delete”
484 482
             command to the rtpproxy, you can then stop just the session
485 483
             for a specific branch when passing the flag '1' or '2' in the
486
-            "unforce_rtpproxy", or stop all sessions for a call when not
484
+            “unforce_rtpproxy”, or stop all sessions for a call when not
487 485
             passing one of those two flags there. This is especially
488 486
             useful if you have serially forked call scenarios where
489
-            rtpproxy gets an "update" command for a new branch, and then a
490
-            "delete" command for the previous branch, which would
487
+            rtpproxy gets an “update” command for a new branch, and then a
488
+            “delete” command for the previous branch, which would
491 489
             otherwise delete the full call, breaking the subsequent
492
-            "lookup" for the new branch. This flag is only supported by
490
+            “lookup” for the new branch. This flag is only supported by
493 491
             the ngcp-mediaproxy-ng rtpproxy at the moment!
494 492
           + 2 - append second Via branch to Call-ID when sending command
495 493
             to rtpproxy. See flag '1' for its meaning.
... ...
@@ -499,11 +497,11 @@ onreply_route[2]
499 497
 rtpproxy_destroy();
500 498
 ...
501 499
 
502
-5.5. unforce_rtp_proxy()
500
+5.5.  unforce_rtp_proxy()
503 501
 
504 502
    Same as rtpproxy_destroy().
505 503
 
506
-5.6. rtpproxy_manage([flags [, ip_address]])
504
+5.6.  rtpproxy_manage([flags [, ip_address]])
507 505
 
508 506
    Manage the RTPProxy session - it combines the functionality of
509 507
    rtpproxy_offer(), rtpproxy_answer() and unfroce_rtpproxy(), detecting
... ...
@@ -531,7 +529,7 @@ rtpproxy_destroy();
531 529
 rtpproxy_manage();
532 530
 ...
533 531
 
534
-5.7. rtpproxy_stream2uac(prompt_name, count),
532
+5.7.  rtpproxy_stream2uac(prompt_name, count),
535 533
 
536 534
    Instruct the RTPproxy to stream prompt/announcement pre-encoded with
537 535
    the makeann command from the RTPproxy distribution. The uac/uas suffix
... ...
@@ -573,11 +571,11 @@ rtpproxy_manage();
573 571
     };
574 572
 ...
575 573
 
576
-5.8. rtpproxy_stream2uas(prompt_name, count)
574
+5.8.  rtpproxy_stream2uas(prompt_name, count)
577 575
 
578 576
    See function rtpproxy_stream2uac(prompt_name, count).
579 577
 
580
-5.9. rtpproxy_stop_stream2uac(),
578
+5.9.  rtpproxy_stop_stream2uac(),
581 579
 
582 580
    Stop streaming of announcement/prompt/MOH started previously by the
583 581
    respective rtpproxy_stream2xxx. The uac/uas suffix selects whose
... ...
@@ -586,10 +584,11 @@ rtpproxy_manage();
586 584
 
587 585
    These functions can be used from REQUEST_ROUTE, ONREPLY_ROUTE.
588 586
 
589
-5.10. start_recording()
587
+5.10.  start_recording()
590 588
 
591
-   This command will send a signal to the RTP-Proxy to record the RTP
592
-   stream on the RTP-Proxy.
589
+   This function will send a signal to the RTP-Proxy to record the RTP
590
+   stream on the RTP-Proxy. This function is only supported by Sippy
591
+   RTPproxy at the moment!
593 592
 
594 593
    This function can be used from REQUEST_ROUTE and ONREPLY_ROUTE.
595 594
 
... ...
@@ -598,7 +597,7 @@ rtpproxy_manage();
598 597
 start_recording();
599 598
 ...
600 599
 
601
-5.11. rtpproxy_stop_stream2uas(prompt_name, count)
600
+5.11.  rtpproxy_stop_stream2uas(prompt_name, count)
602 601
 
603 602
    See function rtpproxy_stop_stream2uac(prompt_name, count).
604 603
 
... ...
@@ -636,7 +635,7 @@ start_recording();
636 635
    NOTE: if a rtpproxy is defined multiple times (in the same or diferente
637 636
    sete), all its instances will be enables/disabled.
638 637
 
639
-   Example 1.16. nh_enable_rtpp usage
638
+   Example 1.16.  nh_enable_rtpp usage
640 639
 ...
641 640
 $ kamctl fifo nh_enable_rtpp udp:192.168.2.133:8081 0
642 641
 ...
... ...
@@ -648,52 +647,52 @@ $ kamctl fifo nh_enable_rtpp udp:192.168.2.133:8081 0
648 647
 
649 648
    No parameter.
650 649
 
651
-   Example 1.17. nh_show_rtpp usage
650
+   Example 1.17.  nh_show_rtpp usage
652 651
 ...
653 652
 $ kamctl fifo nh_show_rtpp
654 653
 ...
655 654
 
656 655
 Chapter 2. Frequently Asked Questions
657 656
 
658
-   2.1. What happend with "rtpproxy_disable" parameter?
657
+   2.1. What happend with “rtpproxy_disable” parameter?
659 658
    2.2. Where can I find more about Kamailio?
660 659
    2.3. Where can I post a question about this module?
661 660
    2.4. How can I report a bug?
662 661
 
663 662
    2.1.
664 663
 
665
-   What happend with "rtpproxy_disable" parameter?
664
+       What happend with “rtpproxy_disable” parameter?
666 665
 
667
-   It was removed as it became obsolete - now "rtpproxy_sock" can take
668
-   empty value to disable the rtpproxy functionality.
666
+       It was removed as it became obsolete - now “rtpproxy_sock” can take
667
+       empty value to disable the rtpproxy functionality.
669 668
 
670 669
    2.2.
671 670
 
672
-   Where can I find more about Kamailio?
671
+       Where can I find more about Kamailio?
673 672
 
674
-   Take a look at http://www.kamailio.org/.
673
+       Take a look at http://www.kamailio.org/.
675 674
 
676 675
    2.3.
677 676
 
678
-   Where can I post a question about this module?
677
+       Where can I post a question about this module?
679 678
 
680
-   First at all check if your question was already answered on one of our
681
-   mailing lists:
682
-     * User Mailing List -
683
-       http://lists.sip-router.org/cgi-bin/mailman/listinfo/sr-users
684
-     * Developer Mailing List -
685
-       http://lists.sip-router.org/cgi-bin/mailman/listinfo/sr-dev
679
+       First at all check if your question was already answered on one of our
680
+       mailing lists:
681
+         * User Mailing List -
682
+           http://lists.sip-router.org/cgi-bin/mailman/listinfo/sr-users
683
+         * Developer Mailing List -
684
+           http://lists.sip-router.org/cgi-bin/mailman/listinfo/sr-dev
686 685
 
687
-   E-mails regarding any stable Kamailio release should be sent to
688
-   <sr-users@lists.sip-router.org> and e-mails regarding development
689
-   versions should be sent to <sr-dev@lists.sip-router.org>.
686
+       E-mails regarding any stable Kamailio release should be sent to
687
+       <sr-users@lists.sip-router.org> and e-mails regarding development
688
+       versions should be sent to <sr-dev@lists.sip-router.org>.
690 689
 
691
-   If you want to keep the mail private, send it to
692
-   <sr-users@lists.sip-router.org>.
690
+       If you want to keep the mail private, send it to
691
+       <sr-users@lists.sip-router.org>.
693 692
 
694 693
    2.4.
695 694
 
696
-   How can I report a bug?
695
+       How can I report a bug?
697 696
 
698
-   Please follow the guidelines provided at:
699
-   http://sip-router.org/tracker.
697
+       Please follow the guidelines provided at:
698
+       http://sip-router.org/tracker.
... ...
@@ -18,13 +18,9 @@
18 18
 	<title>Overview</title>
19 19
 	<para>
20 20
 		This is a module that enables media streams to be proxied
21
-		via an rtpproxy.
22
-	</para>
23
-	<para>
24
-		Known devices that get along over &nat;s with rtpproxy are ATAs
25
-		(as clients) and Cisco Gateways (since 12.2(T)) as servers.  See <ulink
26
-		url="http://www.cisco.com/en/US/products/sw/iosswrel/ps1839/products_feature_guide09186a0080110bf9.html">
27
-		http://www.cisco.com/en/US/products/sw/iosswrel/ps1839/products_feature_guide09186a0080110bf9.html"></ulink>
21
+		via an rtpproxy.  Rtpproxies know to work with this module
22
+		are Sippy RTPproxy <ulink url="http://www.rtpproxy.org"></ulink>
23
+		and ngcp-rtpproxy-ng <ulink url="http://deb.sipwise.com/spce/2.6/pool/main/n/ngcp-mediaproxy-ng"></ulink>.  Some features of rtpproxy module apply only one of the two rtpproxies.
28 24
 	</para>
29 25
 	</section>
30 26
 
... ...
@@ -673,8 +669,8 @@ rtpproxy_manage();
673 669
 		<function moreinfo="none">start_recording()</function>
674 670
 		</title>
675 671
 		<para>
676
-		This command will send a signal to the RTP-Proxy to record
677
-		the RTP stream on the RTP-Proxy.
672
+		This function will send a signal to the RTP-Proxy to record
673
+		the RTP stream on the RTP-Proxy. <emphasis>This function is only supported by Sippy RTPproxy at the moment!</emphasis>
678 674
 		</para>
679 675
 		<para>
680 676
 		This function can be used from REQUEST_ROUTE and ONREPLY_ROUTE.