Browse code

admin documentation refurbished -- quite many changes, don't want me to list all of them

Jiri Kuthan authored on 09/12/2002 02:32:56
Showing 9 changed files
... ...
@@ -1,3 +1,4 @@
1
+
1 2
 -------------------------------------------------------------------------
2 3
 IMPORTANT NOTES
3 4
 
... ...
@@ -19,7 +20,7 @@ IMPORTANT NOTES
19 19
     for a detailed explanation)
20 20
 
21 21
 3) Note that the GPL bellow is copyrighted by the Free Software Foundation,
22
-   but the ser software is copyrighted by iptel.org.
22
+   but the ser software is copyrighted by FhG
23 23
 
24 24
 
25 25
 -------------------------------------------------------------------------
... ...
@@ -81,7 +82,7 @@ patent must be licensed for everyone's free use or not licensed at all.
81 81
 
82 82
   The precise terms and conditions for copying, distribution and
83 83
 modification follow.
84
-
84
+
85 85
 		    GNU GENERAL PUBLIC LICENSE
86 86
    TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
87 87
 
... ...
@@ -136,7 +137,7 @@ above, provided that you also meet all of these conditions:
136 136
     License.  (Exception: if the Program itself is interactive but
137 137
     does not normally print such an announcement, your work based on
138 138
     the Program is not required to print an announcement.)
139
-
139
+
140 140
 These requirements apply to the modified work as a whole.  If
141 141
 identifiable sections of that work are not derived from the Program,
142 142
 and can be reasonably considered independent and separate works in
... ...
@@ -194,7 +195,7 @@ access to copy from a designated place, then offering equivalent
194 194
 access to copy the source code from the same place counts as
195 195
 distribution of the source code, even though third parties are not
196 196
 compelled to copy the source along with the object code.
197
-
197
+
198 198
   4. You may not copy, modify, sublicense, or distribute the Program
199 199
 except as expressly provided under this License.  Any attempt
200 200
 otherwise to copy, modify, sublicense or distribute the Program is
... ...
@@ -251,7 +252,7 @@ impose that choice.
251 251
 
252 252
 This section is intended to make thoroughly clear what is believed to
253 253
 be a consequence of the rest of this License.
254
-
254
+
255 255
   8. If the distribution and/or use of the Program is restricted in
256 256
 certain countries either by patents or by copyrighted interfaces, the
257 257
 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
304 304
 POSSIBILITY OF SUCH DAMAGES.
305 305
 
306 306
 		     END OF TERMS AND CONDITIONS
