GitList
Browse code

minor documentation changes

Jiri Kuthan authored on 28/03/2003 21:23:23
Showing 10 changed files
README-MODULES
History View file @ 16e00a7dc0
... ... 
@@ -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 
+
doc/seruser/apps.sgml
History View file @ 16e00a7dc0
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 
+
doc/seruser/general.sgml
History View file @ 16e00a7dc0
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 -->
doc/seruser/intro.sgml
History View file @ 16e00a7dc0
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