siproxd_guide.sgml

这是一个C程序

</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 &lt;pattern>           set debug-pattern
-c, --config &lt;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 &lt;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 &lt;main>, argc=3, 
    argv=0xbffffc54, init=0x8049a08 &lt;_init>, fini=0x804edac &lt;_fini>, 
    rtld_fini=0x4000a350 &lt;_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:[e-mail]</literal>. The softphone is
        configured to register itself at siproxd running on the
        firewall host (10.0.0.1) as <literal>sip:[e-mail]</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:           &lt;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:             &lt;empty>
Subscribe for MWI:      No
Send DTMF:              via RTP (RFC2833)