307
-
308
-	    How to Apply These Terms to Your New Programs
309
-
310
-  If you develop a new program, and you want it to be of the greatest
311
-possible use to the public, the best way to achieve this is to make it
312
-free software which everyone can redistribute and change under these terms.
313
-
314
-  To do so, attach the following notices to the program.  It is safest
315
-to attach them to the start of each source file to most effectively
316
-convey the exclusion of warranty; and each file should have at least
317
-the "copyright" line and a pointer to where the full notice is found.
318
-
319
-    <one line to give the program's name and a brief idea of what it does.>
320
-    Copyright (C) <year>  <name of author>
321
-
322
-    This program is free software; you can redistribute it and/or modify
323
-    it under the terms of the GNU General Public License as published by
324
-    the Free Software Foundation; either version 2 of the License, or
325
-    (at your option) any later version.
326
-
327
-    This program is distributed in the hope that it will be useful,
328
-    but WITHOUT ANY WARRANTY; without even the implied warranty of
329
-    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
330
-    GNU General Public License for more details.
331
-
332
-    You should have received a copy of the GNU General Public License
333
-    along with this program; if not, write to the Free Software
334
-    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
335
-
336
-
337
-Also add information on how to contact you by electronic and paper mail.
338
-
339
-If the program is interactive, make it output a short notice like this
340
-when it starts in an interactive mode:
341
-
342
-    Gnomovision version 69, Copyright (C) year  name of author
343
-    Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
344
-    This is free software, and you are welcome to redistribute it
345
-    under certain conditions; type `show c' for details.
346
-
347
-The hypothetical commands `show w' and `show c' should show the appropriate
348
-parts of the General Public License.  Of course, the commands you use may
349
-be called something other than `show w' and `show c'; they could even be
350
-mouse-clicks or menu items--whatever suits your program.
351
-
352
-You should also get your employer (if you work as a programmer) or your
353
-school, if any, to sign a "copyright disclaimer" for the program, if
354
-necessary.  Here is a sample; alter the names:
355
-
356
-  Yoyodyne, Inc., hereby disclaims all copyright interest in the program
357
-  `Gnomovision' (which makes passes at compilers) written by James Hacker.
358
-
359
-  <signature of Ty Coon>, 1 April 1989
360
-  Ty Coon, President of Vice
361
-
362
-This General Public License does not permit incorporating your program into
363
-proprietary programs.  If your program is a subroutine library, you may
364
-consider it more useful to permit linking proprietary applications with the
365
-library.  If this is what you want to do, use the GNU Library General
366
-Public License instead of this License.
... ...
@@ -7,6 +7,14 @@
7 7
 <!ENTITY redirectexample SYSTEM "../../examples/redirect.cfg">
8 8
 <!ENTITY replyexample SYSTEM "../../examples/onr.cfg">
9 9
 <!ENTITY statefuluaexample SYSTEM "../../examples/uas.cfg">
10
+<!ENTITY gpllicense SYSTEM "../../COPYING">
11
+<!ENTITY sendim SYSTEM "../../examples/web_im/send_im.php">
12
+<!ENTITY gatewayacl SYSTEM "../../examples/pstn.cfg">
13
+<!ENTITY accountingexample SYSTEM "../../examples/acc.cfg">
14
+<!ENTITY replicateexample SYSTEM "../../examples/replicate.cfg">
15
+<!ENTITY defscr SYSTEM "../../etc/ser.cfg">
16
+
17
+
10 18
 
11 19
 ]>
12 20
 
... ...
@@ -15,8 +23,8 @@
15 15
 
16 16
 <?dbhtml filename="index.html">
17 17
 
18
-
19
-    <title>iptel.org SIP Express Router v0.8.8 -- User's Guide</title>
18
+   
19
+    <title>iptel.org SIP Express Router v0.8.10 -- Admin's Guide</title>
20 20
     <bookinfo>
21 21
 	<authorgroup>
22 22
 	    <author>
... ...
@@ -79,12 +87,13 @@
79 79
 	    </para>
80 80
 	</abstract>
81 81
 	<releaseinfo>
82
-	    This is a pre-release documentation of the SER SIP Server.
83
-	    For the latest and most complete documentation, visit our
84
-	    site at <ulink url="http://www.iptel.org/ser/">http://www.iptel.org/ser</ulink>
82
+	    This documentation is continuously updated. For the latest and most complete 
83
+	    version, visit our site at 
84
+	    <ulink url="http://www.iptel.org/ser/">http://www.iptel.org/ser</ulink>.
85
+	    Version of this document is $Id$.
85 86
 	</releaseinfo>
86 87
     </bookinfo>
87
-    
88
+
88 89
     <toc></toc>
89 90
     
90 91
     <chapter id="general">
... ...
@@ -93,7 +102,7 @@
93 93
 	    <title>About <acronym>SIP</acronym> Express Router (<acronym>SER</acronym>)</title>
94 94
 	    <para>
95 95
 		SIP Express Router (<acronym>SER</acronym>) is an industrial-strength, free VoIP 
96
-		server based on the session initiation protocol (<acronym>SIP</acronym> RFC3261). 
96
+		server based on the Session Initiation Protocol (<acronym>SIP</acronym>, RFC3261). 
97 97
 		It is engineered to power <acronym>IP</acronym> telephony infrastructures up to large 
98 98
 		scale. The server keeps track of users, sets up VoIP sessions, 
99 99
 		relays instant messages and creates space for new plug-in applications. 
... ...
@@ -113,12 +122,12 @@
113 113
 	    </para>
114 114
 	    <para>
115 115
 		Its performance and robustness allows it to serve millions of users 
116
-		and accommodate needs of very large operators. With a $3000 dual-CPU, the 
116
+		and accommodate needs of very large operators. With a $3000 dual-CPU PC, the 
117 117
 		<acronym>SIP</acronym> Express Router is able to power <acronym>IP</acronym> telephony services in an area 
118 118
 		as large as the Bay Area during peak hours. Even on an IPAQ <acronym>PDA</acronym>, the server 
119 119
 		withstands 150 calls per second (<acronym>CPS</acronym>)! The server has been powering our 
120 120
 		iptel.org free <acronym>SIP</acronym> site withstanding heavy daily load that is further 
121
-		increasing with the popularity of Microsoft's Messenger.  
121
+		increasing with the popularity of Microsoft's Windows Messenger.  
122 122
 	    </para>
123 123
 	    <para>
124 124
 		The <acronym>SIP</acronym> Express Router is extremely configurable to allow the creation of 
... ...
@@ -131,12 +140,11 @@
131 131
 		<application moreinfo="none">ser</application> can be also
132 132
 		used with contributed applications. Currently, 
133 133
 		<application moreinfo="none">serweb</application>, a
134
-		<application moreinfo="none">ser</application> web interface
134
+		<application moreinfo="none">ser</application> web interface,
135 135
 		and <application moreinfo="none">SIPSak</application>
136
-		diagnostic tools are available. Visit our site, 
137
-		<ulink url="http://www.iptel.org/">http://www.iptel.org/</ulink>
138
-		, for more information on
139
-		contributed packages.
136
+		diagnostic tool are available. Visit our site, 
137
+		<ulink url="http://www.iptel.org/">http://www.iptel.org/</ulink>, 
138
+                for more information on contributed packages.
140 139
 	    </para>
141 140
 	</section> 
142 141
 
... ...
@@ -154,6 +162,13 @@
154 154
 		technological information, is a best proof of interest. Thousands 
155 155
 		of hits come every day from the whole Internet.
156 156
 	    </para>
157
+	    <para>
158
+		The iptel.org site, powered by SER, offers SIP services on the public 
159
+		Internet. Feel free to apply for a free SIP account at
160
+		<ulink url="http://www.iptel.org/user/">http://www.iptel.org/user/
161
+		</ulink>
162
+	    </para>
163
+
157 164
 	    
158 165
 	</section> <!-- iptel -->
159 166
 	<section id="serfeatures">
... ...
@@ -161,34 +176,44 @@
161 161
 	    <para>
162 162
 		Based on the latest standards, the <acronym>SIP</acronym> Express Router (<acronym>SER</acronym>) includes 
163 163
 		support for registrar, proxy and redirect mode. Further it acts as 
164
-		an application server with support for <acronym>CPL</acronym>, instant messaging and 
165
-		presence including a <acronym>2G/SMS</acronym> gateway, a call control policy 
164
+		an application server with support for instant messaging and 
165
+		presence including a <acronym>2G/SMS</acronym> and Jabber gateway, a call control policy 
166 166
 		language, call number translation, private dial plans and accounting, 
167
-		authorization and authentication (<acronym>AAA</acronym>) services. <acronym>SER</acronym> runs on Sun/Solaris, 
168
-		PC/Linux, IPAQ/Linux platforms and supports  both <acronym>IPv4</acronym> and <acronym>IPv6</acronym>. 
167
+		authorization and authentication (<acronym>AAA</acronym>) services. <application>SER</application> runs on Sun/Solaris, 
168
+		PC/Linux, PC/BSD, IPAQ/Linux platforms and supports  both <acronym>IPv4</acronym> and <acronym>IPv6</acronym>. 
169 169
 		Hosting multiple domains and database redundancy is supported.
170 170
 	    </para>
171 171
 	    <para>
172 172
 		Other extensions are underway: presence server, firewall control and more.
173 173
 	    </para>
174 174
 	    <para>
175
-		ser has been carefully engineered with the following design objectives in mind:
175
+		<application>ser</application> has been carefully engineered with the following 
176
+		design objectives in mind:
176 177
 		<itemizedlist>
177 178
 		    <listitem>
178 179
 			<para>
179
-			    <emphasis>Speed</emphasis> - With SER, thousands of calls per seconds are achievable 
180
+			    <emphasis>Speed</emphasis> - With <application>ser</application>, 
181
+			    thousands of calls per seconds are achievable 
180 182
 			    even on low-cost platforms. This competitive capacity allows 
181 183
 			    setting up networks which are inexpensive and easy to manage 
182
-			    due to low number of devices required. The speed has been 
183
-			    achieved by extensive code optimization, usage of customized code, 
184
+			    due to low number of devices required. The processing capacity 
185
+			    makes dealing with many stress factors easier. The stress
186
+			    factors may include but are not limited to broken configurations and implementations,
187
+			    boot avalanches on power-up, high-traffic applications such as presence, 
188
+			    redundancy replications and denial-of-service attacks.
189
+			</para>
190
+			<para> The speed has been achieved by extensive code optimization, use of customized code, 
184 191
 			    <acronym>ANSI C</acronym> combined with assembly instructions and leveraging latest 
185
-			    <acronym>SIP</acronym> improvements. When powered by a dual-CPU Linux PC, <application>ser</application> is able
186
-to serve call signaling Bay Area population.
192
+			    <acronym>SIP</acronym> improvements. When powered by a dual-CPU Linux PC, 
193
+			    <application>ser</application> is able to process thousands of calls per second,
194
+			    capacity needed to serve call signaling demands of Bay Area population.
195
+			   
187 196
 			</para>
188 197
 		    </listitem>
189 198
 		    <listitem>
190 199
 			<para>
191
-			    <emphasis>Flexibility</emphasis> - <acronym>SER</acronym> allows its users to define its behavior. 
200
+			    <emphasis>Flexibility</emphasis> - <application>SER</application> allows its users 
201
+			    to define its behavior. 
192 202
 			    Administrators may write textual scripts which determine <acronym>SIP</acronym> routing 
193 203
 			    decisions, the main job of a proxy server. They may use the script to 
194 204
 			    configure numerous parameters and introduce additional logic. For example, 
... ...
@@ -200,12 +225,12 @@ to serve call signaling Bay Area population.
200 200
 		    </listitem>
201 201
 		    <listitem>
202 202
 			<para>
203
-			    <acronym>Extensibility</acronym> - <acronym>SER</acronym>'s extensibility allows linking of 
203
+			    <emphasis>Extensibility</emphasis> - <application>SER</application>'s extensibility allows linking of 
204 204
 			    new C code to ser to 
205 205
 			    redefine or extend its logic. The new code can be developed independently 
206
-			    on <acronym>SER</acronym> core and linked to it in run-time. The concept is similar to 
206
+			    on <application>SER</application> core and linked to it in run-time. The concept is similar to 
207 207
 			    the module concept known for example in Apache Web server. Even such essential parts such 
208
-			    as transaction management have been developed as modules to keep the <acronym>SER</acronym> core 
208
+			    as transaction management have been developed as modules to keep the <application>SER</application> core 
209 209
 			    compact and fast.
210 210
 			</para>
211 211
 		    </listitem>
... ...
@@ -214,8 +239,8 @@ to serve call signaling Bay Area population.
214 214
 			    <emphasis>
215 215
 				Portability.
216 216
 			    </emphasis>
217
-			    Ser has been written in ANSI C. It has been extensively tested on PC/Linux and 
218
-			    Sun/Solaris. 
217
+			    <application>ser</application> has been written in ANSI C. It has been extensively tested 
218
+			    on PC/Linux and Sun/Solaris. Ports to BSD and IPAQ/Linux exist.
219 219
 			</para>
220 220
 		    </listitem>
221 221
 		    <listitem>
... ...
@@ -223,11 +248,19 @@ to serve call signaling Bay Area population.
223 223
 			    <emphasis>			   
224 224
 				Interoperability. 
225 225
 			</emphasis>
226
-			Ser is based on open SIP standard. It has undergone extensive testing with 
227
-			    products of other vendors. It powers the public iptel.org site 24 hours a day, 356 days a year 
226
+			<application>ser</application> is based on the open <acronym>SIP</acronym> standard. 
227
+			    It has undergone extensive tests with products of other vendors both in iptel.org
228
+			    labs and in the SIP Interoperability Tests (SIPIT). <application>ser</application> 
229
+			    powers the public iptel.org site 24 hours a day, 356 days a year 
228 230
 			    serving numerous SIP implementations using this site.
229 231
 			</para>
230 232
 		    </listitem>
233
+		    <listitem>
234
+			<para>
235
+			    <emphasis>Small size.</emphasis>
236
+			    Footprint of the core is 300k, add-on modules take up to 630k.
237
+			</para>
238
+		    </listitem>
231 239
 		</itemizedlist>
232 240
 	    </para>
233 241
 	</section> <!-- serfeatures -->
... ...
@@ -254,9 +287,9 @@ to serve call signaling Bay Area population.
254 254
 		    SIP Express Router has been engineered to power large scale networks: its capacity can deal 
255 255
 		    with large number of customers under high load caused by modern applications. Premium 
256 256
 		    performance allows deploying a low number of boxes while keeping investments and operational 
257
-		    expenses extremely low. ISPs can start by providing instant messaging services on this 
258
-		    standardized platform. This can be combined with the SIP-to-SMS gateway service also supported 
259
-		    by SER. In a second step VoIP services can be added in addition to voicemail services and  UMS.
257
+		    expenses extremely low. ISPs can offer SIP-based instant messaging services and interface
258
+		    them to other instant messaging systems (Jabber, SMS). VoIP can be easily integrated along
259
+		    with added-value services, such as voicemail.
260 260
 		</para>
261 261
 	    </section> <!-- Added-value ISP -->
262 262
 	    <section>
... ...
@@ -264,12 +297,13 @@ to serve call signaling Bay Area population.
264 264
 		<para>
265 265
 		    Internet Telephony Service Providers (ITSPs) offer the service of interconnecting 
266 266
 		    Internet telephony users using PC softphone or appliances to PSTN. Particularly with 
267
-		    long-distance and international calls, substantial savings can be achieved by 
267
+		    long-distance and international calls, competitive pricing can be achieved by 
268 268
 		    routing the calls over the Internet.
269 269
 		</para>
270 270
 		<para>
271 271
 		    SIP Express Router can be easily configured to serve pc2phone users, distribute
272
-		    calls to geographically appropriate PSTN gateway, act as a security barrier and keep track of charging. 
272
+		    calls to geographically appropriate PSTN gateway, act as a security barrier and keep 
273
+		    track of charging. 
273 274
 		</para>
274 275
 	    </section>
275 276
 	    <section>
... ...
@@ -296,15 +330,15 @@ to serve call signaling Bay Area population.
296 296
 	<section id="aboutsip">
297 297
 	    <title>About SIP Technology</title>
298 298
 	    <para>
299
-		The SIP protocol family is the technology which has succeeded in realizing the vision of the 
300
-		integrated services. With SIP, Internet users can easily contact each other; figure out 
299
+		The SIP protocol family is the technology which integrates services. 
300
+		With SIP, Internet users can easily contact each other; figure out 
301 301
 		willingness to have a conversation and couple different applications such as VoIP, video 
302 302
 		and instant messaging. Integration with added-value services is seamless and easy. Examples 
303 303
 		include integration with web (click-to-dial), E-mail (voice2email, UMS), and PSTN-like 
304 304
 		services (conditional forwarding).
305 305
 	    </para>
306 306
 	    <para>
307
-		The core piece of the technology is the Session Initiation Protocol (SIP) standardized by IETF. 
307
+		The core piece of the technology is the Session Initiation Protocol (SIP, RFC3261) standardized by IETF. 
308 308
 		Its main function is to establish communication sessions between users connected to the public 
309 309
 		Internet and identified by e-mail-like addresses. One of SIP's greatest features is its transparent 
310 310
 		support for multiple applications: the same infrastructure may be used for voice, video, gaming 
... ...
@@ -331,24 +365,22 @@ to serve call signaling Bay Area population.
331 331
 		    </listitem>
332 332
 		    <listitem>
333 333
 			<para>
334
-			    Loose routing
335
-			</para>
336
-		    </listitem>
337
-		    <listitem>
338
-			<para>
339 334
 			    Script processing of multiple branches on forking
340 335
 			</para>
341 336
 
342 337
 			<warning>
343 338
 			    <para>
344
-				ser's request processing language allows to make request decisions based on current URI. 
339
+				<application>ser</application>'s request processing language allows 
340
+				to make request decisions based on current URI. 
345 341
 				When a request if forked to multiple destinations, only the first branch's URI is used as 
346 342
 				input for script processing. This might lead to unexpected results. Whenever a URI resolves 
347 343
 				to multiple different next-hop URIs, only the first is processed which may result in handling 
348 344
 				not appropriate for the other branch. For example, a URI might resolve to an IP phone SIP 
349 345
 				address and PSTN gateway SIP address. If the IP phone address is the first, then script 
350
-				execution ignores the second branch and vice versa. That might result in ignoring of 
351
-				gateway admission control rules or applying them unnecessarily to non-gateway destinations.
346
+				execution ignores the second branch. If a script includes checking gateway address in
347
+				request URI, the checks never match. That might result in ignoring of 
348
+				gateway admission control rules or applying them unnecessarily to non-gateway 
349
+				destinations.
352 350
 			    </para>
353 351
 			</warning>
354 352
 		    </listitem>
... ...
@@ -361,16 +393,108 @@ to serve call signaling Bay Area population.
361 361
 		</ulink>.
362 362
 	    </para>
363 363
 	</section> <!-- limitations -->
364
-	<section id="contact">
365
-	    <title>Contact and Licencing</title>
364
+	<section id="licensing">
365
+	    <title>Licensing</title>
366 366
 	    <para>
367
-		For any additional information, send an inquiry to info@iptel.org. 
368
-		Licensing conditions other than GPL are available on request. If
369
-		you need a help with ser, send an email to serhelp@iptel.org.
370
-		Report bugs at 
371
-		<ulink url="http://developer.berlios.de/bugs/?group_id=480">
372
-		    http://developer.berlios.de/bugs/?group_id=480
373
-		</ulink>
367
+		<application>ser</application> is freely available under terms and
368
+		conditions of the GNU General Public License.
369
+	    </para>	
370
+	    <!-- COPYING -->
371
+	    <screen>
372
+	    	    &gpllicense;
373
+	    </screen>
374
+	    
375
+	</section>
376
+	<section id="support">
377
+	    <title>Obtaining Technical Assistance</title>
378
+	    <para>
379
+		We offer best-effort free support for <application>ser</application>.
380
+		"best-effort" means that we try to solve your problems via email
381
+		as soon as we can, subject to available manpower. If you need
382
+		commercial support, contact info@iptel.org.
383
+	    </para>
384
+	    <para>
385
+		To receive feedback to your inquiries, we recommend you to subscribe
386
+		to the <emphasis>serusers</emphasis> mailing list and post your
387
+		queries there. This mailing list is set up for mutual help by
388
+		the community of <application>ser</application> users and developers.
389
+	    </para>
390
+	    <itemizedlist>
391
+		<title>Mailing List Instructions</title>
392
+		<listitem>
393
+		    <para>
394
+			Public archives and subscription form:
395
+			<ulink url="http://mail.iptel.org/mailman/listinfo/serusers">
396
+			    http://mail.iptel.org/mailman/listinfo/serusers
397
+			</ulink>			
398
+		    </para>
399
+		</listitem>
400
+		<listitem>
401
+		    <para>
402
+			To post, send an email to serusers@iptel.org
403
+		    </para>
404
+		</listitem>
405
+		<listitem>
406
+		    <para>
407
+			If you think you encountered an error, please submit the
408
+			following information to avoid unnecessary round-trip times:			
409
+			<itemizedlist>
410
+			    <listitem>
411
+				<para>
412
+				    Name and version of your operating system --
413
+				    you can obtain it by calling
414
+				    <command>uname -a</command>
415
+				</para>
416
+			    </listitem>
417
+			    <listitem>
418
+				<para>
419
+				    <application>ser</application> distribution: 
420
+				    release number and package				    
421
+				</para>
422
+			    </listitem>
423
+			    <listitem>
424
+				<para>
425
+				    <application>ser</application> build -- 
426
+				    you can obtain it by calling 
427
+				    <command moreinfo="none">ser -V</command>
428
+				</para>
429
+			    </listitem>
430
+			    <listitem>
431
+				<para>
432
+				    Your <application>ser</application> configuration file
433
+				</para>
434
+			    </listitem>
435
+			    <listitem>
436
+				<para>
437
+				    <application>ser</application> logs -- with default settings
438
+				    few logs are printed to <command>syslog</command> facility which
439
+				    typically dumps them to 
440
+				    <filename moreinfo="none">/var/log/messages</filename>. To 
441
+				    enable detailed logs dumped to <filename>stderr</filename>,
442
+				    apply the following configuration options: <command moreinfo="none">
443
+				    debug=8, log_stderror=yes, fork=no</command>.
444
+				</para>
445
+			    </listitem>
446
+			    <listitem>
447
+				<para>
448
+				    Captured SIP messages -- you can obtain them 
449
+				    using tools such as <application>ngrep</application>
450
+				    or <application moreinfo="none">ethereal</application>.
451
+				</para>
452
+			    </listitem>
453
+			</itemizedlist>
454
+		    </para>
455
+		    
456
+		</listitem>
457
+	    </itemizedlist>	    
458
+	
459
+	    <para>
460
+		If you are concerned about your privacy and do not wish your
461
+		queries to be posted and archived publicly, you may post to
462
+		serhelp@iptel.org. E-mails to this address are only forwarded
463
+		to iptel.org's <application>ser</application> development team.
464
+		However, as the team is quite busy you should not be surprised
465
+		to get replies with considerable delay.
374 466
 
375 467
 	    </para>
376 468
 	</section>
... ...
@@ -380,7 +504,7 @@ to serve call signaling Bay Area population.
380 380
 	    <para>
381 381
 		Most up-to-date information including latest and most complete version
382 382
 		of this documentation is always available at our website,
383
-		<ulink url="http://www.iptel.org/ser/">http://www.iptel.org/ser/</ulink>
383
+		<ulink url="http://www.iptel.org/ser/">http://www.iptel.org/ser/</ulink>.
384 384
 		For information on how to install ser, read INSTALL.
385 385
 		SGML documentation is available in the 'doc' directory.
386 386
 		A SIP tutorial (slide set) is available at 
... ...
@@ -401,130 +525,79 @@ to serve call signaling Bay Area population.
401 401
 		location service or enforce static routing to a gateway. Real-world
402 402
 		deployments actually ask for quite complex routing logic, which
403 403
 		needs to reflex static routes to PSTN gateways, dynamic routes
404
-		to registered users, authentication policy, etc.
404
+		to registered users, authentication policy, capabilities of
405
+		SIP devices, etc.
405 406
 	    </para>
406 407
 	    <para>
407 408
 		SER's answer to this need for routing flexibility is a routing
408
-		language, which allows administrators to define the SIP routing
409
-		logic in a detailed manner. They can for example easily
409
+		language, which allows administrators to define the SIP request
410
+		processing logic in a detailed manner. They can for example easily
410 411
 		split SIP traffic by method or destination, perform user location, 
411 412
 		trigger authentication, verify access permissions, and so on.
412 413
 	    </para>
413 414
 	    <para>
414
-		The primary building block of the routing language are actions. There are 
415
-		built-in actions (like forward for stateless forwarding) as 
416
-		well as external actions supplied in shared library modules. The actions can be combined in composed statements 
417
-		({a1(); a2();}). The language includes conditional statements and subroutines (recursive too). 
415
+		The primary building block of the routing language are <emphasis>actions</emphasis>. 
416
+		There are built-in actions (like <command>forward</command> for stateless forwarding
417
+		or <command>strip</command> for stripping URIs) as 
418
+		well as external actions imported from shared library modules. All actions can 
419
+		be combined in compound actions by enclosing them in braces, 
420
+		e.g. <command>{a1(); a2();}</command>. 
421
+		Actions are aggregated in one or more <emphasis>route blocks</emphasis>.
422
+		Initially, only the default routing block denoted by <command>route[0]</command>
423
+		is called. Other routing blocks can be called by the action
424
+		<command>route(blocknumber)</command>, recursion is permitted.
425
+		The language includes <emphasis>conditional statements</emphasis>. 
418 426
 	    </para>
419 427
 
420 428
 	    <para>
421
-		The routing script is executed for every received request in sequential order. Actions may return 
422
-		positive/negative/zero value. 
429
+		The routing script is executed for every received request in sequential order. 
430
+		Actions may return positive/negative/zero value. 
423 431
 
424 432
 		Positive values are considered success and evaluated as
425 433
 		TRUE in conditional expressions. Negative values are considered FALSE. 
426
-		Script processing may be explicitly exited 
427
-		by calling "break". 
428
-
429
-		Zero value means error and stops processing the script. 
430 434
 
431
-		One might jump to another route[x] block by calling route(x) (similar to function calling).
435
+		Zero value means error and leaves execution of currently processed
436
+		route block. The route block is left too, if <command>break</command> is explicitly
437
+		called from it.
432 438
 
433 439
 	    </para>
434 440
 	    <para>
435
-		The easiest way for ser users to affect routing logic is
436
-		to determine next hop statically. A useful scenario is
437
-		routing to a gateway whose static IP address is well known.
438
-		To configure static routing, simply use the commands
439
-		forward( IP_address, port_number>) for stateless
440
-		forwarding or t_relay_to( IP_address, port_number )
441
-		for stateful forwarding.
441
+		The easiest and still very useful way for <application>ser</application>
442
+		users to affect request routing logic is
443
+		to determine next hop statically. An example is
444
+		routing to a PSTN gateway whose static IP address is well known.
445
+		To configure static routing, simply use the action
446
+		<command>forward( IP_address, port_number)</command>.
447
+		This action forwards an incoming request "as is" to the
448
+		destination described in action's parameters.
442 449
 	    </para>
443 450
 
444 451
 	    <example>
445
-		<title>Stateless versus stateful forwarding</title>
452
+		<title>Static Forwarding</title>
446 453
 		<programlisting format="linespecific">
447 454
 # if requests URI is numerical and starts with
448
-# zero, forward statelessly, otherwise forward 
449
-# statefully
455
+# zero, forward statelessly to a static destination
450 456
 
451 457
 if (uri=~"^sip:0[0-9]*@iptel.org) {
452
-    # statelessly
453 458
     forward( 192.168.99.3, 5080 );
454
-} else {
455
-    # statefully
456
-    t_relay_to( "192.168.99.3", "5080" );
457
-}
459
+} 
458 460
 		</programlisting>
459 461
 	    </example>
460
-	</section>
461
-	
462
-	<section>
463
-	    <title>URI Rewriting</title>
464 462
 
465 463
 	    <para>
466
-		A powerful tool for affecting routing logic is changing
467
-		request URI. This can be done with any of built-in commands
468
-		<command>rewriteuri</command>, 
469
-		<command>rewritehost</command>, 
470
-		<command>rewritehostport</command>, 
471
-		<command>rewriteuser</command>, 
472
-		<command>rewriteuserpass</command> and 
473
-		<command>rewriteport</command>. All these commands
474
-		rewrite request URI or a part of it. When later in a ser script
475
-		a forwarding command is encountered, the command forwards
476
-		the request to address in the rewritten URI.
464
+		However, static forwarding is not sufficient in many cases.
465
+		Users desire mobility and change their location frequently.
466
+		Lowering costs for termination of calls in PSTN requires
467
+		locating a least-cost gateway. Which next-hop is taken may
468
+		depend on user's preferences. These and many other scenarios
469
+		need the routing logic to be more dynamic. We describe in
470
+		<xref linkend="conditions"> how to make request processing
471
+		subject to various conditions and in 
472
+		<xref linkend="urirewriting"> how to determine next SIP hop.
477 473
 	    </para>
478
-	    <para>Two URI-rewriting commands are of special importance
479
-		for implementation of dialing plans. <command>prefix(s)
480
-		</command>, inserts 
481
-		a string "s" in front of SIP address and 
482
-		<command>strip(n)</command> takes
483
-		away the first "n" characters of a SIP address.
484
-	    </para>
485
-	    
486
-	    <example>
487
-		<title>Rewriting URIs</title>
488
-		<programlisting format="linespecific">
489
-if (uri=~"dan@foo.bar") {
490
-    rewriteuri("sip:bla@somewherelse.com")
491
-    # forward statelessly
492
-    forward( dst:uri, dst:port);
493
-}
494
-		</programlisting>
495
-	    </example>
496
-
497
-	    <para>
498
-		Commands exported by external modules can change URI too.
499
-		The most important application is changing URI using the
500
-		user location database. The command 
501
-		<command>lookup(table)</command> rewrites
502
-		current URI with a value stored previously during SIP
503
-		registration. If there is no registration, the 
504
-		command returns negative value.
505
-	    </para>
506
-	    <example>
507
-		<title>Rewriting URIs Using User Location Database</title>
508
-		<programlisting format="linespecific">
509
-# store user location if a REGISTER appears
510
-if (method=="REGISTER") {
511
-   save("mydomain1");
512
-} else {
513
-# try to use the previously registered contacts to
514
-# determine next hop
515
-   if(lookup("mydomain1")) {
516
-     # if found, forward there...
517
-     t_relay();
518
-   } else {
519
-     sl_send_reply("404", "Not Found" );
520
-   };
521
-};
522
-		</programlisting>
523
-	    </example>
524
-
525
-	</section> <!-- URI rewriting -->
474
+	</section>
526 475
 
527
-	<section>
476
+	<section id="conditions">
528 477
 	    <title>Conditional Statements</title>
529 478
 	    <para>
530 479
 		A very useful feature is the ability to make routing
... ...
@@ -533,55 +606,92 @@ if (method=="REGISTER") {
533 533
 		served and foreign domains, IP and PSTN routes,
534 534
 		it may split traffic by method or username, it
535 535
 		may determine whether a request should be authenticated
536
-		or not, etc.
536
+		or not, etc. <application moreinfo="none">ser</application>
537
+		allows administrators to form conditions based on
538
+		properties of processed request, such as method or uri,
539
+		as well as on virtually any piece of data on the
540
+		Internet.
537 541
 	    </para>
538 542
 	    <example>
539 543
 		<title>Conditional Statement</title>
540 544
 		<para>
541 545
 		    This example shows how a conditional statement is
542
-		    used to selectively authenticate REGISTER requests.
546
+		    used to split incoming requests between a PSTN
547
+		    gateway and a user location server based on
548
+		    request URI.
543 549
 		</para>
544 550
 		<programlisting format="linespecific">
545
-# we want to authentication only registrations;
546
-# no other request, such as INVITE, will be authenticated
547
-# because we want to accept anonymous incoming calls
548
-if (method=="REGISTER") {
549
-
550
-    # are authentication credential valid ? ...
551
-    if (!www_authorize("iptel.org", "subscriber")) {
552
-        # .... they are not, challenge user and stop processing
553
-
554
-        www_challenge("iptel.org", "0");
555
-        break;
556
-    };
557
-
558
-# ... credentials valid -> save a new entry
559
-# in user location database
560
-
561
-    save("location");
551
+# if request URI is numerical, forward the request to PSTN gateway...
552
+if (uri=~"^sip:[0-9]+@foo.bar") { # match using a regular expression
553
+    forward( gateway.foo.bar, 5060 );
554
+} else { # ... forward the request to user location server otherwise
555
+    forward( userloc.foo.bar, 5060 );
562 556
 };
563 557
 		</programlisting>
564 558
 	    </example>
565
-	    
566
-	    <section>
559
+
560
+	    <para>
561
+		Conditional statements in <application>ser</application> scripts may depend
562
+		on a variety of  expressions. The simplest expressions are 
563
+		action calls. They return true if they completed successfully or false otherwise. 
564
+		An example of an action frequently used in conditional statements is
565
+		<command moreinfo="none">search</command> imported from textops module.
566
+		<command moreinfo="none">search</command> action leverages textual
567
+		nature of SIP and compares SIP requests against a regular expression.
568
+		The action returns true if the expression matched, false otherwise.
569
+		<example>
570
+		    <title>Use of <command>search</command> Action in Conditional Expression</title>
571
+		    <programlisting format="linespecific">
572
+# prevent strangers from claiming to belong to our domain;
573
+# if sender claims to be in our domain in From header field,
574
+# better authenticate him 
575
+if (search("(f|From): .*@mydomain.com)) {
576
+    if (!(proxy_authorize("mydomain.com" /* realm */,"subscriber" /* table name */ ))) {
577
+           proxy_challenge("mydomain.com /* ream */, "1" /* use qop */ );
578
+           break;
579
+    }
580
+}
581
+ 		    </programlisting>
582
+		</example>
583
+	    </para>
584
+	    <para>
585
+		As modules may be created, which export new functions, there is virtually
586
+		no limitation on what functionality <application moreinfo="none">ser</application>
587
+		conditions are based on. Implementers may introduce new actions whose
588
+		return status depends on request content or any external data as well. Such actions
589
+		can query SQL, web, local file systems or any other place which can provide
590
+		information wanted for request processing.
591
+	    </para>
592
+	    <para>
593
+		Furthermore, many request properties may be examined using existing built-in operands
594
+		and operators. Available left-hand-side operands and legal combination with
595
+		operators and right-hand-side operands are described in <xref linkend="logicalexpr">.
596
+		Expressions may be grouped together using logical operators:
597
+		negation (<command>!</command>), AND (<command>&&</command>), OR (<command moreinfo="none">
598
+		||</command> and precedence parentheses (<command>()</command>).
599
+	    </para>
600
+
601
+	    <section id="operators">
567 602
 		<title>Operators and Operands</title>
568 603
 		<para>
569 604
 		    There is a set of predefined operators and operands
570
-		    in ser, which in addition to actions, may be evaluated
605
+		    in ser, which in addition to actions may be evaluated
571 606
 		    in conditional expressions. 
572 607
 		</para>
573 608
 		<para>
574
-		    Operands, which ser understands are the following:
609
+		    Left hand-side operands, which <application>ser</application>
610
+		    understands are the following:
575 611
 		    <itemizedlist>
576 612
 			<listitem>
577 613
 			    <para>
578
-				method, which refers to requests method
614
+				<emphasis>method</emphasis>, which refers to 
615
+				request method
579 616
 				such as REGISTER or INVITE
580 617
 			    </para>
581 618
 			</listitem>
582 619
 			<listitem>
583 620
 			    <para>
584
-				uri, which refers to current request URI, i
621
+				<emphasis>uri</emphasis>, which refers to current request URI,
585 622
 				such as 
586 623
 				"sip:john.doe@foo.bar"
587 624
 				<note>
... ...
@@ -595,10 +705,16 @@ if (method=="REGISTER") {
595 595
 			</listitem>
596 596
 			<listitem>
597 597
 			    <para>
598
-				scr_ip, which referes to IP address from 
598
+				<emphasis>scr_ip</emphasis>, which refers to IP address from 
599 599
 				which a request came.
600 600
 			    </para>
601 601
 			</listitem>
602
+			<listitem>
603
+			    <para>
604
+				<emphasis>dst_ip</emphasis> refers to server's IP address 
605
+				at which a request was received
606
+			    </para>
607
+			</listitem>
602 608
 		    </itemizedlist>
603 609
 		</para>
604 610
 		<para>
... ...
@@ -612,20 +728,133 @@ if (method=="REGISTER") {
612 612
 			</listitem>
613 613
 			<listitem>
614 614
 			    <para>
615
-				=~ stand for regular expression match
615
+				=~ stands for regular expression matching
616 616
 			    </para>
617 617
 			</listitem>
618 618
 			<listitem>
619 619
 			    <para>
620
-				logical operators: and, or, negation
620
+				logical operators: and, or, negation, parentheses
621 621
 				(C-notation for the operators may be used too)
622 622
 			    </para>
623 623
 			</listitem>
624 624
 		    </itemizedlist>
625 625
 		</para>
626
+
627
+	    <table id="logicalexpr">
628
+		<title>Valid Combinations of Operands and Operators in Expressions</title>
629
+		<tgroup cols="4">
630
+		    <thead>
631
+			<row>
632
+			    <entry>
633
+				left-hand-side operand
634
+			    </entry>			    
635
+			    <entry>
636
+				valid operators
637
+			    </entry>
638
+			    <entry>
639
+				valid right-hand side operators
640
+			    </entry>
641
+			    <entry>
642
+				examples/comments
643
+			    </entry>
644
+			</row>
645
+
646
+		    </thead>
647
+		    <tbody>
648
+
649
+			<row>
650
+			    <entry>
651
+				method
652
+			    </entry>			    
653
+			    <entry>
654
+				== (exact match), =~ (regular expression matching)
655
+			    </entry>
656
+			    <entry>
657
+				string
658
+			    </entry>
659
+			    <entry>
660
+				method=="INVITE" || method=="ACK" || method=="CANCEL"
661
+			    </entry>
662
+			</row>			
663
+
664
+			<row>
665
+			    <entry>
666
+				uri
667
+			    </entry>			    
668
+			    <entry>
669
+				== (exact match), =~ (regular expression matching)
670
+			    </entry>
671
+			    <entry>
672
+				string
673
+			    </entry>
674
+			    <entry>
675
+				uri=="sip:foo@bar.com" matches only if exactly this uri
676
+				is in request URI
677
+
678
+			    </entry>
679
+			</row>				
680
+
681
+			<row>
682
+			    <entry>
683
+				
684
+			    </entry>			    
685
+			    <entry>
686
+				== (exact match)
687
+			    </entry>
688
+			    <entry>
689
+				myself
690
+			    </entry>
691
+			    <entry>
692
+				
693
+				the expression uri==myself is true if the host part in 
694
+				request URI equals a server name or a server alias (set using
695
+				the alias option in configuration file)
696
+				
697
+			    </entry>
698
+			</row>				
699
+
700
+			<row>
701
+			    <entry>
702
+				src_ip
703
+			    </entry>			    
704
+			    <entry>
705
+				== (match)
706
+			    </entry>
707
+			    <entry>
708
+				IP, IP/mask_length, IP/mask, hostname, myself
709
+			    </entry>
710
+			    <entry>
711
+				src_ip==192.168.0.0/16 matches requests coming from
712
+				a private network
713
+			    </entry>
714
+			</row>
715
+
716
+			<row>
717
+			    <entry>
718
+				dst_ip
719
+				by <application moreinfo="none">ser</application>
720
+			    </entry>			    
721
+			    <entry>
722
+				== (match)
723
+			    </entry>
724
+			    <entry>
725
+				IP, IP/mask_length, IP/mask, hostname, myself
726
+			    </entry>
727
+			    <entry>
728
+				dst_ip==127.0.0.1 matches if a request was received
729
+				via loopback interface
730
+			    </entry>
731
+			</row>
732
+
733
+
734
+		    </tbody>
735
+		</tgroup>
736
+	    </table>
737
+	    
738
+
626 739
 		<example>
627 740
 		    <title>
628
-			Use of ser operators and operands in conditional
741
+			More examples of use of <application>ser</application> operators and operands in conditional
629 742
 			statements
630 743
 		    </title>
631 744
 		    <programlisting format="linespecific">
... ...
@@ -652,15 +881,516 @@ if (search("^(Contact|m): .*@(192\.168\.|10\.|172\.16)")) {
652 652
 # ...
653 653
 </programlisting>
654 654
 		</example>
655
+	    </section> <!-- operators and operands -->
656
+	    <section>
657
+		<title>URI Matching</title>
658
+		<para>URI matching expressions have a broad use in a SIP server
659
+		    and deserve more explanation. Typical uses of
660
+		    URI matching include implementation of numbering plans,
661
+		    domain matching,
662
+		    binding external applications to specific URIs,
663
+		    etc. This section shows examples of typical applications
664
+		    of URI-matching.
665
+		</para>
666
+		<section id="domainmatching">
667
+		    <title>Domain Matching</title>
668
+		    <para>
669
+			One of most important uses of URI matching is deciding
670
+			whether a request is targeted to a served or outside domain.
671
+			Typically, different request
672
+			processing applies. Requests for outside domains
673
+			are simply forwarded to them, whereas
674
+			more complex logic applies to requests for a served domain.
675
+			The logic may include saving user's contacts
676
+			when REGISTER requests are received, forwarding requests
677
+			to current user's location or a PSTN gateways, 
678
+			interaction with external applications, etc.
679
+		    </para>
680
+		    <para>
681
+			The easiest way to decide whether a request belongs
682
+			a served domain is using the <command moreinfo="none">myself</command>
683
+			operand. 
684
+			The expression "uri==myself" returns true if domain name
685
+			in request URI matches name of the host at which
686
+			<application moreinfo="none">ser</application> is
687
+			running. This may be insufficient in cases when
688
+			server name is not equal to domain name for which the server
689
+			is responsible. For example, the "uri==myself" condition
690
+			does not match if a server "sipserver.foo.bar" 
691
+			receives a request for "sip:john.doe@foo.bar". To
692
+			match other names in URI than server's own,
693
+			set up the <varname>alias</varname> configuration
694
+			option. The option may be used multiple times,
695
+			each its use adds a new item to a list of aliases.
696
+			The myself condition returns then  true 
697
+			also for any hostname on the list of aliases.
698
+			<example>
699
+			    <title>Use of uri==myself Expression</title>
700
+			    <programlisting format="linespecific">
701
+# ser powers a domain "foo.bar" and runs at host sipserver.foo.bar;
702
+# Names of served domains need to be stated in the aliases
703
+# option; myself would not match them otherwise and would only
704
+# match requests with "sipserver.foo.bar" in request-URI
705
+alias="foo.bar"
706
+alias="sales.foo.bar"
707
+route[0] {
708
+        if (uri==myself) {
709
+            # the request either has server name or some of the
710
+            # aliases in its URI
711
+            log(1,"request for served domain")
712
+            # some domain-specific logic follows here ....
713
+        } else {
714
+            # aha -- the server is not responsible for this
715
+            # requests; that happens for example with the following URIs
716
+            #  - sip:a@marketing.foo.bar
717
+            #  - sip:a@otherdomain.bar
718
+            log(1,"request for outbound domain");
719
+            # outbound forwarding			  
720
+            t_relay();
721
+        };
722
+}			</programlisting>
723
+		    </example>
724
+		</para>
725
+		<para>
726
+		    It is possible to recognize whether a request belongs to
727
+		    a domain using regular expressions too. Care needs to
728
+		    be paid to construction of regular expressions. URI
729
+		    syntax is rich and an incorrect expression would result
730
+		    in incorrect call processing. The following example shows
731
+		    how an expression for domain matching can be formed.
732
+		    <example id="redomainmatching">
733
+			<title>Domain Matching Using Regular Expressions</title>
734
+			<para>
735
+			    In this example, server named "sip.foo.bar" with
736
+			    IP address 192.168.0.10 is responsible for the
737
+			    "foo.bar" domain. That means, requests with the
738
+			    following hostnames in URI should be matched:
739
+			    <itemizedlist>
740
+				<listitem>
741
+				    <para>
742
+					foo.bar, which is the name of server domain
743
+				    </para>
744
+				</listitem>
745
+				<listitem>
746
+				    <para>
747
+					sip.foo.bar, since it is server's name and some
748
+					devices put server's name in request URI
749
+				    </para>
750
+				</listitem>
751
+				<listitem>
752
+				    <para>
753
+					192.168.0.10, since it is server's IP address and
754
+					some devices put server's IP address in request URI
755
+				    </para>
756
+				</listitem>
757
+			    </itemizedlist>			
758
+			    Note how this regular expression is constructed. In particular:
759
+			    <itemizedlist>
760
+				<listitem>
761
+				    <para>
762
+					User name is optional (it is for example never included
763
+					in REGISTER requests) and there are no restrictions on
764
+					what characters it contains. That is what 
765
+					<emphasis>(.+@)?</emphasis> mandates. 
766
+				    </para>
767
+				</listitem>
768
+				<listitem>
769
+				    <para>
770
+					Hostname must be followed by port number, parameters
771
+					or headers -- that is what the delimiters 
772
+					<emphasis>[:;\?]</emphasis> are good for. If none
773
+					it these follows, the URI must be ended 
774
+					(<emphasis>$</emphasis>). Otherwise, longer hostnames
775
+					such as 192.168.0.101 or foo.bar.otherdomain.com would
776
+					mistakenly match.
777
+				    </para>
778
+				</listitem>
779
+				<listitem>
780
+				    <para>
781
+					Matches are case-insensitive. All hostnames "foo.bar", "FOO.BAR"
782
+					and "FoO.bAr" match.
783
+				    </para>
784
+				</listitem>
785
+			    </itemizedlist>
786
+			</para>
787
+			<programlisting>
788
+if (uri=~"^sip:(.+@)?(192\.168\.0\.10|(sip\.)?foo\.bar)([:;\?].*)?$")
789
+      log(1, "yes, it is a request for our domain");
790
+      break;
791
+ };
792
+			</programlisting>
793
+		    </example>
794
+		</para>
795
+		</section> <!-- domain matching -->
796
+		<section id="numberingplans">
797
+		    <title>Numbering Plans</title>
798
+
799
+		    <para>
800
+			Other use of URI matching is implementation of dialing
801
+			plans. A typical task when designing a dialing plan for SIP networks
802
+			is to distinguish between "pure-IP" and PSTN destinations.
803
+			IP users typically have either alphanumerical or numerical
804
+			usernames. The numerical usernames are convenient for PSTN
805
+			callers who can only
806
+			use numeric keypads. Next-hop destination of IP users is looked up dynamically
807
+			using user location database. On the other hand, PSTN destinations are 
808
+			always indicated by nummerical usernames. Requests to PSTN are statically 
809
+			forwarded to well-known PSTN gateways.
810
+		    </para>
811
+		    <example>
812
+			<title>A simple Numbering Plan</title>
813
+			<para>
814
+			    This example shows a simple dialing plan which reserves
815
+			    dialing prefix "8" for IP users, other numbers
816
+			    are used for PSTN destinations and all other non-nummerical
817
+			    usernames are used for IP users.
818
+			</para>
819
+			<programlisting format="linespecific">
820
+# is it a PSTN destination? (is username nummerical and does not begin with 8?)
821
+if (uri=~"^sip:[0-79][0-9]*@") { # ... forward to gateways then;
822
+      # check first to which PSTN destination the requests goes;
823
+      # if it is US (prefix "1"), use the gateway 192.168.0.1...
824
+      if (uri=~"^sip:1") {
825
+           # strip the leading "1"
826
+           strip(1);
827
+           forward(192.168.0.1, 5060);
828
+      } else {
829
+           # ... use the gateway 10.0.0.1 for all other destinations
830
+           forward(10.0.0.1, 5060);
831
+      }
832
+      break;
833
+} else {
834
+      # it is an IP destination -- try to lookup it up in user location DB
835
+      if (!lookup("location")) {
836
+          # bad luck ... user off-line
837
+          sl_send_reply("404", "Not Found");
838
+          break;
839
+      }
840
+      # user on-line...forward to his current destination
841
+      forward(uri:host,uri:port);
842
+}
843
+			</programlisting>
844
+		    </example>
845
+		</section> <!-- numbering plans -->
655 846
 	    </section>
656 847
 	</section> <!-- conditional statements -->
657 848
 	
849
+	<section id="urirewriting">
850
+	    <title>Request URI Rewriting</title>
851
+
852
+	    <para>
853
+		The ability to give users and services a unique name using URI
854
+		is a powerful tool. It allows users to advertise how to reach
855
+		them, to state to whom they wish to communicate and what services 
856
+		they wish to use.
857
+		Thus, the ability to change URIs is very important and is
858
+		used for implementation of many services. 
859
+		"Unconditional forwarding" from user "boss" to user
860
+		"secretary" is a typical example of application relying
861
+		on change of URI address.
862
+	    </para>
863
+	    <para>
864
+		<application moreinfo="none">ser</application> has the ability
865
+		to change request URI in many ways.
866
+		A script can use any of the following
867
+		built-in actions to change request URI or a part of it:
868
+
869
+		<command>rewriteuri</command>, 
870
+		<command>rewritehost</command>, 
871
+		<command>rewritehostport</command>, 
872
+		<command>rewriteuser</command>, 
873
+		<command>rewriteuserpass</command> and 
874
+		<command>rewriteport</command>. 
875
+		When later in the script
876
+		a forwarding action is encountered, the action forwards
877
+		the request to address in the rewritten URI.
878
+		<example>
879
+		    <title>Rewriting URIs</title>
880
+		    <programlisting format="linespecific">
881
+if (uri=~"dan@foo.bar") {
882
+    rewriteuri("sip:bla@somewherelse.com")
883
+    # forward statelessly to the destination in current URI, i.e.,
884
+    # to sip:bla@somewherelese.com:5060
885
+    forward( uri:host, uri:port);
886
+}
887
+		    </programlisting>
888
+		</example>
889
+	    </para>	    
890
+	    <para>Two more built-in URI-rewriting commands are of special importance
891
+		for implementation of dialing plans and manipulation of dialing
892
+		prefixes. <command>prefix(s)
893
+		</command>, inserts 
894
+		a string "s" in front of SIP address and 
895
+		<command>strip(n)</command> takes
896
+		away the first "n" characters of a SIP address.
897
+		See <xref linkend="urirewritingexamples"> for examples of use of
898
+		built-in URI-rewriting actions.
899
+	    </para>
900
+
901
+	    <para>
902
+		Commands exported by external modules can change URI too
903
+		and many do so.
904
+		The most important application is changing URI using the
905
+		user location database. The command 
906
+		<command>lookup(table)</command> looks up current
907
+		user's location and rewrites user's address with it.
908
+		If there is no registered contact, the 	command returns a negative value.
909
+
910
+
911
+		<example id=rewriteuri>
912
+		    <title>Rewriting URIs Using User Location Database</title>
913
+		    <programlisting format="linespecific">
914
+# store user location if a REGISTER appears
915
+if (method=="REGISTER") {
916
+   save("mydomain1");
917
+} else {
918
+# try to use the previously registered contacts to
919
+# determine next hop
920
+   if(lookup("mydomain1")) {
921
+     # if found, forward there...
922
+     t_relay();
923
+   } else {
924
+     # ... if no contact on-line, tell it upstream
925
+     sl_send_reply("404", "Not Found" );
926
+   };
927
+};
928
+		    </programlisting>
929
+		</example>
930
+	    </para>
931
+	    <para>
932
+		External applications can be used to rewrite URI too.
933
+		The "exec" module provides script actions, which start external programs
934
+		and read new URI value from their output. <command moreinfo="none">exec_uri</command>
935
+		and <command moreinfo="none">exec_user</command> both call an external program,
936
+		pass current URI or its user part to it respectively, wait until it completes,
937
+		and eventually rewrite current URI with its output.
938
+	    </para>
939
+	    <para>
940
+		It is important to realize that <application moreinfo="none">ser</application>
941
+		operates over <emphasis>current URI</emphasis> all the time. If an original
942
+		URI is rewritten by a new one, the original will will be forgotten and the new one will 
943
+		be used in any further processing. In particular, the uri matching operand
944
+		and the user location action <command moreinfo="none">lookup</command>
945
+		always take current URI as input, regardless what the original URI was.
946
+	    </para>
947
+	    <para>
948
+		<xref linkend="urirewritingexamples"> shows how URI-rewriting actions affect 
949
+		an example URI, sip:12345@foo.bar:6060.
950
+		<table id="urirewritingexamples">
951
+		    <title>URI-rewriting Using Built-In Actions</title>
952
+		    <tgroup cols="2">
953
+			<thead>
954
+			    <row>
955
+				<entry>
956
+				    Example Action
957
+				</entry>				
958
+				<entry>
959
+				    Resulting URI
960
+				</entry>
961
+			    </row>
962
+			</thead>
963
+			<tbody>
964
+			    <row>
965
+				<entry>
966
+				    <command moreinfo="none">rewritehost("192.168.0.10")</command> rewrites
967
+				    the hostname in URI, other parts (including port number) remain unaffected.
968
+				</entry>
969
+				<entry>
970
+				    sip:12345@192.168.10:6060
971
+				</entry>
972
+			    </row>
973
+			    <row>
974
+				<entry>
975
+				    <command moreinfo="none">rewriteuri("sip:alice@foo.bar");</command> rewrites
976
+				    the whole URI completely.
977
+				</entry>
978
+				<entry>
979
+				    sip:alice@foo.bar
980
+				</entry>
981
+			    </row>
982
+			    <row>
983
+				<entry>
984
+				    <command moreinfo="none">rewritehostport("192.168.0.10:3040")</command>rewrites 
985
+				    both hostname and port number in URI.
986
+				</entry>
987
+				<entry>
988
+				    sip:12345@192.168.0.10:3040
989
+				</entry>
990
+			    </row>
991
+			    <row>
992
+				<entry>
993
+				    <command moreinfo="none">rewriteuser("alice")</command> rewrites user part of URI.
994
+				</entry>
995
+				<entry>
996
+				    sip:alice@foo.bar:6060
997
+				</entry>
998
+			    </row>
999
+			    <row>
1000
+				<entry>
1001
+				    <command moreinfo="none">rewriteuserpass("alice:pw")</command> replaces the pair
1002
+				    user:password in URI with a new value.
1003
+				</entry>
1004
+				<entry>
1005
+				    sip:alice:pw@foo.bar:6060
1006
+				</entry>
1007
+			    </row>
1008
+			    <row>
1009
+				<entry>
1010
+				    <command moreinfo="none">rewriteport("1234")</command> replaces port number in URI
1011
+				</entry>
1012
+				<entry>
1013
+				    sip:12345@foo.bar:1234
1014
+				</entry>
1015
+			    </row>
1016
+			    <row>
1017
+				<entry>
1018
+				    <command moreinfo="none">prefix("9")</command> inserts a string ahead of user part of URI
1019
+				</entry>
1020
+				<entry>
1021
+				    sip:912345@foo.bar:6060
1022
+				</entry>
1023
+			    </row>
1024
+			    <row>
1025
+				<entry>
1026
+				    <command moreinfo="none">strip(2)</command> removes leading characters from user part of URI
1027
+				</entry>
1028
+				<entry>
1029
+				    sip:345@foo.bar:6060
1030
+				</entry>
1031
+			    </row>
1032
+
1033
+
1034
+			</tbody>
1035
+		    </tgroup>
1036
+		</table>
1037
+	    </para>	    
1038
+	    <para>
1039
+		You can verify whether you understood URI processing by
1040
+		looking at the following example. It rewrites URI
1041
+		several times. The question is what is the final URI to which
1042
+		the script fill forward any incoming request.
1043
+		<example>
1044
+		    <title>URI-rewriting Quiz</title>
1045
+		    <programlisting format="linespecific">
1046
+exec_uri("echo sip:2234@foo.bar; echo > /dev/null");
1047
+strip(2);
1048
+if (uri=~"^sip:2") {
1049
+    prefix("0");
1050
+} else {
1051
+    prefix("1");
1052
+};			
1053
+forward(uri:host, uri:port);
1054
+		    </programlisting>
1055
+		</example>
1056
+	    </para>
1057
+	    <para>
1058
+		The correct answer is the resulting URI will be
1059
+		"sip:134@foo.bar". <command moreinfo="none">exec_uri</command>
1060
+		rewrites original URI to "sip:2234@foo.bar", 
1061
+		<command moreinfo="none">strip(2)</command> takes
1062
+		two leading characters from username away resulting
1063
+		in "34@iptel.org", the condition does not match
1064
+		because URI does not begin with "2" any more,
1065
+		so the prefix "1" is inserted.
1066
+	    </para>
1067
+
1068
+
1069
+	</section> <!-- URI rewriting -->
1070
+
1071
+	<section>
1072
+	    <title>Destination Set</title>
1073
+	    <para>
1074
+		Whereas needs of many scenarios can by accommodated by maintaining
1075
+		a single request URI, some scenarios are better served by
1076
+		multiple URIs. Consider for example a user with address
1077
+		john.doe@iptel.org. The user wishes to be reachable at his 
1078
+		home phone, office phone, cell phone, softphone, etc.