1<!doctype book PUBLIC "-//OASIS//DTD DocBook V4.2//EN" [ 2]> 3<book id="siproxd-doc"> 4 <?dbhtml filename="siproxd_guide.html"> 5 6 <bookinfo> 7 <date>2005-04-10</date> 8 <title>Siproxd Users Guide</title> 9 <abbrev>Siproxd</abbrev> 10 <authorgroup> 11 <author> 12 <firstname>Thomas</firstname> 13 <surname>Ries</surname> 14 </author> 15 </authorgroup> 16 <address> 17 <email>tries@users.sourceforge.net</email> 18 </address> 19 <copyright> 20 <year>2005-2010</year> 21 <holder>Thomas Ries</holder> 22 </copyright> 23 <legalnotice> 24 <para>This document can be freely redistributed according to 25 the terms of the GNU General Public License.</para> 26 </legalnotice> 27 <revhistory> 28 <revision> 29 <revnumber>0.1</revnumber> 30 <date>2005-04-10</date> 31 <authorinitials>tries@users.sourceforge.net</authorinitials> 32 <revremark>Initial version</revremark> 33 </revision> 34 <revision> 35 <revnumber>0.2</revnumber> 36 <date>2006-07-28</date> 37 <authorinitials>tries@users.sourceforge.net</authorinitials> 38 <revremark>Comment on Asterisk Scenario</revremark> 39 </revision> 40 <revision> 41 <revnumber>0.3</revnumber> 42 <date>2007-05-15</date> 43 <authorinitials>tries@users.sourceforge.net</authorinitials> 44 <revremark>New Asterisk Config Files</revremark> 45 </revision> 46 <revision> 47 <revnumber>0.7.1</revnumber> 48 <date>2008-01-27</date> 49 <authorinitials>tries@users.sourceforge.net</authorinitials> 50 <revremark>Plug-in API</revremark> 51 </revision> 52 <revision> 53 <revnumber>0.8.0</revnumber> 54 <date>2010-02-24</date> 55 <authorinitials>tries@users.sourceforge.net</authorinitials> 56 <revremark>TCP, STUN plugin, config file updates</revremark> 57 </revision> 58 </revhistory> 59 </bookinfo> 60 <toc></toc> 61 62 <!-- We are done with the preliminaries, now we can start with 63 the body of the document --> 64 65 <!-- Chapter 1: Overview --> 66 <chapter label="" id="README"> 67 <?dbhtml filename="siproxd_guide_c0.html"> 68 <title>README</title> 69 <para>Important information, please read me!</para> 70 71 <sect1 label=""> 72 <?dbhtml filename="siproxd_guide_c0s1.html"> 73 <title>Important / Warning</title> 74 <para>As it still happens that people try to mix different NAT 75 traversal techologies together with siproxd I'll put some words 76 here: 77 <itemizedlist mark='bullet'> 78 <listitem><para>Do NOT USE anything like an STUN Server together 79 with siproxd.</para></listitem> 80 <listitem><para>Do NOT USE any additional techologies trying to 81 help in NAT traversal (additional firewall modules like 82 ip_nat_sip.ko or whatever fancy stuff may tempt you). 83 </para></listitem> 84 </itemizedlist> 85 If you do not follow the above rules, those other 86 "helping technologies" WILL DO CONFLICT with siproxd and result 87 in a mess.</para> 88 </sect1> 89 </chapter> 90 91 <!-- Chapter 1: Overview --> 92 <chapter label="1" id="Overview"> 93 <?dbhtml filename="siproxd_guide_c1.html"> 94 <title>Overview</title> 95 <para>Siproxd is an proxy/masquerading daemon for the SIP protocol. 96 It handles registrations of SIP clients on a private IP network 97 and performs rewriting of the SIP message bodies to make SIP 98 connections possible via an masquerading firewall. It allows SIP 99 clients (like kphone, linphone) to work behind an IP masquerading 100 firewall or router.</para> 101 <para>SIP (Session Initiation Protocol, RFC3261) is used by Softphones 102 and Hardphones (Voice over IP) to initiate communication. By itself, 103 SIP does not work via masquerading firewalls as the transfered data 104 contains IP addresses and port numbers.</para> 105 <para>There exist so called STUN servers that allow a SIP client to 106 figure out its public visible IP address and use this one instead. 107 As a drawback, usually on the masquerading firewall a very wide port 108 range must be opened up for the incoming RTP traffic. The SIP client 109 must support STUN (which most of them do).</para> 110 <para>Siproxd uses another approach (application layer proxy) and places 111 itself as outbound proxy in between the local SIP client and the 112 remote client or registrar. It does rewrite the SIP traffic on the 113 fly and also includes a RTP proxy for incoming and outgoing RTP 114 traffic (the actual audio data). The port range to be used for 115 receiving RTP data is configurable, so the firewall only must 116 allow incoming traffic for a small port range.</para> 117 <para>A standard scenario would look like: 118<screen> 119private IP address range : Internet 12010.0.0.x : (public IP address range) 121 : 122 : foo.bar.org 123+-------------+ +--------------+ 124! !.10 .1 ! masquerading ! publicIP 125! IntHost !---------------! Firewall !------------>> 126! ! ! ! 127+-------------+ +--------------+ 128 eth0 : ppp0 129</screen> 130 131 <itemizedlist mark='bullet'> 132 <listitem><para>The Firewall does IP masquerading and is running 133 siproxd</para></listitem> 134 <listitem><para>IntHost is running an SIP softphone (like linphone, 135 kphone)</para></listitem> 136 <listitem><para>The SIP address used by the softphone is 137 sip:johndoe@foo.bar.org</para></listitem> 138 139 <listitem><para>The softphone is configured to register itself at 140 siproxd running on the firewall host (10.0.0.1) as 141 sip:johndoe@foo.bar.org</para></listitem> 142 <listitem><para>foo.bar.org is the domain name corresponding to the 143 public IP address of the firewall (e.g. use some dynamic DNS 144 service [1])</para></listitem> 145 </itemizedlist> 146 </para> 147 </chapter> 148 149 <!-- Chapter 2: Building and Installation --> 150 <chapter label="2" id="Building-and-Installation"> 151 <?dbhtml filename="siproxd_guide_c2.html"> 152 <title>Building and Installation</title> 153 154 <!-- Chapter 2.1: Prerequisites --> 155 <sect1 label="2.1" > 156 <?dbhtml filename="siproxd_guide_c2s1.html"> 157 <title>Prerequisites</title> 158 <para>Operating system of either: 159 <itemizedlist mark='bullet'> 160 <listitem><para>Linux (should work with any kernel)</para></listitem> 161 <listitem><para>FreeBSD</para></listitem> 162 <listitem><para>Solaris (porting is still being worked on but 163 you may try it)</para></listitem> 164 </itemizedlist> 165 Additional required Packages: 166 <itemizedlist mark='bullet'> 167 <listitem><para><ulink url='http://www.gnu.org/software/osip'> 168 Libosip2 package</ulink></para></listitem> 169 </itemizedlist> 170 </para> 171 </sect1> 172 173 <!-- Chapter 2.2: Compiling and Installing --> 174 <sect1 label="2.2"> 175 <?dbhtml filename="siproxd_guide_c2s2.html"> 176 <title>Compiling and Installing</title> 177 <para>It is quite simple. If you have a more-or-less standard 178 installation and libosip2 installed at a standard location, 179 it should be sufficient to do: 180<screen> 181./configure 182make 183make install 184</screen> 185 </para> 186 <para>This will install siproxd into /usr/local/. If you wish 187 to install it into another location, specify 188 <userinput>--prefix=<myprefix></userinput> when running 189 <userinput>./configure</userinput>. If you have installed 190 libosip2 in an non-standard location use 191 <userinput>--with-libosip-prefix=<libosipprefix></userinput> 192 to tell configure where to find libosip2 (e.g. 193 <userinput>--with-libosip-prefix=$HOME/lib</userinput>).</para> 194 <para>Common features for ./configure: 195<screen> 196--enable-static build statically linked executable 197--with-libosip-prefix=DIR use libosip2 from DIR/include and DIR/lib 198--with-extra-includes=DIR adds non standard include paths 199--with-extra-libs=DIR adds non standard library paths 200</screen> 201 </para> 202 <para>Edit <filename>/usr/etc/siproxd.conf</filename> according 203 to your situation, at least configure 204 <parameter>if_inbound</parameter> and 205 <parameter>if_outbound</parameter>. They must represent the 206 interface names (e.g. on Linux: ppp0, eth1) for the inbound 207 and outbound interfaces.</para> 208 <para>Edit <filename>/usr/etc/siproxd_passwd.cfg</filename> 209 if you enable client authentication.</para> 210 <para>Start siproxd: 211<screen> 212# siproxd 213</screen> 214 </para> 215 </sect1> 216 </chapter> 217 218 <!-- Chapter 3: Configuration --> 219 <chapter label="3" id="Configuration"> 220 <?dbhtml filename="siproxd_guide_c3.html"> 221 <title>Configuration</title> 222 223 <!-- Chapter 3.1: The configuration file 'siproxd.conf' --> 224 <sect1 label="3.1"> 225 <?dbhtml filename="siproxd_guide_c3s1.html"> 226 <title>The configuration file 'siproxd.conf'</title> 227 <para>Siproxd by default searches for its configuration 228 file in the following locations: 229 <itemizedlist mark='bullet'> 230 <listitem><para><filename>$HOME/.siproxdrc 231 </filename></para></listitem> 232 <listitem><para><filename><buildingprefix>/etc/siproxd.conf 233 </filename></para></listitem> 234 <listitem><para><filename>/etc/siproxd.conf 235 </filename></para></listitem> 236 <listitem><para><filename>/usr/etc/siproxd.conf 237 </filename></para></listitem> 238 <listitem><para><filename>/usr/local/etc/siproxd.conf 239 </filename></para></listitem> 240 </itemizedlist> 241 </para> 242 243 <para>The following is a list of directives that do exist. 244 Note that string values MUST NOT contain spaces or tabs. 245 Also read the explanations included in the supplied example 246 configuration file fro more explanation. Items with a # in 247 front are normally disabled / not defined.</para> 248 <para>To start with siproxd in the first run, just adapt the 249 interface definition for the inbound and outbound network 250 interfaces (<parameter>if_inbound</parameter> and 251 <parameter>if_outbound</parameter>).</para> 252 <para>Definition of network interfaces for the inbound network 253 (local network where your SIP client is connected, this 254 network normally uses IP addresses from on of the private 255 IP ranges like 10.x.x.x, 192.168.x.x) and outbound network 256 (your connection to the Internet, normally this interface 257 has a public IP assigned by your provider).</para> 258<screen> 259if_inbound = eth0 260if_outbound = ppp0 261</screen> 262 <para>Usually only the <parameter>if_inbound</parameter> and 263 <parameter>if_outbound</parameter> directives will be used. 264 The <parameter>host_outbound</parameter> directive comes into 265 play when running siproxd "in front of" a NAT router. Please 266 check the configuration examples in this document for more 267 details. Also check the STUN plugin.</para> 268<screen> 269# host_outbound = <my_public_ip_address> 270</screen> 271 272 <para>Access control lists for incoming SIP registrations and 273 SIP traffic in general. These are comma separated lists of 274 the form <IP>/<mask>, note that no spaces are 275 allowed within the list (the configuration file parser 276 cannot yet handle spaces).</para> 277<screen> 278# hosts_allow_reg = 192.168.1.0/24,192.168.2.0/24 279# hosts_allow_sip = 123.45.0.0/16,123.46.0.0/16 280# hosts_deny_sip = 10.0.0.0/8,11.0.0.0/8 281</screen> 282 283 <para>Port to listen for incoming SIP messages. 5060 is 284 usually the correct choice, don't change this unless you 285 have a reason to.</para> 286<screen> 287sip_listen_port = 5060 288</screen> 289 290 <para>Shall siproxd run as daemon? Usually 1 is the correct 291 choice. If you want siproxd not to daemonize and keep 292 running in foreground and writing its output to the terminal 293 set this to 0.</para> 294<screen> 295daemonize = 1 296</screen> 297 298 <para>Siproxd does log using the syslog() facility when 299 running a daemon. This setting controls how much logging 300 is done: 301 <itemizedlist mark='bullet'> 302 <listitem><para><literal>0 - DEBUGs, INFOs, WARNINGs and ERRORs 303 </literal></para></listitem> 304 <listitem><para><literal>1 - INFOs, WARNINGs and ERRORs 305 </literal></para></listitem> 306 <listitem><para><literal>2 - WARNINGs and ERRORs 307 </literal></para></listitem> 308 <listitem><para><literal>3 - only ERRORs 309 </literal></para></listitem> 310 <listitem><para><literal>4 - absolutely nothing 311 </literal></para></listitem> 312 </itemizedlist> 313 </para> 314<screen> 315silence_log = 0 316</screen> 317 318 <para>If siproxd is started as root, it can drop the root 319 privileges and change its user ID at startup. It also can 320 put itself into a chroot() jail (see 4.2 for details)</para> 321<screen> 322user = nobody 323# chrootjail = /var/lib/siproxd/ 324</screen> 325 326 <para>Where to store the current registrations and the cycle 327 in seconds to perform the cyclic writing. This allows 328 siproxd to remember registration across a restart. An empty 329 value means we do not save registrations. The specified 330 directory path must exist.</para> 331<screen> 332registration_file = /var/lib/siproxd/siproxd_registrations 333autosave_registrations = 300 334</screen> 335 336 <para>Where to create the PID file.</para> 337<screen> 338pid_file = /var/run/siproxd/siproxd.pid 339</screen> 340 341 <para>Enable/disable the RTP proxy. This must always be 342 enabled. In some future release this directive will 343 become obsolete and will be removed.</para> 344<screen> 345rtp_proxy_enable = 1 346</screen> 347 348 <para>Port range (UDP) that siproxd will use for incoming 349 and outgoing RTP traffic. A firewall must be configured 350 to allow traffic from and to these ports (UDP only). By 351 default the range 7070 up to (and including) 7089 is used. 352 This allows up to 10 simultaneous calls (2 ports per call). 353 If you need more simultaneous calls, increase the range.</para> 354<screen> 355rtp_port_low = 7070 356rtp_port_high = 7089 357</screen> 358 359 <para>Timeout for an RTP stream. If for the specified number 360 of seconds no data is relayed on an active stream, it is 361 considered dead and will be killed.</para> 362<screen> 363rtp_timeout = 300 364</screen> 365 366 <para>DSCP (differentiated services) value to be assigned 367 to RTP and SIP UDP packets. Allows QOS aware routers to 368 handle different types traffic with different priorities.</para> 369<screen> 370rtp_dscp = 46 371sip_dscp = 0 372</screen> 373 374 <para>If a REGISTER request does not contain an 375 <literal>Expires</literal> header or <literal>expires=</literal> 376 parameter in the <literal>Contact</literal> header, this 377 number of seconds will be used and reported back to the UA 378 in the answer.</para> 379<screen> 380default_expires = 600 381</screen> 382 383 <para>TCP inactivity timeout: For TCP SIP signalling, this 384 indicates the inactivity timeout (seconds) after that an 385 idling TCP connection is disconnected. Note that making 386 this too short may cause multiple parallell registrations 387 for the same phone. This timeout must be set larger than the 388 used registration interval.</para> 389<screen> 390tcp_timeout = 600 391</screen> 392 393 <para>Timeout for connection attempts in msec: 394 How many msecs shall siproxd wait for an successful connect 395 when establishing an outgoing SIP signalling connection. This 396 should be kept as short as possible as waiting for an TCP 397 connection to establish is a BLOCKING operation - while waiting 398 for a connect to succeed not SIP messages are processed (RTP is 399 not affected).</para> 400<screen> 401tcp_connect_timeout = 500 402</screen> 403 404 405 <para>TCP keepalive period: 406 For TCP SIP signalling, if > 0 empty SIP packets will be sent 407 every 'n' seconds to keep the connection alive. Default is off. 408 </para> 409<screen> 410tcp_keepalive = 20 411</screen> 412 413 <para>If siproxd is used as registration server and 414 authentication is wanted, define the following directive. 415 If <parameter>proxy_auth_realm</parameter> is defined 416 (a string), clients will be forced to authenticate themselfs 417 to the proxy (for registration only). To disable Authentication, 418 simply comment out this line. Default is disabled.</para> 419<screen> 420# proxy_auth_realm = Authentication_Realm 421</screen> 422 423 <para>The password to be used for authentication may be a global 424 one</para> 425<screen> 426# proxy_auth_passwd = some_password 427</screen> 428 429 <para>or on a per user base, stored in its own file. 430 <parameter>proxy_auth_pwfile</parameter> takes precedence over 431 <parameter>proxy_auth_passwd</parameter></para> 432<screen> 433# proxy_auth_pwfile = /etc/mysiproxd_passwd.cfg 434</screen> 435 436 <para>To enable additional debug output of siproxd. 437 This is a bit pattern representing the following items. 438 Default is 0x0 - disabled. See below in this document 439 for information on how to create a debug log file. 440 <itemizedlist mark='bullet'> 441 <listitem><para><literal>DBCLASS_BABBLE 0x00000001 // babble (like entering/leaving fnc) 442 </literal></para></listitem> 443 <listitem><para><literal>DBCLASS_NET 0x00000002 // network 444 </literal></para></listitem> 445 <listitem><para><literal>DBCLASS_SIP 0x00000004 // SIP manipulations 446 </literal></para></listitem> 447 <listitem><para><literal>DBCLASS_REG 0x00000008 // Client registration 448 </literal></para></listitem> 449 <listitem><para><literal>DBCLASS_NOSPEC 0x00000010 // non specified class 450 </literal></para></listitem> 451 <listitem><para><literal>DBCLASS_PROXY 0x00000020 // proxy 452 </literal></para></listitem> 453 <listitem><para><literal>DBCLASS_DNS 0x00000040 // DNS stuff 454 </literal></para></listitem> 455 <listitem><para><literal>DBCLASS_NETTRAF 0x00000080 // network traffic 456 </literal></para></listitem> 457 <listitem><para><literal>DBCLASS_CONFIG 0x00000100 // configuration 458 </literal></para></listitem> 459 <listitem><para><literal>DBCLASS_RTP 0x00000200 // RTP proxy 460 </literal></para></listitem> 461 <listitem><para><literal>DBCLASS_ACCESS 0x00000400 // Access list evaluation 462 </literal></para></listitem> 463 <listitem><para><literal>DBCLASS_AUTH 0x00000800 // Authentication 464 </literal></para></listitem> 465 </itemizedlist> 466 </para> 467<screen> 468debug_level = 0x00000000 469</screen> 470 471 <para>You may connect to this port from a remote machine and 472 receive the debug output. This allows bettwer creation of 473 debug output on embedded systems that do not have enough 474 memory for large disk files. Port number 0 means this feature 475 is disabled.</para> 476<screen> 477debug_port = 0 478</screen> 479 480 <para>Some UAs (SIP clients) will always use the host/ip they 481 register TO as host part in the registration record (which 482 will be the inbound ip address/hostname of the proxy) and 483 can not be told to register a different host (public IP 484 address). This Mask feature allows to force such a UA to be 485 masqueraded to a different host. Siemens SIP Phones seem to 486 need this feature. Normally disabled.</para> 487<screen> 488# mask_host=local.ip.of.sipphone 489# masked_host=public.domaind.org 490</screen> 491 492 <para>User Agent Masquerading: 493 Siproxd can masquerade the User Agent string of your local UAs. 494 Useful for Providers that do not work with some specific UAs 495 (e.g. sipcall.ch - it does not work if your outgoing SIP 496 traffic contains an Asterisk UA string...) 497 Default is to do no replacement.</para> 498<screen> 499ua_string = Siproxd-UA 500</screen> 501 502 <para>Use ;rport in via header: 503 may be required in some cases where you have a NAT router that 504 remaps the source port 5060 to something different and the 505 registrar sends back the responses to port 5060. 506 Default is disabled (0)</para> 507<screen> 508use_rport = 0 509</screen> 510 511 <para>Siproxd itself can be told to send all traffic to another 512 outbound proxy. You can use this feature to 'chain' multiple 513 siproxd proxies if you have several masquerading firewalls 514 to cross. Normally disabled.</para> 515<screen> 516# outbound_proxy_host = my.outboundproxy.org 517# outbound_proxy_port = 5060 518</screen> 519 520 <para>Outbound proxies can be specified on a per-domain base. 521 This allows to use an outbound proxy needed for ProviderA 522 and none (or another) for ProviderB. Multiple domain specific 523 proxies may be specified, each one with one set of the following 524 directives. Note: These directives must always be specified as a 525 triple, skipping one of them will affect later definitions.</para> 526<screen> 527#outbound_domain_name = freenet.de 528#outbound_domain_host = proxy.for.domain.freende.de 529#outbound_domain_port = 5060 530</screen> 531 532 <para>Siproxd supports dynamic loadable plug-ins. Such plug-ins 533 are loaded during runtime and do not require recompilation 534 of the executable. This allows the easy addition of specific 535 functionality to siproxd. Even 3rd party functional extensions 536 are possible without the requirement to patch and rebuild the 537 siproxd source code with each new release.</para> 538 <para>Note: Dynamic loading of shared libraries is not supported 539 on all platforms. If a platform does not support it, plug-ins 540 can still be used but they will be statically linked during 541 the build process of siproxd. The configuration ("loading" the 542 plugins) is identical. 543 For more information on this topic you may familiarize yourself 544 with libltdl. 545 </para> 546 <para>Note: As the plug-in mechanism uses LTDL, the plugins to load 547 MUST use a .la extension and not an .so extension! Trying to load an 548 plugin using xxx.so as it's name will fail.</para> 549<screen> 550# plugin_dir: MUST be terminated with '/' 551plugindir=/usr/lib/siproxd/ 552 553# List of plugins to load: 554#load_plugin=plugin_demo.la 555load_plugin=plugin_logcall.la 556</screen> 557 558 <para>Each plugin does manage it's own set of configuration 559 options. They are named like plugin_<pluginname>_xxxxx. 560 For the detailed description of configuration settings, refer 561 to the plugin description.</para> 562<screen> 563plugin_demo_string = This_is_a_string_passed_to_the_demo_plugin 564</screen> 565 </sect1> 566 567 <!-- Chapter 3.2: Command Line Options --> 568 <sect1 label="3.2"> 569 <?dbhtml filename="siproxd_guide_c3s2.html"> 570 <title>Command Line Options</title> 571 <para>Siproxd knows the following command line options:</para> 572<screen> 573-h, --help help 574-d, --debug <pattern> set debug-pattern 575-c, --config <cfgfile> use the specified config file 576-p, --pid-file <pidfile> create pid file at <pidfile> 577</screen> 578 <para>These options take precedence over the values configured 579 in the configuration file.</para> 580 </sect1> 581 </chapter> 582 583 <!-- Chapter 4: Features --> 584 <chapter label="4" id="Features"> 585 <?dbhtml filename="siproxd_guide_c4.html"> 586 <title>Features</title> 587 588 <!-- Chapter 4.1: Custom Firewall Module --> 589 <sect1 label="4.1"> 590 <?dbhtml filename="siproxd_guide_c4s1.html"> 591 <title>Custom Firewall Module</title> 592<!--&&&& do be completed --> 593 <para>The API</para> 594 <para>make your library</para> 595 <para>example code</para> 596<screen> 597./configure --with-custom-fwmodule=LIBRARY.a 598</screen> 599 </sect1> 600 601 <!-- Chapter 4.2: Chroot() Jail --> 602 <sect1 label="4.2"> 603 <?dbhtml filename="siproxd_guide_c4s2.html"> 604 <title>Chroot() Jail</title> 605<!--&&&& do be completed --> 606 <para>Create chroot jail</para> 607 <para>What files must be present? To be completed!</para> 608 </sect1> 609 </chapter> 610 611 <!-- Chapter 5: Plug-ins --> 612 <chapter label="5" id="Plug-ins"> 613 <?dbhtml filename="siproxd_guide_c5.html"> 614 <title>Plug-ins</title> 615 616 <!-- Chapter 5.1: Plug-in API --> 617 <sect1 label="5.1"> 618 <?dbhtml filename="siproxd_guide_c5s1.html"> 619 <title>Plug-in API</title> 620 <para>Siproxd plug-ins are dynamic loadable libraries and must provide 621 3 functions towards siproxd. As we make use of some libltdl features 622 we do some internal macor magic - the PLUGIN_xxx funcation names 623 are actually CPP macros that will expand in unique names. Th have 624 this working properly the PLUGIN_NAME must be #defined before 625 the plugins.h header file is included: 626 </para> 627<screen> 628#define PLUGIN_NAME plugin_myplugin 629#include "plugins.h" 630[...] 631int PLUGIN_INIT(plugin_def_t *plugin_def); 632int PLUGIN_PROCESS(int stage, sip_ticket_t *ticket); 633int PLUGIN_END(plugin_def_t *plugin_def); 634</screen> 635 <para> 636 The <filename>PLUGIN_INIT</filename> function is called when 637 the plug-in is loaded during startup of siproxd. The plug-in must 638 define the following 4 fields of the plugin_def structure: 639 <orderedlist numeration="arabic"> 640 <listitem><para><filename>api_version</filename></para></listitem> 641 <listitem><para><filename>name</filename></para></listitem> 642 <listitem><para><filename>desc</filename></para></listitem> 643 <listitem><para><filename>exe_mask</filename></para></listitem> 644 </orderedlist> 645 646 Example code fragment: 647 </para> 648<screen> 649/* API version number of siproxd that this plug-in is built against. 650 * This constant will change whenever changes to the API are made 651 * that require adaptions in the plug-in. */ 652plugin_def->api_version=SIPROXD_API_VERSION; 653 654/* Name and descriptive text of the plug-in. Those item MUST NOT be 655 on the stack but either allocated via malloc (and then freed 656 of course) or a static string in the plug-in. */ 657plugin_def->name=strdup("plugin_demo"); 658plugin_def->desc=strdup("This is just a demo plugin without any purpose"); 659 660/* Execution mask - during what stages of SIP processing shall 661 * the plug-in be called. */ 662plugin_def->exe_mask=PLUGIN_DETERMINE_TARGET|PLUGIN_PRE_PROXY; 663</screen> 664 <para> 665 The <filename>PLUGIN_PROCESS</filename> function is called at 666 the requested SIP processing stages (see 'execution mask'). 667 Your processing will be done here. 668 </para> 669 <para> 670 The <filename>PLUGIN_END</filename> function is called at 671 shutdown of siproxd and gives the plug-in the opportunity 672 to clean up and properly shutdown itself.</para> 673 <para>Note: The previously allocated 'name' and 'desc' must be 674 freed by the plug-in. If you did use a static string then of 675 course you must not try to free() anything.</para> 676 <para> 677 Minimum required clean up procedure: 678<screen> 679int PLUGIN_END(plugin_def_t *plugin_def){ 680 /* free my allocated rescources (if allocated via malloc only) */ 681 if (plugin_def->name) {free(plugin_def->name); plugin_def->name=NULL;} 682 if (plugin_def->desc) {free(plugin_def->desc); plugin_def->desc=NULL;} 683 return STS_SUCCESS; 684} 685</screen> 686 </para> 687 <para> 688 For a simple example refer to the simple demonstration plug-in 689 <filename>plugin_demo</filename>. 690 </para> 691 <para> 692 Each plug-in can have its own set of configuration parameters 693 in <filename>siproxd.conf</filename>. The plug-in has to define 694 a <filename>cfgopts_t</filename> structure and call <filename> 695 read_config</filename> during its initialization. Look at <filename> 696 plugin_demo</filename> for a simple example. The naming of 697 the config parameters is by definition 698 <filename>plugin_name_</filename>option. 699 </para> 700 </sect1> 701 702 <!-- Chapter 5.2: Available Plug-ins --> 703 <sect1 label="5.2"> 704 <?dbhtml filename="siproxd_guide_c5s2.html"> 705 <title>Available Plug-ins</title> 706 <para>The following plug-ins are provided with siproxd: 707 <orderedlist numeration="arabic"> 708 <listitem><para><filename>plugin_demo</filename></para> 709 <para>Demo plug-in. Provides the basic framework to 710 be used for plug-ins. 711 </para></listitem> 712 <listitem><para><filename>plugin_logcall</filename></para> 713 <para>Very simplistic call logging to syslog. 714 </para></listitem> 715 <listitem><para><filename>plugin_shortdial</filename></para> 716 <para>Quick Dial feature. 717 </para></listitem> 718 <listitem><para><filename>plugin_defaulttarget</filename></para> 719 <para>Incoming calls to a non-existing UA are 720 redirected to a specific target (catch-all). 721 </para></listitem> 722 <listitem><para><filename>plugin_fix_bogus_via</filename></para> 723 <para>Fixes broken VIA headers on incoming calls. 724 </para></listitem> 725 <listitem><para><filename>plugin_stun</filename></para> 726 <para>Cyclically checks with an STUN server for 727 the public IP address of siproxd. 728 </para></listitem> 729 </orderedlist> 730 Some of the plug-ins are described in more detail in the 731 following chapters. 732 </para> 733 734 <!-- Chapter 5.2.1: Demo Plug-in --> 735 <sect2 label="5.2.1"> 736 <?dbhtml filename="siproxd_guide_c5s2-1.html"> 737 <title>Demo Plug-in</title> 738 <para>Name: plugin_demo</para> 739 <para>Purpose: To be used as skeletton for your own plug-ins.</para> 740 <para>Configuration options:</para> 741<screen> 742plugin_demo_string = This_is_a_string_passed_to_the_demo_plugin 743</screen> 744 <para>Description:</para> 745 <para>This plug-in can be used as framework for your own plug-ins. 746 It contains the required code for the API and also shows 747 how to load plug-in specific configuration parameters. 748 </para> 749 </sect2> 750 751 <!-- Chapter 5.2.2: Call Logging Plug-in --> 752 <sect2 label="5.2.2"> 753 <?dbhtml filename="siproxd_guide_c5s2-2.html"> 754 <title>Call Logging Plug-in</title> 755 <para>Name: plugin_logcall</para> 756 <para>Purpose: Does a very simplistic call logging to syslog.</para> 757 <para>Configuration options:</para> 758<screen> 759none 760</screen> 761 <para>Description:</para> 762 <para>The numbering starts with "1" ("*01") and every following 763 "plugin_shortdial_entry" entry will allocate the following position. 764 It is not possible to freely assign the positions.</para> 765 </sect2> 766 767 <!-- Chapter 5.2.3: Short Dial Plug-in --> 768 <sect2 label="5.2.3"> 769 <?dbhtml filename="siproxd_guide_c5s2-3.html"> 770 <title>Short Dial Plug-in</title> 771 <para>Name: plugin_shortdial.c</para> 772 <para>Purpose: Provides a quick-Dial feature. 773 </para> 774 <para>Configuration options:</para> 775<screen> 776# The first character is the "key", the following characters give 777# the length of the number string. E.g. "*00" allows speed dials 778# from *01 to *99. (the number "*100" will be passed through unprocessed) 779plugin_shortdial_akey = *00 780# 781# *01 sipphone echo test 782plugin_shortdial_entry = 17474743246 783# *02 sipphone welcome message 784plugin_shortdial_entry = 17474745000 785</screen> 786 <para>Description:</para> 787 <para>Allows the definition of quick dial entries. E.g. 788 *01 to *99 can be defined to redirect the caller. 789 Note: Currently only the user part (phone number) can 790 be replaced, the domain part will not be changed (means 791 a short dial tarket of sip:111@other.domain.com will 792 not work). The '*' character can be chosen freely 793 (plugin_shortdial_akey). 794 Note: To call a real number like "*12" you have to dial 795 "**12" 796 </para> 797 </sect2> 798 799 <!-- Chapter 5.2.4: Default Target Plug-in --> 800 <sect2 label="5.2.4"> 801 <?dbhtml filename="siproxd_guide_c5s2-4.html"> 802 <title>Default Target Plug-in</title> 803 <para>Name: plugin_defaulttarget</para> 804 <para>Purpose: Incoming calls to non-existing local UAs are 805 redirected to another SIP URI.</para> 806 <para>Configuration options:</para> 807<screen> 808# Log redirects to syslog 809plugin_defaulttarget_log = 1 810# target must be a full SIP URI with the syntax 811# sip:user@host[:port] 812plugin_defaulttarget_target = sip:defaulttarget@some.sip.domain:port 813</screen> 814 <para>Description:</para> 815 <para>Incoming SIP calls directed to a non-existing (registered) 816 local UA will be redirected to another target. This basically 817 implements a catch-all feature. The new target can be any SIP 818 URI and is not required to be local.</para> 819 </sect2> 820 821 <!-- Chapter 5.2.5: Fix bogus Via Plug-in --> 822 <sect2 label="5.2.5"> 823 <?dbhtml filename="siproxd_guide_c5s2-4.html"> 824 <title>Fix bogus Via Plug-in</title> 825 <para>Name: plugin_fix_bogus_via</para> 826 <para>Purpose: Fixes broken VIA headers on incoming SIP requests.</para> 827 <para>Configuration options:</para> 828<screen> 829# Incoming (from public network) SIP messages are checked for broken 830# SIP Via headers. If the IP address in the latest Via Header is 831# part of the list below, it will be replaced by the IP where the 832# SIP message has been received from. 833plugin_fix_bogus_via_networks = 10.0.0.0/8,172.16.0.0/12,192.168.0.0/16 834</screen> 835 <para>Description:</para> 836 <para>Fixes broken VIA headers on incoming SIP requests 837 (inspired by Ralph Babel, see http://babel.de/art20080317a.html 838 for more info). Can be applied if you have remote UAs calling you 839 from the Internet and those UAs do have crappy Via headers (like 840 private IPs because there is some NAT involved on their side).</para> 841 </sect2> 842 843 <!-- Chapter 5.2.6: STUN Plug-in --> 844 <sect2 label="5.2.6"> 845 <?dbhtml filename="siproxd_guide_c5s2-6.html"> 846 <title>STUN Plug-in</title> 847 <para>Name: plugin_stun</para> 848 <para>Purpose: Uses an external STUN server to determine the 849 public IP address of the host running siproxd.</para> 850 <para>Configuration options:</para> 851<screen> 852# Plugin_stun 853# 854# Uses an external STUN server to determine the public IP 855# address of siproxd. Useful for "in-front-of-NAT-router" 856# scenarios. 857plugin_stun_server = stun.ekiga.net 858plugin_stun_port = 3478 859# period in seconds to request IP info from STUN server 860plugin_stun_period = 300 861</screen> 862 <para>Description:</para> 863 <para>Does contact the configured STUN server at startup and then 864 cyclically at the configured interval to determine the public 865 visible IP address of the host running siproxd. Useful for setups 866 that have changing public IP addresses and siproxd is running 867 in the "in-front-of-NAT-router" scenario.</para> 868 </sect2> 869 </sect1> 870 </chapter> 871 872 <!-- Chapter 6: Troubleshooting --> 873 <chapter label="6" id="Troubleshooting"> 874 <?dbhtml filename="siproxd_guide_c6.html"> 875 <title>Troubleshooting</title> 876 877 <!-- Chapter 6.1: Problem Reporting --> 878 <sect1 label="6.1"> 879 <?dbhtml filename="siproxd_guide_c6s1.html"> 880 <title>Problem Reporting</title> 881 <para>If you encounter problems/crashes and ask for support, 882 please include as much information as possible. Very helpful 883 is a debug log that has been recorded at the time of the 884 misbehavior. Also include the exact versions of the siproxd 885 package and libosip2 that you are using. You should also 886 include your <filename>siproxd.conf</filename>.</para> 887 </sect1> 888 889 <!-- Chapter 6.2: Create a Debug Log --> 890 <sect1 label="6.2"> 891 <?dbhtml filename="siproxd_guide_c6s2.html"> 892 <title>Create a Debug Log</title> 893 <para>The easiest way to generate a debug log is: 894 <orderedlist numeration="arabic"> 895 <listitem><para>make sure siproxd is not started as daemon 896 ('daemonize = 0' in the config file)</para></listitem> 897 <listitem><para>start siproxd: 898 <userinput>$ ./siproxd -d -1 2>debug.log</userinput> 899 </para></listitem> 900 <listitem><para>reproduce the error</para></listitem> 901 <listitem><para>include the generated <filename>debug.log 902 </filename> in your error report</para></listitem> 903 </orderedlist> 904 </para> 905 <para>Another possibility of to use TCP logging. This method 906 is recommended if you run siproxd on a router with limited 907 disk space (e.g. an embedded system). To enable TCP logging: 908 <orderedlist numeration="arabic"> 909 <listitem><para>Edit the configuration file and set 910 <parameter>debug_port</parameter> to 5050 (or any other 911 TCP port number you like).</para></listitem> 912 <listitem><para>Restart siproxd</para></listitem> 913 <listitem><para><userinput>$ telnet <IP_of_siproxd> 914 5050 > debug.log</userinput></para></listitem> 915 </orderedlist> 916 </para> 917 <para>You may prefer to use netcat instead of telnet. 918 Note: The TCP debug port is bound to all available interfaces 919 on the system, make sure no unauthorized people (like from 920 the outbound network) can connect.</para> 921 </sect1> 922 923 <!-- Chapter 6.3: Siproxd crashes --> 924 <sect1 label="6.3"> 925 <?dbhtml filename="siproxd_guide_c6s3.html"> 926 <title>Siproxd crashes</title> 927 <para>If siproxd crashes, a stack back trace usually is 928 helpful to me: 929 <orderedlist numeration="arabic"> 930 <listitem><para>start siproxd in the debugger 931 (daemonize set to 0):</para> 932 <para><userinput>$ gdb ./src/siproxd</userinput></para> 933 <para><userinput>(gdb) set args -c /path/to/siproxd.conf 934 </userinput></para> 935 <para><userinput>(gdb) run</userinput></para> 936 </listitem> 937 <listitem><para>reproduce the crash</para></listitem> 938 939 <listitem><para>use gdb to print the stack backtrace: 940<screen> 941(gdb) info thread 942... 943(gdb) bt 944#0 0x400ec9ee in __select () 945#1 0xbffff6f8 in ?? () 946#2 0x804a5c2 in main (argc=3, argv=0xbffffc54) at siproxd.c:186 947#3 0x4005bcb3 in __libc_start_main (main=0x804a30c <main>, argc=3, 948 argv=0xbffffc54, init=0x8049a08 <_init>, fini=0x804edac <_fini>, 949 rtld_fini=0x4000a350 <_dl_fini>, stack_end=0xbffffc4c) 950 at ../sysdeps/generic/libc-start.c:78 951(gdb) 952</screen> 953 </para></listitem> 954 <listitem><para>copy-paste all the output and include 955 it in your problem report.</para></listitem> 956 </orderedlist> 957 </para> 958 </sect1> 959 </chapter> 960 961 <!-- Chapter 7: Sample Configurations --> 962 <chapter label="7" id="Sample-Configurations"> 963 <?dbhtml filename="siproxd_guide_c7.html"> 964 <title>Sample Configurations</title> 965 <para>Check also the FAQ in the siproxd package.</para> 966 967 <!-- Chapter 7.1: The "Standard Scenario" --> 968 <sect1 label="7.1"> 969 <?dbhtml filename="siproxd_guide_c7s1.html"> 970 <title>The "Standard Scenario"</title> 971 <para>Scenario:</para> 972<screen> 973private IP address range : Internet 97410.0.0.x : (public IP address range) 975 : 976 : foo.bar.org 977+-------------+ +--------------+ 978! !.10 .1 ! masquerading ! publicIP 979! IntHost !---------------! Firewall !------------>> 980! ! ! ! 981+-------------+ +--------------+ 982 eth0 : ppp0 983</screen> 984 <para>The Firewall does IP masquerading and is running 985 siproxd. IntHost is running an SIP softphone (like linphone, 986 kphone). The SIP address used by the softphone is 987 <literal>sip:johndoe@foo.bar.org</literal>. The softphone is 988 configured to register itself at siproxd running on the 989 firewall host (10.0.0.1) as <literal>sip:johndoe@foo.bar.org</literal>. 990 <literal>Foo.bar.org</literal> is the domain name corresponding 991 to the public IP address of the firewall (e.g. use some dynamic 992 DNS service like DynDNS).</para> 993 <para>Firewall configuration (iptables):</para> 994<screen> 995# allow incoming SIP and RTP traffic 996iptables -A INPUT -m udp -p udp -i ppp0 --dport 5060 -j ACCEPT 997iptables -A INPUT -m udp -p udp -i ppp0 --dport 7070:7089 -j ACCEPT 998</screen> 999 <para>Firewall configuration (ipchains):</para> 1000<screen> 1001# allow incoming SIP and RTP traffic 1002ipchains -A input --proto udp --dport 5060 -j ACCEPT 1003ipchains -A input --proto udp --dport 7070:7089 -j ACCEPT 1004</screen> 1005 <para>The first line will allow incoming SIP traffic. The 1006 second line will allow incoming RTP traffic on the ports 1007 7070 - 7089 (the default port range used by siproxd for 1008 incoming RTP traffic).</para> 1009 </sect1> 1010 1011 <!-- Chapter 7.2: GS BT-100 behind NAT Router running Siproxd --> 1012 <sect1 label="7.2"> 1013 <?dbhtml filename="siproxd_guide_c7s2.html"> 1014 <title>GS BT-100 behind NAT Router running Siproxd</title> 1015 <para>Scenario:</para> 1016<screen> 1017private IP address range : Internet 101810.0.0.x : (public IP address range) 1019 : 1020 : foo.bar.org 1021+-------------+ +--------------+ 1022! !.10 .1 ! masquerading ! publicIP 1023! SIP UA !---------------! Firewall !------------>> 1024! BT-100 ! ! siproxd ! 1025+-------------+ +--------------+ 1026 eth0 : ppp0 1027</screen> 1028 <para>Siproxd is running on the same host as the masquerading 1029 firewall. The SIP phone is a Grandstream BudgeTone-100. 1030 In this example the external SIP registrar used is 1031 <ulink url='http://www.sipphone.com/'>sipphone.com</ulink>.</para> 1032 <para>siproxd.conf:</para> 1033<screen> 1034if_inbound = eth0 1035if_outbound = ppp0 1036hosts_allow_reg = 10.0.0.0/24 1037sip_listen_port = 5060 1038daemonize = 1 1039silence_log = 1 1040user = siproxd 1041registration_file = /var/lib/siproxd_registrations 1042pid_file = /var/run/siproxd/siproxd.pid 1043rtp_proxy_enable = 1 1044rtp_port_low = 7070 1045rtp_port_high = 7089 1046rtp_timeout = 300 1047default_expires = 600 1048debug_level = 0 1049debug_port = 0 1050</screen> 1051 <para>Firewall configuration (iptables):</para> 1052<screen> 1053# allow incoming SIP and RTP traffic 1054iptables -A INPUT -m udp -p udp -i ppp0 --dport 5060 -j ACCEPT 1055iptables -A INPUT -m udp -p udp -i ppp0 --dport 7070:7089 -j ACCEPT 1056</screen> 1057 <para>Phone configuration (only the relevant items are listed):</para> 1058<screen> 1059IP Address: 10.0.0.10 1060Subnet Mask: 255.255.255.0 1061Default Router: 10.0.0.1 1062DNS Server 1: <DNS Server of your Internet provider> 1063SIP Server: proxy01.sipphone.com 1064Outbound Proxy: 10.0.0.1 1065SIP User ID: 1747669xxxx 1066Authenticate ID: 1747660xxxx 1067Authenticate Passwd: ********* 1068Name: Your Name Here 1069Use DNS SRV: no 1070User ID is phone #: no 1071Sip Registration: yes 1072Unregister on reboot:no 1073Register expiration: 60 1074Early Dial: no 1075local SIP port: 5060 1076local RTP port: 5004 1077Use random port: yes 1078NAT traversal: no 1079Use NAT IP: <empty> 1080Subscribe for MWI: No 1081Send DTMF: via RTP (RFC2833) 1082</screen> 1083 </sect1> 1084 1085 <!-- Chapter 7.3: GS BT-100 with Siproxd running "in front of" a NAT router --> 1086 <sect1 label="7.3"> 1087 <?dbhtml filename="siproxd_guide_c7s3.html"> 1088 <title>GS BT-100 with Siproxd running "in front of" a NAT router</title> 1089 <para>Scenario:</para> 1090<screen> 1091private IP address range : Internet 109210.0.0.x : (public IP address range) 1093 : 1094 : foo.bar.org 1095+-------------+ +--------------+ 1096! !.10 .1 ! masquerading ! publicIP 1097! SIP UA !---------------! NAT router !------------>> 1098! BT-100 ! ! ! ! 1099+-------------+ ! +--------------+ 1100 ! eth0 : ppp0 1101 ! : 1102 ! : 1103 eth0 !.2 1104 +-------------+ 1105 ! siproxd ! 1106 ! ! 1107 +-------------+ 1108</screen> 1109 <para>Siproxd is running on 10.0.0.2. The masquerading NAT 1110 router (e.g. a ADSL NAT router that cannot run any user 1111 applications).</para> 1112 <para>siproxd.conf:</para> 1113<screen> 1114if_inbound = eth0 1115if_outbound = eth0 1116host_outbound = foo.bar.org 1117hosts_allow_reg = 10.0.0.0/24 1118sip_listen_port = 5060 1119daemonize = 1 1120silence_log = 1 1121user = siproxd 1122registration_file = /var/lib/siproxd_registrations 1123pid_file = /var/run/siproxd/siproxd.pid 1124rtp_proxy_enable = 1 1125rtp_port_low = 7070 1126rtp_port_high = 7089 1127rtp_timeout = 300 1128default_expires = 600 1129debug_level = 0 1130debug_port = 0 1131</screen> 1132 <para>NAT router configuration:</para> 1133<screen> 1134forward all incoming traffic on 5060/udp to 10.0.0.2 1135forward all incoming traffic from 7070/udp - 7089/udp to 10.0.0.2 1136</screen> 1137 <para>Phone configuration:</para> 1138<screen> 1139IP Address: 10.0.0.10 1140Subnet Mask: 255.255.255.0 1141Default Router: 10.0.0.1 1142DNS Server 1: <DNS Server of your Internet provider> 1143SIP Server: proxy01.sipphone.com 1144Outbound Proxy: 10.0.0.2 1145SIP User ID: 1747669xxxx 1146Authenticate ID: 1747660xxxx 1147Authenticate Passwd: ********* 1148Name: Your Name Here 1149Use DNS SRV: no 1150User ID is phone #: no 1151Sip Registration: yes 1152Unregister on reboot:no 1153Register expiration: 60 1154Early Dial: no 1155local SIP port: 5060 1156local RTP port: 5004 1157Use random port: yes 1158NAT traversal: no 1159Use NAT IP: <empty> 1160Subscribe for MWI: No 1161Send DTMF: via RTP (RFC2833) 1162</screen> 1163 </sect1> 1164 1165 1166 <!-- Chapter 7.4: Transparent SIP Proxy --> 1167 <sect1 label="7.4"> 1168 <?dbhtml filename="siproxd_guide_c7s4.html"> 1169 <title>Transparent SIP Proxy</title> 1170 <para>Scenario:</para> 1171<screen> 1172private IP address range : Internet 117310.0.0.x : (public IP address range) 1174 : 1175 : foo.bar.org 1176+-------------+ +--------------+ 1177! !.10 .1 ! masquerading ! publicIP 1178! SIP UA !---------------! Firewall !------------>> 1179! ! ! siproxd ! 1180+-------------+ +--------------+ 1181 eth0 : ppp0 1182</screen> 1183 <para>You may have a SIP UA (Phone) that does not allow the 1184 specification of an outbound proxy. If siproxd is running 1185 on the masquerading router, the following configuration will 1186 do so called transparent proxying. The firewall will redirect 1187 outgoing SIP messages to siproxd, however the local Client 1188 is not aware of it.</para> 1189 <para>siproxd.conf:</para> 1190<screen> 1191if_inbound = eth0 1192if_outbound = ppp0 1193hosts_allow_reg = 10.0.0.0/24 1194sip_listen_port = 5060 1195daemonize = 1 1196silence_log = 1 1197user = siproxd 1198registration_file = /var/lib/siproxd_registrations 1199pid_file = /var/run/siproxd/siproxd.pid 1200rtp_proxy_enable = 1 1201rtp_port_low = 7010 1202rtp_port_high = 7019 1203rtp_timeout = 300 1204default_expires = 600 1205debug_level = 0 1206debug_port = 0 1207</screen> 1208 <para>Firewall configuration (iptables):</para> 1209<screen> 1210# redirect outgoing SIP traffic to siproxd (myself) 1211iptables -t nat -A PREROUTING -m udp -p udp -i eth0 \ 1212 --destination-port 5060 -j REDIRECT 1213# allow incoming SIP and RTP traffic 1214iptables -A INPUT -m udp -p udp -i ppp0 --dport 5060 -j ACCEPT 1215iptables -A INPUT -m udp -p udp -i ppp0 --dport 7070:7089 -j ACCEPT 1216</screen> 1217 </sect1> 1218 1219 <!-- Chapter 7.5: Masquerading an Asterisk box --> 1220 <sect1 label="7.5"> 1221 <?dbhtml filename="siproxd_guide_c7s5.html"> 1222 <title>Masquerading an Asterisk box</title> 1223 <para>Scenario:</para> 1224<screen> 1225private IP address range : Internet 122610.0.0.x : (public IP address range) 1227 : 1228 : foo.bar.org 1229+-------------+ +--------------+ 1230! !.10 .1 ! masquerading ! publicIP 1231! Asterisk !---------------! Firewall !------------>> 1232! ! SIP trunk ! siproxd ! 1233+-------------+ +--------------+ 1234 ! ! ! ! ! eth0 : ppp0 1235..!.!.!.!.!..... 1236 extensions 1237 (local SIP clients) 1238</screen> 1239 <para>Siproxd can also be used to masquerade an Asterisk server. 1240 The Asterisk server will register itself as a SIP UA (Client) 1241 to an external SIP registrar. In this example this would be 1242 again sipphone.com. As Asterisk does not allow to specify an 1243 SIP outbound proxy we use the same setup for transparent proxying. 1244 The context values of the asterisk configuration probably must 1245 be adapted to fit your needs.</para> 1246 <para>siproxd.conf:</para> 1247<screen> 1248if_inbound = eth0 1249if_outbound = ppp0 1250hosts_allow_reg = 10.0.0.0/24 1251sip_listen_port = 5060 1252daemonize = 1 1253silence_log = 1 1254user = siproxd 1255registration_file = /var/lib/siproxd_registrations 1256pid_file = /var/run/siproxd/siproxd.pid 1257rtp_proxy_enable = 1 1258rtp_port_low = 7070 1259rtp_port_high = 7089 1260rtp_timeout = 300 1261default_expires = 600 1262debug_level = 0 1263debug_port = 0 1264</screen> 1265 <para>Firewall configuration (iptables):</para> 1266<screen> 1267# redirect outgoing SIP traffic to siproxd (myself) 1268iptables -t nat -A PREROUTING -m udp -p udp -i eth0 \ 1269 --source 10.0.0.11 --destination-port 5060 -j REDIRECT 1270# allow incoming SIP and RTP traffic 1271iptables -A INPUT -m udp -p udp -i ppp0 --dport 5060 -j ACCEPT 1272iptables -A INPUT -m udp -p udp -i ppp0 --dport 7070:7080 -j ACCEPT 1273</screen> 1274 <para>Asterisk configuration (SIP related part):</para> 1275 <para>Note: Very important are the fromuser and fromdomain 1276 keywords in the client section. They are required to have 1277 Asterisk send the correct From headers in SIP dialogs. 1278 The used Asterisk version is 'SVN-branch-1.4-r62331M'.</para> 1279 <para>With newer Asterisk versions, it is no longer required 1280 to have a separate REGISTER definition, this can be made 1281 implicit in the SIP trunk config.</para> 1282<screen> 1283; sip.conf: 1284 1285[general] 1286port = 5060 ; Port to bind to (SIP is 5060) 1287bindaddr = 0.0.0.0 ; Address to bind to (all addresses on machine) 1288context = from-sip-external ; Send unknown SIP callers to this context 1289 1290useragent = PBX ; NOTE: some providers (e.g sipcall.ch) do simply 1291 ; not work with the default "AsteriskPBX" 1292 ; UA String. 1293 1294; Network Settings 1295nat=never 1296localnet = 10.0.0.0/24 1297domain = 10.0.0.10 1298 1299; Codecs 1300disallow=all 1301allow=gsm ; 13 Kbps 1302allow=ulaw ; 64 Kbps 1303allow=alaw ; 64 Kbps 1304autoframing = yes 1305 1306; SIP Settings 1307canreinvite = no ; important! 1308 1309; the following are just my settings I use, however 1310; I dont' consider them critical 1311allowexternaldomains = yes 1312allowexternalinvites = yes 1313allowguest = yes 1314allowsubscribe = no 1315allowtransfer = yes 1316alwaysauthreject = no 1317autodomain = yes 1318callevents = no 1319compactheaders = no 1320dumphistory = no 1321g726nonstandard = no 1322ignoreregexpire = no 1323jbenable = no 1324jbforce = no 1325jblog = no 1326maxcallbitrate = 384 1327maxexpiry = 3600 1328minexpiry = 180 1329notifyringing = no 1330pedantic = no 1331promiscredir = no 1332recordhistory = no 1333relaxdtmf = no 1334rtcachefriends = no 1335rtsavesysname = no 1336rtupdate = no 1337sendrpid = yes 1338sipdebug = no 1339t1min = 100 1340progressinband = no 1341;register = 1342t38pt_udptl = no 1343trustrpid = no 1344usereqphone = no 1345videosupport = no 1346</screen> 1347 <para>The Trunk definition looks like:</para> 1348<screen> 1349; users.conf: 1350 1351[general] 1352; 1353; Full name of a user 1354; 1355fullname = New User 1356userbase = 200 1357; 1358; Create voicemail mailbox and use use macro-stdexten 1359; 1360hasvoicemail = yes 1361; 1362; Set voicemail mailbox 6000 password to 1234 1363; 1364vmsecret = 1234 1365; 1366; Create SIP Peer 1367; 1368hassip = yes 1369hasiax = no 1370; 1371; Create H.323 friend 1372; 1373;hash323 = yes 1374; 1375; Create manager entry 1376; 1377hasmanager = no 1378; 1379; Remaining options are not specific to users.conf entries but are general. 1380; 1381callwaiting = yes 1382threewaycalling = yes 1383callwaitingcallerid = yes 1384transfer = yes 1385canpark = yes 1386cancallforward = yes 1387callreturn = yes 1388callgroup = 1 1389pickupgroup = 1 1390host = dynamic 1391localextenlength = 3 1392allow_aliasextns = no 1393allow_an_extns = no 1394hasagent = no 1395hasdirectory = no 1396 1397 1398;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; 1399; Local SIP UAs 1400; = locally connected phones. nothing special here. 1401;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; 1402[201] 1403callwaiting = yes 1404cid_number = 201 1405context = local_sip 1406email = e@mail 1407fullname = Full Name 1408group = 1409hasagent = yes 1410hasdirectory = yes 1411hasiax = no 1412hasmanager = no 1413hassip = yes 1414hasvoicemail = yes 1415host = dynamic 1416mailbox = 201 1417secret = sip_password 1418threewaycalling = yes 1419zapchan = 1420registeriax = no 1421registersip = yes 1422vmsecret = 1234 1423 1424 1425;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; 1426; SIP Trunks 1427; these are masqueraded via siproxd 1428;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; 1429[trunk_1] 1430disallow = all 1431allow = gsm,ulaw,alaw,adpcm,speex,g729,g723 1432callerid = 1433contact = 17476691234 ; IMPORTANT 1434context = DID_trunk_1 1435dialformat = ${EXTEN:1} 1436fromdomain = proxy01.sipphone.com 1437fromuser = 17476691234 ; IMPORTANT 1438group = 1439hasexten = no 1440hasiax = no 1441hassip = yes 1442host = proxy01.sipphone.com 1443insecure = very 1444port = 5060 1445provider = 1446registeriax = no 1447registersip = yes 1448secret = sip_password 1449trunkname = Custom - sipphone1234 1450trunkstyle = customvoip 1451username = 17476691234 1452</screen> 1453 </sect1> 1454 </chapter> 1455</book> 1456