userapps/opensource/siproxd/README

   1
   2
   3 Be warned, this (and all the other) documentation is far from
   4 complete. This is still considered an alpha release.
   5
   6
   7 OVERVIEW
   8 ========
   9 Siproxd is a proxy/masquerading daemon for the SIP protocol.
  10 It handles registrations of SIP clients on a private IP network
  11 and performs rewriting of the SIP message bodies to make SIP
  12 connections work via an masquerading firewall (NAT).
  13 It allows SIP software clients (like kphone, linphone) or SIP
  14 hardware clients (Voice over IP phones which are SIP-compatible,
  15 such as those from Cisco, Grandstream or Snom) to work behind
  16 an IP masquerading firewall or NAT router.
  17
  18 SIP (Session Initiation Protocol, RFC3261) is the protocol of
  19 choice for most VoIP (Voice over IP) phones to initiate
  20 communication. By itself, SIP does not work via masquerading
  21 firewalls as the transfered data contains IP addresses and
  22 port numbers. There do exist other solutions to traverse NAT existing
  23 (like STUN, or SIP aware NAT routers), but such a solutions has its
  24 disadvantages or may not be applied to a given situation.
  25 Siproxd does not aim to be a replacement for these solutions,
  26 however in some situations siproxd may bring advantages.
  27
  28
  29 PREREQUISITES
  30 =============
  31 - OS of either:
  32   * Linux (preferred kernel 2.2.x or 2.4.x)
  33   * FreeBSD
  34   * OpenBSD
  35   * SunOS
  36   * Mac OS X
  37
  38 - libosip2 package (http://www.fsf.org/software/osip/)
  39
  40
  41
  42 HOW TO GET STARTED
  43 ==================
  44 - make sure libosip2 is installed
  45   If your libposip2 libraries are installed in
  46   /usr/local/lib, be sure to include this library path to /etc/ld.so.conf
  47
  48 - ./configure
  49   For Flifl: see doc/FLI4L_HOWTO.txt
  50
  51 - make
  52
  53 - make install
  54
  55 - edit /usr/etc/siproxd.conf according to your situation
  56   At least configure  'if_inbound' and 'if_outbound'. The must represent
  57   the interface names (e.g. on Linux: ppp0, eth1) for the inbound
  58   and outbound interface.
  59
  60
  61 - edit /usr/etc/siproxd_passwd.cfg if you enable client authentication
  62   in siproxd.conf
  63
  64 - start siproxd (siproxd does *not* require root privileges)
  65   $ siproxd
  66
  67
  68
  69 PROBLEM REPORTING
  70 =================
  71 If you encounter problems/crashes and ask for support, please include
  72 as much information as possible. Very helpful is a debug log that
  73 has been recorded at the time of the misbehavior.
  74 Also include the exact versions of the siproxd package and libosip2
  75 that you are using. You should also include your siproxd.conf.
  76
  77
  78 The easiest way to generate a debug log is:
  79   1) make sure siproxd is not started as daemon.
  80      -> 'daemonize = 0' in the config file.
  81   2) start siproxd:
  82      $ ./siproxd -d -1 2>debug.log
  83   3) reproduce the error
  84   4) include the file debug.log in your error report.
  85
  86 Since Version 0.5.10 there also exists the possibility to obtain
  87 the debug log remote via TCP (useful if running siproxd on an embedded
  88 system). To enable this feature, edit the configuration file and
  89 set 'debug_port' to a free TCP port number (e.g. 5050). Then (after
  90 starting siproxd) you can connect from any remote client to this
  91 TCP port (e.g. using netcat) and all the debug output will be sent
  92 via network:
  93   1) edit configuration file:
  94      -> 'daemonize = 1' have siproxd started as daemon
  95      -> 'silence_log' should be set to 1
  96      -> 'debug_pattern = -1'
  97      -> 'debug_port = 5050' (or any other TCP port you like)
  98   2) have siproxd started the usual way
  99   3) connect from a remote machine and write into a file:
 100      $ netcat <IP_of_siproxd> <port> > debug.log
 101   4) reproduce the error
 102   5) include the file debug.log in your error report.
 103
 104
 105 If siproxd crashes, a stack backtrace usually is helpful to me:
 106   1) start siproxd in the debugger (daemonize set to 0):
 107      $ gdb ./src/siproxd
 108      (gdb) set args -c /path/to/siproxd.conf
 109      (gdb) run
 110   2) reproduce the crash
 111   3) use gdb to print the stack backtrace:
 112    (gdb) info thread
 113    ...
 114    (gdb) bt
 115    #0  0x400ec9ee in __select ()
 116    #1  0xbffff6f8 in ?? ()
 117    #2  0x804a5c2 in main (argc=3, argv=0xbffffc54) at siproxd.c:186
 118    #3  0x4005bcb3 in __libc_start_main (main=0x804a30c <main>, argc=3,
 119        argv=0xbffffc54, init=0x8049a08 <_init>, fini=0x804edac <_fini>,
 120        rtld_fini=0x4000a350 <_dl_fini>, stack_end=0xbffffc4c)
 121        at ../sysdeps/generic/libc-start.c:78
 122    (gdb)
 123   4) copy-paste all the output and include it in your error report.
 124
 125
 126
 127 SENDING A PATCH
 128 ===============
 129 If you send a patch, please make the diff using "diff -Naur" and
 130 include the version of siproxd you used to patch. This makes it a lot
 131 easier for me to merge it.
 132
 133
 134 WHAT SIPROXD DOES
 135 =================
 136 Siproxd's purpose is to act as an SIP proxy for SIP softphones/hardphones
 137 located behind an masquerading router (NAT). It will rewrite SIP messages
 138 to allow a SIP phone to communicate to a counterpart that is located in
 139 the Internet. Check the scenarios drawn below.
 140
 141
 142
 143 Scenario 1
 144 ----------
 145
 146  private IP address range             :          Internet
 147  10.0.0.x                             :          (public IP address range)
 148                                       :
 149                                       :         foo.bar.org
 150  +-------------+               +--------------+
 151  !             !.10         .1 ! masquerading ! publicIP
 152  ! IntHost     !---------------! Firewall     !------------>>
 153  !             !               !              !
 154  +-------------+               +--------------+
 155                            eth0       :        ppp0
 156
 157  - The Firewall does IP masquerading (NAT) and is running siproxd
 158
 159  - IntHost is running an SIP phone (like linphone, kphone)
 160
 161  - The SIP address used by the SIP phone is sip:johndoe@foo.bar.org
 162
 163  - The SIP phone is configured to register itself at siproxd
 164    running on the firewall host (10.0.0.1) as sip:johndoe@foo.bar.org
 165
 166  - foo.bar.org is the domain name corresponding to the public IP address
 167    of the firewall (e.g. use some dynamic DNS service [1])
 168
 169
 170 Scenario 2
 171 ----------
 172
 173  private IP address range             :          Internet
 174  10.0.0.x                             :          (public IP address range)
 175                                       :
 176                                       :     foo.bar.org
 177  +-------------+               +--------------+              +--------------+
 178  !             !.10         .1 ! masquerading ! publicIP     ! external SIP !
 179  ! IntHost     !---------------! Firewall     !------------>>! Registrar    !
 180  !             !               !              !              !              !
 181  +-------------+               +--------------+              +--------------+
 182                            eth0       :        ppp0
 183
 184  - The Firewall does IP masquerading (NAT) and is running siproxd
 185
 186  - IntHost is running an SIP phone (like linphone, kphone)
 187
 188  - The SIP address used by the SIP phone is sip:johndoe@foo.bar.org
 189
 190  - The SIP phone is configured to register itself at the external<BR>
 191    registrar as sip:johndoe@foo.bar.org
 192
 193  - foo.bar.org is the domain name corresponding to the public IP address
 194    of the firewall (e.g. use some dynamic DNS service [1])
 195
 196
 197 IPCHAINS:
 198  Firewall rules for incoming traffic:
 199  # ipchains -A input --proto udp --dport 5060 --log  -j ACCEPT
 200  # ipchains -A input --proto udp --dport 7070:7080   -j ACCEPT
 201
 202 IPTABLES:
 203  Firewall rules for incoming traffic:
 204  # iptables -A INPUT -i ppp0 -p udp -m udp --dport 5060      -j ACCEPT
 205  # iptables -A INPUT -i ppp0 -p udp -m udp --dport 7070:7080 -j ACCEPT
 206
 207  The first line will allow incoming SIP traffic (UDP port 5060). The second
 208  line will allow incoming RTP traffic on the ports 7070-7080 (the default port
 209  range used by siproxd for incoming RTP traffic).<P>
 210
 211
 212 REFERENCES
 213 ==========
 214 [1] dynamic DNS service http://www.dyndns.org
 215
 216
 217
 218 LIMITATIONS
 219 ===========
 220 - currently, the SIP part only supports UDP
 221 - very likely it does not follow the SIP spec (RFC3261) in all details
 222 - check the TODO file for more things that we-cannot-do-but-would-like-to
 223
 224
 225 IMPORTANT NOTICE
 226 ================
 227 The gethostbyname() function leaks memory in glibc 2.1.1 (-> RedHat 6.0).
 228 The quick fix is to delete the nisplus service from hosts entry in
 229 /etc/nsswitch.conf.
 230 In my tests, memory usage remained stable after I made the mentioned change.
 231
 232 (source: http://www.squid-cache.org/Doc/FAQ/FAQ-14.html)
 233
 234
 235 CONTACTS
 236 ========
 237 Please feel free to contact the author to:
 238    - provide feedback, report bugs,
 239    - request for additional features
 240    - report interoperability with various phones
 241    - ...
 242
 243 and visit the website at http://siproxd.sourceforge.net/
 244
 245
 246 There is a siproxd mailing list available on sourceforge.
 247
 248 Thomas Ries  (tries@gmx.net)
 249 GnuPG: pub  1024D/87BCDC94 2000-03-19 Thomas Ries <tries@gmx.net>
 250 -      Fingerprint = 13D1 19F5 77D0 4CEC 8D3F  A24E 09FC C18A 87BC DC94
 251 -      Key via pgp.openpkg.org / http://www.ries.ch.vu/87BCDC94.pub
 252 VoIP:  sip:17476691342@proxy01.sipphone.com | sip:431783@fwd.pulver.com
 253
 254
 255 CREDITS
 256 =======
 257
 258 Thanks to sourceforge.net for providing the distribution platform and
 259 infrastructure.
 260
 261 Also credits to the maintainers of linphone from where I have taken some
 262 code parts for MD5 proxy authentication.
 263