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.



REQUIREMENTS
============
- libosip-0.8.8		(http://www.fsf.org/software/osip/)
- pthreads		(should be part of any Linux distribution)

Up to now, siporxd only has been tested under:
- Redhat Linux 6.0
- Redhat Linux 7.2
- SUSE 5.3 (libc5)

However, it should build and run under newer versions (feedback is welcome).



HOW TO GET STARTED
==================

- ./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.

The easiest way to do this:
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 (core dump), a stack backtrace usually is helpful to me:
1) reproduce the crash -> core file
2) use gdb to print the stack backtrace:
   $ gdb ./src/siproxd core
   (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) 



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.

With release 0.1.2 siproxd is also able to proxy incoming RTP data
streams. The config parameters 'rtp_port_low' and rtp_port_high' define
the port range that siproxd will use for incoming RTP data streams.
'rtp_timeout' defines after what time an unused  (no data received)
rtp stream is considered dead and removed.

** RTP data stream proxying is still experimental code.
** As I had not yet the possibility to test this feature extensively,
** I'm happy about any feedback.



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:johndoe@foo.bar.org

 - The softphone is configured to register itself at siproxd
   running on the firewall host (10.0.0.1) as sip:johndoe@foo.bar.org

 - 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  (tries@gmx.net)
   GnuPG Public Key:
   pub  1024D/87BCDC94 2000-03-19 Thomas Ries (tries@gmx.net)
   Key fingerprint = 13D1 19F5 77D0 4CEC 8D3F  A24E 09FC C18A 87BC DC94



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.