@@ -1,3 +1,4 @@

+

 -------------------------------------------------------------------------

 IMPORTANT NOTES

@@ -19,7 +20,7 @@ IMPORTANT NOTES

     for a detailed explanation)

 3) Note that the GPL bellow is copyrighted by the Free Software Foundation,

-   but the ser software is copyrighted by iptel.org.

+   but the ser software is copyrighted by FhG

 -------------------------------------------------------------------------

@@ -81,7 +82,7 @@ patent must be licensed for everyone's free use or not licensed at all.

   The precise terms and conditions for copying, distribution and

 modification follow.

-

+

 		    GNU GENERAL PUBLIC LICENSE

    TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

@@ -136,7 +137,7 @@ above, provided that you also meet all of these conditions:

     License.  (Exception: if the Program itself is interactive but

     does not normally print such an announcement, your work based on

     the Program is not required to print an announcement.)

-

+

 These requirements apply to the modified work as a whole.  If

 identifiable sections of that work are not derived from the Program,

 and can be reasonably considered independent and separate works in

@@ -194,7 +195,7 @@ access to copy from a designated place, then offering equivalent

 access to copy the source code from the same place counts as

 distribution of the source code, even though third parties are not

 compelled to copy the source along with the object code.

-

+

   4. You may not copy, modify, sublicense, or distribute the Program

 except as expressly provided under this License.  Any attempt

 otherwise to copy, modify, sublicense or distribute the Program is

@@ -251,7 +252,7 @@ impose that choice.

 This section is intended to make thoroughly clear what is believed to

 be a consequence of the rest of this License.

-

+

   8. If the distribution and/or use of the Program is restricted in

 certain countries either by patents or by copyrighted interfaces, the

 original copyright holder who places the Program under this License

@@ -304,63 +305,3 @@ PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE

 POSSIBILITY OF SUCH DAMAGES.

 		     END OF TERMS AND CONDITIONS

-

-	    How to Apply These Terms to Your New Programs

-

-  If you develop a new program, and you want it to be of the greatest

-possible use to the public, the best way to achieve this is to make it

-free software which everyone can redistribute and change under these terms.

-

-  To do so, attach the following notices to the program.  It is safest

-to attach them to the start of each source file to most effectively

-convey the exclusion of warranty; and each file should have at least

-the "copyright" line and a pointer to where the full notice is found.

-

-    <one line to give the program's name and a brief idea of what it does.>

-    Copyright (C) <year>  <name of author>

-

-    This program 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.

-

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

-

-    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

-

-

-Also add information on how to contact you by electronic and paper mail.

-

-If the program is interactive, make it output a short notice like this

-when it starts in an interactive mode:

-

-    Gnomovision version 69, Copyright (C) year  name of author

-    Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.

-    This is free software, and you are welcome to redistribute it

-    under certain conditions; type `show c' for details.

-

-The hypothetical commands `show w' and `show c' should show the appropriate

-parts of the General Public License.  Of course, the commands you use may

-be called something other than `show w' and `show c'; they could even be

-mouse-clicks or menu items--whatever suits your program.

-

-You should also get your employer (if you work as a programmer) or your

-school, if any, to sign a "copyright disclaimer" for the program, if

-necessary.  Here is a sample; alter the names:

-

-  Yoyodyne, Inc., hereby disclaims all copyright interest in the program

