Browse code

minor documentation changes

Jiri Kuthan authored on 28/03/2003 21:23:23
Showing 10 changed files
... ...
@@ -73,19 +73,6 @@ Maturity:   alpha
73 73
 Depends on: -
74 74
 Purpose:    Database emulation in plaintext files
75 75
 
76
-Name:       domain
77
-Owner:      jih
78
-Use:        experimental
79
-Maturity:   beta
80
-Depends on: mysql
81
-Purpose:    Local domain lists and related functions
82
-
83
-Name:       enum
84
-Owner:      jih
85
-Use:        experimental
86
-Maturity:   beta
87
-Depends on: -
88
-Purpose:    Enum support
89 76
 
90 77
 Name:       exec
91 78
 Owner:      jiri
... ...
@@ -102,7 +89,7 @@ Depends on: -
102 102
 Purpose:    Execution of external URI processing logic
103 103
 
104 104
 Name:       extcmd
105
-Owner:      jiri
105
+Owner:      bogdan
106 106
 Use:        experimental
107 107
 Maturity:   alpha
108 108
 Depends on: -
... ...
@@ -171,13 +158,6 @@ Maturity:   stable
171 171
 Depends on: -
172 172
 Purpose:    Printing messages to stdout
173 173
 
174
-Name:       radius_acc
175
-Owner:      ssi
176
-Use:        experimental
177
-Maturity:   beta
178
-Depends on: tm
179
-Purpose:    radius accounting
180
-
181 174
 Name:       registrar
182 175
 Owner:      janakj
183 176
 Use:        regular
... ...
@@ -254,3 +234,34 @@ Use:        experimental
254 254
 Maturity:   alpha
255 255
 Depends on: tm
256 256
 Purpose:    Voicemail interface
