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