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