257
+
258
+Contributions
259
+-------------
260
+Name:       domain
261
+Owner:      jih
262
+Use:        experimental
263
+Maturity:   beta
264
+Depends on: mysql
265
+Purpose:    Local domain lists and related functions
266
+
267
+Name:       enum
268
+Owner:      jih
269
+Use:        experimental
270
+Maturity:   beta
271
+Depends on: -
272
+Purpose:    Enum support
273
+
274
+Name:       domain
275
+Owner:      jih
276
+Use:        experimental
277
+Maturity:   beta
278
+Depends on: -
279
+Purpose:    support for maintenance of multiple domains
280
+
281
+Name:		permissions
282
+Owner:		tirpi
283
+Use:		experimental
284
+Maturity:	beta
285
+Depends on:	-
286
+Purpose:	hosts.allow-like ACLs
287
+
257 288
new file mode 100644
... ...
@@ -0,0 +1,801 @@
0
+    <chapter>
1
+	<title>Application Writing</title>
2
+	<para>
3
+	    <application moreinfo="none">ser</application> offers several
4
+	    ways to couple its functionality with applications. The coupling
5
+	    is bidirectional: <application moreinfo="none">ser</application>
6
+	    can utilize external applications and external applications can
7
+	    utilize <application moreinfo="none">ser</application>. 
8
+	    An example of the former direction would be an external program
9
+	    determining a least-cost route for a called destination  using 
10
+	    a pricing table. An example of the latter case
11
+	    is a web application for server provisioning.
12
+	    Such an application may want to send instant 
13
+	    messages, query all current user's locations and monitor server
14
+	    health. An existing web interface to <application moreinfo="none">ser</application>,
15
+	    <application moreinfo="none">serweb</application>, actually
16
+	    does all of it. 
17
+	</para>
18
+	<para>
19
+	    The easiest, language-independent way of using external logic 
20
+	    from <application moreinfo="none">ser</application> is provided
21
+	    by exec module. exec module allows <application moreinfo="none">ser</application>
22
+	    to start external programs on receipt of a request. The
23
+	    programs can execute arbitrary logic and/or affect routing of SIP
24
+	    requests. A great benefit of this programming method is it
25
+	    is language-independent. Programmers may use programming languages
26
+	    that are effective or with which they are best familiar.
27
+	    <xref linkend="usingexec"> gives additional examples illustrating 
28
+	    use of the exec module.
29
+	</para>
30
+	<para>
31
+	    Another method for extending <application moreinfo="none">ser</application>
32
+	    capabilities is to write new modules in C. This method takes
33
+	    deeper understanding of <application moreinfo="none">ser</application>
34
+	    internals but gains the highest flexibility. Modules can implement
35
+	    arbitrary brand-new commands upon which <application moreinfo="none">ser</application>
36
+	    scripts can rely on. Guidelines on module programming can be
37
+	    found in <application moreinfo="none">ser</application>
38
+	    programmer's handbook available from iptel.org website.
39
+	</para>
40
+	<para>
41
+	    To address needs of applications wishing to leverage
42
+	    <application moreinfo="none">ser</application>,
43
+	    <application moreinfo="none">ser</application> exports
44
+	    parts of its functionality via its built-in
45
+	    "Application FIFO server". This is a simple textual
46
+	    interface that allows any external applications
47
+	    to communicate with the server. It can be used to
48
+	    send instant messages, manipulate user contacts,
49
+	    watch server health, etc. Programs written in any
50
+	    language (PHP, shell scripts, Perl, C, etc.) can
51
+	    utilize this feature. How to use it is shown in
52
+	    <xref linkend="fifoserver">.
53
+	</para>
54
+
55
+
56
+	<section id="usingexec">
57
+	    <title>Using exec Module</title>
58
+	    <para>
59
+		
60
+		The easiest way is to couple <application moreinfo="none">ser</application>
61
+		with external applications via the <emphasis>exec</emphasis>
62
+		module. This module allows execution of logic and URI manipulation 
63
+		by external applications on request receipt. While very
64
+		simple, many useful services can be
65
+		implemented this way. External applications can be written in
66
+		any programming language and do not be aware of SIP at all.
67
+		<application moreinfo="none">ser</application> interacts with
68
+		the application via standard input/output and environment 
69
+		variables.
70
+		
71
+
72
+	    </para>
73
+	
74
+
75
+	    <para>
76
+		For example, an external shell script
77
+		may send an email whenever a request for a user arrives.
78
+	    </para>
79
+
80
+	    <example>
81
+		<title>Using exec: Step 1</title>
82
+		<programlisting format="linespecific">
83
+# send email if a request for user "jiri" arrives
84
+if (uri=~"^sip:jiri@") {
85
+     exec_msg("echo 'body: call arrived'|mail -s 'call for you' jiri");
86
+}
87
+		</programlisting>
88
+	    </example> <!-- step 1 -->
89
+	    <para>
90
+		In this example, the <command moreinfo="none">exec_msg</command> 
91
+		action starts an external shell. It passes a received SIP request
92
+		to shell's input. In the shell, <command>mail</command> command
93
+		is called to send a notification by e-mail.
94
+		The script however features several simplifications:
95
+		<orderedlist inheritnum="ignore" continuation="restarts">
96
+		    <listitem>
97
+			<para>
98
+			    The email notification does not tell who was calling.
99
+			</para>
100
+		    </listitem>
101
+		    <listitem>
102
+			<para>
103
+			    The logic is not general: it only supports one well-known user (jiri).
104
+			</para>
105
+		    </listitem>
106
+		    <listitem>
107
+			<para>
108
+			    The logic is stateless. It will be executed on
109
+			    every retransmission.
110
+			</para>
111
+		    </listitem>
112
+		    <listitem>
113
+			<para>
114
+			    It is a script fragment not explaining the 
115
+			    context. This particular example may be for
116
+			    example used to report on missed calls.
117
+			</para>
118
+		    </listitem>
119
+		</orderedlist>
120
+		All of these simplifications are addressed step-by-step
121
+		in the following examples.
122
+	    </para>
123
+	    <example> <!-- step 2: who called me -->
124
+		<title>Using exec: Step 2, Who Called Me</title>
125
+		<para>
126
+		    This example shows how to display caller's address
127
+		    in email notification. The trick is easy: process
128
+		    request received on shell programm's input
129
+		    and grep From header field.
130
+		</para>
131
+		<programlisting format="linespecific">
132
+&execstep2;
133
+		</programlisting>
134
+		<para>
135
+			The following two figures show an example SIP request and
136
+			email notification generated on its receipt.
137
+			
138
+		    <screen format="linespecific">
139
+
140
+<![CDATA[
141
+INVITE sip:jiri@iptel.org SIP/2.0
142
+Via: SIP/2.0/UDP 195.37.77.100:5040
143
+Max-Forwards: 10
144
+From: "alice" <sip:alice@iptel.org>;tag=76ff7a07-c091-4192-84a0-d56e91fe104f
145
+To: <sip:jiri@iptel.org>
146
+Call-ID: d10815e0-bf17-4afa-8412-d9130a793d96@213.20.128.35
147
+CSeq: 2 INVITE
148
+Contact: <sip:123.20.128.35:9315>
149
+Content-Type: application/sdp
150
+Content-Length: 451
151
+
152
+--- SDP payload snipped ---
153
+]]>
154
+
155
+		    </screen>
156
+		
157
+		    email received:
158
+		
159
+			<screen format="linespecific">
160
+<![CDATA[
161
+Date: Thu, 12 Dec 2002 14:25:02 +0100
162
+From: root <root@cat.iptel.org>
163
+To: jiri@cat.iptel.org
164
+Subject: request for you
165
+
166
+From: "alice" <sip:alice@iptel.org>;tag=76ff7a07-c091-4192-84a0-d56e91fe104f
167
+request received
168
+]]>
169
+		    </screen>
170
+		</para>
171
+		<para>
172
+		    There is another way to learn values of request
173
+		    header fields, simpler than use of <command moreinfo="none">grep</command>. 
174
+		    <application moreinfo="none">ser</application>
175
+		    parses header fields and passes their values in 
176
+		    environment variables. Their names correspond
177
+		    to header field names prefixed with "SIP_HF_".
178
+		<programlisting format="linespecific">
179
+# send email if a request for "jiri" arrives
180
+if (uri=~"^sip:jiri@") {
181
+     exec_msg("echo request received from $SIP_HF_FROM | mail -s 'request for you' jiri");
182
+};
183
+		</programlisting>
184
+		    Moreover, several other values are passed in environment
185
+		    variables. <varname>SIP_TID</varname> is a token uniquely identifying 
186
+		    transaction, to which the request belongs. <varname>SIP_DID</varname>
187
+		    includes to-tag, and is empty in requests creating a dialog.
188
+		    <varname>SIP_SRCIP</varname> includes IP address, from which the
189
+		    request was sent. <varname>SIP_RURI</varname> and <varname>SIP_ORURI</varname>
190
+		    include current request-uri and original request-uri respectively,
191
+		    <varname>SIP_USER</varname> and <varname>SIP_OUSER</varname> username
192
+		    parts of these. The following listing shows environment variables
193
+		    passed to a shell script on receipt of the previous message:
194
+		    <programlisting format="linespecific">
195
+<![CDATA[
196
+SIP_HF_MAX_FORWARDS=10
197
+SIP_HF_VIA=SIP/2.0/UDP 195.37.77.100:5040
198
+SIP_HF_CSEQ=2 INVITE
199
+SIP_HF_FROM="alice" <sip:alice@iptel.org>;tag=76ff7a07-c091-4192-84a0-d56e91fe104f
200
+SIP_ORUI=sip:jiri@iptel.org
201
+SIP_HF_CONTENT_LENGTH=451
202
+SIP_TID=3b6b8295db0835815847b1f35f3b29b8
203
+SIP_DID=
204
+SIP_RURI=iptel.org
205
+SIP_HF_TO=<sip:jiri@iptel.org>
206
+SIP_OUSER=jiri
207
+SIP_HF_CALLID=d10815e0-bf17-4afa-8412-d9130a793d96@213.20.128.35
208
+SIP_SRCIP=195.37.77.100
209
+SIP_HF_CONTENT_TYPE=application/sdp
210
+SIP_HF_CONTACT=<sip:123.20.128.35:9315>
211
+]]>
212
+		    </programlisting>
213
+				    
214
+		</para>
215
+	    </example> <!-- step 2, who called me -->
216
+
217
+
218
+	    <example>  <!-- step 3,  make the script work for anyone -->
219
+		<title>Using exec: step 3, Make The Script Work For Anyone</title>
220
+		<para>
221
+		    A drawback of the previous example is it works only
222
+		    for one well-known user: request URI is matched against
223
+		    his SIP address and notification is sent to his hard-wired email
224
+		    address. In real scenarios, one would like
225
+		    to enable such a service for all users without enumerating
226
+		    their addresses in the script. The missing piece
227
+		    is translation of user's SIP name to his email address.
228
+		    This information is maintained in subscriber profiles,
229
+		    stored in MySQL by <application moreinfo="none">ser</application>.
230
+		    To translate the username to email address, the executed script
231
+		    needs to query the MySQL database. That is what this example
232
+		    shows. First, an SQL query is constructed which looks up
233
+		    email address of user, for whom a request arrived. If the
234
+		    query does not return a valid email address, the script
235
+		    returns with an error status and <application moreinfo="none">ser</application>
236
+		    script replies with "user does not exist". Otherwise
237
+		    an email notification is sent.
238
+		
239
+		    <programlisting format="linespecific">
240
+&execstep3;
241
+		    </programlisting>
242
+		</para>
243
+	    </example> <!-- step 3 make the script work for anyone -->
244
+	    <example> <!-- step 4, stateful processing -->
245
+		<title>Adding Stateful Processing</title>
246
+		<para>
247
+		    The previously improved example still features a shortcoming.
248
+		    When a message retransmission arrives due to a nework
249
+		    mistake such as lost reply, the email notification is
250
+		    executed again and again. That happens because the script
251
+		    is stateless, i.e., no track of current transactions is
252
+		    kept. The script does not know whether a request is
253
+		    a new or a retransmitted one. Transaction management may
254
+		    be introduced by use of tm module as described in
255
+		    <xref linkend="statefulua">. In the script,
256
+		    <command moreinfo="none">t_newtran</command> is first
257
+		    called to absorb requests retransmission -- if they
258
+		    occur, script does not continue. Then, as in the previous
259
+		    example, an exec module action is called. Eventually,
260
+		    a reply is sent statefully.
261
+		    <note>
262
+			<para>
263
+			    Note carefuly: it is important that the stateful
264
+			    reply processing (<command moreinfo="none">t_reply</command>)
265
+			    is used as opposed to using stateless replies
266
+			    (<command moreinfo="none">sl_send_reply</command>).
267
+			    Otherwise, the outgoing reply would not affect
268
+			    transactional context and would not be resent on
269
+			    receipt of a request retransmission.
270
+			</para>
271
+		    </note>
272
+		    <programlisting format="linespecific">
273
+&execstep4;
274
+		    </programlisting>
275
+		    
276
+		</para>
277
+	    </example> <!-- step 4,  stateful processing -->
278
+	    <example> <!-- step 5, full exec use -->
279
+		<title>Full Example of exec Use</title>
280
+		<para>
281
+		    The last example iteration shows how to integrate the
282
+		    email notification on missed calls with the default
283
+		    <application moreinfo="none">ser</application> script
284
+		    (see <xref linkend="defaultscript">). It generates an
285
+		    email for every call invitation to an off-line user.
286
+		    <programlisting format="linespecific">
287
+&execstep5;
288
+		    </programlisting>
289
+		</para>
290
+		    
291
+		<para>
292
+		    Production "missed calls" services may want to 
293
+		    report on calls missed for other reasons than
294
+		    being off-line too. Particularly, users may wish to be
295
+		    reported calls missed due to call cancellation,
296
+		    busy status or a downstream failure. Such missed
297
+		    calls can be easily reported to syslog or mysql
298
+		    using the acc module (see <xref linkend="missedcalls">).
299
+		    The other, more general way, is to return to request
300
+		    processing on receipt of a negative reply.
301
+		    (see <xref linkend="replyprocessingsection">). Before
302
+		    a request is forwarded, it is labeled to be
303
+		    re-processed in a <command moreinfo="none">reply_route</command>
304
+		    on receipt of a negative reply -- this is what
305
+		    <command moreinfo="none">t_on_negative</command> action
306
+		    is used for. It does not matter what caused the transaction
307
+		    to fail -- it may be unresponsive downstream server,
308
+		    server responding with 6xx, or server sending a 487
309
+		    reply, because an INVITE was cancelled. When any such
310
+		    circumstances occur (i.e., transaction does not complete
311
+		    with a 2xx status code), <command moreinfo="none">reply_route</command>
312
+		    is entered.
313
+		</para>
314
+		<para>
315
+		    The following <application moreinfo="none">ser</application>
316
+		    script reports missed calls in all possible cases.
317
+		    It reports them when a user is off-line as well as when
318
+		    a user is on-line, but INVITE transaction does not complete
319
+		    successfully.
320
+		    <programlisting format="linespecific">
321
+&execstep5b;
322
+		    </programlisting>
323
+		</para>
324
+		
325
+	    </example> <!-- step 5, full exec use -->
326
+
327
+	</section> <!-- using exec -->
328
+
329
+	<section id="fifoserver">
330
+	    <title>Application FIFO Server</title>
331
+
332
+	    <para>
333
+	    Application FIFO server is a very powerful method to program
334
+	    SIP services. The most valuable benefit
335
+	    is it works with SIP-unaware applications
336
+	    written in any programming language. Textual nature of the
337
+	    FIFO interface allows for easy integration with a lot of
338
+	    existing programs. Today, <application moreinfo="none">ser</application>'s
339
+	    complementary web-interface, <application moreinfo="none">serweb</application>,
340
+	    written in PHP, leverages the FIFO interface when displaying
341
+	    and changing user location records stored in server's memory.
342
+	    It uses this interface to send instant messages too, without
343
+	    any knowledge of underlying <acronym>SIP</acronym> stack.
344
+	    Another application relying on the FIFO interface is 
345
+	    <application moreinfo="none">serctl</application>, <application moreinfo="none">ser</application>
346
+	    management utility. The command-line utility can browse
347
+	    server's in-memory user-location database, display 
348
+	    running processes and operational statistics.
349
+	    </para>
350
+	    <para>
351
+		The way the FIFO server works is similar to how 
352
+		<filename moreinfo="none">/proc</filename> filesystem works
353
+		on some operating systems. It provides a human-readable way
354
+		to access <application moreinfo="none">ser</application>'s
355
+		internals. Applications dump their requests into the FIFO
356
+		server and receive a status report when request processing
357
+		completes. <application moreinfo="none">ser</application>
358
+		exports a lot of its functionality located in both the
359
+		core and external modules through the FIFO server. 
360
+		</para>
361
+	    <para>
362
+		FIFO requests are formed easily. They begin with a command
363
+		enclosed in colons and followed by name of file or pipe (relative
364
+		to <filename moreinfo="none">/tmp/</filename> path), to which
365
+		a reply should be printed. The first request line may be
366
+		followed by additional lines with command-specific 
367
+		parameters. For example, the <command moreinfo="none">t_uac_dlg</command>
368
+		FIFO command for initiating a transaction allows 
369
+		to pass additional header fields and message body to
370
+		a newly created transaction. Each request is terminated by
371
+		an empty line. Whole requests must be sent by applications
372
+		atomically in a single batch to avoid mixing with
373
+		requests from other applications. Requests are sent to
374
+		pipe at which <application moreinfo="none">ser</application>
375
+		listens (filename configured by the <varname>fifo</varname> config
376
+		file option).
377
+	    </para>
378
+	    <para>
379
+		An easy way to use the FIFO interface is via the
380
+		<application moreinfo="none">serctl</application>
381
+		command-line tool. When called along with "fifo",
382
+		FIFO command name, and optional parameters, the tool
383
+		generates a FIFO request and prints request result.
384
+		The following example shows use of this tool with
385
+		the <command moreinfo="none">uptime</command> and
386
+		<command moreinfo="none">which</command> commands.
387
+		<command moreinfo="none">uptime</command> returns
388
+		server's running time, <command moreinfo="none">which</command>
389
+		returns list of available FIFO commands. Note that only
390
+		the built-in FIFO command set is displayed as no modules
391
+		were loaded in this example.
392
+		<example>
393
+		    <title>Use of <application moreinfo="none">serctl</application> 
394
+		    to Access FIFO Server</title>
395
+		    <programlisting format="linespecific">
396
+[jiri@cat test]$ serctl fifo uptime
397
+Now: Fri Dec  6 17:56:10 2002
398
+Up Since: Fri Dec  6 17:56:07 2002
399
+Up time: 3 [sec]
400
+
401
+[jiri@cat test]$ serctl fifo which
402
+ps
403
+which
404
+version
405
+uptime
406
+print
407
+		    </programlisting>
408
+		</example>
409
+		The request which the <application moreinfo="none">serctl</application>
410
+		command-line tool sent to FIFO server looked like this:
411
+		<example>
412
+		    <title><command moreinfo="none">uptime</command> FIFO Request</title>
413
+		    <programlisting format="linespecific">
414
+:uptime:ser_receiver_1114
415
+		    </programlisting>
416
+		</example>
417
+		This request contains no parameters and consists only of
418
+		command name enclosed in colons and name of file, to which
419
+		a reply should be printed. FIFO replies consist of a status
420
+		line followed by optional parameters. The status line consists,
421
+		similarly to <acronym>SIP</acronym> reply status, of 
422
+		a three-digit status code and a reason phrase. Status codes
423
+		with leading digit 2 (200..299) are considered positive,
424
+		any other values indicate an error. For example, FIFO server
425
+		returns "500" if execution of a non-existing FIFO command is 
426
+		requested.
427
+		<example>
428
+		    <title>FIFO Errors</title>
429
+		    <programlisting format="linespecific">
430
+[jiri@cat sip_router]$ serctl fifo foobar
431
+500 command 'foobar' not available
432
+		    </programlisting>
433
+		</example>
434
+
435
+		<example>
436
+		    <title>Showing User Contacts Using serctl</title>
437
+		    <para>
438
+			Another example of use of FIFO is accessing server's
439
+			in-memory user location database. That's a very powerful
440
+			feature: web applications and other tools can use it
441
+			to gain users access to the database. They can add new
442
+			contacts (like permanent gateway destinations), remove
443
+			and review their whereabouts. The example here utilizes
444
+			FIFO command <command>ul_show_contact</command> to
445
+			retrieve current whereabouts of user "jiri".
446
+			<programlisting>
447
+<![CDATA[
448
+[jiri@fox ser]$ serctl fifo ul_show_contact location jiri
449
+<sip:195.37.78.160:14519>;q=0.00;expires=1012
450
+]]>
451
+			</programlisting>
452
+		    </para>
453
+		</example>
454
+	    </para>
455
+	    <para>
456
+		The user location example demonstrates an essential feature
457
+		of the FIFO server: extensibility. It is able to export new 
458
+		commands implemented in new modules.
459
+		Currently, usrloc module exports FIFO
460
+		commands for maintaining in-memory user location
461
+		database and tm module exports FIFO commands for
462
+		management of SIP transactions. See the 
463
+		example in 
464
+		<filename moreinfo="none">examples/web_im/send_im.php</filename>
465
+		for how to initiate a SIP transaction
466
+		(instant message)
467
+		from a PHP script via the FIFO server. This example
468
+		uses FIFO command 
469
+		<command moreinfo="none">t_uac_dlg</command>. The command
470
+		is followed by parameters: header fields and 
471
+		message body. The same FIFO command can be used from
472
+		other environments to send instant messages too. The
473
+		following example shows how to send instant messages
474
+		from a shell script.
475
+		<example>
476
+		    <title>Sending IM From Shell Script</title>
477
+		    <programlisting format="linespecific">
478
+#!/bin/sh
479
+#
480
+# call this script to send an instant message; script parameters
481
+# will be displayed in message body
482
+#
483
+# paremeters mean: message type, request-URI, outbound server is
484
+# left blank ("."), required header fields From and To follow,
485
+# then optional header fields terminated by dot and optional
486
+# dot-terminated body
487
+
488
+cat &gt; /tmp/ser_fifo &lt;&lt;EOF
489
+:t_uac_dlg:hh
490
+NOTIFY
491
+sip:receiver@127.0.0.1
492
+.
493
+From: sip:originator@foo.bar
494
+To: sip:receiver@127.0.0.1
495
+foo: bar_special_header
496
+x: y
497
+p_header: p_value
498
+Contact: &lt;sip:devnull@192.168.0.100:9&gt;
499
+Content-Type: text/plain; charset=UTF-8
500
+.
501
+Hello world!!!! $@
502
+.
503
+EOF
504
+		    </programlisting>
505
+		</example>
506
+		</para>
507
+	    <example>
508
+		<title>Manipulation of User Contacts</title>
509
+		<para>
510
+		    The following example shows use of FIFO server to change 
511
+		    user's contacts. This may be very practical, if for example
512
+		    a user wishes to set up his cell phone number as his temporary
513
+		    contact. The cell phone, which is behind a PSTN gateway, cannot
514
+		    register automatically using SIP. The user needs to set 
515
+		    forwarding manually through some convenient web interface.
516
+		    The web interface needs to have the ability to upload new user's
517
+		    contacts to <application moreinfo="none">ser</application>.
518
+		    This is what the <command moreinfo="none">ul_add</command> FIFO
519
+		    command is good far. Paremeterized by user's name, table name,
520
+		    expiration time and wight, it allows external applications to
521
+		    introduce new contacts to server's in-memory user location table.
522
+		</para>
523
+		<para>
524
+		    The example is borrowed from <application moreinfo="none">serweb</application>,
525
+		    <application moreinfo="none">ser</application>'s web 
526
+		    PHP-written interface.
527
+		    It consists of a short "stub" function which carries out
528
+		    all mechanics of FIFO communication and of forming the FIFO
529
+		    request.
530
+		</para>
531
+		<programlisting format="linespecific">
532
+<![CDATA[
533
+
534
+/* construct and send a FIFO command; the command parameters $sip_address, 
535
+   $expires are PHP variables originating from an HTML form
536
+ */
537
+	$fifo_cmd=":ul_add:".$config->reply_fifo_filename."\n".
538
+		$config->ul_table."\n".			//table
539
+		$user_id."\n".		//username
540
+		$sip_address."\n".				//contact
541
+		$expires."\n".					//expires
542
+		$config->ul_priority."\n\n";		//priority
543
+		$message=write2fifo($fifo_cmd, $errors, $status);
544
+
545
+/* .......... snip .................. */
546
+
547
+/* this is the stub function for communicating with FIFO server.
548
+   it dumps a request to FIFO server, opens a reply FIFO and
549
+   reads server's reply from it
550
+*/
551
+function write2fifo($fifo_cmd, &$errors, &$status){
552
+	global $config;
553
+
554
+	/* open fifo now */
555
+	$fifo_handle=fopen( $config->fifo_server, "w" );
556
+	if (!$fifo_handle) {
557
+		$errors[]="sorry -- cannot open fifo"; return;
558
+	}
559
+	
560
+	/* create fifo for replies */
561
+	@system("mkfifo -m 666 ".$config->reply_fifo_path );
562
+
563
+	/* add command separator */
564
+	$fifo_cmd=$fifo_cmd."\n";
565
+	
566
+	/* write fifo command */
567
+	if (fwrite( $fifo_handle, $fifo_cmd)==-1) {
568
+	    @unlink($config->reply_fifo_path);
569
+	    @fclose($fifo_handle);
570
+		$errors[]="sorry -- fifo writing error"; return;
571
+	}
572
+	@fclose($fifo_handle);
573
+	
574
+	/* read output now */
575
+	@$fp = fopen( $config->reply_fifo_path, "r");
576
+	if (!$fp) {
577
+	    @unlink($config->reply_fifo_path);
578
+		$errors[]="sorry -- fifo reading error"; return;
579
+	}
580
+
581
+	$status=fgetS($fp,256);
582
+	if (!$status) {
583
+	    @unlink($config->reply_fifo_path);
584
+		$errors[]="sorry -- fifo reading error"; return;
585
+	}
586
+	
587
+	$rd=fread($fp,8192);
588
+	@unlink($config->reply_fifo_path);
589
+	
590
+	return $rd;
591
+}
592
+]]>		   
593
+		</programlisting>
594
+	    </example>
595
+	    <para>
596
+		See
597
+		<xref linkend="fiforeference"> for a complete listing
598
+		of FIFO commands available with current 
599
+		<application moreinfo="none">ser</application>
600
+		distribution.
601
+	    </para>
602
+	    <section>
603
+		<title>Advanced Example: Click-To-Dial</title>
604
+		<para>
605
+		    A very useful SIP application is phonebook with
606
+		    "click-to-dial" feature. It allows users to keep their 
607
+		    phonebooks on the web and dial by clicking on an entry. 
608
+		    The great advantage is that you can use the phonebook 
609
+		    alone with any phone you have. If you temporarily use 
610
+		    another phone, upgrade it permanently with another make, 
611
+		    or use multiple phones in parallel, your phonebook will 
612
+		    stay with you on the web. You just need to click an entry 
613
+		    to initiate a call. Other scenario using "click-to-dial"
614
+		    feature includes "click to be connected with our
615
+		    sales representative".
616
+		</para>
617
+		<para>
618
+		    There are basically two ways how to build such a feature:
619
+		    distributed and centralized. We prefer the distributed
620
+		    approach since it is very robust and leight-weighted.
621
+		    The "click-to-dial" application just needs to instruct
622
+		    the calling user to call a destination and that's it.
623
+		    (That's done using "REFER" method.)
624
+		    Then, the calling user takes over whereas the initating
625
+		    application disappears from signaling and
626
+		    is no longer involved in subsequent communication. Which
627
+		    is good because such a simple design scales well. 
628
+		</para>
629
+		<para>
630
+		    The other design alternative is use of a B2BUA 
631
+		    <footnote>
632
+			<para>
633
+			    See <filename moreinfo="none">
634
+				draft-ietf-sipping-3pcc-02.txt 
635
+			    </filename>  for more details.
636
+			</para>
637
+		    </footnote>
638
+		    which acts as a "middleman" involved in signaling during the
639
+		    whole session. It is complex: ringing needs to be achieved
640
+		    using a media server, it introduces session state,
641
+		    mangling of SIP payloads, complexity when QoS reservation
642
+		    is used and possibly other threats which result from 
643
+		    e2e-unfriendly design. The only benefit
644
+		    is it works even for poor phones which do not support
645
+		    REFER -- which should not matter because you do not wish
646
+		    to buy such.
647
+		</para>
648
+		<para>
649
+		    So how does "distributed click-to-dial" application
650
+		    work? It is simple. The core piece is sending a REFER
651
+		    request to the calling party. REFER method is typically
652
+		    used for call transfer and it means "set up a call 
653
+		    to someone else". 
654
+		    </para>
655
+		<para>
656
+		    There is an issue -- most phones
657
+		    don't accept unsolicited REFER. If a malicious
658
+		    user made your phone to call thirty destinations without
659
+		    your agreement, you would certainly not appreciate it.
660
+		    The workaround is that first of all the click-to-dial
661
+		    application gives you a "wrapper call". If you accept it, 
662
+		    the application will send a REFER which will be considered
663
+		    by the phone as a part of approved communication and
664
+		    granted. Be aware that without cryptography, 
665
+		    security is still weak. Anyone who saw an INVITE can 
666
+		    generate an acceptable REFER.
667
+		    <example>
668
+			<title>Call-Flow for Click-To-Dial Using REFER</title>
669
+
670
+			<programlisting format="linespecific">
671
+
672
+        CTD                  Caller               Callee
673
+            #1 INVITE
674
+            ----------------->
675
+                             ...
676
+                             caller answers
677
+            #2 200
678
+            <-----------------
679
+            #3 ACK
680
+            ----------------->
681
+            #4 REFER
682
+            ----------------->
683
+            #5 202
684
+            <-----------------
685
+            #6 BYE
686
+            ----------------->
687
+            #7 200
688
+            <-----------------
689
+                                  #8 INVITE
690
+                                  ------------------>
691
+                                  #9 180 ringing
692
+                                  <------------------
693
+
694
+
695
+#1 click-to-dial (CTD) is started and the "wrapper call" is initiated
696
+INVITE caller
697
+From: controller
698
+To: caller
699
+SDP: on hold
700
+
701
+#2 calling user answes
702
+200 OK
703
+From: controller
704
+To: caller
705
+
706
+#3 CTD acknowledges
707
+ACK caller
708
+From controller
709
+To: caller
710
+
711
+#4 CTD initiates a transfer
712
+REFER caller
713
+From: controller
714
+To: caller
715
+Refer-To: callee
716
+Refered-By: controller
717
+
718
+#5 caller confirms delivery of REFER
719
+202 Accepted
720
+From: controller
721
+To: caller
722
+
723
+#6 CTD terminates the wrapper call -- it is no longer needed
724
+BYE caller
725
+From: controller
726
+To: caller
727
+
728
+#7 BYE is confirmed
729
+200 Ok
730
+From: controller
731
+To: caller
732
+
733
+#8 caller initates transaction solicited through REFER
734
+INVITE callee
735
+From: caller
736
+To: callee
737
+Referred-By: controller
738
+
739
+#9 that's it -- it is now up to callee to answer the INVITE
740
+180 ringing
741
+From: caller
742
+To: callee
743
+			</programlisting>
744
+
745
+		    </example>
746
+		</para>
747
+		<para>
748
+		    Implementation of this scenario is quite
749
+		    straight-forward: you initiate INVITE, BYE and
750
+		    REFER transaction.
751
+
752
+
753
+
754
+		    The largest amount of code
755
+		    is spent with getting dialog processing right.
756
+		    The subsequent BYE and REFER transactions need to
757
+		    be build using information learned from the reply
758
+		    to INVITE: Contact header field, To-tag and Route
759
+		    set. That's what the function 
760
+		    <function moreinfo="none">filter_fl</function>
761
+		    is used for. The "main" part just initiates
762
+		    each of the transactions, waits for its completion
763
+		    and proceeds to the next one until BYE is over.
764
+		    Source code of the example written in Bourne shell
765
+		    is available in source distrubtion, in 
766
+		    <filename moreinfo="none">examples/ctd.sh</filename>.
767
+		    A PHP implementation exists as well.
768
+		</para>
769
+		<example>
770
+		    <title>Running the CTD Example</title>
771
+		    <programlisting format="linespecific">
772
+[jiri@cat examples]$ ./ctd.sh 
773
+destination unspecified -- taking default value sip:23@192.168.2.16
774
+caller unspecified -- taking default value sip:113311@192.168.2.16
775
+invitation succeeded
776
+refer succeeded
777
+bye succeeded
778
+		    </programlisting>
779
+		</example>
780
+	    </section> <!-- click-to-dial -->
781
+<!-- for some reason, this does not work :-(
782
+
783
+		<example>
784
+		    <title>Initiating a SIP Transaction from PHP via FIFO</title>
785
+
786
+
787
+		    <programlisting format="linespecific">
788
+			<textobject>
789
+			    <textdata fileref="../../examples/web_im/send_im.php" format="linespecific">
790
+			</textobject>
791
+			    
792
+		    </programlisting>
793
+
794
+		    
795
+		</example>
796
+-->
797
+
798
+	</section> <!-- FIFO server -->
799
+    </chapter>
800
+
0 801
new file mode 100644
... ...
@@ -0,0 +1,425 @@
0
+    <chapter id="general">
1
+	<title>General Information</title>
2
+	<section id="aboutser">
3
+	    <title>About <acronym>SIP</acronym> Express Router (<acronym>SER</acronym>)</title>
4
+	    <para>
5
+		SIP Express Router (<acronym>SER</acronym>) is an industrial-strength, free VoIP 
6
+		server based on the Session Initiation Protocol (<acronym>SIP</acronym>, RFC3261). 
7
+		It is engineered to power <acronym>IP</acronym> telephony infrastructures up to large 
8
+		scale. The server keeps track of users, sets up VoIP sessions, 
9
+		relays instant messages and creates space for new plug-in applications. 
10
+		Its proven interoperability guarantees seamless integration with 
11
+		components from other vendors, eliminating the risk of a single-vendor 
12
+		trap. It has successfully participated in various interoperability 
13
+		tests in which it worked with the products of other leading <acronym>SIP</acronym> vendors.
14
+	    </para>
15
+	    <para>
16
+		The <acronym>SIP</acronym> Express Router enables a flexible plug-in model for new 
17
+		applications: Third parties can easily link their plug-ins with 
18
+		the server code and provide thereby advanced and customized services. 
19
+		In this way, plug-ins such as <acronym>SNMP</acronym> support, RADIUS accounting,
20
+		or SMS gateway have already been developed and are provided as 
21
+		advanced features. Other modules are underway: Presence server,
22
+		firewall control, and more.
23
+	    </para>
24
+	    <para>
25
+		Its performance and robustness allows it to serve millions of users 
26
+		and accommodate needs of very large operators. With a $3000 dual-CPU PC, the 
27
+		<acronym>SIP</acronym> Express Router is able to power <acronym>IP</acronym> telephony services in an area 
28
+		as large as the Bay Area during peak hours. Even on an IPAQ <acronym>PDA</acronym>, the server 
29
+		withstands 150 calls per second (<acronym>CPS</acronym>)! The server has been powering our 
30
+		iptel.org free <acronym>SIP</acronym> site withstanding heavy daily load that is further 
31
+		increasing with the popularity of Microsoft's Windows Messenger.  
32
+	    </para>
33
+	    <para>
34
+		The <acronym>SIP</acronym> Express Router is extremely configurable to allow the creation of 
35
+		various routing and admission policies as well as setting up new and 
36
+		customized services. Its configurability allows it to serve many roles: 
37
+		network security barrier, application server, or <acronym>PSTN</acronym> gateway guard for 
38
+		example.
39
+	    </para>
40
+	    <para>
41
+		<application moreinfo="none">ser</application> can be also
42
+		used with contributed applications. Currently, 
43
+		<application moreinfo="none">serweb</application>, a
44
+		<application moreinfo="none">ser</application> web interface,
45
+		and <application moreinfo="none">SIPSak</application>
46
+		diagnostic tool are available. Visit our site, 
47
+		<ulink url="http://www.iptel.org/">http://www.iptel.org/</ulink>, 
48
+                for more information on contributed packages.
49
+	    </para>
50
+	</section> 
51
+
52
+	<section id="aboutiptel">
53
+	    <title>About iptel.org</title>
54
+	    <para>
55
+		iptel.org is a know-how company spun off from Germany's national 
56
+		research company FhG Fokus. One of the first <acronym>SIP</acronym> implementations ever, 
57
+		low-QoS enhancements, interoperability tests and VoIP-capable firewall 
58
+		control concepts are examples of well-known FhG's work.
59
+	    </para>
60
+	    <para>
61
+		iptel.org continues to keep this know-how leadership in <acronym>SIP</acronym>. 
62
+		The access rate of the company's site, a well-known source of 
63
+		technological information, is a best proof of interest. Thousands 
64
+		of hits come every day from the whole Internet.
65
+	    </para>
66
+	    <para>
67
+		The iptel.org site, powered by SER, offers SIP services on the public 
68
+		Internet. Feel free to apply for a free SIP account at
69
+		<ulink url="http://www.iptel.org/user/">http://www.iptel.org/user/
70
+		</ulink>
71
+	    </para>
72
+
73
+	    
74
+	</section> <!-- iptel -->
75
+	<section id="serfeatures">
76
+	    <title>Feature List</title>
77
+	    <para>
78
+		Based on the latest standards, the <acronym>SIP</acronym> Express Router (<acronym>SER</acronym>) includes 
79
+		support for registrar, proxy and redirect mode. Further it acts as 
80
+		an application server with support for instant messaging and 
81
+		presence including a <acronym>2G/SMS</acronym> and Jabber gateway, a call control policy 
82
+		language, call number translation, private dial plans and accounting, 
83
+		authorization and authentication (<acronym>AAA</acronym>) services. <application>SER</application> runs on Sun/Solaris, 
84
+		PC/Linux, PC/BSD, IPAQ/Linux platforms and supports  both <acronym>IPv4</acronym> and <acronym>IPv6</acronym>. 
85
+		Hosting multiple domains and database redundancy is supported.
86
+	    </para>
87
+	    <para>
88
+		Other extensions are underway: presence server, firewall control and more.
89
+	    </para>
90
+	    <para>
91
+		<application>ser</application> has been carefully engineered with the following 
92
+		design objectives in mind:
93
+		<itemizedlist>
94
+		    <listitem>
95
+			<para>
96
+			    <emphasis>Speed</emphasis> - With <application>ser</application>, 
97
+			    thousands of calls per seconds are achievable 
98
+			    even on low-cost platforms. This competitive capacity allows 
99
+			    setting up networks which are inexpensive and easy to manage 
100
+			    due to low number of devices required. The processing capacity 
101
+			    makes dealing with many stress factors easier. The stress
102
+			    factors may include but are not limited to broken configurations and implementations,
103
+			    boot avalanches on power-up, high-traffic applications such as presence, 
104
+			    redundancy replications and denial-of-service attacks.
105
+			</para>
106
+			<para> The speed has been achieved by extensive code optimization, use of customized code, 
107
+			    <acronym>ANSI C</acronym> combined with assembly instructions and leveraging latest 
108
+			    <acronym>SIP</acronym> improvements. When powered by a dual-CPU Linux PC, 
109
+			    <application>ser</application> is able to process thousands of calls per second,
110
+			    capacity needed to serve call signaling demands of Bay Area population.
111
+			   
112
+			</para>
113
+		    </listitem>
114
+		    <listitem>
115
+			<para>
116
+			    <emphasis>Flexibility</emphasis> - <application>SER</application> allows its users 
117
+			    to define its behavior. 
118
+			    Administrators may write textual scripts which determine <acronym>SIP</acronym> routing 
119
+			    decisions, the main job of a proxy server. They may use the script to 
120
+			    configure numerous parameters and introduce additional logic. For example, 
121
+			    the scripts can determine for which destinations record routing should be 
122
+			    performed, who will be authenticated, which transactions should be processed 
123
+			    statefully, which requests will be proxied or redirected, etc.
124
+			</para>
125
+
126
+		    </listitem>
127
+		    <listitem>
128
+			<para>
129
+			    <emphasis>Extensibility</emphasis> - <application>SER</application>'s extensibility allows linking of 
130
+			    new C code to ser to 
131
+			    redefine or extend its logic. The new code can be developed independently 
132
+			    on <application>SER</application> core and linked to it in run-time. The concept is similar to 
133
+			    the module concept known for example in Apache Web server. Even such essential parts such 
134
+			    as transaction management have been developed as modules to keep the <application>SER</application> core 
135
+			    compact and fast.
136
+			</para>
137
+		    </listitem>
138
+		    <listitem>
139
+			<para>
140
+			    <emphasis>
141
+				Portability.
142
+			    </emphasis>
143
+			    <application>ser</application> has been written in ANSI C. It has been extensively tested 
144
+			    on PC/Linux and Sun/Solaris. Ports to BSD and IPAQ/Linux exist.
145
+			</para>
146
+		    </listitem>
147
+		    <listitem>
148
+			<para>
149
+			    <emphasis>			   
150
+				Interoperability. 
151
+			</emphasis>
152
+			<application>ser</application> is based on the open <acronym>SIP</acronym> standard. 
153
+			    It has undergone extensive tests with products of other vendors both in iptel.org
154
+			    labs and in the SIP Interoperability Tests (SIPIT). <application>ser</application> 
155
+			    powers the public iptel.org site 24 hours a day, 356 days a year 
156
+			    serving numerous SIP implementations using this site.
157
+			</para>
158
+		    </listitem>
159
+		    <listitem>
160
+			<para>
161
+			    <emphasis>Small size.</emphasis>
162
+			    Footprint of the core is 300k, add-on modules take up to 630k.
163
+			</para>
164
+		    </listitem>
165
+		</itemizedlist>
166
+	    </para>
167
+	</section> <!-- serfeatures -->
168
+
169
+	<section id="usecases">
170
+	    <title>Use Cases</title>
171
+	    <para>
172
+		This section illustrates the most frequent uses of SIP. In all these scenarios, 
173
+		the SIP Express Router (SER) can be easily deployed as the glue connecting all 
174
+		SIP components together, be it soft-phones, hard-phones, PSTN gateways or any other 
175
+		SIP-compliant devices.
176
+	    </para>
177
+	    <section>
178
+		<title>Added-Value ISP Services</title>
179
+		<para>
180
+		    To attract customers, ISPs frequently offer applications bundled with IP access. 
181
+		    With SIP, the providers can conveniently offer a variety of services running on top 
182
+		    of a single infrastructure. Particularly, deploying VoIP and instant messaging and 
183
+		    presence services is as easy as setting up a SIP server and guiding customers to use 
184
+		    Windows Messenger. Additionally, the ISPs may offer advanced services such as PSTN 
185
+		    termination, user-driven call handling or unified messaging all using the same infrastructure.
186
+		</para>
187
+		<para>
188
+		    SIP Express Router has been engineered to power large scale networks: its capacity can deal 
189
+		    with large number of customers under high load caused by modern applications. Premium 
190
+		    performance allows deploying a low number of boxes while keeping investments and operational 
191
+		    expenses extremely low. ISPs can offer SIP-based instant messaging services and interface
192
+		    them to other instant messaging systems (Jabber, SMS). VoIP can be easily integrated along
193
+		    with added-value services, such as voicemail.
194
+		</para>
195
+	    </section> <!-- Added-value ISP -->
196
+	    <section>
197
+		<title>PC2Phone</title>
198
+		<para>
199
+		    Internet Telephony Service Providers (ITSPs) offer the service of interconnecting 
200
+		    Internet telephony users using PC softphone or appliances to PSTN. Particularly with 
201
+		    long-distance and international calls, competitive pricing can be achieved by 
202
+		    routing the calls over the Internet.
203
+		</para>
204
+		<para>
205
+		    SIP Express Router can be easily configured to serve pc2phone users, distribute
206
+		    calls to geographically appropriate PSTN gateway, act as a security barrier and keep 
207
+		    track of charging. 
208
+		</para>
209
+	    </section>
210
+	    <section>
211
+		<title>PBX Replacement</title>
212
+		<para>
213
+		    Replacing a traditional PBX in an enterprise can achieve reasonable 
214
+		    savings. Enterprises can deploy a single infrastructure for both voice 
215
+		    and data and bridge distant locations over the Internet. Additionally, they can 
216
+		    benefit of integration of voice and data.
217
+		</para>
218
+		<para>
219
+		    The SIP Express Router scales from SOHOs to large, international enterprises. 
220
+		    Even a single installation on a common PC is able to serve VoIP signaling of any 
221
+		    world's enterprise. Its policy-based routing language makes implementation of numbering 
222
+		    plans of companies spread across the world very easy. ACL features allow for protection of 
223
+		    PSTN gateway from unauthorized callers.
224
+		</para>
225
+		<para>
226
+		    SIP Express Router's support for programmable routing and accounting efficiently allows for 
227
+		    implementation of such a scenario.
228
+		</para>
229
+	    </section>
230
+	</section> <!-- Use Cases -->
231
+	<section id="aboutsip">
232
+	    <title>About SIP Technology</title>
233
+	    <para>
234
+		The SIP protocol family is the technology which integrates services. 
235
+		With SIP, Internet users can easily contact each other; figure out 
236
+		willingness to have a conversation and couple different applications such as VoIP, video 
237
+		and instant messaging. Integration with added-value services is seamless and easy. Examples 
238
+		include integration with web (click-to-dial), E-mail (voice2email, UMS), and PSTN-like 
239
+		services (conditional forwarding).
240
+	    </para>
241
+	    <para>
242
+		The core piece of the technology is the Session Initiation Protocol (SIP, RFC3261) standardized by IETF. 
243
+		Its main function is to establish communication sessions between users connected to the public 
244
+		Internet and identified by e-mail-like addresses. One of SIP's greatest features is its transparent 
245
+		support for multiple applications: the same infrastructure may be used for voice, video, gaming 
246
+		or instant messaging as well as any other communication application.
247
+	    </para>
248
+	    <para>
249
+		There are numerous scenarios in which SIP is already deployed: PBX replacement allows for 
250
+		deployment of single inexpensive infrastructure in enterprises; PC-2-phone long-distance 
251
+		services (e.g., Deltathree) cut callers long-distance expenses; instant messaging offered 
252
+		by public severs (e.g., iptel.org) combines voice and text services with presence information. 
253
+		New deployment scenarios are underway: SIP is a part of UMTS networks and research publications 
254
+		suggest the use of SIP for virtual home environments or distributed network games.
255
+	    </para>
256
+	</section> <!-- about sip -->
257
+	<section id="serlimitations">
258
+	    <title>Known SER Limitations</title>
259
+	    <para>
260
+		The following items are not part of current distribution and are planned for next releases:
261
+		<itemizedlist>
262
+		    <listitem>
263
+			<para>
264
+			    Script processing of multiple branches on forking
265
+			</para>
266
+
267
+			<warning>
268
+			    <para>
269
+				<application>ser</application>'s request processing language allows 
270
+				to make request decisions based on current URI. 
271
+				When a request if forked to multiple destinations, only the first branch's URI is used as 
272
+				input for script processing. This might lead to unexpected results. Whenever a URI resolves 
273
+				to multiple different next-hop URIs, only the first is processed which may result in handling 
274
+				not appropriate for the other branch. For example, a URI might resolve to an IP phone SIP 
275
+				address and PSTN gateway SIP address. If the IP phone address is the first, then script 
276
+				execution ignores the second branch. If a script includes checking gateway address in
277
+				request URI, the checks never match. That might result in ignoring of 
278
+				gateway admission control rules or applying them unnecessarily to non-gateway 
279
+				destinations.
280
+			    </para>
281
+			</warning>
282
+		    </listitem>
283
+		</itemizedlist>
284
+	    </para>
285
+	    <para>
286
+		List of known bugs is publicly available at the 
287
+		<application>ser</application> webpage at
288
+		<ulink url="http://www.iptel.org/ser/">
289
+		    http://www.iptel.org/ser/
290
+		</ulink>. See the "ISSUES" link.
291
+	    </para>
292
+	</section> <!-- limitations -->
293
+	<section id="licensing">
294
+	    <title>Licensing</title>
295
+	    <para>
296
+		<application>ser</application> is freely available under terms and
297
+		conditions of the GNU General Public License.
298
+	    </para>	
299
+	    <!-- COPYING -->
300
+	    <screen>
301
+	    	    &gpllicense;
302
+	    </screen>
303
+	    
304
+	</section>
305
+	<section id="support">
306
+	    <title>Obtaining Technical Assistance</title>
307
+	    <para>
308
+		We offer best-effort free support for <application>ser</application>.
309
+		"best-effort" means that we try to solve your problems via email
310
+		as soon as we can, subject to available manpower. If you need
311
+		commercial support, contact info@iptel.org.
312
+	    </para>
313
+	    <para>
314
+		To receive feedback to your inquiries, we recommend you to subscribe
315
+		to the <emphasis>serusers</emphasis> mailing list and post your
316
+		queries there. This mailing list is set up for mutual help by
317
+		the community of <application>ser</application> users and developers.
318
+	    </para>
319
+	    <itemizedlist>
320
+		<title>Mailing List Instructions</title>
321
+		<listitem>
322
+		    <para>
323
+			Public archives and subscription form:
324
+			<ulink url="http://mail.iptel.org/mailman/listinfo/serusers">
325
+			    http://mail.iptel.org/mailman/listinfo/serusers
326
+			</ulink>			
327
+		    </para>
328
+		</listitem>
329
+		<listitem>
330
+		    <para>
331
+			To post, send an email to serusers@iptel.org
332
+		    </para>
333
+		</listitem>
334
+		<listitem>
335
+		    <para>
336
+			If you think you encountered an error, please submit the
337
+			following information to avoid unnecessary round-trip times:			
338
+			<itemizedlist>
339
+			    <listitem>
340
+				<para>
341
+				    Name and version of your operating system --
342
+				    you can obtain it by calling
343
+				    <command>uname -a</command>
344
+				</para>
345
+			    </listitem>
346
+			    <listitem>
347
+				<para>
348
+				    <application>ser</application> distribution: 
349
+				    release number and package				    
350
+				</para>
351
+			    </listitem>
352
+			    <listitem>
353
+				<para>
354
+				    <application>ser</application> build -- 
355
+				    you can obtain it by calling 
356
+				    <command moreinfo="none">ser -V</command>
357
+				</para>
358
+			    </listitem>
359
+			    <listitem>
360
+				<para>
361
+				    Your <application>ser</application> configuration file
362
+				</para>
363
+			    </listitem>
364
+			    <listitem>
365
+				<para>
366
+				    <application>ser</application> logs -- with default settings
367
+				    few logs are printed to <command>syslog</command> facility which
368
+				    typically dumps them to 
369
+				    <filename moreinfo="none">/var/log/messages</filename>. To 
370
+				    enable detailed logs dumped to <filename>stderr</filename>,
371
+				    apply the following configuration options: <command moreinfo="none">
372
+				    debug=8, log_stderror=yes, fork=no</command>.
373
+				</para>
374
+			    </listitem>
375
+			    <listitem>
376
+				<para>
377
+				    Captured SIP messages -- you can obtain them 
378
+				    using tools such as <application>ngrep</application>
379
+				    or <application moreinfo="none">ethereal</application>.
380
+				</para>
381
+			    </listitem>
382
+			</itemizedlist>
383
+		    </para>
384
+		    
385
+		</listitem>
386
+	    </itemizedlist>	    
387
+	
388
+	    <para>
389
+		If you are concerned about your privacy and do not wish your
390
+		queries to be posted and archived publicly, you may post to
391
+		serhelp@iptel.org. E-mails to this address are only forwarded
392
+		to iptel.org's <application>ser</application> development team.
393
+		However, as the team is quite busy you should not be surprised
394
+		to get replies with considerable delay.
395
+
396
+	    </para>
397
+	</section>
398
+        
399
+	<section id="moreinfo">
400
+	    <title>More Information</title>
401
+	    <para>
402
+		Most up-to-date information including latest and most complete version
403
+		of this documentation is always available at our website,
404
+		<ulink url="http://www.iptel.org/ser/">http://www.iptel.org/ser/</ulink>.
405
+		The site includes links to other important information about
406
+		<application moreinfo="none">ser</application>, such
407
+		as installation guidelines (INSTALL), download links,
408
+		development pages, programmer's manual, etc.
409
+	    </para>
410
+	    <para>
411
+		A SIP tutorial (slide set) is available at 
412
+		<ulink url="http://www.iptel.org/sip/">http://www.iptel.org/sip/</ulink> .
413
+	    </para>
414
+	</section> <!-- info -->
415
+
416
+	<section>
417
+	    <title>Release Notes</title>
418
+	    <literallayout format="linespecific" class="normal">
419
+&releasenotes;
420
+	    </literallayout>
421
+	</section> <!-- release notes -->
422
+
423
+
424
+    </chapter> <!-- general -->
0 425
new file mode 100644
... ...
@@ -0,0 +1,1478 @@
0
+    <chapter>
1
+	<title>Introduction to SER</title>
2
+
3
+	<section id="requestrouting">
4
+	    <title>Request Routing and SER Scripts</title>
5
+	    <para>
6
+		The most important concept of every SIP server is that of
7
+		request routing. The request routing logic determines the next
8
+		hop of a request. It can be for example used to implement user 
9
+		location service or enforce static routing to a gateway. Real-world
10
+		deployments actually ask for quite complex routing logic, which
11
+		needs to reflect static routes to PSTN gateways, dynamic routes
12
+		to registered users, authentication policy, capabilities of
13
+		SIP devices, etc.
14
+	    </para>
15
+	    <para>
16
+		SER's answer to this need for routing flexibility is a routing
17
+		language, which allows administrators to define the SIP request
18
+		processing logic in a detailed manner. They can for example easily
19
+		split SIP traffic by method or destination, perform user location, 
20
+		trigger authentication, verify access permissions, and so on.
21
+	    </para>
22
+	    <para>
23
+		The primary building block of the routing language are <emphasis>actions</emphasis>. 
24
+		There are built-in actions (like <command>forward</command> for stateless forwarding
25
+		or <command>strip</command> for stripping URIs) as 
26
+		well as external actions imported from shared library modules. All actions can 
27
+		be combined in compound actions by enclosing them in braces, 
28
+		e.g. <command>{a1(); a2();}</command>. 
29
+		Actions are aggregated in one or more <emphasis>route blocks</emphasis>.
30
+		Initially, only the default routing block denoted by <command>route[0]</command>
31
+		is called. Other routing blocks can be called by the action
32
+		<command>route(blocknumber)</command>, recursion is permitted.
33
+		The language includes <emphasis>conditional statements</emphasis>. 
34
+	    </para>
35
+
36
+	    <para>
37
+		The routing script is executed for every received request in sequential order. 
38
+		Actions may return positive/negative/zero value. 
39
+
40
+		Positive values are considered success and evaluated as
41
+		TRUE in conditional expressions. Negative values are considered FALSE. 
42
+
43
+		Zero value means error and leaves execution of currently processed
44
+		route block. The route block is left too, if <command>break</command> is explicitly
45
+		called from it.
46
+
47
+	    </para>
48
+	    <para>
49
+		The easiest and still very useful way for <application>ser</application>
50
+		users to affect request routing logic is
51
+		to determine next hop statically. An example is
52
+		routing to a PSTN gateway whose static IP address is well known.
53
+		To configure static routing, simply use the action
54
+		<command>forward( IP_address, port_number)</command>.
55
+		This action forwards an incoming request "as is" to the
56
+		destination described in action's parameters.
57
+	    </para>
58
+
59
+	    <example>
60
+		<title>Static Forwarding</title>
61
+		<programlisting format="linespecific">
62
+# if requests URI is numerical and starts with
63
+# zero, forward statelessly to a static destination
64
+
65
+if (uri=~"^sip:0[0-9]*@iptel.org) {
66
+    forward( 192.168.99.3, 5080 );
67
+} 
68
+		</programlisting>
69
+	    </example>
70
+
71
+	    <para>
72
+		However, static forwarding is not sufficient in many cases.
73
+		Users desire mobility and change their location frequently.
74
+		Lowering costs for termination of calls in PSTN requires
75
+		locating a least-cost gateway. Which next-hop is taken may
76
+		depend on user's preferences. These and many other scenarios
77
+		need the routing logic to be more dynamic. We describe in
78
+		<xref linkend="conditions"> how to make request processing