1136 lines
40 KiB
Plaintext
1136 lines
40 KiB
Plaintext
<!doctype book PUBLIC "-//OASIS//DTD DocBook V4.2//EN" [
|
|
]>
|
|
<book id="siproxd-doc">
|
|
<?dbhtml filename="siproxd_guide.html">
|
|
|
|
<bookinfo>
|
|
<date>2005-04-10</date>
|
|
<title>Siproxd Users Guide</title>
|
|
<abbrev>Siproxd</abbrev>
|
|
<authorgroup>
|
|
<author>
|
|
<firstname>Thomas</firstname>
|
|
<surname>Ries</surname>
|
|
</author>
|
|
</authorgroup>
|
|
<address>
|
|
<email>tries@users.sourceforge.net</email>
|
|
</address>
|
|
<copyright>
|
|
<year>2005-2007</year>
|
|
<holder>Thomas Ries</holder>
|
|
</copyright>
|
|
<legalnotice>
|
|
<para>This document can be freely redistributed according to
|
|
the terms of the GNU General Public License.</para>
|
|
</legalnotice>
|
|
<revhistory>
|
|
<revision>
|
|
<revnumber>0.1</revnumber>
|
|
<date>2005-04-10</date>
|
|
<authorinitials>tries@users.sourceforge.net</authorinitials>
|
|
<revremark>Initial version</revremark>
|
|
</revision>
|
|
<revision>
|
|
<revnumber>0.2</revnumber>
|
|
<date>2006-07-28</date>
|
|
<authorinitials>tries@users.sourceforge.net</authorinitials>
|
|
<revremark>Comment on Asterisk Scenario</revremark>
|
|
</revision>
|
|
<revision>
|
|
<revnumber>0.3</revnumber>
|
|
<date>2007-05-15</date>
|
|
<authorinitials>tries@users.sourceforge.net</authorinitials>
|
|
<revremark>New Asterisk Config Files</revremark>
|
|
</revision>
|
|
</revhistory>
|
|
</bookinfo>
|
|
<toc></toc>
|
|
|
|
<!-- We are done with the preliminaries, now we can start with
|
|
the body of the document -->
|
|
|
|
<!-- Chapter 1: Overview -->
|
|
<chapter label="" id="README">
|
|
<?dbhtml filename="siproxd_guide_c0.html">
|
|
<title>README</title>
|
|
<para>Important information, please read me!</para>
|
|
|
|
<sect1 label="">
|
|
<?dbhtml filename="siproxd_guide_c0s1.html">
|
|
<title>Important / Warning</title>
|
|
<para>As it still happens that people try to mix different NAT
|
|
traversal techologies together with siproxd I'll put some words
|
|
here:
|
|
<itemizedlist mark='bullet'>
|
|
<listitem><para>Do NOT USE anything like an STUN Server together
|
|
with siproxd.</para></listitem>
|
|
<listitem><para>Do NOT USE any additional techologies trying to
|
|
help in NAT traversal (additional firewall modules like
|
|
ip_nat_sip.ko or whatever fancy stuff may tempt you).
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
If you do not follow the above rules, those other
|
|
"helping technologies" WILL DO CONFLICT with siproxd and result
|
|
in a mess.</para>
|
|
</sect1>
|
|
|
|
<!-- Chapter 1: Overview -->
|
|
<chapter label="1" id="Overview">
|
|
<?dbhtml filename="siproxd_guide_c1.html">
|
|
<title>Overview</title>
|
|
<para>Siproxd 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.</para>
|
|
<para>SIP (Session Initiation Protocol, RFC3261) is used by Softphones
|
|
and Hardphones (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.</para>
|
|
<para>There exist so called STUN servers that allow a SIP client to
|
|
figure out its public visible IP address and use this one instead.
|
|
As a drawback, usually on the masquerading firewall a very wide port
|
|
range must be opened up for the incoming RTP traffic. The SIP client
|
|
must support STUN (which most of them do).</para>
|
|
<para>Siproxd uses another approach (application layer proxy) and places
|
|
itself as outbound proxy in between the local SIP client and the
|
|
remote client or registrar. It does rewrite the SIP traffic on the
|
|
fly and also includes a RTP proxy for incoming and outgoing RTP
|
|
traffic (the actual audio data). The port range to be used for
|
|
receiving RTP data is configurable, so the firewall only must
|
|
allow incoming traffic for a small port range.</para>
|
|
<para>A standard scenario would look like:
|
|
<screen>
|
|
private IP address range : Internet
|
|
10.0.0.x : (public IP address range)
|
|
:
|
|
: foo.bar.org
|
|
+-------------+ +--------------+
|
|
! !.10 .1 ! masquerading ! publicIP
|
|
! IntHost !---------------! Firewall !------------>>
|
|
! ! ! !
|
|
+-------------+ +--------------+
|
|
eth0 : ppp0
|
|
</screen>
|
|
|
|
<itemizedlist mark='bullet'>
|
|
<listitem><para>The Firewall does IP masquerading and is running
|
|
siproxd</para></listitem>
|
|
<listitem><para>IntHost is running an SIP softphone (like linphone,
|
|
kphone)</para></listitem>
|
|
<listitem><para>The SIP address used by the softphone is
|
|
sip:johndoe@foo.bar.org</para></listitem>
|
|
|
|
<listitem><para>The softphone is configured to register itself at
|
|
siproxd running on the firewall host (10.0.0.1) as
|
|
sip:johndoe@foo.bar.org</para></listitem>
|
|
<listitem><para>foo.bar.org is the domain name corresponding to the
|
|
public IP address of the firewall (e.g. use some dynamic DNS
|
|
service [1])</para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</chapter>
|
|
|
|
<!-- Chapter 2: Building and Installation -->
|
|
<chapter label="2" id="Building-and-Installation">
|
|
<?dbhtml filename="siproxd_guide_c2.html">
|
|
<title>Building and Installation</title>
|
|
|
|
<!-- Chapter 2.1: Prerequisites -->
|
|
<sect1 label="2.1" >
|
|
<?dbhtml filename="siproxd_guide_c2s1.html">
|
|
<title>Prerequisites</title>
|
|
<para>Operating system of either:
|
|
<itemizedlist mark='bullet'>
|
|
<listitem><para>Linux (should work with any kernel)</para></listitem>
|
|
<listitem><para>FreeBSD</para></listitem>
|
|
<listitem><para>Solaris (porting is still being worked on but
|
|
you may try it)</para></listitem>
|
|
</itemizedlist>
|
|
Additional required Packages:
|
|
<itemizedlist mark='bullet'>
|
|
<listitem><para><ulink url='http://www.gnu.org/software/osip'>
|
|
Libosip2 package</ulink></para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</sect1>
|
|
|
|
<!-- Chapter 2.2: Compiling and Installing -->
|
|
<sect1 label="2.2">
|
|
<?dbhtml filename="siproxd_guide_c2s2.html">
|
|
<title>Compiling and Installing</title>
|
|
<para>It is quite simple. If you have a more-or-less standard
|
|
installation and libosip2 installed at a standard location,
|
|
it should be sufficient to do:
|
|
<screen>
|
|
./configure
|
|
make
|
|
make install
|
|
</screen>
|
|
</para>
|
|
<para>This will install siproxd into /usr/local/. If you wish
|
|
to install it into another location, specify
|
|
<userinput>--prefix=<myprefix></userinput> when running
|
|
<userinput>./configure</userinput>. If you have installed
|
|
libosip2 in an non-standard location use
|
|
<userinput>--with-libosip-prefix=<libosipprefix></userinput>
|
|
to tell configure where to find libosip2 (e.g.
|
|
<userinput>--with-libosip-prefix=$HOME/lib</userinput>).</para>
|
|
<para>Common features for ./configure:
|
|
<screen>
|
|
--enable-static build statically linked executable
|
|
--with-libosip-prefix=DIR use libosip2 from DIR/include and DIR/lib
|
|
--with-extra-includes=DIR adds non standard include paths
|
|
--with-extra-libs=DIR adds non standard library paths
|
|
</screen>
|
|
</para>
|
|
<para>Edit <filename>/usr/etc/siproxd.conf</filename> according
|
|
to your situation, at least configure
|
|
<parameter>if_inbound</parameter> and
|
|
<parameter>if_outbound</parameter>. They must represent the
|
|
interface names (e.g. on Linux: ppp0, eth1) for the inbound
|
|
and outbound interfaces.</para>
|
|
<para>Edit <filename>/usr/etc/siproxd_passwd.cfg</filename>
|
|
if you enable client authentication.</para>
|
|
<para>Start siproxd:
|
|
<screen>
|
|
# siproxd
|
|
</screen>
|
|
</para>
|
|
</sect1>
|
|
</chapter>
|
|
|
|
<!-- Chapter 3: Configuration -->
|
|
<chapter label="3" id="Configuration">
|
|
<?dbhtml filename="siproxd_guide_c3.html">
|
|
<title>Configuration</title>
|
|
|
|
<!-- Chapter 3.1: The configuration file 'siproxd.conf' -->
|
|
<sect1 label="3.1">
|
|
<?dbhtml filename="siproxd_guide_c3s1.html">
|
|
<title>The configuration file 'siproxd.conf'</title>
|
|
<para>Siproxd by default searches for its configuration
|
|
file in the following locations:
|
|
<itemizedlist mark='bullet'>
|
|
<listitem><para><filename>$HOME/.siproxdrc
|
|
</filename></para></listitem>
|
|
<listitem><para><filename><buildingprefix>/etc/siproxd.conf
|
|
</filename></para></listitem>
|
|
<listitem><para><filename>/etc/siproxd.conf
|
|
</filename></para></listitem>
|
|
<listitem><para><filename>/usr/etc/siproxd.conf
|
|
</filename></para></listitem>
|
|
<listitem><para><filename>/usr/local/etc/siproxd.conf
|
|
</filename></para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
|
|
<para>The following is a list of directives that do exist.
|
|
Note that string values MUST NOT contain spaces or tabs.
|
|
Also read the explanations included in the supplied example
|
|
configuration file fro more explanation. Items with a # in
|
|
front are normally disabled / not defined.</para>
|
|
<para>To start with siproxd in the first run, just adapt the
|
|
interface definition for the inbound and outbound network
|
|
interfaces (<parameter>if_inbound</parameter> and
|
|
<parameter>if_outbound</parameter>).</para>
|
|
|
|
<para>Definition of network interfaces for the inbound network
|
|
(local network where your SIP client is connected, this
|
|
network normally uses IP addresses from on of the private
|
|
IP ranges like 10.x.x.x, 192.168.x.x) and outbound network
|
|
(your connection to the Internet, normally this interface
|
|
has a public IP assigned by your provider).</para>
|
|
<screen>
|
|
if_inbound = eth0
|
|
if_outbound = ppp0
|
|
</screen>
|
|
<para>Usually only the <parameter>if_inbound</parameter> and
|
|
<parameter>if_outbound</parameter> directives will be used.
|
|
The <parameter>host_outbound</parameter> directive comes into
|
|
play when running siproxd "in front of" a NAT router. Please
|
|
check the configuration examples in this document for more
|
|
details.</para>
|
|
<screen>
|
|
# host_outbound = <my_public_ip_address>
|
|
</screen>
|
|
|
|
<para>Access control lists for incoming SIP registrations and
|
|
SIP traffic in general. These are comma separated lists of
|
|
the form <IP>/<mask>, note that no spaces are
|
|
allowed within the list (the configuration file parser
|
|
cannot yet handle spaces).</para>
|
|
<screen>
|
|
# hosts_allow_reg = 192.168.1.0/24,192.168.2.0/24
|
|
# hosts_allow_sip = 123.45.0.0/16,123.46.0.0/16
|
|
# hosts_deny_sip = 10.0.0.0/8,11.0.0.0/8
|
|
</screen>
|
|
|
|
<para>Port to listen for incoming SIP messages. 5060 is
|
|
usually the correct choice, don't change this unless you
|
|
have a reason to.</para>
|
|
<screen>
|
|
sip_listen_port = 5060
|
|
</screen>
|
|
|
|
<para>Shall siproxd run as daemon? Usually 1 is the correct
|
|
choice. If you want siproxd not to daemonize and keep
|
|
running in foreground and writing its output to the terminal
|
|
set this to 0.</para>
|
|
<screen>
|
|
daemonize = 1
|
|
</screen>
|
|
|
|
<para>Siproxd does log using the syslog() facility when
|
|
running a daemon. This setting controls how much logging
|
|
is done:
|
|
<itemizedlist mark='bullet'>
|
|
<listitem><para><literal>0 - DEBUGs, INFOs, WARNINGs and ERRORs
|
|
</literal></para></listitem>
|
|
<listitem><para><literal>1 - INFOs, WARNINGs and ERRORs
|
|
</literal></para></listitem>
|
|
<listitem><para><literal>2 - WARNINGs and ERRORs
|
|
</literal></para></listitem>
|
|
<listitem><para><literal>3 - only ERRORs
|
|
</literal></para></listitem>
|
|
<listitem><para><literal>4 - absolutely nothing
|
|
</literal></para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<screen>
|
|
silence_log = 0
|
|
</screen>
|
|
|
|
<para>Siproxd can log call establishment to syslog.</para>
|
|
<screen>
|
|
log_calls = 1
|
|
</screen>
|
|
|
|
<para>If siproxd is started as root, it can drop the root
|
|
privileges and change its user ID at startup. It also can
|
|
put itself into a chroot() jail (see 4.2 for details)</para>
|
|
<screen>
|
|
user = nobody
|
|
# chrootjail = /var/lib/siproxd/
|
|
</screen>
|
|
|
|
<para>Where to store the current registrations. This allows
|
|
siproxd to remember registration across a restart. An empty
|
|
value means we do not save registrations. The specified
|
|
directory path must exist.</para>
|
|
<screen>
|
|
registration_file = /var/lib/siproxd/siproxd_registrations
|
|
</screen>
|
|
|
|
<para>Where to create the PID file.</para>
|
|
<screen>
|
|
pid_file = /var/run/siproxd/siproxd.pid
|
|
</screen>
|
|
|
|
<para>Enable/disable the RTP proxy. This must always be
|
|
enabled. In some future release this directive may
|
|
become obsolete.</para>
|
|
<screen>
|
|
rtp_proxy_enable = 1
|
|
</screen>
|
|
|
|
<para>Port range (UDP) that siproxd will use for incoming
|
|
and outgoing RTP traffic. A firewall must be configured
|
|
to allow traffic from and to these ports (UDP only). By
|
|
default the range 7070 up to (and including) 7089 is used.
|
|
This allows up to 10 simultaneous calls (2 ports per call).
|
|
If you need more simultaneous calls, increase the range.</para>
|
|
<screen>
|
|
rtp_port_low = 7070
|
|
rtp_port_high = 7089
|
|
</screen>
|
|
|
|
<para>Timeout for an RTP stream. If for the specified number
|
|
of seconds no data is relayed on an active stream, it is
|
|
considered dead and will be killed.</para>
|
|
<screen>
|
|
rtp_timeout = 300
|
|
</screen>
|
|
|
|
<para>If a REGISTER request does not contain an
|
|
<literal>Expires</literal> header or <literal>expires=</literal>
|
|
parameter in the <literal>Contact</literal> header, this
|
|
number of seconds will be used and reported back to the UA
|
|
in the answer.</para>
|
|
<screen>
|
|
default_expires = 600
|
|
</screen>
|
|
|
|
<para>If siproxd is used as registration server and
|
|
authentication is wanted, define the following directive.
|
|
If <parameter>proxy_auth_realm</parameter> is defined
|
|
(a string), clients will be forced to authenticate themselfs
|
|
to the proxy (for registration only). To disable Authentication,
|
|
simply comment out this line. Default is disabled.</para>
|
|
<screen>
|
|
# proxy_auth_realm = Authentication_Realm
|
|
</screen>
|
|
|
|
<para>The password to be used for authentication may be a global
|
|
one</para>
|
|
<screen>
|
|
# proxy_auth_passwd = some_password
|
|
</screen>
|
|
|
|
<para>or on a per user base, stored in its own file.
|
|
<parameter>proxy_auth_pwfile</parameter> takes precedence over
|
|
<parameter>proxy_auth_passwd</parameter></para>
|
|
<screen>
|
|
# proxy_auth_pwfile = /etc/mysiproxd_passwd.cfg
|
|
</screen>
|
|
|
|
<para>To enable additional debug output of siproxd.
|
|
This is a bit pattern representing the following items.
|
|
Default is 0x0 - disabled. See below in this document
|
|
for information on how to create a debug log file.
|
|
<itemizedlist mark='bullet'>
|
|
<listitem><para><literal>DBCLASS_BABBLE 0x00000001 // babble (like entering/leaving fnc)
|
|
</literal></para></listitem>
|
|
<listitem><para><literal>DBCLASS_NET 0x00000002 // network
|
|
</literal></para></listitem>
|
|
<listitem><para><literal>DBCLASS_SIP 0x00000004 // SIP manipulations
|
|
</literal></para></listitem>
|
|
<listitem><para><literal>DBCLASS_REG 0x00000008 // Client registration
|
|
</literal></para></listitem>
|
|
<listitem><para><literal>DBCLASS_NOSPEC 0x00000010 // non specified class
|
|
</literal></para></listitem>
|
|
<listitem><para><literal>DBCLASS_PROXY 0x00000020 // proxy
|
|
</literal></para></listitem>
|
|
<listitem><para><literal>DBCLASS_DNS 0x00000040 // DNS stuff
|
|
</literal></para></listitem>
|
|
<listitem><para><literal>DBCLASS_NETTRAF 0x00000080 // network traffic
|
|
</literal></para></listitem>
|
|
<listitem><para><literal>DBCLASS_CONFIG 0x00000100 // configuration
|
|
</literal></para></listitem>
|
|
<listitem><para><literal>DBCLASS_RTP 0x00000200 // RTP proxy
|
|
</literal></para></listitem>
|
|
<listitem><para><literal>DBCLASS_ACCESS 0x00000400 // Access list evaluation
|
|
</literal></para></listitem>
|
|
<listitem><para><literal>DBCLASS_AUTH 0x00000800 // Authentication
|
|
</literal></para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<screen>
|
|
debug_level = 0x00000000
|
|
</screen>
|
|
|
|
<para>You may connect to this port from a remote machine and
|
|
receive the debug output. This allows bettwer creation of
|
|
debug output on embedded systems that do not have enough
|
|
memory for large disk files. Port number 0 means this feature
|
|
is disabled.</para>
|
|
<screen>
|
|
debug_port = 0
|
|
</screen>
|
|
|
|
<para>Some UAs (SIP clients) will always use the host/ip they
|
|
register TO as host part in the registration record (which
|
|
will be the inbound ip address/hostname of the proxy) and
|
|
can not be told to register a different host (public IP
|
|
address). This Mask feature allows to force such a UA to be
|
|
masqueraded to a different host. Siemens SIP Phones seem to
|
|
need this feature. Normally disabled.</para>
|
|
<screen>
|
|
# mask_host=local.ip.of.sipphone
|
|
# masked_host=public.domaind.org
|
|
</screen>
|
|
|
|
<para>Siproxd itself can be told to send all traffic to another
|
|
outbound proxy. You can use this feature to 'chain' multiple
|
|
siproxd proxies if you have several masquerading firewalls
|
|
to cross. Normally disabled.</para>
|
|
<screen>
|
|
# outbound_proxy_host = my.outboundproxy.org
|
|
# outbound_proxy_port = 5060
|
|
</screen>
|
|
|
|
<para>Outbound proxies can be specified on a per-domain base.
|
|
This allows to use an outbound proxy needed for ProviderA
|
|
and none (or another) for ProviderB. Multiple domain specific
|
|
proxies may be specified, each one with one set of the following
|
|
directives. Note: These directives must always be specified as a
|
|
triple, skipping one of them will affect later definitions.</para>
|
|
<screen>
|
|
#outbound_domain_name = freenet.de
|
|
#outbound_domain_host = proxy.for.domain.freende.de
|
|
#outbound_domain_port = 5060
|
|
</screen>
|
|
|
|
<para>Quick-Dial "Plug-in":
|
|
ability to define quick dial numbers that can be accessed by
|
|
dialing "*nn" from a local phone. 'nn' corresponds to the entry number
|
|
pi_shortdial_entry) below. The '*' character can be chosen freely
|
|
(pi_shortdial_akey).
|
|
Note: To call a real number like "*1234" you would have to dial
|
|
"**1234"</para>
|
|
<screen>
|
|
pi_shortdial_enable = 1
|
|
pi_shortdial_akey = *
|
|
#
|
|
# *01 sipphone echo test
|
|
pi_shortdial_entry = 17474743246
|
|
# *02 sipphone welcome message
|
|
pi_shortdial_entry = 17474745000
|
|
</screen>
|
|
</sect1>
|
|
|
|
<!-- Chapter 3.2: Command Line Options -->
|
|
<sect1 label="3.2">
|
|
<?dbhtml filename="siproxd_guide_c3s2.html">
|
|
<title>Command Line Options</title>
|
|
<para>Siproxd knows the following command line options:</para>
|
|
<screen>
|
|
-h, --help help
|
|
-d, --debug <pattern> set debug-pattern
|
|
-c, --config <cfgfile> use the specified config file
|
|
</screen>
|
|
<para>These options take precedence over the values configured
|
|
in the configuration file.</para>
|
|
</sect1>
|
|
</chapter>
|
|
|
|
<!-- Chapter 4: Features -->
|
|
<chapter label="4" id="Features">
|
|
<?dbhtml filename="siproxd_guide_c4.html">
|
|
<title>Features</title>
|
|
|
|
<!-- Chapter 4.1: Custom Firewall Module -->
|
|
<sect1 label="4.1">
|
|
<?dbhtml filename="siproxd_guide_c4s1.html">
|
|
<title>Custom Firewall Module</title>
|
|
<!--&&&& do be completed -->
|
|
<para>The API</para>
|
|
<para>make your library</para>
|
|
<para>example code</para>
|
|
<screen>
|
|
./configure --with-custom-fwmodule=LIBRARY.a
|
|
</screen>
|
|
</sect1>
|
|
|
|
<!-- Chapter 4.2: Chroot() Jail -->
|
|
<sect1 label="4.2">
|
|
<?dbhtml filename="siproxd_guide_c4s2.html">
|
|
<title>Chroot() Jail</title>
|
|
<!--&&&& do be completed -->
|
|
<para>Create chroot jail</para>
|
|
<para>What files must be present?</para>
|
|
</sect1>
|
|
|
|
<!-- Chapter 4.3: Quick Dial -->
|
|
<sect1 label="4.3">
|
|
<?dbhtml filename="siproxd_guide_c4s3.html">
|
|
<title>Quick Dial</title>
|
|
<!--&&&& do be completed -->
|
|
<para>Since 0.5.12, Siproxd includes a Quick-Dial feature. This
|
|
allows you to define SIP numbers that can be accessed by
|
|
using a shortctu (like "*nn") from any local SIP phone.</para>
|
|
<para>For example, the following lines in your siproxd.conf will
|
|
configure 2 Quick-Dial numbers:</para>
|
|
<screen>
|
|
# *01 sipphone echo test
|
|
pi_shortdial_entry = 17474743246
|
|
# *02 sipphone welcome message
|
|
pi_shortdial_entry = 17474745000
|
|
</screen>
|
|
<para>The numbering starts with "1" ("*01") and every following
|
|
"pi_shortdial_entry" entry will allocate the following position.
|
|
Curently it is not possible to freely assign the positions.</para>
|
|
</sect1>
|
|
</chapter>
|
|
|
|
<!-- Chapter 5: Troubleshooting -->
|
|
<chapter label="5" id="Troubleshooting">
|
|
<?dbhtml filename="siproxd_guide_c5.html">
|
|
<title>Troubleshooting</title>
|
|
|
|
<!-- Chapter 5.1: Problem Reporting -->
|
|
<sect1 label="5.1">
|
|
<?dbhtml filename="siproxd_guide_c5s1.html">
|
|
<title>Problem Reporting</title>
|
|
<para>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
|
|
misbehavior. Also include the exact versions of the siproxd
|
|
package and libosip2 that you are using. You should also
|
|
include your <filename>siproxd.conf</filename>.</para>
|
|
</sect1>
|
|
|
|
<!-- Chapter 5.2: Create a Debug Log -->
|
|
<sect1 label="5.2">
|
|
<?dbhtml filename="siproxd_guide_c5s2.html">
|
|
<title>Create a Debug Log</title>
|
|
<para>The easiest way to generate a debug log is:
|
|
<orderedlist numeration="arabic">
|
|
<listitem><para>make sure siproxd is not started as daemon
|
|
('daemonize = 0' in the config file)</para></listitem>
|
|
<listitem><para>start siproxd:
|
|
<userinput>$ ./siproxd -d -1 2>debug.log</userinput>
|
|
</para></listitem>
|
|
<listitem><para>reproduce the error</para></listitem>
|
|
<listitem><para>include the generated <filename>debug.log
|
|
</filename> in your error report</para></listitem>
|
|
</orderedlist>
|
|
</para>
|
|
<para>Another possibility of to use TCP logging. This method
|
|
is recommended if you run siproxd on a router with limited
|
|
disk space (e.g. an embedded system). To enable TCP logging:
|
|
<orderedlist numeration="arabic">
|
|
<listitem><para>Edit the configuration file and set
|
|
<parameter>debug_port</parameter> to 5050 (or any other
|
|
TCP port number you like).</para></listitem>
|
|
<listitem><para>Restart siproxd</para></listitem>
|
|
<listitem><para><userinput>$ telnet <IP_of_siproxd>
|
|
5050 > debug.log</userinput></para></listitem>
|
|
</orderedlist>
|
|
</para>
|
|
<para>You may prefer to use netcat instead of telnet.
|
|
Note: The TCP debug port is bound to all available interfaces
|
|
on the system, make sure no unauthorized people (like from
|
|
the outbound network) can connect.</para>
|
|
</sect1>
|
|
|
|
<!-- Chapter 5.3: Siproxd crashes -->
|
|
<sect1 label="5.3">
|
|
<?dbhtml filename="siproxd_guide_c5s3.html">
|
|
<title>Siproxd crashes</title>
|
|
<para>If siproxd crashes, a stack back trace usually is
|
|
helpful to me:
|
|
<orderedlist numeration="arabic">
|
|
<listitem><para>start siproxd in the debugger
|
|
(daemonize set to 0):</para>
|
|
<para><userinput>$ gdb ./src/siproxd</userinput></para>
|
|
<para><userinput>(gdb) set args -c /path/to/siproxd.conf
|
|
</userinput></para>
|
|
<para><userinput>(gdb) run</userinput></para>
|
|
</listitem>
|
|
<listitem><para>reproduce the crash</para></listitem>
|
|
|
|
<listitem><para>use gdb to print the stack backtrace:
|
|
<screen>
|
|
(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)
|
|
</screen>
|
|
</para></listitem>
|
|
<listitem><para>copy-paste all the output and include
|
|
it in your problem report.</para></listitem>
|
|
</orderedlist>
|
|
</para>
|
|
</sect1>
|
|
</chapter>
|
|
|
|
<!-- Chapter 6: Sample Configurations -->
|
|
<chapter label="6" id="Sample-Configurations">
|
|
<?dbhtml filename="siproxd_guide_c6.html">
|
|
<title>Sample Configurations</title>
|
|
<para>Check also the FAQ in the siproxd package.</para>
|
|
|
|
<!-- Chapter 6.1: The "Standard Scenario" -->
|
|
<sect1 label="6.1">
|
|
<?dbhtml filename="siproxd_guide_c6s1.html">
|
|
<title>The "Standard Scenario"</title>
|
|
<para>Scenario:</para>
|
|
<screen>
|
|
private IP address range : Internet
|
|
10.0.0.x : (public IP address range)
|
|
:
|
|
: foo.bar.org
|
|
+-------------+ +--------------+
|
|
! !.10 .1 ! masquerading ! publicIP
|
|
! IntHost !---------------! Firewall !------------>>
|
|
! ! ! !
|
|
+-------------+ +--------------+
|
|
eth0 : ppp0
|
|
</screen>
|
|
<para>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
|
|
<literal>sip:johndoe@foo.bar.org</literal>. The softphone is
|
|
configured to register itself at siproxd running on the
|
|
firewall host (10.0.0.1) as <literal>sip:johndoe@foo.bar.org</literal>.
|
|
<literal>Foo.bar.org</literal> is the domain name corresponding
|
|
to the public IP address of the firewall (e.g. use some dynamic
|
|
DNS service like DynDNS).</para>
|
|
<para>Firewall configuration (iptables):</para>
|
|
<screen>
|
|
# allow incoming SIP and RTP traffic
|
|
iptables -A INPUT -m udp -p udp -i ppp0 --dport 5060 -j ACCEPT
|
|
iptables -A INPUT -m udp -p udp -i ppp0 --dport 7070:7089 -j ACCEPT
|
|
</screen>
|
|
<para>Firewall configuration (ipchains):</para>
|
|
<screen>
|
|
# allow incoming SIP and RTP traffic
|
|
ipchains -A input --proto udp --dport 5060 -j ACCEPT
|
|
ipchains -A input --proto udp --dport 7070:7089 -j ACCEPT
|
|
</screen>
|
|
<para>The first line will allow incoming SIP traffic. The
|
|
second line will allow incoming RTP traffic on the ports
|
|
7070 - 7089 (the default port range used by siproxd for
|
|
incoming RTP traffic).</para>
|
|
</sect1>
|
|
|
|
<!-- Chapter 6.2: GS BT-100 behind NAT Router running Siproxd -->
|
|
<sect1 label="6.2">
|
|
<?dbhtml filename="siproxd_guide_c6s2.html">
|
|
<title>GS BT-100 behind NAT Router running Siproxd</title>
|
|
<para>Scenario:</para>
|
|
<screen>
|
|
private IP address range : Internet
|
|
10.0.0.x : (public IP address range)
|
|
:
|
|
: foo.bar.org
|
|
+-------------+ +--------------+
|
|
! !.10 .1 ! masquerading ! publicIP
|
|
! SIP UA !---------------! Firewall !------------>>
|
|
! BT-100 ! ! siproxd !
|
|
+-------------+ +--------------+
|
|
eth0 : ppp0
|
|
</screen>
|
|
<para>Siproxd is running on the same host as the masquerading
|
|
firewall. The SIP phone is a Grandstream BudgeTone-100.
|
|
In this example the external SIP registrar used is
|
|
<ulink url='http://www.sipphone.com/'>sipphone.com</ulink>.</para>
|
|
<para>siproxd.conf:</para>
|
|
<screen>
|
|
if_inbound = eth0
|
|
if_outbound = ppp0
|
|
hosts_allow_reg = 10.0.0.0/24
|
|
sip_listen_port = 5060
|
|
daemonize = 1
|
|
silence_log = 1
|
|
log_calls = 1
|
|
user = siproxd
|
|
registration_file = /var/lib/siproxd_registrations
|
|
pid_file = /var/run/siproxd/siproxd.pid
|
|
rtp_proxy_enable = 1
|
|
rtp_port_low = 7070
|
|
rtp_port_high = 7089
|
|
rtp_timeout = 300
|
|
default_expires = 600
|
|
debug_level = 0
|
|
debug_port = 0
|
|
</screen>
|
|
<para>Firewall configuration (iptables):</para>
|
|
<screen>
|
|
# allow incoming SIP and RTP traffic
|
|
iptables -A INPUT -m udp -p udp -i ppp0 --dport 5060 -j ACCEPT
|
|
iptables -A INPUT -m udp -p udp -i ppp0 --dport 7070:7089 -j ACCEPT
|
|
</screen>
|
|
<para>Phone configuration (only the relevant items are listed):</para>
|
|
<screen>
|
|
IP Address: 10.0.0.10
|
|
Subnet Mask: 255.255.255.0
|
|
Default Router: 10.0.0.1
|
|
DNS Server 1: <DNS Server of your Internet provider>
|
|
SIP Server: proxy01.sipphone.com
|
|
Outbound Proxy: 10.0.0.1
|
|
SIP User ID: 1747669xxxx
|
|
Authenticate ID: 1747660xxxx
|
|
Authenticate Passwd: *********
|
|
Name: Your Name Here
|
|
Use DNS SRV: no
|
|
User ID is phone #: no
|
|
Sip Registration: yes
|
|
Unregister on reboot:no
|
|
Register expiration: 60
|
|
Early Dial: no
|
|
local SIP port: 5060
|
|
local RTP port: 5004
|
|
Use random port: yes
|
|
NAT traversal: no
|
|
Use NAT IP: <empty>
|
|
Subscribe for MWI: No
|
|
Send DTMF: via RTP (RFC2833)
|
|
</screen>
|
|
</sect1>
|
|
|
|
<!-- Chapter 6.3: GS BT-100 with Siproxd running "in front of" a NAT router -->
|
|
<sect1 label="6.3">
|
|
<?dbhtml filename="siproxd_guide_c6s3.html">
|
|
<title>GS BT-100 with Siproxd running "in front of" a NAT router</title>
|
|
<para>Scenario:</para>
|
|
<screen>
|
|
private IP address range : Internet
|
|
10.0.0.x : (public IP address range)
|
|
:
|
|
: foo.bar.org
|
|
+-------------+ +--------------+
|
|
! !.10 .1 ! masquerading ! publicIP
|
|
! SIP UA !---------------! NAT router !------------>>
|
|
! BT-100 ! ! ! !
|
|
+-------------+ ! +--------------+
|
|
! eth0 : ppp0
|
|
! :
|
|
! :
|
|
eth0 !.2
|
|
+-------------+
|
|
! siproxd !
|
|
! !
|
|
+-------------+
|
|
</screen>
|
|
<para>Siproxd is running on 10.0.0.2. The masquerading NAT
|
|
router (e.g. a ADSL NAT router that cannot run any user
|
|
applications).</para>
|
|
<para>siproxd.conf:</para>
|
|
<screen>
|
|
if_inbound = eth0
|
|
if_outbound = eth0
|
|
host_outbound = foo.bar.org
|
|
hosts_allow_reg = 10.0.0.0/24
|
|
sip_listen_port = 5060
|
|
daemonize = 1
|
|
silence_log = 1
|
|
log_calls = 1
|
|
user = siproxd
|
|
registration_file = /var/lib/siproxd_registrations
|
|
pid_file = /var/run/siproxd/siproxd.pid
|
|
rtp_proxy_enable = 1
|
|
rtp_port_low = 7070
|
|
rtp_port_high = 7089
|
|
rtp_timeout = 300
|
|
default_expires = 600
|
|
debug_level = 0
|
|
debug_port = 0
|
|
</screen>
|
|
<para>NAT router configuration:</para>
|
|
<screen>
|
|
forward all incoming traffic on 5060/udp to 10.0.0.2
|
|
forward all incoming traffic from 7070/udp - 7089/udp to 10.0.0.2
|
|
</screen>
|
|
<para>Phone configuration:</para>
|
|
<screen>
|
|
IP Address: 10.0.0.10
|
|
Subnet Mask: 255.255.255.0
|
|
Default Router: 10.0.0.1
|
|
DNS Server 1: <DNS Server of your Internet provider>
|
|
SIP Server: proxy01.sipphone.com
|
|
Outbound Proxy: 10.0.0.2
|
|
SIP User ID: 1747669xxxx
|
|
Authenticate ID: 1747660xxxx
|
|
Authenticate Passwd: *********
|
|
Name: Your Name Here
|
|
Use DNS SRV: no
|
|
User ID is phone #: no
|
|
Sip Registration: yes
|
|
Unregister on reboot:no
|
|
Register expiration: 60
|
|
Early Dial: no
|
|
local SIP port: 5060
|
|
local RTP port: 5004
|
|
Use random port: yes
|
|
NAT traversal: no
|
|
Use NAT IP: <empty>
|
|
Subscribe for MWI: No
|
|
Send DTMF: via RTP (RFC2833)
|
|
</screen>
|
|
</sect1>
|
|
|
|
|
|
<!-- Chapter 6.4: Transparent SIP Proxy -->
|
|
<sect1 label="6.4">
|
|
<?dbhtml filename="siproxd_guide_c6s4.html">
|
|
<title>Transparent SIP Proxy</title>
|
|
<para>Scenario:</para>
|
|
<screen>
|
|
private IP address range : Internet
|
|
10.0.0.x : (public IP address range)
|
|
:
|
|
: foo.bar.org
|
|
+-------------+ +--------------+
|
|
! !.10 .1 ! masquerading ! publicIP
|
|
! SIP UA !---------------! Firewall !------------>>
|
|
! ! ! siproxd !
|
|
+-------------+ +--------------+
|
|
eth0 : ppp0
|
|
</screen>
|
|
<para>You may have a SIP UA (Phone) that does not allow the
|
|
specification of an outbound proxy. If siproxd is running
|
|
on the masquerading router, the following configuration will
|
|
do so called transparent proxying. The firewall will redirect
|
|
outgoing SIP messages to siproxd, however the local Client
|
|
is not aware of it.</para>
|
|
<para>siproxd.conf:</para>
|
|
<screen>
|
|
if_inbound = eth0
|
|
if_outbound = ppp0
|
|
hosts_allow_reg = 10.0.0.0/24
|
|
sip_listen_port = 5060
|
|
daemonize = 1
|
|
silence_log = 1
|
|
log_calls = 1
|
|
user = siproxd
|
|
registration_file = /var/lib/siproxd_registrations
|
|
pid_file = /var/run/siproxd/siproxd.pid
|
|
rtp_proxy_enable = 1
|
|
rtp_port_low = 7010
|
|
rtp_port_high = 7019
|
|
rtp_timeout = 300
|
|
default_expires = 600
|
|
debug_level = 0
|
|
debug_port = 0
|
|
</screen>
|
|
<para>Firewall configuration (iptables):</para>
|
|
<screen>
|
|
# redirect outgoing SIP traffic to siproxd (myself)
|
|
iptables -t nat -A PREROUTING -m udp -p udp -i eth0 \
|
|
--destination-port 5060 -j REDIRECT
|
|
# allow incoming SIP and RTP traffic
|
|
iptables -A INPUT -m udp -p udp -i ppp0 --dport 5060 -j ACCEPT
|
|
iptables -A INPUT -m udp -p udp -i ppp0 --dport 7070:7089 -j ACCEPT
|
|
</screen>
|
|
</sect1>
|
|
|
|
<!-- Chapter 6.5: Masquerading an Asterisk box -->
|
|
<sect1 label="6.5">
|
|
<?dbhtml filename="siproxd_guide_c6s5.html">
|
|
<title>Masquerading an Asterisk box</title>
|
|
<para>Scenario:</para>
|
|
<screen>
|
|
private IP address range : Internet
|
|
10.0.0.x : (public IP address range)
|
|
:
|
|
: foo.bar.org
|
|
+-------------+ +--------------+
|
|
! !.10 .1 ! masquerading ! publicIP
|
|
! Asterisk !---------------! Firewall !------------>>
|
|
! ! SIP trunk ! siproxd !
|
|
+-------------+ +--------------+
|
|
! ! ! ! ! eth0 : ppp0
|
|
..!.!.!.!.!.....
|
|
extensions
|
|
(local SIP clients)
|
|
</screen>
|
|
<para>Siproxd can also be used to masquerade an Asterisk server.
|
|
The Asterisk server will register itself as a SIP UA (Client)
|
|
to an external SIP registrar. In this example this would be
|
|
again sipphone.com. As Asterisk does not allow to specify an
|
|
SIP outbound proxy we use the same setup for transparent proxying.
|
|
The context values of the asterisk configuration probably must
|
|
be adapted to fit your needs.</para>
|
|
<para>siproxd.conf:</para>
|
|
<screen>
|
|
if_inbound = eth0
|
|
if_outbound = ppp0
|
|
hosts_allow_reg = 10.0.0.0/24
|
|
sip_listen_port = 5060
|
|
daemonize = 1
|
|
silence_log = 1
|
|
log_calls = 1
|
|
user = siproxd
|
|
registration_file = /var/lib/siproxd_registrations
|
|
pid_file = /var/run/siproxd/siproxd.pid
|
|
rtp_proxy_enable = 1
|
|
rtp_port_low = 7070
|
|
rtp_port_high = 7089
|
|
rtp_timeout = 300
|
|
default_expires = 600
|
|
debug_level = 0
|
|
debug_port = 0
|
|
</screen>
|
|
<para>Firewall configuration (iptables):</para>
|
|
<screen>
|
|
# redirect outgoing SIP traffic to siproxd (myself)
|
|
iptables -t nat -A PREROUTING -m udp -p udp -i eth0 \
|
|
--source 10.0.0.11 --destination-port 5060 -j REDIRECT
|
|
# allow incoming SIP and RTP traffic
|
|
iptables -A INPUT -m udp -p udp -i ppp0 --dport 5060 -j ACCEPT
|
|
iptables -A INPUT -m udp -p udp -i ppp0 --dport 7070:7080 -j ACCEPT
|
|
</screen>
|
|
<para>Asterisk configuration (SIP related part):</para>
|
|
<para>Note: Very important are the fromuser and fromdomain
|
|
keywords in the client section. They are required to have
|
|
Asterisk send the correct From headers in SIP dialogs.
|
|
The used Asterisk version is 'SVN-branch-1.4-r62331M'.</para>
|
|
<para>With newer Asterisk versions, it is no longer required
|
|
to have a separate REGISTER definition, this can be made
|
|
implicit in the SIP trunk config.</para>
|
|
<screen>
|
|
; sip.conf:
|
|
|
|
[general]
|
|
port = 5060 ; Port to bind to (SIP is 5060)
|
|
bindaddr = 0.0.0.0 ; Address to bind to (all addresses on machine)
|
|
context = from-sip-external ; Send unknown SIP callers to this context
|
|
|
|
useragent = PBX ; NOTE: some providers (e.g sipcall.ch) do simply
|
|
; not work with the default "AsteriskPBX"
|
|
; UA String.
|
|
|
|
; Network Settings
|
|
nat=never
|
|
localnet = 10.0.0.0/24
|
|
domain = 10.0.0.10
|
|
|
|
; Codecs
|
|
disallow=all
|
|
allow=gsm ; 13 Kbps
|
|
allow=ulaw ; 64 Kbps
|
|
allow=alaw ; 64 Kbps
|
|
autoframing = yes
|
|
|
|
; SIP Settings
|
|
canreinvite = no ; important!
|
|
|
|
; the following are just my settings I use, however
|
|
; I dont' consider them critical
|
|
allowexternaldomains = yes
|
|
allowexternalinvites = yes
|
|
allowguest = yes
|
|
allowsubscribe = no
|
|
allowtransfer = yes
|
|
alwaysauthreject = no
|
|
autodomain = yes
|
|
callevents = no
|
|
compactheaders = no
|
|
dumphistory = no
|
|
g726nonstandard = no
|
|
ignoreregexpire = no
|
|
jbenable = no
|
|
jbforce = no
|
|
jblog = no
|
|
maxcallbitrate = 384
|
|
maxexpiry = 3600
|
|
minexpiry = 180
|
|
notifyringing = no
|
|
pedantic = no
|
|
promiscredir = no
|
|
recordhistory = no
|
|
relaxdtmf = no
|
|
rtcachefriends = no
|
|
rtsavesysname = no
|
|
rtupdate = no
|
|
sendrpid = yes
|
|
sipdebug = no
|
|
t1min = 100
|
|
progressinband = no
|
|
;register =
|
|
t38pt_udptl = no
|
|
trustrpid = no
|
|
usereqphone = no
|
|
videosupport = no
|
|
</screen>
|
|
<para>The Trunk definition looks like:</para>
|
|
<screen>
|
|
; users.conf:
|
|
|
|
[general]
|
|
;
|
|
; Full name of a user
|
|
;
|
|
fullname = New User
|
|
userbase = 200
|
|
;
|
|
; Create voicemail mailbox and use use macro-stdexten
|
|
;
|
|
hasvoicemail = yes
|
|
;
|
|
; Set voicemail mailbox 6000 password to 1234
|
|
;
|
|
vmsecret = 1234
|
|
;
|
|
; Create SIP Peer
|
|
;
|
|
hassip = yes
|
|
hasiax = no
|
|
;
|
|
; Create H.323 friend
|
|
;
|
|
;hash323 = yes
|
|
;
|
|
; Create manager entry
|
|
;
|
|
hasmanager = no
|
|
;
|
|
; Remaining options are not specific to users.conf entries but are general.
|
|
;
|
|
callwaiting = yes
|
|
threewaycalling = yes
|
|
callwaitingcallerid = yes
|
|
transfer = yes
|
|
canpark = yes
|
|
cancallforward = yes
|
|
callreturn = yes
|
|
callgroup = 1
|
|
pickupgroup = 1
|
|
host = dynamic
|
|
localextenlength = 3
|
|
allow_aliasextns = no
|
|
allow_an_extns = no
|
|
hasagent = no
|
|
hasdirectory = no
|
|
|
|
|
|
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
|
|
; Local SIP UAs
|
|
; = locally connected phones. nothing special here.
|
|
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
|
|
[201]
|
|
callwaiting = yes
|
|
cid_number = 201
|
|
context = local_sip
|
|
email = e@mail
|
|
fullname = Full Name
|
|
group =
|
|
hasagent = yes
|
|
hasdirectory = yes
|
|
hasiax = no
|
|
hasmanager = no
|
|
hassip = yes
|
|
hasvoicemail = yes
|
|
host = dynamic
|
|
mailbox = 201
|
|
secret = sip_password
|
|
threewaycalling = yes
|
|
zapchan =
|
|
registeriax = no
|
|
registersip = yes
|
|
vmsecret = 1234
|
|
|
|
|
|
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
|
|
; SIP Trunks
|
|
; these are masqueraded via siproxd
|
|
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
|
|
[trunk_1]
|
|
disallow = all
|
|
allow = gsm,ulaw,alaw,adpcm,speex,g729,g723
|
|
callerid =
|
|
contact = 17476691234 ; IMPORTANT
|
|
context = DID_trunk_1
|
|
dialformat = ${EXTEN:1}
|
|
fromdomain = proxy01.sipphone.com
|
|
fromuser = 17476691234 ; IMPORTANT
|
|
group =
|
|
hasexten = no
|
|
hasiax = no
|
|
hassip = yes
|
|
host = proxy01.sipphone.com
|
|
insecure = very
|
|
port = 5060
|
|
provider =
|
|
registeriax = no
|
|
registersip = yes
|
|
secret = sip_password
|
|
trunkname = Custom - sipphone1234
|
|
trunkstyle = customvoip
|
|
username = 17476691234
|
|
</screen>
|
|
</sect1>
|
|
</chapter>
|
|
</book>
|