readme

siproxd is a proxy/masquerading for the SIP protocal.

Be warned, this (and all the other) documentantation is far from
complete. This is still considered an alpha release.


OVERVIEW
========
Siprox is an proxy/masquerading daemon for the SIP protocol.
It handles registrations of SIP clients on a private IP network
and performs rewriting of the SIP message bodies to make SIP
connections possible via an masquerading firewall.
It allows SIP clients (like kphone, linphone) to work behind
an IP masquerading firewall or router.

SIP (Session Initiation Protocol, RFC3261) is used by Softphones
(Voice over IP) to initiate communication. By itself, SIP does not
work via masquerading firewalls as the transfered data contains
IP addresses and port numbers.



PREREQUISITES
=============
- OS of either:
  * Linux (preferred kernel 2.2.x or 2.4.x)
  * FreeBSD
  * Solaris (porting is beeing worked on but you may try it)
  
- libosip2 package (http://www.fsf.org/software/osip/)



HOW TO GET STARTED
==================
- make sure libosip2 is installed

- ./configure
  For Flifl: see doc/FLI4L_HOWTO.txt

- make

- make install

- edit /usr/etc/siproxd.conf according to your situation
  At least configure  'if_inbound' and 'if_outbound'. The must represent
  the interface names (eg. on Linux: ppp0, eth1) for the inbound
  and outbound interface.
  ** The use of 'host_inbound' and 'host_outbound' is deprecheated!
     'host_inbound' is the firewalls IP address of your private network,
     'host_outbound' is the  publich IP address or hostname of the
     firewall. (If you have dynamic IP addresses, then you might want
     to use a hostname here and use a dynamic DNS service like [1])


- edit /usr/etc/siproxd_passwd.cfg if you enable client authentication
  in siproxd.conf

- start siproxd (siproxd does *not* require root privilegdes)
  $ siproxd



PROBLEM REPORTING
=================
If you encounter problems/crashes and ask for support, please include
as much information as possible. Very helpful is a debug log that
has been recorded at the time of the misbehaviour.
Also include the exact versions of the siproxd package and libosip2
that you are using. You should also include your siproxd.conf.
 

The easiest way to generate a debug log is:
1) make sure siproxd is not started as daemon.
   -> 'daemonize = 0' in the config file.
2) start siproxd:
   $ ./siproxd -d -1 2>debug.log
3) reproduce the error
4) include the debug.log in your error report.

If siproxd crashes, a stack backtrace usually is helpful to me:
1) start siproxd in the debugger (daemonize set to 0):
   $ gdb ./src/siproxd
   (gdb) set args -c /path/to/siproxd.conf
   (gdb) run
2) reproduce the crash
3) use gdb to print the stack backtrace:
   (gdb) info thread
   ...
   (gdb) bt
   #0  0x400ec9ee in __select ()
   #1  0xbffff6f8 in ?? ()
   #2  0x804a5c2 in main (argc=3, argv=0xbffffc54) at siproxd.c:186
   #3  0x4005bcb3 in __libc_start_main (main=0x804a30c <main>, argc=3, 
       argv=0xbffffc54, init=0x8049a08 <_init>, fini=0x804edac <_fini>, 
       rtld_fini=0x4000a350 <_dl_fini>, stack_end=0xbffffc4c)
       at ../sysdeps/generic/libc-start.c:78
   (gdb) 
4) copy-paste all the output and include it in your problem report.


WHAT SIPROXD DOES
=================
Siproxd's purpose is to act as an SIP proxy for softphones located
in private IP ranges. Therefore it will rewrite SIP messages to allow a
softphone to communicate to a counterpart that is located in the Internet.
There usually will be a masquerading firewall in between to 'hide' the
private IP range (either via NAT - network address translation or 
masuerading). Check the scenario drawn below.



Scenario
--------

 private IP address range             :          Internet
 10.0.0.x                             :          (publich IP address range)
                                      :
                                      :         foo.bar.org
 +-------------+	       +--------------+
 !             !.10	    .1 ! masquerading ! publicIP
 ! IntHost     !---------------! Firewall     !------------>>  
 !             !               !              !   
 +-------------+	       +--------------+
                           eth0       :        ppp0



 - The Firewall does IP masquerading and is running siproxd

 - IntHost is running an SIP softphone (like linphone, kphone)

 - The SIP address used by the softphone is sip:[e-mail]

 - The softphone is configured to register itself at siproxd
   running on the firewall host (10.0.0.1) as sip:[e-mail]

 - foo.bar.org is the domain name corresponding to the public IP address
   of the firewall (eg use some dynamic DNS service [1])

IPCHAINS:
 Firewall rules for incoming traffic:
 $ ipchains -A input --proto udp --dport 5060 --log  -j ACCEPT
 $ ipchains -A input --proto udp --dport 7070:7080   -j ACCEPT

 Firewall rule for masquerading outgoing traffic:
 $ ipchains -A forward -i ppp0 -j MASQ -s 10.0.0.0/24 -d 0.0.0.0/0

IPTABLES:
 Firewall rules for incoming traffic:
 $iptables -A INPUT -i ppp0 -p udp -m udp --dport 5060      -j ACCEPT 
 $iptables -A INPUT -i ppp0 -p udp -m udp --dport 7070:7080 -j ACCEPT 

 Firewall rule for masquerading outgoing traffic:
 $ iptables -t nat -A POSTROUTING -s 10.0.0.0/255.255.255.0 -j MASQUERADE


 The first line will allow incoming SIP traffic. The second line will
 allow incoming RTP traffic on the ports 7070 - 7080 (the default port
 range used by siproxd for incoming RTP traffic).

 The rule for masquerading will ensure that the outgoing RTP data stream
 is masqueraded properly and sent to the remote host.


REFERENCES
==========
[1] dynamic DNS service http://www.dyndns.org



LIMITATIONS
===========
- currently, the SIP part only supports UDP
- very likely it does not follow the SIP spec (RFC3261) in all details
- check the TODO file for more things that we-cannot-do-but-would-like-to


IMPORTANT NOTICE
================
The gethostbyname() function leaks memory in glibc 2.1.1 (-> RedHat 6.0).
The quick fix is to delete the nisplus service from hosts entry in
/etc/nsswitch.conf.
In my tests, memory usage remained stable after I made the mentioned change.

(source: http://www.squid-cache.org/Doc/FAQ/FAQ-14.html)


CONTACTS
========
Please feel free to contact the author to:
   - provide feedback, report bugs,
   - request for additional features
   - report interoperability with softphones
   - ...

and visit the website at http://siproxd.sourceforge.net/


There is a siproxd mailinglist available on sourceforge.

Thomas Ries  ([e-mail])
GnuPG: pub  1024D/87BCDC94 2000-03-19 Thomas Ries <[e-mail]>
-      Fingerprint = 13D1 19F5 77D0 4CEC 8D3F  A24E 09FC C18A 87BC DC94
-      Key via pgp.openpkg.org / http://www.ries.ch.vu/87BCDC94.pub
VoIP:  sip:[e-mail] | sip:[e-mail]


CREDITS
=======

Thanks to sourceforge.net for providing the distribution platform and
infrastructure.

Also credits to the maintainers of linphone from where I have taken some
code parts for MD5 proxy authentication.