-  `Gnomovision' (which makes passes at compilers) written by James Hacker.

-

-  <signature of Ty Coon>, 1 April 1989

-  Ty Coon, President of Vice

-

-This General Public License does not permit incorporating your program into

-proprietary programs.  If your program is a subroutine library, you may

-consider it more useful to permit linking proprietary applications with the

-library.  If this is what you want to do, use the GNU Library General

-Public License instead of this License.

@@ -7,6 +7,14 @@

 <!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">

+

+

 ]>

@@ -15,8 +23,8 @@

 <?dbhtml filename="index.html">

-

-    <title>iptel.org SIP Express Router v0.8.8 -- User's Guide</title>

+   

+    <title>iptel.org SIP Express Router v0.8.10 -- Admin's Guide</title>

     <bookinfo>

 	<authorgroup>

 	    <author>

@@ -79,12 +87,13 @@

 	    </para>

 	</abstract>

 	<releaseinfo>

-	    This is a pre-release documentation of the SER SIP Server.

-	    For the latest and most complete documentation, visit our

-	    site at <ulink url="http://www.iptel.org/ser/">http://www.iptel.org/ser</ulink>

+	    This documentation is continuously updated. For the latest and most complete 

+	    version, visit our site at 

+	    <ulink url="http://www.iptel.org/ser/">http://www.iptel.org/ser</ulink>.

+	    Version of this document is $Id$.

 	</releaseinfo>

     </bookinfo>

-    

+

     <toc></toc>

     <chapter id="general">

@@ -93,7 +102,7 @@

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

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

@@ -113,12 +122,12 @@

 	    </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, the 

+		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 Messenger.  

+		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 

@@ -131,12 +140,11 @@

 		<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">ser</application> web interface,

 		and <application moreinfo="none">SIPSak</application>

-		diagnostic tools are available. Visit our site, 

-		<ulink url="http://www.iptel.org/">http://www.iptel.org/</ulink>

-		, for more information on

-		contributed packages.

+		diagnostic tool are available. Visit our site, 

+		<ulink url="http://www.iptel.org/">http://www.iptel.org/</ulink>, 

+                for more information on contributed packages.

 	    </para>

 	</section> 

@@ -154,6 +162,13 @@

 		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">

@@ -161,34 +176,44 @@

 	    <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 <acronym>CPL</acronym>, instant messaging and 

-		presence including a <acronym>2G/SMS</acronym> gateway, a call control policy 

+		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, 

-		authorization and authentication (<acronym>AAA</acronym>) services. <acronym>SER</acronym> runs on Sun/Solaris, 

-		PC/Linux, IPAQ/Linux platforms and supports  both <acronym>IPv4</acronym> and <acronym>IPv6</acronym>. 

+		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>

 		Other extensions are underway: presence server, firewall control and more.

 	    </para>

 	    <para>

-		ser has been carefully engineered with the following design objectives in mind:

+		<application>ser</application> has been carefully engineered with the following 

+		design objectives in mind:

 		<itemizedlist>

 		    <listitem>

 			<para>

-			    <emphasis>Speed</emphasis> - With SER, thousands of calls per seconds are achievable 

+			    <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 speed has been 

-			    achieved by extensive code optimization, usage of customized code, 

+			    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 serve call signaling Bay Area population.

+			    <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> - <acronym>SER</acronym> allows its users to define its behavior. 

+			    <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, 

@@ -200,12 +225,12 @@ to serve call signaling Bay Area population.

 		    </listitem>

 		    <listitem>

 			<para>

-			    <acronym>Extensibility</acronym> - <acronym>SER</acronym>'s extensibility allows linking of 

+			    <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 <acronym>SER</acronym> core and linked to it in run-time. The concept is similar to 

+			    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 <acronym>SER</acronym> core 

+			    as transaction management have been developed as modules to keep the <application>SER</application> core 

 			    compact and fast.

 			</para>

 		    </listitem>

@@ -214,8 +239,8 @@ to serve call signaling Bay Area population.

 			    <emphasis>

 				Portability.

 			    </emphasis>

-			    Ser has been written in ANSI C. It has been extensively tested on PC/Linux and 

-			    Sun/Solaris. 

+			    <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>

@@ -223,11 +248,19 @@ to serve call signaling Bay Area population.

 			    <emphasis>			   

 				Interoperability. 

 			</emphasis>

-			Ser is based on open SIP standard. It has undergone extensive testing with 

-			    products of other vendors. It powers the public iptel.org site 24 hours a day, 356 days a year 

+			<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 -->

@@ -254,9 +287,9 @@ to serve call signaling Bay Area population.

 		    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 start by providing instant messaging services on this 

-		    standardized platform. This can be combined with the SIP-to-SMS gateway service also supported 

-		    by SER. In a second step VoIP services can be added in addition to voicemail services and  UMS.

+		    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>

@@ -264,12 +297,13 @@ to serve call signaling Bay Area population.

 		<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, substantial savings can be achieved by 

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

+		    calls to geographically appropriate PSTN gateway, act as a security barrier and keep 

+		    track of charging. 

 		</para>

 	    </section>

 	    <section>

@@ -296,15 +330,15 @@ to serve call signaling Bay Area population.

 	<section id="aboutsip">

 	    <title>About SIP Technology</title>

 	    <para>

-		The SIP protocol family is the technology which has succeeded in realizing the vision of the 

-		integrated services. With SIP, Internet users can easily contact each other; figure out 

+		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) standardized by IETF. 

+		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 

@@ -329,11 +363,6 @@ to serve call signaling Bay Area population.

 			    TCP transport

 			</para>

 		    </listitem>

-		    <listitem>

-			<para>

-			    Loose routing

-			</para>

-		    </listitem>

 		    <listitem>

 			<para>

 			    Script processing of multiple branches on forking

@@ -341,14 +370,17 @@ to serve call signaling Bay Area population.

 			<warning>

 			    <para>

-				ser's request processing language allows to make request decisions based on current URI. 

+				<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 and vice versa. That might result in ignoring of 

-				gateway admission control rules or applying them unnecessarily to non-gateway destinations.

+				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>

@@ -361,16 +393,108 @@ to serve call signaling Bay Area population.

 		</ulink>.

 	    </para>

 	</section> <!-- limitations -->

-	<section id="contact">

-	    <title>Contact and Licencing</title>

+	<section id="licensing">

+	    <title>Licensing</title>

 	    <para>

-		For any additional information, send an inquiry to info@iptel.org. 

-		Licensing conditions other than GPL are available on request. If

-		you need a help with ser, send an email to serhelp@iptel.org.

-		Report bugs at 

-		<ulink url="http://developer.berlios.de/bugs/?group_id=480">

-		    http://developer.berlios.de/bugs/?group_id=480

-		</ulink>

+		<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>

+		We offer best-effort free support for <application>ser</application>.

+		"best-effort" means that we try to solve your problems via email

+		as soon as we can, subject to available manpower. If you need

+		commercial support, contact info@iptel.org.

+	    </para>

+	    <para>

+		To receive feedback to your inquiries, we recommend you to subscribe

+		to the <emphasis>serusers</emphasis> mailing list and post your

+		queries there. This mailing list is set up for mutual help by

+		the community of <application>ser</application> users and developers.

+	    </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 serusers@iptel.org

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

+		serhelp@iptel.org. 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>

@@ -380,7 +504,7 @@ to serve call signaling Bay Area population.

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

+		<ulink url="http://www.iptel.org/ser/">http://www.iptel.org/ser/</ulink>.

 		For information on how to install ser, read INSTALL.

 		SGML documentation is available in the 'doc' directory.

 		A SIP tutorial (slide set) is available at 

@@ -401,130 +525,79 @@ to serve call signaling Bay Area population.

 		location service or enforce static routing to a gateway. Real-world

 		deployments actually ask for quite complex routing logic, which

 		needs to reflex static routes to PSTN gateways, dynamic routes

-		to registered users, authentication policy, etc.

+		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 routing

-		logic in a detailed manner. They can for example easily

+		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 actions. There are 

-		built-in actions (like forward for stateless forwarding) as 

-		well as external actions supplied in shared library modules. The actions can be combined in composed statements 

-		({a1(); a2();}). The language includes conditional statements and subroutines (recursive too). 

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

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

-		Script processing may be explicitly exited 

-		by calling "break". 

-

-		Zero value means error and stops processing the script. 

-		One might jump to another route[x] block by calling route(x) (similar to function calling).

+		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 way for ser users to affect routing logic is

-		to determine next hop statically. A useful scenario is

-		routing to a gateway whose static IP address is well known.

-		To configure static routing, simply use the commands

-		forward( IP_address, port_number>) for stateless

-		forwarding or t_relay_to( IP_address, port_number )

-		for stateful forwarding.

+		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>Stateless versus stateful forwarding</title>

+		<title>Static Forwarding</title>

 		<programlisting format="linespecific">

 # if requests URI is numerical and starts with

-# zero, forward statelessly, otherwise forward 

-# statefully

+# zero, forward statelessly to a static destination

 if (uri=~"^sip:0[0-9]*@iptel.org) {

-    # statelessly

     forward( 192.168.99.3, 5080 );

-} else {

-    # statefully

-    t_relay_to( "192.168.99.3", "5080" );

-}

+} 

 		</programlisting>

 	    </example>

-	</section>

-	

-	<section>

-	    <title>URI Rewriting</title>

 	    <para>

-		A powerful tool for affecting routing logic is changing

-		request URI. This can be done with any of built-in commands

-		<command>rewriteuri</command>, 

-		<command>rewritehost</command>, 

-		<command>rewritehostport</command>, 

-		<command>rewriteuser</command>, 

-		<command>rewriteuserpass</command> and 

-		<command>rewriteport</command>. All these commands

-		rewrite request URI or a part of it. When later in a ser script

-		a forwarding command is encountered, the command forwards

-		the request to address in the rewritten URI.

+		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>

-	    <para>Two URI-rewriting commands are of special importance

-		for implementation of dialing plans. <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.

-	    </para>

-	    

-	    <example>

-		<title>Rewriting URIs</title>

-		<programlisting format="linespecific">

-if (uri=~"dan@foo.bar") {

-    rewriteuri("sip:bla@somewherelse.com")

-    # forward statelessly

-    forward( dst:uri, dst:port);

-}

-		</programlisting>

-	    </example>

-

-	    <para>

-		Commands exported by external modules can change URI too.

-		The most important application is changing URI using the

-		user location database. The command 

-		<command>lookup(table)</command> rewrites

-		current URI with a value stored previously during SIP

-		registration. If there is no registration, the 

-		command returns negative value.

-	    </para>

-	    <example>

-		<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 {

-     sl_send_reply("404", "Not Found" );

-   };

-};

-		</programlisting>

-	    </example>

-

-	</section> <!-- URI rewriting -->

+	</section>

-	<section>

+	<section id="conditions">

 	    <title>Conditional Statements</title>

 	    <para>

 		A very useful feature is the ability to make routing

@@ -533,55 +606,92 @@ if (method=="REGISTER") {

 		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.

+		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 selectively authenticate REGISTER requests.

+		    used to split incoming requests between a PSTN

+		    gateway and a user location server based on

+		    request URI.

 		</para>

 		<programlisting format="linespecific">

-# we want to authentication only registrations;

-# no other request, such as INVITE, will be authenticated

-# because we want to accept anonymous incoming calls

-if (method=="REGISTER") {

-

-    # are authentication credential valid ? ...

-    if (!www_authorize("iptel.org", "subscriber")) {

-        # .... they are not, challenge user and stop processing

-

-        www_challenge("iptel.org", "0");

-        break;

-    };

-

-# ... credentials valid -> save a new entry

-# in user location database

-

-    save("location");

+# if request URI is numerical, forward the request to PSTN gateway...

+if (uri=~"^sip:[0-9]+@foo.bar") { # 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>

-	    

-	    <section>

+

+	    <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 ser, which in addition to actions may be evaluated

 		    in conditional expressions. 

 		</para>

 		<para>

-		    Operands, which ser understands are the following:

+		    Left hand-side operands, which <application>ser</application>

+		    understands are the following:

 		    <itemizedlist>

 			<listitem>

 			    <para>

-				method, which refers to requests method

+				<emphasis>method</emphasis>, which refers to 

+				request method

 				such as REGISTER or INVITE

 			    </para>

 			</listitem>

 			<listitem>

 			    <para>

-				uri, which refers to current request URI, i

+				<emphasis>uri</emphasis>, which refers to current request URI,

 				such as 

 				"sip:john.doe@foo.bar"

 				<note>

@@ -595,10 +705,16 @@ if (method=="REGISTER") {

 			</listitem>

 			<listitem>

 			    <para>

-				scr_ip, which referes to IP address from 

+				<emphasis>scr_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>

 		    </itemizedlist>

 		</para>

 		<para>

@@ -612,20 +728,133 @@ if (method=="REGISTER") {

 			</listitem>

 			<listitem>

 			    <para>

-				=~ stand for regular expression match

+				=~ stands for regular expression matching

 			    </para>

 			</listitem>

 			<listitem>

 			    <para>

-				logical operators: and, or, negation

+				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>