- Improved documentation system

- documentation makefiles
- XML-based dialect of docbook used

doc/ser_radius/Makefile

@@ -0,0 +1,29 @@
+#
+# The list of documents to build (without extensions)
+#
+DOCUMENTS = ser_radius
+
+#
+# The root directory containing Makefile.doc
+#
+ROOT_DIR=../..
+
+#
+# Validate docbook documents before generating output
+# (may be slow)
+#
+#VALIDATE=1
+
+#
+# You can override the stylesheet used to generate
+# xhtml documents here
+#
+#XHTML_XSL=$(ROOT_DIR)/doc/stylesheets/xhtml.xsl
+
+#
+# You can override the stylesheet used to generate
+# plain text documents here
+#
+#TXT_XSL=$(XHTML_XSL)
+
+include $(ROOT_DIR)/Makefile.doc

doc/ser_radius/ser_radius.sgml

@@ -1,593 +0,0 @@
-<!-- $Id$ -->
-<!DOCTYPE Book PUBLIC "-//OASIS//DTD DocBook V4.2//EN" [
-
-<!ENTITY ser "<acronym>SIP</acronym> Express Router">
-<!ENTITY nat "<acronym>NAT</acronym>">
-<!ENTITY ip "<acronym>IP</acronym>">
-<!ENTITY rtp "<acronym>RTP</acronym>">
-<!ENTITY stun "<acronym>STUN</acronym>">
-<!ENTITY fokus "FhG FOKUS">
-<!ENTITY sip "<acronym>SIP</acronym>">
-<!ENTITY rad "RADIUS">
-<!ENTITY pstn "<acronym>PSTN</acronym>">
-
-]>
-
-<book>
-    <bookinfo>
-	<title>&ser &rad; HOWTO</title>
-	<authorgroup>
-	    <author>
-		<firstname>Jan</firstname>
-		<surname>Janak</surname>
-		<email>[email protected]</email>
-	    </author>
-	</authorgroup>
-	<copyright>
-	    <year>2003</year>
-	    <holder>&fokus;</holder>
-	</copyright>
-	<revhistory>
-	    <revision>
-		<revnumber>$Revision$</revnumber>
-		<date>$Date$</date>
-	    </revision>
-	</revhistory>
-    </bookinfo>
-
-    <chapter>
-	<title>Introduction</title>
-	<simpara>
-	    &ser can be configured to use &rad; server for authentication, accounting, and group
-	    membership checking. Since configuration of &rad; seems to be a common source of
-	    problems, we decided to put together this HOWTO.
-	</simpara>
-	<simpara>
-	    The HOWTO covers installation and configuration of FreeRADIUS server only. There are
-	    also other &rad; servers available and as long as they support digest authentication,
-	    they should work too. Any volunteers willing to describe setup of other &rad; servers
-	    are encouraged to contact the author.
-	</simpara>
-	<section>
-	    <title>Prerequisites</title>
-	    <simpara>
-		To setup &rad; support in &ser; you will need the following:
-	    </simpara>
-	    <itemizedlist>
-		<listitem>
-		    <simpara>
-			FreeRADIUS server, you can get it from <ulink
-			    url="http://www.freeradius.org">FreeRADIUS website</ulink>. The HOWTO
-			    describes installation and setup of release 0.9.1.
-		    </simpara>
-		</listitem>
-		<listitem>
-		    <simpara>
-			Radiusclient library. In version 0.8.14 we started to use the new version of
-			radiusclient library developed by Maxim Sobolev called radiusclient-ng. The 
-			homepage of the library is <ulink
-			    url="http://developer.berlios.de/projects/radiusclient-ng/">http://developer.berlios.de/projects/radiusclient-ng/</ulink>
-		    </simpara>
-		</listitem>
-		<listitem>
-		    <simpara>
-			&ser;, get it from <ulink url="http://iptel.org/ser">http://iptel.org/ser</ulink>
-		    </simpara>
-		</listitem>
-		<listitem>
-		    <simpara>
-			You should also have some experience in configuring &ser;. Before you enable
-			&rad; authentication or accounting make sure that the basic server is
-			running and that you know how to customize it to your taste.
-		    </simpara>
-		</listitem>
-		<listitem>
-		    <simpara>
-			If you want to use &rad; accounting then you will have to compile &ser; from
-			sources so you should know how to do it.
-		    </simpara>
-		</listitem>
-	    </itemizedlist>
-	    <simpara>
-		Various unix/linux distributions might include binary packages of the mentioned
-		applications. In that case you can safely use the packages, there shouldn't be any
-		problem. Location of some files may be different, though. We will describe
-		how to install the software from sources only.
-	    </simpara>
-	    <warning>
-		<simpara>
-		    Configuration of FreeRADIUS server described in the document is in no way
-		    exhaustive. This document is a sort of quick-start-guide, it shows how to get
-		    things running, but you should definitely read FreeRADIUS documentation
-		    and configure the server properly ! You have been warned.
-		</simpara>
-	    </warning>
-	</section>
-    </chapter>
-    <chapter>
-	<title>Radiusclient Library</title>
-	<simpara>
-	    Untar the source tarball.
-	</simpara>
-	<screen format="linespecific">
-root@localhost:/usr/local/src# tar xvfz radiusclient-0.4.3.tar.gz
-</screen>
-	    <simpara>
-		Compile and install the library.
-	    </simpara>
-	    <screen format="linespecific">
-root@localhost:/usr/local/src# cd radiusclient-0.3.2
-root@localhost:/usr/local/src/radiusclient-0.3.2# ./configure
-root@localhost:/usr/local/src/radiusclient-0.3.2# make
-root@localhost:/usr/local/src/radiusclient-0.3.2# make install
-</screen>
-	<simpara>
-	    By default all the configuration files of the radiusclient library will be in
-	    <filename moreinfo="none">/usr/local/etc/radiusclient</filename> directory.
-	</simpara>
-	<simpara>
-	    If you use binary packages then the configuration files will be probably in <filename
-	    moreinfo="none">/etc/radiusclient</filename>.
-	</simpara>
-	<section>
-	    <title>File <filename moreinfo="none">radiusclient.conf</filename></title>
-	    <simpara>
-		The main configuration file of the library is <filename
-		    moreinfo="none">/usr/local/etc/radiusclient/radiusclient.conf</filename>, open
-		    the file in your favorite text editor and find lines containing the following:
-	    </simpara>
-	    <programlisting format="linespecific">
-authserver      localhost
-</programlisting>
-	    <simpara>
-		This is the hostname or &ip; address of the RADIUS server used for authentication. You
-		will have to change this unless the server is running on the same host as your &sip;
-		proxy.
-	    </simpara>
-	    <programlisting format="linespecific">
-acctserver      localhost
-</programlisting>
-	    <simpara>
-		This is the hostname or &ip; address of the RADIUS server used for accounting. You
-		will have to change this unless the server is running on the same host as your &sip
-		proxy.
-	    </simpara>
-	</section>
-	<section>
-	    <title>File <filename moreinfo="none">servers</filename></title>
-	    <simpara>
-		&rad; protocol uses simple access control mechanism based on shared secrets
-		that allows &rad; servers to limit access from &rad; clients. A &rad; server is
-		configured with a secret string and only &rad; clients that have the same
-		secret will be accepted.
-	    </simpara>
-	    <simpara>
-		You need to configure a shared secret for each server you have configured in
-		    <filename moreinfo="none">radiusclient.conf</filename> file in the previous
-		    step. The shared secrets are stored in <filename
-		    moreinfo="none">/usr/local/etc/radiusclient/servers</filename> file.
-	    </simpara>
-	    <simpara>
-		Each line contains hostname of a &rad; server and shared secret used in
-		communication with that server. The two values are separated by
-		whitespaces. Configure shared secrets for every &rad; server you are going to use.
-	    </simpara>
-	    <warning>
-		<simpara>
-		    &rad; servers and clients must be configured with the same shared secret,
-		    otherwise they will not accept RADIUS messages from each other and neither
-		    authentication nor accounting will work !
-		</simpara>
-	    </warning>
-	</section>
-	<section>
-	    <title>File <filename moreinfo="none">dictionary</filename></title>
-	    <simpara>
-		Radiusclient library contains file called <filename
-		moreinfo="none">dictionary.ser</filename>. That file includes all the attributes
-		that are needed by &ser;. Include the file in the main <filename
-		moreinfo="none">dictionary</filename> file. To include the file, put the following
-		line at the end of <filename moreinfo="none">dictionary</filename> file:
-	    </simpara>
-	    <screen format="linespecific">
-$INCLUDE /usr/local/etc/radiuclient/dictionary.ser
-</screen>
-	</section>
-    </chapter>
-
-    <chapter>
-	<title>FreeRADIUS Server</title>
-	<simpara>
-	    Untar, configure, build, and install the server:
-	</simpara>
-	    <screen format="linespecific">
-root@localhost:/usr/local/src# tar xvfz freeradius-0.9.1.tar.gz
-root@localhost:/usr/local/src# cd freeradius-0.9.1
-root@localhost"/usr/local/src/freeradius-0.9.1# ./configure
-root@localhost"/usr/local/src/freeradius-0.9.1# make
-root@localhost"/usr/local/src/freeradius-0.9.1# make install
-</screen>
-	<simpara>
-	    All the configuration files of FreeRADIUS server will be in <filename
-	    moreinfo="none">/usr/local/etc/raddb</filename> directory. If you install a binary
-	    package then you will probably find them in <filename moreinfo="none">/etc/raddb</filename>.
-	</simpara>
-	<simpara>
-	    The following sections describe how to configure freeradius server. First we describe
-	    the common configuration that must be done in any case. Configuration specific for
-	    authentication, accounting, and group membership checking will be described in separate
-	    sections.
-	</simpara>
-	
-	<section>
-	    <title>Common configuration</title>
-	    <section>
-		<title>File <filename moreinfo="none">clients.conf</filename></title>
-		<simpara>
-		    File <filename moreinfo="none">/usr/local/etc/raddb/clients.conf</filename>
-		    contains description of &rad; clients that are allowed to use the server. For
-		    each of the clients you need to specify it's hostname or &ip address and also a
-		    shared secret. The shared secret must be the same string you configured in
-		    radiusclient library.
-		</simpara>
-		<simpara>
-		    Suppose that your &sip; server is running on host proxy.foo.bar and
-		    radiusclient library on that machine has been configure with
-		    <quote>foobarsecret</quote> as the shared secret. You need to put the
-		    following section into the file:
-		</simpara>
-		<programlisting format="linespecific">
-client proxy.foo.bar {
-    secret = foobarsecret
-    shortname = foo
-}
-</programlisting>
-		<simpara>
-		    This fragment allows access from &rad; clients on proxy.foo.bar if they use
-		    <quote>foobarsecret</quote> as the shared secret.
-		</simpara>
-		<note>
-		    <simpara>
-			The file already contains an entry for localhost (127.0.0.1), so if you are
-			running the &rad; server on the same host as your &sip; server, then modify
-			the existing entry instead. By default it contains shared secret
-			<quote>testing123</quote>.
-		    </simpara>
-		</note>
-	    </section>
-	    
-	    <section>
-		<title>File <filename moreinfo="none">dictionary</filename></title>
-		<simpara>
-		    File <filename moreinfo="none">/usr/local/etc/raddb/dictionary</filename>
-		    contains the dictionary of FreeRADIUS server. You have to add the same
-		    dictionary file (<filename moreinfo="none">dictionary.ser</filename>), which you
-		    added to the dictionary of radiusclient library, also here. In this case you
-		    don't have to append the contents of the file, you can include it into the main
-		    file.  Add the following line at the end of <filename
-		    moreinfo="none">/usr/local/etc/raddb/dictionary</filename>:
-		</simpara>
-		<programlisting format="linespecific">
-$INCLUDE /usr/local/etc/radiusclient/dictionary.ser
-</programlisting>
-		<simpara>
-		    That will include the same attribute definitions that are used in radiusclient
-		    library so the client and server will understand each other.
-		</simpara>
-	    </section>
-
-	    <section>
-		<title>File <filename moreinfo="none">radiusd.conf</filename></title>
-		<simpara>
-		    Digest authentication is disabled by default and you must enable it in this
-		    file. There are two sections, <quote>authorize</quote> and
-		    <quote>authenticate</quote>. Both sections contain line containing word
-		    <quote>digest</quote>. Both of them are commented and you must un-comment them
-		    to enable digest authentication.
-		</simpara>
-		<note>
-		    <simpara>
-			There is also another line containing word <quote>digest</quote> followed by
-			curly braces and it is enabled by default. The section is supposed to
-			contain digest module parameters but because digest module has no parameters,
-			it is empty. This is not the line you are supposed to uncomment ! There are
-			two more.
-		    </simpara>
-		</note>
-	    </section>
-	    
-	    <section>
-		<title>File <filename moreinfo="none">users</filename></title>
-		<simpara>
-		    This file contains authentication information for each user. For testing
-		    purposes we will create user <quote>test</quote>. Put the following into the file:
-		</simpara>
-		    <programlisting format="linespecific">
-test Auth-Type := Digest, User-Password == "test"
-     Reply-Message = "Hello, test with digest"
-</programlisting>
-
-		<simpara>
-		    The username and password is for testing only, you can safely remove the entry
-		    once your RADIUS server works and you are able to authenticate.
-		</simpara>
-	    </section>
-	</section>
-
-	<section>
-	    <title>Test The Server</title>
-	    <note>
-		<simpara>
-		    This step is optional.
-		</simpara>
-	    </note>
-	    <simpara>
-		The basic configuration of FreeRADIUS server is done it now we are going to test if
-		it really works. Start the server with parameter -X. That will cause the server to
-		stay in the foreground (it will not turn into daemon) and produce a lot of debugging
-		information on the standard output:
-	    </simpara>
-	    <screen format="linespecific">
-root@/usr/local/src# radiusd -X
-</screen>
-	    <simpara>
-		Create file <filename moreinfo="none">digest</filename> and put the following
-		into the file:
-	    </simpara>
-		<programlisting format="linespecific">
-User-Name = "test", Digest-Response = "631d6d73147add2f9e437f59bbc3aeb7", 
-Digest-Realm = "testrealm", Digest-Nonce = "1234abcd" , 
-Digest-Method = "INVITE", Digest-URI = "sip:[email protected]", 
-Digest-Algorithm = "MD5", Digest-User-Name = "test"
-</programlisting>
-	    <simpara>
-		All the attributes must be on a single line.
-	    </simpara>
-	    <simpara>
-		Run <command moreinfo="none">radclient</command> to test the server:
-	    </simpara>
-	    <screen format="linespecific">
-root@/usr/local/src# radclient -f digest localhost auth &lt;shared_secret&gt;
-</screen>
-	    <note>
-		<simpara>
-		    I suppose that you run the test utility directly on the &rad; server since
-		    it comes with the FreeRADIUS server package. That also means that you have
-		    to enable access from localhost in your <filename
-		    moreinfo="none">clients.conf</filename> file. Don't forget to
-		    replace &lt;shared_secret&gt; with the shared secret configured for locahost
-		    clients in <filename moreinfo="none">clients.conf</filename>.
-		</simpara>
-	    </note>
-	    <simpara>
-		If your server works properly then you should see the following response:
-	    </simpara>
-	    <screen format="linespecific">
-Received response ID 224, code 2, length = 45
-        Reply-Message = "Hello, test with digest"
-</screen>
-	</section>
-	
-	<section>
-	    <title>Authentication Configuration</title>
-	    <simpara>
-		To create user <quote>joe</quote> in domain <quote>iptel.org</quote> with password
-		<quote>heslo</quote> put the following into file <filename
-		moreinfo="none">/usr/local/etc/raddb/users</filename>:
-	    </simpara>
-	    <programlisting format="linespecific">
[email protected] Auth-Type := Digest, User-Password == "heslo"
-     Reply-Message = "Authenticated",
-     Sip-Rpid = "1234"
-</programlisting>
-	    <simpara>
-		Attribute <quote>Sip-Rpid</quote> is optional. The attribute contains a phone number
-		associated to the user. &ser; can be configured to put the phone number into
-		Remote-Party-ID header field of the &sip; message. The header field can be then used
-		by &pstn; gateways to display the number as the number of the caller on regular
-		phones. You can omit the attribute if you don't need it.
-	    </simpara>
-	</section>
-	
-	<section>
-	    <title>Accounting Configuration</title>
-	    <simpara>
-		By default FreeRADIUS server will log all accounting requests into <filename
-		    moreinfo="none">/usr/local/var/log/radius/radacct</filename> directory in form
-		    of plain text files. The server will create one file for each hostname in the
-		    directory. The following example shows how the log files look like.
-	    </simpara>
-	    <example>
-		<title>Example of Accounting Report</title>
-		<programlisting format="linespecific">
-Tue Jun 24 00:20:55 2003
-        Acct-Status-Type = Start
-        Service-Type = 15
-        Sip-Response-Code = 200
-        Sip-Method = 1
-        User-Name = "[email protected]"
-        Calling-Station-Id = "sip:[email protected]"
-        Called-Station-Id = "sip:[email protected]"
-        Sip-Translated-Request-URI = "sip:[email protected]"
-        Acct-Session-Id = "[email protected]"
-        Sip-To-Tag = "cb2cfe2e-3659-28c7-a8cc-ab0b8cbd3012"
-        Sip-From-Tag = "a783bd2f-bb8d-46fd-84a9-00a9833f189e"
-        Sip-CSeq = "1"
-        NAS-IP-Address = 192.168.2.16
-        NAS-Port = 5060
-        Acct-Delay-Time = 0
-        Client-IP-Address = 127.0.0.1
-        Acct-Unique-Session-Id = "9b323e6b2f5b0f33"
-        Timestamp = 1056406855
-
-Tue Jun 24 00:20:56 2003
-        Acct-Status-Type = Stop
-        Service-Type = 15
-        Sip-Response-Code = 200
-        Sip-Method = 8
-        User-Name = "[email protected]"
-        Calling-Station-Id = "sip:[email protected]"
-        Called-Station-Id = "sip:[email protected]"
-        Sip-Translated-Request-URI = "sip:192.168.2.32:9576"
-        Acct-Session-Id = "[email protected]"
-        Sip-To-Tag = "a783bd2f-bb8d-46fd-84a9-00a9833f189e"
-        Sip-From-Tag = "cb2cfe2e-3659-28c7-a8cc-ab0b8cbd3012"
-        Sip-CSeq = "4580"
-        NAS-IP-Address = 192.168.2.16
-        NAS-Port = 5060
-        Acct-Delay-Time = 0
-        Client-IP-Address = 127.0.0.1
-        Acct-Unique-Session-Id = "b2c2479a07b17c95"
-        Timestamp = 1056406856
-</programlisting>
-	    </example>
-	</section>
-	<section>
-	    <title>Group Checking Configuration</title>
-	    <simpara>
-		If you want to make user <quote>joe</quote> in domain <quote>iptel.org</quote>
-		member of group <quote>pstn</quote> then add the following to your <filename
-		moreinfo="none">/usr/local/etc/raddb/users</filename> file:
-	    </simpara>
-	    <programlisting format="linespecific">
[email protected] Sip-Group == "pstn", Auth-Type := Accept
-        Reply-Message = "Authorized"
-</programlisting>
-	</section>
-    </chapter>
-    <chapter>
-	<title>&ser; Configuration</title>
-	<simpara>
-	    We will describe installation from sources here. If you use binary packages then there
-	    is an additional package containing &rad; related modules. You will need to install the
-	    package.
-	</simpara>
-	<warning>
-	    <simpara>
-		Due to a mistake the binary packages for &rad; do not include &rad;-enabled
-		version of acc (accounting) module. The packages contain modules for &rad;
-		authentication and group membership checking only.
-	    </simpara>
-	    <simpara>
-		If you need accounting over &rad; then you will have to compile &rad;-enabled
-		version of acc module from the sources. This will be fixed in one of future
-		releases, we apologize for any inconvenience.
-	    </simpara>
-	</warning>
-	<simpara>
-	    &rad;-related modules are not compiled by default. To compile them, edit <filename
-		moreinfo="none">Makefile</filename>, find variable
-	    <varname>exclude_modules</varname> and you should see <quote>auth_radius</quote>,
-	    <quote>group_radius</quote>, and <quote>uri_radius</quote> among excluded
-	    modules. Simply remove the three modules from the list.
-	</simpara>
-	<simpara>
-	    If you need &rad; accounting then edit also sip_router/modules/acc/Makefile and
-	    uncomment lines containing:
-	</simpara>
-	    <programlisting format="linespecific">
-DEFS+=-DRAD_ACC
-LIBS=-L$(LOCALBASE)/lib -lradiusclient
-</programlisting>
-	<simpara>
-	    Then recompile and re-install &ser:
-	</simpara>
-	    <screen format="linespecific">
-root@localhost:/usr/local/src/sip_router# make proper
-root@localhost:/usr/local/src/sip_router# make all
-root@localhost:/usr/local/src/sip_router# make install
-</screen>
-	<section>
-	    <title>Authentication Configuration</title>
-	    <simpara>
-		Edit configuration file of &ser; and instead of <filename
-		    moreinfo="none">auth_db.so</filename> load <filename
-		    moreinfo="none">auth_radius.so</filename> and also replace <function
-		    moreinfo="none">www_authorize</function> with <function
-		    moreinfo="none">radius_www_authorize</function>.
-	    </simpara>
-	    <note>
-		<simpara>
-		    <function moreinfo="none">radius_www_authorize</function> takes just one
-		    parameter (as opposed to <function moreinfo="none">www_authorize</function>
-		    which takes 2).
-		</simpara>
-	    </note>
-	</section>
-	<section>
-	    <title>Accounting Configuration</title>
-	    <simpara>
-		To enable &rad; accounting simply use <varname>radius_log_flag</varname> and
-		<varname>radius_log_missed_flag</varname> parameters instead of <varname>log_flag</varname>
-		and <varname>log_missed_flag</varname>. Mark transactions that should be logged with
-		flags configured in the parameters.
-	    </simpara>
-	</section>
-	<section>
-	    <title>Group Membership Checking</title>
-	    <simpara>
-		Instead of <filename moreinfo="none">group.so</filename> load <filename
-		    moreinfo="none">group_radius.so</filename>. The module exports the same
-		    functions as <filename moreinfo="none">group.so</filename>, the only difference
-		    is that all the function names exported by <filename
-		    moreinfo="none">group_radius.so</filename> have <quote>radius_</quote> prefix.
-	    </simpara>
-	</section>
-    </chapter>
-
-    <chapter>
-	<title>Frequently Asked Questions</title>
-	<qandaset>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			I compiled &ser; &rad; modules and installed radiusclient library, but when I
-			try to start ser I get the following error message:
-		    </simpara>
-		    <programlisting format="linespecific">
-libradiusclient.so.0: cannot open shared object file: No such file or directory
-</programlisting>
-		</question>
-		<answer>
-		    <simpara>
-			Make sure that the directory which contains the library (usually <filename
-			    moreinfo="none">/usr/local/lib</filename>) is listed in <filename
-			    moreinfo="none">/etc/ld.so.conf</filename> and run <command
-			    moreinfo="none">ldconfig -v</command> (as root).
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			I configured everything as described in this HOWTO, but I get the following
-			message from radiusclient library <quote> check_radius_reply: received
-			invalid reply digest from RADIUS server</quote>. What does that mean ?
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			That means that radiusclient library was unable to verify digest of the
-			RADIUS message (it is not related to &sip; digest) because shared secret of
-			the client and server do not match.
-		    </simpara>
-		    <note>
-			<simpara>
-			    FreeRADIUS server has two files that can contain definitions of clients
-			    and corresponding shared secrets--<filename
-				moreinfo="none">clients</filename> and <filename
-			    moreinfo="none">clients.conf</filename>.
-			</simpara>
-			<simpara>
-			    If you have proper shared secret in one file and you still get the
-			    mentioned error message then check also the other file. This can easily
-			    happen to clients running on the same host (127.0.0.1 or localhost),
-			    because <filename moreinfo="none">clients.conf</filename> contains
-			    definition for localhost by default with secret <quote>testing123</quote>.
-			</simpara>
-		    </note>
-		</answer>
-	    </qandaentry>
-	</qandaset>
-    </chapter>
-</book>

doc/ser_radius/ser_radius.xml

@@ -0,0 +1,631 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4//EN"
+                      "file:///usr/share/sgml/docbook/dtd/xml/4/docbookx.dtd">
+
+<section id="ser_radius" xmlns:xi="http://www.w3.org/2001/XInclude">
+    <sectioninfo>
+	<authorgroup>
+	    <author>
+		<firstname>Jan</firstname>
+		<surname>Janak</surname>
+		<email>[email protected]</email>
+	    </author>
+	</authorgroup>
+	<copyright>
+	    <year>2003</year>
+	    <holder>FhG FOKUS</holder>
+	</copyright>
+	<revhistory>
+	    <revision>
+		<revnumber>$Revision$</revnumber>
+		<date>$Date$</date>
+	    </revision>
+	</revhistory>
+    </sectioninfo>
+
+    <title>SER RADIUS Howto</title>
+
+    <section id="introduction">
+	<title>Introduction</title>
+	<simpara>
+	    SER can be configured to use RADIUS server for authentication,
+	    accounting, and group membership checking. Since configuration of
+	    RADIUS seems to be a common source of problems, we decided to put
+	    together this HOWTO.
+	</simpara>
+	<simpara>
+	    The HOWTO covers installation and configuration of FreeRADIUS
+	    server only. There are also other RADIUS servers available and as
+	    long as they support digest authentication, they should work
+	    too. Any volunteers willing to describe setup of other RADIUS
+	    servers are encouraged to contact the author.
+	</simpara>
+	
+	<section id="prerequisities">
+	    <title>Prerequisites</title>
+	    <simpara>
+		To setup RADIUS support in SER you will need the following:
+	    </simpara>
+	    <itemizedlist>
+		<listitem>
+		    <simpara>
+			FreeRADIUS server, you can get it from <ulink
+			    url="http://www.freeradius.org">FreeRADIUS
+			    website</ulink>. The HOWTO describes installation
+			and setup of release 0.9.1.
+		    </simpara>
+		</listitem>
+		<listitem>
+		    <simpara>
+			Radiusclient library. In version 0.8.14 we started to
+			use the new version of radiusclient library developed
+			by Maxim Sobolev called radiusclient-ng. The homepage
+			of the library is <ulink
+			url="http://developer.berlios.de/projects/radiusclient-ng/">http://developer.berlios.de/projects/radiusclient-ng/</ulink>
+		    </simpara>
+		</listitem>
+		<listitem>
+		    <simpara>
+			SER, get it from <ulink url="http://iptel.org/ser">http://iptel.org/ser</ulink>
+		    </simpara>
+		</listitem>
+		<listitem>
+		    <simpara>
+			You should also have some experience in configuring
+			SER. Before you enable RADIUS authentication or
+			accounting make sure that the basic server is running
+			and that you know how to customize it to your taste.
+		    </simpara>
+		</listitem>
+		<listitem>
+		    <simpara>
+			If you want to use RADIUS accounting then you will have
+			to compile SER from sources so you should know how to
+			do it.
+		    </simpara>
+		</listitem>
+	    </itemizedlist>
+	    <simpara>
+		Various unix/linux distributions might include binary packages
+		of the mentioned applications. In that case you can safely use
+		the packages, there shouldn't be any problem. Location of some
+		files may be different, though. We will describe how to install
+		the software from sources only.
+	    </simpara>
+	    <warning>
+		<simpara>
+		    Configuration of FreeRADIUS server described in the
+		    document is in no way exhaustive. This document is a sort
+		    of quick-start-guide, it shows how to get things running,
+		    but you should definitely read FreeRADIUS documentation and
+		    configure the server properly ! You have been warned.
+		</simpara>
+	    </warning>
+	</section>
+    </section>
+
+    <section id="radiusclient">
+	<title>Radiusclient Library</title>
+	<simpara>
+	    Untar the source tarball.
+	</simpara>
+	<screen>
+root@localhost:/usr/local/src# tar xvfz radiusclient-0.4.3.tar.gz
+	</screen>
+	<simpara>
+	    Compile and install the library.
+	</simpara>
+	<screen>
+root@localhost:/usr/local/src# cd radiusclient-0.3.2
+root@localhost:/usr/local/src/radiusclient-0.3.2# ./configure
+root@localhost:/usr/local/src/radiusclient-0.3.2# make
+root@localhost:/usr/local/src/radiusclient-0.3.2# make install
+	</screen>
+	<simpara>
+	    By default all the configuration files of the radiusclient library
+	    will be in <filename>/usr/local/etc/radiusclient</filename>
+	    directory.
+	</simpara>
+	<simpara>
+	    If you use binary packages then the configuration files will be
+	    probably in <filename>/etc/radiusclient</filename>.
+	</simpara>
+	<section>
+	    <title>File <filename>radiusclient.conf</filename></title>
+	    <simpara>
+		The main configuration file of the library is
+		<filename>/usr/local/etc/radiusclient/radiusclient.conf</filename>,
+		open the file in your favorite text editor and find lines
+		containing the following:
+	    </simpara>
+	    <programlisting>
+authserver      localhost
+	    </programlisting>
+	    <simpara>
+		This is the hostname or IP address of the RADIUS server used
+		for authentication. You will have to change this unless the
+		server is running on the same host as your SIP proxy.
+	    </simpara>
+	    <programlisting>
+acctserver      localhost
+	    </programlisting>
+	    <simpara>
+		This is the hostname or IP address of the RADIUS server used
+		for accounting. You will have to change this unless the server
+		is running on the same host as your SIP proxy.
+	    </simpara>
+	</section>
+
+	<section id="servers">
+	    <title>File <filename>servers</filename></title>
+	    <simpara>
+		RADIUS protocol uses simple access control mechanism based on
+		shared secrets that allows RADIUS servers to limit access from
+		RADIUS clients. A RADIUS server is configured with a secret
+		string and only RADIUS clients that have the same secret will
+		be accepted.
+	    </simpara>
+	    <simpara>
+		You need to configure a shared secret for each server you have
+		configured in <filename>radiusclient.conf</filename> file in
+		the previous step. The shared secrets are stored in
+		<filename>/usr/local/etc/radiusclient/servers</filename> file.
+	    </simpara>
+	    <simpara>
+		Each line contains hostname of a RADIUS server and shared
+		secret used in communication with that server. The two values
+		are separated by whitespaces. Configure shared secrets for
+		every RADIUS server you are going to use.
+	    </simpara>
+	    <warning>
+		<simpara>
+		    RADIUS servers and clients must be configured with the same
+		    shared secret, otherwise they will not accept RADIUS
+		    messages from each other and neither authentication nor
+		    accounting will work !
+		</simpara>
+	    </warning>
+	</section>
+
+	<section id="dictionary_client">
+	    <title>File <filename>dictionary</filename></title>
+	    <simpara>
+		Radiusclient library contains file called
+		<filename>dictionary.ser</filename>. That file includes all the
+		attributes that are needed by SER. Include the file in the
+		main <filename>dictionary</filename> file. To
+		include the file, put the following line at the end of
+		<filename>dictionary</filename> file:
+	    </simpara>
+	    <screen>
+$INCLUDE /usr/local/etc/radiuclient/dictionary.ser
+	    </screen>
+	</section>
+    </section>
+    
+    <section id="freeradius">
+	<title>FreeRADIUS Server</title>
+	<simpara>
+	    Untar, configure, build, and install the server:
+	</simpara>
+	<screen>
+root@localhost:/usr/local/src# tar xvfz freeradius-0.9.1.tar.gz
+root@localhost:/usr/local/src# cd freeradius-0.9.1
+root@localhost"/usr/local/src/freeradius-0.9.1# ./configure
+root@localhost"/usr/local/src/freeradius-0.9.1# make
+root@localhost"/usr/local/src/freeradius-0.9.1# make install
+	</screen>
+	<simpara>
+	    All the configuration files of FreeRADIUS server will be in
+	    <filename>/usr/local/etc/raddb</filename> directory. If you install
+	    a binary package then you will probably find them in
+	    <filename>/etc/raddb</filename>.
+	</simpara>
+	<simpara>
+	    The following sections describe how to configure freeradius
+	    server. First we describe the common configuration that must be
+	    done in any case. Configuration specific for authentication,
+	    accounting, and group membership checking will be described in
+	    separate sections.
+	</simpara>
+	
+	<section id="common_configuration">
+	    <title>Common configuration</title>
+	    <section>
+		<title>File <filename>clients.conf</filename></title>
+		<simpara>
+		    File <filename>/usr/local/etc/raddb/clients.conf</filename>
+		    contains description of RADIUS clients that are allowed to
+		    use the server. For each of the clients you need to specify
+		    it's hostname or IP address and also a shared secret. The
+		    shared secret must be the same string you configured in
+		    radiusclient library.
+		</simpara>
+		<simpara>
+		    Suppose that your SIP server is running on host
+		    proxy.foo.bar and radiusclient library on that machine has
+		    been configure with "foobarsecret" as the shared
+		    secret. You need to put the following section into the
+		    file:
+		</simpara>
+		<programlisting>
+client proxy.foo.bar {
+    secret = foobarsecret
+    shortname = foo
+}
+		</programlisting>
+		<simpara>
+		    This fragment allows access from RADIUS clients on
+		    proxy.foo.bar if they use "foobarsecret" as the shared
+		    secret.
+		</simpara>
+		<note>
+		    <simpara>
+			The file already contains an entry for localhost (127.0.0.1), so if you are
+			running the RADIUS server on the same host as your SIP server, then modify
+			the existing entry instead. By default it contains shared secret
+			"testing123".
+		    </simpara>
+		</note>
+	    </section>
+	    
+	    <section id="dictionary_server">
+		<title>File <filename>dictionary</filename></title>
+		<simpara>
+		    File <filename>/usr/local/etc/raddb/dictionary</filename>
+		    contains the dictionary of FreeRADIUS server. You have to
+		    add the same dictionary file
+		    (<filename>dictionary.ser</filename>), which you added to
+		    the dictionary of radiusclient library, also here. In this
+		    case you don't have to append the contents of the file, you
+		    can include it into the main file.  Add the following line
+		    at the end of
+		    <filename>/usr/local/etc/raddb/dictionary</filename>:
+		</simpara>
+		<programlisting>
+$INCLUDE /usr/local/etc/radiusclient/dictionary.ser
+		</programlisting>
+		<simpara>
+		    That will include the same attribute definitions that are
+		    used in radiusclient library so the client and server will
+		    understand each other.
+		</simpara>
+	    </section>
+	    
+	    <section id="radiusd.conf">
+		<title>File <filename>radiusd.conf</filename></title>
+		<simpara>
+		    Digest authentication is disabled by default and you must
+		    enable it in this file. There are two sections, "authorize"
+		    and "authenticate". Both sections contain line containing
+		    word "digest". Both of them are commented and you must
+		    un-comment them to enable digest authentication.
+		</simpara>
+		<note>
+		    <simpara>
+			There is also another line containing word "digest"
+			followed by curly braces and it is enabled by
+			default. The section is supposed to contain digest
+			module parameters but because digest module has no
+			parameters, it is empty. This is not the line you are
+			supposed to uncomment ! There are two more.
+		    </simpara>
+		</note>
+	    </section>
+	    
+	    <section id="users">
+		<title>File <filename>users</filename></title>
+		<simpara>
+		    This file contains authentication information for each
+		    user. For testing purposes we will create user "test". Put
+		    the following into the file:
+		</simpara>
+		    <programlisting>
+test Auth-Type := Digest, User-Password == "test"
+     Reply-Message = "Hello, test with digest"
+		</programlisting>
+		
+		<simpara>
+		    The username and password is for testing only, you can
+		    safely remove the entry once your RADIUS server works and
+		    you are able to authenticate.
+		</simpara>
+	    </section>
+	</section>
+	
+	<section id="test">
+	    <title>Test The Server</title>
+	    <note>
+		<simpara>
+		    This step is optional.
+		</simpara>
+	    </note>
+	    <simpara>
+		The basic configuration of FreeRADIUS server is done it now we
+		are going to test if it really works. Start the server with
+		parameter -X. That will cause the server to stay in the
+		foreground (it will not turn into daemon) and produce a lot of
+		debugging information on the standard output:
+	    </simpara>
+	    <screen>
+root@/usr/local/src# radiusd -X
+	    </screen>
+	    <simpara>
+		Create file <filename>digest</filename> and put the following
+		into the file:
+	    </simpara>
+	    <programlisting>
+User-Name = "test", Digest-Response = "631d6d73147add2f9e437f59bbc3aeb7", 
+Digest-Realm = "testrealm", Digest-Nonce = "1234abcd" , 
+Digest-Method = "INVITE", Digest-URI = "sip:[email protected]", 
+Digest-Algorithm = "MD5", Digest-User-Name = "test"
+	    </programlisting>
+	    <simpara>
+		All the attributes must be on a single line.
+	    </simpara>
+	    <simpara>
+		Run <command>radclient</command> to test the server:
+	    </simpara>
+	    <screen>
+root@/usr/local/src# radclient -f digest localhost auth &lt;shared_secret&gt;
+</screen>
+	    <note>
+		<simpara>
+		    I suppose that you run the test utility directly on the
+		    RADIUS server since it comes with the FreeRADIUS server
+		    package. That also means that you have to enable access
+		    from localhost in your <filename>clients.conf</filename>
+		    file. Don't forget to replace &lt;shared_secret&gt; with
+		    the shared secret configured for locahost clients in
+		    <filename>clients.conf</filename>.
+		</simpara>
+	    </note>
+	    <simpara>
+		If your server works properly then you should see the following response:
+	    </simpara>
+	    <screen>
+Received response ID 224, code 2, length = 45
+        Reply-Message = "Hello, test with digest"
+	    </screen>
+	</section>
+	
+	<section id="auth_configuration">
+	    <title>Authentication Configuration</title>
+	    <simpara>
+		To create user "joe" in domain "iptel.org" with password
+		"heslo" put the following into file
+		<filename>/usr/local/etc/raddb/users</filename>:
+	    </simpara>
+	    <programlisting>
[email protected] Auth-Type := Digest, User-Password == "heslo"
+     Reply-Message = "Authenticated",
+     Sip-Rpid = "1234"
+	    </programlisting>
+	    <simpara>
+		Attribute "Sip-Rpid" is optional. The attribute
+		contains a phone number associated to the user. SER can be
+		configured to put the phone number into Remote-Party-ID header
+		field of the SIP message. The header field can be then used
+		by PSTN gateways to display the number as the number of the
+		caller on regular phones. You can omit the attribute if you
+		don't need it.
+	    </simpara>
+	</section>
+	
+	<section id="accounting_configuration_server"> 
+	    <title>Accounting Configuration</title>
+	    <simpara>
+		By default FreeRADIUS server will log all accounting requests
+		into <filename>/usr/local/var/log/radius/radacct</filename>
+		directory in form of plain text files. The server will
+		create one file for each hostname in the directory. The
+		following example shows how the log files look like.
+	    </simpara>
+	    <example>
+		<title>Example of Accounting Report</title>
+		<programlisting>
+Tue Jun 24 00:20:55 2003
+        Acct-Status-Type = Start
+        Service-Type = 15
+        Sip-Response-Code = 200
+        Sip-Method = 1
+        User-Name = "[email protected]"
+        Calling-Station-Id = "sip:[email protected]"
+        Called-Station-Id = "sip:[email protected]"
+        Sip-Translated-Request-URI = "sip:[email protected]"
+        Acct-Session-Id = "[email protected]"
+        Sip-To-Tag = "cb2cfe2e-3659-28c7-a8cc-ab0b8cbd3012"
+        Sip-From-Tag = "a783bd2f-bb8d-46fd-84a9-00a9833f189e"
+        Sip-CSeq = "1"
+        NAS-IP-Address = 192.168.2.16
+        NAS-Port = 5060
+        Acct-Delay-Time = 0
+        Client-IP-Address = 127.0.0.1
+        Acct-Unique-Session-Id = "9b323e6b2f5b0f33"
+        Timestamp = 1056406855
+
+Tue Jun 24 00:20:56 2003
+        Acct-Status-Type = Stop
+        Service-Type = 15
+        Sip-Response-Code = 200
+        Sip-Method = 8
+        User-Name = "[email protected]"
+        Calling-Station-Id = "sip:[email protected]"
+        Called-Station-Id = "sip:[email protected]"
+        Sip-Translated-Request-URI = "sip:192.168.2.32:9576"
+        Acct-Session-Id = "[email protected]"
+        Sip-To-Tag = "a783bd2f-bb8d-46fd-84a9-00a9833f189e"
+        Sip-From-Tag = "cb2cfe2e-3659-28c7-a8cc-ab0b8cbd3012"
+        Sip-CSeq = "4580"
+        NAS-IP-Address = 192.168.2.16
+        NAS-Port = 5060
+        Acct-Delay-Time = 0
+        Client-IP-Address = 127.0.0.1
+        Acct-Unique-Session-Id = "b2c2479a07b17c95"
+        Timestamp = 1056406856
+		</programlisting>
+	    </example>
+	</section>
+	
+	<section id="group_checking">
+	    <title>Group Checking Configuration</title>
+	    <simpara>
+		If you want to make user "joe" in domain "iptel.org" member of
+		group "pstn" then add the following to your
+		<filename>/usr/local/etc/raddb/users</filename> file:
+	    </simpara>
+	    <programlisting>
[email protected] Sip-Group == "pstn", Auth-Type := Accept
+        Reply-Message = "Authorized"
+	    </programlisting>
+	</section>
+    </section>
+    
+    <section id="ser_config">
+	<title>SER Configuration</title>
+	<simpara>
+	    We will describe installation from sources here. If you use binary
+	    packages then there is an additional package containing RADIUS
+	    related modules. You will need to install the package.
+	</simpara>
+	<warning>
+	    <simpara>
+		Due to a mistake the binary packages for RADIUS do not include
+		RADIUS-enabled version of acc (accounting) module. The packages
+		contain modules for RADIUS authentication and group membership
+		checking only.
+	    </simpara>
+	    <simpara>
+		If you need accounting over RADIUS then you will have to
+		compile RADIUS-enabled version of acc module from the
+		sources. This will be fixed in one of future releases, we
+		apologize for any inconvenience.
+	    </simpara>
+	</warning>
+	<simpara>
+	    RADIUS-related modules are not compiled by default. To compile
+	    them, edit <filename>Makefile</filename>, find variable
+	    <varname>exclude_modules</varname> and you should see
+	    "auth_radius", "group_radius", and "uri_radius" among excluded
+	    modules. Simply remove the three modules from the list.
+	</simpara>
+	<simpara>
+	    If you need RADIUS accounting then edit also sip_router/modules/acc/Makefile and
+	    uncomment lines containing:
+	</simpara>
+	    <programlisting>
+DEFS+=-DRAD_ACC
+LIBS=-L$(LOCALBASE)/lib -lradiusclient
+	</programlisting>
+	<simpara>
+	    Then recompile and re-install SER:
+	</simpara>
+	<screen>
+root@localhost:/usr/local/src/sip_router# make proper
+root@localhost:/usr/local/src/sip_router# make all
+root@localhost:/usr/local/src/sip_router# make install
+	</screen>
+
+	<section id="auth_configuration_client">
+	    <title>Authentication Configuration</title>
+	    <simpara>
+		Edit configuration file of SER and instead of
+		<filename>auth_db.so</filename> load
+		<filename>auth_radius.so</filename> and also replace
+		<function>www_authorize</function> with
+		<function>radius_www_authorize</function>.
+	    </simpara>
+	    <note>
+		<simpara>
+		    <function>radius_www_authorize</function> takes just one
+		    parameter (as opposed to <function>www_authorize</function>
+		    which takes 2).
+		</simpara>
+	    </note>
+	</section>
+
+	<section id="acc_configuration">
+	    <title>Accounting Configuration</title>
+	    <simpara>
+		To enable RADIUS accounting simply use
+		<varname>radius_log_flag</varname> and
+		<varname>radius_log_missed_flag</varname> parameters instead of
+		<varname>log_flag</varname> and
+		<varname>log_missed_flag</varname>. Mark transactions that
+		should be logged with flags configured in the parameters.
+	    </simpara>
+	</section>
+
+	<section id="group_membership_checking">
+	    <title>Group Membership Checking</title>
+	    <simpara>
+		Instead of <filename>group.so</filename> load
+		<filename>group_radius.so</filename>. The module exports the
+		same functions as <filename>group.so</filename>, the only
+		difference is that all the function names exported by
+		<filename>group_radius.so</filename> have "radius_" prefix.
+	    </simpara>
+	</section>
+    </section>
+	
+    <section id="faq">
+	<title>Frequently Asked Questions</title>
+	<qandaset>
+	    <qandaentry>
+		<question>
+		    <simpara>
+			I compiled SER RADIUS modules and installed
+			radiusclient library, but when I try to start ser I get
+			the following error message:
+		    </simpara>
+		    <programlisting>
+libradiusclient.so.0: cannot open shared object file: No such file or directory
+		    </programlisting>
+		</question>
+		<answer>
+		    <simpara>
+			Make sure that the directory which contains the library
+			(usually <filename>/usr/local/lib</filename>) is listed
+			in <filename>/etc/ld.so.conf</filename> and run
+			<command>ldconfig -v</command> (as root).
+		    </simpara>
+		</answer>
+	    </qandaentry>
+	    <qandaentry>
+		<question>
+		    <simpara>
+			I configured everything as described in this HOWTO, but
+			I get the following message from radiusclient library
+			"check_radius_reply: received invalid reply digest from
+			RADIUS server". What does that mean ?
+		    </simpara>
+		</question>
+		<answer>
+		    <simpara>
+			That means that radiusclient library was unable to
+			verify digest of the RADIUS message (it is not related
+			to SIP digest) because shared secret of the client
+			and server do not match.
+		    </simpara>
+		    <note>
+			<simpara>
+			    FreeRADIUS server has two files that can contain
+			    definitions of clients and corresponding shared
+			    secrets--<filename>clients</filename> and
+			    <filename>clients.conf</filename>.
+			</simpara>
+			<simpara>
+			    If you have proper shared secret in one file and you still get the
+			    mentioned error message then check also the other file. This can easily
+			    happen to clients running on the same host (127.0.0.1 or localhost),
+			    because <filename>clients.conf</filename> contains
+			    definition for localhost by default with secret "testing123".
+			</simpara>
+		    </note>
+		</answer>
+	    </qandaentry>
+	</qandaset>
+    </section>
+    
+</section>
+

doc/serfaq/Makefile

@@ -0,0 +1,29 @@
+#
+# The list of documents to build (without extensions)
+#
+DOCUMENTS = serfaq
+
+#
+# The root directory containing Makefile.doc
+#
+ROOT_DIR=../..
+
+#
+# Validate docbook documents before generating output
+# (may be slow)
+#
+#VALIDATE=1
+
+#
+# You can override the stylesheet used to generate
+# xhtml documents here
+#
+#XHTML_XSL=$(ROOT_DIR)/doc/stylesheets/xhtml.xsl
+
+#
+# You can override the stylesheet used to generate
+# plain text documents here
+#
+#TXT_XSL=$(XHTML_XSL)
+
+include $(ROOT_DIR)/Makefile.doc

doc/serfaq/serfaq.sgml

@@ -1,1304 +0,0 @@
-<!-- $Id$ -->
-<!DOCTYPE Book PUBLIC "-//OASIS//DTD DocBook V4.2//EN" [
-
-<!-- Include general SER documentation entities -->
-<!ENTITY % serentities SYSTEM "../ser_entities.sgml">
-
-<!ENTITY % licensing SYSTEM "licensing.sgml">
-<!ENTITY % serweb SYSTEM "serweb.sgml">
-
-%serentities;
-
-]>
-
-<book>
-    <bookinfo>
-	<title>&ser; Frequently Asked Questions</title>
-	<authorgroup>
-	    <editor>
-		<firstname>Jan</firstname>
-		<surname>Janak</surname>
-		<email>[email protected]</email>
-	    </editor>
-	</authorgroup>
-	<copyright>
-	    <year>2003</year>
-	    <holder>&fhg;</holder>
-	</copyright>
-	<abstract>
-	    <para>
-		A compilation of questions and answers from <email>[email protected]</email>,
-		<email>[email protected]</email>, and <email>[email protected]</email> mailing
-		lists.
-	    </para>
-	</abstract>
-    </bookinfo>
-    <toc></toc>
-    
-    <chapter>
-	<title>General</title>
-	<qandaset>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			Is it possible to use &ser; as a &sip; user agent (both of User Agent Client
-			(&uac;) and User Agent Server (&uas;)?
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			Not easily. &ser; has built-in some functions that allow to use it as user
-			agent, but our primary goal is to develop a server so this is without
-			guarantee and can even disappear in future versions.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			Can &ser; work well together with some of the location server (e. g.LDAP or DNS) ?
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			&ser;'s built-in location server uses in-<acronym>RAM</acronym> database for
-			high performance and optionally MySQL for persistence. More database
-			protocols may be supplied on contractual basis. As far as I know,
-			<acronym>DNS</acronym> is not used in the industry for user location.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			What is a proxy server ?
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			A proxy server is an entity that routes &sip; messages. See &sip
-			introduction which is part of the distribution.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    What is the difference between proxy server and back to back user agent (B2BUA) ?
-		</question>
-		<answer>
-		    <simpara>
-			The main difference is that proxy servers are transaction-stateful, while
-			B2BUAs are call stateful. That means proxy servers keep state only during
-			&sip; transactions (that is at the beginning and and of a call) and do not
-			keep any state during the whole call.
-		    </simpara>
-		    <simpara>
-			A B2BUA acts merely as connection of two or more user agents which are
-			connected through some means. B2BUAs keep some state (usually some structures
-			in the memory) during the whole call.
-		    </simpara>
-		    <para>
-			This property gives B2BUA some interesting features that proxies don't
-			have. For example B2BUA can tear down and existing call--proxies can't do
-			that. On the other hand B2BUAs can easily become a bottleneck in terms of
-			scalability.
-		    </para>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			So is &ser; proxy or B2BUA ? Can it terminate an existing call ?
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			&ser; is a proxy. I can't terminate existing call.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			I'd like to know if &ser; supports <acronym>CPL</acronym> and
-			servlets. Where can I find any documentation about this, or any link ?
-		    </simpara>
-		    </question>
-		    <answer>
-		    <simpara>
-			Yes, <acronym>CPL</acronym> is supported through cpl module, the module
-			needs an external <acronym>CPL</acronym> interpreter written in Java. A C
-			version is under development. There is no support for Java servlets. The
-			documentation can be found at <ulink
-			url="http://iptel.org/ser/doc">http://iptel.org/ser/doc</ulink>.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			I wanted to know whether &lt;PUT_YOUR_FAVOURITE_METHOD_HERE&gt; is supported
-			by &ser;.
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			Proxy server are indifferent of non-INVITEs methods. &lt;METHOD&gt; works as
-			good as BYE, INFO, and FOOBAR.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			I was wondering if &ser; has been tested and is supported on FreeBSD ?
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			Yes.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			Does &ser; support <acronym>TCP</acronym> ?
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			Yes.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			I think I found a bug that should be fixed, what information should I send
-			and where should I send it?
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			Please send us as much info as possible. We would like see the following:
-		    </simpara>
-		    <itemizedlist>
-			<listitem>
-			    <simpara>&ser; version (ser -V).</simpara>
-			</listitem>
-		    </itemizedlist>
-		    <itemizedlist>
-			<listitem>
-			    <simpara>Configuration file.</simpara>
-			</listitem>
-		    </itemizedlist>
-		    <itemizedlist>
-			<listitem>
-			    <simpara>&sip; message dumps.</simpara>
-			</listitem>
-		    </itemizedlist>
-		    <itemizedlist>
-			<listitem>
-			    <simpara>Coredump (if any, if not please generate it).</simpara>
-			</listitem>
-		    </itemizedlist>
-		    <itemizedlist>
-			<listitem>
-			    <simpara>Anything else you think might help us.</simpara>
-			</listitem>
-		    </itemizedlist>
-		    <itemizedlist>
-			<listitem>
-			    <simpara>The whole compiled source tree.</simpara>
-			</listitem>
-		    </itemizedlist>
-		    <simpara>
-			Please send it to <email>[email protected]</email>.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			How does &ser; scale ?
-		    </simpara>
-		    <simpara>
-			&ser; is able to handle thousands calls per second on a regular
-			<acronym>PC</acronym>.
-		    </simpara>
-		</question>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			I read <quote>Throughput thousands of calls per second
-			    (<acronym>CPS</acronym>) on a dual-<acronym>CPU</acronym>
-			    <acronym>PC</acronym></quote> on your webpage. How fast is it really ?
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			Last time we have  checked ~4900cps on a dual Athlon MP2000.
-		    </simpara>
-		    <simpara>
-			This was ser 0.8.9 running statefully (stateless is should be much faster),
-			with 4 processes and 256 Mb shared mem.  It was compiled with: STATS:Off,
-			USE_IPV6, NO_DEBUG, SHM_MEM, SHM_MMAP, PKG_MALLOC, F_MALLOC,
-			FAST_LOCK-ADAPTIVE_WAIT ADAPTIVE_WAIT_LOOPS=1024, MAX_RECV_BUFFER_SIZE
-			262144, MAX_LISTEN 16, MAX_URI_SIZE 1024, BUF_SIZE 3040
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			Do you think that &ser; is suitable for a commercial environment in your opinion ?
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			Sure.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			Do you have any recommendations on additional open source or developer
-			community resources to round out my platform?
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			I'm a &ser; believer and think that other servers simply don't compare :) If
-			you wish more detailed propaganda, check our website and if that is not
-			enough I will send you some more.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			Do you have any thoughts on how it compares in deployability and features to
-			the Vovida stuff or other options ? Also, are there any issues I should be
-			thinking of that would make a commercial venture with &ser; difficult
-			(licensing, scaling, etc..)
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			&ser; is licensed under &gnu; &gpl;. I would be surprised if any &sip;
-			server available today would scale a bit better--we spent lot of work on
-			performance, achieved thousands of <acronym>CPS</acronym> on a
-			<acronym>PC</acronym>--I guess it will take lot of time until your demand
-			hits this capacity.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			Does &ser; have the capability to automatically send an INVITE from one
-			number to another?
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			Yes if the phones support REFER. There is an application called
-			Click-To-Dial which can connect two phones.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			Is it necessary to have a <acronym>DNS SVR</acronym> Resource Record, as
-			mentioned in the ser-Howto guide for connecting to &ser; ?
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			No. It's nice to have it, but you can work around it setting a normal A
-			record for your domain. The <acronym>SRV</acronym> lookup will fall back to
-			normal A lookup.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			What would you charge to help get us started?
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			See <ulink url="http://iptel.org/support">http://iptel.org/support</ulink>.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			Are you going to provide integration support from &sip; to H.323 and vice
-			versa ?
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			No, we are not going to provide the integration.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			I've gone thru the &ser; Admin's Guide and the module documentation
-			(sip_router/modules/). Is there additional documentation on how to use the
-			modules?
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			Each module has a doc subdirectory which contains complete documentation of
-			the module in docbook format. <acronym>PS</acronym>, <acronym>PDF</acronym>
-			and <acronym>HTML</acronym> renderings can be obtained through our web page,
-			see <ulink url="http://iptel.org/ser/doc">http://iptel.org/ser/doc</ulink>.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			What functions would I use in my ser.cfg to log <quote>missed calls</quote>?
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			FIXME.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			Are there some additional requirements for using the acc.so module?  Radius?
-			I want to be able to view dialed calls from serweb.
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			FIXME.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			Do you have any example configs that use nathelper?
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			FIXME.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			Who are the people behind &ser; ?
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			FIXME.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			How successful has nathelper been with <acronym>NAT</acronym>/firewall transversal?
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			I only know that users reported success with nathelper and ATAs.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			Does ser support <acronym>LDAP</acronym> ?
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			FIXME.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			Is it possible to get access to iptel's working copy of ser.cfg?
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			We no longer disclose our operational policy to the public audience. The
-			configuration file is only available to our customers under <acronym>NDA</acronym>.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			Can you send me detail for me to sign up for the commercial program. I would
-			also like detail on your levels of support you offer (ie...paid support)?
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			See <ulink
-			    url="http://iptel.org/support/">http://iptel.org/support/</ulink>. Don't
-			    hesitate to approach us if you have any further questions.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			I need a method to determine if a called &uri; has an account on the system.
-			I found a function in the groups module,
-			<function>is_user_in</function>. but haven't yet figured out how to use it.
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			The uri module's <function>does_uri_exist</function> is what you are seeking.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			We have a question regarding usrloc: where are the active sessions
-			being stored? We were not able to find any entries in MySQL.
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			&ser; has no notion of active session. &ser; is a transaction-stateful proxy,
-			that means it knows about transactions (INVITE transaction, BYE
-			transaction), but it keeps no state if there is no transaction active.
-		    </simpara>
-		    <simpara>
-			That means, it keeps state when an INVITE comes and until a final response
-			to the INVITE is sent. The same for BYE.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			Has the timeout for re-registering at the &ua; to be the same as in the tm
-			module mentioned in <filename>ser.cfg</filename> ?
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			No.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			How do we deal with aliases? If for example uid=mic is authenticated, he is
-			available with sip address sip:[email protected]. If I would want to be
-			addressable with [email protected] how is this accomplished with ser
-			?
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			Aliases are tied to user location. It uses a special table which has the
-			same structure as user location table and includes an entry for each
-			alias. You do not have to do something special for that. You have to create
-			this table and then you can use serctl to add aliases.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			I would like to know if &ser; supports <acronym>IPv6</acronym>. If not, do
-			you have any plans for it ? When ?
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			Yes, &ser; supports <acronym>IPv6</acronym>.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			Is there any way to change the default log file to a special SER.log file ?
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			Try logging to stderr and redirecting it to a file:
-		    </simpara>
-		    <screen format="linespecific">
-ser -E     2>/tmp/ser.log
-</screen>
-		    <simpara>
-			(by default ser logs to syslog)
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			Does anybody know anything about the P-Hint Header Field added from &ser;?
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			<ulink url="http://www.iptel.org/ser/doc/seruser-html/c638.html#AEN729">
-			    http://www.iptel.org/ser/doc/seruser-html/c638.html#AEN729
-			</ulink>
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			When using the Jabber Gateway, some users get the following error from time to
-			time:
-		    </simpara>
-		    <simpara>
-			ERROR: Connection to Jabber server lost. You have to login to Jabber server
-			again (join again the conferences that you were participating, too).
-		    </simpara>
-		    <simpara>
-			sip_to_jabber_gateway says:
-		    </simpara>
-		    <simpara>
-			INFO: Your are now offline in Jabber network. Thank you for using &sip;-Jabber
-			gateway.
-		    </simpara>
-		    <simpara>
-			Do you know the reason why these messages appear and if it is possible to
-			avoid them?
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			that usually occurs because Jabber server crashes or, for some unknown
-			reasons, the <acronym>TCP</acronym> connection with jabber server is
-			down. The second message is to inform the users that they are no more
-			connected to Jabber network.
-		    </simpara>
-		    <simpara>
-			There is no way to disable sending these messages. I may introduce a new
-			parameter to enable/disable them. But I am not sure it is a good idea (users
-			must be informed about the changes of the status).
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			I would like know if &ser; support also the transmission protocol
-			<acronym>TCP</acronym>, or <acronym>TLS</acronym>.
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			Yes, &ser; supports <acronym>TCP</acronym>. <acronym>TLS</acronym> is work
-			in progress.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			I'm trying to rewrite the to domain, as in:
-		    </simpara>
-		    <simpara>
-			To: &lt;sip:[email protected]&gt; ;user=phone.
-		    </simpara>
-		    <simpara>
-			I can't find any rewrite* function to rewrite the
-			to domain.
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			The proxy is not supposed to touch To or From &uri;s. Only Request-&uri; can
-			be changed.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			When the messenger sends a message for the jabber gateway the following
-			error occurs:
-		    </simpara>
-		    <simpara>
-			<quote>ERROR: Your message was not sent. You do not have permissions to use the
-			    gateway.</quote>
-		    </simpara>
-		    <simpara>
-			What could be the problem here?
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			You have to create the database for SIMPLE2Jabber gateway and after that you
-			have to associate &sip; users with Jabber IDs.
-		    </simpara>
-		    <simpara>
-			<ulink
-			    url="http://www.iptel.org/ser/doc/jabgw/xjab-manual.html#5._Admins_guide">
-			    http://www.iptel.org/ser/doc/jabgw/xjab-manual.html#5._Admins_guide
-			</ulink>
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			Authentication doesn't work!!!  Where am I wrong?
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			Windows Messenger needs same string both realm and SIP_DOMAIN, and it wants
-			to reach this address oh your network.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			I was wondering whether there is a ser module for
-			<acronym>SIP-CGI</acronym>. Or whether there are attempts at creating one?
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			There is no <acronym>SIP-CGI</acronym> module for &ser;. The most similar,
-			though much simpler, functionality is provided by the exec module.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			How could I integrate &sip; and H323 together?
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			You will need a &sip; to H.323 gateway. &ser; is a &sip; proxy only, it
-			cannot act as H.323 gateway.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			How can I contribute code ?
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			FIXME.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			What, if anything, should the &ser; server do with a OPTIONS method?
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			FIXME.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			What should I do to see the detailed debugs?
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			Set debug=9 in your config script.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			Is it possible for &ser; to forward a call to another phone if the recipient
-			does not answer?
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			This could be achieved with sequential forking (by trying contacts in
-			decreasing q order), but sequential forking is not yet supported in &ser;.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			Is it possible to configure &ser; so that it only has the latest
-			registration?
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			FIXME.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			mkdir: cannot create directory `/usr/local/etc/ser': Permission denied
-			make: *** [/usr/local/etc/ser] Error 1
-		    </simpara>
-		    <simpara>
-			what may be the error ?
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			You have no write permissions to the directory, try it again as root.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			Can a proxy terminate a call ?
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			No, proxy cannot do that because it is transaction stateful only.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			i want to know what accounting support is available using MySql. what
-			settings need to be done? are any records generated and placed in the
-			database? how do i access these records?
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			FIXME.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			It seems that &ser; supports only strict routing. Please tell me if it
-			supports loose routing. if yes, do i have to enable it somehow?
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			Yes, it does support loose routing as of 0.8.11, you don't have to enable it.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			I need to know if currently generated call records can be put into MySql
-			database. if yes, is there any tool available to view these records?
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			Serweb can do it.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			If I want to use &ser; commercially do I need to purchase any license for
-			the same, as long as I'm not going to charge the customer for the &sip;
-			service but only for the termination of calls.
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			&ser; is distributed under the &gpl; so you don't need to purchase any
-			license, you can use it freely.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			Is there a support for accounting ?
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			Yes, see acc module.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			What tool can I use to capture &sip; traffic ?
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			<ulink url="http://ngrep.sourceforge.net">ngrep</ulink>, <ulink
-			    url="http://www.ethereal.com">ethereal</ulink>, <ulink
-			    url="http:/www.tcpdump.org">tcpdump</ulink>.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			Is there ENUM support in &ser; ?
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			Yes, see enum module.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			Do you have any experience (or know) where I can get some info on setting up
-			an ENUM testbed with <acronym>DNS</acronym> and Linux?
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			if by testbed you mean running your own e164.arpa root, then you simply
-			make your dns server a root for e164.arpa domain by adding line
-		    </simpara>
-		    <programlisting format="linespecific">
-primary         e164.arpa               e164.arpa.db
-</programlisting>
-		    <simpara>
-			into your named.boot file and then by populating file e164.arpa.db with
-			your enum entries.  Below is an example.
-		    </simpara>
-		    <programlisting format="linespecific">
-$ORIGIN .
-$TTL 0  ; 0 seconds
-e164.arpa               IN SOA  foo.fi. hostmaster.foo.fi. (
-                                200204681  ; serial
-				28800      ; refresh (8 hours)
-				7200       ; retry (2 hours)
-				604800     ; expire (1 week)
-				86400      ; minimum (1 day)
-			)
-		        NS      foo.fi.
-$ORIGIN e164.arpa.
-$ORIGIN 8.5.3.e164.arpa.
-$ORIGIN 9.3.8.1.5.6.2.8.5.3.e164.arpa.
-3.1   NAPTR   1 1 <quote>u</quote> <quote>E2U+sip</quote> <quote>!(^.*$)!sip:[email protected]!i</quote> .
-</programlisting>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			Will &ser; support <acronym>STUN</acronym> in the future?
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			<acronym>STUN</acronym> is a protocol operated separately from &ser;
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			Is there any way to show active calls (dialed number, duration, originating
-			<acronym>IP</acronym>...) with &ser;?
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			No, ser is not call stateful.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			If I'm working with &rfc2543; compliant phones (such as
-			<acronym>ATA</acronym>) may I use loose routing?
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			Yes, loose routing is backwards compatible.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			How can I configure radiator for digest authentication?
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			In case of radiator, you don't need to do anything special in the
-			configuration.  Just install the latest radiator and then make sure your
-			config can handle the service-types you have configured ser to use. For
-			example, you can have
-		    </simpara>
-		    <programlisting format="linespecific">
-&lt;Handler Service-Type=SIP&gt;
-...
-&lt;/AuthBy&gt;
-</programlisting>
-		    <simpara>
-			Or whatever your strategy is.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			How can I configure radiator for digest authentication?
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			see freeradius-0.8.1/doc/rlm_digest
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			Trying to create alias, I am getting the following message:
-		    </simpara>
-		    <simpara>
-			<quote>400 Table 'aliases' Not Found</quote>
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			You must have lookup(<quote>aliases</quote>) somewhere in your script.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-
-	    <qandaentry>
-		<question>
-		    <simpara>
-			Also how much shared memory does &ser; allocate by default?
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			32 Mb.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			How can I identify what ser doesn't like about the config file?
-		    </simpara>
-		</question>
-		<answer>
-		    <programlisting format="linespecific">
-0(612) parse error (81,1-10): syntax error
-0(612) parse error (91,1-6):
-                    ^^^^^^
-</programlisting>
-		    <simpara>
-			These are the line number and the characters. So look in line 81 and 91 of
-			your config file for errors.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <programlisting format="linespecific">
-Warning: 392 216.87.144.203:5060 "Noisy feedback tells:  pid=19604
-req_src_ip=216.87.144.205 req_src_port=5065 in_uri=sip:addaline.com
-out_uri=sip:addaline.com via_cnt==1".
-</programlisting>
-		    <simpara>
-			I want to get rid of these?
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			Use sip_warning=no
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			Is &ser; a gatekeeper ?
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			No, &ser; is a &sip; proxy.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			Is there an example of the session timer with &ser; somewhere?
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			That's a theoretical &sip; option today, &ser; is not supporting
-			session-timer.  We gave it a try more than one year ago and gave up due to
-			interop problems.  The specification was developing at that time so quickly
-			that there was not any UA which would work with another one correctly.
-		    </simpara>
-		    <simpara>
-			Once the interoperability gets better, it could be worth implementing. It is
-			in general a nice mechanism for avoiding session state silo in network,
-			which is good for scalability.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			Could someone point me where I can read about this www_authorize()
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			The documentation is in sip_router/modules/auth_db/doc
-		    </simpara>
-		    <simpara>
-			The function tries to verify user's credentials. It returns 1 if they are
-			correct and -1 if not.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			I'm new to &ser; and would like to set up a test lab with a couple different
-			ip phones / adapters to learn from. Could someone recommend a few devices
-			that we could use for that purpose?
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			Hardphones: Grandstream, Cisco, ATA, Mitel, Pingtel, Snom
-		    </simpara>
-		    <simpara>
-			Softphones: kphone, Xten, Windows Messenger, Hotsip client.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			how can i configure my ser for multiple domains?
-			For example [email protected] and [email protected] on the same server?
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			If you are using 0.8.10, it is a manual process--copy and paste
-			<acronym>SQL</acronym> tables, have a table set for each served domain, and
-			refer to the table names from your scripts. E.g.,
-		    </simpara>
-		    <simpara>
-			if (uri=~"domain1.com") { lookup("domain1"); ...
-		    </simpara>
-		    <simpara>
-			With 0.8.11 you can automate the process quite a lot. Authorization
-			functions with realm set to empty value take domain name from &sip;
-			requests. User location database keeps track of domains as well. The
-			<quote>domain</quote> modules allows you to keep track of maintained domains
-			in a way which does not take changing scripts.
-		    </simpara>
-		    <simpara>
-			It is possible there are some magic options in domain/usrloc/auth_db/
-			registrar/auth modules you need to turn on to enable multidomain
-			operation--I don't remember these by heart, hopefuly some people
-			on the mailing list do.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			I am testing &ser; version 0.8.11pre29 with two <acronym>MSN</acronym>
-			Messenger(v4.6) clients. I tried to send the following MESSAGE through &ser;
-			with record-route header added by &ser;. However, the receiving
-			<acronym>MSN</acronym> client responded with a 400 Bad Request for that
-			message.
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			It's <acronym>MSN</acronym> Messenger's bug--lr parameter is not
-			recognized as specified in &rfc3261;. Use
-		    </simpara>
-		    <simpara>
-			modparam(<quote>rr</quote>, <quote>enable_full_lr</quote>, 1)
-		    </simpara>
-		    <simpara>
-			in ser config file to make it working.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			I have got an H.323 Mediatrix <acronym>FXO</acronym> gateway. It is not &sip;
-			based. May I use it with &ser; ?
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			No.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			It is possible to process the voicemail request on the same instance I use to
-			forward/register users ?
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			Yes.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			How can I checkout the sources from the <acronym>CVS</acronym> ?
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			FIXME.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			Are there any binary packages available ?
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			FIXME.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			What is symmetric signaling ?
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			FIXME.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			What is &sip;, <acronym>SIMPLE</acronym>, &sdp;, Proxy, Registrar, Redirect server ?
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			FIXME.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <simpara>
-			&ser; starts normally with the default <filename>ser.cfg</filename>. When I
-			uncommented the line load module
-			<quote>/usr/local/lib/ser/modules/mysql.so</quote> to load mysql.so,
-			everything seems normally. But actually, ser stops abnormally.
-		    </simpara>
-		</question>
-		<answer>
-		    <simpara>
-			mysql module is excluded from compilation/installation by default
-			(dependencies issue). You can compile it separately with: make modules
-			modules=modules/mysql. Also, you can add it in the list of the default
-			compiled modules with: make all include_modules=<quote>mysql</quote>.  Then
-			use: make install include_modules=<quote>mysql</quote>. To install only the
-			modules: make install-modules include_modules=<quote>mysql</quote> or only
-			the mysql module: make install-modules modules=modules/mysql.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-
-	    <qandaentry>
-		<question>
-		    <simpara>
-			Is ser compatible with MySQL 4.x ?
-		</simpara>
-		</question>
-		<answer>
-		    <simpara>
-			Yes.
-		    </simpara>
-		</answer>
-	    </qandaentry>
-
-	</qandaset>
-    </chapter>
-</book>

doc/serfaq/serfaq.xml

@@ -0,0 +1,1620 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4//EN"
+                      "file:///usr/share/sgml/docbook/dtd/xml/4/docbookx.dtd">
+
+<section id="serfaq" xmlns:xi="http://www.w3.org/2001/XInclude">
+    <sectioninfo>
+	<authorgroup>
+	    <editor>
+		<firstname>Jan</firstname>
+		<surname>Janak</surname>
+		<email>[email protected]</email>
+	    </editor>
+	</authorgroup>
+	<revhistory>
+	    <revision>
+		<revnumber>$Revision$</revnumber>
+		<date>$Date$</date>
+	    </revision>
+	</revhistory>
+	<abstract>
+	    <para>
+		A compilation of questions and answers from <email>[email protected]</email>,
+		<email>[email protected]</email>, and <email>[email protected]</email> mailing
+		lists.
+	    </para>
+	</abstract>
+	<copyright>
+	    <year>2003</year>
+	    <holder>FhG FOKUS</holder>
+	</copyright>
+    </sectioninfo>
+    
+    <title>Frequently Asked Questions</title>
+
+    <qandaset>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    Is it possible to use SER as a SIP user agent (both of User
+		    Agent Client (UAC) and User Agent Server (UASS)?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    Not easily. SER has built-in some functions that allow to
+		    use it as user agent, but our primary goal is to develop a
+		    server so this is without guarantee and can even disappear
+		    in future versions.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    Can SER work well together with some of the location server
+		    (e. g.LDAP or DNS) ?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    SER's built-in location server uses
+		    in-<acronym>RAM</acronym> database for high performance and
+		    optionally MySQL for persistence. More database protocols
+		    may be supplied on contractual basis. As far as I know,
+		    <acronym>DNS</acronym> is not used in the industry for user
+		    location.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    What is a proxy server ?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    A proxy server is an entity that routes SIP messages. See
+		    SIP introduction which is part of the distribution.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		What is the difference between proxy server and back to back
+		user agent (B2BUA) ?
+	    </question>
+	    <answer>
+		<simpara>
+		    The main difference is that proxy servers are
+		    transaction-stateful, while B2BUAs are call stateful. That
+		    means proxy servers keep state only during SIP transactions
+		    (that is at the beginning and and of a call) and do not
+		    keep any state during the whole call.
+		</simpara>
+		<simpara>
+		    A B2BUA acts merely as connection of two or more user
+		    agents which are connected through some means. B2BUAs keep
+		    some state (usually some structures in the memory) during
+		    the whole call.
+		</simpara>
+		<para>
+		    This property gives B2BUA some interesting features that
+		    proxies don't have. For example B2BUA can tear down and
+		    existing call--proxies can't do that. On the other hand
+		    B2BUAs can easily become a bottleneck in terms of
+		    scalability.
+		</para>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    So is SER proxy or B2BUA ? Can it terminate an existing
+		    call ?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    SER is a proxy. I can't terminate existing call.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    I'd like to know if SER supports <acronym>CPL</acronym> and
+		    servlets. Where can I find any documentation about this, or
+		    any link ?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    Yes, <acronym>CPL</acronym> is supported through cpl
+		    module, the module needs an external <acronym>CPL</acronym>
+		    interpreter written in Java. A C version is under
+		    development. There is no support for Java servlets. The
+		    documentation can be found at <ulink
+		    url="http://iptel.org/ser/doc">http://iptel.org/ser/doc</ulink>.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    I wanted to know whether &lt;PUT_YOUR_FAVOURITE_METHOD_HERE&gt; is supported
+		    by SER.
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    Proxy server are indifferent of non-INVITEs methods. &lt;METHOD&gt; works as
+		    good as BYE, INFO, and FOOBAR.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    I was wondering if SER has been tested and is supported on FreeBSD ?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    Yes.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    Does SER support <acronym>TCP</acronym> ?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    Yes.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    I think I found a bug that should be fixed, what information should I send
+		    and where should I send it?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    Please send us as much info as possible. We would like see the following:
+		</simpara>
+		<itemizedlist>
+		    <listitem>
+			<simpara>SER version (ser -V).</simpara>
+		    </listitem>
+		</itemizedlist>
+		<itemizedlist>
+		    <listitem>
+			<simpara>Configuration file.</simpara>
+		    </listitem>
+		</itemizedlist>
+		<itemizedlist>
+		    <listitem>
+			<simpara>SIP message dumps.</simpara>
+		    </listitem>
+		</itemizedlist>
+		<itemizedlist>
+		    <listitem>
+			<simpara>Coredump (if any, if not please generate it).</simpara>
+		    </listitem>
+		</itemizedlist>
+		<itemizedlist>
+		    <listitem>
+			<simpara>Anything else you think might help us.</simpara>
+		    </listitem>
+		</itemizedlist>
+		<itemizedlist>
+		    <listitem>
+			<simpara>The whole compiled source tree.</simpara>
+		    </listitem>
+		</itemizedlist>
+		<simpara>
+		    Please send it to <email>[email protected]</email>.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    How does SER scale ?
+		</simpara>
+		<simpara>
+		    SER is able to handle thousands calls per second on a regular
+		    <acronym>PC</acronym>.
+		</simpara>
+	    </question>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    I read <quote>Throughput thousands of calls per second
+			(<acronym>CPS</acronym>) on a dual-<acronym>CPU</acronym>
+			<acronym>PC</acronym></quote> on your webpage. How fast is it really ?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    Last time we have  checked ~4900cps on a dual Athlon MP2000.
+		</simpara>
+		<simpara>
+		    This was ser 0.8.9 running statefully (stateless is should be much faster),
+		    with 4 processes and 256 Mb shared mem.  It was compiled with: STATS:Off,
+		    USE_IPV6, NO_DEBUG, SHM_MEM, SHM_MMAP, PKG_MALLOC, F_MALLOC,
+		    FAST_LOCK-ADAPTIVE_WAIT ADAPTIVE_WAIT_LOOPS=1024, MAX_RECV_BUFFER_SIZE
+		    262144, MAX_LISTEN 16, MAX_URI_SIZE 1024, BUF_SIZE 3040
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    Do you think that SER is suitable for a commercial environment in your opinion ?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    Sure.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    Do you have any recommendations on additional open source or developer
+		    community resources to round out my platform?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    I'm a SER believer and think that other servers simply don't compare :) If
+		    you wish more detailed propaganda, check our website and if that is not
+		    enough I will send you some more.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    Do you have any thoughts on how it compares in
+		    deployability and features to the Vovida stuff or other
+		    options ? Also, are there any issues I should be thinking
+		    of that would make a commercial venture with SER difficult
+		    (licensing, scaling, etc..)
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    SER is licensed under the GNU GPL. I would be surprised if
+		    any SIP server available today would scale a bit better--we
+		    spent lot of work on performance, achieved thousands of
+		    <acronym>CPS</acronym> on a <acronym>PC</acronym>--I guess
+		    it will take lot of time until your demand hits this
+		    capacity.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    Does SER have the capability to automatically send an
+		    INVITE from one number to another?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    Yes if the phones support REFER. There is an application
+		    called Click-To-Dial which can connect two phones.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    Is it necessary to have a <acronym>DNS SVR</acronym> Resource Record, as
+		    mentioned in the ser-Howto guide for connecting to SER ?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    No. It's nice to have it, but you can work around it
+		    setting a normal A record for your domain. The
+		    <acronym>SRV</acronym> lookup will fall back to normal A
+		    lookup.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    What would you charge to help get us started?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    See <ulink url="http://iptel.org/support">http://iptel.org/support</ulink>.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    Are you going to provide integration support from SIP to H.323 and vice
+		    versa ?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    No, we are not going to provide the integration.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    I've gone thru the SER Admin's Guide and the module documentation
+		    (sip_router/modules/). Is there additional documentation on how to use the
+		    modules?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    Each module has a doc subdirectory which contains complete documentation of
+		    the module in docbook format. <acronym>PS</acronym>, <acronym>PDF</acronym>
+		    and <acronym>HTML</acronym> renderings can be obtained through our web page,
+		    see <ulink url="http://iptel.org/ser/doc">http://iptel.org/ser/doc</ulink>.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    What functions would I use in my ser.cfg to log <quote>missed calls</quote>?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    FIXME.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    Are there some additional requirements for using the acc.so module?  Radius?
+		    I want to be able to view dialed calls from serweb.
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    FIXME.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    Do you have any example configs that use nathelper?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    FIXME.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    Who are the people behind SER ?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    FIXME.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    How successful has nathelper been with <acronym>NAT</acronym>/firewall transversal?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    I only know that users reported success with nathelper and ATAs.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    Does ser support <acronym>LDAP</acronym> ?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    FIXME.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    Is it possible to get access to iptel's working copy of ser.cfg?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    We no longer disclose our operational policy to the public audience. The
+		    configuration file is only available to our customers under <acronym>NDA</acronym>.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    Can you send me detail for me to sign up for the commercial program. I would
+		    also like detail on your levels of support you offer (ie...paid support)?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    See <ulink
+			url="http://iptel.org/support/">http://iptel.org/support/</ulink>. Don't
+		    hesitate to approach us if you have any further questions.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    I need a method to determine if a called URI has an account on the system.
+		    I found a function in the groups module,
+		    <function>is_user_in</function>. but haven't yet figured out how to use it.
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    The uri module's <function>does_uri_exist</function> is what you are seeking.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    We have a question regarding usrloc: where are the active sessions
+		    being stored? We were not able to find any entries in MySQL.
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    SER has no notion of active session. SER is a
+		    transaction-stateful proxy, that means it knows about
+		    transactions (INVITE transaction, BYE transaction), but it
+		    keeps no state if there is no transaction active.
+		</simpara>
+		<simpara>
+		    That means, it keeps state when an INVITE comes and until a
+		    final response to the INVITE is sent. The same for BYE.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    Has the timeout for re-registering at the UA to be the same as in the tm
+		    module mentioned in <filename>ser.cfg</filename> ?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    No.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    How do we deal with aliases? If for example uid=mic is
+		    authenticated, he is available with sip address
+		    sip:[email protected]. If I would want to be addressable with
+		    [email protected] how is this accomplished with ser
+		    ?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    Aliases are tied to user location. It uses a special table
+		    which has the same structure as user location table and
+		    includes an entry for each alias. You do not have to do
+		    something special for that. You have to create this table
+		    and then you can use serctl to add aliases.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    I would like to know if SER supports <acronym>IPv6</acronym>. If not, do
+		    you have any plans for it ? When ?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    Yes, SER supports <acronym>IPv6</acronym>.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    Is there any way to change the default log file to a special SER.log file ?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    Try logging to stderr and redirecting it to a file:
+		</simpara>
+		<screen format="linespecific">
+		    ser -E     2>/tmp/ser.log
+		</screen>
+		<simpara>
+		    (by default ser logs to syslog)
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    Does anybody know anything about the P-Hint Header Field added from SER?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    <ulink url="http://www.iptel.org/ser/doc/seruser-html/c638.html#AEN729">
+			http://www.iptel.org/ser/doc/seruser-html/c638.html#AEN729
+		    </ulink>
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    When using the Jabber Gateway, some users get the following
+		    error from time to time:
+		</simpara>
+		<simpara>
+		    ERROR: Connection to Jabber server lost. You have to login
+		    to Jabber server again (join again the conferences that you
+		    were participating, too).
+		</simpara>
+		<simpara>
+		    sip_to_jabber_gateway says:
+		</simpara>
+		<simpara>
+		    INFO: Your are now offline in Jabber network. Thank you for
+		    using SIP-Jabber gateway.
+		</simpara>
+		<simpara>
+		    Do you know the reason why these messages appear and if it
+		    is possible to avoid them?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    that usually occurs because Jabber server crashes or, for
+		    some unknown reasons, the <acronym>TCP</acronym> connection
+		    with jabber server is down. The second message is to inform
+		    the users that they are no more connected to Jabber
+		    network.
+		</simpara>
+		<simpara>
+		    There is no way to disable sending these messages. I may
+		    introduce a new parameter to enable/disable them. But I am
+		    not sure it is a good idea (users must be informed about
+		    the changes of the status).
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    I would like know if SER support also the transmission protocol
+		    <acronym>TCP</acronym>, or <acronym>TLS</acronym>.
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    Yes, SER supports <acronym>TCP</acronym>. <acronym>TLS</acronym> is work
+		    in progress.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    I'm trying to rewrite the to domain, as in:
+		</simpara>
+		<simpara>
+		    To: &lt;sip:[email protected]&gt; ;user=phone.
+		</simpara>
+		<simpara>
+		    I can't find any rewrite* function to rewrite the
+		    to domain.
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    The proxy is not supposed to touch To or From URIs. Only Request-URI can
+		    be changed.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    When the messenger sends a message for the jabber gateway the following
+		    error occurs:
+		</simpara>
+		<simpara>
+		    <quote>ERROR: Your message was not sent. You do not have permissions to use the
+			gateway.</quote>
+		</simpara>
+		<simpara>
+		    What could be the problem here?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    You have to create the database for SIMPLE2Jabber gateway and after that you
+		    have to associate SIP users with Jabber IDs.
+		</simpara>
+		<simpara>
+		    <ulink
+			url="http://www.iptel.org/ser/doc/jabgw/xjab-manual.html#5._Admins_guide">
+			http://www.iptel.org/ser/doc/jabgw/xjab-manual.html#5._Admins_guide
+		    </ulink>
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    Authentication doesn't work!!!  Where am I wrong?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    Windows Messenger needs same string both realm and
+		    SIP_DOMAIN, and it wants to reach this address oh your
+		    network.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    I was wondering whether there is a ser module for
+		    <acronym>SIP-CGI</acronym>. Or whether there are attempts
+		    at creating one?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    There is no <acronym>SIP-CGI</acronym> module for SER. The
+		    most similar, though much simpler, functionality is
+		    provided by the exec module.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    How could I integrate SIP and H323 together?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    You will need a SIP to H.323 gateway. SER is a SIP proxy
+		    only, it cannot act as H.323 gateway.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    How can I contribute code ?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    FIXME.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    What, if anything, should the SER server do with a OPTIONS
+		    method?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    FIXME.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    What should I do to see the detailed debugs?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    Set debug=9 in your config script.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    Is it possible for SER to forward a call to another phone
+		    if the recipient does not answer?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    This could be achieved with sequential forking (by trying
+		    contacts in decreasing q order), but sequential forking is
+		    not yet supported in SER.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    Is it possible to configure SER so that it only has the
+		    latest registration?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    FIXME.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    mkdir: cannot create directory `/usr/local/etc/ser': Permission denied
+		    make: *** [/usr/local/etc/ser] Error 1
+		</simpara>
+		<simpara>
+		    what may be the error ?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    You have no write permissions to the directory, try it again as root.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    Can a proxy terminate a call ?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    No, proxy cannot do that because it is transaction stateful only.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    i want to know what accounting support is available using
+		    MySql. what settings need to be done? are any records
+		    generated and placed in the database? how do i access these
+		    records?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    FIXME.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    It seems that SER supports only strict routing. Please tell
+		    me if it supports loose routing. if yes, do i have to
+		    enable it somehow?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    Yes, it does support loose routing as of 0.8.11, you don't have to enable it.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    I need to know if currently generated call records can be
+		    put into MySql database. if yes, is there any tool
+		    available to view these records?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    Serweb can do it.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    If I want to use SER commercially do I need to purchase any
+		    license for the same, as long as I'm not going to charge
+		    the customer for the SIP service but only for the
+		    termination of calls.
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    SER is distributed under the GPL so you don't need to purchase any
+		    license, you can use it freely.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    Is there a support for accounting ?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    Yes, see acc module.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    What tool can I use to capture SIP traffic ?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    <ulink url="http://ngrep.sourceforge.net">ngrep</ulink>, <ulink
+			url="http://www.ethereal.com">ethereal</ulink>, <ulink
+			url="http:/www.tcpdump.org">tcpdump</ulink>.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    Is there ENUM support in SER ?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    Yes, see enum module.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    Do you have any experience (or know) where I can get some info on setting up
+		    an ENUM testbed with <acronym>DNS</acronym> and Linux?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    if by testbed you mean running your own e164.arpa root, then you simply
+		    make your dns server a root for e164.arpa domain by adding line
+		</simpara>
+		<programlisting>
+primary         e164.arpa               e164.arpa.db
+		</programlisting>
+		<simpara>
+		    into your named.boot file and then by populating file
+		    e164.arpa.db with your enum entries.  Below is an example.
+		</simpara>
+		<programlisting>
+$ORIGIN .
+$TTL 0  ; 0 seconds
+e164.arpa               IN SOA  foo.fi. hostmaster.foo.fi. (
+200204681  ; serial
+28800      ; refresh (8 hours)
+7200       ; retry (2 hours)
+604800     ; expire (1 week)
+86400      ; minimum (1 day)
+)
+NS      foo.fi.
+$ORIGIN e164.arpa.
+$ORIGIN 8.5.3.e164.arpa.
+$ORIGIN 9.3.8.1.5.6.2.8.5.3.e164.arpa.
+3.1   NAPTR   1 1 "u" "E2U+sip" "!(^.*$)!sip:[email protected]!i" .
+		</programlisting>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    Will SER support <acronym>STUN</acronym> in the future?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    <acronym>STUN</acronym> is a protocol operated separately from SER
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    Is there any way to show active calls (dialed number, duration, originating
+		    <acronym>IP</acronym>...) with SER?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    No, ser is not call stateful.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    If I'm working with RFC2543 compliant phones (such as
+		    <acronym>ATA</acronym>) may I use loose routing?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    Yes, loose routing is backwards compatible.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    How can I configure radiator for digest authentication?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    In case of radiator, you don't need to do anything special in the
+		    configuration.  Just install the latest radiator and then make sure your
+		    config can handle the service-types you have configured ser to use. For
+		    example, you can have
+		</simpara>
+		<programlisting>
+&lt;Handler Service-Type=SIP&gt;
+...
+&lt;/AuthBy&gt;
+		</programlisting>
+		<simpara>
+		    Or whatever your strategy is.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    How can I configure radiator for digest authentication?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    see freeradius-0.8.1/doc/rlm_digest
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    Trying to create alias, I am getting the following message:
+		</simpara>
+		<simpara>
+		    <quote>400 Table 'aliases' Not Found</quote>
+		</simpara>
+
+	    </question>
+	    <answer>
+		<simpara>
+		    You must have lookup(<quote>aliases</quote>) somewhere in your script.
+		</simpara>
+	    </answer>
+	</qandaentry>
+
+	<qandaentry>
+	    <question>
+		<simpara>
+		    Also how much shared memory does SER allocate by default?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    32 Mb.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    How can I identify what ser doesn't like about the config file?
+		</simpara>
+	    </question>
+	    <answer>
+		<programlisting>
+0(612) parse error (81,1-10): syntax error
+0(612) parse error (91,1-6):
+                    ^^^^^^
+		</programlisting>
+		<simpara>
+		    These are the line number and the characters. So look in line 81 and 91 of
+		    your config file for errors.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<programlisting>
+Warning: 392 216.87.144.203:5060 "Noisy feedback tells:  pid=19604
+         req_src_ip=216.87.144.205 req_src_port=5065 in_uri=sip:addaline.com
+         out_uri=sip:addaline.com via_cnt==1".
+		</programlisting>
+		<simpara>
+		    I want to get rid of these?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    Use sip_warning=no
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    Is SER a gatekeeper ?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    No, SER is a SIP proxy.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    Is there an example of the session timer with SER somewhere?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    That's a theoretical SIP option today, SER is not supporting
+		    session-timer.  We gave it a try more than one year ago and gave up due to
+		    interop problems.  The specification was developing at that time so quickly
+		    that there was not any UA which would work with another one correctly.
+		</simpara>
+		<simpara>
+		    Once the interoperability gets better, it could be worth implementing. It is
+		    in general a nice mechanism for avoiding session state silo in network,
+		    which is good for scalability.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    Could someone point me where I can read about this www_authorize()
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    The documentation is in sip_router/modules/auth_db/doc
+		</simpara>
+		<simpara>
+		    The function tries to verify user's credentials. It returns 1 if they are
+		    correct and -1 if not.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    I'm new to SER and would like to set up a test lab with a couple different
+		    ip phones / adapters to learn from. Could someone recommend a few devices
+		    that we could use for that purpose?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    Hardphones: Grandstream, Cisco, ATA, Mitel, Pingtel, Snom
+		</simpara>
+		<simpara>
+		    Softphones: kphone, Xten, Windows Messenger, Hotsip client.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    how can i configure my ser for multiple domains?
+		    For example [email protected] and [email protected] on the same server?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    If you are using 0.8.10, it is a manual process--copy and paste
+		    <acronym>SQL</acronym> tables, have a table set for each served domain, and
+		    refer to the table names from your scripts. E.g.,
+		</simpara>
+		<simpara>
+		    if (uri=~"domain1.com") { lookup("domain1"); ...
+		</simpara>
+		<simpara>
+		    With 0.8.11 you can automate the process quite a lot. Authorization
+		    functions with realm set to empty value take domain name from SIP
+		    requests. User location database keeps track of domains as well. The
+		    "domain" modules allows you to keep track of maintained domains
+		    in a way which does not take changing scripts.
+		</simpara>
+		<simpara>
+		    It is possible there are some magic options in domain/usrloc/auth_db/
+		    registrar/auth modules you need to turn on to enable multidomain
+		    operation--I don't remember these by heart, hopefuly some people
+		    on the mailing list do.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    I am testing SER version 0.8.11pre29 with two <acronym>MSN</acronym>
+		    Messenger(v4.6) clients. I tried to send the following MESSAGE through SER
+		    with record-route header added by SER. However, the receiving
+		    <acronym>MSN</acronym> client responded with a 400 Bad Request for that
+		    message.
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    It's <acronym>MSN</acronym> Messenger's bug--lr parameter is not
+		    recognized as specified in RFC3261. Use
+		</simpara>
+		<simpara>
+		    modparam("rr", "enable_full_lr", 1)
+		</simpara>
+		<simpara>
+		    in ser config file to make it working.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    I have got an H.323 Mediatrix <acronym>FXO</acronym> gateway. It is not SIP
+		    based. May I use it with SER ?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    No.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    It is possible to process the voicemail request on the same instance I use to
+		    forward/register users ?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    Yes.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    How can I checkout the sources from the <acronym>CVS</acronym> ?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    FIXME.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    Are there any binary packages available ?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    FIXME.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    What is symmetric signaling ?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    FIXME.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    What is SIP, <acronym>SIMPLE</acronym>, SDP, Proxy, Registrar, Redirect server ?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    FIXME.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    SER starts normally with the default <filename>ser.cfg</filename>. When I
+		    uncommented the line load module
+		    "/usr/local/lib/ser/modules/mysql.so" to load mysql.so,
+		    everything seems normally. But actually, ser stops abnormally.
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    mysql module is excluded from compilation/installation by default
+		    (dependencies issue). You can compile it separately with: make modules
+		    modules=modules/mysql. Also, you can add it in the list of the default
+		    compiled modules with: make all include_modules="mysql".  Then
+		    use: make install include_modules="mysql". To install only the
+		    modules: make install-modules include_modules="mysql" or only
+		    the mysql module: make install-modules modules=modules/mysql.
+		</simpara>
+	    </answer>
+	</qandaentry>
+
+	<qandaentry>
+	    <question>
+		<simpara>
+		    Is ser compatible with MySQL 4.x ?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    Yes.
+		</simpara>
+	    </answer>
+	</qandaentry>
+
+	<qandaentry>
+	    <question>
+		<simpara>
+		    Is the SIP Express Router (SER) free ? Or do we need to pay ? Because my boss worry
+		    about that, please help me.
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    Yes, it is free. See
+		    <ulink url="http://cvs.berlios.de/cgi-bin/viewcvs.cgi/*checkout*/ser/sip_router/COPYING?rev=HEAD&amp;content-type=text/plain">
+			http://cvs.berlios.de/cgi-bin/viewcvs.cgi/*checkout*/ser/sip_router/COPYING?rev=HEAD&amp;content-type=text/plain
+		    </ulink>
+		</simpara>
+	    </answer>
+	</qandaentry>
+
+	<qandaentry>
+	    <question>
+		<simpara>
+		    Mar 10 16:46:33 ttalksvr /usr/sbin/ser[6592]: connect_db(): Can't connect to
+		    local MySQL server through socket '/var/lib/mysql/mysql.sock' (2)
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    Make sure your MySQL server is running.
+		</simpara>
+	    </answer>
+	</qandaentry>
+
+	<qandaentry>
+	    <question>
+		<simpara>
+		    I get the following error:
+		</simpara>
+		<screen>
+0(5164) db_init(): Error while trying to connect database
+0(5164) mod_init(): Error while connecting database
+0(5164) init_modules(): Error while initializing module usrloc
+</screen>
+		<simpara>
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    Modules using database have variable called db_url which contains username,
+		    password, hostname, and name of the database. Make sure the settings are
+		    correct. See module documentation for more information.
+		</simpara>
+	    </answer>
+	</qandaentry>
+
+	<qandaentry>
+	    <question>
+		<simpara>
+		    Does MySQL/Postgres/Whatever have to reside on localhost?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    No.
+		    </simpara>
+	    </answer>
+	</qandaentry>
+
+	<qandaentry>
+	    <question>
+		<simpara>
+		    Why do I need a database ?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    Many modules need the database. Authentication modules retrieve users'
+		    credentials from the database, user location module can be configured to store
+		    registered bindings into the database, accounting module can use database to
+		    store CDR and so on.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    Which database engines are supported ?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    Currently we support MySQL, Postgres and plaintext files.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	
+	<qandaentry>
+	    <question>
+		<simpara>
+		    Which database engine should I use ?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    That depends on your requirements. Performance aspects are probably not very
+		    important. The most stable and proven is MySQL module. Also serctl utility works
+		    well with this database.
+		</simpara>
+		<simpara>
+		    Another option is postgres support which was donated by Greg Fausak. The module
+		    still new and not that mature (read proven) yet. People using the module
+		    reported that it worked well.
+		</simpara>
+		<simpara>
+		    Last option is dbtext module which uses plaintext files to store the data. This
+		    module is somewhat experimental and shouldn't be used for any serious
+		    deployment. The module is quite slow, but it can fit well into small
+		    installations containing only a couple of users or demos where you need to change
+		    the content of the database often by hand.
+		</simpara>
+	    </answer>
+	</qandaentry>
+
+	<qandaentry>
+	    <question>
+		<simpara>
+		    Is there <quote>send IM</quote> page for sending instant messages only or does
+		    it accept replies as well (i.e. does it act like a full UA) ?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    It can send messages only.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	
+	<qandaentry>
+	    <question>
+		<simpara>
+		    I have serweb running. I'm able to connect to <acronym>MySQL</acronym> fine. But
+		    it doesn't seem like the form params are getting assigned to variables. Is there
+		    something obvious I'm missing?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    Please check if <varname>register_globals</varname> is set to On in your
+		    <filename>php.ini</filename> file. The option is set off by default due to
+		    security reasons.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	
+	<qandaentry>
+	    <question>
+		<simpara>
+		    Can somebody tell me how to configure the serweb? Which directory should I put
+		    those files and which file and parameters should I modify. Or maybe this
+		    question was asked previously by somebody already, then please provide me a like
+		    to those answers.
+		</simpara>
+	</question>
+	    <answer>
+		<simpara>
+		    Dan Austin's HOWTO (see SER webpage) is probably the currently most extensive
+		    documentation available.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	
+	<qandaentry>
+	    <question>
+		<simpara>
+		    Trying to load the serweb page I get the following error message: Fatal error:
+		    Call to undefined function: mysql_pconnect() in
+		    /var/www/html/phplib/db_mysql.inc on line 73
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    Configure <acronym>PHP</acronym> to load the MySQL extension.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	
+	<qandaentry>
+	    <question>
+		<simpara>
+		    I can open the page and even make changes and save them, but I'm receiving the
+		    following warning message: Warning: fopen("/tmp/ser_fifo",
+		    "w") ? Permission denied in /var/www/html/serweb/functions.php on
+		    line 172 Sorry - cannot open fifo.
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    Make sure that the user under which the web server is running has read and write
+		    access to the <acronym>FIFO</acronym>.
+		</simpara>
+	    </answer>
+	</qandaentry>
+    
+	<qandaentry>
+	    <question>
+		<simpara>
+		    Is there a way to add/edit/view aliases from serweb?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    When new user confirm registration, new numeric alias is created. There is no
+		    another way to add or edit aliases from serweb.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	
+	<qandaentry>
+	    <question>
+		<simpara>
+		    I am getting a "Forbidden" reply from the Apache. The Apache is
+		    pointing to the index.php for the serweb. I've only changed the IP address of
+		    the local host to 127.0.0.1 in the config.php. Does anyone have any suggestions
+		    ?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    Check if the file/folder has read permission for everybody.
+		</simpara>
+	    </answer>
+	</qandaentry>
+
+	<qandaentry>
+	    <question>
+		<simpara>
+		    I get following warnings and error on NetBSD when I call
+		    user_interface/index.php:
+		    </simpara>
+		<simpara>
+		    [Wed Jul 16 09:56:53 2003] [error] PHP Warning: Call-time pass-by-reference has
+		    been deprecated - argument passed by value; If you would like to pass it by
+		    reference, modify the declaration of [runtime function name]().  If you would
+		    like to enable call-time pass-by-reference, you can set
+		    allow_call_time_pass_reference to true in your INI file.  However, future
+		    versions may not support this any longer.  in
+		    /usr/pkg/share/httpd/htdocs/iptel/phplib/user.inc on line 72 [Wed Jul 16
+		    09:56:53 2003] [error] PHP Fatal error: Call to undefined function:
+		    mysql_pconnect() in /usr/pkg/share/httpd/htdocs/iptel/phplib/db_mysql.inc on
+		    line 73
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    Simply do what the text says: enable allow_call_time_pass_reference in
+		    <filename>/usr/pkg/etc/php.ini</filename> and install <acronym>PHP</acronym>
+		    MySQL support.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	
+	<qandaentry>
+	    <question>
+		<simpara>
+		    I started the webserver and got the following message: Starting up of httpd:
+		    [Thu Aug 14 15:16:51 2003] alert ] httpd: Could not determine the of server
+		    fully qualified domain name, using 127.0.0.1 for ServerName 
+		</simpara>
+		<simpara>
+		    Does anyone know where is the problem ?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    Set ServerName variable in the configuration file of your webserver to hostname
+		    of your computer.
+		</simpara>
+	    </answer>
+	</qandaentry>
+	<qandaentry>
+	    <question>
+		<simpara>
+		    What version of ser should I use with serweb from the CVS ?
+		</simpara>
+	    </question>
+	    <answer>
+		<simpara>
+		    CVS version of serweb is aligned to the stable branch of ser. It will not work
+		    with ser 0.8.10 because the database tables have been changed recently.
+		</simpara>
+	    </answer>
+	</qandaentry>
+
+    </qandaset>
+</section>
+

doc/serhowto/Makefile

@@ -0,0 +1,29 @@
+#
+# The list of documents to build (without extensions)
+#
+DOCUMENTS = ser-howto
+
+#
+# The root directory containing Makefile.doc
+#
+ROOT_DIR=../..
+
+#
+# Validate docbook documents before generating output
+# (may be slow)
+#
+#VALIDATE=1
+
+#
+# You can override the stylesheet used to generate
+# xhtml documents here
+#
+#XHTML_XSL=$(ROOT_DIR)/doc/stylesheets/xhtml.xsl
+
+#
+# You can override the stylesheet used to generate
+# plain text documents here
+#
+#TXT_XSL=$(XHTML_XSL)
+
+include $(ROOT_DIR)/Makefile.doc

doc/seruser/Makefile

@@ -0,0 +1,29 @@
+#
+# The list of documents to build (without extensions)
+#
+DOCUMENTS = seruser
+
+#
+# The root directory containing Makefile.doc
+#
+ROOT_DIR=../..
+
+#
+# Validate docbook documents before generating output
+# (may be slow)
+#
+#VALIDATE=1
+
+#
+# You can override the stylesheet used to generate
+# xhtml documents here
+#
+#XHTML_XSL=$(ROOT_DIR)/doc/stylesheets/xhtml.xsl
+
+#
+# You can override the stylesheet used to generate
+# plain text documents here
+#
+#TXT_XSL=$(XHTML_XSL)
+
+include $(ROOT_DIR)/Makefile.doc

doc/seruser/apps.sgml → doc/seruser/apps.xml

@@ -1,47 +1,61 @@
-    <chapter>
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4//EN"
+                      "file:///usr/share/sgml/docbook/dtd/xml/4/docbookx.dtd">
+
+<section id="application_writing" xmlns:xi="http://www.w3.org/2001/XInclude">
+    <sectioninfo>
+	<revhistory>
+	    <revision>
+		<revnumber>$Revision$</revnumber>
+		<date>$Date$</date>
+	    </revision>
+	</revhistory>
+    </sectioninfo>
+
+    <section>
 	<title>Application Writing</title>
 	<para>
-	    <application moreinfo="none">ser</application> offers several
+	    <application>ser</application> offers several
 	    ways to couple its functionality with applications. The coupling
-	    is bidirectional: <application moreinfo="none">ser</application>
+	    is bidirectional: <application>ser</application>
 	    can utilize external applications and external applications can
-	    utilize <application moreinfo="none">ser</application>. 
+	    utilize <application>ser</application>. 
 	    An example of the former direction would be an external program
 	    determining a least-cost route for a called destination  using 
 	    a pricing table. An example of the latter case
 	    is a web application for server provisioning.
 	    Such an application may want to send instant 
 	    messages, query all current user's locations and monitor server
-	    health. An existing web interface to <application moreinfo="none">ser</application>,
-	    <application moreinfo="none">serweb</application>, actually
+	    health. An existing web interface to <application>ser</application>,
+	    <application>serweb</application>, actually
 	    does all of it. 
 	</para>
 	<para>
 	    The easiest, language-independent way of using external logic 
-	    from <application moreinfo="none">ser</application> is provided
-	    by exec module. exec module allows <application moreinfo="none">ser</application>
+	    from <application>ser</application> is provided
+	    by exec module. exec module allows <application>ser</application>
 	    to start external programs on receipt of a request. The
 	    programs can execute arbitrary logic and/or affect routing of SIP
 	    requests. A great benefit of this programming method is it
 	    is language-independent. Programmers may use programming languages
 	    that are effective or with which they are best familiar.
-	    <xref linkend="usingexec"> gives additional examples illustrating 
+	    <xref linkend="usingexec"/> gives additional examples illustrating 
 	    use of the exec module.
 	</para>
 	<para>
-	    Another method for extending <application moreinfo="none">ser</application>
+	    Another method for extending <application>ser</application>
 	    capabilities is to write new modules in C. This method takes
-	    deeper understanding of <application moreinfo="none">ser</application>
+	    deeper understanding of <application>ser</application>
 	    internals but gains the highest flexibility. Modules can implement
-	    arbitrary brand-new commands upon which <application moreinfo="none">ser</application>
+	    arbitrary brand-new commands upon which <application>ser</application>
 	    scripts can rely on. Guidelines on module programming can be
-	    found in <application moreinfo="none">ser</application>
+	    found in <application>ser</application>
 	    programmer's handbook available from iptel.org website.
 	</para>
 	<para>
 	    To address needs of applications wishing to leverage
-	    <application moreinfo="none">ser</application>,
-	    <application moreinfo="none">ser</application> exports
+	    <application>ser</application>,
+	    <application>ser</application> exports
 	    parts of its functionality via its built-in
 	    "Application FIFO server". This is a simple textual
 	    interface that allows any external applications
@@ -50,29 +64,24 @@
 	    watch server health, etc. Programs written in any
 	    language (PHP, shell scripts, Perl, C, etc.) can
 	    utilize this feature. How to use it is shown in
-	    <xref linkend="fifoserver">.
+	    <xref linkend="fifoserver"/>.
 	</para>
 
-
 	<section id="usingexec">
 	    <title>Using exec Module</title>
 	    <para>
 		
-		The easiest way is to couple <application moreinfo="none">ser</application>
+		The easiest way is to couple <application>ser</application>
 		with external applications via the <emphasis>exec</emphasis>
 		module. This module allows execution of logic and URI manipulation 
 		by external applications on request receipt. While very
 		simple, many useful services can be
 		implemented this way. External applications can be written in
 		any programming language and do not be aware of SIP at all.
-		<application moreinfo="none">ser</application> interacts with
+		<application>ser</application> interacts with
 		the application via standard input/output and environment 
 		variables.
-		
-
 	    </para>
-	
-
 	    <para>
 		For example, an external shell script
 		may send an email whenever a request for a user arrives.
@@ -80,7 +89,7 @@
 
 	    <example>
 		<title>Using exec: Step 1</title>
-		<programlisting format="linespecific">
+		<programlisting>
 # send email if a request for user "jiri" arrives
 if (uri=~"^sip:jiri@") {
      exec_msg("echo 'body: call arrived'|mail -s 'call for you' jiri");
@@ -88,7 +97,7 @@ if (uri=~"^sip:jiri@") {
 		</programlisting>
 	    </example> <!-- step 1 -->
 	    <para>
-		In this example, the <command moreinfo="none">exec_msg</command> 
+		In this example, the <command>exec_msg</command> 
 		action starts an external shell. It passes a received SIP request
 		to shell's input. In the shell, <command>mail</command> command
 		is called to send a notification by e-mail.
@@ -129,14 +138,13 @@ if (uri=~"^sip:jiri@") {
 		    request received on shell program's input
 		    and grep From header field.
 		</para>
-		<programlisting format="linespecific">
-&execstep2;
+		<programlisting>
+<xi:include href="../../examples/exec_s2.cfg" parse="text"/>
 		</programlisting>
 		<para>
 			The following two figures show an example SIP request and
 			email notification generated on its receipt.
-			
-		    <screen format="linespecific">
+		    <screen>
 
 <![CDATA[
 INVITE sip:[email protected] SIP/2.0
@@ -152,12 +160,11 @@ Content-Length: 451
 
 --- SDP payload snipped ---
 ]]>
-
 		    </screen>
 		
 		    email received:
 		
-			<screen format="linespecific">
+		    <screen>
 <![CDATA[
 Date: Thu, 12 Dec 2002 14:25:02 +0100
 From: root <[email protected]>
@@ -171,12 +178,12 @@ request received
 		</para>
 		<para>
 		    There is another way to learn values of request
-		    header fields, simpler than use of <command moreinfo="none">grep</command>. 
-		    <application moreinfo="none">ser</application>
+		    header fields, simpler than use of <command>grep</command>. 
+		    <application>ser</application>
 		    parses header fields and passes their values in 
 		    environment variables. Their names correspond
 		    to header field names prefixed with "SIP_HF_".
-		<programlisting format="linespecific">
+		<programlisting>
 # send email if a request for "jiri" arrives
 if (uri=~"^sip:jiri@") {
      exec_msg("echo request received from $SIP_HF_FROM | mail -s 'request for you' jiri");
@@ -192,7 +199,7 @@ if (uri=~"^sip:jiri@") {
 		    <varname>SIP_USER</varname> and <varname>SIP_OUSER</varname> username
 		    parts of these. The following listing shows environment variables
 		    passed to a shell script on receipt of the previous message:
-		    <programlisting format="linespecific">
+		    <programlisting>
 <![CDATA[
 SIP_HF_MAX_FORWARDS=10
 SIP_HF_VIA=SIP/2.0/UDP 195.37.77.100:5040
@@ -227,18 +234,18 @@ SIP_HF_CONTACT=<sip:123.20.128.35:9315>
 		    their addresses in the script. The missing piece
 		    is translation of user's SIP name to his email address.
 		    This information is maintained in subscriber profiles,
-		    stored in MySQL by <application moreinfo="none">ser</application>.
+		    stored in MySQL by <application>ser</application>.
 		    To translate the username to email address, the executed script
 		    needs to query the MySQL database. That is what this example
 		    shows. First, an SQL query is constructed which looks up
 		    email address of user, for whom a request arrived. If the
 		    query does not return a valid email address, the script
-		    returns with an error status and <application moreinfo="none">ser</application>
+		    returns with an error status and <application>ser</application>
 		    script replies with "user does not exist". Otherwise
 		    an email notification is sent.
 		
-		    <programlisting format="linespecific">
-&execstep3;
+		    <programlisting>
+<xi:include href="../../examples/exec_s3.cfg" parse="text"/>
 		    </programlisting>
 		</para>
 	    </example> <!-- step 3 make the script work for anyone -->
@@ -253,8 +260,8 @@ SIP_HF_CONTACT=<sip:123.20.128.35:9315>
 		    kept. The script does not know whether a request is
 		    a new or a retransmitted one. Transaction management may
 		    be introduced by use of tm module as described in
-		    <xref linkend="statefulua">. In the script,
-		    <command moreinfo="none">t_newtran</command> is first
+		    <xref linkend="statefulua"/>. In the script,
+		    <command>t_newtran</command> is first
 		    called to absorb requests retransmission -- if they
 		    occur, script does not continue. Then, as in the previous
 		    example, an exec module action is called. Eventually,
@@ -262,16 +269,16 @@ SIP_HF_CONTACT=<sip:123.20.128.35:9315>
 		    <note>
 			<para>
 			    Note carefully: it is important that the stateful
-			    reply processing (<command moreinfo="none">t_reply</command>)
+			    reply processing (<command>t_reply</command>)
 			    is used as opposed to using stateless replies
-			    (<command moreinfo="none">sl_send_reply</command>).
+			    (<command>sl_send_reply</command>).
 			    Otherwise, the outgoing reply would not affect
 			    transactional context and would not be resent on
 			    receipt of a request retransmission.
 			</para>
 		    </note>
-		    <programlisting format="linespecific">
-&execstep4;
+		    <programlisting>
+<xi:include href="../../examples/exec_s4.cfg" parse="text"/>
 		    </programlisting>
 		    
 		</para>
@@ -281,11 +288,11 @@ SIP_HF_CONTACT=<sip:123.20.128.35:9315>
 		<para>
 		    The last example iteration shows how to integrate the
 		    email notification on missed calls with the default
-		    <application moreinfo="none">ser</application> script
-		    (see <xref linkend="defaultscript">). It generates an
+		    <application>ser</application> script
+		    (see <xref linkend="defaultscript"/>). It generates an
 		    email for every call invitation to an off-line user.
-		    <programlisting format="linespecific">
-&execstep5;
+		    <programlisting>
+<xi:include href="../../examples/exec_s5.cfg" parse="text"/>
 		    </programlisting>
 		</para>
 		    
@@ -296,30 +303,30 @@ SIP_HF_CONTACT=<sip:123.20.128.35:9315>
 		    reported calls missed due to call cancellation,
 		    busy status or a downstream failure. Such missed
 		    calls can be easily reported to syslog or mysql
-		    using the acc module (see <xref linkend="missedcalls">).
+		    using the acc module (see <xref linkend="missedcalls"/>).
 		    The other, more general way, is to return to request
 		    processing on receipt of a negative reply.
-		    (see <xref linkend="replyprocessingsection">). Before
+		    (see <xref linkend="replyprocessingsection"/>). Before
 		    a request is forwarded, it is labeled to be
-		    re-processed in a <command moreinfo="none">failure_route</command>
+		    re-processed in a <command>failure_route</command>
 		    on receipt of a negative reply -- this is what
-		    <command moreinfo="none">t_on_failure</command> action
+		    <command>t_on_failure</command> action
 		    is used for. It does not matter what caused the transaction
 		    to fail -- it may be unresponsive downstream server,
 		    server responding with 6xx, or server sending a 487
 		    reply, because an INVITE was canceled. When any such
 		    circumstances occur (i.e., transaction does not complete
-		    with a 2xx status code), <command moreinfo="none">failure_route</command>
+		    with a 2xx status code), <command>failure_route</command>
 		    is entered.
 		</para>
 		<para>
-		    The following <application moreinfo="none">ser</application>
+		    The following <application>ser</application>
 		    script reports missed calls in all possible cases.
 		    It reports them when a user is off-line as well as when
 		    a user is on-line, but INVITE transaction does not complete
 		    successfully.
-		    <programlisting format="linespecific">
-&execstep5b;
+		    <programlisting>
+<xi:include href="../../examples/exec_s5b.cfg" parse="text"/>
 		    </programlisting>
 		</para>
 		
@@ -336,64 +343,64 @@ SIP_HF_CONTACT=<sip:123.20.128.35:9315>
 	    is it works with SIP-unaware applications
 	    written in any programming language. Textual nature of the
 	    FIFO interface allows for easy integration with a lot of
-	    existing programs. Today, <application moreinfo="none">ser</application>'s
-	    complementary web-interface, <application moreinfo="none">serweb</application>,
+	    existing programs. Today, <application>ser</application>'s
+	    complementary web-interface, <application>serweb</application>,
 	    written in PHP, leverages the FIFO interface when displaying
 	    and changing user location records stored in server's memory.
 	    It uses this interface to send instant messages too, without
 	    any knowledge of underlying <acronym>SIP</acronym> stack.
 	    Another application relying on the FIFO interface is 
-	    <application moreinfo="none">serctl</application>, <application moreinfo="none">ser</application>
+	    <application>serctl</application>, <application>ser</application>
 	    management utility. The command-line utility can browse
 	    server's in-memory user-location database, display 
 	    running processes and operational statistics.
 	    </para>
 	    <para>
 		The way the FIFO server works is similar to how 
-		<filename moreinfo="none">/proc</filename> filesystem works
+		<filename>/proc</filename> filesystem works
 		on some operating systems. It provides a human-readable way
-		to access <application moreinfo="none">ser</application>'s
+		to access <application>ser</application>'s
 		internals. Applications dump their requests into the FIFO
 		server and receive a status report when request processing
-		completes. <application moreinfo="none">ser</application>
+		completes. <application>ser</application>
 		exports a lot of its functionality located in both the
 		core and external modules through the FIFO server. 
 		</para>
 	    <para>
 		FIFO requests are formed easily. They begin with a command
 		enclosed in colons and followed by name of file or pipe (relative
-		to <filename moreinfo="none">/tmp/</filename> path), to which
+		to <filename>/tmp/</filename> path), to which
 		a reply should be printed. The first request line may be
 		followed by additional lines with command-specific 
-		parameters. For example, the <command moreinfo="none">t_uac_dlg</command>
+		parameters. For example, the <command>t_uac_dlg</command>
 		FIFO command for initiating a transaction allows 
 		to pass additional header fields and message body to
 		a newly created transaction. Each request is terminated by
 		an empty line. Whole requests must be sent by applications
 		atomically in a single batch to avoid mixing with
 		requests from other applications. Requests are sent to
-		pipe at which <application moreinfo="none">ser</application>
+		pipe at which <application>ser</application>
 		listens (filename configured by the <varname>fifo</varname> config
 		file option).
 	    </para>
 	    <para>
 		An easy way to use the FIFO interface is via the
-		<application moreinfo="none">serctl</application>
+		<application>serctl</application>
 		command-line tool. When called along with "fifo",
 		FIFO command name, and optional parameters, the tool
 		generates a FIFO request and prints request result.
 		The following example shows use of this tool with
-		the <command moreinfo="none">uptime</command> and
-		<command moreinfo="none">which</command> commands.
-		<command moreinfo="none">uptime</command> returns
-		server's running time, <command moreinfo="none">which</command>
+		the <command>uptime</command> and
+		<command>which</command> commands.
+		<command>uptime</command> returns
+		server's running time, <command>which</command>
 		returns list of available FIFO commands. Note that only
 		the built-in FIFO command set is displayed as no modules
 		were loaded in this example.
 		<example>
-		    <title>Use of <application moreinfo="none">serctl</application> 
+		    <title>Use of <application>serctl</application> 
 		    to Access FIFO Server</title>
-		    <programlisting format="linespecific">
+		    <programlisting>
 [jiri@cat test]$ serctl fifo uptime
 Now: Fri Dec  6 17:56:10 2002
 Up Since: Fri Dec  6 17:56:07 2002
@@ -407,11 +414,11 @@ uptime
 print
 		    </programlisting>
 		</example>
-		The request which the <application moreinfo="none">serctl</application>
+		The request which the <application>serctl</application>
 		command-line tool sent to FIFO server looked like this:
 		<example>
-		    <title><command moreinfo="none">uptime</command> FIFO Request</title>
-		    <programlisting format="linespecific">
+		    <title><command>uptime</command> FIFO Request</title>
+		    <programlisting>
 :uptime:ser_receiver_1114
 		    </programlisting>
 		</example>
@@ -427,7 +434,7 @@ print
 		requested.
 		<example>
 		    <title>FIFO Errors</title>
-		    <programlisting format="linespecific">
+		    <programlisting>
 [jiri@cat sip_router]$ serctl fifo foobar
 500 command 'foobar' not available
 		    </programlisting>
@@ -462,12 +469,12 @@ print
 		database and tm module exports FIFO commands for
 		management of SIP transactions. See the 
 		example in 
-		<filename moreinfo="none">examples/web_im/send_im.php</filename>
+		<filename>examples/web_im/send_im.php</filename>
 		for how to initiate a SIP transaction
 		(instant message)
 		from a PHP script via the FIFO server. This example
 		uses FIFO command 
-		<command moreinfo="none">t_uac_dlg</command>. The command
+		<command>t_uac_dlg</command>. The command
 		is followed by parameters: header fields and 
 		message body. The same FIFO command can be used from
 		other environments to send instant messages too. The
@@ -475,7 +482,7 @@ print
 		from a shell script.
 		<example>
 		    <title>Sending IM From Shell Script</title>
-		    <programlisting format="linespecific">
+		    <programlisting>
 #!/bin/sh
 #
 # call this script to send an instant message; script parameters
@@ -515,21 +522,21 @@ EOF
 		    register automatically using SIP. The user needs to set 
 		    forwarding manually through some convenient web interface.
 		    The web interface needs to have the ability to upload new user's
-		    contacts to <application moreinfo="none">ser</application>.
-		    This is what the <command moreinfo="none">ul_add</command> FIFO
+		    contacts to <application>ser</application>.
+		    This is what the <command>ul_add</command> FIFO
 		    command is good for. Parameterized by user's name, table name,
 		    expiration time and weight, it allows external applications to
 		    introduce new contacts to server's in-memory user location table.
 		</para>
 		<para>
-		    The example is borrowed from <application moreinfo="none">serweb</application>,
-		    <application moreinfo="none">ser</application>'s web 
+		    The example is borrowed from <application>serweb</application>,
+		    <application>ser</application>'s web 
 		    PHP-written interface.
 		    It consists of a short "stub" function which carries out
 		    all mechanics of FIFO communication and of forming the FIFO
 		    request.
 		</para>
-		<programlisting format="linespecific">
+		<programlisting>
 <![CDATA[
 
 /* construct and send a FIFO command; the command parameters $sip_address, 
@@ -595,9 +602,9 @@ function write2fifo($fifo_cmd, &$errors, &$status){
 	    </example>
 	    <para>
 		See
-		<xref linkend="fiforeference"> for a complete listing
+		<xref linkend="fiforeference"/> for a complete listing
 		of FIFO commands available with current 
-		<application moreinfo="none">ser</application>
+		<application>ser</application>
 		distribution.
 	    </para>
 	    <section>
@@ -631,7 +638,7 @@ function write2fifo($fifo_cmd, &$errors, &$status){
 		    The other design alternative is use of a B2BUA 
 		    <footnote>
 			<para>
-			    See <filename moreinfo="none">
+			    See <filename>
 				draft-ietf-sipping-3pcc-02.txt 
 			    </filename>  for more details.
 			</para>
@@ -678,29 +685,29 @@ function write2fifo($fifo_cmd, &$errors, &$status){
 		    <example>
 			<title>Call-Flow for Click-To-Dial Using REFER</title>
 
-			<programlisting format="linespecific">
+			<programlisting>
 
         CTD                  Caller               Callee
             #1 INVITE
-            ----------------->
+            -----------------&gt;
                              ...
                              caller answers
             #2 200
-            <-----------------
+            &lt;-----------------
             #3 ACK
-            ----------------->
+            -----------------&gt;
             #4 REFER
-            ----------------->
+            -----------------&gt;
             #5 202
-            <-----------------
+            &lt;-----------------
             #6 BYE
-            ----------------->
+            -----------------&gt;
             #7 200
-            <-----------------
+            &lt;-----------------
                                   #8 INVITE
-                                  ------------------>
+                                  ------------------&gt;
                                   #9 180 ringing
-                                  <------------------
+                                  &lt;------------------
 
 
 #1 click-to-dial (CTD) is started and the "wrapper call" is initiated
@@ -764,13 +771,13 @@ To: callee
 
 		    Source code of the example written in Bourne shell
 		    is available in source distrubtion, in 
-		    <filename moreinfo="none">examples/ctd.sh</filename>.
+		    <filename>examples/ctd.sh</filename>.
 		    A PHP implementation exists as well as a part of
 			<application>serweb</application>.
 		</para>
 		<example>
 		    <title>Running the CTD Example</title>
-		    <programlisting format="linespecific">
+		    <programlisting>
 [jiri@cat examples]$ ./ctd.sh 
 destination unspecified -- taking default value sip:[email protected]
 caller unspecified -- taking default value sip:[email protected]
@@ -786,9 +793,9 @@ bye succeeded
 		    <title>Initiating a SIP Transaction from PHP via FIFO</title>
 
 
-		    <programlisting format="linespecific">
+		    <programlisting>
 			<textobject>
-			    <textdata fileref="../../examples/web_im/send_im.php" format="linespecific">
+			    <textdata fileref="../../examples/web_im/send_im.php">
 			</textobject>
 			    
 		    </programlisting>
@@ -798,5 +805,6 @@ bye succeeded
 -->
 
 	</section> <!-- FIFO server -->
-    </chapter>
-
+    </section>
+</section>
+	

doc/seruser/db_fifo.sgml → doc/seruser/db_fifo.xml

@@ -1,8 +1,20 @@
-<!-- <!DOCTYPE Book PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [ ]> -->
-<chapter>
-<title>Database FIFO interface</title>
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4//EN"
+                      "file:///usr/share/sgml/docbook/dtd/xml/4/docbookx.dtd">
 
-<section>
+<section id="db_fifo" xmlns:xi="http://www.w3.org/2001/XInclude">
+    <sectioninfo>
+	<revhistory>
+	    <revision>
+		<revnumber>$Revision$</revnumber>
+		<date>$Date$</date>
+	    </revision>
+	</revhistory>
+    </sectioninfo>
+
+    <title>Database FIFO interface</title>
+
+    <section id="introduction">
 	<title>Introduction</title>
 	<para>
 	<application>SER</application> offers to its module developers a common 
@@ -19,9 +31,9 @@
 	aliases, access control wrights, etc) using the same FIFO commands 
 	without caring about the database type that's used by SER.
 	</para>
-</section>
+    </section>
 
-<section>
+    <section id="advantages">
 	<title>Advantages</title>
 	<para>
 	All external applications that need to work with SER's database (like 
@@ -36,10 +48,10 @@
 	external applications. They will use automatically the same database as 
 	<application>SER</application> is configure to use.
 	</para>
-</section>
-
+    </section>
+    
 
-<section>
+    <section id="limitations">
 	<title>Limitations</title>
 	<para>
 	DB FIFO interface is restricted to the limitation of the internal DB
@@ -49,15 +61,14 @@
 	Also the size (can fit on only one line) and the the content (\n or \r
 	characters must be escaped) of a BLOB value is restricted.
 	</para>
-</section>
+    </section>
 
-
-<section>
+    <section id="configuration">
 	<title>Configuration</title>
 	<para>
 	FIFO server presents is required, so configure in your config file the FIFO
 	file to be used by the <application>SER</application> FIFO server:
-	<programlisting format="linespecific">
+	<programlisting>
 fifo="/tmp/ser_fifo"
 	</programlisting>
 	To enable the DB FIFO interface, it's required to load at least one 
@@ -66,7 +77,7 @@ fifo="/tmp/ser_fifo"
 	<para>
 	The database module that you want to use and the database configuration are
 	configured via parameter <varname>fifo_db_url</varname>:
-	<programlisting format="linespecific">
+	<programlisting>
 fifo_db_url="mysql:mysql_url"
 fifo_db_url="dbtext:dbtext_url"
 	</programlisting>
@@ -80,10 +91,10 @@ fifo_db_url="dbtext:dbtext_url"
 	If no fifo_db_url is specified or no appropriate DB module found, the 
 	DB FIFO interface will be disabled.
 	</para>
-</section>
+    </section>
 
 
-<section>
+    <section id="db_fifo_commands">
 	<title>DB FIFO commands</title>
 	<para>
 	From FIFO point of view, all DB FIFO commands are mapped with the 
@@ -109,15 +120,17 @@ fifo_db_url="dbtext:dbtext_url"
 			<para>EAW_QUERY_RES</para>
 		</listitem>
 	</itemizedlist>
-	The grammar used in the commands definition can be found in next section
-	"DB FIFO grammar". The presence of the <varname>reply_fifo_file</varname> 
-	in the FIFO command is <emphasis>required</emphasis> for all commands.
+	    The grammar used in the commands definition can be found in next
+	    section "DB FIFO grammar". The presence of the
+	    <varname>reply_fifo_file</varname> in the FIFO command is
+	    <emphasis>required</emphasis> for all commands.
+	</para>
 
 	<section>
-		<title><function moreinfo="none">SELECT</function> command</title>
+		<title><function>SELECT</function> command</title>
 		<para>
 		This function implements SELECT DB directive. Its syntax is:
-		<programlisting format="linespecific">
+		<programlisting>
 :DB:reply_fifo_file
 select
 [COLUMN]*
@@ -137,12 +150,12 @@ TABLE_NAME
 		</para>
 	</section>
 
-	<section>
-		<title><function moreinfo="none">INSERT</function> command</title>
+	<section id="insert">
+		<title><function>INSERT</function> command</title>
 		<para>
 		This function implements INSERT DB directive - inserts one row in 
 		a table. Its syntax is:
-		<programlisting format="linespecific">
+		<programlisting>
 :DB:reply_fifo_file
 insert
 TABLE_NAME
@@ -156,12 +169,12 @@ TABLE_NAME
 	</section>
 
 
-	<section>
-		<title><function moreinfo="none">UPDATE</function> command</title>
+	<section id="update">
+		<title><function>UPDATE</function> command</title>
 		<para>
 		The function implements UPDATE DB directive - it is possible to 
 		modify one or more rows in a table. Its syntax is:
-		<programlisting format="linespecific">
+		<programlisting>
 :DB:reply_fifo_file
 update
 [EQUAL_CVP]+
@@ -177,12 +190,12 @@ TABLE_NAME
 	</section>
 
 
-	<section>
-		<title><function moreinfo="none">DELETE</function> command</title>
+	<section id="delete">
+		<title><function>DELETE</function> command</title>
 		<para>
 		This function implements DELETE DB directive - it is possible to 
 		delete one or more rows from a table. Its syntax is:
-		<programlisting format="linespecific">
+		<programlisting>
 :DB:reply_fifo_file
 delete
 TABLE_NAME
@@ -198,53 +211,54 @@ TABLE_NAME
 	</section>
 
 
-	<section>
-		<title><function moreinfo="none">RAW_QUERY</function> command</title>
+	<section id="raw_query">
+		<title><function>RAW_QUERY</function> command</title>
 		<para>
 		This function sends a raw query directly to the database driver 
 		without trying to understand the command. This command <emphasis>MUST
 		NOT</emphasis> generate any response.Otherwise, the database driver 
 		can block or desynchronize (depending of the driver).
 		Its syntax is:
-		<programlisting format="linespecific">
+		<programlisting>
 :DB:reply_fifo_file
 raw_query
 (ASCII)+
 		</programlisting>
-		</para>
-		<para>
+	    </para>
+	    <para>
 		Command returns nothing if success or, other way, an error message.
-		</para>
+	    </para>
 	</section>
 
 
-	<section>
-		<title>
-			<function moreinfo="none">RAW_QUERY_RES</function> command
-		</title>
-		<para>
+	<section id="raw_query_res">
+	    <title>
+		<function>RAW_QUERY_RES</function> command
+	    </title>
+	    <para>
 		This function sends a raw query directly to the database driver without
 		trying to understand the command. This command <emphasis>MUST
 		</emphasis> generate an response (even if an empty one). Otherwise, 
 		the database driver can block or desynchronize (depending of the 
 		driver). Its syntax is:
-		<programlisting format="linespecific">
+		<programlisting>
 :DB:reply_fifo_file
 raw_query_res
 (ASCII)+
 		</programlisting>
-		</para>
-		<para>
+	    </para>
+	    <para>
 		Command's output format is identical with the one from 
-		<function moreinfo="none">SELECT</function> command.
-		</para>
+		<function>SELECT</function> command.
+	    </para>
 	</section>
-</section>
+    </section>
 
 
-<section>
+    <section id="db_fifo_grammar">
 	<title>DB FIFO grammar</title>
-	<programlisting format="linespecific">
+	<programlisting>
+<![CDATA[
 COLUMN=(alfa-numeric|'_')+
 
 GAP=' '|'\t'
@@ -268,8 +282,7 @@ CVP(column-value-pair)=
 		(COLUMN GAP* DEF_OP GAP* VALUE) | (COLUMN GAP+ UNDEF_OP GAP+ VALUE)
 EQUAL-CVP(column-equal-value-pair)=
 		(COLUMN GAP* '=' GAP* VALUE)
+]]>
 	</programlisting>
+    </section>
 </section>
-
-</chapter>
-

doc/seruser/general.sgml

@@ -1,430 +0,0 @@
-    <chapter id="general">
-	<title>General Information</title>
-	<section id="aboutser">
-	    <title>About <acronym>SIP</acronym> Express Router (<acronym>SER</acronym>)</title>
-	    <para>
-		SIP Express Router (<acronym>SER</acronym>) is an industrial-strength, free VoIP 
-		server based on the Session Initiation Protocol (<acronym>SIP</acronym>, RFC3261). 
-		It is engineered to power <acronym>IP</acronym> telephony infrastructures up to large 
-		scale. The server keeps track of users, sets up VoIP sessions, 
-		relays instant messages and creates space for new plug-in applications. 
-		Its proven interoperability guarantees seamless integration with 
-		components from other vendors, eliminating the risk of a single-vendor 
-		trap. It has successfully participated in various interoperability 
-		tests in which it worked with the products of other leading <acronym>SIP</acronym> vendors.
-	    </para>
-	    <para>
-		The <acronym>SIP</acronym> Express Router enables a flexible plug-in model for new 
-		applications: Third parties can easily link their plug-ins with 
-		the server code and provide thereby advanced and customized services. 
-		In this way, plug-ins such as RADIUS accounting,
-		SMS gateway, ENUM queries, or presence agent have already been developed and are provided as 
-		advanced features. Other modules are underway: 
-		firewall control, postgres and LDAP database drivers and more.
-	    </para>
-	    <para>
-		Its performance and robustness allows it to serve millions of users 
-		and accommodate needs of very large operators. With a $3000 dual-CPU PC, the 
-		<acronym>SIP</acronym> Express Router is able to power <acronym>IP</acronym> telephony services in an area 
-		as large as the Bay Area during peak hours. Even on an IPAQ <acronym>PDA</acronym>, the server 
-		withstands 150 calls per second (<acronym>CPS</acronym>)! The server has been powering our 
-		iptel.org free <acronym>SIP</acronym> site withstanding heavy daily load that is further 
-		increasing with the popularity of Microsoft's Windows Messenger.  
-	    </para>
-	    <para>
-		The <acronym>SIP</acronym> Express Router is extremely configurable to allow the creation of 
-		various routing and admission policies as well as setting up new and 
-		customized services. Its configurability allows it to serve many roles: 
-		network security barrier, application server, or <acronym>PSTN</acronym> gateway guard for 
-		example.
-	    </para>
-	    <para>
-		<application moreinfo="none">ser</application> can be also
-		used with contributed applications. Currently, 
-		<application moreinfo="none">serweb</application>, a
-		<application moreinfo="none">ser</application> web interface,
-		<application moreinfo="none">SIPSak</application> diagnostic tool 
-		and 
-		<application>SEMS</application> media server
-		are available. Visit our site, 
-		<ulink url="http://www.iptel.org/">http://www.iptel.org/</ulink>, 
-                for more information on contributed packages.
-	    </para>
-	</section> 
-
-	<section id="aboutiptel">
-	    <title>About iptel.org</title>
-	    <para>
-		iptel.org is a know-how organization spun off from Germany's national 
-		research company FhG Fokus. One of the first <acronym>SIP</acronym> implementations ever, 
-		low-QoS enhancements, interoperability tests and VoIP-capable firewall 
-		control concepts are examples of well-known FhG's work.
-	    </para>
-	    <para>
-		iptel.org continues to keep this know-how leadership in <acronym>SIP</acronym>. 
-		The access rate of the company's site, a well-known source of 
-		technological information, is a best proof of interest. Thousands 
-		of hits come every day from the whole Internet.
-	    </para>
-	    <para>
-		The iptel.org site, powered by SER, offers SIP services on the public 
-		Internet. Feel free to apply for a free SIP account at
-		<ulink url="http://www.iptel.org/user/">http://www.iptel.org/user/
-		</ulink>
-	    </para>
-
-	    
-	</section> <!-- iptel -->
-	<section id="serfeatures">
-	    <title>Feature List</title>
-	    <para>
-		Based on the latest standards, the <acronym>SIP</acronym> Express Router (<acronym>SER</acronym>) includes 
-		support for registrar, proxy and redirect mode. Further it acts as 
-		an application server with support for instant messaging and 
-		presence including a <acronym>2G/SMS</acronym> and Jabber gateway, a call control policy 
-		language, call number translation, private dial plans and accounting, ENUM,
-		authorization and authentication (<acronym>AAA</acronym>) services. <application>SER</application> runs on Sun/Solaris, 
-		PC/Linux, PC/BSD, IPAQ/Linux platforms and supports  both <acronym>IPv4</acronym> and <acronym>IPv6</acronym>. 
-		Hosting multiple domains and database redundancy is supported.
-	    </para>
-	    <para>
-		<application>ser</application> has been carefully engineered with the following 
-		design objectives in mind:
-		<itemizedlist>
-		    <listitem>
-			<para>
-			    <emphasis>Speed</emphasis> - With <application>ser</application>, 
-			    thousands of calls per seconds are achievable 
-			    even on low-cost platforms. This competitive capacity allows 
-			    setting up networks which are inexpensive and easy to manage 
-			    due to low number of devices required. The processing capacity 
-			    makes dealing with many stress factors easier. The stress
-			    factors may include but are not limited to broken configurations and implementations,
-			    boot avalanches on power-up, high-traffic applications such as presence, 
-			    redundancy replications and denial-of-service attacks.
-			</para>
-			<para> The speed has been achieved by extensive code optimization, use of customized code, 
-			    <acronym>ANSI C</acronym> combined with assembly instructions and leveraging latest 
-			    <acronym>SIP</acronym> improvements. When powered by a dual-CPU Linux PC, 
-			    <application>ser</application> is able to process thousands of calls per second,
-			    capacity needed to serve call signaling demands of Bay Area population.
-			   
-			</para>
-		    </listitem>
-		    <listitem>
-			<para>
-			    <emphasis>Flexibility</emphasis> - <application>SER</application> allows its users 
-			    to define its behavior. 
-			    Administrators may write textual scripts which determine <acronym>SIP</acronym> routing 
-			    decisions, the main job of a proxy server. They may use the script to 
-			    configure numerous parameters and introduce additional logic. For example, 
-			    the scripts can determine for which destinations record routing should be 
-			    performed, who will be authenticated, which transactions should be processed 
-			    statefully, which requests will be proxied or redirected, etc.
-			</para>
-
-		    </listitem>
-		    <listitem>
-			<para>
-			    <emphasis>Extensibility</emphasis> - <application>SER</application>'s extensibility allows linking of 
-			    new C code to ser to 
-			    redefine or extend its logic. The new code can be developed independently 
-			    on <application>SER</application> core and linked to it in run-time. The concept is similar to 
-			    the module concept known for example in Apache Web server. Even such essential parts such 
-			    as transaction management have been developed as modules to keep the <application>SER</application> core 
-			    compact and fast.
-			</para>
-		    </listitem>
-		    <listitem>
-			<para>
-			    <emphasis>
-				Portability.
-			    </emphasis>
-			    <application>ser</application> has been written in ANSI C. It has been extensively tested 
-			    on PC/Linux and Sun/Solaris. Ports to BSD and IPAQ/Linux exist.
-			</para>
-		    </listitem>
-		    <listitem>
-			<para>
-			    <emphasis>			   
-				Interoperability. 
-			</emphasis>
-			<application>ser</application> is based on the open <acronym>SIP</acronym> standard. 
-			    It has undergone extensive tests with products of other vendors both in iptel.org
-			    labs and in the SIP Interoperability Tests (SIPIT). <application>ser</application> 
-			    powers the public iptel.org site 24 hours a day, 356 days a year 
-			    serving numerous SIP implementations using this site.
-			</para>
-		    </listitem>
-		    <listitem>
-			<para>
-			    <emphasis>Small size.</emphasis>
-			    Footprint of the core is 300k, add-on modules take up to 630k.
-			</para>
-		    </listitem>
-		</itemizedlist>
-	    </para>
-	</section> <!-- serfeatures -->
-
-	<section id="usecases">
-	    <title>Use Cases</title>
-	    <para>
-		This section illustrates the most frequent uses of SIP. In all these scenarios, 
-		the SIP Express Router (SER) can be easily deployed as the glue connecting all 
-		SIP components together, be it soft-phones, hard-phones, PSTN gateways or any other 
-		SIP-compliant devices.
-	    </para>
-	    <section>
-		<title>Added-Value ISP Services</title>
-		<para>
-		    To attract customers, ISPs frequently offer applications bundled with IP access. 
-		    With SIP, the providers can conveniently offer a variety of services running on top 
-		    of a single infrastructure. Particularly, deploying VoIP and instant messaging and 
-		    presence services is as easy as setting up a SIP server and guiding customers to use 
-		    Windows Messenger. Additionally, the ISPs may offer advanced services such as PSTN 
-		    termination, user-driven call handling or unified messaging all using the same infrastructure.
-		</para>
-		<para>
-		    SIP Express Router has been engineered to power large scale networks: its capacity can deal 
-		    with large number of customers under high load caused by modern applications. Premium 
-		    performance allows deploying a low number of boxes while keeping investments and operational 
-		    expenses extremely low. ISPs can offer SIP-based instant messaging services and interface
-		    them to other instant messaging systems (Jabber, SMS). VoIP can be easily integrated along
-		    with added-value services, such as voicemail.
-		</para>
-	    </section> <!-- Added-value ISP -->
-	    <section>
-		<title>PC2Phone</title>
-		<para>
-		    Internet Telephony Service Providers (ITSPs) offer the service of interconnecting 
-		    Internet telephony users using PC softphone or appliances to PSTN. Particularly with 
-		    long-distance and international calls, competitive pricing can be achieved by 
-		    routing the calls over the Internet.
-		</para>
-		<para>
-		    SIP Express Router can be easily configured to serve pc2phone users, distribute
-		    calls to geographically appropriate PSTN gateway, act as a security barrier and keep 
-		    track of charging. 
-		</para>
-	    </section>
-	    <section>
-		<title>PBX Replacement</title>
-		<para>
-		    Replacing a traditional PBX in an enterprise can achieve reasonable 
-		    savings. Enterprises can deploy a single infrastructure for both voice 
-		    and data and bridge distant locations over the Internet. Additionally, they can 
-		    benefit of integration of voice and data.
-		</para>
-		<para>
-		    The SIP Express Router scales from SOHOs to large, international enterprises. 
-		    Even a single installation on a common PC is able to serve VoIP signaling of any 
-		    world's enterprise. Its policy-based routing language makes implementation of numbering 
-		    plans of companies spread across the world very easy. ACL features allow for protection of 
-		    PSTN gateway from unauthorized callers.
-		</para>
-		<para>
-		    SIP Express Router's support for programmable routing and accounting efficiently allows for 
-		    implementation of such a scenario.
-		</para>
-	    </section>
-	</section> <!-- Use Cases -->
-	<section id="aboutsip">
-	    <title>About SIP Technology</title>
-	    <para>
-		The SIP protocol family is the technology which integrates services. 
-		With SIP, Internet users can easily contact each other; figure out 
-		willingness to have a conversation and couple different applications such as VoIP, video 
-		and instant messaging. Integration with added-value services is seamless and easy. Examples 
-		include integration with web (click-to-dial), E-mail (voice2email, UMS), and PSTN-like 
-		services (conditional forwarding).
-	    </para>
-	    <para>
-		The core piece of the technology is the Session Initiation Protocol (SIP, RFC3261) standardized by IETF. 
-		Its main function is to establish communication sessions between users connected to the public 
-		Internet and identified by e-mail-like addresses. One of SIP's greatest features is its transparent 
-		support for multiple applications: the same infrastructure may be used for voice, video, gaming 
-		or instant messaging as well as any other communication application.
-	    </para>
-	    <para>
-		There are numerous scenarios in which SIP is already deployed: PBX replacement allows for 
-		deployment of single inexpensive infrastructure in enterprises; PC-2-phone long-distance 
-		services (e.g., Deltathree) cut callers long-distance expenses; instant messaging offered 
-		by public severs (e.g., iptel.org) combines voice and text services with presence information. 
-		New deployment scenarios are underway: SIP is a part of UMTS networks and research publications 
-		suggest the use of SIP for virtual home environments or distributed network games.
-	    </para>
-	</section> <!-- about sip -->
-	<section id="serlimitations">
-	    <title>Known SER Limitations</title>
-	    <para>
-		The following items are not part of current distribution and are planned for next releases:
-		<itemizedlist>
-		    <listitem>
-			<para>
-			    Script processing of multiple branches on forking
-			</para>
-
-			<warning>
-			    <para>
-				<application>ser</application>'s request processing language allows 
-				to make request decisions based on current URI. 
-				When a request if forked to multiple destinations, only the first branch's URI is used as 
-				input for script processing. This might lead to unexpected results. Whenever a URI resolves 
-				to multiple different next-hop URIs, only the first is processed which may result in handling 
-				not appropriate for the other branch. For example, a URI might resolve to an IP phone SIP 
-				address and PSTN gateway SIP address. If the IP phone address is the first, then script 
-				execution ignores the second branch. If a script includes checking gateway address in
-				request URI, the checks never match. That might result in ignoring of 
-				gateway admission control rules or applying them unnecessarily to non-gateway 
-				destinations.
-			    </para>
-			</warning>
-		    </listitem>
-		</itemizedlist>
-	    </para>
-	    <para>
-		List of known problems is publicly available at the 
-		<application>ser</application> webpage at
-		<ulink url="http://www.iptel.org/ser/">
-		    http://www.iptel.org/ser/
-		</ulink>. See the "ISSUES" link.
-	    </para>
-	</section> <!-- limitations -->
-	<section id="licensing">
-	    <title>Licensing</title>
-	    <para>
-		<application>ser</application> is freely available under terms and
-		conditions of the GNU General Public License.
-	    </para>	
-	    <!-- COPYING -->
-	    <screen>
-	    	    &gpllicense;
-	    </screen>
-	    
-	</section>
-	<section id="support">
-	    <title>Obtaining Technical Assistance</title>
-		<para>
-			iptel.org offers qualified professional services. We help you to 
-			plan your network, configure your server, build applications, 
-			integrate SIP components with each other, and set up advanced features
-			such as redundancy, multidomain support, CLID interworking and others
-			not described in this document. Our customer alert services
-			notifies you on all new features and code fixes. We help you to
-			solve operational troubles in short time and keep you updated on
-			latest operational practices. Ask [email protected] for
-			information on enrollment in our support program.
-		</para>
-
-	    <para>
-		Additionally, help may be obtained from our user forum. The community
-		of <application>SER</application> users is subscribed to the
-		[email protected] mailing list and discusses issues related to
-		<application>SER</application> operation.
-	    </para>
-	    <itemizedlist>
-		<title>Mailing List Instructions</title>
-		<listitem>
-		    <para>
-			Public archives and subscription form:
-			<ulink url="http://mail.iptel.org/mailman/listinfo/serusers">
-			    http://mail.iptel.org/mailman/listinfo/serusers
-			</ulink>			
-		    </para>
-		</listitem>
-		<listitem>
-		    <para>
-			To post, send an email to [email protected]
-		    </para>
-		</listitem>
-		<listitem>
-		    <para>
-			If you think you encountered an error, please submit the
-			following information to avoid unnecessary round-trip times:			
-			<itemizedlist>
-			    <listitem>
-				<para>
-				    Name and version of your operating system --
-				    you can obtain it by calling
-				    <command>uname -a</command>
-				</para>
-			    </listitem>
-			    <listitem>
-				<para>
-				    <application>ser</application> distribution: 
-				    release number and package				    
-				</para>
-			    </listitem>
-			    <listitem>
-				<para>
-				    <application>ser</application> build -- 
-				    you can obtain it by calling 
-				    <command moreinfo="none">ser -V</command>
-				</para>
-			    </listitem>
-			    <listitem>
-				<para>
-				    Your <application>ser</application> configuration file
-				</para>
-			    </listitem>
-			    <listitem>
-				<para>
-				    <application>ser</application> logs -- with default settings
-				    few logs are printed to <command>syslog</command> facility which
-				    typically dumps them to 
-				    <filename moreinfo="none">/var/log/messages</filename>. To 
-				    enable detailed logs dumped to <filename>stderr</filename>,
-				    apply the following configuration options: <command moreinfo="none">
-				    debug=8, log_stderror=yes, fork=no</command>.
-				</para>
-			    </listitem>
-			    <listitem>
-				<para>
-				    Captured SIP messages -- you can obtain them 
-				    using tools such as <application>ngrep</application>
-				    or <application moreinfo="none">ethereal</application>.
-				</para>
-			    </listitem>
-			</itemizedlist>
-		    </para>
-		    
-		</listitem>
-	    </itemizedlist>	    
-	
-	    <para>
-		If you are concerned about your privacy and do not wish your
-		queries to be posted and archived publicly, you may post to
-		[email protected]. E-mails to this address are only forwarded
-		to iptel.org's <application>ser</application> development team.
-		However, as the team is quite busy you should not be surprised
-		to get replies with considerable delay.
-
-	    </para>
-	</section>
-        
-	<section id="moreinfo">
-	    <title>More Information</title>
-	    <para>
-		Most up-to-date information including latest and most complete version
-		of this documentation is always available at our website,
-		<ulink url="http://www.iptel.org/ser/">http://www.iptel.org/ser/</ulink>.
-		The site includes links to other important information about
-		<application moreinfo="none">ser</application>, such
-		as installation guidelines (INSTALL), download links,
-		development pages, programmer's manual, etc.
-	    </para>
-	    <para>
-		A SIP tutorial (slide set) is available at 
-		<ulink url="http://www.iptel.org/sip/">http://www.iptel.org/sip/</ulink> .
-	    </para>
-	</section> <!-- info -->
-
-	<section>
-	    <title>Release Notes</title>
-	    <literallayout format="linespecific" class="normal">
-&releasenotes;
-	    </literallayout>
-	</section> <!-- release notes -->
-
-
-    </chapter> <!-- general -->

doc/seruser/general.xml

@@ -0,0 +1,490 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4//EN"
+                      "file:///usr/share/sgml/docbook/dtd/xml/4/docbookx.dtd">
+
+<section id="general" xmlns:xi="http://www.w3.org/2001/XInclude">
+    <sectioninfo>
+	<revhistory>
+	    <revision>
+		<revnumber>$Revision$</revnumber>
+		<date>$Date$</date>
+	    </revision>
+	</revhistory>
+    </sectioninfo>
+    
+    <title>General Information</title>
+    <section id="aboutser">
+	<title>About <acronym>SIP</acronym> Express Router (<acronym>SER</acronym>)</title>
+	<para>
+	    SIP Express Router (<acronym>SER</acronym>) is an
+	    industrial-strength, free VoIP server based on the Session
+	    Initiation Protocol (<acronym>SIP</acronym>, RFC3261).  It is
+	    engineered to power <acronym>IP</acronym> telephony infrastructures
+	    up to large scale. The server keeps track of users, sets up VoIP
+	    sessions, relays instant messages and creates space for new plug-in
+	    applications.  Its proven interoperability guarantees seamless
+	    integration with components from other vendors, eliminating the
+	    risk of a single-vendor trap. It has successfully participated in
+	    various interoperability tests in which it worked with the products
+	    of other leading <acronym>SIP</acronym> vendors.
+	</para>
+	<para>
+	    The <acronym>SIP</acronym> Express Router enables a flexible
+	    plug-in model for new applications: Third parties can easily link
+	    their plug-ins with the server code and provide thereby advanced
+	    and customized services.  In this way, plug-ins such as RADIUS
+	    accounting, SMS gateway, ENUM queries, or presence agent have
+	    already been developed and are provided as advanced features. Other
+	    modules are underway: firewall control, postgres and LDAP database
+	    drivers and more.
+	</para>
+	<para>
+	    Its performance and robustness allows it to serve millions of users
+	    and accommodate needs of very large operators. With a $3000
+	    dual-CPU PC, the <acronym>SIP</acronym> Express Router is able to
+	    power <acronym>IP</acronym> telephony services in an area as large
+	    as the Bay Area during peak hours. Even on an IPAQ
+	    <acronym>PDA</acronym>, the server withstands 150 calls per second
+	    (<acronym>CPS</acronym>)! The server has been powering our
+	    iptel.org free <acronym>SIP</acronym> site withstanding heavy daily
+	    load that is further increasing with the popularity of Microsoft's
+	    Windows Messenger.
+	</para>
+	<para>
+	    The <acronym>SIP</acronym> Express Router is extremely configurable
+	    to allow the creation of various routing and admission policies as
+	    well as setting up new and customized services. Its configurability
+	    allows it to serve many roles: network security barrier,
+	    application server, or <acronym>PSTN</acronym> gateway guard for
+	    example.
+	</para>
+	<para>
+	    <application>ser</application> can be also
+	    used with contributed applications. Currently, 
+	    <application>serweb</application>, a
+	    <application>ser</application> web interface,
+	    <application>SIPSak</application> diagnostic tool 
+	    and 
+	    <application>SEMS</application> media server
+	    are available. Visit our site, 
+	    <ulink url="http://www.iptel.org/">http://www.iptel.org/</ulink>, 
+	    for more information on contributed packages.
+	</para>
+    </section> 
+
+    <section id="aboutiptel">
+	<title>About iptel.org</title>
+	<para>
+	    iptel.org is a know-how organization spun off from Germany's
+	    national research company FhG Fokus. One of the first
+	    <acronym>SIP</acronym> implementations ever, low-QoS enhancements,
+	    interoperability tests and VoIP-capable firewall control concepts
+	    are examples of well-known FhG's work.
+	</para>
+	<para>
+	    iptel.org continues to keep this know-how leadership in
+	    <acronym>SIP</acronym>.  The access rate of the company's site, a
+	    well-known source of technological information, is a best proof of
+	    interest. Thousands of hits come every day from the whole Internet.
+	</para>
+	<para>
+	    The iptel.org site, powered by SER, offers SIP services on the public 
+	    Internet. Feel free to apply for a free SIP account at
+	    <ulink url="http://www.iptel.org/user/">http://www.iptel.org/user/
+	    </ulink>
+	</para>
+
+	</section> <!-- iptel -->
+	<section id="serfeatures">
+	<title>Feature List</title>
+	<para>
+	    Based on the latest standards, the <acronym>SIP</acronym> Express
+	    Router (<acronym>SER</acronym>) includes support for registrar,
+	    proxy and redirect mode. Further it acts as an application server
+	    with support for instant messaging and presence including a
+	    <acronym>2G/SMS</acronym> and Jabber gateway, a call control policy
+	    language, call number translation, private dial plans and
+	    accounting, ENUM, authorization and authentication
+	    (<acronym>AAA</acronym>) services. <application>SER</application>
+	    runs on Sun/Solaris, PC/Linux, PC/BSD, IPAQ/Linux platforms and
+	    supports both <acronym>IPv4</acronym> and <acronym>IPv6</acronym>.
+	    Hosting multiple domains and database redundancy is supported.
+	</para>
+	<para>
+	    <application>ser</application> has been carefully engineered with
+	    the following design objectives in mind:
+	    <itemizedlist>
+		<listitem>
+		    <para>
+			<emphasis>Speed</emphasis> - With
+			<application>ser</application>, thousands of calls per
+			seconds are achievable even on low-cost platforms. This
+			competitive capacity allows setting up networks which
+			are inexpensive and easy to manage due to low number of
+			devices required. The processing capacity makes dealing
+			with many stress factors easier. The stress factors may
+			include but are not limited to broken configurations
+			and implementations, boot avalanches on power-up,
+			high-traffic applications such as presence, redundancy
+			replications and denial-of-service attacks.
+		    </para>
+		    <para> The speed has been achieved by extensive code
+			optimization, use of customized code, <acronym>ANSI
+			C</acronym> combined with assembly instructions and
+			leveraging latest <acronym>SIP</acronym>
+			improvements. When powered by a dual-CPU Linux PC,
+			<application>ser</application> is able to process
+			thousands of calls per second, capacity needed to serve
+			call signaling demands of Bay Area population.
+		    </para>
+		    </listitem>
+		    <listitem>
+		    <para>
+			<emphasis>Flexibility</emphasis> -
+			<application>SER</application> allows its users to
+			define its behavior.  Administrators may write textual
+			scripts which determine <acronym>SIP</acronym> routing
+			decisions, the main job of a proxy server. They may use
+			the script to configure numerous parameters and
+			introduce additional logic. For example, the scripts
+			can determine for which destinations record routing
+			should be performed, who will be authenticated, which
+			transactions should be processed statefully, which
+			requests will be proxied or redirected, etc.
+		    </para>
+		</listitem>
+		<listitem>
+		    <para>
+			<emphasis>Extensibility</emphasis> -
+			<application>SER</application>'s extensibility allows
+			linking of new C code to ser to redefine or extend its
+			logic. The new code can be developed independently on
+			<application>SER</application> core and linked to it in
+			run-time. The concept is similar to the module concept
+			known for example in Apache Web server. Even such
+			essential parts such as transaction management have
+			been developed as modules to keep the
+			<application>SER</application> core compact and fast.
+		    </para>
+		</listitem>
+		<listitem>
+		    <para>
+			<emphasis>
+			    Portability.
+			</emphasis>
+			<application>ser</application> has been written in ANSI
+			C. It has been extensively tested on PC/Linux and
+			Sun/Solaris. Ports to BSD and IPAQ/Linux exist.
+		    </para>
+		</listitem>
+		<listitem>
+		    <para>
+			<emphasis>			   
+			    Interoperability. 
+			</emphasis>
+			<application>ser</application> is based on the open
+			<acronym>SIP</acronym> standard.  It has undergone
+			extensive tests with products of other vendors both in
+			iptel.org labs and in the SIP Interoperability Tests
+			(SIPIT). <application>ser</application> powers the
+			public iptel.org site 24 hours a day, 356 days a year
+			serving numerous SIP implementations using this site.
+		    </para>
+		</listitem>
+		<listitem>
+		    <para>
+			<emphasis>Small size.</emphasis>
+			Footprint of the core is 300k, add-on modules take up to 630k.
+		    </para>
+		</listitem>
+	    </itemizedlist>
+	</para>
+    </section> <!-- serfeatures -->
+    
+    <section id="usecases">
+	<title>Use Cases</title>
+	<para>
+	    This section illustrates the most frequent uses of SIP. In all
+	    these scenarios, the SIP Express Router (SER) can be easily
+	    deployed as the glue connecting all SIP components together, be it
+	    soft-phones, hard-phones, PSTN gateways or any other SIP-compliant
+	    devices.
+	</para>
+	<section>
+	    <title>Added-Value ISP Services</title>
+	    <para>
+		To attract customers, ISPs frequently offer applications
+		bundled with IP access.  With SIP, the providers can
+		conveniently offer a variety of services running on top of a
+		single infrastructure. Particularly, deploying VoIP and instant
+		messaging and presence services is as easy as setting up a SIP
+		server and guiding customers to use Windows
+		Messenger. Additionally, the ISPs may offer advanced services
+		such as PSTN termination, user-driven call handling or unified
+		messaging all using the same infrastructure.
+	    </para>
+	    <para>
+		SIP Express Router has been engineered to power large scale
+		networks: its capacity can deal with large number of customers
+		under high load caused by modern applications. Premium
+		performance allows deploying a low number of boxes while
+		keeping investments and operational expenses extremely
+		low. ISPs can offer SIP-based instant messaging services and
+		interface them to other instant messaging systems (Jabber,
+		SMS). VoIP can be easily integrated along with added-value
+		services, such as voicemail.
+	    </para>
+	</section> <!-- Added-value ISP -->
+	<section>
+	    <title>PC2Phone</title>
+	    <para>
+		Internet Telephony Service Providers (ITSPs) offer the service
+		of interconnecting Internet telephony users using PC softphone
+		or appliances to PSTN. Particularly with long-distance and
+		international calls, competitive pricing can be achieved by
+		routing the calls over the Internet.
+	    </para>
+	    <para>
+		SIP Express Router can be easily configured to serve pc2phone
+		users, distribute calls to geographically appropriate PSTN
+		gateway, act as a security barrier and keep track of charging.
+	    </para>
+	</section>
+	<section>
+	    <title>PBX Replacement</title>
+	    <para>
+		Replacing a traditional PBX in an enterprise can achieve
+		reasonable savings. Enterprises can deploy a single
+		infrastructure for both voice and data and bridge distant
+		locations over the Internet. Additionally, they can benefit of
+		integration of voice and data.
+	    </para>
+	    <para>
+		The SIP Express Router scales from SOHOs to large,
+		international enterprises.  Even a single installation on a
+		common PC is able to serve VoIP signaling of any world's
+		enterprise. Its policy-based routing language makes
+		implementation of numbering plans of companies spread across
+		the world very easy. ACL features allow for protection of PSTN
+		gateway from unauthorized callers.
+	    </para>
+	    <para>
+		SIP Express Router's support for programmable routing and
+		accounting efficiently allows for implementation of such a
+		scenario.
+	    </para>
+	</section>
+    </section> <!-- Use Cases -->
+    <section id="aboutsip">
+	<title>About SIP Technology</title>
+	<para>
+	    The SIP protocol family is the technology which integrates
+	    services.  With SIP, Internet users can easily contact each other;
+	    figure out willingness to have a conversation and couple different
+	    applications such as VoIP, video and instant messaging. Integration
+	    with added-value services is seamless and easy. Examples include
+	    integration with web (click-to-dial), E-mail (voice2email, UMS),
+	    and PSTN-like services (conditional forwarding).
+	</para>
+	<para>
+	    The core piece of the technology is the Session Initiation Protocol
+	    (SIP, RFC3261) standardized by IETF.  Its main function is to
+	    establish communication sessions between users connected to the
+	    public Internet and identified by e-mail-like addresses. One of
+	    SIP's greatest features is its transparent support for multiple
+	    applications: the same infrastructure may be used for voice, video,
+	    gaming or instant messaging as well as any other communication
+	    application.
+	</para>
+	<para>
+	    There are numerous scenarios in which SIP is already deployed: PBX
+	    replacement allows for deployment of single inexpensive
+	    infrastructure in enterprises; PC-2-phone long-distance services
+	    (e.g., Deltathree) cut callers long-distance expenses; instant
+	    messaging offered by public severs (e.g., iptel.org) combines voice
+	    and text services with presence information.  New deployment
+	    scenarios are underway: SIP is a part of UMTS networks and research
+	    publications suggest the use of SIP for virtual home environments
+	    or distributed network games.
+	</para>
+    </section> <!-- about sip -->
+    <section id="serlimitations">
+	<title>Known SER Limitations</title>
+	<para>
+	    The following items are not part of current distribution and are
+	    planned for next releases:
+	    <itemizedlist>
+		<listitem>
+		    <para>
+			Script processing of multiple branches on forking
+		    </para>
+		    
+		    <warning>
+			<para>
+			    <application>ser</application>'s request processing
+			    language allows to make request decisions based on
+			    current URI.  When a request if forked to multiple
+			    destinations, only the first branch's URI is used
+			    as input for script processing. This might lead to
+			    unexpected results. Whenever a URI resolves to
+			    multiple different next-hop URIs, only the first is
+			    processed which may result in handling not
+			    appropriate for the other branch. For example, a
+			    URI might resolve to an IP phone SIP address and
+			    PSTN gateway SIP address. If the IP phone address
+			    is the first, then script execution ignores the
+			    second branch. If a script includes checking
+			    gateway address in request URI, the checks never
+			    match. That might result in ignoring of gateway
+			    admission control rules or applying them
+			    unnecessarily to non-gateway destinations.
+			</para>
+			</warning>
+		    </listitem>
+	    </itemizedlist>
+	</para>
+	<para>
+	    List of known problems is publicly available at the 
+	    <application>ser</application> webpage at
+	    <ulink url="http://www.iptel.org/ser/">
+		http://www.iptel.org/ser/
+	    </ulink>. See the "ISSUES" link.
+	</para>
+    </section> <!-- limitations -->
+    <section id="licensing">
+	<title>Licensing</title>
+	<para>
+	    <application>ser</application> is freely available under terms and
+	    conditions of the GNU General Public License.
+	</para>	
+	<!-- COPYING -->
+	<screen>
+<xi:include href="../../COPYING" parse="text"/>
+	</screen>
+    </section>
+
+    <section id="support">
+	<title>Obtaining Technical Assistance</title>
+	<para>
+	    iptel.org offers qualified professional services. We help you to
+	    plan your network, configure your server, build applications,
+	    integrate SIP components with each other, and set up advanced
+	    features such as redundancy, multidomain support, CLID interworking
+	    and others not described in this document. Our customer alert
+	    services notifies you on all new features and code fixes. We help
+	    you to solve operational troubles in short time and keep you
+	    updated on latest operational practices. Ask [email protected] for
+	    information on enrollment in our support program.
+	</para>
+	
+	<para>
+	    Additionally, help may be obtained from our user forum. The
+	    community of <application>SER</application> users is subscribed to
+	    the [email protected] mailing list and discusses issues related to
+	    <application>SER</application> operation.
+	</para>
+	<itemizedlist>
+	    <title>Mailing List Instructions</title>
+	    <listitem>
+		<para>
+		    Public archives and subscription form:
+		    <ulink url="http://mail.iptel.org/mailman/listinfo/serusers">
+			http://mail.iptel.org/mailman/listinfo/serusers
+		    </ulink>
+		</para>
+	    </listitem>
+	    <listitem>
+		<para>
+		    To post, send an email to [email protected]
+		</para>
+	    </listitem>
+	    <listitem>
+		<para>
+		    If you think you encountered an error, please submit the
+		    following information to avoid unnecessary round-trip
+		    times:
+		    <itemizedlist>
+			<listitem>
+			    <para>
+				Name and version of your operating system --
+				you can obtain it by calling <command>uname
+				-a</command>
+			    </para>
+			</listitem>
+			<listitem>
+			    <para>
+				<application>ser</application> distribution: 
+				release number and package				    
+			    </para>
+			</listitem>
+			<listitem>
+			    <para>
+				<application>ser</application> build -- 
+				you can obtain it by calling 
+				<command>ser -V</command>
+			    </para>
+			</listitem>
+			<listitem>
+			    <para>
+				Your <application>ser</application> configuration file
+			    </para>
+			</listitem>
+			<listitem>
+			    <para>
+				<application>ser</application> logs -- with
+				default settings few logs are printed to
+				<command>syslog</command> facility which
+				typically dumps them to
+				<filename>/var/log/messages</filename>. To
+				enable detailed logs dumped to
+				<filename>stderr</filename>, apply the
+				following configuration options: <command>
+				debug=8, log_stderror=yes, fork=no</command>.
+			    </para>
+			</listitem>
+			<listitem>
+			    <para>
+				Captured SIP messages -- you can obtain them 
+				using tools such as <application>ngrep</application>
+				or <application>ethereal</application>.
+			    </para>
+			</listitem>
+		    </itemizedlist>
+		</para>
+	    </listitem>
+	</itemizedlist>
+	<para>
+	    If you are concerned about your privacy and do not wish your
+	    queries to be posted and archived publicly, you may post to
+	    [email protected]. E-mails to this address are only forwarded to
+	    iptel.org's <application>ser</application> development team.
+	    However, as the team is quite busy you should not be surprised to
+	    get replies with considerable delay.
+	</para>
+    </section>
+    
+    <section id="moreinfo">
+	<title>More Information</title>
+	<para>
+	    Most up-to-date information including latest and most complete
+	    version of this documentation is always available at our website,
+	    <ulink
+	    url="http://www.iptel.org/ser/">http://www.iptel.org/ser/</ulink>.
+	    The site includes links to other important information about
+	    <application>ser</application>, such as installation guidelines
+	    (INSTALL), download links, development pages, programmer's manual,
+	    etc.
+	</para>
+	<para>
+	    A SIP tutorial (slide set) is available at 
+	    <ulink url="http://www.iptel.org/sip/">http://www.iptel.org/sip/</ulink> .
+	</para>
+    </section> <!-- info -->
+    
+    <section>
+	<title>Release Notes</title>
+	<literallayout>
+<xi:include href="../../NEWS" parse="text"/>
+	</literallayout>
+    </section> <!-- release notes -->
+</section> <!-- general -->

doc/seruser/intro.sgml

@@ -1,1466 +0,0 @@
-    <chapter>
-	<title>Introduction to SER</title>
-
-	<section id="requestrouting">
-	    <title>Request Routing and SER Scripts</title>
-	    <para>
-		The most important concept of every SIP server is that of
-		request routing. The request routing logic determines the next
-		hop of a request. It can be for example used to implement user 
-		location service or enforce static routing to a gateway. Real-world
-		deployments actually ask for quite complex routing logic, which
-		needs to reflect static routes to PSTN gateways, dynamic routes
-		to registered users, authentication policy, capabilities of
-		SIP devices, etc.
-	    </para>
-	    <para>
-		SER's answer to this need for routing flexibility is a routing
-		language, which allows administrators to define the SIP request
-		processing logic in a detailed manner. They can for example easily
-		split SIP traffic by method or destination, perform user location, 
-		trigger authentication, verify access permissions, and so on.
-	    </para>
-	    <para>
-		The primary building block of the routing language are <emphasis>actions</emphasis>. 
-		There are built-in actions (like <command>forward</command> for stateless forwarding
-		or <command>strip</command> for stripping URIs) as 
-		well as external actions imported from shared library modules. All actions can 
-		be combined in compound actions by enclosing them in braces, 
-		e.g. <command>{a1(); a2();}</command>. 
-		Actions are aggregated in one or more <emphasis>route blocks</emphasis>.
-		Initially, only the default routing block denoted by <command>route[0]</command>
-		is called. Other routing blocks can be called by the action
-		<command>route(blocknumber)</command>, recursion is permitted.
-		The language includes <emphasis>conditional statements</emphasis>. 
-	    </para>
-
-	    <para>
-		The routing script is executed for every received request in sequential order. 
-		Actions may return positive/negative/zero value. 
-
-		Positive values are considered success and evaluated as
-		TRUE in conditional expressions. Negative values are considered FALSE. 
-
-		Zero value means error and leaves execution of currently processed
-		route block. The route block is left too, if <command>break</command> is explicitly
-		called from it.
-
-	    </para>
-	    <para>
-		The easiest and still very useful way for <application>ser</application>
-		users to affect request routing logic is
-		to determine next hop statically. An example is
-		routing to a PSTN gateway whose static IP address is well known.
-		To configure static routing, simply use the action
-		<command>forward( IP_address, port_number)</command>.
-		This action forwards an incoming request "as is" to the
-		destination described in action's parameters.
-	    </para>
-
-	    <example>
-		<title>Static Forwarding</title>
-		<programlisting format="linespecific">
-# if requests URI is numerical and starts with
-# zero, forward statelessly to a static destination
-
-if (uri=~"^sip:0[0-9]*@iptel.org") {
-    forward( 192.168.99.3, 5080 );
-} 
-		</programlisting>
-	    </example>
-
-	    <para>
-		However, static forwarding is not sufficient in many cases.
-		Users desire mobility and change their location frequently.
-		Lowering costs for termination of calls in PSTN requires
-		locating a least-cost gateway. Which next-hop is taken may
-		depend on user's preferences. These and many other scenarios
-		need the routing logic to be more dynamic. We describe in
-		<xref linkend="conditions"> how to make request processing
-		subject to various conditions and in 
-		<xref linkend="urirewriting"> how to determine next SIP hop.
-	    </para>
-	</section>
-
-	<section id="conditions">
-	    <title>Conditional Statements</title>
-	    <para>
-		A very useful feature is the ability to make routing
-		logic depend on a condition. A script condition may for
-		example distinguish between request processing for
-		served and foreign domains, IP and PSTN routes,
-		it may split traffic by method or username, it
-		may determine whether a request should be authenticated
-		or not, etc. <application moreinfo="none">ser</application>
-		allows administrators to form conditions based on
-		properties of processed request, such as method or uri,
-		as well as on virtually any piece of data on the
-		Internet.
-	    </para>
-	    <example>
-		<title>Conditional Statement</title>
-		<para>
-		    This example shows how a conditional statement is
-		    used to split incoming requests between a PSTN
-		    gateway and a user location server based on
-		    request URI.
-		</para>
-		<programlisting format="linespecific">
-# if request URI is numerical, forward the request to PSTN gateway...
-if (uri=~"^sip:[0-9][email protected]") { # match using a regular expression
-    forward( gateway.foo.bar, 5060 );
-} else { # ... forward the request to user location server otherwise
-    forward( userloc.foo.bar, 5060 );
-};
-		</programlisting>
-	    </example>
-
-	    <para>
-		Conditional statements in <application>ser</application> scripts may depend
-		on a variety of  expressions. The simplest expressions are 
-		action calls. They return true if they completed successfully or false otherwise. 
-		An example of an action frequently used in conditional statements is
-		<command moreinfo="none">search</command> imported from textops module.
-		<command moreinfo="none">search</command> action leverages textual
-		nature of SIP and compares SIP requests against a regular expression.
-		The action returns true if the expression matched, false otherwise.
-		<example>
-		    <title>Use of <command>search</command> Action in Conditional Expression</title>
-		    <programlisting format="linespecific">
-# prevent strangers from claiming to belong to our domain;
-# if sender claims to be in our domain in From header field,
-# better authenticate him 
-if (search("(f|From): .*@mydomain.com)) {
-    if (!(proxy_authorize("mydomain.com" /* realm */,"subscriber" /* table name */ ))) {
-           proxy_challenge("mydomain.com /* ream */, "1" /* use qop */ );
-           break;
-    }
-}
- 		    </programlisting>
-		</example>
-	    </para>
-	    <para>
-		As modules may be created, which export new functions, there is virtually
-		no limitation on what functionality <application moreinfo="none">ser</application>
-		conditions are based on. Implementers may introduce new actions whose
-		return status depends on request content or any external data as well. Such actions
-		can query SQL, web, local file systems or any other place which can provide
-		information wanted for request processing.
-	    </para>
-	    <para>
-		Furthermore, many request properties may be examined using existing built-in operands
-		and operators. Available left-hand-side operands and legal combination with
-		operators and right-hand-side operands are described in <xref linkend="logicalexpr">.
-		Expressions may be grouped together using logical operators:
-		negation (<command>!</command>), AND (<command>&&</command>), OR (<command moreinfo="none">
-		||</command> and precedence parentheses (<command>()</command>).
-	    </para>
-
-	    <section id="operators">
-		<title>Operators and Operands</title>
-		<para>
-		    There is a set of predefined operators and operands
-		    in ser, which in addition to actions may be evaluated
-		    in conditional expressions. 
-		</para>
-		<para>
-		    Left hand-side operands, which <application>ser</application>
-		    understands are the following:
-		    <itemizedlist>
-			<listitem>
-			    <para>
-				<emphasis>method</emphasis>, which refers to 
-				request method
-				such as REGISTER or INVITE
-			    </para>
-			</listitem>
-			<listitem>
-			    <para>
-				<emphasis>uri</emphasis>, which refers to current request URI,
-				such as 
-				"sip:[email protected]"
-				<note>
-				    <para>
-					Note that "uri" always refers to current
-					value of URI, which is subject to change
-					be uri-rewriting actions.
-				    </para>
-				</note>
-			    </para>
-			</listitem>
-			<listitem>
-			    <para>
-				<emphasis>src_ip</emphasis>, which refers to IP address from 
-				which a request came.
-			    </para>
-			</listitem>
-			<listitem>
-			    <para>
-				<emphasis>dst_ip</emphasis> refers to server's IP address 
-				at which a request was received
-			    </para>
-			</listitem>
-			<listitem>
-			    <para>
-				<emphasis>src_port</emphasis> port number from which a SIP
-				request came
-			    </para>
-			</listitem>
-		    </itemizedlist>
-		</para>
-		<para>
-		    ser understands the following operators:
-		    <itemizedlist>
-			<listitem>
-			    <para>
-				== stands for equity
-			    </para>
-			    
-			</listitem>
-			<listitem>
-			    <para>
-				=~ stands for regular expression matching
-			    </para>
-			</listitem>
-			<listitem>
-			    <para>
-				logical operators: and, or, negation, parentheses
-				(C-notation for the operators may be used too)
-			    </para>
-			</listitem>
-		    </itemizedlist>
-		</para>
-
-	    <table id="logicalexpr">
-		<title>Valid Combinations of Operands and Operators in Expressions</title>
-		<tgroup cols="4">
-		    <thead>
-			<row>
-			    <entry>
-				left-hand-side operand
-			    </entry>			    
-			    <entry>
-				valid operators
-			    </entry>
-			    <entry>
-				valid right-hand side operators
-			    </entry>
-			    <entry>
-				examples/comments
-			    </entry>
-			</row>
-
-		    </thead>
-		    <tbody>
-
-			<row>
-			    <entry>
-				method
-			    </entry>			    
-			    <entry>
-				== (exact match), =~ (regular expression matching)
-			    </entry>
-			    <entry>
-				string
-			    </entry>
-			    <entry>
-				method=="INVITE" || method=="ACK" || method=="CANCEL"
-			    </entry>
-			</row>			
-
-			<row>
-			    <entry>
-				uri
-			    </entry>			    
-			    <entry>
-				== (exact match), =~ (regular expression matching)
-			    </entry>
-			    <entry>
-				string
-			    </entry>
-			    <entry>
-				uri=="sip:[email protected]" matches only if exactly this uri
-				is in request URI
-
-			    </entry>
-			</row>				
-
-			<row>
-			    <entry>
-				
-			    </entry>			    
-			    <entry>
-				== (exact match)
-			    </entry>
-			    <entry>
-				myself
-			    </entry>
-			    <entry>
-				
-				the expression uri==myself is true if the host part in 
-				request URI equals a server name or a server alias (set using
-				the alias option in configuration file)
-				
-			    </entry>
-			</row>				
-
-			<row>
-			    <entry>
-				src_ip
-			    </entry>			    
-			    <entry>
-				== (match)
-			    </entry>
-			    <entry>
-				IP, IP/mask_length, IP/mask, hostname, myself
-			    </entry>
-			    <entry>
-				src_ip==192.168.0.0/16 matches requests coming from
-				a private network
-			    </entry>
-			</row>
-
-			<row>
-			    <entry>
-				dst_ip				
-			    </entry>			    
-			    <entry>
-				== (match)
-			    </entry>
-			    <entry>
-				IP, IP/mask_length, IP/mask, hostname, myself
-			    </entry>
-			    <entry>
-				dst_ip==127.0.0.1 matches if a request was received
-				via loopback interface
-			    </entry>
-			</row>
-
-			<row>
-			    <entry>
-				    src_port
-			    </entry>			    
-			    <entry>
-				== (match)
-			    </entry>
-			    <entry>
-				port number
-			    </entry>
-			    <entry>
-				port number from which a request was sent, e.g. src_port==5060
-			    </entry>
-			</row>			    
-
-
-		    </tbody>
-		</tgroup>
-	    </table>
-	    
-
-		<example>
-		    <title>
-			More examples of use of <application>ser</application> operators and operands in conditional
-			statements
-		    </title>
-		    <programlisting format="linespecific">
-# using an action as condition input; in this
-# case, an actions 'search' looks for Contacts
-# with private IP address in requests; the condition
-# is processed if such a contact header field is
-# found
-
-if (search("^(Contact|m): .*@(192\.168\.|10\.|172\.16)")) {
-# .... 
-
-# this condition is true if request URI matches
-# the regular expression "@bat\.iptel\.org"
-    if (uri=~"@bat\.iptel\.org") {
-# ...
-
-# and this condition is true if a request came
-# from an IP address (useful for example for
-# authentication by IP address if digest is not
-# supported) AND the request method is INVITE
-
-# if ( (src_ip==192.68.77.110 and method=="INVITE")
-# ...
-</programlisting>
-		</example>
-	    </section> <!-- operators and operands -->
-	    <section>
-		<title>URI Matching</title>
-		<para>URI matching expressions have a broad use in a SIP server
-		    and deserve more explanation. Typical uses of
-		    URI matching include implementation of numbering plans,
-		    domain matching,
-		    binding external applications to specific URIs,
-		    etc. This section shows examples of typical applications
-		    of URI-matching.
-		</para>
-		<section id="domainmatching">
-		    <title>Domain Matching</title>
-		    <para>
-			One of most important uses of URI matching is deciding
-			whether a request is targeted to a served or outside domain.
-			Typically, different request
-			processing applies. Requests for outside domains
-			are simply forwarded to them, whereas
-			more complex logic applies to requests for a served domain.
-			The logic may include saving user's contacts
-			when REGISTER requests are received, forwarding requests
-			to current user's location or a PSTN gateways, 
-			interaction with external applications, etc.
-		    </para>
-		    <para>
-			The easiest way to decide whether a request belongs
-			a served domain is using the <command moreinfo="none">myself</command>
-			operand. 
-			The expression "uri==myself" returns true if domain name
-			in request URI matches name of the host at which
-			<application moreinfo="none">ser</application> is
-			running. This may be insufficient in cases when
-			server name is not equal to domain name for which the server
-			is responsible. For example, the "uri==myself" condition
-			does not match if a server "sipserver.foo.bar" 
-			receives a request for "sip:[email protected]". To
-			match other names in URI than server's own,
-			set up the <varname>alias</varname> configuration
-			option. The option may be used multiple times,
-			each its use adds a new item to a list of aliases.
-			The myself condition returns then  true 
-			also for any hostname on the list of aliases.
-			<example>
-			    <title>Use of uri==myself Expression</title>
-			    <programlisting format="linespecific">
-# ser powers a domain "foo.bar" and runs at host sipserver.foo.bar;
-# Names of served domains need to be stated in the aliases
-# option; myself would not match them otherwise and would only
-# match requests with "sipserver.foo.bar" in request-URI
-alias="foo.bar"
-alias="sales.foo.bar"
-route[0] {
-        if (uri==myself) {
-            # the request either has server name or some of the
-            # aliases in its URI
-            log(1,"request for served domain")
-            # some domain-specific logic follows here ....
-        } else {
-            # aha -- the server is not responsible for this
-            # requests; that happens for example with the following URIs
-            #  - sip:[email protected]
-            #  - sip:[email protected]
-            log(1,"request for outbound domain");
-            # outbound forwarding			  
-            t_relay();
-        };
-}			</programlisting>
-		    </example>
-		</para>
-		<para>
-		    It is possible to recognize whether a request belongs to
-		    a domain using regular expressions too. Care needs to
-		    be paid to construction of regular expressions. URI
-		    syntax is rich and an incorrect expression would result
-		    in incorrect call processing. The following example shows
-		    how an expression for domain matching can be formed.
-		    <example id="redomainmatching">
-			<title>Domain Matching Using Regular Expressions</title>
-			<para>
-			    In this example, server named "sip.foo.bar" with
-			    IP address 192.168.0.10 is responsible for the
-			    "foo.bar" domain. That means, requests with the
-			    following hostnames in URI should be matched:
-			    <itemizedlist>
-				<listitem>
-				    <para>
-					foo.bar, which is the name of server domain
-				    </para>
-				</listitem>
-				<listitem>
-				    <para>
-					sip.foo.bar, since it is server's name and some
-					devices put server's name in request URI
-				    </para>
-				</listitem>
-				<listitem>
-				    <para>
-					192.168.0.10, since it is server's IP address and
-					some devices put server's IP address in request URI
-				    </para>
-				</listitem>
-			    </itemizedlist>			
-			    Note how this regular expression is constructed. In particular:
-			    <itemizedlist>
-				<listitem>
-				    <para>
-					User name is optional (it is for example never included
-					in REGISTER requests) and there are no restrictions on
-					what characters it contains. That is what 
-					<emphasis>(.+@)?</emphasis> mandates. 
-				    </para>
-				</listitem>
-				<listitem>
-				    <para>
-					Hostname must be followed by port number, parameters
-					or headers -- that is what the delimiters 
-					<emphasis>[:;\?]</emphasis> are good for. If none
-					it these follows, the URI must be ended 
-					(<emphasis>$</emphasis>). Otherwise, longer hostnames
-					such as 192.168.0.101 or foo.bar.otherdomain.com would
-					mistakenly match.
-				    </para>
-				</listitem>
-				<listitem>
-				    <para>
-					Matches are case-insensitive. All hostnames "foo.bar", "FOO.BAR"
-					and "FoO.bAr" match.
-				    </para>
-				</listitem>
-			    </itemizedlist>
-			</para>
-			<programlisting>
-if (uri=~"^sip:(.+@)?(192\.168\.0\.10|(sip\.)?foo\.bar)([:;\?].*)?$")
-      log(1, "yes, it is a request for our domain");
-      break;
- };
-			</programlisting>
-		    </example>
-		</para>
-		</section> <!-- domain matching -->
-		<section id="numberingplans">
-		    <title>Numbering Plans</title>
-
-		    <para>
-			Other use of URI matching is implementation of dialing
-			plans. A typical task when designing a dialing plan for SIP networks
-			is to distinguish between "pure-IP" and PSTN destinations.
-			IP users typically have either alphanumerical or numerical
-			usernames. The numerical usernames are convenient for PSTN
-			callers who can only
-			use numeric keypads. Next-hop destination of IP users is looked up dynamically
-			using user location database. On the other hand, PSTN destinations are 
-			always indicated by numerical usernames. Requests to PSTN are statically 
-			forwarded to well-known PSTN gateways.
-		    </para>
-		    <example>
-			<title>A simple Numbering Plan</title>
-			<para>
-			    This example shows a simple dialing plan which reserves
-			    dialing prefix "8" for IP users, other numbers
-			    are used for PSTN destinations and all other non-numerical
-			    usernames are used for IP users.
-			</para>
-			<programlisting format="linespecific">
-# is it a PSTN destination? (is username numerical and does not begin with 8?)
-if (uri=~"^sip:[0-79][0-9]*@") { # ... forward to gateways then;
-      # check first to which PSTN destination the requests goes;
-      # if it is US (prefix "1"), use the gateway 192.168.0.1...
-      if (uri=~"^sip:1") {
-           # strip the leading "1"
-           strip(1);
-           forward(192.168.0.1, 5060);
-      } else {
-           # ... use the gateway 10.0.0.1 for all other destinations
-           forward(10.0.0.1, 5060);
-      }
-      break;
-} else {
-      # it is an IP destination -- try to lookup it up in user location DB
-      if (!lookup("location")) {
-          # bad luck ... user off-line
-          sl_send_reply("404", "Not Found");
-          break;
-      }
-      # user on-line...forward to his current destination
-      forward(uri:host,uri:port);
-}
-			</programlisting>
-		    </example>
-		</section> <!-- numbering plans -->
-	    </section>
-	</section> <!-- conditional statements -->
-	
-	<section id="urirewriting">
-	    <title>Request URI Rewriting</title>
-
-	    <para>
-		The ability to give users and services a unique name using URI
-		is a powerful tool. It allows users to advertise how to reach
-		them, to state to whom they wish to communicate and what services 
-		they wish to use.
-		Thus, the ability to change URIs is very important and is
-		used for implementation of many services. 
-		"Unconditional forwarding" from user "boss" to user
-		"secretary" is a typical example of application relying
-		on change of URI address.
-	    </para>
-	    <para>
-		<application moreinfo="none">ser</application> has the ability
-		to change request URI in many ways.
-		A script can use any of the following
-		built-in actions to change request URI or a part of it:
-
-		<command>rewriteuri</command>, 
-		<command>rewritehost</command>, 
-		<command>rewritehostport</command>, 
-		<command>rewriteuser</command>, 
-		<command>rewriteuserpass</command> and 
-		<command>rewriteport</command>. 
-		When later in the script
-		a forwarding action is encountered, the action forwards
-		the request to address in the rewritten URI.
-		<example>
-		    <title>Rewriting URIs</title>
-		    <programlisting format="linespecific">
-if (uri=~"[email protected]") {
-    rewriteuri("sip:[email protected]")
-    # forward statelessly to the destination in current URI, i.e.,
-    # to sip:[email protected]:5060
-    forward( uri:host, uri:port);
-}
-		    </programlisting>
-		</example>
-	    </para>	    
-	    <para>Two more built-in URI-rewriting commands are of special importance
-		for implementation of dialing plans and manipulation of dialing
-		prefixes. <command>prefix(s)
-		</command>, inserts 
-		a string "s" in front of SIP address and 
-		<command>strip(n)</command> takes
-		away the first "n" characters of a SIP address.
-		See <xref linkend="urirewritingexamples"> for examples of use of
-		built-in URI-rewriting actions.
-	    </para>
-
-	    <para>
-		Commands exported by external modules can change URI too
-		and many do so.
-		The most important application is changing URI using the
-		user location database. The command 
-		<command>lookup(table)</command> looks up current
-		user's location and rewrites user's address with it.
-		If there is no registered contact, the 	command returns a negative value.
-
-
-		<example id=rewriteuri>
-		    <title>Rewriting URIs Using User Location Database</title>
-		    <programlisting format="linespecific">
-# store user location if a REGISTER appears
-if (method=="REGISTER") {
-   save("mydomain1");
-} else {
-# try to use the previously registered contacts to
-# determine next hop
-   if(lookup("mydomain1")) {
-     # if found, forward there...
-     t_relay();
-   } else {
-     # ... if no contact on-line, tell it upstream
-     sl_send_reply("404", "Not Found" );
-   };
-};
-		    </programlisting>
-		</example>
-	    </para>
-	    <para>
-		External applications can be used to rewrite URI too.
-		The "exec" module provides script actions, which start external programs
-		and read new URI value from their output. <command moreinfo="none">exec_dset</command>
-		both calls an external program, passes SIP request elements to it, waits until it completes,
-		and eventually rewrites current destination set with its output.
-	    </para>
-	    <para>
-		It is important to realize that <application moreinfo="none">ser</application>
-		operates over <emphasis>current URI</emphasis> all the time. If an original
-		URI is rewritten by a new one, the original will will be forgotten and the new one will 
-		be used in any further processing. In particular, the uri matching operand
-		and the user location action <command moreinfo="none">lookup</command>
-		always take current URI as input, regardless what the original URI was.
-	    </para>
-	    <para>
-		<xref linkend="urirewritingexamples"> shows how URI-rewriting actions affect 
-		an example URI, sip:[email protected]:6060.
-		<table id="urirewritingexamples">
-		    <title>URI-rewriting Using Built-In Actions</title>
-		    <tgroup cols="2">
-			<thead>
-			    <row>
-				<entry>
-				    Example Action
-				</entry>				
-				<entry>
-				    Resulting URI
-				</entry>
-			    </row>
-			</thead>
-			<tbody>
-			    <row>
-				<entry>
-				    <command moreinfo="none">rewritehost("192.168.0.10")</command> rewrites
-				    the hostname in URI, other parts (including port number) remain unaffected.
-				</entry>
-				<entry>
-				    sip:[email protected]:6060
-				</entry>
-			    </row>
-			    <row>
-				<entry>
-				    <command moreinfo="none">rewriteuri("sip:[email protected]");</command> rewrites
-				    the whole URI completely.
-				</entry>
-				<entry>
-				    sip:[email protected]
-				</entry>
-			    </row>
-			    <row>
-				<entry>
-				    <command moreinfo="none">rewritehostport("192.168.0.10:3040")</command>rewrites 
-				    both hostname and port number in URI.
-				</entry>
-				<entry>
-				    sip:[email protected]:3040
-				</entry>
-			    </row>
-			    <row>
-				<entry>
-				    <command moreinfo="none">rewriteuser("alice")</command> rewrites user part of URI.
-				</entry>
-				<entry>
-				    sip:[email protected]:6060
-				</entry>
-			    </row>
-			    <row>
-				<entry>
-				    <command moreinfo="none">rewriteuserpass("alice:pw")</command> replaces the pair
-				    user:password in URI with a new value. Rewriting password in URI is of historical
-					meaning though, since basic password has been replaced with digest authentication.
-				</entry>
-				<entry>
-				    sip:alice:[email protected]:6060
-				</entry>
-			    </row>
-			    <row>
-				<entry>
-				    <command moreinfo="none">rewriteport("1234")</command> replaces port number in URI
-				</entry>
-				<entry>
-				    sip:[email protected]:1234
-				</entry>
-			    </row>
-			    <row>
-				<entry>
-				    <command moreinfo="none">prefix("9")</command> inserts a string ahead of user part of URI
-				</entry>
-				<entry>
-				    sip:[email protected]:6060
-				</entry>
-			    </row>
-			    <row>
-				<entry>
-				    <command moreinfo="none">strip(2)</command> removes leading characters from user part of URI
-				</entry>
-				<entry>
-				    sip:[email protected]:6060
-				</entry>
-			    </row>
-
-
-			</tbody>
-		    </tgroup>
-		</table>
-	    </para>	    
-	    <para>
-		You can verify whether you understood URI processing by
-		looking at the following example. It rewrites URI
-		several times. The question is what is the final URI to which
-		the script fill forward any incoming request.
-		<example>
-		    <title>URI-rewriting Exercise</title>
-		    <programlisting format="linespecific">
-exec_dset("echo sip:[email protected]; echo > /dev/null");
-strip(2);
-if (uri=~"^sip:2") {
-    prefix("0");
-} else {
-    prefix("1");
-};			
-forward(uri:host, uri:port);
-		    </programlisting>
-		</example>
-	    </para>
-	    <para>
-		The correct answer is the resulting URI will be
-		"sip:[email protected]". <command moreinfo="none">exec_dset</command>
-		rewrites original URI to "sip:[email protected]", 
-		<command moreinfo="none">strip(2)</command> takes
-		two leading characters from username away resulting
-		in "[email protected]", the condition does not match
-		because URI does not begin with "2" any more,
-		so the prefix "1" is inserted.
-	    </para>
-
-
-	</section> <!-- URI rewriting -->
-
-	<section>
-	    <title>Destination Set</title>
-	    <para>
-		Whereas needs of many scenarios can by accommodated by maintaining
-		a single request URI, some scenarios are better served by
-		multiple URIs. Consider for example a user with address
-		[email protected]. The user wishes to be reachable at his 
-		home phone, office phone, cell phone, softphone, etc. 
-		However, he still wishes to maintain a single public address
-		on his business card.
-	    </para>
-	    <para>
-		To enable such scenarios, <application>ser</application>
-		allows translation of a single request URI into multiple
-		outgoing URIs. The ability to forward a request to multiple
-		destinations is known as <emphasis>forking</emphasis>
-		in SIP language. All outgoing URIs (in trivial case one of them)
-		are called <emphasis>destination set</emphasis>. The destination
-		set always includes one default URI, to which additional URIs
-		can be appended. Maximum size of a destination set is limited by 
-		a compile-time constant, MAX_BRANCHES,
-		in <filename moreinfo="none">config.h</filename>.
-	    </para>
-	    <para>
-		Some actions are designed for use with a single URI whereas
-		other actions work with the whole destination set.
-	    </para>
-	    <para>
-		Actions which are currently available for creating the destination
-		set are <command>lookup</command> from usrloc module and 
-		<command>exec_dset</command> from exec module.
-		<command moreinfo="none">lookup</command> fills in the destination
-		set with user contact's registered previously with REGISTER
-		requests. The <command moreinfo="none">exec</command> actions
-		fill in the destination set with output of an external program.
-		In both cases, current destination set is completely rewritten.		
-		New URIs can be appended to destination set by a call to the built-in
-		action <command>append_branch(uri)</command>.
-	    </para>
-	    <para>		
-		Currently supported features which utilize destination sets
-		are <emphasis>forking</emphasis> and <emphasis>redirection</emphasis>. 
-		Action <command>t_relay</command> (TM module) for stateful
-		forwarding supports forking. If called with a non-trivial destination
-		set, <command moreinfo="none">t_relay</command> forks
-		incoming request to all URIs in current destination set.
-		See <xref linkend="rewriteuri">. If a user
-		previously registered from three locations, the destination set is filled with 
-		all of them by <command>lookup</command> and the <command>t_relay</command>
-		command forwards the incoming request to all these destinations.
-		Eventually, all user's phone will be ringing in parallel.
-	    </para>
-	    <para>
-		SIP redirection is another feature which leverages destination sets.
-		It is a very light-weighted method to establish communication
-		between two parties with minimum burden put on the server. In
-		<application>ser</application>, the action <command>sl_send_reply</command>
-		(SL module) is used for this purpose. This action 
-		allows to generate replies to SIP requests without keeping 
-		any state. If the status code passed to the action is 3xx, 
-		the current destination set is printed in reply's Contact header
-		fields. Such a reply instructs the originating client to 
-		retry at these addresses. (See <xref linkend="redirectexample">).
-	    </para>
-	    <para>
-		Most other  <application>ser</application> actions ignore destination
-		sets: they either do not relate to URI processing (<command moreinfo="none">
-		log</command>, for example) or they work only with the default URI.
-		All URI-rewriting functions such as
-		<command moreinfo="none">rewriteuri</command> belong in this
-		category. URI-comparison operands only refer to the first URI
-		(see <xref linkend="operators">). Also, the built-in action
-		for stateless forwarding, <command>forward</command> works only
-		with the default URI and ignores rest of the destination set. The reason 
-		is a proxy server willing to fork must guarantee that the burden
-		of processing multiple replies is not put unexpectedly on upstream
-		client. This is only achievable with stateful processing.  
-		Forking cannot be used along with stateless <command>forward</command>,
-		which thus only processes one URI out of the whole destination set.
-	    </para> 
-
-	</section> <!-- Destination Set -->
-
-	<section>
-	    <title>User Location</title>
-	    <para>
-		Mobility is a key feature of SIP. Users are able to use one
-		one or more SIP devices and be reachable at them. Incoming requests 
-		for users are forwarded to all user's devices in use. The key
-		concept is that of soft-state registration. Users can
-		-- if in possession of valid credentials -- link SIP
-		devices to their e-mail like address of record. Their SIP devices
-		do so using a REGISTER request, as in <xref linkend="register">.
-		The request creates a binding between the public address of
-		record (To header field) and SIP device's current address
-		(Contact header field). 
-		<example id="register">
-		    <title>REGISTER Request</title>
-		    <programlisting format="linespecific">
-REGISTER sip:192.168.2.16 SIP/2.0
-Via: SIP/2.0/UDP 192.168.2.16;branch=z9hG4bKd5e5.5a9947e4.0
-Via: SIP/2.0/UDP 192.168.2.33:5060
-From: sip:[email protected]
-To: sip:[email protected]
-Call-ID: [email protected]
-Date: Wed, 29 Jan 2003 18:13:15 GMT
-CSeq: 101 REGISTER
-User-Agent: CSCO/4
-Contact: sip:[email protected]:5060
-Content-Length: 0
-Expires: 600
-		    </programlisting>
-		</example>
-		Similar requests can be used to query all user's current contacts or to
-		delete them. All Contacts have certain time to live, when the time expires,
-		contact is removed and no longer used for processing of incoming requests.
-	    </para>
-	    <para>
-		<application moreinfo="none">ser</application> is built to do both: update
-		user location database from received REGISTER requests and look-up these
-		contacts when inbound requests for a user arrive. To achieve high performance,
-		the user location table is stored in memory. In regular intervals
-		(usrloc module's parameter <varname>timer_interval</varname> determines
-		their length), all changes to the in-memory table are backed up in
-		<application moreinfo="none">mysql</application> database to achieve
-		persistence across server reboots. Administrators or application writers
-		can lookup list of current user's contacts stored in memory using the
-		<application moreinfo="none">serctl</application> tool (see <xref linkend="serctl">).
-		<example>
-		    <title>Use of <application>serctl</application> Tool to Query User Location</title>
-		    <screen format="linespecific">
-<![CDATA[
-[jiri@fox jiri]$ sc ul show jiri
-<sip:[email protected]>;q=0.00;expires=456
-<sip:[email protected]>;q=0.00;expires=36000
-]]>
-		    </screen>
-		</example>
-	    </para>
-	    <para>
-		Building user location in <application moreinfo="none">ser</application> scripts is
-		quite easy. One first needs to determine whether a request is for served domain,
-		as described in <xref linkend="domainmatching">. If that is the case, the script
-		needs to distinguish between REGISTER requests, that update user location table,
-		and all other requests for which next hop is determined from the table. The
-		<command moreinfo="none">save</command> action is used to update user location
-		(i.e., it writes to it). The <command moreinfo="none">lookup</command> actions
-		reads from the user location table and fills in destination set with current
-		user's contacts.
-		<example>
-		    <title>Use of User Location Actions</title>
-		    <programlisting format="linespecific">
-# is the request for my domain ?
-if (uri==myself) {
-    if (method=="REGISTER") { # REGISTERs are used to update
-         save("location");
-         break; # that's it, we saved the contacts, exit now
-    } else {
-         if (!lookup("location") { # no registered contact
-            sl_send_reply("404", "Not Found");
-            break;
-         }
-         # ok -- there are some contacts for the user; forward
-         # the incoming request to all of them
-         t_relay();
-    };
-};
-		    </programlisting>
-		</example>
-	    </para>
-	    <para>
-		Note that we used the action for stateful forwarding, 
-		<command moreinfo="none">t_relay</command>. That's because
-		stateful forwarding allows to fork an incoming request to
-		multiple destinations. If we used stateless forwarding,
-		the request would be forwarded only to one uri out of
-		all user's contacts.
-	    </para>
-	</section> <!-- User Location -->
-	
-	<section>
-	    <title>External Modules</title>
-	    <para>
-		<application moreinfo="none">ser</application> provides the ability to link the server with external
-		third-party shared libraries. Lot of functionality which is
-		included in the <application moreinfo="none">ser</application> distribution is actually located in
-		modules to keep the server "core" compact and clean.
-		Among others, there are modules for checking max_forwards
-		value in SIP requests (maxfwd), transactional processing (tm),
-		record routing (rr), accounting (acc), authentication (auth),
-		SMS gateway (sms), replying requests (sl), user location
-		(usrloc, registrar) and more.
-	    </para>
-	    <para>
-		In order to utilize new actions exported by a module, 
-		ser must first load it. To load a module, the directive
-		<command moreinfo="none">loadmodule "filename"</command>
-		must be included in beginning of
-		a <application>ser</application> script file.
-	    </para>
-
-	    <example>
-		<title>Using Modules</title>
-		<para>
-		    This example shows how a script instructs 
-		    <application moreinfo="none">ser</application> to
-		    load a module and use actions exported by it.
-		    Particularly, the sl module exports an action
-		    <command>sl_send_reply</command> which makes 
-		    <application>ser</application> act as a stateless
-		    user agent and reply all incoming requests with 404.
-		</para>
-		<programlisting format="linespecific">
-# first of all, load the module!
-loadmodule "/usr/lib/ser/modules/sl.so
-route{
-    # reply all requests with 404
-    sl_send_reply("404", "I am so sorry -- user not found");
-}
-</programlisting>
-	    </example>
-	    <note>
-		<para>Note that unlike with core commands, all actions
-		    exported by modules must have parameters enclosed
-		    in quotation marks in current version of 
-		    <application moreinfo="none">ser</application>.
-		    In the following example, the built-in action
-		    <command moreinfo="none">forward</command> for
-		    stateless forwarding takes
-		    IP address and port numbers as parameters without
-		    quotation marks whereas a module action 
-		    <command moreinfo="none">t_relay</command> for
-		    stateful forwarding takes parameters enclosed in
-		    quotation marks.
-		    <example>
-			<title>Parameters in built-in and exported
-			actions</title>
-			<programlisting format="linespecific">
-# built-in action doesn't enclose IP addresses and port numbers
-# in quotation marks
-forward(192.168.99.100, 5060);
-# module-exported functions enclose all parameters in quotation
-# marks
-t_relay_to_udp("192.168.99.100", "5060");
-			</programlisting>
-		    </example>
-		</para>
-	    </note>
-	    <para>
-		Many modules also allow users to change the way how they
-		work using predefined parameters. For example, the
-		authentication module needs to know location of MySQL
-		database which contains users' security credentials.
-		How module parameters
-		are set using the <command moreinfo="none">modparam</command>
-		directive is shown in <xref linkend="moduleparameters">. 
-		<command moreinfo="none">modparam</command>
-		always contains identification of module, parameter
-		name and parameter value. Description of parameters
-		available in modules is available in module documentation.
-	    </para>
-	    <para>
-		Yet another thing to notice in this example is module
-		dependency. Modules may depend on each other. For example,
-		the authentication modules leverages the mysql module
-		for accessing mysql databases and sl module for generating
-		authentication challenges. We recommend that modules are
-		loaded in dependency order to avoid ambiguous server
-		behavior.
-	    </para>	    
-	    <para>
-		<example id="moduleparameters">
-		    <title>Module Parameters</title>
-		    <programlisting format="linespecific">
-# ------------------ module loading ----------------------------------
-
-# load first modules on which 'auth' module depends;
-# sl is used for sending challenges, mysql for storage
-# of user credentials
-loadmodule "modules/sl/sl.so"
-loadmodule "modules/mysql/mysql.so"
-loadmodule "modules/auth/auth.so"
-
-# ------------------ module parameters -------------------------------
-# tell the auth module the access data for SQL database:
-# username, password, hostname and database name
-modparam("auth", "db_url","mysql://ser:secret@dbhost/ser")
-
-
-# -------------------------  request routing logic -------------------
-
-# authenticate all requests prior to forwarding them
-
-route{
-
-        if (!proxy_authorize("foo.bar" /* realm */,
-                        "subscriber" /* table name */ )) {
-                proxy_challenge("foo.bar", "0");
-                break;
-        };
-        forward(192.168.0.10,5060);
-}
-
-		    </programlisting>
-		</example>
-	    </para>
-	</section>
-
-	<section>
-	    <title>Writing Scripts</title>
-	    <para>
-		This section demonstrates simple examples
-		how to configure server's behavior using the
-		<application moreinfo="none">ser</application>
-		request routing language. All configuration scripts follow the 
-		<application moreinfo="none">ser</application> language 
-		syntax, which dictates the following section ordering:
-		<itemizedlist>
-		    <listitem>
-			<para>
-			    <emphasis>global configuration parameters</emphasis> --
-			    these value affect behavior of the server such as port
-			    number at which it listens, number of spawned children
-			    processes, and log-level. See <xref linkend="coreoptions">
-			    for a list of available options.
-			</para>
-		    </listitem>
-
-		    <listitem>
-			<para>
-			    <emphasis>module loading</emphasis> -- these statements
-			    link external modules, such as transaction management
-			    (tm) or stateless UA server (sl)  dynamically. See
-			    <xref linkend="modulereference"> for a list of modules
-			    included in <application moreinfo="none">ser</application>
-			    distribution.
-			</para>
-			<note>
-				<para>
-					If modules depend on each other, than the depending
-					modules must be loaded after modules on which they
-					depend. We recommend to load first modules
-					<command>tm</command> and <command>sl</command>
-					because many other modules (authentication, user
-					location, accounting, etc.) depend on these.
-				</para>
-			</note>
-		    </listitem>
-		    <listitem>
-			<para>
-			    <emphasis>module-specific parameters</emphasis> -- determine
-			    how modules behave; for example, it is possible to configure
-			    database to be used by authentication module.
-			</para>
-		    </listitem>
-		    <listitem>
-			<para>
-			    one or more <emphasis>route blocks</emphasis> containing the
-			    request processing logic, which includes built-in actions
-			    as well as actions exported by modules. See <xref linkend="builtinref">
-			    for a list of built-in actions.
-			</para>
-		    </listitem>
-		    <listitem>
-			<para>
-			    optionally, if modules supporting reply
-			    processing (currently only TM) are loaded,
-			    one or more <emphasis>failure_route blocks</emphasis> containing
-			    logic triggered by received replies. Restrictions on use of
-			    actions within <command moreinfo="none">failure_route</command>
-			    blocks apply -- see <xref linkend="builtinref"> for more
-			    information.
-			</para>
-		    </listitem>
-		</itemizedlist>
-	    </para>
-
-	    <section id="defaultscript">
-		<title>Default Configuration Script</title>		
-		<para>
-		    The configuration script, <filename moreinfo="none">ser.cfg</filename>,
-		    is a part of every <application moreinfo="none">ser</application>
-		    distribution and defines default behavior. It allows users
-		    to register with the server and have requests proxied to each
-		    other.
-		</para>
-		<para>
-		    After performing
-		    routine checks, the script looks whether incoming request is for
-		    served domain. If so and the request is "REGISTER", <application moreinfo="none">ser</application>
-		    acts as SIP registrar and updates database of user's contacts.
-		    Optionally, it verifies user's identity first to avoid
-		    unauthorized contact manipulation.
-		</para>
-		<para>
-		    Non-REGISTER requests for served domains are then processed using
-		    user location database. If a contact is found for requested URI,
-		    script execution proceeds to stateful forwarding, a negative 404
-		    reply is generated otherwise. Requests outside served domain
-		    are always statefully forwarded.
-		</para>
-		<para>
-		    Note that this simple script features several limitations:
-		    <itemizedlist>
-			<listitem>			    
-			    <para>
-				By default, authentication is turned off to avoid
-				dependency on mysql. Unless it it turned on, anyone
-				can register using any name and "steal" someone else's
-				calls.
-			    </para>
-			</listitem>
-			<listitem>
-			    <para>
-				Even it authentication is turned on, there is no relationship
-				between authentication username and address of record. That
-				means that for example a user authenticating himself correctly
-				with "john.doe" id may register contacts for "gw.bush".
-				Site policy may wish to mandate authentication id to be equal
-				to username claimed in To header field. <action moreinfo="none">check_to</action>
-				action from auth module can be used to enforce such a policy.
-			    </para>
-			</listitem>
-			<listitem>
-			    <para>
-				There is no dialing plan implemented. All users are supposed to
-				be reachable via user location database. See <xref linkend="numberingplans">
-				for more information.
-			    </para>
-			</listitem>
-			<listitem>
-			    <para>
-				The script assumes users will be using server's name as a part of
-				their address of record. If users wish to use another name (domain
-				name for example), this must be set using the <varname>alias</varname>
-				options. See <xref linkend="domainmatching"> for more information.
-			    </para>
-			</listitem>
-			<listitem>
-			    <para>
-				If authentication is turned on by uncommenting related configuration
-				options, clear-text user passwords will by assumed in back-end database.
-			    </para>
-			</listitem>
-		    </itemizedlist>
-		</para>
-		<example>
-		    <title>Default Configuration Script</title>
-		    <programlisting format="linespecific">
-&defscr;			
-		    </programlisting>
-		</example>
-	    </section>
-
-	    <section id="statefulua">
-		<title>Stateful User Agent Server</title>
-		<para>
-		    This examples shows how to make ser act as a stateful user
-		    agent (UA). Ability to act as as a stateful UA is essential
-		    to many applications which terminate a SIP path. These
-		    applications wish to focus on their added value. They
-		    do not wish to be involved in all SIP gory details, such
-		    as request and reply retransmission, reply formatting, etc.
-		    For example, we use the UA functionality to shield 
-		    SMS gateway and instant message store from SIP transactional
-		    processing.
-		    The simple example bellow issues a log report on receipt
-		    of a new transaction. 
-		    If we did not use a stateful UA, every single request retransmission
-		    would cause the application to be re-executed which would result in
-		    duplicated SMS messages, instant message in message store or 
-		    log reports.
-		</para>
-		<para>
-		    The most important actions are <command moreinfo="none">
-			t_newtran</command> and <command moreinfo="none">
-			t_reply</command>. <command moreinfo="none">
-			
-		    t_newtran</command> shields subsequent code from retransmissions.
-		    It returns success and continues when a new request arrived.
-		    It exits current route block immediately on receipt of
-		    a retransmission. It only returns a negative value when
-		    a serious error, such as lack of memory, occurs.
-		</para>
-		<para>
-		    <command moreinfo="none">t_reply</command> generates
-		    a reply for a request. It generates the reply statefully,
-		    i.e., it is kept for future retransmissions in memory.
-		</para>
-		<note>
-			<para>
-				Applications that do not need stateful processing
-				may act as stateless UA Server too. They just use
-				the <command>sl_send_reply</command> action to
-				send replies to requests without keeping any
-				state. The benefit is memory cannot run out,
-				the drawback is that each retransmission needs to
-				be processed as a new request. An example of use
-				of a stateless server is shown in
-		    	<xref linkend="redirectserver"> and
-		    	<xref linkend="executingscript">.
-			</para>
-		</note>
-		<example>
-		    <title>Stateful UA Server</title>
-		    <programlisting format="linespecific">
-			<!-- ../../examples/uas.cfg -->
-			&statefuluaexample;
-		    </programlisting>
-		</example>
-	    </section> <!-- Stateful UAS -->
-
-	    <section id="redirectserver">
-		<title>Redirect Server</title>
-		<para>
-		    The redirect example shows how to redirect a request
-		    to multiple destination using 3xx reply. Redirecting
-		    requests as opposed to proxying them is essential to
-		    various scalability scenarios. Once a message is
-		    redirected, <application moreinfo="none">ser</application>
-		    discards all related state and is no more involved
-		    in subsequent SIP transactions (unless the redirection
-		    addresses point to the same server again).
-		</para>
-		<para>
-		    The key <application>ser</application> actions in this example 
-		    are <command moreinfo="none">append_branch</command> and 
-		    <command moreinfo="none">sl_send_reply</command> (sl module).
-		</para>
-		<para>
-		    <command moreinfo="none">append_branch</command> adds
-		    a new item to the destination set. The destinations set always
-		    includes the current URI and may be enhanced up to
-		    <constant>MAX_BRANCHES</constant> items.
-		    <command moreinfo="none">sl_send_reply</command> command, 
-		    if passed SIP reply code 3xx, takes all values in current 
-		    destination set and adds them to Contact header field in 
-		    the reply being  sent.
-		</para>
-		<example id="redirectexample">
-		    <title>Redirect Server</title>
-		    <programlisting format="linespecific">
-			<!-- ../../examples/redirect.cfg -->
-			&redirectexample;
-		    </programlisting>
-		</example>
-	    </section> <!-- redirect server-->
-	    
-	    <section id="executingscript">
-		<title>Executing External Script</title>
-		<para>
-		    Like in the previous example, we show how to
-		    make <application>ser</application> act as a redirect server. The difference is 
-		    that we do not use redirection addresses hardwired in
-		    <application moreinfo="none">ser</application> script but
-		    get them from external shell commands. We also use
-		    ser's ability to execute shell commands to log
-		    source IP address of incoming SIP requests.
-		</para>
-		<para>
-		    The new commands introduced in this example are
-		    <command moreinfo="none">exec_msg</command> and
-		    <command moreinfo="none">exec_dset</command>.
-		    <command moreinfo="none">exec_msg</command> takes
-		    current requests, starts an external command, and
-		    passes the requests to the command's standard input.
-		    It also passes request's source IP address in
-		    environment variable named <constant>SRCIP</constant>.
-		</para>
-		<para>
-		    <command moreinfo="none">exec_dset</command> serves
-		    for URI rewriting by external applications.  The
-		    <command moreinfo="none">exec_dset</command> action
-		    passes current URI to the called external program, 
-		    and rewrites current destination
-		    set with the program's output. An example use would
-		    be an implementation of a Least-Cost-Router, software which
-		    returns URI of the cheapest PSTN provider for a given
-		    destination based on some pricing tables. <xref linkend="execscript">
-		    is much easier: it prints fixed URIs on its output using
-		    shell script <command moreinfo="none">echo</command> command.
-		</para>
-		<note>
-			<para>
-				This script works statelessly -- it uses this action for
-				stateless replying, <command>sl_send_reply</command>.
-				No transaction is kept in memory and each request retransmission
-				is processed as a brand-new request. That may be a particular
-				concern if the server logic (<command>exec</command> actions
-				in this example) is too expensive. See 
-		    	<xref linkend="statefulua"> for instructions on how
-				to make server logic stateful, so that retransmissions
-				are absorbed and do not cause re-execution of the logic.
-			
-			</para>
-		</note>
-		<example id="execscript">
-		    <title>Executing External Script</title>
-		    <programlisting format="linespecific">
-			<!-- ../../examples/exec.cfg -->
-			&execexample;
-		    </programlisting>
-		</example>
-	    </section> <!-- exec example -->
-	    
-	    <section id="replyprocessingsection">
-		<title>On-Reply Processing (Forward on Unavailable)</title>
-		<para>
-		    Many services depend on status of messages relayed
-		    downstream: <emphasis>forward on busy</emphasis> and 
-		    <emphasis>forward on no reply</emphasis> to name the
-		    most well-known ones. To support implementation of
-		    such services, <application moreinfo="none">ser</application>
-		    allows to return to request processing when request
-		    forwarding failed. When a request is reprocessed,
-		    new request branches may be initiated or the transaction
-		    can be completed at discretion of script writer.
-		</para>
-		<para>
-		    The primitives used are <command moreinfo="none">t_on_failure(r)</command>
-		    and <command moreinfo="none">failure_route[r]{}.</command> If
-		    <command>t_on_failure</command> is called before
-		    a request is statefully forwarded and a forwarding failure occurs, 
-		    <application moreinfo="none">ser</application>
-		    will return to request processing in a <command moreinfo="none">failure_route</command>
-		    block. Failures include receipt of a SIP error
-		    (status code >= 300 ) from downstream or not receiving
-		    any final reply within final response period.
-		</para>
-		<para>
-		    The length of the timer is governed by parameters of the
-		    tm module. <varname>fr_timer</varname> is the length of
-		    timer set for non-INVITE transactions and INVITE transactions
-		    for which no provisional response is received. If a timer
-		    hits, it indicates that a downstream server is unresponsive.
-		    <varname>fr_inv_timer</varname> governs time to wait for 
-		    a final reply for an INVITE. It is typically longer than
-		    <varname>fr_timer</varname> because final reply may take
-		    long time until callee (finds a mobile phone in a pocket and)
-		    answers the call.
-		</para>
-		<para>
-		    In <xref linkend="replyprocessing">, <command moreinfo="none">failure_route[1]</command>
-		    is set to be entered on error using the <command moreinfo="none">t_on_failure(1)</command>
-		    action. Within this reply block, <application moreinfo="none">ser</application>
-		    is instructed to initiate a new branch and try to reach called party
-		    at another destination (sip:[email protected]). To deal with the case when neither the alternate
-		    destination succeeds, <application moreinfo="none">t_on_failure</application>
-		    is set again. If the case really occurs, <command moreinfo="none">failure_route[2]</command>
-		    is entered and a last resort destination (sip:[email protected]) is tried.
-		</para>
-		<example id="replyprocessing">
-		    <title>On-Reply Processing</title>
-		    <programlisting format="linespecific">
-			<!-- ../../examples/onr.cfg -->
-			&replyexample;
-		    </programlisting>
-
-		</example>
-	    </section> <!-- reply processing -->
-	</section> <!-- examples -->
-    </chapter>

doc/seruser/intro.xml

@@ -0,0 +1,1465 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4//EN"
+                      "file:///usr/share/sgml/docbook/dtd/xml/4/docbookx.dtd">
+
+<section id="introduction" xmlns:xi="http://www.w3.org/2001/XInclude">
+    <sectioninfo>
+	<revhistory>
+	    <revision>
+		<revnumber>$Revision$</revnumber>
+		<date>$Date$</date>
+	    </revision>
+	</revhistory>
+    </sectioninfo>
+
+    <title>Introduction to SER</title>
+
+    <section id="requestrouting">
+	<title>Request Routing and SER Scripts</title>
+	<para>
+	    The most important concept of every SIP server is that of
+	    request routing. The request routing logic determines the next
+	    hop of a request. It can be for example used to implement user 
+	    location service or enforce static routing to a gateway. Real-world
+	    deployments actually ask for quite complex routing logic, which
+	    needs to reflect static routes to PSTN gateways, dynamic routes
+	    to registered users, authentication policy, capabilities of
+	    SIP devices, etc.
+	</para>
+	<para>
+	    SER's answer to this need for routing flexibility is a routing
+	    language, which allows administrators to define the SIP request
+	    processing logic in a detailed manner. They can for example easily
+	    split SIP traffic by method or destination, perform user location, 
+	    trigger authentication, verify access permissions, and so on.
+	</para>
+	<para>
+	    The primary building block of the routing language are <emphasis>actions</emphasis>. 
+	    There are built-in actions (like <command>forward</command> for stateless forwarding
+	    or <command>strip</command> for stripping URIs) as 
+	    well as external actions imported from shared library modules. All actions can 
+	    be combined in compound actions by enclosing them in braces, 
+	    e.g. <command>{a1(); a2();}</command>. 
+	    Actions are aggregated in one or more <emphasis>route blocks</emphasis>.
+	    Initially, only the default routing block denoted by <command>route[0]</command>
+	    is called. Other routing blocks can be called by the action
+	    <command>route(blocknumber)</command>, recursion is permitted.
+	    The language includes <emphasis>conditional statements</emphasis>. 
+	</para>
+
+	<para>
+	    The routing script is executed for every received request in sequential order. 
+	    Actions may return positive/negative/zero value. 
+
+	    Positive values are considered success and evaluated as
+	    TRUE in conditional expressions. Negative values are considered FALSE. 
+
+	    Zero value means error and leaves execution of currently processed
+	    route block. The route block is left too, if <command>break</command> is explicitly
+	    called from it.
+
+	</para>
+	<para>
+	    The easiest and still very useful way for <application>ser</application>
+	    users to affect request routing logic is
+	    to determine next hop statically. An example is
+	    routing to a PSTN gateway whose static IP address is well known.
+	    To configure static routing, simply use the action
+	    <command>forward( IP_address, port_number)</command>.
+	    This action forwards an incoming request "as is" to the
+	    destination described in action's parameters.
+	</para>
+
+	<example>
+	    <title>Static Forwarding</title>
+	    <programlisting>
+# if requests URI is numerical and starts with
+# zero, forward statelessly to a static destination
+
+if (uri=~"^sip:0[0-9]*@iptel.org") {
+    forward( 192.168.99.3, 5080 );
+} 
+	    </programlisting>
+	</example>
+
+	<para>
+	    However, static forwarding is not sufficient in many cases.
+	    Users desire mobility and change their location frequently.
+	    Lowering costs for termination of calls in PSTN requires
+	    locating a least-cost gateway. Which next-hop is taken may
+	    depend on user's preferences. These and many other scenarios
+	    need the routing logic to be more dynamic. We describe in
+	    <xref linkend="conditions"/> how to make request processing
+		subject to various conditions and in 
+		<xref linkend="urirewriting"/> how to determine next SIP hop.
+	</para>
+    </section>
+
+    <section id="conditions">
+	<title>Conditional Statements</title>
+	<para>
+	    A very useful feature is the ability to make routing
+	    logic depend on a condition. A script condition may for
+	    example distinguish between request processing for
+	    served and foreign domains, IP and PSTN routes,
+	    it may split traffic by method or username, it
+	    may determine whether a request should be authenticated
+	    or not, etc. <application>ser</application>
+	    allows administrators to form conditions based on
+	    properties of processed request, such as method or uri,
+	    as well as on virtually any piece of data on the
+	    Internet.
+	</para>
+	<example>
+	    <title>Conditional Statement</title>
+	    <para>
+		This example shows how a conditional statement is
+		used to split incoming requests between a PSTN
+		gateway and a user location server based on
+		request URI.
+	    </para>
+	    <programlisting>
+# if request URI is numerical, forward the request to PSTN gateway...
+if (uri=~"^sip:[0-9][email protected]") { # match using a regular expression
+    forward( gateway.foo.bar, 5060 );
+} else { # ... forward the request to user location server otherwise
+    forward( userloc.foo.bar, 5060 );
+};
+	    </programlisting>
+	</example>
+
+	<para>
+	    Conditional statements in <application>ser</application> scripts may depend
+	    on a variety of  expressions. The simplest expressions are 
+	    action calls. They return true if they completed successfully or false otherwise. 
+	    An example of an action frequently used in conditional statements is
+	    <command moreinfo="none">search</command> imported from textops module.
+	    <command moreinfo="none">search</command> action leverages textual
+	    nature of SIP and compares SIP requests against a regular expression.
+	    The action returns true if the expression matched, false otherwise.
+	    <example>
+		<title>Use of <command>search</command> Action in Conditional Expression</title>
+		<programlisting>
+# prevent strangers from claiming to belong to our domain;
+# if sender claims to be in our domain in From header field,
+# better authenticate him 
+if (search("(f|From): .*@mydomain.com)) {
+    if (!(proxy_authorize("mydomain.com" /* realm */,"subscriber" /* table name */ ))) {
+        proxy_challenge("mydomain.com /* ream */, "1" /* use qop */ );
+        break;
+    }
+}
+		</programlisting>
+	    </example>
+	</para>
+	<para>
+	    As modules may be created, which export new functions, there is virtually
+	    no limitation on what functionality <application>ser</application>
+	    conditions are based on. Implementers may introduce new actions whose
+	    return status depends on request content or any external data as well. Such actions
+	    can query SQL, web, local file systems or any other place which can provide
+	    information wanted for request processing.
+	</para>
+	<para>
+	    Furthermore, many request properties may be examined using existing built-in operands
+	    and operators. Available left-hand-side operands and legal combination with
+	    operators and right-hand-side operands are described in <xref linkend="logicalexpr"/>.
+		Expressions may be grouped together using logical operators:
+		negation (<command>!</command>), AND (<command>&amp;&amp;</command>), OR (<command>
+		    ||</command> and precedence parentheses (<command>()</command>).
+	</para>
+
+	<section id="operators">
+	    <title>Operators and Operands</title>
+	    <para>
+		There is a set of predefined operators and operands
+		in ser, which in addition to actions may be evaluated
+		in conditional expressions. 
+	    </para>
+	    <para>
+		Left hand-side operands, which <application>ser</application>
+		understands are the following:
+		<itemizedlist>
+		    <listitem>
+			<para>
+			    <emphasis>method</emphasis>, which refers to 
+			    request method
+			    such as REGISTER or INVITE
+			</para>
+		    </listitem>
+		    <listitem>
+			<para>
+			    <emphasis>uri</emphasis>, which refers to current request URI,
+			    such as 
+			    "sip:[email protected]"
+			    <note>
+				<para>
+				    Note that "uri" always refers to current
+				    value of URI, which is subject to change
+				    be uri-rewriting actions.
+				</para>
+			    </note>
+			</para>
+		    </listitem>
+		    <listitem>
+			<para>
+			    <emphasis>src_ip</emphasis>, which refers to IP address from 
+			    which a request came.
+			</para>
+		    </listitem>
+		    <listitem>
+			<para>
+			    <emphasis>dst_ip</emphasis> refers to server's IP address 
+			    at which a request was received
+			</para>
+		    </listitem>
+		    <listitem>
+			<para>
+			    <emphasis>src_port</emphasis> port number from which a SIP
+			    request came
+			</para>
+		    </listitem>
+		</itemizedlist>
+	    </para>
+	    <para>
+		ser understands the following operators:
+		<itemizedlist>
+		    <listitem>
+			<para>
+			    == stands for equity
+			</para>
+		    </listitem>
+		    <listitem>
+			<para>
+			    =~ stands for regular expression matching
+			</para>
+		    </listitem>
+		    <listitem>
+			<para>
+			    logical operators: and, or, negation, parentheses
+			    (C-notation for the operators may be used too)
+			</para>
+		    </listitem>
+		</itemizedlist>
+	    </para>
+
+	    <table id="logicalexpr">
+		<title>Valid Combinations of Operands and Operators in Expressions</title>
+		<tgroup cols="4">
+		    <thead>
+			<row>
+			    <entry>
+				left-hand-side operand
+			    </entry>			    
+			    <entry>
+				valid operators
+			    </entry>
+			    <entry>
+				valid right-hand side operators
+			    </entry>
+			    <entry>
+				examples/comments
+			    </entry>
+			</row>
+
+		    </thead>
+		    <tbody>
+
+			<row>
+			    <entry>
+				method
+			    </entry>			    
+			    <entry>
+				== (exact match), =~ (regular expression matching)
+			    </entry>
+			    <entry>
+				string
+			    </entry>
+			    <entry>
+				method=="INVITE" || method=="ACK" || method=="CANCEL"
+			    </entry>
+			</row>			
+
+			<row>
+			    <entry>
+				uri
+			    </entry>			    
+			    <entry>
+				== (exact match), =~ (regular expression matching)
+			    </entry>
+			    <entry>
+				string
+			    </entry>
+			    <entry>
+				uri=="sip:[email protected]" matches only if exactly this uri
+				is in request URI
+
+			    </entry>
+			</row>				
+
+			<row>
+			    <entry>
+				
+			    </entry>			    
+			    <entry>
+				== (exact match)
+			    </entry>
+			    <entry>
+				myself
+			    </entry>
+			    <entry>
+				
+				the expression uri==myself is true if the host part in 
+				request URI equals a server name or a server alias (set using
+				the alias option in configuration file)
+				
+			    </entry>
+			</row>				
+
+			<row>
+			    <entry>
+				src_ip
+			    </entry>			    
+			    <entry>
+				== (match)
+			    </entry>
+			    <entry>
+				IP, IP/mask_length, IP/mask, hostname, myself
+			    </entry>
+			    <entry>
+				src_ip==192.168.0.0/16 matches requests coming from
+				a private network
+			    </entry>
+			</row>
+
+			<row>
+			    <entry>
+				dst_ip				
+			    </entry>			    
+			    <entry>
+				== (match)
+			    </entry>
+			    <entry>
+				IP, IP/mask_length, IP/mask, hostname, myself
+			    </entry>
+			    <entry>
+				dst_ip==127.0.0.1 matches if a request was received
+				via loopback interface
+			    </entry>
+			</row>
+
+			<row>
+			    <entry>
+				src_port
+			    </entry>			    
+			    <entry>
+				== (match)
+			    </entry>
+			    <entry>
+				port number
+			    </entry>
+			    <entry>
+				port number from which a request was sent, e.g. src_port==5060
+			    </entry>
+			</row>			    
+
+
+		    </tbody>
+		</tgroup>
+	    </table>
+
+	    <example>
+		<title>
+		    More examples of use of <application>ser</application> operators and operands in conditional
+		    statements
+		</title>
+		<programlisting>
+# using an action as condition input; in this
+# case, an actions 'search' looks for Contacts
+# with private IP address in requests; the condition
+# is processed if such a contact header field is
+# found
+
+if (search("^(Contact|m): .*@(192\.168\.|10\.|172\.16)")) {
+    # .... 
+
+    # this condition is true if request URI matches
+    # the regular expression "@bat\.iptel\.org"
+    if (uri=~"@bat\.iptel\.org") {
+        # ...
+
+	# and this condition is true if a request came
+	# from an IP address (useful for example for
+	# authentication by IP address if digest is not
+	# supported) AND the request method is INVITE
+
+	# if ( (src_ip==192.68.77.110 and method=="INVITE")
+	# ...
+		</programlisting>
+	    </example>
+	</section> <!-- operators and operands -->
+	<section>
+	    <title>URI Matching</title>
+	    <para>URI matching expressions have a broad use in a SIP server
+		and deserve more explanation. Typical uses of
+		URI matching include implementation of numbering plans,
+		domain matching,
+		binding external applications to specific URIs,
+		etc. This section shows examples of typical applications
+		of URI-matching.
+	    </para>
+	    <section id="domainmatching">
+		<title>Domain Matching</title>
+		<para>
+		    One of most important uses of URI matching is deciding
+		    whether a request is targeted to a served or outside domain.
+		    Typically, different request
+		    processing applies. Requests for outside domains
+		    are simply forwarded to them, whereas
+		    more complex logic applies to requests for a served domain.
+		    The logic may include saving user's contacts
+		    when REGISTER requests are received, forwarding requests
+		    to current user's location or a PSTN gateways, 
+		    interaction with external applications, etc.
+		</para>
+		<para>
+		    The easiest way to decide whether a request belongs
+		    a served domain is using the <command>myself</command>
+		    operand. 
+		    The expression "uri==myself" returns true if domain name
+		    in request URI matches name of the host at which
+		    <application>ser</application> is
+		    running. This may be insufficient in cases when
+		    server name is not equal to domain name for which the server
+		    is responsible. For example, the "uri==myself" condition
+		    does not match if a server "sipserver.foo.bar" 
+		    receives a request for "sip:[email protected]". To
+		    match other names in URI than server's own,
+		    set up the <varname>alias</varname> configuration
+		    option. The option may be used multiple times,
+		    each its use adds a new item to a list of aliases.
+		    The myself condition returns then  true 
+		    also for any hostname on the list of aliases.
+		    <example>
+			<title>Use of uri==myself Expression</title>
+			<programlisting>
+# ser powers a domain "foo.bar" and runs at host sipserver.foo.bar;
+# Names of served domains need to be stated in the aliases
+# option; myself would not match them otherwise and would only
+# match requests with "sipserver.foo.bar" in request-URI
+alias="foo.bar"
+alias="sales.foo.bar"
+route[0] {
+    if (uri==myself) {
+        # the request either has server name or some of the
+        # aliases in its URI
+        log(1,"request for served domain")
+        # some domain-specific logic follows here ....
+    } else {
+        # aha -- the server is not responsible for this
+        # requests; that happens for example with the following URIs
+        #  - sip:[email protected]
+        #  - sip:[email protected]
+        log(1,"request for outbound domain");
+        # outbound forwarding			  
+        t_relay();
+    };
+}
+			</programlisting>
+		    </example>
+		</para>
+		<para>
+		    It is possible to recognize whether a request belongs to
+		    a domain using regular expressions too. Care needs to
+		    be paid to construction of regular expressions. URI
+		    syntax is rich and an incorrect expression would result
+		    in incorrect call processing. The following example shows
+		    how an expression for domain matching can be formed.
+		    <example id="redomainmatching">
+			<title>Domain Matching Using Regular Expressions</title>
+			<para>
+			    In this example, server named "sip.foo.bar" with
+			    IP address 192.168.0.10 is responsible for the
+			    "foo.bar" domain. That means, requests with the
+			    following hostnames in URI should be matched:
+			    <itemizedlist>
+				<listitem>
+				    <para>
+					foo.bar, which is the name of server domain
+				    </para>
+				</listitem>
+				<listitem>
+				    <para>
+					sip.foo.bar, since it is server's name and some
+					devices put server's name in request URI
+				    </para>
+				</listitem>
+				<listitem>
+				    <para>
+					192.168.0.10, since it is server's IP address and
+					some devices put server's IP address in request URI
+				    </para>
+				</listitem>
+			    </itemizedlist>			
+			    Note how this regular expression is constructed. In particular:
+			    <itemizedlist>
+				<listitem>
+				    <para>
+					User name is optional (it is for example never included
+					in REGISTER requests) and there are no restrictions on
+					what characters it contains. That is what 
+					<emphasis>(.+@)?</emphasis> mandates. 
+				    </para>
+				</listitem>
+				<listitem>
+				    <para>
+					Hostname must be followed by port number, parameters
+					or headers -- that is what the delimiters 
+					<emphasis>[:;\?]</emphasis> are good for. If none
+					it these follows, the URI must be ended 
+					(<emphasis>$</emphasis>). Otherwise, longer hostnames
+					such as 192.168.0.101 or foo.bar.otherdomain.com would
+					mistakenly match.
+				    </para>
+				</listitem>
+				<listitem>
+				    <para>
+					Matches are case-insensitive. All hostnames "foo.bar", "FOO.BAR"
+					and "FoO.bAr" match.
+				    </para>
+				</listitem>
+			    </itemizedlist>
+			</para>
+			<programlisting>
+if (uri=~"^sip:(.+@)?(192\.168\.0\.10|(sip\.)?foo\.bar)([:;\?].*)?$")
+    log(1, "yes, it is a request for our domain");
+    break;
+};
+			</programlisting>
+		    </example>
+		</para>
+	    </section> <!-- domain matching -->
+	    <section id="numberingplans">
+		<title>Numbering Plans</title>
+
+		<para>
+		    Other use of URI matching is implementation of dialing
+		    plans. A typical task when designing a dialing plan for SIP networks
+		    is to distinguish between "pure-IP" and PSTN destinations.
+		    IP users typically have either alphanumerical or numerical
+		    usernames. The numerical usernames are convenient for PSTN
+		    callers who can only
+		    use numeric keypads. Next-hop destination of IP users is looked up dynamically
+		    using user location database. On the other hand, PSTN destinations are 
+		    always indicated by numerical usernames. Requests to PSTN are statically 
+		    forwarded to well-known PSTN gateways.
+		</para>
+		<example>
+		    <title>A simple Numbering Plan</title>
+		    <para>
+			This example shows a simple dialing plan which reserves
+			dialing prefix "8" for IP users, other numbers
+			are used for PSTN destinations and all other non-numerical
+			usernames are used for IP users.
+		    </para>
+		    <programlisting>
+# is it a PSTN destination? (is username numerical and does not begin with 8?)
+if (uri=~"^sip:[0-79][0-9]*@") { # ... forward to gateways then;
+    # check first to which PSTN destination the requests goes;
+    # if it is US (prefix "1"), use the gateway 192.168.0.1...
+    if (uri=~"^sip:1") {
+        # strip the leading "1"
+ 	strip(1);
+	forward(192.168.0.1, 5060);
+    } else {
+	# ... use the gateway 10.0.0.1 for all other destinations
+	forward(10.0.0.1, 5060);
+    }
+    break;
+} else {
+    # it is an IP destination -- try to lookup it up in user location DB
+    if (!lookup("location")) {
+        # bad luck ... user off-line
+        sl_send_reply("404", "Not Found");
+        break;
+    }
+    # user on-line...forward to his current destination
+    forward(uri:host,uri:port);
+}
+		    </programlisting>
+		</example>
+	    </section> <!-- numbering plans -->
+	</section>
+    </section> <!-- conditional statements -->
+    
+    <section id="urirewriting">
+	<title>Request URI Rewriting</title>
+
+	<para>
+	    The ability to give users and services a unique name using URI
+	    is a powerful tool. It allows users to advertise how to reach
+	    them, to state to whom they wish to communicate and what services 
+	    they wish to use.
+	    Thus, the ability to change URIs is very important and is
+	    used for implementation of many services. 
+	    "Unconditional forwarding" from user "boss" to user
+	    "secretary" is a typical example of application relying
+	    on change of URI address.
+	</para>
+	<para>
+	    <application>ser</application> has the ability
+	    to change request URI in many ways.
+	    A script can use any of the following
+	    built-in actions to change request URI or a part of it:
+
+	    <command>rewriteuri</command>, 
+	    <command>rewritehost</command>, 
+	    <command>rewritehostport</command>, 
+	    <command>rewriteuser</command>, 
+	    <command>rewriteuserpass</command> and 
+	    <command>rewriteport</command>. 
+	    When later in the script
+	    a forwarding action is encountered, the action forwards
+	    the request to address in the rewritten URI.
+	    <example>
+		<title>Rewriting URIs</title>
+		<programlisting>
+if (uri=~"[email protected]") {
+    rewriteuri("sip:[email protected]")
+    # forward statelessly to the destination in current URI, i.e.,
+    # to sip:[email protected]:5060
+    forward( uri:host, uri:port);
+}
+		</programlisting>
+	    </example>
+	</para>	    
+	<para>Two more built-in URI-rewriting commands are of special importance
+	    for implementation of dialing plans and manipulation of dialing
+	    prefixes. <command>prefix(s)
+	    </command>, inserts 
+	    a string "s" in front of SIP address and 
+	    <command>strip(n)</command> takes
+	    away the first "n" characters of a SIP address.
+	    See <xref linkend="urirewritingexamples"/> for examples of use of
+		built-in URI-rewriting actions.
+	</para>
+
+	<para>
+	    Commands exported by external modules can change URI too
+	    and many do so.
+	    The most important application is changing URI using the
+	    user location database. The command 
+	    <command>lookup(table)</command> looks up current
+	    user's location and rewrites user's address with it.
+	    If there is no registered contact, the 	command returns a negative value.
+
+
+	    <example id="rewriteuri">
+		<title>Rewriting URIs Using User Location Database</title>
+		<programlisting>
+# store user location if a REGISTER appears
+if (method=="REGISTER") {
+    save("mydomain1");
+} else {
+    # try to use the previously registered contacts to
+    # determine next hop
+    if(lookup("mydomain1")) {
+        # if found, forward there...
+        t_relay();
+    } else {
+        # ... if no contact on-line, tell it upstream
+        sl_send_reply("404", "Not Found" );
+    };
+};
+		</programlisting>
+	    </example>
+	</para>
+	<para>
+	    External applications can be used to rewrite URI too.
+	    The "exec" module provides script actions, which start external programs
+	    and read new URI value from their output. <command>exec_dset</command>
+	    both calls an external program, passes SIP request elements to it, waits until it completes,
+	    and eventually rewrites current destination set with its output.
+	</para>
+	<para>
+	    It is important to realize that <application>ser</application>
+	    operates over <emphasis>current URI</emphasis> all the time. If an
+	    original URI is rewritten by a new one, the original will will be
+	    forgotten and the new one will be used in any further
+	    processing. In particular, the uri matching operand and the user
+	    location action <command>lookup</command> always take current URI
+	    as input, regardless what the original URI was.
+	</para>
+	<para>
+	    <xref linkend="urirewritingexamples"/> shows how URI-rewriting actions affect 
+		an example URI, sip:[email protected]:6060.
+		<table id="urirewritingexamples">
+		    <title>URI-rewriting Using Built-In Actions</title>
+		    <tgroup cols="2">
+			<thead>
+			    <row>
+				<entry>
+				    Example Action
+				</entry>				
+				<entry>
+				    Resulting URI
+				</entry>
+			    </row>
+			</thead>
+			<tbody>
+			    <row>
+				<entry>
+				    <command>rewritehost("192.168.0.10")</command> rewrites
+				    the hostname in URI, other parts (including port number) remain unaffected.
+				</entry>
+				<entry>
+				    sip:[email protected]:6060
+				</entry>
+			    </row>
+			    <row>
+				<entry>
+				    <command>rewriteuri("sip:[email protected]");</command> rewrites
+				    the whole URI completely.
+				</entry>
+				<entry>
+				    sip:[email protected]
+				</entry>
+			    </row>
+			    <row>
+				<entry>
+				    <command>rewritehostport("192.168.0.10:3040")</command>rewrites 
+				    both hostname and port number in URI.
+				</entry>
+				<entry>
+				    sip:[email protected]:3040
+				</entry>
+			    </row>
+			    <row>
+				<entry>
+				    <command>rewriteuser("alice")</command> rewrites user part of URI.
+				</entry>
+				<entry>
+				    sip:[email protected]:6060
+				</entry>
+			    </row>
+			    <row>
+				<entry>
+				    <command>rewriteuserpass("alice:pw")</command> replaces the pair
+				    user:password in URI with a new value. Rewriting password in URI is of historical
+				    meaning though, since basic password has been replaced with digest authentication.
+				</entry>
+				<entry>
+				    sip:alice:[email protected]:6060
+				</entry>
+			    </row>
+			    <row>
+				<entry>
+				    <command>rewriteport("1234")</command> replaces port number in URI
+				</entry>
+				<entry>
+				    sip:[email protected]:1234
+				</entry>
+			    </row>
+			    <row>
+				<entry>
+				    <command>prefix("9")</command> inserts a string ahead of user part of URI
+				</entry>
+				<entry>
+				    sip:[email protected]:6060
+				</entry>
+			    </row>
+			    <row>
+				<entry>
+				    <command>strip(2)</command> removes leading characters from user part of URI
+				</entry>
+				<entry>
+				    sip:[email protected]:6060
+				</entry>
+			    </row>
+			</tbody>
+		    </tgroup>
+		</table>
+	</para>	    
+	<para>
+	    You can verify whether you understood URI processing by
+	    looking at the following example. It rewrites URI
+	    several times. The question is what is the final URI to which
+	    the script fill forward any incoming request.
+	    <example>
+		<title>URI-rewriting Exercise</title>
+		<programlisting>
+exec_dset("echo sip:[email protected]; echo > /dev/null");
+strip(2);
+if (uri=~"^sip:2") {
+    prefix("0");
+} else {
+    prefix("1");
+};			
+forward(uri:host, uri:port);
+		</programlisting>
+	    </example>
+	</para>
+	<para>
+	    The correct answer is the resulting URI will be
+	    "sip:[email protected]". <command>exec_dset</command>
+	    rewrites original URI to "sip:[email protected]", 
+	    <command>strip(2)</command> takes
+	    two leading characters from username away resulting
+	    in "[email protected]", the condition does not match
+	    because URI does not begin with "2" any more,
+	    so the prefix "1" is inserted.
+	</para>
+
+
+    </section> <!-- URI rewriting -->
+
+    <section>
+	<title>Destination Set</title>
+	<para>
+	    Whereas needs of many scenarios can by accommodated by maintaining
+	    a single request URI, some scenarios are better served by
+	    multiple URIs. Consider for example a user with address
+	    [email protected]. The user wishes to be reachable at his 
+	    home phone, office phone, cell phone, softphone, etc. 
+	    However, he still wishes to maintain a single public address
+	    on his business card.
+	</para>
+	<para>
+	    To enable such scenarios, <application>ser</application>
+	    allows translation of a single request URI into multiple
+	    outgoing URIs. The ability to forward a request to multiple
+	    destinations is known as <emphasis>forking</emphasis>
+	    in SIP language. All outgoing URIs (in trivial case one of them)
+	    are called <emphasis>destination set</emphasis>. The destination
+	    set always includes one default URI, to which additional URIs
+	    can be appended. Maximum size of a destination set is limited by 
+	    a compile-time constant, MAX_BRANCHES,
+	    in <filename>config.h</filename>.
+	</para>
+	<para>
+	    Some actions are designed for use with a single URI whereas
+	    other actions work with the whole destination set.
+	</para>
+	<para>
+	    Actions which are currently available for creating the destination
+	    set are <command>lookup</command> from usrloc module and 
+	    <command>exec_dset</command> from exec module.
+	    <command>lookup</command> fills in the destination
+	    set with user contact's registered previously with REGISTER
+	    requests. The <command>exec</command> actions
+	    fill in the destination set with output of an external program.
+	    In both cases, current destination set is completely rewritten.		
+	    New URIs can be appended to destination set by a call to the built-in
+	    action <command>append_branch(uri)</command>.
+	</para>
+	<para>		
+	    Currently supported features which utilize destination sets
+	    are <emphasis>forking</emphasis> and <emphasis>redirection</emphasis>. 
+	    Action <command>t_relay</command> (TM module) for stateful
+	    forwarding supports forking. If called with a non-trivial destination
+	    set, <command>t_relay</command> forks
+	    incoming request to all URIs in current destination set.
+	    See <xref linkend="rewriteuri"/>. If a user
+		previously registered from three locations, the destination set is filled with 
+		all of them by <command>lookup</command> and the <command>t_relay</command>
+		command forwards the incoming request to all these destinations.
+		Eventually, all user's phone will be ringing in parallel.
+	</para>
+	<para>
+	    SIP redirection is another feature which leverages destination sets.
+	    It is a very light-weighted method to establish communication
+	    between two parties with minimum burden put on the server. In
+	    <application>ser</application>, the action <command>sl_send_reply</command>
+	    (SL module) is used for this purpose. This action 
+	    allows to generate replies to SIP requests without keeping 
+	    any state. If the status code passed to the action is 3xx, 
+	    the current destination set is printed in reply's Contact header
+	    fields. Such a reply instructs the originating client to 
+	    retry at these addresses. (See <xref linkend="redirectexample"/>).
+	</para>
+	<para>
+	    Most other  <application>ser</application> actions ignore destination
+	    sets: they either do not relate to URI processing (<command moreinfo="none">
+		log</command>, for example) or they work only with the default URI.
+	    All URI-rewriting functions such as
+	    <command moreinfo="none">rewriteuri</command> belong in this
+	    category. URI-comparison operands only refer to the first URI
+	    (see <xref linkend="operators"/>). Also, the built-in action
+		for stateless forwarding, <command>forward</command> works only
+		with the default URI and ignores rest of the destination set. The reason 
+		is a proxy server willing to fork must guarantee that the burden
+		of processing multiple replies is not put unexpectedly on upstream
+		client. This is only achievable with stateful processing.  
+		Forking cannot be used along with stateless <command>forward</command>,
+		which thus only processes one URI out of the whole destination set.
+	</para> 
+
+    </section> <!-- Destination Set -->
+
+    <section>
+	<title>User Location</title>
+	<para>
+	    Mobility is a key feature of SIP. Users are able to use one
+	    one or more SIP devices and be reachable at them. Incoming requests 
+	    for users are forwarded to all user's devices in use. The key
+	    concept is that of soft-state registration. Users can
+	    -- if in possession of valid credentials -- link SIP
+	    devices to their e-mail like address of record. Their SIP devices
+	    do so using a REGISTER request, as in <xref linkend="register"/>.
+		The request creates a binding between the public address of
+		record (To header field) and SIP device's current address
+		(Contact header field). 
+		<example id="register">
+		    <title>REGISTER Request</title>
+		    <programlisting>
+REGISTER sip:192.168.2.16 SIP/2.0
+Via: SIP/2.0/UDP 192.168.2.16;branch=z9hG4bKd5e5.5a9947e4.0
+Via: SIP/2.0/UDP 192.168.2.33:5060
+From: sip:[email protected]
+To: sip:[email protected]
+Call-ID: [email protected]
+Date: Wed, 29 Jan 2003 18:13:15 GMT
+CSeq: 101 REGISTER
+User-Agent: CSCO/4
+Contact: sip:[email protected]:5060
+Content-Length: 0
+Expires: 600
+		    </programlisting>
+		</example>
+		Similar requests can be used to query all user's current contacts or to
+		delete them. All Contacts have certain time to live, when the time expires,
+		contact is removed and no longer used for processing of incoming requests.
+	</para>
+	<para>
+	    <application>ser</application> is built to do both: update
+	    user location database from received REGISTER requests and look-up these
+	    contacts when inbound requests for a user arrive. To achieve high performance,
+	    the user location table is stored in memory. In regular intervals
+	    (usrloc module's parameter <varname>timer_interval</varname> determines
+	    their length), all changes to the in-memory table are backed up in
+	    <application>mysql</application> database to achieve
+	    persistence across server reboots. Administrators or application writers
+	    can lookup list of current user's contacts stored in memory using the
+	    <application>serctl</application> tool (see <xref linkend="serctl"/>).
+		<example>
+		    <title>Use of <application>serctl</application> Tool to Query User Location</title>
+		    <screen>
+<![CDATA[
+[jiri@fox jiri]$ sc ul show jiri
+<sip:[email protected]>;q=0.00;expires=456
+<sip:[email protected]>;q=0.00;expires=36000
+]]>
+		    </screen>
+		</example>
+	</para>
+	<para>
+	    Building user location in <application>ser</application> scripts is
+	    quite easy. One first needs to determine whether a request is for served domain,
+	    as described in <xref linkend="domainmatching"/>. If that is the case, the script
+		needs to distinguish between REGISTER requests, that update user location table,
+		and all other requests for which next hop is determined from the table. The
+		<command>save</command> action is used to update user location
+		(i.e., it writes to it). The <command>lookup</command> actions
+		reads from the user location table and fills in destination set with current
+		user's contacts.
+		<example>
+		    <title>Use of User Location Actions</title>
+		    <programlisting>
+# is the request for my domain ?
+if (uri==myself) {
+    if (method=="REGISTER") { # REGISTERs are used to update
+        save("location");
+        break; # that's it, we saved the contacts, exit now
+    } else {
+        if (!lookup("location") { # no registered contact
+	    sl_send_reply("404", "Not Found");
+	    break;
+        }
+        # ok -- there are some contacts for the user; forward
+        # the incoming request to all of them
+        t_relay();
+    };
+};
+		    </programlisting>
+		</example>
+	</para>
+	<para>
+	    Note that we used the action for stateful forwarding, 
+	    <command>t_relay</command>. That's because
+	    stateful forwarding allows to fork an incoming request to
+	    multiple destinations. If we used stateless forwarding,
+	    the request would be forwarded only to one uri out of
+	    all user's contacts.
+	</para>
+    </section> <!-- User Location -->
+    
+    <section>
+	<title>External Modules</title>
+	<para>
+	    <application>ser</application> provides the ability to link the server with external
+	    third-party shared libraries. Lot of functionality which is
+	    included in the <application>ser</application> distribution is actually located in
+	    modules to keep the server "core" compact and clean.
+	    Among others, there are modules for checking max_forwards
+	    value in SIP requests (maxfwd), transactional processing (tm),
+	    record routing (rr), accounting (acc), authentication (auth),
+	    SMS gateway (sms), replying requests (sl), user location
+	    (usrloc, registrar) and more.
+	</para>
+	<para>
+	    In order to utilize new actions exported by a module, 
+	    ser must first load it. To load a module, the directive
+	    <command>loadmodule "filename"</command>
+	    must be included in beginning of
+	    a <application>ser</application> script file.
+	</para>
+
+	<example>
+	    <title>Using Modules</title>
+	    <para>
+		This example shows how a script instructs 
+		<application>ser</application> to
+		load a module and use actions exported by it.
+		Particularly, the sl module exports an action
+		<command>sl_send_reply</command> which makes 
+		<application>ser</application> act as a stateless
+		user agent and reply all incoming requests with 404.
+	    </para>
+	    <programlisting>
+# first of all, load the module!
+loadmodule "/usr/lib/ser/modules/sl.so
+route{
+    # reply all requests with 404
+    sl_send_reply("404", "I am so sorry -- user not found");
+}
+	    </programlisting>
+	</example>
+	<note>
+	    <para>
+		Note that unlike with core commands, all actions exported by
+		modules must have parameters enclosed in quotation marks in
+		current version of <application>ser</application>.  In the following example,
+		the built-in action <command>forward</command>
+		for stateless forwarding takes IP address and port numbers as
+		parameters without quotation marks whereas a module action
+		<command>t_relay</command> for stateful
+		forwarding takes parameters enclosed in quotation marks.
+		<example>
+		    <title>Parameters in built-in and exported
+			actions</title>
+		    <programlisting>
+# built-in action doesn't enclose IP addresses and port numbers
+# in quotation marks
+forward(192.168.99.100, 5060);
+# module-exported functions enclose all parameters in quotation
+# marks
+t_relay_to_udp("192.168.99.100", "5060");
+		    </programlisting>
+		</example>
+	    </para>
+	</note>
+	<para>
+	    Many modules also allow users to change the way how they work using
+	    predefined parameters. For example, the authentication module needs
+	    to know location of MySQL database which contains users' security
+	    credentials.  How module parameters are set using the
+	    <command>modparam</command> directive is shown in <xref
+	    linkend="moduleparameters"/>.  <command>modparam</command> always
+	    contains identification of module, parameter name and parameter
+	    value. Description of parameters available in modules is available
+	    in module documentation.
+	</para>
+	<para>
+	    Yet another thing to notice in this example is module
+	    dependency. Modules may depend on each other. For example, the
+	    authentication modules leverages the mysql module for accessing
+	    mysql databases and sl module for generating authentication
+	    challenges. We recommend that modules are loaded in dependency
+	    order to avoid ambiguous server behavior.  </para>
+	<para>
+	    <example id="moduleparameters">
+		<title>Module Parameters</title>
+		<programlisting>
+# ------------------ module loading ----------------------------------
+
+# load first modules on which 'auth' module depends;
+# sl is used for sending challenges, mysql for storage
+# of user credentials
+loadmodule "modules/sl/sl.so"
+loadmodule "modules/mysql/mysql.so"
+loadmodule "modules/auth/auth.so"
+
+# ------------------ module parameters -------------------------------
+# tell the auth module the access data for SQL database:
+# username, password, hostname and database name
+modparam("auth", "db_url","mysql://ser:secret@dbhost/ser")
+
+
+# -------------------------  request routing logic -------------------
+# authenticate all requests prior to forwarding them
+
+route{
+
+    if (!proxy_authorize("foo.bar" /* realm */,
+         "subscriber" /* table name */ )) {
+        proxy_challenge("foo.bar", "0");
+        break;
+    };
+    forward(192.168.0.10,5060);
+}
+		</programlisting>
+	    </example>
+	</para>
+    </section>
+
+    <section id="writing_scripts">
+	<title>Writing Scripts</title>
+	<para>
+	    This section demonstrates simple examples
+	    how to configure server's behavior using the
+	    <application>ser</application>
+	    request routing language. All configuration scripts follow the 
+	    <application>ser</application> language 
+	    syntax, which dictates the following section ordering:
+	    <itemizedlist>
+		<listitem>
+		    <para>
+			<emphasis>global configuration parameters</emphasis> --
+			these value affect behavior of the server such as port
+			number at which it listens, number of spawned children
+			processes, and log-level. See <xref
+			linkend="coreoptions"/> for a list of available options.
+		    </para>
+		</listitem>
+
+		<listitem>
+		    <para>
+			<emphasis>module loading</emphasis> -- these statements
+			link external modules, such as transaction management
+			(tm) or stateless UA server (sl)  dynamically. See
+			<xref linkend="modulereference"/> for a list of modules
+			    included in <application>ser</application>
+			    distribution.
+		    </para>
+		    <note>
+			<para>
+			    If modules depend on each other, than the depending
+			    modules must be loaded after modules on which they
+			    depend. We recommend to load first modules
+			    <command>tm</command> and <command>sl</command>
+			    because many other modules (authentication, user
+			    location, accounting, etc.) depend on these.
+			</para>
+		    </note>
+		</listitem>
+		<listitem>
+		    <para>
+			<emphasis>module-specific parameters</emphasis> -- determine
+			how modules behave; for example, it is possible to configure
+			database to be used by authentication module.
+		    </para>
+		</listitem>
+		<listitem>
+		    <para>
+			one or more <emphasis>route blocks</emphasis> containing the
+			request processing logic, which includes built-in actions
+			as well as actions exported by modules. See <xref linkend="builtinref"/>
+			    for a list of built-in actions.
+		    </para>
+		</listitem>
+		<listitem>
+		    <para>
+			optionally, if modules supporting reply
+			processing (currently only TM) are loaded,
+			one or more <emphasis>failure_route blocks</emphasis> containing
+			logic triggered by received replies. Restrictions on use of
+			actions within <command>failure_route</command>
+			blocks apply -- see <xref linkend="builtinref"/> for more
+			    information.
+		    </para>
+		</listitem>
+	    </itemizedlist>
+	</para>
+
+	<section id="defaultscript">
+	    <title>Default Configuration Script</title>		
+	    <para>
+		The configuration script, <filename>ser.cfg</filename>,
+		is a part of every <application>ser</application>
+		distribution and defines default behavior. It allows users
+		to register with the server and have requests proxied to each
+		other.
+	    </para>
+	    <para>
+		After performing
+		routine checks, the script looks whether incoming request is for
+		served domain. If so and the request is "REGISTER", <application>ser</application>
+		acts as SIP registrar and updates database of user's contacts.
+		Optionally, it verifies user's identity first to avoid
+		unauthorized contact manipulation.
+	    </para>
+	    <para>
+		Non-REGISTER requests for served domains are then processed using
+		user location database. If a contact is found for requested URI,
+		script execution proceeds to stateful forwarding, a negative 404
+		reply is generated otherwise. Requests outside served domain
+		are always statefully forwarded.
+	    </para>
+	    <para>
+		Note that this simple script features several limitations:
+		<itemizedlist>
+		    <listitem>			    
+			<para>
+			    By default, authentication is turned off to avoid
+			    dependency on mysql. Unless it it turned on, anyone
+			    can register using any name and "steal" someone else's
+			    calls.
+			</para>
+		    </listitem>
+
+		    <listitem>
+			<para>
+			    Even it authentication is turned on, there is no relationship
+			    between authentication username and address of record. That
+			    means that for example a user authenticating himself correctly
+			    with "john.doe" id may register contacts for "gw.bush".
+			    Site policy may wish to mandate authentication id to be equal
+			    to username claimed in To header field. <action>check_to</action>
+			    action from auth module can be used to enforce such a policy.
+			</para>
+		    </listitem>
+		    <listitem>
+			<para>
+			    There is no dialing plan implemented. All users are supposed to
+			    be reachable via user location database. See <xref linkend="numberingplans"/>
+				for more information.
+			</para>
+		    </listitem>
+		    <listitem>
+			<para>
+			    The script assumes users will be using server's name as a part of
+			    their address of record. If users wish to use another name (domain
+			    name for example), this must be set using the <varname>alias</varname>
+			    options. See <xref linkend="domainmatching"/> for more information.
+			</para>
+		    </listitem>
+		    <listitem>
+			<para>
+			    If authentication is turned on by uncommenting related configuration
+			    options, clear-text user passwords will by assumed in back-end database.
+			</para>
+		    </listitem>
+		</itemizedlist>
+	    </para>
+	    <example>
+		<title>Default Configuration Script</title>
+		<programlisting>
+<xi:include href="../../etc/ser.cfg" parse="text"/>
+		</programlisting>
+	    </example>
+	</section>
+
+	<section id="statefulua">
+	    <title>Stateful User Agent Server</title>
+	    <para>
+		This examples shows how to make ser act as a stateful user
+		agent (UA). Ability to act as as a stateful UA is essential
+		to many applications which terminate a SIP path. These
+		applications wish to focus on their added value. They
+		do not wish to be involved in all SIP gory details, such
+		as request and reply retransmission, reply formatting, etc.
+		For example, we use the UA functionality to shield 
+		SMS gateway and instant message store from SIP transactional
+		processing.
+		The simple example bellow issues a log report on receipt
+		of a new transaction. 
+		If we did not use a stateful UA, every single request retransmission
+		would cause the application to be re-executed which would result in
+		duplicated SMS messages, instant message in message store or 
+		log reports.
+	    </para>
+	    <para>
+		The most important actions are <command> t_newtran</command>
+		    and <command> t_reply</command>. <command>
+		    
+		    t_newtran</command> shields subsequent code from
+		retransmissions.  It returns success and continues when a new
+		request arrived.  It exits current route block immediately on
+		receipt of a retransmission. It only returns a negative value
+		when a serious error, such as lack of memory, occurs.
+	    </para>
+	    <para>
+		<command>t_reply</command> generates
+		a reply for a request. It generates the reply statefully,
+		i.e., it is kept for future retransmissions in memory.
+	    </para>
+	    <note>
+		<para>
+		    Applications that do not need stateful processing
+		    may act as stateless UA Server too. They just use
+		    the <command>sl_send_reply</command> action to
+		    send replies to requests without keeping any
+		    state. The benefit is memory cannot run out,
+		    the drawback is that each retransmission needs to
+		    be processed as a new request. An example of use
+		    of a stateless server is shown in
+		    <xref linkend="redirectserver"/> and
+		    	<xref linkend="executingscript"/>.
+		</para>
+	    </note>
+	    <example>
+		<title>Stateful UA Server</title>
+		<programlisting format="linespecific">
+<xi:include href="../../examples/uas.cfg" parse="text"/>
+		</programlisting>
+	    </example>
+	</section> <!-- Stateful UAS -->
+
+	<section id="redirectserver">
+	    <title>Redirect Server</title>
+	    <para>
+		The redirect example shows how to redirect a request
+		to multiple destination using 3xx reply. Redirecting
+		requests as opposed to proxying them is essential to
+		various scalability scenarios. Once a message is
+		redirected, <application>ser</application>
+		discards all related state and is no more involved
+		in subsequent SIP transactions (unless the redirection
+		addresses point to the same server again).
+	    </para>
+	    <para>
+		The key <application>ser</application> actions in this example 
+		are <command>append_branch</command> and 
+		<command>sl_send_reply</command> (sl module).
+	    </para>
+	    <para>
+		<command>append_branch</command> adds
+		a new item to the destination set. The destinations set always
+		includes the current URI and may be enhanced up to
+		<constant>MAX_BRANCHES</constant> items.
+		<command>sl_send_reply</command> command, 
+		if passed SIP reply code 3xx, takes all values in current 
+		destination set and adds them to Contact header field in 
+		the reply being  sent.
+	    </para>
+	    <example id="redirectexample">
+		<title>Redirect Server</title>
+		<programlisting>
+<xi:include href="../../examples/redirect.cfg" parse="text"/>
+		</programlisting>
+	    </example>
+	</section> <!-- redirect server-->
+	
+	<section id="executingscript">
+	    <title>Executing External Script</title>
+	    <para>
+		Like in the previous example, we show how to
+		make <application>ser</application> act as a redirect server. The difference is 
+		that we do not use redirection addresses hardwired in
+		<application>ser</application> script but
+		get them from external shell commands. We also use
+		ser's ability to execute shell commands to log
+		source IP address of incoming SIP requests.
+	    </para>
+	    <para>
+		The new commands introduced in this example are
+		<command>exec_msg</command> and
+		<command>exec_dset</command>.
+		<command>exec_msg</command> takes
+		current requests, starts an external command, and
+		passes the requests to the command's standard input.
+		It also passes request's source IP address in
+		environment variable named <constant>SRCIP</constant>.
+	    </para>
+	    <para>
+		<command>exec_dset</command> serves for URI rewriting by
+		external applications.  The <command>exec_dset</command> action
+		passes current URI to the called external program, and rewrites
+		current destination set with the program's output. An example
+		use would be an implementation of a Least-Cost-Router, software
+		which returns URI of the cheapest PSTN provider for a given
+		destination based on some pricing tables. <xref
+		linkend="execscript"/> is much easier: it prints fixed URIs on
+		its output using shell script <command>echo</command> command.
+	    </para>
+	    <note>
+		<para>
+		    This script works statelessly -- it uses this action for
+		    stateless replying, <command>sl_send_reply</command>.  No
+		    transaction is kept in memory and each request
+		    retransmission is processed as a brand-new request. That
+		    may be a particular concern if the server logic
+		    (<command>exec</command> actions in this example) is too
+		    expensive. See <xref linkend="statefulua"/> for instructions
+		    on how to make server logic stateful, so that
+		    retransmissions are absorbed and do not cause re-execution
+		    of the logic.
+		</para>
+	    </note>
+	    <example id="execscript">
+		<title>Executing External Script</title>
+		<programlisting>
+<xi:include href="../../examples/exec.cfg" parse="text"/>
+		</programlisting>
+	    </example>
+	</section> <!-- exec example -->
+	
+	<section id="replyprocessingsection">
+	    <title>On-Reply Processing (Forward on Unavailable)</title>
+	    <para>
+		Many services depend on status of messages relayed
+		downstream: <emphasis>forward on busy</emphasis> and 
+		<emphasis>forward on no reply</emphasis> to name the
+		most well-known ones. To support implementation of
+		such services, <application>ser</application>
+		allows to return to request processing when request
+		forwarding failed. When a request is reprocessed,
+		new request branches may be initiated or the transaction
+		can be completed at discretion of script writer.
+	    </para>
+	    <para>
+		The primitives used are <command>t_on_failure(r)</command>
+		and <command>failure_route[r]{}.</command> If
+		<command>t_on_failure</command> is called before
+		a request is statefully forwarded and a forwarding failure occurs, 
+		<application>ser</application>
+		will return to request processing in a <command>failure_route</command>
+		block. Failures include receipt of a SIP error
+		(status code >= 300 ) from downstream or not receiving
+		any final reply within final response period.
+	    </para>
+	    <para>
+		The length of the timer is governed by parameters of the
+		tm module. <varname>fr_timer</varname> is the length of
+		timer set for non-INVITE transactions and INVITE transactions
+		for which no provisional response is received. If a timer
+		hits, it indicates that a downstream server is unresponsive.
+		<varname>fr_inv_timer</varname> governs time to wait for 
+		a final reply for an INVITE. It is typically longer than
+		<varname>fr_timer</varname> because final reply may take
+		long time until callee (finds a mobile phone in a pocket and)
+		answers the call.
+	    </para>
+	    <para>
+		In <xref linkend="replyprocessing"/>,
+		    <command>failure_route[1]</command> is set to be entered on
+		    error using the <command>t_on_failure(1)</command>
+		    action. Within this reply block,
+		    <application>ser</application> is instructed to initiate a
+		    new branch and try to reach called party at another
+		    destination (sip:[email protected]). To deal with the case
+		    when neither the alternate destination succeeds,
+		    <application>t_on_failure</application> is set again. If
+		    the case really occurs, <command>failure_route[2]</command>
+		    is entered and a last resort destination
+		    (sip:[email protected]) is tried.
+	    </para>
+	    <example id="replyprocessing">
+		<title>On-Reply Processing</title>
+		<programlisting>
+<xi:include href="../../examples/onr.cfg" parse="text"/>
+		</programlisting>
+	    </example>
+	</section> <!-- reply processing -->
+    </section> <!-- examples -->
+</section>

doc/seruser/operation.sgml

@@ -1,1502 +0,0 @@
-    <chapter>
-	<title>Server Operation</title>
-	<section id="operationalpractices">
-	    <title>Recommended Operational Practices</title>
-
-	    <para>
-		Operation of a SIP server is not always easy task.
-		Server administrators are challenged by broken or
-		misconfigured user agents, network and host failures,
-		hostile attacks and other stress-makers. All such
-		situations may lead to an operational failure. It is sometimes
-		very difficult to figure out the root reason of
-		a failure, particularly in a distributed environment
-		with many SIP components involved.		
-		In this section,
-		we share some of our practices and refer to tools
-		which have proven to
-		make life of administrators easier
-	    </para>
-
-	<qandaset>
-	    <qandaentry>
-		<question>
-		    <para>
-			Keeping track of messages is good
-		    </para>
-		</question>
-		<answer>
-			<para>
-			    Frequently, operational errors are discovered or reported
-			    with a delay.
-			    Users frustrated by an error
-			    frequently approach administrators
-			    and scream "even though my SIP requests were absolutely ok
-			    yesterday, they were mistakenly denied by your server".
-			    If administrators do not record all SIP traffic at
-			    their site, they will be no more able to identify
-			    the problem reason.
-			    We thus recommend that site
-			    operators record all messages passing their site and keep them
-			    stored for some period of time.
-			They may use utilities such as 
-			<application>ngrep 
-			</application> or 
-			<application>tcpdump
-			</application>.
-			There is also a utility <application moreinfo="none">
-			    scripts/harv_ser.sh</application> in <application moreinfo="none">
-			ser</application> distribution for post-processing
-			of captured messages. It summarizes messages captured
-			by reply status and user-agent header field.
-		    </para>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <para>
-			Real-time Traffic Watching
-		    </para>
-		</question>
-		<answer>
-			<para>
-		    Looking at SIP messages in real-time may help to gain
-		    understanding of problems. Though there are commercial
-		    tools available, using a simple, text-oriented tool
-		    such as <application>ngrep</application> makes the job very well thanks to SIP's textual nature.
-			</para>
-		    <example id="usingngrep">
-			<title>Using <application>ngrep</application>
-			</title>
-			<para>In this example, all messages at port 5060
-			which include the string "bkraegelin" are captured
-			and displayed</para>
-			<programlisting format="linespecific">
-[jiri@fox s]$ ngrep bkraegelin@ port 5060
-interface: eth0 (195.37.77.96/255.255.255.240)
-filter: ip and ( port 5060 )
-match: bkraegelin@
-#
-U +0.000000 153.96.14.162:50240 -> 195.37.77.101:5060
-REGISTER sip:iptel.org SIP/2.0.
-Via: SIP/2.0/UDP 153.96.14.162:5060.
-From: sip:[email protected].
-To: sip:[email protected].
-Call-ID: [email protected].
-Date: Thu, 26 Sep 2002 22:03:55 GMT.
-CSeq: 101 REGISTER.
-Expires: 10.
-Content-Length: 0.
-.
-
-#
-U +0.000406 195.37.77.101:5060 -> 153.96.14.162:5060
-SIP/2.0 401 Unauthorized.
-Via: SIP/2.0/UDP 153.96.14.162:5060.
-From: sip:[email protected].
-To: sip:[email protected].
-Call-ID: [email protected].
-CSeq: 101 REGISTER.
-WWW-Authenticate: Digest realm="iptel.org", nonce="3d9385170000000043acbf6ba9c9741790e0c57adee73812", algorithm=MD5.
-Server: Sip EXpress router(0.8.8 (i386/linux)).
-Content-Length: 0.
-Warning: 392 127.0.0.1:5060 "Noisy feedback tells: pid=31604 req_src_ip=153.96.14.162 in_uri=sip:iptel.org out_uri=sip:iptel.org via_cnt==1".
-
-			</programlisting>
-		    </example>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <para>
-			Tracing Errors in Server Chains
-		    </para>
-		</question>
-		<answer>
-			<para>
-			    A request may pass any number of proxy servers on
-			    its path to its destination. If an error occurs
-			    in the chain, it is difficult for upstream troubleshooters
-			    and/or users complaining to administrators to learn 
-			    more about error circumstances. 
-			    <application moreinfo="none">ser
-			    </application> does its best and displays extensive
-			    diagnostics information in SIP replies. It allows 
-			    troubleshooters and/or users who report to troubleshooters
-			    to gain additional knowledge about request processing
-			    status. 
-			    This extended debugging information is part of the warning 
-			    header field. See <xref linkend="usingngrep"> for an illustration
-			    of a reply that includes such a warning header field. The header
-			    field contains the following pieces of information:
-			<itemizedlist>
-			    <listitem>
-				<para>
-				Server's IP Address -- good to identify
-				from which server in a chain the reply
-				came.
-				    </para>
-			    </listitem>
-			    <listitem>
-				    <para>
-					Incoming and outgoing URIs -- good to
-					learn for which URI the reply was
-					generated, as it may be rewritten
-					many times in the path. Particularly
-					useful for debugging of numbering plans.
-				    </para>
-			    </listitem>
-			    <listitem>
-				<para>
-					Number of Via header fields in replied
-					request -- that helps in assessment of
-					request path length. Upstream clients would
-					not know otherwise, how far away in terms
-					of SIP hops their requests were replied.
-				</para>
-			    </listitem>
-				<listitem>
-				    <para>
-					Server's process id. That is useful for
-					debugging to discover situations when
-					multiple servers listen at the same
-					address.
-				    </para>
-				</listitem>
-				<listitem>
-				    <para>
-					IP address of previous SIP hop as seen by
-					the SIP server.
-				    </para>
-				</listitem>
-			</itemizedlist>
-		    </para>
-			<para>
-			    If server administrator is not comfortable with
-			    disclosing all this information, he can turn them
-			    off using the <varname>sip_warning</varname> configuration
-			    option.
-			</para>
-		    <para>
-			A nice utility for debugging server chains is
-			<application moreinfo="none">sipsak</application>,
-			SIP Swiss Army Knife, traceroute-like tool for SIP
-			developed at iptel.org. It allows you to send
-			OPTIONS request with low, increasing Max-Forwards 
-			header-fields and follow how it propagates in
-			SIP network. See its webpage at
-			<ulink url="http://sipsak.berlios.de/">
-			    http://sipsak.berlios.de/
-			</ulink>.
-		    </para>
-		    <example>
-			<title>Use of SIPSak for Learning SIP Path</title>
-			<programlisting format="linespecific">
-[jiri@bat sipsak]$ ./sipsak -T -s sip:[email protected]
-warning: IP extract from warning activated to be more informational
-0: 127.0.0.1 (0.456 ms) SIP/2.0 483 Too Many Hops
-1: ?? (31.657 ms) SIP/2.0 200 OK
-	without Contact header
-
-			</programlisting>
-			<para>
-			    Note that in this example, the second hop
-			    server does not issue any warning header fields
-			    in replies and it is thus impossible to display 
-			    its IP address in <application moreinfo="none">
-			    SIPsak</application>'s output.
-			</para>
-		    </example>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <para>
-			Watching Server Health
-		    </para>
-		</question>
-		<answer>
-		    <para>
-			Watching Server's operation status in real-time may
-			also be a great aid for trouble-shooting. 
-			<application>ser</application> has an excellent 
-			facility, a FIFO server, which allows UNIX
-			tools to access server's internals. (It is 
-			similar to how Linux tool access Linux kernel
-			via the proc file system.) The FIFO server
-			accepts commands via a FIFO (named pipe) and
-			returns data asked for. Administrators do not
-			need to learn details of the FIFO communication
-			and can serve themselves using a front-end
-			utility <application moreinfo="none">serctl</application>.
-			Of particular interest for 
-			monitoring server's operation are 
-			<application moreinfo="none">serctl</application>
-			commands
-			<command moreinfo="none">ps</command> and
-			<command moreinfo="none">moni</command>.
-			The former displays running 
-			<application moreinfo="none">ser</application>
-			processes, whereas the latter shows statistics.
-		    </para>
-		    <example>
-			<title>serctl ps command</title>
-			<para>
-			    This example shows 10 processes running at a host.
-			    The process 0, "attendant" watches child processes
-			    and terminates all of them if a failure occurs in
-			    any of them. Processes 1-4 listen at local
-			    interface and processes 5-8 listen at Ethernet
-			    interface at port number 5060. Process number
-			    9 runs FIFO server, and process number 10
-			    processes all server timeouts.
-			</para>
-			<programlisting format="linespecific">
-[jiri@fox jiri]$ serctl ps
-0	31590	attendant
-1	31592	receiver child=0 sock=0 @ 127.0.0.1::5060
-2	31595	receiver child=1 sock=0 @ 127.0.0.1::5060
-3	31596	receiver child=2 sock=0 @ 127.0.0.1::5060
-4	31597	receiver child=3 sock=0 @ 127.0.0.1::5060
-5	31604	receiver child=0 sock=1 @ 195.37.77.101::5060
-6	31605	receiver child=1 sock=1 @ 195.37.77.101::5060
-7	31606	receiver child=2 sock=1 @ 195.37.77.101::5060
-8	31610	receiver child=3 sock=1 @ 195.37.77.101::5060
-9	31611	fifo server
-10	31627	timer
-			  
-			</programlisting>
-		    </example>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <para>
-			Is Server Alive
-		    </para>
-		</question>
-		<answer>
-		    <para>
-			It is essential for solid operation to know
-			continuously that server is alive. We've been
-			using two tools for this purpose. 
-			<application moreinfo="none">sipsak</application>
-			does a great job of "pinging" a server, which
-			may be used for alerting on unresponsive servers.
-		    </para>
-		    <para>
-			<application moreinfo="none">monit</application> is
-			a server watching utility which alerts when
-			a server dies.
-		    </para>
-		</answer>
-	    </qandaentry>
-	    <qandaentry>
-		<question>
-		    <para>
-			Dealing with DNS
-		    </para>
-		</question>
-		<answer>
-		    <para>
-			SIP standard leverages DNS. Administrators of
-			<application moreinfo="none">ser</application> should
-			be aware of impact of DNS on server's operation.
-			Server's attempt to resolve an unresolvable address
-			may block a server process in terms of seconds. To be
-			safer that the server doesn't stop responding
-			due to being blocked by DNS resolving, we recommend
-			the following practices:
-			<itemizedlist>
-			    <listitem>
-				<para>
-				    Start a sufficient number of children processes.
-				    If one is blocked, the other children will
-				    keep serving.
-				</para>
-			    </listitem>
-			    <listitem>
-				<para>
-				    Use DNS caching. For example, in Linux,
-				    there is an <application moreinfo="none">
-				    nscd</application> daemon available for
-				    this purpose.
-				</para>
-			    </listitem>
-			    <listitem>
-				<para>
-				    Process transactions statefully if memory
-				    allows. That helps to absorb retransmissions
-				    without having to resolve DNS for each of
-				    them.
-				</para>
-			    </listitem>
-			</itemizedlist>
-		    </para>
-		</answer>
-	    </qandaentry>
-		<qandaentry>
-			<question>
-				<para>
-					Logging
-				</para>
-			</question>
-			<answer>
-			<anchor id="logging">
-			<para>
-			    <application>ser</application> by default logs
-			    to <application>syslog</application> facility.
-			    It is very useful to watch log messages for
-			    abnormal behavior. Log messages, subject to
-			    <application>syslog</application> configuration
-			    may be stored at different files, or even at remote
-			    systems. A typical location of the log file is
-			    <filename>/var/log/messages</filename>.
-			</para>
-			<note>
-			    <para>
-				One can also use other <application>syslogd</application>
-				implementation. <application>metalog</application>
-				(<ulink url="http://metalog.sourceforge.net/">
-				    http://metalog.sourceforge.net/
-				</ulink>)
-				features regular expression matching that enables
-				to filter and group log messages.
-			    </para>
-			</note>
-			<para>
-			    For the purpose of debugging configuration scripts, one may
-			    want to redirect log messages to console not to pollute
-			    syslog files. To do so configure <application moreinfo="none">ser</application>
-			    in the following way:
-			    <itemizedlist>
-				<listitem>
-				    <para>
-					Attach ser to console by setting <varname>fork=no</varname>.
-				    </para>
-				</listitem>
-				<listitem>
-				    <para>
-					Set explicitly at which address 
-					<application moreinfo="none">ser</application>
-					should be listening, e.g., <varname>listen=192.168.2.16</varname>.
-				    </para>
-				</listitem>
-				<listitem>
-				    <para>
-					Redirect log messages to standard error by setting
-					<varname>log_stderror=yes</varname>
-				    </para>
-				</listitem>
-				<listitem>
-				    <para>
-					Set appropriately high log level. (Be sure that you redirected logging
-					to standard output. Flooding system logs with many detailed messages
-					would make the logs difficult to read and use.) You can set the global
-					logging threshold value with the option <varname>debug=nr</varname>,
-					where the higher <varname>nr</varname> the more detailed output.
-					If you wish to set log level only for some script events, include
-					the desired log level as the first parameter of the
-					<command moreinfo="none">log</command> action in your script.
-					The messages will be then printed if <command moreinfo="none">log</command>'s
-					level is lower than the global threshold, i.e., the lower the more
-					noisy output you get.
-					<example>
-					    <title>Logging Script</title>
-					    <programlisting format="linespecific">
-&logging;
-					    </programlisting>
-					    <para>
-						The following SIP message causes then logging output as shown
-						bellow.
-					    </para>
-					    <programlisting format="linespecific">
-REGISTER sip:192.168.2.16 SIP/2.0
-Via: SIP/2.0/UDP 192.168.2.33:5060
-From: sip:[email protected]
-To: sip:[email protected]
-Call-ID: [email protected]
-Date: Thu, 27 Feb 2003 15:10:52 GMT
-CSeq: 101 REGISTER
-User-Agent: CSCO/4
-Contact: sip:[email protected]:5060
-Content-Length: 0
-Expires: 600                                 
-					    </programlisting>
-					    <programlisting format="linespecific">
-[jiri@cat sip_router]$ ./ser -f examples/logging.cfg 
-Listening on 
-              192.168.2.16 [192.168.2.16]::5060
-Aliases: cat.iptel.org:5060 cat:5060 
-WARNING: no fork mode 
- 0(0) INFO: udp_init: SO_RCVBUF is initially 65535
- 0(0) INFO: udp_init: SO_RCVBUF is finally 131070
- 0(17379) REGISTER received
- 0(17379) request for other domain received					
-					    </programlisting>
-					</example>
-				    </para>
-				</listitem>
-			    </itemizedlist>
-			</para>
-			</answer>
-		</qandaentry>
-	    <qandaentry>
-		<question>
-		    <para>
-			Labeling Outbound Requests
-		    </para>
-		</question>
-		<answer>
-		    <para>
-		    Without knowing, which pieces of script code a relayed
-		    request visited, trouble-shooting would be difficult.
-		    Scripts typically apply different processing to
-		    different routes such as to IP phones and PSTN
-		    gateways. We thus recommend to label outgoing
-		    requests with a label describing the type of processing
-		    applied to the request.
-			</para>
-		    <para>
-			Attaching "routing-history" hints to relayed
-			requests is as easy as using the 
-			<command moreinfo="none">append_hf</command>
-			action exported by textops module. The following
-			example shows how different labels are attached
-			to requests to which different routing logic
-			was applied.
-			<example>
-			    <title>"Routing-history" labels</title>
-			    <programlisting format="linespecific">
-# is the request for our domain?
-# if so, process it using UsrLoc and label it so.
-if (uri=~[@:\.]domain.foo") {
-   if (!lookup("location")) {
-    sl_send_reply("404", "Not Found");
-    break;
-   };
-   # user found -- forward to him and label the request
-   append_hf("P-hint: USRLOC\r\n");
-} else {
-# it is an outbound request to some other domain --
-# indicate it in the routing-history label
-   append_hf("P-hint: OUTBOUND\r\n");
-};
-t_relay();
-			    </programlisting>
-			    <para>
-				This is how such a labeled requests looks
-				like. The last header field includes
-				a label indicating the script processed
-				the request as outbound.
-			    </para>
-			    <programlisting format="linespecific">
-#
-U 2002/09/26 02:03:09.807288 195.37.77.101:5060 -> 203.122.14.122:5060
-SUBSCRIBE sip:[email protected] SIP/2.0.
-Max-Forwards: 10.
-Via: SIP/2.0/UDP 195.37.77.101;branch=53.b44e9693.0.
-Via: SIP/2.0/UDP 203.122.14.115:16819.
-From: sip:[email protected];tag=5c7cecb3-cfa2-491d-a0eb-72195d4054c4.
-To: sip:[email protected].
-Call-ID: [email protected].
-CSeq: 2 SUBSCRIBE.
-Contact: sip:203.122.14.115:16819.
-User-Agent: Windows RTC/1.0.
-Proxy-Authorization: Digest username="rajeshacl", realm="iptel.org", algorithm="MD5", uri="sip:[email protected]", nonce="3d924fe900000000fd6227db9e565b73c465225d94b2a938", response="a855233f61d409a791f077cbe184d3e3".
-Expires: 1800.
-Content-Length: 0.
-P-hint: OUTBOUND.			    </programlisting>
-			</example>
-		</para>
-		</answer>
-	    </qandaentry>
-	</qandaset>
-	</section> <!-- operational practises -->
-
-	<section>
-	    <title>HOWTOs</title>
-	    <para>
-		This section is a "cookbook" for dealing with common tasks,
-		such as user management or controlling access
-		to PSTN gateways.
-	    </para>
-	    <section>
-		<title>User Management</title>
-
-			<para>
-			    There are two tasks related to management of SIP users:
-			    maintaining user accounts and maintaining user contacts.
-			    Both these jobs can be done using the 
-			    <application moreinfo="none">serctl</application>
-			    command-line tool. Also, the complimentary web
-			    interface, <application moreinfo="none">serweb</application>,
-			    can be used for this purpose as well.
-			</para>
-			<para>
-			    If user authentication is turned on, which is a highly
-			    advisable practice, user account must be created before
-			    a user can log in. To create a new user account, call the
-			    <command moreinfo="none">serctl add</command> utility
-			    with username, password and email as parameters. It
-			    is important that the environment <varname>SIP_DOMAIN</varname>
-			    is set to your realm and matches realm values used in
-			    your script. The realm value is used for calculation
-			    of credentials stored in subscriber database, which are
-			    bound permanently to this value.
-			    <screen format="linespecific">
-[jiri@cat gen_ha1]$ export SIP_DOMAIN=foo.bar
-[jiri@cat gen_ha1]$ serctl add newuser secret [email protected]
-MySql Password: 
-new user added
-			    </screen>
-			</para>
-			<para><application moreinfo="none">serctl</application> can
-			    also change user's password or remove existing accounts
-			    from system permanently.
-			    <screen format="linespecific">
-[jiri@cat gen_ha1]$ serctl passwd newuser newpassword
-MySql Password: 
-password change succeeded
-[jiri@cat gen_ha1]$ serctl rm newuser                
-MySql Password: 
-user removed
-			    </screen>
-			</para>
-			<para>
-			    User contacts are typically automatically uploaded by SIP phones
-			    to server during registration process and administrators do not
-			    need to worry about them. However, users
-			    may wish to append permanent contacts to PSTN gateways
-			    or to locations in other administrative domains. 
-			    To manipulate the contacts in such cases, use
-			    <application moreinfo="none">serctl ul</application>
-			    tool. Note that this is the only correct way
-			    to update contacts -- direct changes to back-end
-			    MySql database do not affect server's memory. Also note,
-			    that if persistence is turned off (usrloc "db_mode"
-			    parameter set to "0"), all contacts are gone on server
-			    reboot. Make sure that persistence is enabled if you
-			    add permanent contacts.
-			</para>
-			<para>
-			    To add a new permanent contact for a user, call 
-			    <application moreinfo="none">serctl ul add &lt;username&gt
-			    &lt;contact&gt;</application>. To delete 
-			    all user's contacts, call 
-			    <application>serctl ul rm &lt;username&gt;</application>.
-			    <application moreinfo="none">serctl ul show &lt;username&gt;</application>
-			    prints all current user's contacts.
-			    <screen format="linespecific">
-[jiri@cat gen_ha1]$ serctl ul add newuser sip:[email protected]
-sip:[email protected]
-200 Added to table
-('newuser','sip:[email protected]') to 'location'
-[jiri@cat gen_ha1]$ serctl ul show newuser
-&lt;sip:[email protected]&gt;;q=1.00;expires=1073741812
-[jiri@cat gen_ha1]$ serctl ul rm newuser  
-200 user (location, newuser) deleted
-[jiri@cat gen_ha1]$ serctl ul show newuser
-404 Username newuser in table location not found
-			    </screen>
-			</para>
-	    </section> <!-- user management -->
-	    <section>
-		<title>User Aliases</title>
-
-			<para>
-			    Frequently, it is desirable for a user to have multiple
-			    addresses in a domain. For example, a user with username "john.doe" wants to be
-			    reachable at a shorter address "john" or at a numerical address
-			    "12335", so that PSTN callers with digits-only key-pad can reach
-			    him too.
-			</para>
-			<para>
-			    With <application moreinfo="none">ser</application>, you can maintain
-			    a special user-location table and translate existing aliases to canonical
-			    usernames using the <command moreinfo="none">lookup</command>
-			    action from usrloc module. The following script fragment demonstrates
-			    use of <command moreinfo="none">lookup</command> for this purpose.
-			    <example>
-				<title>Configuration of Use of Aliases</title>
-				<programlisting format="linespecific">
-if (!uri==myself) { # request not for our domain...
-  route(1); # go somewhere else, where outbound requests are processed
-  break;
-};
-# the request is for our domain -- process registrations first
-if (method=="REGISTER") { route(3); break; };
-
-# look now, if there is an alias in the "aliases" table; don't care
-# about return value: whether there is some or not, move ahead then
-lookup("aliases");
-
-# there may be aliases which translate to other domain and for which
-# local processing is not appropriate; check again, if after the
-# alias translation, the request is still for us
-if (!uri==myself) { route(1); break; };
-
-# continue with processing for our domain...
-...
-  
-				</programlisting>
-			    </example>
-			</para>
-			<para>
-			    The table with aliases is updated using the
-			    <application moreinfo="none">serctl</application>
-			    tool. <application moreinfo="none">
-			    serctl alias add &lt;alias&gt; &lt;uri&gt;</application>
-			    adds a new alias, 
-			    <application moreinfo="none">serctl alias show &lt;user&gt;</application>
-			    prints an existing alias, and
-			    <application moreinfo="none">serctl alias rm &lt;user&gt;</application>
-			    removes it.
-			    <screen format="linespecific">
-[jiri@cat sip_router]$ serctl alias add 1234 sip:[email protected]
-sip:[email protected]
-200 Added to table
-('1234','sip:[email protected]') to 'aliases'
-[jiri@cat sip_router]$ serctl alias add john sip:[email protected]
-sip:[email protected]
-200 Added to table
-('john','sip:[email protected]') to 'aliases'
-[jiri@cat sip_router]$ serctl alias show john                    
-&lt;sip:[email protected]&gt;;q=1.00;expires=1073741811
-[jiri@cat sip_router]$ serctl alias rm john  
-200 user (aliases, john) deleted				
-			    </screen>
-			</para>
-			<para>
-			    Note that persistence needs to be turned on in usrloc
-			    module. All changes to aliases will be otherwise lost
-			    on server reboot. To enable persistence, set the
-			    db_mode usrloc parameter to a non-zero value.
-			    <programlisting format="linespecific">
-# ....load module ...
-loadmodule "modules/usrloc/usrloc.so"
-# ... turn on persistence -- all changes to user tables are immediately
-# flushed to mysql
-modparam("usrloc", "db_mode",   1)
-# the SQL address:
-modparam("usrloc", "db_url","mysql://ser:secret@dbhost/ser")
-			    </programlisting>
-			</para>
-	    </section> <!-- user aliases -->
-	    <section id=acl>
-		<title>Access Control (PSTN Gateway)</title>
-			<para>
-			    It is sometimes important to exercise some sort of
-			    access control. A typical use case is when 
-			    <application moreinfo="none">ser</application> is used
-			    to guard a PSTN gateway. If a gateway was not well guarded,
-			    unauthorized users would be able to use it to terminate calls in PSTN,
-			    and cause high charges to its operator.
-			</para>
-			<para>
-			    There are few issues you need to understand when
-			    configuring <application moreinfo="none">ser</application>
-			    for this purpose. First, if a gateway is built or configured to
-			    accept calls from anywhere, callers may easily bypass your
-			    access control server and communicate with the gateway
-			    directly. You then need to enforce at transport layer
-			    that signaling is only accepted if coming via
-			    <application moreinfo="none">ser</application> and
-			    deny SIP packets coming from other hosts and port numbers.
-			    Your network must be configured not to allow forged
-			    IP addresses. Also, you need to turn on record-routing
-			    to assure that all session requests will travel via 
-			    <application moreinfo="none">ser</application>.			    
-			    Otherwise, caller's devices would send subsequent SIP requests 
-			    directly to your gateway, which would fail because of transport 
-			    filtering.
-			</para>
-			<para>
-			    Authorization (i.e., the process of determining who may call where)
-			    is facilitated in <application moreinfo="none">ser</application>
-			    using <emphasis>group membership</emphasis> concept. Scripts make 
-			    decisions on whether a caller is authorized to make a call to
-			    a specific destination based on user's membership in a group.
-			    For example a policy may be set up to allow calls to international
-			    destinations only to users, who are members of an "int" group.			    
-			    Before user's group membership is checked, his identity
-			    must be verified first. Without cryptographic verification of user's
-			    identity, it would be impossible to assert that a caller really
-			    is who he claims to be.
-			</para>
-			<para>
-			    The following script demonstrates, how to configure <application moreinfo="none">ser</application>
-			    as an access control server for a PSTN gateway. The script verifies user
-			    identity using digest authentication, checks user's privileges,
-			    and forces all requests to visit the server.
-			    <example>
-				<title>Script for Gateway Access Control</title>
-				<programlisting format="linespecific">
-&gatewayacl;
-				</programlisting>
-			    </example>
-			</para>
-			<para>
-			    Use the <application moreinfo="none">serctl</application> tool to
-			    maintain group membership. 
-			    <application moreinfo="none">serctl acl grant &lt;username&gt; &lt;group&gt;</application>
-			    makes a user member of a group, 
-			    <application>serctl acl show &lt;username&gt;</application> shows groups
-			    of which a user is member, and
-			    <application>serctl acl revoke &lt;username&gt; [&lt;group&gt;]</application>
-			    revokes user's membership in one or all groups.
-			    <screen format="linespecific">
-[jiri@cat sip_router]$ serctl acl grant john int
-MySql Password: 
-+------+-----+---------------------+
-| user | grp | last_modified       |
-+------+-----+---------------------+
-| john | int | 2002-12-08 02:09:20 |
-+------+-----+---------------------+
-			    </screen>
-			</para>
-	    </section> <!-- access control -->
-	    <section>
-		<title>Accounting</title>
-			<para>
-			    In some scenarios, like termination of calls in PSTN, SIP administrators
-			    may wish to keep track of placed calls. <application moreinfo="none">ser</application>
-			    can be configured to report on completed transactions. Reports are sent
-			    by default to <application moreinfo="none">syslog</application> facility.
-			    Support for RADIUS and mysql accounting exists as well.
-			</para>
-			<para>
-			    Note that <application moreinfo="none">ser</application> is no way 
-			    call-stateful. It reports on completed transactions, i.e., after 
-			    a successful call set up is reported, it drops any call-related 
-			    state. When a call is terminated, transactional state for BYE request
-			    is created and forgotten again after the transaction completes.
-			    This is a feature and not a bug -- keeping only transactional
-			    state allows for significantly higher scalability. It is then
-			    up to the accounting application to correlate call initiation
-			    and termination events.
-			</para>
-			<para>
-			    To enable call accounting, tm and acc modules need to be loaded,
-			    requests need to be processed statefully and labeled for
-			    accounting. That means, if you want a transaction to be reported,
-				the initial request must have taken the path 
-				"<command>setflag(X)</command>, <command>t_relay</command>"
-				in <application>ser</application> script. X must have the
-				value configured in <varname>acc_flag</varname>
-				configuration option.
-			</para>
-			<para>
-				Also note, that by default only transactions that initiate
-				a SIP dialog (typically INVITE) visit a proxy server.
-				Subsequent transactions are exchanged directly between
-				end-devices, do not visit proxy server and cannot be
-				reported. To be able to report on subsequent transactions,
-				you need to force them visit proxy server by turning 
-				record-routing on. 
-			</para>
-			<para>
-				
-			    <example>
-				<title>Configuration with Enabled Accounting</title>
-				<programlisting format="linespecific">
-&accountingexample;
-				</programlisting>
-			    </example>
-			</para>
-	    </section> <!-- accounting -->
-	    <section>
-		<title>Reliability</title>
-
-			<para>
-			    It is essential to guarantee continuous
-			    service operation even under erroneous conditions, 
-			    such as host or network failure. The major issue in such
-			    situations is transfer of operation to a backup
-			    infrastructure and making clients use it.
-			</para>
-			<para>
-			    The SIP standard's use of DNS SRV records has been
-			    explicitly constructed to handle with server failures.
-			    There may be multiple servers responsible for a domain
-			    and referred to by DNS. If it is impossible to communicate
-			    with a primary server, a client can proceed to another one.
-			    Backup servers may be located in a different geographic
-			    area to minimize risk caused by areal operational
-			    disasters: lack of power, flooding, earthquake, etc.
-			    <note>
-				<sidebar>
-				    <para>Unless there are redundant DNS
-				    servers, fail-over capability cannot be guaranteed.
-				    </para>
-				</sidebar>
-			    </note>
-			    Unfortunately, at the moment of writing this documentation
-			    (end of December 2002) only very few SIP products
-			    actually implement the DNS fail-over mechanism. Unless
-			    networks with SIP devices supporting this mechanism are
-			    built, alternative mechanisms must be used to force 
-			    clients to use backup servers. Such a mechanism is
-			    disconnecting primary server and replacing it with
-			    a backup server locally.
-			    It unfortunately precludes geographic dispersion and
-			    requires network multihoming to avoid dependency on
-			    single IP access. Another method is to update DNS
-			    when failure of the primary server is detected.
-			    The primary drawback of this method is its latency:
-			    it may take long time until all clients learn to use
-			    the new server.
-			</para>
-			<para>
-			    The easier part of the redundancy story is replication of 
-			    <application moreinfo="none">ser</application>
-			    data. <application moreinfo="none">ser</application>
-			    relies on replication capabilities of its back-end database.
-			    This works with one exception: user location database.
-			    User location database is a frequently accessed table,
-			    which is thus cached in server's memory to improve
-			    performance. Back-end replication does not affect
-			    in-memory tables, unless server reboots. To facilitate
-			    replication of user location database, 
-			    server's SIP replication feature must be enabled
-			    in parallel with back-end replication.
-			</para>
-			<para>
-			    The design idea of replication of user location database
-			    is easy: Replicate any successful REGISTER requests to
-			    a peer server. To assure that digest credentials can
-			    be properly verified, both servers need to use the same
-			    digest generation secret and maintain synchronized time.
-			    A known limitation of this method is it does not replicate
-			    user contacts entered in another way, for example using
-			    web interface through FIFO server.
-			    The following script example shows configuration of
-			    a server that replicates all REGISTERs.
-			    <example>
-				<title>Script for Replication of User Contacts</title>
-				<programlisting format="linespecific">
-&replicateexample;				    
-				</programlisting>
-			    </example>
-			</para>
-	    </section> <!-- reliability -->
-	    <section>
-		<title>Stateful versus Stateless Forwarding</title>
-		<para>
-		    <application moreinfo="none">ser</application> allows both stateless
-		    and stateful request processing. This memo explains what are pros and cons of
-		    using each method. The rule of thumb is "stateless for scalability,
-		    stateful for services". If you are unsure which you need, stateful
-		    is a safer choice which supports more usage scenarios.
-		</para>
-			<para>
-			    Stateless forwarding with the
-			    <command moreinfo="none">forward(uri:host, uri:port)</command> action
-			    guarantees high scalability. It withstands high load and
-			    does not run out of memory. A perfect use of stateless forwarding
-			    is load distribution.
-			</para>
-			<para>
-			    Stateful forwarding using the <command moreinfo="none">t_relay()</command>
-			    action is known to scale worse. It can quickly run out of memory and
-			    consumes more CPU time. Nevertheless, there are scenarios which are
-			    not implementable without stateful processing. In particular:
-			    <itemizedlist>
-				<listitem>
-				    <para>
-					<emphasis>Accounting</emphasis> requires stateful processing
-					to be able to collect transaction status and issue a single
-					report when a transaction completes.
-				    </para>
-				</listitem>
-				<listitem>
-				    <para>
-					<emphasis>Forking</emphasis> only works with stateful forwarding.
-					Stateless forwarding only forwards to the default URI out of the
-					whole destination set.
-				    </para>
-				</listitem>
-				<listitem>
-				    <para>
-					<emphasis>DNS resolution</emphasis>. DNS resolution may be
-					better served with stateful processing. If a request is forwarded
-					to a destination whose address takes long time to resolve,
-					a server process is blocked and unresponsive. Subsequent 
-					request retransmissions from client will cause other processes
-					to block too if requests are processed statelessly. As a result,
-					<application moreinfo="none">ser</application> will quickly
-					run out of available processes. With stateful forwarding,
-					retransmissions are absorbed and do not cause blocking of
-					another process.
-				    </para>
-				</listitem>
-				<listitem>
-				    <para>
-					<emphasis>Forwarding Services</emphasis>. All sort of services 
-					with the "forward_on_event" logic, which rely on 
-					<command moreinfo="none">t_on_failure</command> tm
-					action must be processed statefully.
-				    </para>
-				</listitem>
-			<listitem>
-			    <para>
-				<emphasis>
-				    Fail-over.
-				</emphasis>
-				If you wish to try out another destination, after a primary destination
-				failed you need to use stateful processing. With stateless processing
-				you never know with what status a forwarded request completed downstream
-				because you immediately release all processing information after the 
-				request is sent out. 
-
-				<note>
-				    <para>
-					Positive return value of stateless
-					<command moreinfo="none">forward</command> action only indicates that
-					a request was successfully sent out, and does not gain any knowledge
-					about whether it was successfully received or replied. Neither does
-					the return value of
-					the stateful <command moreinfo="none">t_relay</command> action family
-					gain you this knowledge. However, these actions store transactional
-					context with which includes original request and allows you to
-					take an action when a negative reply comes back or a timer strikes.
-					See <xref linkend="replyprocessingsection"> for an example script 
-					which launches another
-					branch if the first try fails.
-				    </para>
-				</note>
-
-			    </para>
-			</listitem>
-			    </itemizedlist>
-			</para>
-	    </section> <!-- stateful vs. stateless -->
-	    <section>
-		<title>Serving Multiple Domains</title>
-			<para>
-			    <application moreinfo="none">ser</application> can be configured to
-			    serve multiple domains. To do so, you need to take the following steps:
-			    <orderedlist>
-				<listitem id="createtable">
-				    <para>
-					Create separate subscriber and location database table
-					for each domain served and name them uniquely.
-				    </para>
-				</listitem>
-				<listitem>
-				    <para>
-					Configure your script to distinguish between multiple
-					served domains. Use regular expressions for domain
-					matching as described in <xref linkend="redomainmatching">.
-				    </para>
-				</listitem>
-				<listitem>
-				    <para>
-					Update table names in usrloc and auth actions to reflect
-					names you created in <xref linkend="createtable">.
-				    </para>
-				</listitem>
-				
-			    </orderedlist>
-			</para>
-			<para>
-				The latest <application>SER</application> release includes automated
-				multidomain management which greatly automates maintenance of multiple	
-				domains. Ask our technical support for more help.
-			</para>
-	    </section> <!-- multiple domains -->
-	    <section id="missedcalls">
-		<title>Reporting Missed Calls</title>
-			<para>
-			    <application moreinfo="none">ser</application> can report missed
-			    calls via <application moreinfo="none">syslog</application> facility
-			    or to mysql. Mysql reporting can be utilized by 
-			    <application moreinfo="none">ser</application>'s 
-			    complementary web-interface, <application moreinfo="none">serweb</application>.
-			    (See more in <xref linkend="serweb">).
-			</para>
-			<para>
-			    Reporting on missed calls is enabled by acc module.
-			    There are two cases, on which you want to report. The first
-			    case is when a callee is off-line. The other case is when
-			    a user is on-line, but call establishment fails. There
-			    may be many failure reasons (call cancellation, inactive phone,
-			    busy phone, server timer, etc.), all of them leading to
-			    a negative (>=300) reply sent to caller. The acc module
-			    can be configured to issue a missed-call report whenever
-			    a transaction completes with a negative status. Two following
-			    script fragment deals with both cases.
-			</para>
-			<para>
-			    First, it reports
-			    on calls missed due to off-line callee status
-			    using the <command moreinfo="none">acc_request</command>
-			    action. The action is wrapped in transactional
-			    processing (<command moreinfo="none">t_newtran</command>)
-			    to guarantee that reports are not
-			    duplicated on receipt of retransmissions.
-			    </para>
-			<para>
-			    Secondly, transactions to on-line users are marked
-			    to be reported on failure. That is what the 
-			    <command moreinfo="none">setflag(3)</command> action
-			    is responsible for, along with the configuration option
-			    "log_missed_flag". This option configures <application moreinfo="none">ser</application>
-			    to report on all transactions, which were marked
-			    with flag 3.			   
-			    <programlisting format="linespecific">
-loadmodule("modules/tm/tm.so");
-loadmodule("modules/acc/acc.so");
-....
-# if a call is labeled using setflag(3) and is missed, it will
-# be reported
-...
-modparam("acc", "log_missed_flag", 3 );
-if (!lookup("location")) {
-     # call invitations to off-line users are reported using the
-     # acc_request action; to avoid duplicate reports on request
-     # retransmissions, request is processed statefully (t_newtran,
-     # t_reply)
-     if ((method=="INVITE" || method=="ACK") && t_newtran() ) {
-          t_reply("404", "Not Found");
-	  acc_request("404 Not Found");
-          break;
-     };
-     # all other requests to off-line users are simply replied
-     # statelessly and no reports are issued
-    sl_send_reply("404", "Not Found");
-    break;
-} else {
-     # user on-line; report on failed transactions; mark the
-     # transaction for reporting using the same number as 
-     # configured above; if the call is really missed, a report
-     # will be issued
-     setflag(3);
-     # forward to user's current destination
-     t_relay();
-     break;
-};
-			    </programlisting>
-			    
-			</para>
-	    </section> <!-- missed calls -->
-	    <section>
-		<title>NAT Traversal</title>
-		<para>
-		    NATs are worst things that ever happened to SIP. These devices
-		    are very popular because they help to conserve IP address space
-		    and save money charged for IP addresses. Unfortunately, they
-		    translate addresses in a way which is not compatible with SIP.
-		    SIP advertises receiver addresses in its payload. The advertised
-		    addresses are invalid out of NATed networks. As a result,
-		    SIP communication does not work across NATs without extra
-		    effort.
-		</para>
-		<para>
-		    There are few methods that may be deployed to traverse NATs.
-		    How proper their use is depends on the deployment scenario.
-		    Unfortunately, all the methods have some limitations and
-		    there is no straight-forward solution addressing all
-		    scenarios. Note that none of these methods takes explicit
-		    support in <application moreinfo="none">ser</application>.
-		</para>
-		<para>
-		    The first issue is whether SIP users are in control of 
-		    their NATs. If not (NATs are either operated by ISP or
-		    they are sealed to prevent users setting them up), the
-		    only method is use of a STUN-enabled phone. STUN is 
-		    a very simple protocol used to fool NAT in such a way,
-		    they permit SIP sessions. Currently, we are aware of
-		    one softphone (kphone) and one hardphone (snom) with
-		    STUN support, other vendors are working on STUN support
-		    too. Unfortunately, STUN gives no NAT traversal
-		    guarantee -- there are types of NATs, so called
-		    symmetric NATs, over which STUN fails to work.
-		    <note>
-			<para>
-			    There is actually yet another method to address
-			    SIP-unaware, user-uncontrolled NATs. It is based
-			    on a proxy server, which relays all signaling and
-			    media and mangles packets to make them more
-			    NAT-friendly. The very serious problem with this
-			    method is it does not scale.
-			</para>
-		    </note>
-		</para>
-		<para>
-		    If users are in control of their own NAT, as typically residential
-		    users are, they can still use STUN. However, they may use other
-		    alternatives too. One of them is to replace their NAT with
-		    a SIP-aware NAT. Such NATs have built-in SIP awareness,
-		    that patches problems caused by address translations. Prices
-		    of such devices are getting low and there are available
-		    implementations (Intertex, Cisco/PIX). No special support
-		    in phones is needed.
-		</para>
-		<para>
-		    Other emerging option is UPnP. UPnP is a protocol that allows
-		    phones to negotiate with NAT boxes. You need UPnP support in
-		    both, NAT and phones. As UPnP NATs are quite affordable,
-		    costs are not an obstacle. Currently, we are aware of one
-		    SIP phone (SNOM) with UPnP support.
-		</para>
-		<para>
-		    Geeks not wishing to upgrade their firewall to a SIP-aware or
-		    UPnP-enabled one may try to configure static address translation.
-		    That takes phones with configuration ability to use fixed port
-		    numbers and advertise outside address in signaling. Cisco phones
-		    have this capability, for example. The NAT devices need to
-		    be configured to translate outside port ranges to the 
-		    ranges configured in phones.		    
-		</para>
-	    </section> <!-- NAT traversal -->
-
-		<section>
-		<title>Using Only Latest User's Contact for Forwarding
-		</title>
-			<para>
-				In some scenarios, it may be beneficial only to use only one
-				registered contact per user. If that is the case, setting
-				registrar module's parameter <varname>append_branches</varname>
-				to 1 will eliminate forking and forward all requests only
-				to a single contact. If there are multiple contacts, a contact
-				with highest priority is chosen. This can be changed to
-				the "freshest" contact by setting module parameter's
-				<varname>desc_time_order</varname> to 1.
-			</para>
-
-		</section>
-
-	    <section>
-		<title>Authentication Policy: Prevention of Unauthorized Domain 
-		    Name Use in From and More</title>
-		<para>
-		    Malicious users can claim a name of domain, to which they do 
-		    not administratively belong, in From header field. This
-		    behavior cannot be generally prevented. The reason is
-		    that requests with such a faked header field do not need
-		    to visit servers of the domain in question. However, if they
-		    do so, it is desirable to assure that users claiming
-		    membership in a domain are actually associated with it.
-		    Otherwise the faked requests would be relayed and appear
-		    as coming from the domain, which would increase
-		    credibility of the faked address and decrease credibility of
-		    the proxy server.
-		</para>
-		<para>
-		    Preventing unauthorized domain name use in relayed requests 
-		    is not difficult.
-		    One needs to authenticate each request with name of the
-		    served domain in From header field. To do so, one can
-		    search for such a header field using <command moreinfo="none">search</command>
-		    action (textops module) and force authentication if the
-		    search succeeds.
-		    <note>
-			<para>
-			    A straight-forward solution might be to authenticate
-			    ALL requests. However, that only works in closed
-			    networks in which all users have an account in the
-			    server domain. In open networks, it is desirable to permit
-			    incoming calls from callers from other domains without
-			    any authentication. For example, a company may wish
-			    to accept calls from unknown callers who are
-			    new prospective customers.
-			    
-			</para>
-		    </note>
-		    <programlisting format="linespecific">
-# does the user claim our domain "foo.bar" in From?
-if (search("^(f|From):.*foo.bar")) {
-        # if so, verify credential
-	if (!proxy_authorize("foo.bar", "subscriber")) { 
-              # don't proceed if credentials broken; challenge
-	      proxy_challenge("foo.bar", "0");
-	      break;
-        };
-};
-		    </programlisting>
-		</para>
-		<para>
-		    In general, the authentication policy may be very rich. You may not
-		    forget each request deserves its own security and you need to 
-		    decide whether it shall be authenticated or not. As mentioned
-		    above, in closed networks, you may want to authenticate absolutely 
-		    every request. That however prohibits traffic from users from
-		    other domains. A pseudo-example of a reasonable policy is attached:
-		    it looks whether a request is registration, it claims to originate
-		    from our domain in From header field, or is a local request to
-		    another domain.
-		    <programlisting format="linespecific">
-# (example provided by Michael Graff on [serusers] mailing list
-if (to me):
-    if register
-          www_authorize or fail if not a valid register
-          done
-    if claiming to be "From" one of the domains I accept registrations for
-          proxy_authorize
-          done
-    if not to me (I'm relaying for a local phone to an external address)
-          proxy_authorize
-          done
-		    </programlisting>
-		</para>
-		<para>
-		    You also may want to apply additional restriction to how
-		    digest username relates to usernames claimed in From and
-		    To header fields. For example, the <command moreinfo="none">check_to</command>
-		    action enforces the digest id to be equal to username
-		    in To header fields. That is good in preventing someone
-		    with valid credentials to register as someone else
-		    (e.g., sending a REGISTER with valid credentials of
-		    "joe" and To belonging to "alice"). Similarly,
-		    <command moreinfo="none">check_from</command> is used
-		    to enforce username in  from to equal to digest id.
-		    <note>
-			<para>
-			    There may be a need for a more complex relationship
-			    between From/To username and digest id. For example,
-			    providers with an established user/password database
-			    may wish to keep using it, whereas permitting users
-			    to claim some telephone numbers in From. To address
-			    such needs generally, there needs to be a 1:N mapping
-			    between digest id and all usernames that are acceptable
-			    for it. This is being addressed in a newly contributed
-			    module "domain", which also addresses more generally
-			    issues of domain matching for multidomain scenarios.
-			</para>
-		    </note>
-		</para>
-		<para>
-		    Other operational aspect affecting the authentication policy
-		    is guarding PSTN gateways (see <xref linkend="acl">). There
-		    may be destinations that are given away for free whereas
-		    other destinations may require access control using
-		    group membership, to which  authentication is a prerequisite.
-		</para>
-
-	    </section> <!-- authentication policy, faked froms -->
-	    <section>
-		<title>Connecting to PBX Voicemail Using a Cisco Gateway</title>
-		<para>
-		    In some networks, administrators may wish to utilize their
-		    PBX voicemail systems behind PSTN gateways. There is a practical problem
-		    in many network settings: it is not clear for whom a call to
-		    voicemail is. If voicemail is identified by a single number,
-		    which is then put in INVITE's URI, there is no easy way to
-		    learn for whom a message should be recorded. PBX voicemails
-		    utilize that PSTN protocols signal the number of originally
-		    called party. If you wish to make the PBX voicemail work,
-		    you need to convey the number in SIP and translate it in
-		    PSTN gateways to its PSTN counterpart.
-		</para>
-		<para>
-		    There may be many different ways to achieve this scenario. Here
-		    we describe the proprietary mechanism Cisco gateways use and how to 
-		    configure <application moreinfo="none">ser</application> to
-		    make the gateways happy. Cisco gateways expect the number
-		    of originally called party to be located in proprietary
-		    <varname>CC-Diversion</varname> header field. When a SIP 
-		    INVITE sent via a PSTN gateway to PBX voicemail has number
-		    of originally called party in the header field, the voicemail
-		    system knows for whom the incoming message is. That is at least
-		    true for AS5300/2600 with Cisco IOS 12.2.(2)XB connected to
-		    Nortel pbxs via PRI. (On the other hand, 12.2.(7b) is known
-		    not to work in this scenario.)
-		</para>
-		<para>
-		    <application moreinfo="none">ser</application> needs then to
-		    be configured to append the <varname>CC-Diversion</varname>
-		    header field name for INVITEs sent to PBX voicemail.
-		    The following script shows that: when initial forwarding
-		    fails (nobody replies, busy is received, etc.), a new branch
-		    is initiated to the pbx's phone number. 
-		    <command moreinfo="none">append_urihf</command> is used to
-		    append the <varname>CC-Diversion</varname> header field. It
-		    takes two parameters: prefix, which includes header name,
-		    and suffix which takes header field separator. 
-		    <command moreinfo="none">append_urihf</command> inserts
-		    original URI between those two.
-		    <example>
-			<title>Forwarding to PBX/Voicemail via Cisco Gateways</title>
-			<programlisting format="linespecific">
-&ccdiversion;
-			</programlisting>
-		    </example>
-		    
-		</para>
-	    </section>
-	</section> <!-- howtos -->
-
-	<section>
-	    <title>Troubleshooting</title>
-	    <para>
-		This section gathers practices how to deal with errors
-		known to occur frequently. To understand how to watch
-		SIP messages, server logs, and in general how to
-		troubleshoot, read also <xref linkend="operationalpractices">. 
-	    </para>
-	    <qandaset>
-		<qandaentry>
-		    <question>
-			<para>
-			SIP requests are replied by <application>ser</application> with
-			"483 Too Many Hops" or "513 Message Too Large"
-		        </para>
-		    </question>
-
-		    <answer>
-			<para>
-			    In both cases, the reason is probably an error in
-			    request routing script which caused an infinite loop.
-			    You can easily verify whether this happens by
-			    watching SIP traffic on loopback interface. A typical
-			    reason for misrouting is a failure to match local
-			    domain correctly. If a server fails to recognize
-			    a request for itself, it will try to forward it
-			    to current URI in believe it would forward them
-			    to a foreign domain. Alas, it forwards the request
-			    to itself again. This continues to happen until
-			    value of max_forwards header field reaches zero
-			    or the request grows too big. Solutions is easy:
-			    make sure that domain matching is correctly
-			    configured. See <xref linkend="domainmatching">
-			    for more information how to get it right.
-			</para>
-		    </answer>		    
-		</qandaentry>
-		<qandaentry>
-			
-		    <question>
-			        
-			<para>
-			
-			    Windows Messenger authentication fails.
-			</para>
-		    </question>
-		    <answer>
-			<anchor id="msmbug">
-			<para>
-			    The most likely reason for this problem is a bug
-			    in Windows Messenger. WM only authenticates if
-			    server name in request URI equals authentication
-			    realm. After a challenge is sent by SIP server,
-			    WM does not resubmit the challenged request at all
-			    and pops up authentication window again.
-			    If you want to authenticate WM, you need to
-			    set up your realm value to equal server name.
-			    If your server has no name, IP address can be used
-			    as realm too. The realm value is configured in
-				scripts as the first parameter of all
-				<command>{www|proxy}_{authorize|challenge}</command>
-				actions.
-			</para>
-		    </answer>
-		</qandaentry>
-		<qandaentry>
-		    <question>
-			<para>
-			    On a multihomed host, forwarded messages carry other 
-			    interface in Via than used for sending, or messages 
-			    are not sent and an error log is issued "invalid 
-			    sendtoparameters one possible reason is the server 
-			    is bound to localhost".
-			</para>
-		    </question>
-		    <answer>
-			<anchor id="mhomed">
-			<para>
-			    Set the configuration option <varname>mhomed</varname>
-			    to "1". <application moreinfo="none">ser</application>
-			    will then attempt to calculate the correct interface.
-			    It's not done by default as it degrades performance
-			    on single-homed hosts or multi-homed hosts that are
-			    not set-up as routers.
-			</para>
-		    </answer>
-		</qandaentry>
-		<qandaentry>
-		    <question>
-			<para>
-			    I receive "ERROR: t_newtran: transaction already in process" in my logs.
-			</para>
-		    </question>
-		    <answer>
-			<para>
-			    That looks like an erroneous use of tm module in script.
-			    tm can handle only one transaction per request. If you
-			    attempt to instantiate a transaction multiple times,
-			    <application moreinfo="none">ser</application> will complain.
-			    Anytime any of <command moreinfo="none">t_newtran</command>,
-			    <command moreinfo="none">t_relay</command> or 
-			    <command moreinfo="none">t_relay_to_udp</command> actions is
-			    encountered, tm attempts to instantiate a transaction.
-			    Doing so twice fails. Make sure that any of this
-			    commands is called only once during script execution.
-			</para>
-		    </answer>
-		</qandaentry>
-		<qandaentry>
-		    <question>
-			<para>
-			    I try to add an alias but 
-			    <command moreinfo="none">serctl</command>
-			    complains that table does not exist.
-			</para>
-		    </question>
-		    <answer>
-			<para>
-			    You need to run <application moreinfo="none">ser</application>
-			    and use the command
-			    <command moreinfo="none">lookup("aliases")</command>
-			    in its routing script. That's because the table 
-			    of aliases is
-			    stored in cache memory for high speed. The cache
-			    memory is only set up when the 
-			    <application moreinfo="none">ser</application>
-			    is running and configured to use it. If that is
-			    not the case, 
-			    <application moreinfo="none">serctl</application>
-			    is not able to manipulate the aliases table.
-			</para>
-		    </answer>
-		</qandaentry>
-
-	    <qandaentry>
-		<question>
-		    <para>I started <application>ser</application> with
-			<varname>children=4</varname> but many more processes
-			were started. What is wrong?
-			</para>
-		    </question>
-		<answer>
-		    <para>
-			That's ok. The <varname>children</varname> parameter defines
-			how many children should process each transport protocol in
-			parallel. Typically, the server listens to multiple protocols
-			and starts other supporting processes like timer or FIFO
-			server too. Call <application>serctl ps</application> to watch
-			running processes.
-			</para>
-		    </answer>
-		</qandaentry>
-	    <qandaentry>
-		<question>
-		    <para>
-			I decided to use a compiled version of <application>ser</application>
-			but it does not start any more.
-			</para>
-		    </question>
-		<answer>
-		    <para>
-			You probably kept the same configuration file, which tries to load modules
-			from the binary distribution you used previously. Make sure that modules
-			paths are valid and point to where you compiled <application>ser</application>.
-			Also, watch logs for error messages "ERROR: load_module: could not open 
-			module".
-			</para>
-		    </answer>
-		</qandaentry>
-	    
-	    </qandaset>
-	</section> <!-- troubleshooting -->
-    </chapter> <!-- operation -->

doc/seruser/operation.xml

@@ -0,0 +1,1507 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4//EN"
+                      "file:///usr/share/sgml/docbook/dtd/xml/4/docbookx.dtd">
+
+<section id="operation" xmlns:xi="http://www.w3.org/2001/XInclude">
+    <sectioninfo>
+	<revhistory>
+	    <revision>
+		<revnumber>$Revision$</revnumber>
+		<date>$Date$</date>
+	    </revision>
+	</revhistory>
+    </sectioninfo>
+
+    <title>Server Operation</title>
+    <section id="operationalpractices">
+	<title>Recommended Operational Practices</title>
+
+	<para>
+	    Operation of a SIP server is not always easy task.
+	    Server administrators are challenged by broken or
+	    misconfigured user agents, network and host failures,
+	    hostile attacks and other stress-makers. All such
+	    situations may lead to an operational failure. It is sometimes
+	    very difficult to figure out the root reason of
+	    a failure, particularly in a distributed environment
+	    with many SIP components involved.		
+	    In this section,
+	    we share some of our practices and refer to tools
+	    which have proven to
+	    make life of administrators easier
+	</para>
+
+	<qandaset>
+	    <qandaentry>
+		<question>
+		    <para>
+			Keeping track of messages is good
+		    </para>
+		</question>
+		<answer>
+		    <para>
+			Frequently, operational errors are discovered or reported
+			with a delay.
+			Users frustrated by an error
+			frequently approach administrators
+			and scream "even though my SIP requests were absolutely ok
+			yesterday, they were mistakenly denied by your server".
+			If administrators do not record all SIP traffic at
+			their site, they will be no more able to identify
+			the problem reason.
+			We thus recommend that site
+			operators record all messages passing their site and keep them
+			stored for some period of time.
+			They may use utilities such as 
+			<application>ngrep 
+			</application> or 
+			<application>tcpdump
+			</application>.
+			There is also a utility <application>
+			    scripts/harv_ser.sh</application> in <application>
+			    ser</application> distribution for post-processing
+			of captured messages. It summarizes messages captured
+			by reply status and user-agent header field.
+		    </para>
+		</answer>
+	    </qandaentry>
+	    <qandaentry>
+		<question>
+		    <para>
+			Real-time Traffic Watching
+		    </para>
+		</question>
+		<answer>
+		    <para>
+			Looking at SIP messages in real-time may help to gain
+			understanding of problems. Though there are commercial
+			tools available, using a simple, text-oriented tool
+			such as <application>ngrep</application> makes the job very well thanks to SIP's textual nature.
+		    </para>
+		    <example id="usingngrep">
+			<title>Using <application>ngrep</application>
+			</title>
+			<para>In this example, all messages at port 5060
+			    which include the string "bkraegelin" are captured
+			    and displayed</para>
+			<programlisting>
+[jiri@fox s]$ ngrep bkraegelin@ port 5060
+interface: eth0 (195.37.77.96/255.255.255.240)
+filter: ip and ( port 5060 )
+match: bkraegelin@
+#
+U +0.000000 153.96.14.162:50240 -> 195.37.77.101:5060
+ REGISTER sip:iptel.org SIP/2.0.
+ Via: SIP/2.0/UDP 153.96.14.162:5060.
+ From: sip:[email protected].
+ To: sip:[email protected].
+ Call-ID: [email protected].
+ Date: Thu, 26 Sep 2002 22:03:55 GMT.
+ CSeq: 101 REGISTER.
+ Expires: 10.
+ Content-Length: 0.
+ .
+
+#
+U +0.000406 195.37.77.101:5060 -> 153.96.14.162:5060
+ SIP/2.0 401 Unauthorized.
+ Via: SIP/2.0/UDP 153.96.14.162:5060.
+ From: sip:[email protected].
+ To: sip:[email protected].
+ Call-ID: [email protected].
+ CSeq: 101 REGISTER.
+ WWW-Authenticate: Digest realm="iptel.org", nonce="3d9385170000000043acbf6ba9c9741790e0c57adee73812", algorithm=MD5.
+ Server: Sip EXpress router(0.8.8 (i386/linux)).
+ Content-Length: 0.
+ Warning: 392 127.0.0.1:5060 "Noisy feedback tells: pid=31604 req_src_ip=153.96.14.162 in_uri=sip:iptel.org out_uri=sip:iptel.org via_cnt==1".
+			</programlisting>
+		    </example>
+		</answer>
+	    </qandaentry>
+	    <qandaentry>
+		<question>
+		    <para>
+			Tracing Errors in Server Chains
+		    </para>
+		</question>
+		<answer>
+		    <para>
+			A request may pass any number of proxy servers on
+			its path to its destination. If an error occurs
+			in the chain, it is difficult for upstream troubleshooters
+			and/or users complaining to administrators to learn 
+			more about error circumstances. 
+			<application>ser
+			</application> does its best and displays extensive
+			diagnostics information in SIP replies. It allows 
+			troubleshooters and/or users who report to troubleshooters
+			to gain additional knowledge about request processing
+			status. 
+			This extended debugging information is part of the warning 
+			header field. See <xref linkend="usingngrep"/> for an illustration
+			    of a reply that includes such a warning header field. The header
+			    field contains the following pieces of information:
+			    <itemizedlist>
+				<listitem>
+				    <para>
+					Server's IP Address -- good to identify
+					from which server in a chain the reply
+					came.
+				    </para>
+				</listitem>
+				<listitem>
+				    <para>
+					Incoming and outgoing URIs -- good to
+					learn for which URI the reply was
+					generated, as it may be rewritten
+					many times in the path. Particularly
+					useful for debugging of numbering plans.
+				    </para>
+				</listitem>
+				<listitem>
+				    <para>
+					Number of Via header fields in replied
+					request -- that helps in assessment of
+					request path length. Upstream clients would
+					not know otherwise, how far away in terms
+					of SIP hops their requests were replied.
+				    </para>
+				</listitem>
+				<listitem>
+				    <para>
+					Server's process id. That is useful for
+					debugging to discover situations when
+					multiple servers listen at the same
+					address.
+				    </para>
+				</listitem>
+				<listitem>
+				    <para>
+					IP address of previous SIP hop as seen by
+					the SIP server.
+				    </para>
+				</listitem>
+			    </itemizedlist>
+		    </para>
+		    <para>
+			If server administrator is not comfortable with
+			disclosing all this information, he can turn them
+			off using the <varname>sip_warning</varname> configuration
+			option.
+		    </para>
+		    <para>
+			A nice utility for debugging server chains is
+			<application>sipsak</application>,
+			SIP Swiss Army Knife, traceroute-like tool for SIP
+			developed at iptel.org. It allows you to send
+			OPTIONS request with low, increasing Max-Forwards 
+			header-fields and follow how it propagates in
+			SIP network. See its webpage at
+			<ulink url="http://sipsak.berlios.de/">
+			    http://sipsak.berlios.de/
+			</ulink>.
+		    </para>
+		    <example>
+			<title>Use of SIPSak for Learning SIP Path</title>
+			<programlisting>
+[jiri@bat sipsak]$ ./sipsak -T -s sip:[email protected]
+warning: IP extract from warning activated to be more informational
+0: 127.0.0.1 (0.456 ms) SIP/2.0 483 Too Many Hops
+1: ?? (31.657 ms) SIP/2.0 200 OK
+   without Contact header
+			</programlisting>
+			<para>
+			    Note that in this example, the second hop
+			    server does not issue any warning header fields
+			    in replies and it is thus impossible to display 
+			    its IP address in <application>
+				SIPsak</application>'s output.
+			</para>
+		    </example>
+		</answer>
+	    </qandaentry>
+	    <qandaentry>
+		<question>
+		    <para>
+			Watching Server Health
+		    </para>
+		</question>
+		<answer>
+		    <para>
+			Watching Server's operation status in real-time may
+			also be a great aid for trouble-shooting. 
+			<application>ser</application> has an excellent 
+			facility, a FIFO server, which allows UNIX
+			tools to access server's internals. (It is 
+			similar to how Linux tool access Linux kernel
+			via the proc file system.) The FIFO server
+			accepts commands via a FIFO (named pipe) and
+			returns data asked for. Administrators do not
+			need to learn details of the FIFO communication
+			and can serve themselves using a front-end
+			utility <application>serctl</application>.
+			Of particular interest for 
+			monitoring server's operation are 
+			<application>serctl</application>
+			commands
+			<command>ps</command> and
+			<command>moni</command>.
+			The former displays running 
+			<application>ser</application>
+			processes, whereas the latter shows statistics.
+		    </para>
+		    <example>
+			<title>serctl ps command</title>
+			<para>
+			    This example shows 10 processes running at a host.
+			    The process 0, "attendant" watches child processes
+			    and terminates all of them if a failure occurs in
+			    any of them. Processes 1-4 listen at local
+			    interface and processes 5-8 listen at Ethernet
+			    interface at port number 5060. Process number
+			    9 runs FIFO server, and process number 10
+			    processes all server timeouts.
+			</para>
+			<programlisting>
+[jiri@fox jiri]$ serctl ps
+0	31590	attendant
+1	31592	receiver child=0 sock=0 @ 127.0.0.1::5060
+2	31595	receiver child=1 sock=0 @ 127.0.0.1::5060
+3	31596	receiver child=2 sock=0 @ 127.0.0.1::5060
+4	31597	receiver child=3 sock=0 @ 127.0.0.1::5060
+5	31604	receiver child=0 sock=1 @ 195.37.77.101::5060
+6	31605	receiver child=1 sock=1 @ 195.37.77.101::5060
+7	31606	receiver child=2 sock=1 @ 195.37.77.101::5060
+8	31610	receiver child=3 sock=1 @ 195.37.77.101::5060
+9	31611	fifo server
+10	31627	timer
+			</programlisting>
+		    </example>
+		</answer>
+	    </qandaentry>
+	    <qandaentry>
+		<question>
+		    <para>
+			Is Server Alive
+		    </para>
+		</question>
+		<answer>
+		    <para>
+			It is essential for solid operation to know
+			continuously that server is alive. We've been
+			using two tools for this purpose. 
+			<application>sipsak</application>
+			does a great job of "pinging" a server, which
+			may be used for alerting on unresponsive servers.
+		    </para>
+		    <para>
+			<application>monit</application> is
+			a server watching utility which alerts when
+			a server dies.
+		    </para>
+		</answer>
+	    </qandaentry>
+	    <qandaentry>
+		<question>
+		    <para>
+			Dealing with DNS
+		    </para>
+		</question>
+		<answer>
+		    <para>
+			SIP standard leverages DNS. Administrators of
+			<application>ser</application> should
+			be aware of impact of DNS on server's operation.
+			Server's attempt to resolve an unresolvable address
+			may block a server process in terms of seconds. To be
+			safer that the server doesn't stop responding
+			due to being blocked by DNS resolving, we recommend
+			the following practices:
+			<itemizedlist>
+			    <listitem>
+				<para>
+				    Start a sufficient number of children processes.
+				    If one is blocked, the other children will
+				    keep serving.
+				</para>
+			    </listitem>
+			    <listitem>
+				<para>
+				    Use DNS caching. For example, in Linux,
+				    there is an <application>
+					nscd</application> daemon available for
+				    this purpose.
+				</para>
+			    </listitem>
+			    <listitem>
+				<para>
+				    Process transactions statefully if memory
+				    allows. That helps to absorb retransmissions
+				    without having to resolve DNS for each of
+				    them.
+				</para>
+			    </listitem>
+			</itemizedlist>
+		    </para>
+		</answer>
+	    </qandaentry>
+	    <qandaentry id="logging">
+		<question>
+		    <para>
+			Logging
+		    </para>
+		</question>
+		<answer>
+			<para>
+			    <application>ser</application> by default logs
+			    to <application>syslog</application> facility.
+			    It is very useful to watch log messages for
+			    abnormal behavior. Log messages, subject to
+			    <application>syslog</application> configuration
+			    may be stored at different files, or even at remote
+			    systems. A typical location of the log file is
+			    <filename>/var/log/messages</filename>.
+			</para>
+			<note>
+			    <para>
+				One can also use other <application>syslogd</application>
+				implementation. <application>metalog</application>
+				(<ulink url="http://metalog.sourceforge.net/">
+				    http://metalog.sourceforge.net/
+				</ulink>)
+				features regular expression matching that enables
+				to filter and group log messages.
+			    </para>
+			</note>
+			<para>
+			    For the purpose of debugging configuration scripts, one may
+			    want to redirect log messages to console not to pollute
+			    syslog files. To do so configure <application>ser</application>
+			    in the following way:
+			    <itemizedlist>
+				<listitem>
+				    <para>
+					Attach ser to console by setting <varname>fork=no</varname>.
+				    </para>
+				</listitem>
+				<listitem>
+				    <para>
+					Set explicitly at which address 
+					<application>ser</application>
+					should be listening, e.g., <varname>listen=192.168.2.16</varname>.
+				    </para>
+				</listitem>
+				<listitem>
+				    <para>
+					Redirect log messages to standard error by setting
+					<varname>log_stderror=yes</varname>
+				    </para>
+				</listitem>
+				<listitem>
+				    <para>
+					Set appropriately high log level. (Be sure that you redirected logging
+					to standard output. Flooding system logs with many detailed messages
+					would make the logs difficult to read and use.) You can set the global
+					logging threshold value with the option <varname>debug=nr</varname>,
+					where the higher <varname>nr</varname> the more detailed output.
+					If you wish to set log level only for some script events, include
+					the desired log level as the first parameter of the
+					<command>log</command> action in your script.
+					The messages will be then printed if <command>log</command>'s
+					level is lower than the global threshold, i.e., the lower the more
+					noisy output you get.
+					<example>
+					    <title>Logging Script</title>
+					    <programlisting>
+<xi:include href="../../examples/logging.cfg" parse="text"/>
+					    </programlisting>
+					    <para>
+						The following SIP message causes then logging output as shown
+						bellow.
+					    </para>
+					    <programlisting>
+REGISTER sip:192.168.2.16 SIP/2.0
+Via: SIP/2.0/UDP 192.168.2.33:5060
+From: sip:[email protected]
+To: sip:[email protected]
+Call-ID: [email protected]
+Date: Thu, 27 Feb 2003 15:10:52 GMT
+CSeq: 101 REGISTER
+User-Agent: CSCO/4
+Contact: sip:[email protected]:5060
+Content-Length: 0
+Expires: 600                                 
+					    </programlisting>
+					    <programlisting>
+[jiri@cat sip_router]$ ./ser -f examples/logging.cfg 
+Listening on 
+	192.168.2.16 [192.168.2.16]::5060
+	Aliases: cat.iptel.org:5060 cat:5060 
+WARNING: no fork mode 
+0(0) INFO: udp_init: SO_RCVBUF is initially 65535
+0(0) INFO: udp_init: SO_RCVBUF is finally 131070
+0(17379) REGISTER received
+0(17379) request for other domain received					
+					    </programlisting>
+					</example>
+				    </para>
+				</listitem>
+			    </itemizedlist>
+			</para>
+		</answer>
+	    </qandaentry>
+	    <qandaentry>
+		<question>
+		    <para>
+			Labeling Outbound Requests
+		    </para>
+		</question>
+		<answer>
+		    <para>
+			Without knowing, which pieces of script code a relayed
+			request visited, trouble-shooting would be difficult.
+			Scripts typically apply different processing to
+			different routes such as to IP phones and PSTN
+			gateways. We thus recommend to label outgoing
+			requests with a label describing the type of processing
+			applied to the request.
+		    </para>
+		    <para>
+			Attaching "routing-history" hints to relayed
+			requests is as easy as using the 
+			<command>append_hf</command>
+			action exported by textops module. The following
+			example shows how different labels are attached
+			to requests to which different routing logic
+			was applied.
+			<example>
+			    <title>"Routing-history" labels</title>
+			    <programlisting>
+# is the request for our domain?
+# if so, process it using UsrLoc and label it so.
+if (uri=~[@:\.]domain.foo") {
+    if (!lookup("location")) {
+        sl_send_reply("404", "Not Found");
+        break;
+    };
+    # user found -- forward to him and label the request
+    append_hf("P-hint: USRLOC\r\n");
+} else {
+    # it is an outbound request to some other domain --
+    # indicate it in the routing-history label
+    append_hf("P-hint: OUTBOUND\r\n");
+};
+t_relay();
+			    </programlisting>
+			    <para>
+				This is how such a labeled requests looks
+				like. The last header field includes
+				a label indicating the script processed
+				the request as outbound.
+			    </para>
+			    <programlisting>
+#
+U 2002/09/26 02:03:09.807288 195.37.77.101:5060 -> 203.122.14.122:5060
+ SUBSCRIBE sip:[email protected] SIP/2.0.
+ Max-Forwards: 10.
+ Via: SIP/2.0/UDP 195.37.77.101;branch=53.b44e9693.0.
+ Via: SIP/2.0/UDP 203.122.14.115:16819.
+ From: sip:[email protected];tag=5c7cecb3-cfa2-491d-a0eb-72195d4054c4.
+ To: sip:[email protected].
+ Call-ID: [email protected].
+ CSeq: 2 SUBSCRIBE.
+ Contact: sip:203.122.14.115:16819.
+ User-Agent: Windows RTC/1.0.
+ Proxy-Authorization: Digest username="rajeshacl", realm="iptel.org", algorithm="MD5", uri="sip:[email protected]", nonce="3d924fe900000000fd6227db9e565b73c465225d94b2a938", response="a855233f61d409a791f077cbe184d3e3".
+ Expires: 1800.
+ Content-Length: 0.
+ P-hint: OUTBOUND.
+			    </programlisting>
+			</example>
+		    </para>
+		</answer>
+	    </qandaentry>
+	</qandaset>
+    </section> <!-- operational practises -->
+    
+    <section>
+	<title>HOWTOs</title>
+	<para>
+	    This section is a "cookbook" for dealing with common tasks, such as
+	    user management or controlling access to PSTN gateways.
+	</para>
+	<section>
+	    <title>User Management</title>
+	    
+	    <para>
+		There are two tasks related to management of SIP users:
+		maintaining user accounts and maintaining user contacts.
+		Both these jobs can be done using the 
+		<application>serctl</application>
+		command-line tool. Also, the complimentary web
+		interface, <application>serweb</application>,
+		can be used for this purpose as well.
+	    </para>
+	    <para>
+		If user authentication is turned on, which is a highly
+		advisable practice, user account must be created before
+		a user can log in. To create a new user account, call the
+		<command>serctl add</command> utility
+		with username, password and email as parameters. It
+		is important that the environment <varname>SIP_DOMAIN</varname>
+		is set to your realm and matches realm values used in
+		your script. The realm value is used for calculation
+		of credentials stored in subscriber database, which are
+		bound permanently to this value.
+		<screen>
+[jiri@cat gen_ha1]$ export SIP_DOMAIN=foo.bar
+[jiri@cat gen_ha1]$ serctl add newuser secret [email protected]
+MySql Password: 
+new user added
+		</screen>
+	    </para>
+	    <para><application>serctl</application> can
+		also change user's password or remove existing accounts
+		from system permanently.
+		<screen>
+[jiri@cat gen_ha1]$ serctl passwd newuser newpassword
+MySql Password: 
+password change succeeded
+[jiri@cat gen_ha1]$ serctl rm newuser                
+MySql Password: 
+user removed
+		</screen>
+	    </para>
+	    <para>
+		User contacts are typically automatically uploaded by SIP phones
+		to server during registration process and administrators do not
+		need to worry about them. However, users
+		may wish to append permanent contacts to PSTN gateways
+		or to locations in other administrative domains. 
+		To manipulate the contacts in such cases, use
+		<application>serctl ul</application>
+		tool. Note that this is the only correct way
+		to update contacts -- direct changes to back-end
+		MySql database do not affect server's memory. Also note,
+		that if persistence is turned off (usrloc "db_mode"
+		parameter set to "0"), all contacts are gone on server
+		reboot. Make sure that persistence is enabled if you
+		add permanent contacts.
+	    </para>
+	    <para>
+		To add a new permanent contact for a user, call 
+		<application>serctl ul add &lt;username&gt;
+		    &lt;contact&gt;</application>. To delete 
+		all user's contacts, call 
+		<application>serctl ul rm &lt;username&gt;</application>.
+		<application>serctl ul show &lt;username&gt;</application>
+		prints all current user's contacts.
+		<screen>
+[jiri@cat gen_ha1]$ serctl ul add newuser sip:[email protected]
+sip:[email protected]
+200 Added to table
+('newuser','sip:[email protected]') to 'location'
+[jiri@cat gen_ha1]$ serctl ul show newuser
+&lt;sip:[email protected]&gt;;q=1.00;expires=1073741812
+[jiri@cat gen_ha1]$ serctl ul rm newuser  
+200 user (location, newuser) deleted
+[jiri@cat gen_ha1]$ serctl ul show newuser
+404 Username newuser in table location not found
+		</screen>
+	    </para>
+	</section> <!-- user management -->
+	<section>
+	    <title>User Aliases</title>
+
+	    <para>
+		Frequently, it is desirable for a user to have multiple
+		addresses in a domain. For example, a user with username "john.doe" wants to be
+		reachable at a shorter address "john" or at a numerical address
+		"12335", so that PSTN callers with digits-only key-pad can reach
+		him too.
+	    </para>
+	    <para>
+		With <application>ser</application>, you can maintain
+		a special user-location table and translate existing aliases to canonical
+		usernames using the <command>lookup</command>
+		action from usrloc module. The following script fragment demonstrates
+		use of <command>lookup</command> for this purpose.
+		<example>
+		    <title>Configuration of Use of Aliases</title>
+		    <programlisting>
+if (!uri==myself) { # request not for our domain...
+    route(1); # go somewhere else, where outbound requests are processed
+    break;
+};
+# the request is for our domain -- process registrations first
+if (method=="REGISTER") { route(3); break; };
+
+# look now, if there is an alias in the "aliases" table; don't care
+# about return value: whether there is some or not, move ahead then
+lookup("aliases");
+
+# there may be aliases which translate to other domain and for which
+# local processing is not appropriate; check again, if after the
+# alias translation, the request is still for us
+if (!uri==myself) { route(1); break; };
+
+# continue with processing for our domain...
+...
+		    </programlisting>
+		</example>
+	    </para>
+	    <para>
+		The table with aliases is updated using the
+		<application>serctl</application>
+		tool. <application>
+		    serctl alias add &lt;alias&gt; &lt;uri&gt;</application>
+		adds a new alias, 
+		<application>serctl alias show &lt;user&gt;</application>
+		prints an existing alias, and
+		<application>serctl alias rm &lt;user&gt;</application>
+		removes it.
+		<screen>
+[jiri@cat sip_router]$ serctl alias add 1234 sip:[email protected]
+sip:[email protected]
+200 Added to table
+('1234','sip:[email protected]') to 'aliases'
+[jiri@cat sip_router]$ serctl alias add john sip:[email protected]
+sip:[email protected]
+200 Added to table
+('john','sip:[email protected]') to 'aliases'
+[jiri@cat sip_router]$ serctl alias show john                    
+&lt;sip:[email protected]&gt;;q=1.00;expires=1073741811
+[jiri@cat sip_router]$ serctl alias rm john  
+200 user (aliases, john) deleted				
+		</screen>
+	    </para>
+	    <para>
+		Note that persistence needs to be turned on in usrloc
+		module. All changes to aliases will be otherwise lost
+		on server reboot. To enable persistence, set the
+		db_mode usrloc parameter to a non-zero value.
+		<programlisting>
+# ....load module ...
+loadmodule "modules/usrloc/usrloc.so"
+# ... turn on persistence -- all changes to user tables are immediately
+# flushed to mysql
+modparam("usrloc", "db_mode",   1)
+# the SQL address:
+modparam("usrloc", "db_url","mysql://ser:secret@dbhost/ser")
+		</programlisting>
+	    </para>
+	</section> <!-- user aliases -->
+	<section id="acl">
+	    <title>Access Control (PSTN Gateway)</title>
+	    <para>
+		It is sometimes important to exercise some sort of
+		access control. A typical use case is when 
+		<application>ser</application> is used
+		to guard a PSTN gateway. If a gateway was not well guarded,
+		unauthorized users would be able to use it to terminate calls in PSTN,
+		and cause high charges to its operator.
+	    </para>
+	    <para>
+		There are few issues you need to understand when
+		configuring <application>ser</application>
+		for this purpose. First, if a gateway is built or configured to
+		accept calls from anywhere, callers may easily bypass your
+		access control server and communicate with the gateway
+		directly. You then need to enforce at transport layer
+		that signaling is only accepted if coming via
+		<application>ser</application> and
+		deny SIP packets coming from other hosts and port numbers.
+		Your network must be configured not to allow forged
+		IP addresses. Also, you need to turn on record-routing
+		to assure that all session requests will travel via 
+		<application>ser</application>.			    
+		Otherwise, caller's devices would send subsequent SIP requests 
+		directly to your gateway, which would fail because of transport 
+		filtering.
+	    </para>
+	    <para>
+		Authorization (i.e., the process of determining who may call where)
+		is facilitated in <application>ser</application>
+		using <emphasis>group membership</emphasis> concept. Scripts make 
+		decisions on whether a caller is authorized to make a call to
+		a specific destination based on user's membership in a group.
+		For example a policy may be set up to allow calls to international
+		destinations only to users, who are members of an "int" group.			    
+		Before user's group membership is checked, his identity
+		must be verified first. Without cryptographic verification of user's
+		identity, it would be impossible to assert that a caller really
+		is who he claims to be.
+	    </para>
+	    <para>
+		The following script demonstrates, how to configure <application>ser</application>
+		as an access control server for a PSTN gateway. The script verifies user
+		identity using digest authentication, checks user's privileges,
+		and forces all requests to visit the server.
+		<example>
+		    <title>Script for Gateway Access Control</title>
+		    <programlisting>
+<xi:include href="../../examples/pstn.cfg" parse="text"/>
+		    </programlisting>
+		</example>
+	    </para>
+	    <para>
+		Use the <application>serctl</application> tool to
+		maintain group membership. 
+		<application>serctl acl grant &lt;username&gt; &lt;group&gt;</application>
+		makes a user member of a group, 
+		<application>serctl acl show &lt;username&gt;</application> shows groups
+		of which a user is member, and
+		<application>serctl acl revoke &lt;username&gt; [&lt;group&gt;]</application>
+		revokes user's membership in one or all groups.
+		<screen>
+[jiri@cat sip_router]$ serctl acl grant john int
+MySql Password: 
++------+-----+---------------------+
+| user | grp | last_modified       |
++------+-----+---------------------+
+| john | int | 2002-12-08 02:09:20 |
++------+-----+---------------------+
+		</screen>
+	    </para>
+	</section> <!-- access control -->
+	<section>
+	    <title>Accounting</title>
+	    <para>
+		In some scenarios, like termination of calls in PSTN, SIP administrators
+		may wish to keep track of placed calls. <application>ser</application>
+		can be configured to report on completed transactions. Reports are sent
+		by default to <application>syslog</application> facility.
+		Support for RADIUS and mysql accounting exists as well.
+	    </para>
+	    <para>
+		Note that <application>ser</application> is no way 
+		call-stateful. It reports on completed transactions, i.e., after 
+		a successful call set up is reported, it drops any call-related 
+		state. When a call is terminated, transactional state for BYE request
+		is created and forgotten again after the transaction completes.
+		This is a feature and not a bug -- keeping only transactional
+		state allows for significantly higher scalability. It is then
+		up to the accounting application to correlate call initiation
+		and termination events.
+	    </para>
+	    <para>
+		To enable call accounting, tm and acc modules need to be loaded,
+		requests need to be processed statefully and labeled for
+		accounting. That means, if you want a transaction to be reported,
+		the initial request must have taken the path 
+		"<command>setflag(X)</command>, <command>t_relay</command>"
+		in <application>ser</application> script. X must have the
+		value configured in <varname>acc_flag</varname>
+		configuration option.
+	    </para>
+	    <para>
+		Also note, that by default only transactions that initiate
+		a SIP dialog (typically INVITE) visit a proxy server.
+		Subsequent transactions are exchanged directly between
+		end-devices, do not visit proxy server and cannot be
+		reported. To be able to report on subsequent transactions,
+		you need to force them visit proxy server by turning 
+		record-routing on. 
+	    </para>
+	    <para>
+		<example>
+		    <title>Configuration with Enabled Accounting</title>
+		    <programlisting>
+<xi:include href="../../examples/acc.cfg" parse="text"/>
+		    </programlisting>
+		</example>
+	    </para>
+	</section> <!-- accounting -->
+	<section>
+	    <title>Reliability</title>
+
+	    <para>
+		It is essential to guarantee continuous
+		service operation even under erroneous conditions, 
+		such as host or network failure. The major issue in such
+		situations is transfer of operation to a backup
+		infrastructure and making clients use it.
+	    </para>
+	    <para>
+		The SIP standard's use of DNS SRV records has been
+		explicitly constructed to handle with server failures.
+		There may be multiple servers responsible for a domain
+		and referred to by DNS. If it is impossible to communicate
+		with a primary server, a client can proceed to another one.
+		Backup servers may be located in a different geographic
+		area to minimize risk caused by areal operational
+		disasters: lack of power, flooding, earthquake, etc.
+		<note>
+		    <sidebar>
+			<para>Unless there are redundant DNS
+			    servers, fail-over capability cannot be guaranteed.
+			</para>
+		    </sidebar>
+		</note>
+		Unfortunately, at the moment of writing this documentation
+		(end of December 2002) only very few SIP products
+		actually implement the DNS fail-over mechanism. Unless
+		networks with SIP devices supporting this mechanism are
+		built, alternative mechanisms must be used to force 
+		clients to use backup servers. Such a mechanism is
+		disconnecting primary server and replacing it with
+		a backup server locally.
+		It unfortunately precludes geographic dispersion and
+		requires network multihoming to avoid dependency on
+		single IP access. Another method is to update DNS
+		when failure of the primary server is detected.
+		The primary drawback of this method is its latency:
+		it may take long time until all clients learn to use
+		the new server.
+	    </para>
+	    <para>
+		The easier part of the redundancy story is replication of 
+		<application>ser</application>
+		data. <application>ser</application>
+		relies on replication capabilities of its back-end database.
+		This works with one exception: user location database.
+		User location database is a frequently accessed table,
+		which is thus cached in server's memory to improve
+		performance. Back-end replication does not affect
+		in-memory tables, unless server reboots. To facilitate
+		replication of user location database, 
+		server's SIP replication feature must be enabled
+		in parallel with back-end replication.
+	    </para>
+	    <para>
+		The design idea of replication of user location database
+		is easy: Replicate any successful REGISTER requests to
+		a peer server. To assure that digest credentials can
+		be properly verified, both servers need to use the same
+		digest generation secret and maintain synchronized time.
+		A known limitation of this method is it does not replicate
+		user contacts entered in another way, for example using
+		web interface through FIFO server.
+		The following script example shows configuration of
+		a server that replicates all REGISTERs.
+		<example>
+		    <title>Script for Replication of User Contacts</title>
+		    <programlisting>
+<xi:include href="../../examples/replicate.cfg" parse="text"/>
+		    </programlisting>
+		</example>
+	    </para>
+	</section> <!-- reliability -->
+	<section>
+	    <title>Stateful versus Stateless Forwarding</title>
+	    <para>
+		<application>ser</application> allows both stateless
+		and stateful request processing. This memo explains what are pros and cons of
+		using each method. The rule of thumb is "stateless for scalability,
+		stateful for services". If you are unsure which you need, stateful
+		is a safer choice which supports more usage scenarios.
+	    </para>
+	    <para>
+		Stateless forwarding with the
+		<command>forward(uri:host, uri:port)</command> action
+		guarantees high scalability. It withstands high load and
+		does not run out of memory. A perfect use of stateless forwarding
+		is load distribution.
+	    </para>
+	    <para>
+		Stateful forwarding using the <command>t_relay()</command>
+		action is known to scale worse. It can quickly run out of memory and
+		consumes more CPU time. Nevertheless, there are scenarios which are
+		not implementable without stateful processing. In particular:
+		<itemizedlist>
+		    <listitem>
+			<para>
+			    <emphasis>Accounting</emphasis> requires stateful processing
+			    to be able to collect transaction status and issue a single
+			    report when a transaction completes.
+			</para>
+		    </listitem>
+		    <listitem>
+			<para>
+			    <emphasis>Forking</emphasis> only works with stateful forwarding.
+			    Stateless forwarding only forwards to the default URI out of the
+			    whole destination set.
+			</para>
+		    </listitem>
+		    <listitem>
+			<para>
+			    <emphasis>DNS resolution</emphasis>. DNS resolution may be
+			    better served with stateful processing. If a request is forwarded
+			    to a destination whose address takes long time to resolve,
+			    a server process is blocked and unresponsive. Subsequent 
+			    request retransmissions from client will cause other processes
+			    to block too if requests are processed statelessly. As a result,
+			    <application>ser</application> will quickly
+			    run out of available processes. With stateful forwarding,
+			    retransmissions are absorbed and do not cause blocking of
+			    another process.
+			</para>
+		    </listitem>
+		    <listitem>
+			<para>
+			    <emphasis>Forwarding Services</emphasis>. All sort of services 
+			    with the "forward_on_event" logic, which rely on 
+			    <command>t_on_failure</command> tm
+			    action must be processed statefully.
+			</para>
+		    </listitem>
+		    <listitem>
+			<para>
+			    <emphasis>
+				Fail-over.
+			    </emphasis>
+			    If you wish to try out another destination, after a primary destination
+			    failed you need to use stateful processing. With stateless processing
+			    you never know with what status a forwarded request completed downstream
+			    because you immediately release all processing information after the 
+			    request is sent out. 
+
+			    <note>
+				<para>
+				    Positive return value of stateless
+				    <command>forward</command> action only indicates that
+				    a request was successfully sent out, and does not gain any knowledge
+				    about whether it was successfully received or replied. Neither does
+				    the return value of
+				    the stateful <command>t_relay</command> action family
+				    gain you this knowledge. However, these actions store transactional
+				    context with which includes original request and allows you to
+				    take an action when a negative reply comes back or a timer strikes.
+				    See <xref linkend="replyprocessingsection"/> for an example script 
+					which launches another
+					branch if the first try fails.
+				</para>
+			    </note>
+
+			</para>
+		    </listitem>
+		</itemizedlist>
+	    </para>
+	</section> <!-- stateful vs. stateless -->
+	<section>
+	    <title>Serving Multiple Domains</title>
+	    <para>
+		<application>ser</application> can be configured to
+		serve multiple domains. To do so, you need to take the following steps:
+		<orderedlist>
+		    <listitem id="createtable">
+			<para>
+			    Create separate subscriber and location database table
+			    for each domain served and name them uniquely.
+			</para>
+		    </listitem>
+		    <listitem>
+			<para>
+			    Configure your script to distinguish between multiple
+			    served domains. Use regular expressions for domain
+			    matching as described in <xref linkend="redomainmatching"/>.
+			</para>
+		    </listitem>
+		    <listitem>
+			<para>
+			    Update table names in usrloc and auth actions to reflect
+			    names you created in <xref linkend="createtable"/>.
+			</para>
+		    </listitem>
+		    
+		</orderedlist>
+	    </para>
+	    <para>
+		The latest <application>SER</application> release includes automated
+		multidomain management which greatly automates maintenance of multiple	
+		domains. Ask our technical support for more help.
+	    </para>
+	</section> <!-- multiple domains -->
+	<section id="missedcalls">
+	    <title>Reporting Missed Calls</title>
+	    <para>
+		<application>ser</application> can report missed
+		calls via <application>syslog</application> facility
+		or to mysql. Mysql reporting can be utilized by 
+		<application>ser</application>'s 
+		complementary web-interface, <application>serweb</application>.
+		(See more in <xref linkend="serweb"/>).
+	    </para>
+	    <para>
+		Reporting on missed calls is enabled by acc module.
+		There are two cases, on which you want to report. The first
+		case is when a callee is off-line. The other case is when
+		a user is on-line, but call establishment fails. There
+		may be many failure reasons (call cancellation, inactive phone,
+		busy phone, server timer, etc.), all of them leading to
+		a negative (>=300) reply sent to caller. The acc module
+		can be configured to issue a missed-call report whenever
+		a transaction completes with a negative status. Two following
+		script fragment deals with both cases.
+	    </para>
+	    <para>
+		First, it reports
+		on calls missed due to off-line callee status
+		using the <command>acc_request</command>
+		action. The action is wrapped in transactional
+		processing (<command>t_newtran</command>)
+		to guarantee that reports are not
+		duplicated on receipt of retransmissions.
+	    </para>
+	    <para>
+		Secondly, transactions to on-line users are marked
+		to be reported on failure. That is what the 
+		<command>setflag(3)</command> action
+		is responsible for, along with the configuration option
+		"log_missed_flag". This option configures <application>ser</application>
+		to report on all transactions, which were marked
+		with flag 3.			   
+		<programlisting>
+loadmodule("modules/tm/tm.so");
+loadmodule("modules/acc/acc.so");
+....
+# if a call is labeled using setflag(3) and is missed, it will
+# be reported
+...
+modparam("acc", "log_missed_flag", 3 );
+if (!lookup("location")) {
+    # call invitations to off-line users are reported using the
+    # acc_request action; to avoid duplicate reports on request
+    # retransmissions, request is processed statefully (t_newtran,
+    # t_reply)
+    if ((method=="INVITE" || method=="ACK") &amp;&amp; t_newtran() ) {
+         t_reply("404", "Not Found");
+         acc_request("404 Not Found");
+         break;
+    };
+    # all other requests to off-line users are simply replied
+    # statelessly and no reports are issued
+    sl_send_reply("404", "Not Found");
+    break;
+} else {
+    # user on-line; report on failed transactions; mark the
+    # transaction for reporting using the same number as 
+    # configured above; if the call is really missed, a report
+    # will be issued
+    setflag(3);
+    # forward to user's current destination
+    t_relay();
+    break;
+};
+		</programlisting>
+		
+	    </para>
+	</section> <!-- missed calls -->
+	<section>
+	    <title>NAT Traversal</title>
+	    <para>
+		NATs are worst things that ever happened to SIP. These devices
+		are very popular because they help to conserve IP address space
+		and save money charged for IP addresses. Unfortunately, they
+		translate addresses in a way which is not compatible with SIP.
+		SIP advertises receiver addresses in its payload. The advertised
+		addresses are invalid out of NATed networks. As a result,
+		SIP communication does not work across NATs without extra
+		effort.
+	    </para>
+	    <para>
+		There are few methods that may be deployed to traverse NATs.
+		How proper their use is depends on the deployment scenario.
+		Unfortunately, all the methods have some limitations and
+		there is no straight-forward solution addressing all
+		scenarios. Note that none of these methods takes explicit
+		support in <application>ser</application>.
+	    </para>
+	    <para>
+		The first issue is whether SIP users are in control of 
+		their NATs. If not (NATs are either operated by ISP or
+		they are sealed to prevent users setting them up), the
+		only method is use of a STUN-enabled phone. STUN is 
+		a very simple protocol used to fool NAT in such a way,
+		they permit SIP sessions. Currently, we are aware of
+		one softphone (kphone) and one hardphone (snom) with
+		STUN support, other vendors are working on STUN support
+		too. Unfortunately, STUN gives no NAT traversal
+		guarantee -- there are types of NATs, so called
+		symmetric NATs, over which STUN fails to work.
+		<note>
+		    <para>
+			There is actually yet another method to address
+			SIP-unaware, user-uncontrolled NATs. It is based
+			on a proxy server, which relays all signaling and
+			media and mangles packets to make them more
+			NAT-friendly. The very serious problem with this
+			method is it does not scale.
+		    </para>
+		</note>
+	    </para>
+	    <para>
+		If users are in control of their own NAT, as typically residential
+		users are, they can still use STUN. However, they may use other
+		alternatives too. One of them is to replace their NAT with
+		a SIP-aware NAT. Such NATs have built-in SIP awareness,
+		that patches problems caused by address translations. Prices
+		of such devices are getting low and there are available
+		implementations (Intertex, Cisco/PIX). No special support
+		in phones is needed.
+	    </para>
+	    <para>
+		Other emerging option is UPnP. UPnP is a protocol that allows
+		phones to negotiate with NAT boxes. You need UPnP support in
+		both, NAT and phones. As UPnP NATs are quite affordable,
+		costs are not an obstacle. Currently, we are aware of one
+		SIP phone (SNOM) with UPnP support.
+	    </para>
+	    <para>
+		Geeks not wishing to upgrade their firewall to a SIP-aware or
+		UPnP-enabled one may try to configure static address translation.
+		That takes phones with configuration ability to use fixed port
+		numbers and advertise outside address in signaling. Cisco phones
+		have this capability, for example. The NAT devices need to
+		be configured to translate outside port ranges to the 
+		ranges configured in phones.		    
+	    </para>
+	</section> <!-- NAT traversal -->
+
+	<section>
+	    <title>Using Only Latest User's Contact for Forwarding
+	    </title>
+	    <para>
+		In some scenarios, it may be beneficial only to use only one
+		registered contact per user. If that is the case, setting
+		registrar module's parameter <varname>append_branches</varname>
+		to 1 will eliminate forking and forward all requests only
+		to a single contact. If there are multiple contacts, a contact
+		with highest priority is chosen. This can be changed to
+		the "freshest" contact by setting module parameter's
+		<varname>desc_time_order</varname> to 1.
+	    </para>
+
+	</section>
+
+	<section>
+	    <title>Authentication Policy: Prevention of Unauthorized Domain 
+		Name Use in From and More</title>
+	    <para>
+		Malicious users can claim a name of domain, to which they do 
+		not administratively belong, in From header field. This
+		behavior cannot be generally prevented. The reason is
+		that requests with such a faked header field do not need
+		to visit servers of the domain in question. However, if they
+		do so, it is desirable to assure that users claiming
+		membership in a domain are actually associated with it.
+		Otherwise the faked requests would be relayed and appear
+		as coming from the domain, which would increase
+		credibility of the faked address and decrease credibility of
+		the proxy server.
+	    </para>
+	    <para>
+		Preventing unauthorized domain name use in relayed requests 
+		is not difficult.
+		One needs to authenticate each request with name of the
+		served domain in From header field. To do so, one can
+		search for such a header field using <command>search</command>
+		action (textops module) and force authentication if the
+		search succeeds.
+		<note>
+		    <para>
+			A straight-forward solution might be to authenticate
+			ALL requests. However, that only works in closed
+			networks in which all users have an account in the
+			server domain. In open networks, it is desirable to permit
+			incoming calls from callers from other domains without
+			any authentication. For example, a company may wish
+			to accept calls from unknown callers who are
+			new prospective customers.
+			
+		    </para>
+		</note>
+		<programlisting>
+# does the user claim our domain "foo.bar" in From?
+if (search("^(f|From):.*foo.bar")) {
+    # if so, verify credential
+    if (!proxy_authorize("foo.bar", "subscriber")) { 
+         # don't proceed if credentials broken; challenge
+         proxy_challenge("foo.bar", "0");
+         break;
+    };
+};
+		</programlisting>
+	    </para>
+	    <para>
+		In general, the authentication policy may be very rich. You may not
+		forget each request deserves its own security and you need to 
+		decide whether it shall be authenticated or not. As mentioned
+		above, in closed networks, you may want to authenticate absolutely 
+		every request. That however prohibits traffic from users from
+		other domains. A pseudo-example of a reasonable policy is attached:
+		it looks whether a request is registration, it claims to originate
+		from our domain in From header field, or is a local request to
+		another domain.
+		<programlisting>
+# (example provided by Michael Graff on [serusers] mailing list
+if (to me):
+    if register
+     www_authorize or fail if not a valid register
+     done
+   if claiming to be "From" one of the domains I accept registrations for
+   proxy_authorize
+   done
+   if not to me (I'm relaying for a local phone to an external address)
+    proxy_authorize
+   done
+		</programlisting>
+	    </para>
+	    <para>
+		You also may want to apply additional restriction to how
+		digest username relates to usernames claimed in From and
+		To header fields. For example, the <command>check_to</command>
+		action enforces the digest id to be equal to username
+		in To header fields. That is good in preventing someone
+		with valid credentials to register as someone else
+		(e.g., sending a REGISTER with valid credentials of
+		"joe" and To belonging to "alice"). Similarly,
+		<command>check_from</command> is used
+		to enforce username in  from to equal to digest id.
+		<note>
+		    <para>
+			There may be a need for a more complex relationship
+			between From/To username and digest id. For example,
+			providers with an established user/password database
+			may wish to keep using it, whereas permitting users
+			to claim some telephone numbers in From. To address
+			such needs generally, there needs to be a 1:N mapping
+			between digest id and all usernames that are acceptable
+			for it. This is being addressed in a newly contributed
+			module "domain", which also addresses more generally
+			issues of domain matching for multidomain scenarios.
+		    </para>
+		</note>
+	    </para>
+	    <para>
+		Other operational aspect affecting the authentication policy
+		is guarding PSTN gateways (see <xref linkend="acl"/>). There
+		    may be destinations that are given away for free whereas
+		    other destinations may require access control using
+		    group membership, to which  authentication is a prerequisite.
+	    </para>
+
+	</section> <!-- authentication policy, faked froms -->
+	<section>
+	    <title>Connecting to PBX Voicemail Using a Cisco Gateway</title>
+	    <para>
+		In some networks, administrators may wish to utilize their
+		PBX voicemail systems behind PSTN gateways. There is a practical problem
+		in many network settings: it is not clear for whom a call to
+		voicemail is. If voicemail is identified by a single number,
+		which is then put in INVITE's URI, there is no easy way to
+		learn for whom a message should be recorded. PBX voicemails
+		utilize that PSTN protocols signal the number of originally
+		called party. If you wish to make the PBX voicemail work,
+		you need to convey the number in SIP and translate it in
+		PSTN gateways to its PSTN counterpart.
+	    </para>
+	    <para>
+		There may be many different ways to achieve this scenario. Here
+		we describe the proprietary mechanism Cisco gateways use and how to 
+		configure <application>ser</application> to
+		make the gateways happy. Cisco gateways expect the number
+		of originally called party to be located in proprietary
+		<varname>CC-Diversion</varname> header field. When a SIP 
+		INVITE sent via a PSTN gateway to PBX voicemail has number
+		of originally called party in the header field, the voicemail
+		system knows for whom the incoming message is. That is at least
+		true for AS5300/2600 with Cisco IOS 12.2.(2)XB connected to
+		Nortel pbxs via PRI. (On the other hand, 12.2.(7b) is known
+		not to work in this scenario.)
+	    </para>
+	    <para>
+		<application>ser</application> needs then to
+		be configured to append the <varname>CC-Diversion</varname>
+		header field name for INVITEs sent to PBX voicemail.
+		The following script shows that: when initial forwarding
+		fails (nobody replies, busy is received, etc.), a new branch
+		is initiated to the pbx's phone number. 
+		<command>append_urihf</command> is used to
+		append the <varname>CC-Diversion</varname> header field. It
+		takes two parameters: prefix, which includes header name,
+		and suffix which takes header field separator. 
+		<command>append_urihf</command> inserts
+		original URI between those two.
+		<example>
+		    <title>Forwarding to PBX/Voicemail via Cisco Gateways</title>
+		    <programlisting>
+<xi:include href="../../examples/ccdiversion.cfg" parse="text"/>
+		    </programlisting>
+		</example>
+		
+	    </para>
+	</section>
+    </section> <!-- howtos -->
+
+    <section>
+	<title>Troubleshooting</title>
+	<para>
+	    This section gathers practices how to deal with errors
+	    known to occur frequently. To understand how to watch
+	    SIP messages, server logs, and in general how to
+	    troubleshoot, read also <xref linkend="operationalpractices"/>. 
+	</para>
+	<qandaset>
+	    <qandaentry>
+		<question>
+		    <para>
+			SIP requests are replied by <application>ser</application> with
+			"483 Too Many Hops" or "513 Message Too Large"
+		    </para>
+		</question>
+
+		<answer>
+		    <para>
+			In both cases, the reason is probably an error in
+			request routing script which caused an infinite loop.
+			You can easily verify whether this happens by
+			watching SIP traffic on loopback interface. A typical
+			reason for misrouting is a failure to match local
+			domain correctly. If a server fails to recognize
+			a request for itself, it will try to forward it
+			to current URI in believe it would forward them
+			to a foreign domain. Alas, it forwards the request
+			to itself again. This continues to happen until
+			value of max_forwards header field reaches zero
+			or the request grows too big. Solutions is easy:
+			make sure that domain matching is correctly
+			configured. See <xref linkend="domainmatching"/>
+			    for more information how to get it right.
+		    </para>
+		</answer>		    
+	    </qandaentry>
+	    <qandaentry id="msmbug">
+		
+		<question>
+		    
+		    <para>
+			
+			Windows Messenger authentication fails.
+		    </para>
+		</question>
+		<answer>
+			<para>
+			    The most likely reason for this problem is a bug
+			    in Windows Messenger. WM only authenticates if
+			    server name in request URI equals authentication
+			    realm. After a challenge is sent by SIP server,
+			    WM does not resubmit the challenged request at all
+			    and pops up authentication window again.
+			    If you want to authenticate WM, you need to
+			    set up your realm value to equal server name.
+			    If your server has no name, IP address can be used
+			    as realm too. The realm value is configured in
+			    scripts as the first parameter of all
+			    <command>{www|proxy}_{authorize|challenge}</command>
+			    actions.
+			</para>
+		</answer>
+	    </qandaentry>
+	    <qandaentry id="mhomed">
+		<question>
+		    <para>
+			On a multihomed host, forwarded messages carry other 
+			interface in Via than used for sending, or messages 
+			are not sent and an error log is issued "invalid 
+			sendtoparameters one possible reason is the server 
+			is bound to localhost".
+		    </para>
+		</question>
+		<answer>
+			<para>
+			    Set the configuration option <varname>mhomed</varname>
+			    to "1". <application>ser</application>
+			    will then attempt to calculate the correct interface.
+			    It's not done by default as it degrades performance
+			    on single-homed hosts or multi-homed hosts that are
+			    not set-up as routers.
+			</para>
+		</answer>
+	    </qandaentry>
+	    <qandaentry>
+		<question>
+		    <para>
+			I receive "ERROR: t_newtran: transaction already in process" in my logs.
+		    </para>
+		</question>
+		<answer>
+		    <para>
+			That looks like an erroneous use of tm module in script.
+			tm can handle only one transaction per request. If you
+			attempt to instantiate a transaction multiple times,
+			<application>ser</application> will complain.
+			Anytime any of <command>t_newtran</command>,
+			<command>t_relay</command> or 
+			<command>t_relay_to_udp</command> actions is
+			encountered, tm attempts to instantiate a transaction.
+			Doing so twice fails. Make sure that any of this
+			commands is called only once during script execution.
+		    </para>
+		</answer>
+	    </qandaentry>
+	    <qandaentry>
+		<question>
+		    <para>
+			I try to add an alias but 
+			<command>serctl</command>
+			complains that table does not exist.
+		    </para>
+		</question>
+		<answer>
+		    <para>
+			You need to run <application>ser</application>
+			and use the command
+			<command>lookup("aliases")</command>
+			in its routing script. That's because the table 
+			of aliases is
+			stored in cache memory for high speed. The cache
+			memory is only set up when the 
+			<application>ser</application>
+			is running and configured to use it. If that is
+			not the case, 
+			<application>serctl</application>
+			is not able to manipulate the aliases table.
+		    </para>
+		</answer>
+	    </qandaentry>
+
+	    <qandaentry>
+		<question>
+		    <para>I started <application>ser</application> with
+			<varname>children=4</varname> but many more processes
+			were started. What is wrong?
+		    </para>
+		</question>
+		<answer>
+		    <para>
+			That's ok. The <varname>children</varname> parameter defines
+			how many children should process each transport protocol in
+			parallel. Typically, the server listens to multiple protocols
+			and starts other supporting processes like timer or FIFO
+			server too. Call <application>serctl ps</application> to watch
+			running processes.
+		    </para>
+		</answer>
+	    </qandaentry>
+	    <qandaentry>
+		<question>
+		    <para>
+			I decided to use a compiled version of <application>ser</application>
+			but it does not start any more.
+		    </para>
+		</question>
+		<answer>
+		    <para>
+			You probably kept the same configuration file, which tries to load modules
+			from the binary distribution you used previously. Make sure that modules
+			paths are valid and point to where you compiled <application>ser</application>.
+			Also, watch logs for error messages "ERROR: load_module: could not open 
+			module".
+		    </para>
+		</answer>
+	    </qandaentry>
+	    
+	</qandaset>
+    </section> <!-- troubleshooting -->
+</section>

doc/seruser/otherapps.sgml → doc/seruser/otherapps.xml

@@ -1,18 +1,29 @@
-    <chapter id="complementaryapps">
-	<title>Complementary Applications</title>
-	<section id="serctl">
-	    <title><application>serctl</application> command-line tool</title>
-	    <para>
-		<application>serctl</application> is a command-line utility which allows to
-		perform most of management tasks needed to operate
-		<application moreinfo="none">ser</application>: adding users, changing their passwords,
-		watching server status, etc. Usage of utility is
-		as follows:
-
-		<example>
-		    <title><application>serctl</application> usage</title>
-		    <programlisting format="linespecific">
-
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4//EN"
+                      "file:///usr/share/sgml/docbook/dtd/xml/4/docbookx.dtd">
+
+<section id="otherapps" xmlns:xi="http://www.w3.org/2001/XInclude">
+    <sectioninfo>
+	<revhistory>
+	    <revision>
+		<revnumber>$Revision$</revnumber>
+		<date>$Date$</date>
+	    </revision>
+	</revhistory>
+    </sectioninfo>
+    
+    <title>Complementary Applications</title>
+    <section id="serctl">
+	<title><application>serctl</application> command-line tool</title>
+	<para>
+	    <application>serctl</application> is a command-line utility which allows to
+	    perform most of management tasks needed to operate
+	    <application>ser</application>: adding users, changing their passwords,
+	    watching server status, etc. Usage of utility is
+	    as follows:
+	    <example>
+		<title><application>serctl</application> usage</title>
+		<programlisting>
 usage: 
            * subscribers *
  serctl add &lt;username&gt; &lt;password&gt; &lt;email&gt; .. add a new subscriber (*)
@@ -41,13 +52,12 @@ usage:
 
    Commands labeled with (*) will prompt for a MySQL password.
    If the variable PW is set, the password will not be prompted.
-
- </programlisting>
-		</example>
-	    </para>
-	    <note>
-		<para>
-
+		</programlisting>
+	    </example>
+	</para>
+	<note>
+	    <para>
+		
 		Prior to using the utility, you have to first 
 		set the environment variable <constant>SIP_DOMAIN</constant>
 		to locally appropriate value (e.g., "foo.com"). It is
@@ -59,10 +69,9 @@ usage:
 
 	    <example>
 		<title>Example Output of Server Watching Command 
-		    <command moreinfo="none">sc monitor</command>
+		    <command>sc monitor</command>
 		</title>
-		<programlisting format="linespecific">
-
+		<programlisting>
 [cycle #: 2; if constant make sure server lives and fifo is on]
 Server: Sip EXpress router(0.8.8 (i386/linux))
 Now: Thu Sep 26 23:16:48 2002
@@ -86,7 +95,6 @@ UsrLoc Stats
 Domain Registered Expired
 'aliases' 9 0
 'location' 29 17
-
 		</programlisting>
 
 	    </example>
@@ -96,11 +104,11 @@ Domain Registered Expired
 	    <title>Web User Provisioning -- <application>serweb</application></title>
 	    <para>
 		To make provisioning of user accounts convenient, 
-		a web front-end to <application moreinfo="none">ser</application>,
-		<application moreinfo="none">serweb</application> has been
-		developed. <application moreinfo="none">serweb</application>,
+		a web front-end to <application>ser</application>,
+		<application>serweb</application> has been
+		developed. <application>serweb</application>,
 		a PHP-written web application,
-		allows users to apply for new <application moreinfo="none">ser</application>
+		allows users to apply for new <application>ser</application>
 		accounts, and maintain these.
 		Users can manipulate their contacts, keep a phone-book
 		with SIP addresses, change password, send instant SIP messages,
@@ -108,26 +116,19 @@ Domain Registered Expired
 		grant or revoke user privileges.
 	    </para>
 	    <para>
-		<application moreinfo="none">serweb</application> is freely
+		<application>serweb</application> is freely
 		available from berlios site at
 		<ulink url="http://developer.berlios.de/cvs/?group_id=500">
 		http://developer.berlios.de/cvs/?group_id=500</ulink>. Installation
 		takes unpacking tarball to a safe destination at web server
 		(better not in the HTML tree) and configuring 
-		<filename moreinfo="none">config.php</filename> accordingly
+		<filename>config.php</filename> accordingly
 		to local conditions.
 	    </para>
 	    <para>
-		Running <application moreinfo="none">serweb</application> can
+		Running <application>serweb</application> can
 		be seen at iptel.org's SIP site. Just create and use a SIP
 		account at <ulink url="http://www.iptel.org/user/">http://www.iptel.org/user/</ulink>
 	    </para>
-	</section> <!-- serweb -->
-
-
-    <section>
-	<title>Voicemail</title>
-&voicemail;
-    </section> <!-- voicemail -->
-
-    </chapter> <!-- other apps -->
+    </section> <!-- serweb -->
+</section>

doc/seruser/reference.sgml → doc/seruser/reference.xml

@@ -1,5 +1,19 @@
-    <chapter>
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4//EN"
+                      "file:///usr/share/sgml/docbook/dtd/xml/4/docbookx.dtd">
+
+<section id="reference" xmlns:xi="http://www.w3.org/2001/XInclude">
+    <sectioninfo>
+	<revhistory>
+	    <revision>
+		<revnumber>$Revision$</revnumber>
+		<date>$Date$</date>
+	    </revision>
+	</revhistory>
+    </sectioninfo>
+
 	<title>Reference</title>
+
 	<section id="coreoptions">
 	    <title>Core Options</title>
 	    <para>Core options are located in beginning of configuration file and
@@ -24,7 +38,7 @@
 				there is no attendant process, no pid file is generated,
 				and server listens only at one address. Make sure you
 				are debugging the same interface at which 
-				<application moreinfo="none">ser</application> listens.
+				<application>ser</application> listens.
 				The easiest way to do so is to set the interface using
 				<varname>listen</varname> option explicitly.
 				</para>
@@ -34,7 +48,7 @@
 		<listitem>
 		    <para>
 			<varname>log_stderror</varname> - If set to yes, the server will print its debugging 
-			information to standard error output. If set to no, <command moreinfo="none">syslog</command> 
+			information to standard error output. If set to no, <command>syslog</command> 
 			will be used. Default is no (printing to syslog).
 		    </para>
 		</listitem>
@@ -50,7 +64,7 @@
 					<command>
 						ser -l foo  -l bar -p 5061 -l x -l y 
 					</command>
-					will listen on foo:5060, bar:5061 & x:5061 & y:5061
+					will listen on foo:5060, bar:5061 &amp; x:5061 &amp; y:5061
 
 				</para>
 			</note>
@@ -95,7 +109,7 @@
 			server multiple requests in parallel when request processing block (e.g., on DNS
 			lookup). Note that <application>ser</application> typically spawns additional
 			processes, such as timer process or FIFO server. If FIFO server is turned on,
-			you can watch running processes using the <application moreinfo="none">serctl</application>
+			you can watch running processes using the <application>serctl</application>
 			utility.
 
 
@@ -129,9 +143,9 @@
 		    <para>
 			<varname>fifo</varname> - FIFO special file pathname, for example "/tmp/ser_fifo". Default is
 			no filename -- no FIFO server is started then. We recommend to set it so that
-			accompanying applications such as <application moreinfo="none">serweb</application> or
-			<application moreinfo="none">serctl</application> can communicate with
-			<application moreinfo="none">ser</application>.
+			accompanying applications such as <application>serweb</application> or
+			<application>serctl</application> can communicate with
+			<application>ser</application>.
 		    </para>
 		</listitem>
 		<listitem>
@@ -168,7 +182,7 @@
 		    <para>
 			<varname>mhomed</varname> -- enable calculation of 
 			outbound interface; useful on multihomed servers,
-			ser <link linkend="mhomed"></link>.
+			see <xref linkend="mhomed"/>.
 		    </para>
 		</listitem>
 		<listitem>
@@ -226,7 +240,7 @@
 		    </para>
 		    <example>
 			<title>route</title>
-			<programlisting format="linespecific">
+			<programlisting>
 route[0] {
         # call routing block number 2
 	route(2);
@@ -246,20 +260,20 @@ route[2] {
 			can return to their processing later. To activate processing
 			of a <command>failure_route</command> block, call the TM action
 			<command>t_on_failure(route_number)</command> before calling
-			<command moreinfo="none">t_relay</command>. When a negative reply
-			comes back, the desired <command moreinfo="none">failure_route</command>
+			<command>t_relay</command>. When a negative reply
+			comes back, the desired <command>failure_route</command>
 			will be entered and processing of the original request may
 			continue. 
 			</para>
 		    <para>
 			The set of actions applicable from within
-			<command moreinfo="none">failure_route</command> blocks is limited.
+			<command>failure_route</command> blocks is limited.
 			Permitted actions are URI-manipulation actions, logging and
-			sending stateful replies using <command moreinfo="none">t_reply</command>.
+			sending stateful replies using <command>t_reply</command>.
 		    </para>
 		    <example>
 			<title>failure_route</title>
-			<programlisting format="linespecific">
+			<programlisting>
 failure_route[1] {
     # for some reason, the original forwarding attempt
     # failed, try at another URI
@@ -279,7 +293,7 @@ failure_route[1] {
 			route block otherwise.
 			<note>
 			    <para>
-				We recommend to use <command moreinfo="none">break</command>
+				We recommend to use <command>break</command>
 				after any request forwarding or replying. This practice
 				helps to avoid erroneous scripts that 
 				continue execution and mistakenly send another reply or
@@ -307,7 +321,7 @@ failure_route[1] {
 		    </para>
 		    <example>
 			<title>Use of <command>if</command></title>
-			<programlisting format="linespecific">
+			<programlisting>
 if (method=="REGISTER) {
     log("register received\n");
 };
@@ -320,7 +334,7 @@ if (method=="REGISTER) {
 		    </para>
 		    <example>
 			<title>Use of <command>if-else</command></title>
-			<programlisting format="linespecific">
+			<programlisting>
 if (method=="REGISTER) {
     log("register received\n");
 } else {
@@ -355,7 +369,7 @@ if (method=="REGISTER) {
 		    </para>
 		    <example>
 			<title>isflagset</title>
-			<programlisting format="linespecific">
+			<programlisting>
 if (isflagset(1)) {
     ....
 };
@@ -445,7 +459,7 @@ if (isflagset(1)) {
 		    <para>
 			<example>
 			    <title>Use of <command>append_branch</command></title>
-			    <programlisting format="linespecific">
+			    <programlisting>
 # redirect to these two destinations: [email protected] and [email protected]
 # 1) rewrite the current URI
 rewriteuri("sip:[email protected]");
@@ -496,9 +510,9 @@ sl_send_reply("300", "redirection");
 		    </para>
 		    <para>
 			Logging is very useful for troubleshooting or attracting administrator's
-			attention to unusual situations. <application moreinfo="none">ser</application>
-			reports log messages to <application moreinfo="none">syslog</application>
-			facility unless it is configured to print them to <filename moreinfo="none">stderr</filename>
+			attention to unusual situations. <application>ser</application>
+			reports log messages to <application>syslog</application>
+			facility unless it is configured to print them to <filename>stderr</filename>
 			with the <varname>log_stderr</varname> configuration option. Log messages
 			are only issued if their log level exceeds threshold set with the
 			<varname>debug</varname> configuration option. If log level is omitted,
@@ -522,7 +536,7 @@ sl_send_reply("300", "redirection");
 		    </para>
 		    <example>
 			<title>Use of <command>len_gt</command></title>
-			<programlisting format="linespecific">
+			<programlisting>
 # deny all requests larger in size than 1 kilobyte
 if (len_gt(1024)) {
     sl_send_reply("513", "Too big");
@@ -662,9 +676,9 @@ if (len_gt(1024)) {
 	    <title>Modules</title>
 	    <para>
 		Module description is currently located in READMEs of
-		respective module directories. <filename moreinfo="none">README-MODULES</filename>
+		respective module directories. <filename>README-MODULES</filename>
 		lists all available modules, including their maturity status.
-		In the current <application moreinfo="none">ser</application>
+		In the current <application>ser</application>
 		distribution, there are the following modules:
 		<itemizedlist>
 		    <listitem>
@@ -672,7 +686,7 @@ if (len_gt(1024)) {
 			    <emphasis>
 				acc
 			    </emphasis>
-			    -- call accounting using <application moreinfo="none">syslog</application> facility.
+			    -- call accounting using <application>syslog</application> facility.
 				RADIUS and mysql support can be compiled in.
 			    Depends on tm.
 			</para>
@@ -832,9 +846,9 @@ if (len_gt(1024)) {
 	    </para>
 	    <para>
 		The most frequently used actions exported by modules are summarized
-		in <xref linkend="moduleactions">. For a full explanation of 
+		in <xref linkend="moduleactions"/>. For a full explanation of 
 		module actions, see documentation in respective module directories
-		in source distribution of <application moreinfo="none">ser</application>.
+		in source distribution of <application>ser</application>.
 	    </para>
 	    <table id="moduleactions">
 		<title>Frequently Used Module Actions</title>
@@ -1186,13 +1200,13 @@ if (len_gt(1024)) {
 	    <title>FIFO Commands Reference</title>
 	    <para>
 		This section lists currently supported FIFO commands. Some of them are
-		built-in in <application moreinfo="none">ser</application> core, whereas
+		built-in in <application>ser</application> core, whereas
 		others are exported by modules. The most important exporters are now
 		tm and usrloc module. tm FIFO commands allow users to initiate transactions
 		without knowledge of underlying SIP stack. usrloc FIFO commands allow
 		users to access in-memory user-location database. Note that that is the
 		only way how to affect content of the data-base in real-time. Changes
-		to MySql database do not affect in-memory table unless <application moreinfo="none">ser</application>
+		to MySql database do not affect in-memory table unless <application>ser</application>
 		is restarted.
 	    </para>
 	    <table>
@@ -1227,13 +1241,14 @@ if (len_gt(1024)) {
 				none
 			    </entry>
 			    <entry>
-				prints running <application moreinfo="none">ser</application> processes
+				prints running <application>ser</application> processes
 			    </entry>
 			</row>
 			<row>
 			    <entry>which</entry>
 			    <entry>core</entry>
 			    <entry>none</entry>
+
 			    <entry>prints list of available FIFO commands</entry>
 			</row>
 			<row>
@@ -1241,26 +1256,26 @@ if (len_gt(1024)) {
 			    <entry>core</entry>
 			    <entry>none</entry>
 			    <entry>prints list of command-line arguments with which 
-				<application moreinfo="none">ser</application> was started</entry>
+				<application>ser</application> was started</entry>
 			</row>
 			<row>
 			    <entry>pwd</entry>
 			    <entry>core</entry>
 			    <entry>none</entry>
-			    <entry>prints <application moreinfo="none">ser</application>'s working
+			    <entry>prints <application>ser</application>'s working
 			    directory</entry>
 			</row>
 			<row>
 			    <entry>version</entry>
 			    <entry>core</entry>
 			    <entry>none</entry>
-			    <entry>prints version of <application moreinfo="none">ser</application></entry>
+			    <entry>prints version of <application>ser</application></entry>
 			</row>
 			<row>
 			    <entry>uptime</entry>
 			    <entry>core</entry>
 			    <entry>none</entry>
-			    <entry>prints <application moreinfo="none">ser</application>'s running time</entry>
+			    <entry>prints <application>ser</application>'s running time</entry>
 			</row>
 			<row>
 			    <entry>sl_stats</entry>
@@ -1345,7 +1360,7 @@ if (len_gt(1024)) {
 	<section>
 	    <title>Used Database Tables</title>
 	    <para>
-		<application moreinfo="none">ser</application> includes MySQL support
+		<application>ser</application> includes MySQL support
 		to guarantee data persistence across server reboots and storage
 		of users' web environment. The data stored in
 		the database include user profiles, access control lists, user location,
@@ -1363,32 +1378,32 @@ if (len_gt(1024)) {
 		    </listitem>
 		    <listitem>
 			<para>
-			    reserved -- reserved user names. <application moreinfo="none">serweb</application>
+			    reserved -- reserved user names. <application>serweb</application>
 			    does not permit creation of accounts with name on this list.
 			</para>
 		    </listitem>
 		    <listitem>
 			<para>
 			    phonebook -- user's personal phonebooks. Accessible via
-			    <application moreinfo="none">serweb</application>.
+			    <application>serweb</application>.
 			</para>
 		    </listitem>
 		    <listitem>
 			<para>
 			    pending -- table of unconfirmed subscription requests. Used by
-			    <application moreinfo="none">serweb</application>.
+			    <application>serweb</application>.
 			</para>
 		    </listitem>
 		    <listitem>
 			<para>
 			    missed_calls -- table of missed calls. Can be fed by acc modules
-			    if mysql support is turned on. Displayed by <application moreinfo="none">serweb</application>.
+			    if mysql support is turned on. Displayed by <application>serweb</application>.
 			</para>
 		    </listitem>
 		    <listitem>
 			<para>
 			    location -- user contacts. Typically updated through
-			    <application moreinfo="none">ser</application>'r registrar
+			    <application>ser</application>'r registrar
 			    functionality.
 			</para>
 		    </listitem>
@@ -1412,13 +1427,13 @@ if (len_gt(1024)) {
 		    <listitem>
 			<para>
 			    active_sessions -- keeps track of currently active web sessions.
-			    For use by <application moreinfo="none">serweb</application>.
+			    For use by <application>serweb</application>.
 			</para>
 		    </listitem>
 		    <listitem>
 			<para>
 			    acc -- keeps track of accounted calls.  Can be fed by acc module
-			    if mysql support is turned on. Displayed by <application moreinfo="none">serweb</application>.
+			    if mysql support is turned on. Displayed by <application>serweb</application>.
 			</para>
 		    </listitem>
 		    <listitem>
@@ -1466,4 +1481,4 @@ if (len_gt(1024)) {
 		
 	    </para>
 	</section>
-    </chapter> <!-- reference -->
+</section>

doc/seruser/seruser.sgml

@@ -1,152 +0,0 @@
-<!-- $Id$ -->
-<!-- DOCTYPE Book SYSTEM "/usr/share/sgml/docbook/dtd-4.2/docbook.dtd" [ -->
-<!DOCTYPE Book PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [ 
-
-
-<!ENTITY execexample SYSTEM "../../examples/exec.cfg">
-<!ENTITY redirectexample SYSTEM "../../examples/redirect.cfg">
-<!ENTITY replyexample SYSTEM "../../examples/onr.cfg">
-<!ENTITY statefuluaexample SYSTEM "../../examples/uas.cfg">
-<!ENTITY gpllicense SYSTEM "../../COPYING">
-<!ENTITY sendim SYSTEM "../../examples/web_im/send_im.php">
-<!ENTITY gatewayacl SYSTEM "../../examples/pstn.cfg">
-<!ENTITY accountingexample SYSTEM "../../examples/acc.cfg">
-<!ENTITY replicateexample SYSTEM "../../examples/replicate.cfg">
-<!ENTITY defscr SYSTEM "../../etc/ser.cfg">
-<!ENTITY execstep2 SYSTEM "../../examples/exec_s2.cfg">
-<!ENTITY execstep3 SYSTEM "../../examples/exec_s3.cfg">
-<!ENTITY execstep4 SYSTEM "../../examples/exec_s4.cfg">
-<!ENTITY execstep5 SYSTEM "../../examples/exec_s5.cfg">
-<!ENTITY execstep5b SYSTEM "../../examples/exec_s5b.cfg">
-<!ENTITY ccdiversion SYSTEM "../../examples/ccdiversion.cfg">
-<!ENTITY logging SYSTEM "../../examples/logging.cfg">
-<!ENTITY releasenotes SYSTEM "../../NEWS">
-<!ENTITY install SYSTEM "../../INSTALL">
-<!ENTITY voicemail SYSTEM "voicemail.sgml">
-<!ENTITY voicemailcfg SYSTEM "../../modules/vm/etc/ser.cfg">
-<!ENTITY intro SYSTEM "intro.sgml">
-<!ENTITY operation SYSTEM "operation.sgml">
-<!ENTITY apps SYSTEM "apps.sgml">
-<!ENTITY reference SYSTEM "reference.sgml">
-<!ENTITY general SYSTEM "general.sgml">
-<!ENTITY otherapps SYSTEM "otherapps.sgml">
-<!ENTITY dbfifo SYSTEM "db_fifo.sgml">
-
-
-
-]>
-
-
-<book label="seruser" id="seruser" lang="EN">
-
-<?dbhtml filename="index.html">
-
-   
-    <title>iptel.org SIP Express Router v0.11.0 -- Admin's Guide</title>
-    <bookinfo>
-	<authorgroup>
-	    <author>
-		<firstname>Jiri</firstname>
-		<surname>Kuthan</surname>
-		<!-- <email>[email protected]</email>  -->
-	    </author>
-	    <author>
-		<firstname>Jan</firstname>
-		<surname>Janak</surname>
-		<!-- <email>[email protected]</email> -->
-	    </author>
-	    <author>
-		<firstname>Yacine</firstname>
-		<surname>Rebahi</surname>
-		<!-- <email>[email protected]</email> -->
-	    </author>
-
-	</authorgroup>
-
-	<copyright>
-	    <year>2001</year>
-	    <year>2002</year>
-	    <holder>FhG Fokus</holder>
-	</copyright>
-	<legalnotice>
-	    <para>
-		This documentation is free software; you can redistribute
-		it and/or modify it under the terms of the GNU General Public
- 		License as published by the Free Software Foundation; either
-		version 2 of the License, or (at your option) any later
-		version.
-	    </para>
-	    
-	    <para>
-		This program is distributed in the hope that it will be
-		useful, but WITHOUT ANY WARRANTY; without even the implied
-		warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
-		See the GNU General Public License for more details.
-	    </para>
-	    
-	    <para>
-		You should have received a copy of the GNU General Public
-		License along with this program; if not, write to the Free
-		Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
-		MA 02111-1307 USA
-	    </para>
-	    
-	    <para>
-		For more details see the file COPYING in the source
-		distribution of <acronym>SER</acronym>.
-	    </para>	    
-	</legalnotice>
-
-	<abstract>
-	    <para>
-		The document describes the <acronym>SIP</acronym> Express Router and its use in
-		<acronym>SIP</acronym> networks. It is intended as an aid to server 
-		administrators. 
-	    </para>
-	</abstract>
-	<releaseinfo>
-	    This documentation is continuously updated. For the latest  
-	    version visit our site at 
-	    <ulink url="http://www.iptel.org/ser/">http://www.iptel.org/ser</ulink>.
-	    $Revision$.
-	</releaseinfo>
-    </bookinfo>
-
-    <toc></toc>
-
-&general;
-
-&intro;
-
-&operation;
-
-&apps;
-
-&otherapps;
-
-&reference;
-
-&dbfifo;
-    
-    
-    <!-- TODO
-
-    serweb, serweb accounting
-
-	new chapter: Network Design Example - should include a nice
-    picture of a network with all components in it and routes
-    to it, which correlate to a script; after the picture,
-	explanation of each route's specifics should be given
-    (use of auth, aaa, t_on_failure, etc.)
-
-    when already doing the pictures, one should make one of the
-    state machine for tm programmer's guide too
-
-    FAQ: 
-    - bandwidth, FW/NATs
-
-
-    -->
-
-</book>
-	

doc/seruser/seruser.xml

@@ -0,0 +1,54 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4//EN"
+                      "file:///usr/share/sgml/docbook/dtd/xml/4/docbookx.dtd">
+
+<section id="seruser" xmlns:xi="http://www.w3.org/2001/XInclude">
+    <sectioninfo>
+	<authorgroup>
+	    <author>
+		<firstname>Jiri</firstname>
+		<surname>Kuthan</surname>
+		<!-- <email>[email protected]</email>  -->
+	    </author>
+	    <author>
+		<firstname>Jan</firstname>
+		<surname>Janak</surname>
+		<!-- <email>[email protected]</email> -->
+	    </author>
+	    <author>
+		<firstname>Yacine</firstname>
+		<surname>Rebahi</surname>
+		<!-- <email>[email protected]</email> -->
+	    </author>
+	</authorgroup>
+	<copyright>
+	    <year>2001</year>
+	    <year>2002</year>
+	    <holder>FhG FOKUS</holder>
+	</copyright>
+	<abstract>
+	    <para>
+		The document describes the <acronym>SIP</acronym> Express Router and its use in
+		<acronym>SIP</acronym> networks. It is intended as an aid to server 
+		administrators. 
+	    </para>
+	</abstract>
+	<revhistory>
+	    <revision>
+		<revnumber>$Revision$</revnumber>
+		<date>$Date$</date>
+	    </revision>
+	</revhistory>
+    </sectioninfo>
+
+    <title>SER Administrator's Guide</title>
+
+    <xi:include href="general.xml"/>
+    <xi:include href="intro.xml"/>
+    <xi:include href="operation.xml"/>
+    <xi:include href="apps.xml"/>
+    <xi:include href="otherapps.xml"/>
+    <xi:include href="reference.xml"/>
+    <xi:include href="db_fifo.xml"/>
+</section>
+	

doc/seruser/voicemail.sgml

@@ -1,170 +0,0 @@
-<!-- <!DOCTYPE Book PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [ ]> -->
-<section>
-<title>Introduction</title>
-<para>
-	The voicemail system provides <application>ser</application>
-	with voice announcement and recording capabilities. Voice
-	messages may then be mailed to the called user. The system
-	relies on <application>ser</application> for implementing
-	the <acronym>SIP</acronym> stack and communicate with it
-	through <acronym>FIFO</acronym>. It implements the dialog and media
-	handling as described in RFC 3264 (An Offer/Answer Model with
-	the Session Description Protocol) and RFC 1889 (Real time
-	transport protocol) to realize its goal.
-</para>
-</section>
-<section>
-
-<title>Advantages</title>
-<para>
-	<itemizedlist>
-		<listitem>
-			<para>
-		            Anyone deploying <application>ser</application> and
-			    <acronym>VoIP</acronym> should profit from this 'ready-to-run'
-			    application. It plugs into <application>ser</application> as
-			    easy as configuring the database location, announce file path
-			    and SMTP server address. 
-			</para>
-	        </listitem>
-	        <listitem>
-			<para>
-			    Further,
-			    <application>voicemail</application>
-			    integrates the most popular free codecs
-			    (G.711ulaw, G.711alaw and GSM 06.10) and
-			    its own SMTP client, which means that you
-			    don't need to install anything else as
-			    <application>ser</application> and
-			    <application>voicemail</application>. 
-			</para>
-	        </listitem>
-	        <listitem>
-			<para>
-			    If you want your voicemail system to support
-			    other codecs, a simple plugin system with
-			    SDK allows you to integrate them fast and
-			    simply (see the basis plugins for examples). 
-			</para>
-	        </listitem>
-	</itemizedlist>
-</para>
-</section>
-<section>
-
-<title>Technical limitations</title>
-<para>
-	<itemizedlist>
-		<listitem>
-		    <para>
-		            The sound conversion engine doesn't
-			    support yet re-sampling. It means that
-			    input and output files have to be
-			    compatible with the sampling rate of the
-			    codec. All codecs included with the
-			    distribution work at 8kHz, which means
-			    that all the input and output files MUST
-			    be sampled at the rate of 8kHz.
-		    </para>
-		</listitem>
-		<listitem>
-		    <para>
-		            At the moment, voicemail only support the
-			    Microsoft Wav file format with PCM 16 bit,
-			    Mu-law and A-law 8 bit encoding.
-		    </para>
-		</listitem>
-	</itemizedlist>
-</para>
-</section>
-<section>
-
-<title>Compilation and installation</title>
-<para>
-        <itemizedlist>
-		<listitem>
-			<para>
-			First, you need to compile Ser with voicemail
-			support. Therefore, you must edit Ser's
-			Makefile.defs file and uncomment the line with
-			'-DVOICE_MAIL' and '-D_TOTAG'.
-			</para>
-		</listitem>
-		<listitem>
-			<para>
-			Then do 'make all' in Ser's root directory.
-			</para>
-		</listitem>
-		<listitem>
-			<para>
-			Configure Ser to fit your needs. You can
-			report to voicemail example config file to
-			know what your configuration file should
-			include. Note that voicemail
-			only needs to know the user database location
-			in order to work. Report to the README file in
-			the vm module directory for description of the
-			functions and variable that are used by
-			voicemail and how they work.
-			</para>
-		</listitem>
-		<listitem>
-			<para>
-			Finally, compile the voicemail application:
-
-			<programlisting>
-			[~/voicemail]$ cd ortp-0.5.0
-			[~/voicemail/ortp-0.5.0]$ ./configure
-			[~/voicemail/ortp-0.5.0]$ make all
-			[~/voicemail/ortp-0.5.0]$ cd ..
-			[~/voicemail]$ cd plug-in/gsm/gsm-????
-			[~/voicemail/plug-in/gsm/gsm-????]$ make all
-			[~/voicemail/plug-in/gsm/gsm-????]$ cd ../..
-			[~/voicemail]$ make all
-			</programlisting>
-
-			You can then start voicemail with following
-			command <command>ans_machine</command> and
-			look if the default fit your needs. If not,
-			type <command>ans_machine -h</command> to see
-			how to change the default parameters.
-
-			  <!--<note>-->
-			  If <application>ans_machine</application> is
-			  not started or can't be joined while
-			  <application>ser</application> tries to
-			  communicate with it, the caller will become
-			  a '500 internal server error' with a comment
-			  saying what the trouble is.
-			  <!--</note>-->
-			</para>
-		</listitem>
-	</itemizedlist>
-</para>
-</section>
-
-<section>
-<title>Example ser Config File</title>
-<para>
-	<example>
-                <title>Example ser Config File</title>
-		<programlisting>
-&voicemailcfg;
-		</programlisting>
-	</example>
-</para>
-</section>
-<section>
-
-<title>Availability, report bugs, contact the author</title>
-<para>
-        Ser's Voicemail's home page is hosted at
-	http://sems.berlios.de. A snapshot may be downloaded directly
-	from the CVS tree. A pre-configured version of 
-	<application>ser</application> including
-	<application>voicemail</application> will be soon available
-	(from version 0.8.11). Bugs can be reported at the voicemail's
-	home page. If you want to contact the author, use the contact
-	email at the home page.
-</para>
-</section>

doc/seruser/voicemail.xml

@@ -0,0 +1,164 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4//EN"
+                      "file:///usr/share/sgml/docbook/dtd/xml/4/docbookx.dtd">
+
+<section id="voicemail" xmlns:xi="http://www.w3.org/2001/XInclude">
+    <sectioninfo>
+	<revhistory>
+	    <revision>
+		<revnumber>$Revision$</revnumber>
+		<date>$Date$</date>
+	    </revision>
+	</revhistory>
+    </sectioninfo>
+    
+    <section>
+	<title>Introduction</title>
+	<para>
+	    The voicemail system provides <application>ser</application> with
+	    voice announcement and recording capabilities. Voice messages may
+	    then be mailed to the called user. The system relies on
+	    <application>ser</application> for implementing the
+	    <acronym>SIP</acronym> stack and communicate with it through
+	    <acronym>FIFO</acronym>. It implements the dialog and media
+	    handling as described in RFC 3264 (An Offer/Answer Model with the
+	    Session Description Protocol) and RFC 1889 (Real time transport
+	    protocol) to realize its goal.
+	</para>
+    </section>
+    <section>
+	<title>Advantages</title>
+	<para>
+	    <itemizedlist>
+		<listitem>
+		    <para>
+			Anyone deploying <application>ser</application> and
+			<acronym>VoIP</acronym> should profit from this 'ready-to-run'
+			application. It plugs into <application>ser</application> as
+			easy as configuring the database location, announce file path
+			and SMTP server address. 
+		    </para>
+	        </listitem>
+	        <listitem>
+		    <para>
+			Further, <application>voicemail</application>
+			integrates the most popular free codecs (G.711ulaw,
+			G.711alaw and GSM 06.10) and its own SMTP client, which
+			means that you don't need to install anything else as
+			<application>ser</application> and
+			<application>voicemail</application>.
+		    </para>
+	        </listitem>
+	        <listitem>
+		    <para>
+			If you want your voicemail system to support other
+			codecs, a simple plugin system with SDK allows you to
+			integrate them fast and simply (see the basis plugins
+			for examples).
+		    </para>
+	        </listitem>
+	    </itemizedlist>
+	</para>
+    </section>
+
+    <section>
+	<title>Technical limitations</title>
+	<para>
+	    <itemizedlist>
+		<listitem>
+		    <para>
+			The sound conversion engine doesn't support yet
+			re-sampling. It means that input and output files have
+			to be compatible with the sampling rate of the
+			codec. All codecs included with the distribution work
+			at 8kHz, which means that all the input and output
+			files MUST be sampled at the rate of 8kHz.
+		    </para>
+		</listitem>
+		<listitem>
+		    <para>
+			At the moment, voicemail only support the Microsoft Wav
+			file format with PCM 16 bit, Mu-law and A-law 8 bit
+			encoding.
+		    </para>
+		</listitem>
+	    </itemizedlist>
+	</para>
+    </section>
+
+    <section>
+	<title>Compilation and installation</title>
+	<para>
+	    <itemizedlist>
+		<listitem>
+		    <para>
+			First, you need to compile Ser with voicemail
+			support. Therefore, you must edit Ser's Makefile.defs
+			file and uncomment the line with '-DVOICE_MAIL' and
+			'-D_TOTAG'.
+		    </para>
+		</listitem>
+		<listitem>
+		    <para>
+			Then do 'make all' in Ser's root directory.
+		    </para>
+		</listitem>
+		<listitem>
+		    <para>
+			Configure Ser to fit your needs. You can report to
+			voicemail example config file to know what your
+			configuration file should include. Note that voicemail
+			only needs to know the user database location in order
+			to work. Report to the README file in the vm module
+			directory for description of the functions and variable
+			that are used by voicemail and how they work.
+		    </para>
+		</listitem>
+		<listitem>
+		    <para>
+			Finally, compile the voicemail application:
+			
+			<programlisting>
+[~/voicemail]$ cd ortp-0.5.0
+[~/voicemail/ortp-0.5.0]$ ./configure
+[~/voicemail/ortp-0.5.0]$ make all
+[~/voicemail/ortp-0.5.0]$ cd ..
+[~/voicemail]$ cd plug-in/gsm/gsm-????
+[~/voicemail/plug-in/gsm/gsm-????]$ make all
+[~/voicemail/plug-in/gsm/gsm-????]$ cd ../..
+[~/voicemail]$ make all
+			</programlisting>
+
+			You can then start voicemail with following
+			command <command>ans_machine</command> and
+			look if the default fit your needs. If not,
+			type <command>ans_machine -h</command> to see
+			how to change the default parameters.
+
+			  <!--<note>-->
+			  If <application>ans_machine</application> is
+			  not started or can't be joined while
+			  <application>ser</application> tries to
+			  communicate with it, the caller will become
+			  a '500 internal server error' with a comment
+			  saying what the trouble is.
+			  <!--</note>-->
+		    </para>
+		</listitem>
+	    </itemizedlist>
+	</para>
+    </section>
+    <section>
+	<title>Availability, report bugs, contact the author</title>
+	<para>
+	    Ser's Voicemail's home page is hosted at
+	    http://sems.berlios.de. A snapshot may be downloaded directly
+	    from the CVS tree. A pre-configured version of 
+	    <application>ser</application> including
+	    <application>voicemail</application> will be soon available
+	    (from version 0.8.11). Bugs can be reported at the voicemail's
+	    home page. If you want to contact the author, use the contact
+	    email at the home page.
+	</para>
+    </section>
+</section>

doc/sip/Makefile

@@ -0,0 +1,29 @@
+#
+# The list of documents to build (without extensions)
+#
+DOCUMENTS = sip_introduction
+
+#
+# The root directory containing Makefile.doc
+#
+ROOT_DIR=../..
+
+#
+# Validate docbook documents before generating output
+# (may be slow)
+#
+#VALIDATE=1
+
+#
+# You can override the stylesheet used to generate
+# xhtml documents here
+#
+#XHTML_XSL=$(ROOT_DIR)/doc/stylesheets/xhtml.xsl
+
+#
+# You can override the stylesheet used to generate
+# plain text documents here
+#
+#TXT_XSL=$(XHTML_XSL)
+
+include $(ROOT_DIR)/Makefile.doc

doc/sip/sip_introduction.sgml

@@ -1,1052 +0,0 @@
-<!-- $Id$ -->
-<!DOCTYPE Book PUBLIC "-//OASIS//DTD DocBook V4.2//EN" [
-
-<!-- Include general SER documentation entities -->
-<!ENTITY % serentities SYSTEM "../ser_entities.sgml">
-%serentities;
-
-]>
-
-<book>
-    <bookinfo>
-	<title>&sip; Introduction</title>
-	<authorgroup>
-	    <author>
-		<firstname>Jan</firstname>
-		<surname>Janak</surname>
-		<email>[email protected]</email>
-	    </author>
-	</authorgroup>
-	<copyright>
-	    <year>2003</year>
-	    <holder>&fhg;</holder>
-	</copyright>
-	<abstract>
-	    <para>
-		A brief overview of &sip; describing all important aspects of the Session Initiation
-		Protocol.
-	    </para>
-	</abstract>
-    </bookinfo>
-    <toc></toc>
-
-    <chapter>
-	<title>&sip; Introduction</title>
-	<section id="sec-purpose-of-sip">
-	    <title>Purpose of &sip;</title>
-	    <simpara>
-		&sip; stands for Session Initiation Protocol. It is an application-layer control
-		protocol which has been developed and designed within the &ietf;. The protocol has
-		been designed with easy implementation, good scalability, and flexibility in mind.
-	    </simpara>
-	    <simpara>
-		The specification is available in form of several <abbrev>RFCs</abbrev>, the most
-		important one is &rfc3261; which contains the core protocol specification. The
-		protocol is used for creating, modifying, and terminating sessions with one or more
-		participants. By sessions we understand a set of senders and receivers that
-		communicate and the state kept in those senders and receivers during the
-		communication. Examples of a session can include Internet telephone calls,
-		distribution of multimedia, multimedia conferences, distributed computer games, etc.
-	    </simpara>
-	    <simpara>
-		&sip; is not the only protocol that the communicating devices will need. It is not
-		meant to be a general purpose protocol. Purpose of &sip; is just to make the
-		communication possible, the communication itself must be achieved by another means
-		(and possibly another protocol). Two protocols that are most often used along with
-		&sip; are &rtp; and &sdp;. &rtp; protocol is used to carry the real-time multimedia
-		data (including audio, video, and text), the protocol makes it possible to encode
-		and split the data into packets and transport such packets over the
-		Internet. Another important protocol is &sdp;, which is used to describe and encode
-		capabilities of session participants. Such a description is then used to negotiate
-		the characteristics of the session so that all the devices can participate (that
-		includes, for example, negotiation of codecs used to encode media so all the
-		participants will be able to decode it, negotiation of transport protocol used and
-		so on).
-	    </simpara>
-	    <simpara>
-		&sip; has been designed in conformance with the Internet model. It is an end-to-end
-		oriented signaling protocol which means, that all the logic is stored in end
-		devices (except routing of &sip; messages). State is also stored in end-devices
-		only, there is no single point of failure and networks designed this way scale
-		well. The price that we have to pay for the distributiveness and scalability is
-		higher message overhead, caused by the messages being sent end-to-end.
-	    </simpara>
-	    <simpara>
-		It is worth of mentioning that the end-to-end concept of &sip; is a significant
-		divergence from regular &pstn; (Public Switched Telephone Network) where all the
-		state and logic is stored in the network and end devices (telephones) are very
-		primitive. Aim of &sip; is to provide the same functionality that the traditional
-		&pstn;s have, but the end-to-end design makes &sip; networks much more powerful and
-		open to the implementation of new services that can be hardly implemented in the
-		traditional &pstn;s.
-	    </simpara>
-	    <simpara>
-		&sip; is based on &http; protocol. The &http; protocol inherited format of message
-		headers from &rfc822;. &http; is probably the most successful and widely used
-		protocol in the Internet. It tries to combine the best of the both. In fact, &http;
-		can be classified as a signaling protocol too, because user agents use the protocol
-		to tell a &http; server in which documents they are interested in. &sip; is used to
-		carry the description of session parameters, the description is encoded into a
-		document using &sdp;. Both protocols (&http; and &sip;) have inherited encoding of
-		message headers from &rfc822;. The encoding has proven to be robust and flexible
-		over the years.
-	    </simpara>
-	</section>
-	<section id="sec-sip-uri">
-	    <title>&sip; &uri;</title>
-	    <simpara>
-		&sip; entities are identified using &sip; &uri; (Uniform Resource Identifier). A
-		&sip; &uri; has form of sip:username@domain, for instance,
-		sip:[email protected]. As we can see, &sip; &uri; consists of username part and
-		domain name part delimited by @ (at) character. &sip; &uri;s are similar to
-		e-mail addresses, it is, for instance, possible to use the same &uri; for e-mail
-		and &sip; communication, such &uri;s are easy to remember.
-	    </simpara>
-	</section>
-	<section id="sec-sip-network-elements">
-	    <title>&sip; Network Elements</title>
-	    <simpara>
-		Although in the simplest configuration it is possible to use just two user agents
-		that send &sip; messages directly to each other, a typical &sip; network will
-		contain more than one type of &sip; elements. Basic &sip; elements are user agents,
-		proxies, registrars, and redirect servers. We will briefly describe them in this
-		section.
-	    </simpara>
-	    <simpara>
-		Note that the elements, as presented in this section, are often only logical
-		entities. It is often profitable to co-locate them together, for instance, to
-		increase the speed of processing, but that depends on a particular implementation
-		and configuration.
-	    </simpara>
-	    <section id="sec-user-agents">
-		<title>User Agents</title>
-		<simpara>
-		    Internet end points that use &sip; to find each other and to negotiate a session
-		    characteristics are called <emphasis>user agents</emphasis>. User agents
-		    usually, but not necessarily, reside on a user's computer in form of an
-		    application--this is currently the most widely used approach, but user agents
-		    can be also cellular phones, &pstn; gateways, <acronym>PDAs</acronym>, automated
-		    <acronym>IVR</acronym> systems and so on.
-		</simpara>
-		<simpara>
-		    User agents are often referred to as <emphasis>User Agent Server</emphasis>
-		    (&uas;) and <emphasis>User Agent Client</emphasis> (&uac;). &uas; and &uac; are
-		    logical entities only, each user agent contains a &uac; and &uas;. &uac; is the
-		    part of the user agent that sends requests and receives responses. &uas; is the
-		    part of the user agent that receives requests and sends responses.
-		</simpara>
-		<simpara>
-		    Because a user agent contains both &uac; and &uas;, we often say that a user
-		    agent behaves like a &uac; or &uas;. For instance, caller's user agent behaves
-		    like &uac; when it sends an INVITE requests and receives responses to the
-		    request. Callee's user agent behaves like a &uas; when it receives the INVITE
-		    and sends responses.
-		</simpara>
-		<simpara>
-		    But this situation changes when the callee decides to send a BYE and terminate
-		    the session. In this case the callee's user agent (sending BYE) behaves like
-		    &uac; and the caller's user agent behaves like &uas;.
-		</simpara>
-		<figure id="fig-ua" float="0">
-		    <title>&uac; and &uas;</title>		    
-		    <mediaobject>
-			<imageobject>
-			    <imagedata align="center" scale="40" fileref="figures/ua.eps" format="EPS">
-			</imageobject>
-			<imageobject>
-			    <imagedata align="center" fileref="figures/ua.png" format="PNG">
-			</imageobject>
-			<textobject>
-			    <phrase>Picture showing &uac; and &uas;</phrase>
-			</textobject>
-		    </mediaobject>
-		</figure>
-		<simpara>
-		    <xref linkend="fig-ua"> shows three user agents and one stateful forking
-		    proxy. Each user agent contains &uac; and &uas;. The part of the proxy that
-		    receives the INVITE from the caller in fact acts as a &uas;. When forwarding the
-		    request statefully the proxy creates two &uac;s, each of them is responsible for
-		    one branch.
-		</simpara>
-		<simpara>
-		    In our example callee B picked up and later when he wants to tear down the call
-		    it sends a BYE. At this time the user agent that was previously &uas; becomes a
-		    &uac; and vice versa.
-		</simpara>
-	    </section>
-	    <section id="sec-proxy-servers">
-		<title>Proxy Servers</title>
-		<simpara>
-		    In addition to that &sip; allows creation of an infrastructure of network hosts
-		    called <emphasis>proxy servers</emphasis>. User agents can send messages to a
-		    proxy server. Proxy servers are very important entities in the &sip;
-		    infrastructure. They perform routing of a session invitations according to
-		    invitee's current location, authentication, accounting and many other important
-		    functions.
-		</simpara>
-		<simpara>
-		    The most important task of a proxy server is to route session invitations
-		    <quote>closer</quote> to callee. The session invitation will usually traverse a
-		    set of proxies until it finds one which knows the actual location of the
-		    callee. Such a proxy will forward the session invitation directly to the callee
-		    and the callee will then accept or decline the session invitation.
-		</simpara>
-		<simpara>
-		    There are two basic types of &sip; proxy servers--stateless and stateful.
-		</simpara>
-
-		<section id="sec-stateless-servers">
-		    <title>Stateless Servers</title>
-		    <simpara>
-			Stateless server are simple message forwarders. They forward messages
-			independently of each other. Although messages are usually arranged into
-			transactions (see <xref linkend="sec-sip-transactions">), stateless proxies
-			do not take care of transactions.
-		    </simpara>
-		    <simpara>
-			Stateless proxies are simple, but faster than stateful proxy servers. They
-			can be used as simple load balancers, message translators and routers. One
-			of drawbacks of stateless proxies is that they are unable to absorb
-			retransmissions of messages and perform more advanced routing, for instance,
-			forking or recursive traversal.
-		    </simpara>
-		</section>
-		<section id="sec-stateful-servers">
-		    <title>Stateful Servers</title>
-		    <simpara>
-			Stateful proxies are more complex. Upon reception of a request, stateful
-			proxies create a state and keep the state until the transaction
-			finishes. Some transactions, especially those created by INVITE, can last
-			quite long (until callee picks up or declines the call). Because stateful
-			proxies must maintain the state for the duration of the transactions, their
-			performance is limited.
-		    </simpara>
-		    <simpara>
-			The ability to associate &sip; messages into transactions gives stateful
-			proxies some interesting features. Stateful proxies can perform forking,
-			that means upon reception of a message two or more messages will be sent
-			out.
-		    </simpara>
-		    <simpara>
-			Stateful proxies can absorb retransmissions because they know, from the
-			transaction state, if they have already received the same message (stateless
-			proxies cannot do the check because they keep no state).
-		    </simpara>
-		    <simpara>
-			Stateful proxies can perform more complicated methods of finding a user. It
-			is, for instance, possible to try to reach user's office phone and when he
-			doesn't pick up then the call is redirected to his cell phone. Stateless
-			proxies can't do this because they have no way of knowing how the
-			transaction targeted to the office phone finished.
-		    </simpara>
-		    <simpara>
-			Most &sip; proxies today are stateful because their configuration is usually
-			very complex. They often perform accounting, forking, some sort of &nat;
-			traversal aid and all those features require a stateful proxy.
-		    </simpara>
-		</section>
-		<section id="sec-proxy-server-usage">
-		    <title>Proxy Server Usage</title>
-		    <simpara>
-			A typical configuration is that each centrally administered entity (a
-			company, for instance) has it's own &sip; proxy server which is used by all
-			user agents in the entity. Let's suppose that there are two companies A and
-			B and each of them has it's own proxy server. <xref linkend="fig-companies">
-			shows how a session invitation from employee Joe in company A will reach
-			employee Bob in company B.
-		    </simpara>
-		    <figure id="fig-companies" float="0">
-			<title>Session Invitation</title>
-			<mediaobject>
-			    <imageobject>
-				<imagedata align="center" scale="40" fileref="figures/companies.eps" format="EPS">
-			    </imageobject>
-			    <imageobject>
-				<imagedata align="center" fileref="figures/companies.png" format="PNG">
-			    </imageobject>
-			    <textobject>
-				<phrase>Picture showing a session invitation message flow</phrase>
-			    </textobject>
-			</mediaobject> 
-		    </figure>
-		    <simpara>
-			User Joe uses address sip:[email protected] to call Bob. Joe's user agent doesn't
-			know how to route the invitation itself but it is configured to send all
-			outbound traffic to the company &sip; proxy server proxy.a.com. The proxy
-			server figures out that user sip:[email protected] is in a different company so it
-			will look up B's &sip; proxy server and send the invitation there. B's proxy
-			server can be either pre-configured at proxy.a.com or the proxy will use
-			<acronym>DNS SRV</acronym> records to find B's proxy server. The invitation
-			reaches proxy.bo.com. The proxy knows that Bob is currently sitting in his
-			office and is reachable through phone on his desk, which has &ip; address
-			1.2.3.4, so the proxy will send the invitation there.
-		    </simpara>
-		</section>
-	    </section>
-	    <section id="sec-registrar">
-		<title>Registrar</title>
-		<simpara>
-		    We mentioned that the &sip; proxy at proxy.b.com knows current Bob's location
-		    but haven't mentioned yet how a proxy can learn current location of a
-		    user. Bob's user agent (&sip; phone) must register with a
-		    <emphasis>registrar</emphasis>. The registrar is a special &sip; entity that
-		    receives registrations from users, extracts information about their current
-		    location (&ip; address, port and username in this case) and stores the
-		    information into location database. Purpose of the location database is to map
-		    sip:[email protected] to something like sip:[email protected]:5060. The location database is
-		    then used by B's proxy server. When the proxy receives an invitation for
-		    sip:[email protected] it will search the location database. It finds
-		    sip:[email protected]:5060 and will send the invitation there. A registrar is very
-		    often a logical entity only. Because of their tight coupling with proxies
-		    registrars, are usually co-located with proxy servers.
-		</simpara>
-		<simpara>
-		    <xref linkend="fig-registrar"> shows a typical &sip; registration. A REGISTER
-		    message containing Address of Record sip:[email protected] and contact address
-		    sip:[email protected]:5060 where 1.2.3.4 is &ip; address of the phone, is sent to the
-		    registrar. The registrar extracts this information and stores it into the
-		    location database. If everything went well then the registrar sends a 200 OK
-		    response to the phone and the process of registration is finished.
-		</simpara>
-		<figure id="fig-registrar" float="0">
-		    <title>Registrar Overview</title>
-		    <mediaobject>
-			<imageobject>
-			    <imagedata align="center" scale="40" fileref="figures/registrar.eps" format="EPS">
-			</imageobject>
-			<imageobject>
-			    <imagedata align="center" fileref="figures/registrar.png" format="PNG">
-			</imageobject>
-			<textobject>
-			    <phrase>Picture showing a typical registrar</phrase>
-			</textobject>
-		    </mediaobject> 
-		</figure>
-		<simpara>
-		    Each registration has a limited lifespan. Expires header field or expires
-		    parameter of Contact header field determines for how long is the registration
-		    valid. The user agent must refresh the registration within the lifespan
-		    otherwise it will expire and the user will become unavailable.
-		</simpara>
-	    </section>
-	    <section id="sec-redirect-server">
-		<title>Redirect Server</title>
-		<simpara>
-		    The entity that receives a request and sends back a reply containing a list of the
-		    current location of a particular user is called <emphasis>redirect server</emphasis>. A
-		    redirect server receives requests and looks up the intended recipient of the request in
-		    the location database created by a registrar. It then creates a list of current
-		    locations of the user and sends it to the request originator in a response within 3xx
-		    class.
-		</simpara>
-		<simpara>
-		    The originator of the request then extracts the list of destinations and sends
-		    another request directly to them. <xref linkend="fig-redirect"> shows a typical
-		    redirection.
-		</simpara>
-		<figure id="fig-redirect" float="0">
-		    <title>&sip; Redirection</title>
-		    <mediaobject>
-			<imageobject>
-			    <imagedata align="center" scale="40" fileref="figures/redirect.eps" format="EPS">
-			</imageobject>
-			<imageobject>
-			    <imagedata align="center" fileref="figures/redirect.png" format="PNG">
-			</imageobject>
-			<textobject>
-			    <phrase>Picture showing a redirection</phrase>
-			</textobject>
-		    </mediaobject> 
-		</figure>
-	    </section>
-	</section>
-	<section id="sec-sip-messages">
-	    <title>&sip; Messages</title>
-	    <simpara>
-		Communication using &sip; (often called signaling) comprises of series of
-		<emphasis>messages</emphasis>. Messages can be transported independently by the
-		network. Usually they are transported in a separate &udp; datagram each. Each
-		message consist of <quote>first line</quote>, message header, and message body. The
-		first line identifies type of the message. There are two types of
-		messages--<emphasis>requests</emphasis> and <emphasis>responses</emphasis>.
-		Requests are usually used to initiate some action or inform recipient of the request
-		of something. Replies are used to confirm that a request was received and processed
-		and contain the status of the processing.
-	    </simpara>
-	    <simpara>
-		A typical &sip; request looks like this:
-	    </simpara>
-	<programlisting format="linespecific">
-INVITE sip:[email protected] SIP/2.0
-Via: SIP/2.0/UDP 195.37.77.100:5040;rport
-Max-Forwards: 10
-From: "jiri" &lt;sip:[email protected]&gt;;tag=76ff7a07-c091-4192-84a0-d56e91fe104f
-To: &lt;sip:[email protected]&gt;
-Call-ID: [email protected]
-CSeq: 2 INVITE
-Contact: &lt;sip:213.20.128.35:9315&gt;
-User-Agent: Windows RTC/1.0
-Proxy-Authorization: Digest username="jiri", realm="iptel.org", 
-  algorithm="MD5", uri="sip:[email protected]", 
-  nonce="3cef753900000001771328f5ae1b8b7f0d742da1feb5753c", 
-  response="53fe98db10e1074
-b03b3e06438bda70f"
-Content-Type: application/sdp
-Content-Length: 451
-
-v=0
-o=jku2 0 0 IN IP4 213.20.128.35
-s=session
-c=IN IP4 213.20.128.35
-b=CT:1000
-t=0 0
-m=audio 54742 RTP/AVP 97 111 112 6 0 8 4 5 3 101
-a=rtpmap:97 red/8000
-a=rtpmap:111 SIREN/16000
-a=fmtp:111 bitrate=16000
-a=rtpmap:112 G7221/16000
-a=fmtp:112 bitrate=24000
-a=rtpmap:6 DVI4/16000
-a=rtpmap:0 PCMU/8000
-a=rtpmap:4 G723/8000
-a=rtpmap: 3 GSM/8000
-a=rtpmap:101 telephone-event/8000
-a=fmtp:101 0-16
-</programlisting>
-	    <simpara>
-		The first line tells us that this is INVITE message which is used to establish a
-		session. The &uri; on the first line--sip:[email protected] is called <emphasis>Request
-		&uri;</emphasis> and contains &uri; of the next hop of the message. In this case it
-		will be host iptel.org.
-	    </simpara>
-	    <simpara>
-		A &sip; request can contain one or more Via header fields which are used to record
-		path of the request. They are later used to route &sip; responses exactly the same
-		way. The INVITE message contains just one Via header field which was created by the
-		user agent that sent the request. From the Via field we can tell that the user agent
-		is running on host 195.37.77.100 and port 5060.
-	    </simpara>
-	    <simpara>
-		From and To header fields identify initiator (caller) and recipient (callee) of the
-		invitation (just like in &smtp; where they identify sender and recipient of a
-		message). From header field contains a tag parameter which serves as a dialog
-		identifier and will be described in <xref linkend="sec-sip-dialogs">.
-	    </simpara>
-	    <simpara>
-		Call-ID header field is a dialog identifier and it's purpose is to identify messages
-		belonging to the same call. Such messages have the same Call-ID identifier. CSeq is
-		used to maintain order of requests. Because requests can be sent over an unreliable
-		transport that can re-order messages, a sequence number must be present in the
-		messages so that recipient can identify retransmissions and out of order requests.
-	    </simpara>
-	    <simpara>
-		Contact header field contains &ip; address and port on which the sender is awaiting
-		further requests sent by callee. Other header fields are not important and will be
-		not described here.
-	    </simpara>
-	    <simpara>
-		Message header is delimited from message body by an empty line. Message body of the INVITE
-		request contains a description of the media type accepted by the sender and encoded in
-		&sdp;.
-	    </simpara>
-	    <section id="sec-sip-requests">
-		<title>&sip; Requests</title>
-		<simpara>
-		    We have described how an INVITE request looks like and said that the request is
-		    used to invite a callee to a session. Other important requests are:
-		</simpara>
-		<itemizedlist>
-		    <listitem>
-			<simpara>
-			    <emphasis>ACK</emphasis>--This message acknowledges receipt of a final
-			    response to INVITE. Establishing of a session utilizes 3-way
-			    hand-shaking due to asymmetric nature of the invitation. It may take a
-			    while before the callee accepts or declines the call so the callee's
-			    user agent periodically retransmits a positive final response until it
-			    receives an ACK (which indicates that the caller is still there and
-			    ready to communicate).
-			</simpara>
-		    </listitem>
-		    <listitem>
-			<simpara>
-			    <emphasis>BYE</emphasis>--Bye messages are used to tear down multimedia
-			    sessions. A party wishing to tear down a session sends a BYE to the
-			    other party.
-			</simpara>
-		    </listitem>
-		    <listitem>
-			<simpara>
-			    <emphasis>CANCEL</emphasis>--Cancel is used to cancel not yet fully
-			    established session. It is used when the callee hasn't replied with a
-			    final response yet but the caller wants to abort the call (typically
-			    when a callee doesn't respond for some time).
-			</simpara>
-		    </listitem>
-		    <listitem>
-			<simpara>
-			    <emphasis>REGISTER</emphasis>--Purpose of REGISTER request is to let
-			    registrar know of current user's location. Information about current
-			    &ip; address and port on which a user can be reached is carried in
-			    REGISTER messages. Registrar extracts this information and puts it into
-			    a location database. The database can be later used by &sip; proxy
-			    servers to route calls to the user. Registrations are time-limited and
-			    need to be periodically refreshed.
-			</simpara>
-		    </listitem>
-		</itemizedlist>
-		<simpara>
-		    The listed requests usually have no message body because it is not needed in
-		    most situations (but can have one). In addition to that many other request types
-		    have been defined but their description is out of the scope of this document.
-		</simpara>
-	    </section>
-	    <section id="sec-sip-responses">
-		<title>&sip; Responses</title>
-		<simpara>
-		    When a user agent or proxy server receives a request it send a reply. Each
-		    request must be replied except ACK requests which trigger no replies.
-		</simpara>
-		<simpara>
-		    A typical reply looks like this:
-		</simpara>
-		<programlisting format="linespecific">
-SIP/2.0 200 OK
-Via: SIP/2.0/UDP 192.168.1.30:5060;received=66.87.48.68
-From: sip:[email protected]
-To: sip:[email protected];tag=794fe65c16edfdf45da4fc39a5d2867c.b713
-Call-ID: [email protected]
-CSeq: 63629 REGISTER
-Contact: &lt;sip:[email protected]:5060;transport=udp&gt;;q=0.00;expires=120
-Server: Sip EXpress router (0.8.11pre21xrc (i386/linux))
-Content-Length: 0
-Warning: 392 195.37.77.101:5060 "Noisy feedback tells:  
-    pid=5110 req_src_ip=66.87.48.68 req_src_port=5060 in_uri=sip:iptel.org 
-    out_uri=sip:iptel.org via_cnt==1"
-</programlisting>
-		<simpara>
-		    As we can see, responses are very similar to the requests, except for the first
-		    line. The first line of response contains protocol version (SIP/2.0), reply
-		    code, and reason phrase.
-		</simpara>
-		<simpara>
-		    The <emphasis>reply code</emphasis> is an integer number from 100 to 699 and
-		    indicates type of the response. There are 6 classes of responses:
-		</simpara>
-		<itemizedlist>
-		    <listitem>
-			<simpara>
-			    <emphasis>1xx</emphasis> are <emphasis>provisional</emphasis>
-			    responses. A provisional response is response that tells to its
-			    recipient that the associated request was received but result of the
-			    processing is not known yet. Provisional responses are sent only when
-			    the processing doesn't finish immediately. The sender must stop
-			    retransmitting the request upon reception of a provisional response.
-			</simpara>
-			<simpara>
-			    Typically proxy servers send responses with code 100 when they start
-			    processing an INVITE and user agents send responses with code 180
-			    (Ringing) which means that the callee's phone is ringing.
-			</simpara>
-		    </listitem>
-		    <listitem>
-			<simpara>
-			    <emphasis>2xx</emphasis> responses are <emphasis>positive
-			    final</emphasis> responses. A final response is the ultimate response
-			    that the originator of the request will ever receive. Therefore final
-			    responses express result of the processing of the associated
-			    request. Final responses also terminate transactions. Responses with
-			    code from 200 to 299 are positive responses that means that the request
-			    was processed successfully and accepted. For instance a 200 OK response
-			    is sent when a user accepts invitation to a session (INVITE request).
-			</simpara>
-			<simpara>
-			    A &uac; may receive several 200 messages to a single INVITE
-			    request. This is because a forking proxy (described later) can fork the
-			    request so it will reach several &uas; and each of them will accept the
-			    invitation. In this case each response is distinguished by the tag
-			    parameter in To header field. Each response represents a distinct dialog
-			    with unambiguous dialog identifier.
-			</simpara>
-		    </listitem>
-		    <listitem>
-			<simpara>
-			    <emphasis>3xx</emphasis> responses are used to redirect a caller. A
-			    redirection response gives information about the user's new location or
-			    an alternative service that the caller might use to satisfy the
-			    call. Redirection responses are usually sent by proxy servers. When a
-			    proxy receives a request and doesn't want or can't process it for any
-			    reason, it will send a redirection response to the caller and put
-			    another location into the response which the caller might want to
-			    try. It can be the location of another proxy or the current location of
-			    the callee (from the location database created by a registrar). The
-			    caller is then supposed to re-send the request to the new location. 3xx
-			    responses are final.
-			</simpara>
-		    </listitem>
-		    <listitem>
-			<simpara>
-			    <emphasis>4xx</emphasis> are <emphasis>negative final</emphasis>
-			    responses. a 4xx response means that the problem is on the sender's
-			    side. The request couldn't be processed because it contains bad syntax
-			    or cannot be fulfilled at that server.
-			</simpara>
-		    </listitem>
-		    <listitem>
-			<simpara>
-			    <emphasis>5xx</emphasis> means that the problem is on server's side. The
-			    request is apparently valid but the server failed to fulfill it. Clients
-			    should usually retry the request later.
-			</simpara>
-		    </listitem>
-		    <listitem>
-			<simpara>
-			    <emphasis>6xx</emphasis> reply code means that the request cannot be
-			    fulfilled at any server. This response is usually sent by a server that
-			    has definitive information about a particular user. User agents usually
-			    send a 603 Decline response when the user doesn't want to participate in
-			    the session.
-			</simpara>
-		    </listitem>
-		</itemizedlist>
-		<simpara>
-		    In addition to the response class the first line also contains <emphasis>reason
-			phrase</emphasis>. The code number is intended to be processed by
-		    machines. It is not very human-friendly but it is very easy to parse and
-		    understand by machines. The reason phrase usually contains a human-readable
-		    message describing the result of the processing. A user agent should render
-		    the reason phrase to the user.
-		</simpara>
-		<simpara>
-		    The request to which a particular response belongs is identified using the CSeq
-		    header field. In addition to the sequence number this header field also contains
-		    method of corresponding request. In our example it was REGISTER request.
-		</simpara>
-	    </section>
-	</section> 
-	<section id="sec-sip-transactions">
-	    <title>&sip; Transactions</title>
-	    <simpara>
-		Although we said that &sip; messages are sent independently over the network, they
-		are usually arranged into <emphasis>transactions</emphasis> by user agents and
-		certain types of proxy servers. Therefore &sip; is said to be a
-		<emphasis>transactional protocol</emphasis>.
-	    </simpara>
-	    <simpara>
-		A transaction is a sequence of &sip; messages exchanged between &sip; network
-		elements. A transaction consists of one request and all responses to that
-		request. That includes zero or more provisional responses and one or more final
-		responses (remember that an INVITE might be answered by more than one final response
-		when a proxy server forks the request).
-	    </simpara>
-	    <simpara>
-		If a transaction was initiated by an INVITE request then the same transaction also
-		includes ACK, but only if the final response was not a 2xx response. If the final
-		response was a 2xx response then the ACK is not considered part of the transaction.
-	    </simpara>
-	    <simpara>
-		As we can see this is quite asymmetric behavior--ACK is part of transactions with a
-		negative final response but is not part of transactions with positive final
-		responses. The reason for this separation is the importance of delivery of all 200
-		OK messages. Not only that they establish a session, but also 200 OK can be
-		generated by multiple entities when a proxy server forks the request and all of them
-		must be delivered to the calling user agent. Therefore user agents take
-		responsibility in this case and retransmit 200 OK responses until they receive an
-		ACK. Also note that only responses to INVITE are retransmitted !
-	    </simpara>
-	    <simpara>
-		&sip; entities that have notion of transactions are called
-		<emphasis>stateful</emphasis>. Such entities usually create a state associated with
-		a transaction that is kept in the memory for the duration of the transaction. When a
-		request or response comes, a stateful entity tries to associate the request (or
-		response) to existing transactions. To be able to do it it must extract a unique
-		transaction identifier from the message and compare it to identifiers of all
-		existing transactions. If such a transaction exists then it's state gets updated
-		from the message.
-	    </simpara>
-	    <simpara>
-		In the previous &sip; &rfc2543; the transaction identifier was calculated as hash of
-		all important message header fields (that included To, From, Request-URI and
-		CSeq). This proved to be very slow and complex, during interoperability tests such
-		transaction identifiers used to be a common source of problems.
-	    </simpara>
-	    <simpara>
-		In the new &rfc3261; the way of calculating transaction identifiers was completely
-		changed. Instead of complicated hashing of important header fields a &sip; message now
-		includes the identifier directly. Branch parameter of Via header fields contains directly
-		the transaction identifier. This is significant simplification, but there still exist old
-		implementations that don't support the new way of calculating of transaction identifier so
-		even new implementations have to support the old way. They must be backwards compatible.
-	    </simpara>
-	    <simpara>
-		<xref linkend="fig-transactions"> shows what messages belong to what transactions
-		during a conversation of two user agents.
-	    </simpara>
-	    <figure id="fig-transactions" float="0">
-		<title>&sip; Transactions</title>
-		<mediaobject>
-		    <imageobject>
-			<imagedata align="center" scale="40" fileref="figures/transaction.eps" format="EPS">
-		    </imageobject>
-		    <imageobject>
-			<imagedata align="center" fileref="figures/transaction.png" format="PNG">
-		    </imageobject>
-		    <textobject>
-			<phrase>Message flow showing messages belonging to the same transaction.</phrase>
-		    </textobject>
-		</mediaobject>
-	    </figure>
-	</section>
-	<section id="sec-sip-dialogs">
-	    <title>&sip; Dialogs</title>
-	    <simpara>
-		We have shown what transactions are, that one transaction includes INVITE and it's
-		responses and another transaction includes BYE and it responses when a session is
-		being torn down. But we feel that those two transactions should be somehow
-		related--both of them belong to the same <emphasis>dialog</emphasis>. A dialog
-		represents a peer-to-peer &sip; relationship between two user agents. A dialog
-		persists for some time and it is very important concept for user agents. Dialogs
-		facilitate proper sequencing and routing of messages between &sip; endpoints.
-	    </simpara>
-	    <simpara>
-		Dialogs are identified using Call-ID, From tag, and To tag. Messages that have these
-		three identifiers same belong to the same dialog. We have shown that CSeq header
-		field is used to order messages, in fact it is used to order messages within a
-		dialog. The number must be monotonically increased for each message sent within a
-		dialog otherwise the peer will handle it as out of order request or
-		retransmission. In fact, the CSeq number identifies a transaction within a dialog
-		because we have said that requests and associated responses are called
-		transaction. This means that only one transaction in each direction can be active
-		within a dialog. One could also say that a <emphasis>dialog is a sequence of
-		transactions</emphasis>. <xref linkend="fig-dialog"> extends <xref
-		linkend="fig-transactions"> to show which messages belong to the same dialog.
-	    </simpara>
-	    <figure id="fig-dialog" float="0">
-		<title>&sip; Dialog</title>
-		<mediaobject>
-		    <imageobject>
-			<imagedata align="center" scale="40" fileref="figures/dialog.eps" format="EPS">
-		    </imageobject>
-		    <imageobject>
-			<imagedata align="center" fileref="figures/dialog.png" format="PNG">
-		    </imageobject>
-		    <textobject>
-			<phrase>Message flow showing transactions belonging to the same dialog.</phrase>
-		    </textobject>
-		</mediaobject>
-	    </figure>
-	    <simpara>
-		Some messages establish a dialog and some do not. This allows to explicitly express
-		the relationship of messages and also to send messages that are not related to other
-		messages outside a dialog. That is easier to implement because user agent don't have
-		to keep the dialog state.
-	    </simpara>
-	    <simpara>
-		For instance, INVITE message establishes a dialog, because it will be later followed
-		by BYE request which will tear down the session established by the INVITE. This BYE
-		is sent within the dialog established by the INVITE.
-	    </simpara>
-	    <simpara>
-		But if a user agent sends a MESSAGE request, such a request doesn't establish any
-		dialog. Any subsequent messages (even MESSAGE) will be sent independently of the
-		previous one.
-	    </simpara>
-	    <section id="sec-dialogs-facilitate-routing">
-		<title>Dialogs Facilitate Routing</title>
-		<simpara>
-		    We have said that dialogs are also used to route the messages between user
-		    agents, let's describe this a little bit.
-		</simpara>
-		<simpara>
-		    Let's suppose that user sip:[email protected] wants to talk to user sip:[email protected]. He
-		    knows &sip; address of the callee (sip:[email protected]) but this address doesn't say
-		    anything about current location of the user--i.e. the caller doesn't know to
-		    which host to send the request. Therefore the INVITE request will be sent to a
-		    proxy server.
-		</simpara>
-		<simpara>
-		    The request will be sent from proxy to proxy until it reaches one that knows
-		    current location of the callee. This process is called routing. Once the request
-		    reaches the callee, the callee's user agent will create a response that will be
-		    sent back to the caller. Callee's user agent will also put Contact header field
-		    into the response which will contain the current location of the user. The
-		    original request also contained Contact header field which means that both user
-		    agents know the current location of the peer.
-		</simpara>
-		<simpara>
-		    Because the user agents know location of each other, it is not necessary to send
-		    further requests to any proxy--they can be sent directly from user agent to user
-		    agent. That's exactly how dialogs facilitate routing.
-		</simpara>
-		<simpara>
-		    Further messages within a dialog are sent directly from user agent to user
-		    agent. This is a significant performance improvement because proxies do not see
-		    all the messages within a dialog, they are used to route just the first request
-		    that establishes the dialog. The direct messages are also delivered with much
-		    smaller latency because a typical proxy usually implements complex routing
-		    logic. <xref linkend="fig-trapezoid"> contains an example of a message
-		    within a dialog (BYE) that bypasses the proxies.
-		</simpara>
-		<figure id="fig-trapezoid" float="0">
-		    <title>&sip; Trapezoid</title>
-		    <mediaobject>
-			<imageobject>
-			    <imagedata align="center" scale="40" fileref="figures/trapezoid.eps" format="EPS">
-			</imageobject>
-			<imageobject>
-			    <imagedata align="center" fileref="figures/trapezoid.png" format="PNG">
-			</imageobject>
-			<textobject>
-			    <phrase>Message flow showing &sip; trapezoid.</phrase>
-			</textobject>
-		    </mediaobject>
-		</figure>
-	    </section>
-	    <section id="sec-dialog-identifiers">
-		<title>Dialog Identifiers</title>
-		<simpara>
-		    We have already shown that dialog identifiers consist of three parts, Call-Id,
-		    From tag, and To tag, but it is not that clear why are dialog identifiers
-		    created exactly this way and who contributes which part.
-		</simpara>
-		<simpara>
-		    Call-ID is so called <emphasis>call identifier</emphasis>. It must be a unique
-		    string that identifies a call. A call consists of one or more dialogs. Multiple
-		    user agents may respond to a request when a proxy along the path forks the
-		    request. Each user agent that sends a 2xx establishes a separate dialog with the
-		    caller. All such dialogs are part of the same call and have the same Call-ID.
-		</simpara>
-		<simpara>
-		    From tag is generated by the caller and it uniquely identifies the dialog in the
-		    caller's user agent.
-		</simpara>
-		<simpara>
-		    To tag is generated by a callee and it uniquely identifies, just like From tag,
-		    the dialog in the callee's user agent.
-		</simpara>
-		<simpara>
-		    This hierarchical dialog identifier is necessary because a single call
-		    invitation can create several dialogs and caller must be able to distinguish
-		    them.
-		</simpara>
-	    </section>
-	</section>
-	<section id="sec-typical-sip-scenarios">
-	    <title>Typical &sip; Scenarios</title>
-	    <simpara>
-		This section gives a brief overview of typical &sip; scenarios that usually make up the
-		&sip; traffic.
-	    </simpara>
-	    <section id="sec-registration">
-		<title>Registration</title>
-		<simpara>
-		    Users must register themselves with a registrar to be reachable by other
-		    users. A registration comprises a REGISTER message followed by a 200 OK sent by
-		    registrar if the registration was successful. Registrations are usually
-		    authorized so a 407 reply can appear if the user didn't provide valid
-		    credentials. <xref linkend="fig-register"> shows an example of registration.
-		</simpara>
-		<figure id="fig-register" float="0">
-		    <title>REGISTER Message Flow</title>
-		    <mediaobject>
-			<imageobject>
-			    <imagedata align="center" scale="40" fileref="figures/register.eps" format="EPS">
-			</imageobject>
-			<imageobject>
-			    <imagedata align="center" fileref="figures/register.png" format="PNG">
-			</imageobject>
-			<textobject>
-			    <phrase>Message flow of a registration.</phrase>
-			</textobject>
-		    </mediaobject>
-		</figure>
-	    </section>
-	    <section id="sec-session-invitation">
-		<title>Session Invitation</title>
-		<simpara>
-		    A session invitation consists of one INVITE request which is usually sent to a
-		    proxy. The proxy sends immediately a 100 Trying reply to stop retransmissions
-		    and forwards the request further.
-		</simpara>
-		<simpara>
-		    All provisional responses generated by callee are sent back to the caller. See
-		    180 Ringing response in the call flow. The response is generated when callee's
-		    phone starts ringing.
-		</simpara>
-		<figure id="fig-invite1" float="0">
-		    <title>INVITE Message Flow</title>
-		    <mediaobject>
-			<imageobject>
-			    <imagedata align="center" scale="40" fileref="figures/invite1.eps" format="EPS">
-			</imageobject>
-			<imageobject>
-			    <imagedata align="center" fileref="figures/invite1.png" format="PNG">
-			</imageobject>
-			<textobject>
-			    <phrase>Picture showing a session invitation.</phrase>
-			</textobject>
-		    </mediaobject>
-		</figure>
-		<simpara>
-		    A 200 OK is generated once the callee picks up the phone and it is retransmitted
-		    by the callee's user agent until it receives an ACK from the caller. The session
-		    is established at this point.
-		</simpara>
-	    </section>
-	    <section id="sec-session-termination">
-		<title>Session Termination</title>
-		<simpara>
-		    Session termination is accomplished by sending a BYE request within dialog
-		    established bye INVITE. BYE messages are sent directly from one user agent to
-		    the other unless a proxy on the path of the INVITE request indicated that it
-		    wishes to stay on the path by using record routing (see <xref
-		    linkend="sec-record-routing">.
-		</simpara>
-		<simpara>
-		    Party wishing to tear down a session sends a BYE request to the other party
-		    involved in the session. The other party sends a 200 OK response to confirm the
-		    BYE and the session is terminated. See <xref linkend="fig-bye">, left message
-		    flow.
-		</simpara>
-	    </section>
-	    <section id="sec-record-routing">
-		<title>Record Routing</title>
-		<simpara>
-		    All requests sent within a dialog are by default sent directly from one user agent
-		    to the other. Only requests outside a dialog traverse &sip; proxies. This approach
-		    makes &sip; network more scalable because only a small number of &sip; messages hit
-		    the proxies.
-		</simpara>
-		<simpara>
-		    There are certain situations in which a &sip; proxy need to stay on the path of all
-		    further messages. For instance, proxies controlling a &nat; box or proxies doing
-		    accounting need to stay on the path of BYE requests.
-		</simpara>
-		<simpara>
-		    Mechanism by which a proxy can inform user agents that it wishes to stay on the path
-		    of all further messages is called <emphasis>record routing</emphasis>. Such a proxy
-		    would insert Record-Route header field into &sip; messages which contain address of
-		    the proxy. Messages sent within a dialog will then traverse all &sip; proxies that
-		    put a Record-Route header field into the message.
-		</simpara>
-		<simpara>
-		    The recipient of the request receives a set of Record-Route header fields in the
-		    message. It must mirror all the Record-Route header fields into responses because
-		    the originator of the request also needs to know the set of proxies.
-		</simpara>
-		<figure id="fig-bye" float="0">
-		    <title>BYE Message Flow (With and without Record Routing)</title>
-		    <mediaobject>
-			<imageobject>
-			    <imagedata align="center" scale="40" fileref="figures/bye.eps" format="EPS">
-			</imageobject>
-			<imageobject>
-			    <imagedata align="center" fileref="figures/bye.png" format="PNG">
-			</imageobject>
-			<textobject>
-			    <phrase>Picture showing BYE message flow with and without record routing.</phrase>
-			</textobject>
-		    </mediaobject>
-		</figure>
-		<simpara>
-		    Left message flow of <xref linkend="fig-bye"> show how a BYE (request
-		    within dialog established by INVITE) is sent directly to the other user agent
-		    when there is no Record-Route header field in the message. Right message flow
-		    show how the situation changes when the proxy puts a Record-Route header field
-		    into the message.
-		</simpara>
-		<section>
-		    <title>Strict versus Loose Routing</title>
-		    <simpara>
-			The way how record routing works has evolved. Record routing according to
-			&rfc2643; rewrote the Request-URI. That means the Request-URI always
-			contained &uri; of the next hop (which can be either next proxy server which
-			inserted Record-Route header field or destination user agent). Because of
-			that it was necessary to save the original Request-URI as the last Route
-			header field. This approach is called <emphasis>strict routing</emphasis>.
-		    </simpara>
-		    <simpara>
-			<emphasis>Loose routing</emphasis>, as specified in &rfc3261;, works in a
-			little bit different way. The Request-URI is no more overwritten, it always
-			contains &uri; of the destination user agent. If there are any Route header
-			field in a message, than the message is sent to the &uri; from the topmost
-			Route header field. This is significant change--Request-URI doesn't
-			necessarily contain &uri to which the request will be sent. In fact, loose
-			routing is very similar to IP source routing.
-		    </simpara>
-		    <simpara>
-			Because transit from strict routing to loose routing would break backwards
-			compatibility and older user agents wouldn't work, it is necessary to make
-			loose routing backwards compatible. The backwards compatibility
-			unfortunately adds a lot of overhead and is often source of major problems.
-		    </simpara>
-		</section>
-	    </section>
-	    <section id="sec-event-subscription-and-notification">
-		<title>Event Subscription And Notification</title>
-		<simpara>
-		    The &sip; specification has been extended to support a general mechanism allowing
-		    subscription to asynchronous events. Such evens can include &sip; proxy statistics
-		    changes, presence information, session changes and so on.
-		</simpara>
-		<simpara>
-		    The mechanism is used mainly to convey information on presence (willingness to
-		    communicate) of users. <xref linkend="fig-event"> shows the basic message
-		    flow.
-		</simpara>
-		<figure id="fig-event" float="0">
-		    <title>Event Subscription And Notification</title>
-		    <mediaobject>
-			<imageobject>
-			    <imagedata align="center" scale="40" fileref="figures/event.eps" format="EPS">
-			</imageobject>
-			<imageobject>
-			    <imagedata align="center" fileref="figures/event.png" format="PNG">
-			</imageobject>
-			<textobject>
-			    <phrase>Picture showing subscription and notification.</phrase>
-			</textobject>
-		    </mediaobject>
-		</figure>
-		<simpara>
-		    A user agent interested in event notification sends a SUBSCRIBE message to a
-		    &sip; server. The SUBSCRIBE message establishes a dialog and is immediately
-		    replied by the server using 200 OK response. At this point the dialog is
-		    established. The server sends a NOTIFY request to the user every time the event
-		    to which the user subscribed changes. NOTIFY messages are sent within the dialog
-		    established by the SUBSCRIBE.
-		</simpara>
-		<simpara>
-		    Note that the first NOTIFY message in <xref linkend="fig-event"> is sent
-			regardless of any event that triggers notifications.
-		</simpara>
-		<simpara>
-		    Subscriptions--as well as registrations--have limited lifespan and therefore must be
-		    periodically refreshed.
-		</simpara>
-	    </section>
-	    <section id="sec-instant-messages">
-		<title>Instant Messages</title>
-		<simpara>
-		    Instant messages are sent using MESSAGE request. MESSAGE requests do not establish a
-		    dialog and therefore they will always traverse the same set of proxies. This is the
-		    simplest form of sending instant messages. The text of the instant message is
-		    transported in the body of the &sip; request.
-		</simpara>
-		<figure id="fig-message" float="0">
-		    <title>Instant Messages</title>
-		    <mediaobject>
-			<imageobject>
-			    <imagedata align="center" scale="40" fileref="figures/message.eps" format="EPS">
-			</imageobject>
-			<imageobject>
-			    <imagedata align="center" fileref="figures/message.png" format="PNG">
-			</imageobject>
-			<textobject>
-			    <phrase>Picture showing a MESSAGE.</phrase>
-			</textobject>
-		    </mediaobject>
-		</figure>
-	    </section>
-	</section>
-    </chapter>
-</book>

doc/sip/sip_introduction.xml

@@ -0,0 +1,1014 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4//EN"
+                      "file:///usr/share/sgml/docbook/dtd/xml/4/docbookx.dtd">
+
+<section id="sip_intro" xmlns:xi="http://www.w3.org/2001/XInclude">
+    <sectioninfo>
+	<authorgroup>
+	    <author>
+		<firstname>Jan</firstname>
+		<surname>Janak</surname>
+		<email>[email protected]</email>
+	    </author>
+	</authorgroup>
+	<copyright>
+	    <year>2003</year>
+	    <holder>FhG FOKUS</holder>
+	</copyright>
+	<abstract>
+	    <para>
+		A brief overview of SIP describing all important aspects of the Session Initiation
+		Protocol.
+	    </para>
+	</abstract>
+    </sectioninfo>
+
+    <title>SIP Introduction</title>
+    <section id="purpose">
+	<title>Purpose of SIP</title>
+	<simpara>
+	    SIP stands for Session Initiation Protocol. It is an application-layer control
+	    protocol which has been developed and designed within the IETF. The protocol has
+	    been designed with easy implementation, good scalability, and flexibility in mind.
+	</simpara>
+	<simpara>
+	    The specification is available in form of several <abbrev>RFCs</abbrev>, the most
+	    important one is RFC3261 which contains the core protocol specification. The
+	    protocol is used for creating, modifying, and terminating sessions with one or more
+	    participants. By sessions we understand a set of senders and receivers that
+	    communicate and the state kept in those senders and receivers during the
+	    communication. Examples of a session can include Internet telephone calls,
+	    distribution of multimedia, multimedia conferences, distributed computer games, etc.
+	</simpara>
+	<simpara>
+	    SIP is not the only protocol that the communicating devices will need. It is not
+	    meant to be a general purpose protocol. Purpose of SIP is just to make the
+	    communication possible, the communication itself must be achieved by another means
+	    (and possibly another protocol). Two protocols that are most often used along with
+	    SIP are RTP and SDP. RTP protocol is used to carry the real-time multimedia
+	    data (including audio, video, and text), the protocol makes it possible to encode
+	    and split the data into packets and transport such packets over the
+	    Internet. Another important protocol is SDP, which is used to describe and encode
+	    capabilities of session participants. Such a description is then used to negotiate
+	    the characteristics of the session so that all the devices can participate (that
+	    includes, for example, negotiation of codecs used to encode media so all the
+	    participants will be able to decode it, negotiation of transport protocol used and
+	    so on).
+	</simpara>
+	<simpara>
+	    SIP has been designed in conformance with the Internet model. It is an end-to-end
+	    oriented signaling protocol which means, that all the logic is stored in end
+	    devices (except routing of SIP messages). State is also stored in end-devices
+	    only, there is no single point of failure and networks designed this way scale
+	    well. The price that we have to pay for the distributiveness and scalability is
+	    higher message overhead, caused by the messages being sent end-to-end.
+	</simpara>
+	<simpara>
+	    It is worth of mentioning that the end-to-end concept of SIP is a significant
+	    divergence from regular PSTN (Public Switched Telephone Network) where all the
+	    state and logic is stored in the network and end devices (telephones) are very
+	    primitive. Aim of SIP is to provide the same functionality that the traditional
+	    PSTNs have, but the end-to-end design makes SIP networks much more powerful and
+	    open to the implementation of new services that can be hardly implemented in the
+	    traditional PSTNs.
+	</simpara>
+	<simpara>
+	    SIP is based on HTTP protocol. The HTTP protocol inherited format of message
+	    headers from RFC822. HTTP is probably the most successful and widely used
+	    protocol in the Internet. It tries to combine the best of the both. In fact, HTTP
+	    can be classified as a signaling protocol too, because user agents use the protocol
+	    to tell a HTTP server in which documents they are interested in. SIP is used to
+	    carry the description of session parameters, the description is encoded into a
+	    document using SDP. Both protocols (HTTP and SIP) have inherited encoding of
+	    message headers from RFC822. The encoding has proven to be robust and flexible
+	    over the years.
+	</simpara>
+    </section>
+    <section id="sip_uri">
+	<title>SIP URI</title>
+	<simpara>
+	    SIP entities are identified using SIP URI (Uniform Resource Identifier). A
+	    SIP URI has form of sip:username@domain, for instance,
+	    sip:[email protected]. As we can see, SIP URI consists of username part and
+	    domain name part delimited by @ (at) character. SIP URIs are similar to
+	    e-mail addresses, it is, for instance, possible to use the same URI for e-mail
+	    and SIP communication, such URIs are easy to remember.
+	</simpara>
+    </section>
+    <section id="sip_network_elements">
+	<title>SIP Network Elements</title>
+	<simpara>
+	    Although in the simplest configuration it is possible to use just two user agents
+	    that send SIP messages directly to each other, a typical SIP network will
+	    contain more than one type of SIP elements. Basic SIP elements are user agents,
+	    proxies, registrars, and redirect servers. We will briefly describe them in this
+	    section.
+	</simpara>
+	<simpara>
+	    Note that the elements, as presented in this section, are often only logical
+	    entities. It is often profitable to co-locate them together, for instance, to
+	    increase the speed of processing, but that depends on a particular implementation
+	    and configuration.
+	</simpara>
+	<section id="user_agents">
+	    <title>User Agents</title>
+	    <simpara>
+		Internet end points that use SIP to find each other and to negotiate a session
+		characteristics are called <emphasis>user agents</emphasis>. User agents
+		usually, but not necessarily, reside on a user's computer in form of an
+		application--this is currently the most widely used approach, but user agents
+		can be also cellular phones, PSTN gateways, <acronym>PDAs</acronym>, automated
+		<acronym>IVR</acronym> systems and so on.
+	    </simpara>
+	    <simpara>
+		User agents are often referred to as <emphasis>User Agent Server</emphasis>
+		(UAS) and <emphasis>User Agent Client</emphasis> (UAC). UAS and UAC are
+		logical entities only, each user agent contains a UAC and UAS. UAC is the
+		part of the user agent that sends requests and receives responses. UAS is the
+		part of the user agent that receives requests and sends responses.
+	    </simpara>
+	    <simpara>
+		Because a user agent contains both UAC and UAS, we often say that a user
+		agent behaves like a UAC or UAS. For instance, caller's user agent behaves
+		like UAC when it sends an INVITE requests and receives responses to the
+		request. Callee's user agent behaves like a UAS when it receives the INVITE
+		and sends responses.
+	    </simpara>
+	    <simpara>
+		But this situation changes when the callee decides to send a BYE and terminate
+		the session. In this case the callee's user agent (sending BYE) behaves like
+		UAC and the caller's user agent behaves like UAS.
+	    </simpara>
+	    <figure id="uac_and_uas">
+		<title>UAC and UAS</title>		    
+		<mediaobject>
+		    <imageobject>
+			<imagedata fileref="figures/ua.png" format="PNG"/>
+		    </imageobject>
+		    <textobject>
+			<phrase>Picture showing UAC and UAS</phrase>
+		    </textobject>
+		</mediaobject>
+	    </figure>
+	    <simpara>
+		<xref linkend="uac_and_uas"/> shows three user agents and one stateful forking
+		    proxy. Each user agent contains UAC and UAS. The part of the proxy that
+		    receives the INVITE from the caller in fact acts as a UAS. When forwarding the
+		    request statefully the proxy creates two UACs, each of them is responsible for
+		    one branch.
+	    </simpara>
+	    <simpara>
+		In our example callee B picked up and later when he wants to tear down the call
+		it sends a BYE. At this time the user agent that was previously UAS becomes a
+		UAC and vice versa.
+	    </simpara>
+	</section>
+	<section id="proxy_servers">
+	    <title>Proxy Servers</title>
+	    <simpara>
+		In addition to that SIP allows creation of an infrastructure of network hosts
+		called <emphasis>proxy servers</emphasis>. User agents can send messages to a
+		proxy server. Proxy servers are very important entities in the SIP
+		infrastructure. They perform routing of a session invitations according to
+		invitee's current location, authentication, accounting and many other important
+		functions.
+	    </simpara>
+	    <simpara>
+		The most important task of a proxy server is to route session invitations
+		"closer" to callee. The session invitation will usually traverse a
+		set of proxies until it finds one which knows the actual location of the
+		callee. Such a proxy will forward the session invitation directly to the callee
+		and the callee will then accept or decline the session invitation.
+	    </simpara>
+	    <simpara>
+		There are two basic types of SIP proxy servers--stateless and stateful.
+	    </simpara>
+
+	    <section id="stateless_servers">
+		<title>Stateless Servers</title>
+		<simpara>
+		    Stateless server are simple message forwarders. They forward messages
+		    independently of each other. Although messages are usually arranged into
+		    transactions (see <xref linkend="sip_transactions"/>), stateless proxies
+			do not take care of transactions.
+		</simpara>
+		<simpara>
+		    Stateless proxies are simple, but faster than stateful proxy servers. They
+		    can be used as simple load balancers, message translators and routers. One
+		    of drawbacks of stateless proxies is that they are unable to absorb
+		    retransmissions of messages and perform more advanced routing, for instance,
+		    forking or recursive traversal.
+		</simpara>
+	    </section>
+	    <section id="stateful_servers">
+		<title>Stateful Servers</title>
+		<simpara>
+		    Stateful proxies are more complex. Upon reception of a request, stateful
+		    proxies create a state and keep the state until the transaction
+		    finishes. Some transactions, especially those created by INVITE, can last
+		    quite long (until callee picks up or declines the call). Because stateful
+		    proxies must maintain the state for the duration of the transactions, their
+		    performance is limited.
+		</simpara>
+		<simpara>
+		    The ability to associate SIP messages into transactions gives stateful
+		    proxies some interesting features. Stateful proxies can perform forking,
+		    that means upon reception of a message two or more messages will be sent
+		    out.
+		</simpara>
+		<simpara>
+		    Stateful proxies can absorb retransmissions because they know, from the
+		    transaction state, if they have already received the same message (stateless
+		    proxies cannot do the check because they keep no state).
+		</simpara>
+		<simpara>
+		    Stateful proxies can perform more complicated methods of finding a user. It
+		    is, for instance, possible to try to reach user's office phone and when he
+		    doesn't pick up then the call is redirected to his cell phone. Stateless
+		    proxies can't do this because they have no way of knowing how the
+		    transaction targeted to the office phone finished.
+		</simpara>
+		<simpara>
+		    Most SIP proxies today are stateful because their configuration is usually
+		    very complex. They often perform accounting, forking, some sort of NAT
+		    traversal aid and all those features require a stateful proxy.
+		</simpara>
+	    </section>
+	    <section id="proxy_server_usage">
+		<title>Proxy Server Usage</title>
+		<simpara>
+		    A typical configuration is that each centrally administered entity (a
+		    company, for instance) has it's own SIP proxy server which is used by all
+		    user agents in the entity. Let's suppose that there are two companies A and
+		    B and each of them has it's own proxy server. <xref linkend="companies"/>
+			shows how a session invitation from employee Joe in company A will reach
+			employee Bob in company B.
+		</simpara>
+		<figure id="companies">
+		    <title>Session Invitation</title>
+		    <mediaobject>
+			<imageobject>
+			    <imagedata fileref="figures/companies.png" format="PNG"/>
+			</imageobject>
+			<textobject>
+			    <phrase>Picture showing a session invitation message flow</phrase>
+			</textobject>
+		    </mediaobject> 
+		</figure>
+		<simpara>
+		    User Joe uses address sip:[email protected] to call Bob. Joe's user agent doesn't
+		    know how to route the invitation itself but it is configured to send all
+		    outbound traffic to the company SIP proxy server proxy.a.com. The proxy
+		    server figures out that user sip:[email protected] is in a different company so it
+		    will look up B's SIP proxy server and send the invitation there. B's proxy
+		    server can be either pre-configured at proxy.a.com or the proxy will use
+		    <acronym>DNS SRV</acronym> records to find B's proxy server. The invitation
+		    reaches proxy.bo.com. The proxy knows that Bob is currently sitting in his
+		    office and is reachable through phone on his desk, which has IP address
+		    1.2.3.4, so the proxy will send the invitation there.
+		</simpara>
+	    </section>
+	</section>
+	<section id="registrar">
+	    <title>Registrar</title>
+	    <simpara>
+		We mentioned that the SIP proxy at proxy.b.com knows current Bob's location
+		but haven't mentioned yet how a proxy can learn current location of a
+		user. Bob's user agent (SIP phone) must register with a
+		<emphasis>registrar</emphasis>. The registrar is a special SIP entity that
+		receives registrations from users, extracts information about their current
+		location (IP address, port and username in this case) and stores the
+		information into location database. Purpose of the location database is to map
+		sip:[email protected] to something like sip:[email protected]:5060. The location database is
+		then used by B's proxy server. When the proxy receives an invitation for
+		sip:[email protected] it will search the location database. It finds
+		sip:[email protected]:5060 and will send the invitation there. A registrar is very
+		often a logical entity only. Because of their tight coupling with proxies
+		registrars, are usually co-located with proxy servers.
+	    </simpara>
+	    <simpara>
+		<xref linkend="registrar_fig"/> shows a typical SIP registration. A REGISTER
+		    message containing Address of Record sip:[email protected] and contact address
+		    sip:[email protected]:5060 where 1.2.3.4 is IP address of the phone, is sent to the
+		    registrar. The registrar extracts this information and stores it into the
+		    location database. If everything went well then the registrar sends a 200 OK
+		    response to the phone and the process of registration is finished.
+	    </simpara>
+	    <figure id="registrar_fig">
+		<title>Registrar Overview</title>
+		<mediaobject>
+		    <imageobject>
+			<imagedata fileref="figures/registrar.png" format="PNG"/>
+		    </imageobject>
+		    <textobject>
+			<phrase>Picture showing a typical registrar</phrase>
+		    </textobject>
+		</mediaobject> 
+	    </figure>
+	    <simpara>
+		Each registration has a limited lifespan. Expires header field or expires
+		parameter of Contact header field determines for how long is the registration
+		valid. The user agent must refresh the registration within the lifespan
+		otherwise it will expire and the user will become unavailable.
+	    </simpara>
+	</section>
+	<section id="redirect_server">
+	    <title>Redirect Server</title>
+	    <simpara>
+		The entity that receives a request and sends back a reply containing a list of the
+		current location of a particular user is called <emphasis>redirect server</emphasis>. A
+		redirect server receives requests and looks up the intended recipient of the request in
+		the location database created by a registrar. It then creates a list of current
+		locations of the user and sends it to the request originator in a response within 3xx
+		class.
+	    </simpara>
+	    <simpara>
+		The originator of the request then extracts the list of destinations and sends
+		another request directly to them. <xref linkend="redirect"/> shows a typical
+		    redirection.
+	    </simpara>
+	    <figure id="redirect">
+		<title>SIP Redirection</title>
+		<mediaobject>
+		    <imageobject>
+			<imagedata fileref="figures/redirect.png" format="PNG"/>
+		    </imageobject>
+		    <textobject>
+			<phrase>Picture showing a redirection</phrase>
+		    </textobject>
+		</mediaobject> 
+	    </figure>
+	</section>
+    </section>
+    <section id="sip_messages">
+	<title>SIP Messages</title>
+	<simpara>
+	    Communication using SIP (often called signaling) comprises of series of
+	    <emphasis>messages</emphasis>. Messages can be transported independently by the
+	    network. Usually they are transported in a separate UDP datagram each. Each
+	    message consist of "first line", message header, and message body. The
+	    first line identifies type of the message. There are two types of
+	    messages--<emphasis>requests</emphasis> and <emphasis>responses</emphasis>.
+	    Requests are usually used to initiate some action or inform recipient of the request
+	    of something. Replies are used to confirm that a request was received and processed
+	    and contain the status of the processing.
+	</simpara>
+	<simpara>
+	    A typical SIP request looks like this:
+	</simpara>
+	<programlisting>
+<![CDATA[
+INVITE sip:[email protected] SIP/2.0
+Via: SIP/2.0/UDP 195.37.77.100:5040;rport
+Max-Forwards: 10
+From: "jiri" <sip:[email protected]>;tag=76ff7a07-c091-4192-84a0-d56e91fe104f
+To: <sip:[email protected]>
+Call-ID: [email protected]
+CSeq: 2 INVITE
+Contact: <sip:213.20.128.35:9315>
+User-Agent: Windows RTC/1.0
+Proxy-Authorization: Digest username="jiri", realm="iptel.org", 
+ algorithm="MD5", uri="sip:[email protected]", 
+ nonce="3cef753900000001771328f5ae1b8b7f0d742da1feb5753c", 
+ response="53fe98db10e1074
+ b03b3e06438bda70f"
+Content-Type: application/sdp
+Content-Length: 451
+
+v=0
+o=jku2 0 0 IN IP4 213.20.128.35
+s=session
+c=IN IP4 213.20.128.35
+b=CT:1000
+t=0 0
+m=audio 54742 RTP/AVP 97 111 112 6 0 8 4 5 3 101
+a=rtpmap:97 red/8000
+a=rtpmap:111 SIREN/16000
+a=fmtp:111 bitrate=16000
+a=rtpmap:112 G7221/16000
+a=fmtp:112 bitrate=24000
+a=rtpmap:6 DVI4/16000
+a=rtpmap:0 PCMU/8000
+a=rtpmap:4 G723/8000
+a=rtpmap: 3 GSM/8000
+a=rtpmap:101 telephone-event/8000
+a=fmtp:101 0-16
+]]>
+	</programlisting>
+	<simpara>
+	    The first line tells us that this is INVITE message which is used to establish a
+	    session. The URI on the first line--sip:[email protected] is called <emphasis>Request
+		URI</emphasis> and contains URI of the next hop of the message. In this case it
+	    will be host iptel.org.
+	</simpara>
+	<simpara>
+	    A SIP request can contain one or more Via header fields which are used to record
+	    path of the request. They are later used to route SIP responses exactly the same
+	    way. The INVITE message contains just one Via header field which was created by the
+	    user agent that sent the request. From the Via field we can tell that the user agent
+	    is running on host 195.37.77.100 and port 5060.
+	</simpara>
+	<simpara>
+	    From and To header fields identify initiator (caller) and recipient (callee) of the
+	    invitation (just like in SMTP where they identify sender and recipient of a
+	    message). From header field contains a tag parameter which serves as a dialog
+	    identifier and will be described in <xref linkend="sip_dialogs"/>.
+	</simpara>
+	<simpara>
+	    Call-ID header field is a dialog identifier and it's purpose is to identify messages
+	    belonging to the same call. Such messages have the same Call-ID identifier. CSeq is
+	    used to maintain order of requests. Because requests can be sent over an unreliable
+	    transport that can re-order messages, a sequence number must be present in the
+	    messages so that recipient can identify retransmissions and out of order requests.
+	</simpara>
+	<simpara>
+	    Contact header field contains IP address and port on which the sender is awaiting
+	    further requests sent by callee. Other header fields are not important and will be
+	    not described here.
+	</simpara>
+	<simpara>
+	    Message header is delimited from message body by an empty line. Message body of the INVITE
+	    request contains a description of the media type accepted by the sender and encoded in
+	    SDP.
+	</simpara>
+	<section id="sip_requests">
+	    <title>SIP Requests</title>
+	    <simpara>
+		We have described how an INVITE request looks like and said that the request is
+		used to invite a callee to a session. Other important requests are:
+	    </simpara>
+	    <itemizedlist>
+		<listitem>
+		    <simpara>
+			<emphasis>ACK</emphasis>--This message acknowledges receipt of a final
+			response to INVITE. Establishing of a session utilizes 3-way
+			hand-shaking due to asymmetric nature of the invitation. It may take a
+			while before the callee accepts or declines the call so the callee's
+			user agent periodically retransmits a positive final response until it
+			receives an ACK (which indicates that the caller is still there and
+			ready to communicate).
+		    </simpara>
+		</listitem>
+		<listitem>
+		    <simpara>
+			<emphasis>BYE</emphasis>--Bye messages are used to tear down multimedia
+			sessions. A party wishing to tear down a session sends a BYE to the
+			other party.
+		    </simpara>
+		</listitem>
+		<listitem>
+		    <simpara>
+			<emphasis>CANCEL</emphasis>--Cancel is used to cancel not yet fully
+			established session. It is used when the callee hasn't replied with a
+			final response yet but the caller wants to abort the call (typically
+			when a callee doesn't respond for some time).
+		    </simpara>
+		</listitem>
+		<listitem>
+		    <simpara>
+			<emphasis>REGISTER</emphasis>--Purpose of REGISTER request is to let
+			registrar know of current user's location. Information about current
+			IP address and port on which a user can be reached is carried in
+			REGISTER messages. Registrar extracts this information and puts it into
+			a location database. The database can be later used by SIP proxy
+			servers to route calls to the user. Registrations are time-limited and
+			need to be periodically refreshed.
+		    </simpara>
+		</listitem>
+	    </itemizedlist>
+	    <simpara>
+		The listed requests usually have no message body because it is not needed in
+		most situations (but can have one). In addition to that many other request types
+		have been defined but their description is out of the scope of this document.
+	    </simpara>
+	</section>
+	<section id="sip_responses">
+	    <title>SIP Responses</title>
+	    <simpara>
+		When a user agent or proxy server receives a request it send a reply. Each
+		request must be replied except ACK requests which trigger no replies.
+	    </simpara>
+	    <simpara>
+		A typical reply looks like this:
+	    </simpara>
+	    <programlisting>
+<![CDATA[
+SIP/2.0 200 OK
+Via: SIP/2.0/UDP 192.168.1.30:5060;received=66.87.48.68
+From: sip:[email protected]
+To: sip:[email protected];tag=794fe65c16edfdf45da4fc39a5d2867c.b713
+Call-ID: [email protected]
+CSeq: 63629 REGISTER
+Contact: Msip:[email protected]:5060;transport=udp>;q=0.00;expires=120
+Server: Sip EXpress router (0.8.11pre21xrc (i386/linux))
+Content-Length: 0
+Warning: 392 195.37.77.101:5060 "Noisy feedback tells:  
+  pid=5110 req_src_ip=66.87.48.68 req_src_port=5060 in_uri=sip:iptel.org 
+  out_uri=sip:iptel.org via_cnt==1"
+]]>
+	    </programlisting>
+	    <simpara>
+		As we can see, responses are very similar to the requests, except for the first
+		line. The first line of response contains protocol version (SIP/2.0), reply
+		code, and reason phrase.
+	    </simpara>
+	    <simpara>
+		The <emphasis>reply code</emphasis> is an integer number from 100 to 699 and
+		indicates type of the response. There are 6 classes of responses:
+	    </simpara>
+	    <itemizedlist>
+		<listitem>
+		    <simpara>
+			<emphasis>1xx</emphasis> are <emphasis>provisional</emphasis>
+			responses. A provisional response is response that tells to its
+			recipient that the associated request was received but result of the
+			processing is not known yet. Provisional responses are sent only when
+			the processing doesn't finish immediately. The sender must stop
+			retransmitting the request upon reception of a provisional response.
+		    </simpara>
+		    <simpara>
+			Typically proxy servers send responses with code 100 when they start
+			processing an INVITE and user agents send responses with code 180
+			(Ringing) which means that the callee's phone is ringing.
+		    </simpara>
+		</listitem>
+		<listitem>
+		    <simpara>
+			<emphasis>2xx</emphasis> responses are <emphasis>positive
+			    final</emphasis> responses. A final response is the ultimate response
+			that the originator of the request will ever receive. Therefore final
+			responses express result of the processing of the associated
+			request. Final responses also terminate transactions. Responses with
+			code from 200 to 299 are positive responses that means that the request
+			was processed successfully and accepted. For instance a 200 OK response
+			is sent when a user accepts invitation to a session (INVITE request).
+		    </simpara>
+		    <simpara>
+			A UAC may receive several 200 messages to a single INVITE
+			request. This is because a forking proxy (described later) can fork the
+			request so it will reach several UAS and each of them will accept the
+			invitation. In this case each response is distinguished by the tag
+			parameter in To header field. Each response represents a distinct dialog
+			with unambiguous dialog identifier.
+		    </simpara>
+		</listitem>
+		<listitem>
+		    <simpara>
+			<emphasis>3xx</emphasis> responses are used to redirect a caller. A
+			redirection response gives information about the user's new location or
+			an alternative service that the caller might use to satisfy the
+			call. Redirection responses are usually sent by proxy servers. When a
+			proxy receives a request and doesn't want or can't process it for any
+			reason, it will send a redirection response to the caller and put
+			another location into the response which the caller might want to
+			try. It can be the location of another proxy or the current location of
+			the callee (from the location database created by a registrar). The
+			caller is then supposed to re-send the request to the new location. 3xx
+			responses are final.
+		    </simpara>
+		</listitem>
+		<listitem>
+		    <simpara>
+			<emphasis>4xx</emphasis> are <emphasis>negative final</emphasis>
+			responses. a 4xx response means that the problem is on the sender's
+			side. The request couldn't be processed because it contains bad syntax
+			or cannot be fulfilled at that server.
+		    </simpara>
+		</listitem>
+		<listitem>
+		    <simpara>
+			<emphasis>5xx</emphasis> means that the problem is on server's side. The
+			request is apparently valid but the server failed to fulfill it. Clients
+			should usually retry the request later.
+		    </simpara>
+		</listitem>
+		<listitem>
+		    <simpara>
+			<emphasis>6xx</emphasis> reply code means that the request cannot be
+			fulfilled at any server. This response is usually sent by a server that
+			has definitive information about a particular user. User agents usually
+			send a 603 Decline response when the user doesn't want to participate in
+			the session.
+		    </simpara>
+		</listitem>
+	    </itemizedlist>
+	    <simpara>
+		In addition to the response class the first line also contains <emphasis>reason
+		    phrase</emphasis>. The code number is intended to be processed by
+		machines. It is not very human-friendly but it is very easy to parse and
+		understand by machines. The reason phrase usually contains a human-readable
+		message describing the result of the processing. A user agent should render
+		the reason phrase to the user.
+	    </simpara>
+	    <simpara>
+		The request to which a particular response belongs is identified using the CSeq
+		header field. In addition to the sequence number this header field also contains
+		method of corresponding request. In our example it was REGISTER request.
+	    </simpara>
+	</section>
+    </section> 
+    <section id="sip_transactions">
+	<title>SIP Transactions</title>
+	<simpara>
+	    Although we said that SIP messages are sent independently over the network, they
+	    are usually arranged into <emphasis>transactions</emphasis> by user agents and
+	    certain types of proxy servers. Therefore SIP is said to be a
+	    <emphasis>transactional protocol</emphasis>.
+	</simpara>
+	<simpara>
+	    A transaction is a sequence of SIP messages exchanged between SIP network
+	    elements. A transaction consists of one request and all responses to that
+	    request. That includes zero or more provisional responses and one or more final
+	    responses (remember that an INVITE might be answered by more than one final response
+	    when a proxy server forks the request).
+	</simpara>
+	<simpara>
+	    If a transaction was initiated by an INVITE request then the same transaction also
+	    includes ACK, but only if the final response was not a 2xx response. If the final
+	    response was a 2xx response then the ACK is not considered part of the transaction.
+	</simpara>
+	<simpara>
+	    As we can see this is quite asymmetric behavior--ACK is part of transactions with a
+	    negative final response but is not part of transactions with positive final
+	    responses. The reason for this separation is the importance of delivery of all 200
+	    OK messages. Not only that they establish a session, but also 200 OK can be
+	    generated by multiple entities when a proxy server forks the request and all of them
+	    must be delivered to the calling user agent. Therefore user agents take
+	    responsibility in this case and retransmit 200 OK responses until they receive an
+	    ACK. Also note that only responses to INVITE are retransmitted !
+	</simpara>
+	<simpara>
+	    SIP entities that have notion of transactions are called
+	    <emphasis>stateful</emphasis>. Such entities usually create a state associated with
+	    a transaction that is kept in the memory for the duration of the transaction. When a
+	    request or response comes, a stateful entity tries to associate the request (or
+	    response) to existing transactions. To be able to do it it must extract a unique
+	    transaction identifier from the message and compare it to identifiers of all
+	    existing transactions. If such a transaction exists then it's state gets updated
+	    from the message.
+	</simpara>
+	<simpara>
+	    In the previous SIP RFC2543 the transaction identifier was calculated as hash of
+	    all important message header fields (that included To, From, Request-URI and
+	    CSeq). This proved to be very slow and complex, during interoperability tests such
+	    transaction identifiers used to be a common source of problems.
+	</simpara>
+	<simpara>
+	    In the new RFC3261 the way of calculating transaction identifiers was completely
+	    changed. Instead of complicated hashing of important header fields a SIP message now
+	    includes the identifier directly. Branch parameter of Via header fields contains directly
+	    the transaction identifier. This is significant simplification, but there still exist old
+	    implementations that don't support the new way of calculating of transaction identifier so
+	    even new implementations have to support the old way. They must be backwards compatible.
+	</simpara>
+	<simpara>
+	    <xref linkend="transactions"/> shows what messages belong to what transactions
+		during a conversation of two user agents.
+	</simpara>
+	<figure id="transactions">
+	    <title>SIP Transactions</title>
+	    <mediaobject>
+		<imageobject>
+		    <imagedata fileref="figures/transaction.png" format="PNG"/>
+		</imageobject>
+		<textobject>
+		    <phrase>Message flow showing messages belonging to the same transaction.</phrase>
+		</textobject>
+	    </mediaobject>
+	</figure>
+    </section>
+    <section id="sip_dialogs">
+	<title>SIP Dialogs</title>
+	<simpara>
+	    We have shown what transactions are, that one transaction includes INVITE and it's
+	    responses and another transaction includes BYE and it responses when a session is
+	    being torn down. But we feel that those two transactions should be somehow
+	    related--both of them belong to the same <emphasis>dialog</emphasis>. A dialog
+	    represents a peer-to-peer SIP relationship between two user agents. A dialog
+	    persists for some time and it is very important concept for user agents. Dialogs
+	    facilitate proper sequencing and routing of messages between SIP endpoints.
+	</simpara>
+	<simpara>
+	    Dialogs are identified using Call-ID, From tag, and To
+	    tag. Messages that have these three identifiers same belong to the
+	    same dialog. We have shown that CSeq header field is used to order
+	    messages, in fact it is used to order messages within a dialog. The
+	    number must be monotonically increased for each message sent within
+	    a dialog otherwise the peer will handle it as out of order request
+	    or retransmission. In fact, the CSeq number identifies a
+	    transaction within a dialog because we have said that requests and
+	    associated responses are called transaction. This means that only
+	    one transaction in each direction can be active within a
+	    dialog. One could also say that a <emphasis>dialog is a sequence of
+	    transactions</emphasis>. <xref linkend="dialog"/> extends <xref
+	    linkend="transactions"/> to show which messages belong to the
+	    same dialog.
+	</simpara>
+	<figure id="dialog">
+	    <title>SIP Dialog</title>
+	    <mediaobject>
+		<imageobject>
+		    <imagedata fileref="figures/dialog.png" format="PNG"/>
+		</imageobject>
+		<textobject>
+		    <phrase>Message flow showing transactions belonging to the same dialog.</phrase>
+		</textobject>
+	    </mediaobject>
+	</figure>
+	<simpara>
+	    Some messages establish a dialog and some do not. This allows to explicitly express
+	    the relationship of messages and also to send messages that are not related to other
+	    messages outside a dialog. That is easier to implement because user agent don't have
+	    to keep the dialog state.
+	</simpara>
+	<simpara>
+	    For instance, INVITE message establishes a dialog, because it will be later followed
+	    by BYE request which will tear down the session established by the INVITE. This BYE
+	    is sent within the dialog established by the INVITE.
+	</simpara>
+	<simpara>
+	    But if a user agent sends a MESSAGE request, such a request doesn't establish any
+	    dialog. Any subsequent messages (even MESSAGE) will be sent independently of the
+	    previous one.
+	</simpara>
+	<section id="dialogs_facilitate_routing">
+	    <title>Dialogs Facilitate Routing</title>
+	    <simpara>
+		We have said that dialogs are also used to route the messages between user
+		agents, let's describe this a little bit.
+	    </simpara>
+	    <simpara>
+		Let's suppose that user sip:[email protected] wants to talk to user sip:[email protected]. He
+		knows SIP address of the callee (sip:[email protected]) but this address doesn't say
+		anything about current location of the user--i.e. the caller doesn't know to
+		which host to send the request. Therefore the INVITE request will be sent to a
+		proxy server.
+	    </simpara>
+	    <simpara>
+		The request will be sent from proxy to proxy until it reaches one that knows
+		current location of the callee. This process is called routing. Once the request
+		reaches the callee, the callee's user agent will create a response that will be
+		sent back to the caller. Callee's user agent will also put Contact header field
+		into the response which will contain the current location of the user. The
+		original request also contained Contact header field which means that both user
+		agents know the current location of the peer.
+	    </simpara>
+	    <simpara>
+		Because the user agents know location of each other, it is not necessary to send
+		further requests to any proxy--they can be sent directly from user agent to user
+		agent. That's exactly how dialogs facilitate routing.
+	    </simpara>
+	    <simpara>
+		Further messages within a dialog are sent directly from user agent to user
+		agent. This is a significant performance improvement because proxies do not see
+		all the messages within a dialog, they are used to route just the first request
+		that establishes the dialog. The direct messages are also delivered with much
+		smaller latency because a typical proxy usually implements complex routing
+		logic. <xref linkend="trapezoid"/> contains an example of a message
+		    within a dialog (BYE) that bypasses the proxies.
+	    </simpara>
+	    <figure id="trapezoid">
+		<title>SIP Trapezoid</title>
+		<mediaobject>
+		    <imageobject>
+			<imagedata fileref="figures/trapezoid.png" format="PNG"/>
+		    </imageobject>
+		    <textobject>
+			<phrase>Message flow showing SIP trapezoid.</phrase>
+		    </textobject>
+		</mediaobject>
+	    </figure>
+	</section>
+	<section id="dialogs_identifiers">
+	    <title>Dialog Identifiers</title>
+	    <simpara>
+		We have already shown that dialog identifiers consist of three parts, Call-Id,
+		From tag, and To tag, but it is not that clear why are dialog identifiers
+		created exactly this way and who contributes which part.
+	    </simpara>
+	    <simpara>
+		Call-ID is so called <emphasis>call identifier</emphasis>. It must be a unique
+		string that identifies a call. A call consists of one or more dialogs. Multiple
+		user agents may respond to a request when a proxy along the path forks the
+		request. Each user agent that sends a 2xx establishes a separate dialog with the
+		caller. All such dialogs are part of the same call and have the same Call-ID.
+	    </simpara>
+	    <simpara>
+		From tag is generated by the caller and it uniquely identifies the dialog in the
+		caller's user agent.
+	    </simpara>
+	    <simpara>
+		To tag is generated by a callee and it uniquely identifies, just like From tag,
+		the dialog in the callee's user agent.
+	    </simpara>
+	    <simpara>
+		This hierarchical dialog identifier is necessary because a single call
+		invitation can create several dialogs and caller must be able to distinguish
+		them.
+	    </simpara>
+	</section>
+    </section>
+    <section id="typical_sip_scenarios">
+	<title>Typical SIP Scenarios</title>
+	<simpara>
+	    This section gives a brief overview of typical SIP scenarios that usually make up the
+	    SIP traffic.
+	</simpara>
+	<section id="registration">
+	    <title>Registration</title>
+	    <simpara>
+		Users must register themselves with a registrar to be reachable by other
+		users. A registration comprises a REGISTER message followed by a 200 OK sent by
+		registrar if the registration was successful. Registrations are usually
+		authorized so a 407 reply can appear if the user didn't provide valid
+		credentials. <xref linkend="register_fig"/> shows an example of registration.
+	    </simpara>
+	    <figure id="register_fig">
+		<title>REGISTER Message Flow</title>
+		<mediaobject>
+		    <imageobject>
+			<imagedata fileref="figures/register.png" format="PNG"/>
+		    </imageobject>
+		    <textobject>
+			<phrase>Message flow of a registration.</phrase>
+		    </textobject>
+		</mediaobject>
+	    </figure>
+	</section>
+	<section id="session_invitation">
+	    <title>Session Invitation</title>
+	    <simpara>
+		A session invitation consists of one INVITE request which is usually sent to a
+		proxy. The proxy sends immediately a 100 Trying reply to stop retransmissions
+		and forwards the request further.
+	    </simpara>
+	    <simpara>
+		All provisional responses generated by callee are sent back to the caller. See
+		180 Ringing response in the call flow. The response is generated when callee's
+		phone starts ringing.
+	    </simpara>
+	    <figure id="invite1">
+		<title>INVITE Message Flow</title>
+		<mediaobject>
+		    <imageobject>
+			<imagedata fileref="figures/invite1.png" format="PNG"/>
+		    </imageobject>
+		    <textobject>
+			<phrase>Picture showing a session invitation.</phrase>
+		    </textobject>
+		</mediaobject>
+	    </figure>
+	    <simpara>
+		A 200 OK is generated once the callee picks up the phone and it is retransmitted
+		by the callee's user agent until it receives an ACK from the caller. The session
+		is established at this point.
+	    </simpara>
+	</section>
+	<section id="session_termination">
+	    <title>Session Termination</title>
+	    <simpara>
+		Session termination is accomplished by sending a BYE request within dialog
+		established bye INVITE. BYE messages are sent directly from one user agent to
+		the other unless a proxy on the path of the INVITE request indicated that it
+		wishes to stay on the path by using record routing (see <xref
+		    linkend="record_routing"/>.
+	    </simpara>
+	    <simpara>
+		Party wishing to tear down a session sends a BYE request to the other party
+		involved in the session. The other party sends a 200 OK response to confirm the
+		BYE and the session is terminated. See <xref linkend="bye"/>, left message
+		    flow.
+	    </simpara>
+	</section>
+	<section id="record_routing">
+	    <title>Record Routing</title>
+	    <simpara>
+		All requests sent within a dialog are by default sent directly from one user agent
+		to the other. Only requests outside a dialog traverse SIP proxies. This approach
+		makes SIP network more scalable because only a small number of SIP messages hit
+		the proxies.
+	    </simpara>
+	    <simpara>
+		There are certain situations in which a SIP proxy need to stay on the path of all
+		further messages. For instance, proxies controlling a NAT box or proxies doing
+		accounting need to stay on the path of BYE requests.
+	    </simpara>
+	    <simpara>
+		Mechanism by which a proxy can inform user agents that it wishes to stay on the path
+		of all further messages is called <emphasis>record routing</emphasis>. Such a proxy
+		would insert Record-Route header field into SIP messages which contain address of
+		the proxy. Messages sent within a dialog will then traverse all SIP proxies that
+		put a Record-Route header field into the message.
+	    </simpara>
+	    <simpara>
+		The recipient of the request receives a set of Record-Route header fields in the
+		message. It must mirror all the Record-Route header fields into responses because
+		the originator of the request also needs to know the set of proxies.
+	    </simpara>
+	    <figure id="bye">
+		<title>BYE Message Flow (With and without Record Routing)</title>
+		<mediaobject>
+		    <imageobject>
+			<imagedata fileref="figures/bye.png" format="PNG"/>
+		    </imageobject>
+		    <textobject>
+			<phrase>Picture showing BYE message flow with and without record routing.</phrase>
+		    </textobject>
+		</mediaobject>
+	    </figure>
+	    <simpara>
+		Left message flow of <xref linkend="bye"/> show how a BYE (request
+		    within dialog established by INVITE) is sent directly to the other user agent
+		    when there is no Record-Route header field in the message. Right message flow
+		    show how the situation changes when the proxy puts a Record-Route header field
+		    into the message.
+	    </simpara>
+	    <section id="strict_vs_loose">
+		<title>Strict versus Loose Routing</title>
+		<simpara>
+		    The way how record routing works has evolved. Record routing according to
+		    RFC2543 rewrote the Request-URI. That means the Request-URI always
+		    contained URI of the next hop (which can be either next proxy server which
+		    inserted Record-Route header field or destination user agent). Because of
+		    that it was necessary to save the original Request-URI as the last Route
+		    header field. This approach is called <emphasis>strict routing</emphasis>.
+		</simpara>
+		<simpara>
+		    <emphasis>Loose routing</emphasis>, as specified in RFC3261, works in a
+		    little bit different way. The Request-URI is no more overwritten, it always
+		    contains URI of the destination user agent. If there are any Route header
+		    field in a message, than the message is sent to the URI from the topmost
+		    Route header field. This is significant change--Request-URI doesn't
+		    necessarily contain URI to which the request will be sent. In fact, loose
+		    routing is very similar to IP source routing.
+		</simpara>
+		<simpara>
+		    Because transit from strict routing to loose routing would break backwards
+		    compatibility and older user agents wouldn't work, it is necessary to make
+		    loose routing backwards compatible. The backwards compatibility
+		    unfortunately adds a lot of overhead and is often source of major problems.
+		</simpara>
+	    </section>
+	</section>
+	<section id="sub_not">
+	    <title>Event Subscription And Notification</title>
+	    <simpara>
+		The SIP specification has been extended to support a general mechanism allowing
+		subscription to asynchronous events. Such evens can include SIP proxy statistics
+		changes, presence information, session changes and so on.
+	    </simpara>
+	    <simpara>
+		The mechanism is used mainly to convey information on presence (willingness to
+		communicate) of users. <xref linkend="event"/> shows the basic message
+		    flow.
+	    </simpara>
+	    <figure id="event">
+		<title>Event Subscription And Notification</title>
+		<mediaobject>
+		    <imageobject>
+			<imagedata fileref="figures/event.png" format="PNG"/>
+		    </imageobject>
+		    <textobject>
+			<phrase>Picture showing subscription and notification.</phrase>
+		    </textobject>
+		</mediaobject>
+	    </figure>
+	    <simpara>
+		A user agent interested in event notification sends a SUBSCRIBE message to a
+		SIP server. The SUBSCRIBE message establishes a dialog and is immediately
+		replied by the server using 200 OK response. At this point the dialog is
+		established. The server sends a NOTIFY request to the user every time the event
+		to which the user subscribed changes. NOTIFY messages are sent within the dialog
+		established by the SUBSCRIBE.
+	    </simpara>
+	    <simpara>
+		Note that the first NOTIFY message in <xref linkend="event"/> is sent
+		    regardless of any event that triggers notifications.
+	    </simpara>
+	    <simpara>
+		Subscriptions--as well as registrations--have limited lifespan and therefore must be
+		periodically refreshed.
+	    </simpara>
+	</section>
+	<section id="im">
+	    <title>Instant Messages</title>
+	    <simpara>
+		Instant messages are sent using MESSAGE request. MESSAGE requests do not establish a
+		dialog and therefore they will always traverse the same set of proxies. This is the
+		simplest form of sending instant messages. The text of the instant message is
+		transported in the body of the SIP request.
+	    </simpara>
+	    <figure id="message">
+		<title>Instant Messages</title>
+		<mediaobject>
+		    <imageobject>
+			<imagedata fileref="figures/message.png" format="PNG"/>
+		    </imageobject>
+		    <textobject>
+			<phrase>Picture showing a MESSAGE.</phrase>
+		    </textobject>
+		</mediaobject>
+	    </figure>
+	</section>
+    </section>
+</section>