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 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 
+
doc/seruser/apps.sgml
History View file @ 16e00a7dc0
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 
+
doc/seruser/general.sgml
History View file @ 16e00a7dc0
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 -->
doc/seruser/intro.sgml
History View file @ 16e00a7dc0
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