siproxd_guide.sgml

这是一个C程序

<!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>[e-mail]</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>[e-mail]</authorinitials>
        <revremark>Initial version</revremark>
      </revision>
      <revision>
        <revnumber>0.2</revnumber>
        <date>2006-07-28</date>
        <authorinitials>[e-mail]</authorinitials>
        <revremark>Comment on Asterisk Scenario</revremark>
      </revision>
      <revision>
        <revnumber>0.3</revnumber>
        <date>2007-05-15</date>
        <authorinitials>[e-mail]</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:[e-mail]</para></listitem>

        <listitem><para>The softphone is configured to register itself at
          siproxd running on the firewall host (10.0.0.1) as
          sip:[e-mail]</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=&lt;myprefix></userinput> when running 
        <userinput>./configure</userinput>. If you have installed
        libosip2 in an non-standard location use
        <userinput>--with-libosip-prefix=&lt;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>&lt;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 = &lt;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 &lt;IP>/&lt;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