Browse code

user location and place-holder for voicemail introduced

Jiri Kuthan authored on 29/01/2003 20:49:33
Showing 2 changed files
... ...
@@ -21,6 +21,7 @@
21 21
 <!ENTITY ccdiversion SYSTEM "../../examples/ccdiversion.cfg">
22 22
 <!ENTITY releasenotes SYSTEM "../../NEWS">
23 23
 <!ENTITY install SYSTEM "../../INSTALL">
24
+<!ENTITY voicemail SYSTEM "voicemail.sgml">
24 25
 
25 26
 
26 27
 
... ...
@@ -32,7 +33,7 @@
32 33
 <?dbhtml filename="index.html">
33 34
 
34 35
    
35
-    <title>iptel.org SIP Express Router v0.8.11 -- Admin's Guide</title>
36
+    <title>iptel.org SIP Express Router v0.9.0 -- Admin's Guide</title>
36 37
     <bookinfo>
37 38
 	<authorgroup>
38 39
 	    <author>
... ...
@@ -736,6 +737,12 @@ if (search("(f|From): .*@mydomain.com)) {
736 737
 				at which a request was received
737 738
 			    </para>
738 739
 			</listitem>
740
+			<listitem>
741
+			    <para>
742
+				<emphasis>src_port</emphasis> port number from which a SIP
743
+				request came
744
+			    </para>
745
+			</listitem>
739 746
 		    </itemizedlist>
740 747
 		</para>
741 748
 		<para>
... ...
@@ -852,8 +859,7 @@ if (search("(f|From): .*@mydomain.com)) {
852 859
 
853 860
 			<row>
854 861
 			    <entry>
855
-				dst_ip
856
-				by <application moreinfo="none">ser</application>
862
+				dst_ip				
857 863
 			    </entry>			    
858 864
 			    <entry>
859 865
 				== (match)
... ...
@@ -867,6 +873,21 @@ if (search("(f|From): .*@mydomain.com)) {
867 873
 			    </entry>
868 874
 			</row>
869 875
 
876
+			<row>
877
+			    <entry>
878
+				    src_port
879
+			    </entry>			    
880
+			    <entry>
881
+				== (match)
882
+			    </entry>
883
+			    <entry>
884
+				port number
885
+			    </entry>
886
+			    <entry>
887
+				port number from which a request was sent, e.g. src_port==5060
888
+			    </entry>
889
+			</row>			    
890
+
870 891
 
871 892
 		    </tbody>
872 893
 		</tgroup>
... ...
@@ -1404,7 +1425,102 @@ forward(uri:host, uri:port);
1404 1425
 
1405 1426
 	</section> <!-- Destination Set -->
1406 1427
 
1407
-
1428
+	<section>
1429
+	    <title>User Location</title>
1430
+	    <para>
1431
+		Mobility is a key feature of SIP. Users are able to use one
1432
+		one or more SIP devices and be reachable at them. Incoming requests 
1433
+		for users are forwarded to all user's devices in use. The key
1434
+		concept is that of soft-state registration. Users can
1435
+		-- if in possession of valid credentials -- link SIP
1436
+		devices to their e-mail like address of record. Their SIP devices
1437
+		do so using a REGISTER request, as in <xref linkend="register">.
1438
+		The request creates a binding between the public address of
1439
+		record (To header field) and SIP device's current address
1440
+		(Contact header field). 
1441
+		<example id="register">
1442
+		    <title>REGISTER Request</title>
1443
+		    <programlisting format="linespecific">
1444
+REGISTER sip:192.168.2.16 SIP/2.0
1445
+Via: SIP/2.0/UDP 192.168.2.16;branch=z9hG4bKd5e5.5a9947e4.0
1446
+Via: SIP/2.0/UDP 192.168.2.33:5060
1447
+From: sip:123312@192.168.2.16
1448
+To: sip:123312@192.168.2.16
1449
+Call-ID: 00036bb9-0fd30217-491b6aa6-0a7092e9@192.168.2.33
1450
+Date: Wed, 29 Jan 2003 18:13:15 GMT
1451
+CSeq: 101 REGISTER
1452
+User-Agent: CSCO/4
1453
+Contact: sip:123312@192.168.2.33:5060
1454
+Content-Length: 0
1455
+Expires: 600
1456
+		    </programlisting>
1457
+		</example>
1458
+		Similar requests can be used to query all user's current contacts or to
1459
+		delete them. All Contacts have certain time to live, when the time expires,
1460
+		contact is removed and no longer used for processing of incoming requests.
1461
+	    </para>
1462
+	    <para>
1463
+		<application moreinfo="none">ser</application> is built to do both: update
1464
+		user location database from received REGISTER requests and look-up these
1465
+		contacts when inbound requests for a user arrive. To achieve high performance,
1466
+		the user location table is stored in memory. In regular intervals
1467
+		(usrloc module's parameter <varname>timer_interval</varname> determines
1468
+		their length), all changes to the in-memory table are backed up in
1469
+		<application moreinfo="none">mysql</application> database to achieve
1470
+		peristence accross server reboots. Administrators or application writers
1471
+		can lookup list of current user's contacts stored in memory using the
1472
+		<application moreinfo="none">serctl</application> tool (see <xref linkend="serctl">).
1473
+		<example>
1474
+		    <title>Use of <application>serctl</application> Tool to Query User Location</title>
1475
+		    <screen format="linespecific">
1476
+<![CDATA[
1477
+[jiri@fox jiri]$ sc ul show jiri
1478
+<sip:jiri@212.202.172.134>;q=0.00;expires=456
1479
+<sip:7271@gateway.foo.bar>;q=0.00;expires=36000
1480
+]]>
1481
+		    </screen>
1482
+		</example>
1483
+	    </para>
1484
+	    <para>
1485
+		Building user location in <application moreinfo="none">ser</application> scripts is
1486
+		quite easy. One first needs to determine whether a request is for served domain,
1487
+		as described in <xref linkend="domainmatching">. If that is the case, the script
1488
+		needs to distinguish between REGISTER requests, that update user location table,
1489
+		and all other requests for which next hop is determined from the table. The
1490
+		<command moreinfo="none">save</command> action is used to update user location
1491
+		(i.e., it writes to it). The <command moreinfo="none">lookup</command> actions
1492
+		reads from the user location table and fills in destination set with current
1493
+		user's contacts.
1494
+		<example>
1495
+		    <title>Use of User Location Actions</title>
1496
+		    <programlisting format="linespecific">
1497
+# is the request for my domain ?
1498
+if (uri==myself) {
1499
+    if (method=="REGISTER") { # REGISTERs are used to update
1500
+         save("location");
1501
+         break; # that's it, we saved the contacts, exit now
1502
+    } else {
1503
+         if (!lookup("location") { # no registered contact
1504
+            sl_send_reply("404", "Not Found");
1505
+            break;
1506
+         }
1507
+         # ok -- there are some contacts for the user; forward
1508
+         # the incoming request to all of them
1509
+         t_relay();
1510
+    };
1511
+};
1512
+		    </programlisting>
1513
+		</example>
1514
+	    </para>
1515
+	    <para>
1516
+		Note that we used the action for stateful forwarding, 
1517
+		<command moreinfo="none">t_relay</command>. That's is because
1518
+		stateful forwarding allows to fork an incoming request to
1519
+		multiple destinations. If we used stateful forwarding,
1520
+		the request would be forwarded only to one uri out of
1521
+		all user's contacts.
1522
+	    </para>
1523
+	</section> <!-- User Location -->
1408 1524
 	
1409 1525
 	<section>
1410 1526
 	    <title>External Modules</title>
... ...
@@ -3959,9 +4075,15 @@ Domain Registered Expired
3959 4075
 		be seen at iptel.org's SIP site. Just create and use a SIP
3960 4076
 		account at <ulink url="http://www.iptel.org/user/">http://www.iptel.org/user/</ulink>
3961 4077
 	    </para>
3962
-	</section>
4078
+	</section> <!-- serweb -->
4079
+
3963 4080
 
3964
-    </chapter> <!-- serweb -->
4081
+    <section>
4082
+	<title>Voicemail</title>
4083
+&voicemail;
4084
+    </section> <!-- voicemail -->
4085
+
4086
+    </chapter> <!-- other apps -->
3965 4087
     
3966 4088
     <chapter>
3967 4089
 	<title>Reference</title>
... ...
@@ -4979,6 +5101,36 @@ if (len_gt(1024)) {
4979 5101
 				record-route a request
4980 5102
 			    </entry>
4981 5103
 			</row>
5104
+			<row>
5105
+			    <entry>
5106
+				replace
5107
+			    </entry>
5108
+			    <entry>
5109
+				textops
5110
+			    </entry>
5111
+			    <entry>
5112
+				RegExp, Substitute
5113
+			    </entry>
5114
+			    <entry>
5115
+				find the first occurence of a string matching the regular 
5116
+				expression in header or body and replace it with a substitute
5117
+			    </entry>
5118
+			</row>
5119
+			<row>
5120
+			    <entry>
5121
+				replace_all
5122
+			    </entry>
5123
+			    <entry>
5124
+				textops
5125
+			    </entry>
5126
+			    <entry>
5127
+				RegExp, Substitute
5128
+			    </entry>
5129
+			    <entry>
5130
+				find all occurences of a string matching the regular 
5131
+				expression in header or body and replace it with a substitute
5132
+			    </entry>
5133
+			</row>
4982 5134
 			<row>
4983 5135
 			    <entry>
4984 5136
 				save
... ...
@@ -5005,7 +5157,7 @@ if (len_gt(1024)) {
5005 5157
 				regular expression
5006 5158
 			    </entry>
5007 5159
 			    <entry>
5008
-				search for a regular expression match in request
5160
+				search for a regular expression match in request header of body
5009 5161
 			    </entry>
5010 5162
 			</row>
5011 5163
 
... ...
@@ -5129,6 +5281,20 @@ if (len_gt(1024)) {
5129 5281
 			    <entry>none</entry>
5130 5282
 			    <entry>prints list of available FIFO commands</entry>
5131 5283
 			</row>
5284
+			<row>
5285
+			    <entry>arg</entry>
5286
+			    <entry>core</entry>
5287
+			    <entry>none</entry>
5288
+			    <entry>prints list of command-line arguments with which 
5289
+				<application moreinfo="none">ser</application> was started</entry>
5290
+			</row>
5291
+			<row>
5292
+			    <entry>pwd</entry>
5293
+			    <entry>core</entry>
5294
+			    <entry>none</entry>
5295
+			    <entry>prints <application moreinfo="none">ser</application>'s working
5296
+			    directory</entry>
5297
+			</row>
5132 5298
 			<row>
5133 5299
 			    <entry>version</entry>
5134 5300
 			    <entry>core</entry>
5135 5301
new file mode 100644
... ...
@@ -0,0 +1,7 @@
1
+<para>
2
+	This is a place-holder for user documentation of the voicemail system.
3
+</para>
4
+<para>
5
+	It will include what it is good for, how to get it running, its
6
+	current technical limitations, etc.
7
+</para>