operation.sgml

用来作为linux中SIP SERVER,完成VOIP网络电话中服务器的功能

				</listitem>
				<listitem>
				    <para>
					Set explicitly at which address 
					<application moreinfo="none">ser</application>
					should be listening, e.g., <varname>listen=192.168.2.16</varname>.
				    </para>
				</listitem>
				<listitem>
				    <para>
					Redirect log messages to standard error by setting
					<varname>log_stderror=yes</varname>
				    </para>
				</listitem>
				<listitem>
				    <para>
					Set appropriately high log level. (Be sure that you redirected logging
					to standard output. Flooding system logs with many detailed messages
					would make the logs difficult to read and use.) You can set the global
					logging threshold value with the option <varname>debug=nr</varname>,
					where the higher <varname>nr</varname> the more detailed output.
					If you wish to set log level only for some script events, include
					the desired log level as the first parameter of the
					<command moreinfo="none">log</command> action in your script.
					The messages will be then printed if <command moreinfo="none">log</command>'s
					level is lower than the global threshold, i.e., the lower the more
					noisy output you get.
					<example>
					    <title>Logging Script</title>
					    <programlisting format="linespecific">
&logging;
					    </programlisting>
					    <para>
						The following SIP message causes then logging output as shown
						bellow.
					    </para>
					    <programlisting format="linespecific">
REGISTER sip:192.168.2.16 SIP/2.0
Via: SIP/2.0/UDP 192.168.2.33:5060
From: sip:113311@192.168.2.16
To: sip:113311@192.168.2.16
Call-ID: 00036bb9-0fd305e2-7daec266-212e5ec9@192.168.2.33
Date: Thu, 27 Feb 2003 15:10:52 GMT
CSeq: 101 REGISTER
User-Agent: CSCO/4
Contact: sip:113311@192.168.2.33:5060
Content-Length: 0
Expires: 600                                 
					    </programlisting>
					    <programlisting format="linespecific">
[jiri@cat sip_router]$ ./ser -f examples/logging.cfg 
Listening on 
              192.168.2.16 [192.168.2.16]::5060
Aliases: cat.iptel.org:5060 cat:5060 
WARNING: no fork mode 
 0(0) INFO: udp_init: SO_RCVBUF is initially 65535
 0(0) INFO: udp_init: SO_RCVBUF is finally 131070
 0(17379) REGISTER received
 0(17379) request for other domain received					
					    </programlisting>
					</example>
				    </para>
				</listitem>
			    </itemizedlist>
			</para>
			</answer>
		</qandaentry>
	    <qandaentry>
		<question>
		    <para>
			Labeling Outbound Requests
		    </para>
		</question>
		<answer>
		    <para>
		    Without knowing, which pieces of script code a relayed
		    request visited, trouble-shooting would be difficult.
		    Scripts typically apply different processing to
		    different routes such as to IP phones and PSTN
		    gateways. We thus recommend to label outgoing
		    requests with a label describing the type of processing
		    applied to the request.
			</para>
		    <para>
			Attaching "routing-history" hints to relayed
			requests is as easy as using the 
			<command moreinfo="none">append_hf</command>
			action exported by textops module. The following
			example shows how different labels are attached
			to requests to which different routing logic
			was applied.
			<example>
			    <title>"Routing-history" labels</title>
			    <programlisting format="linespecific">
# is the request for our domain?
# if so, process it using UsrLoc and label it so.
if (uri=~[@:\.]domain.foo") {
   if (!lookup("location")) {
    sl_send_reply("404", "Not Found");
    break;
   };
   # user found -- forward to him and label the request
   append_hf("P-hint: USRLOC\r\n");
} else {
# it is an outbound request to some other domain --
# indicate it in the routing-history label
   append_hf("P-hint: OUTBOUND\r\n");
};
t_relay();
			    </programlisting>
			    <para>
				This is how such a labeled requests looks
				like. The last header field includes
				a label indicating the script processed
				the request as outbound.
			    </para>
			    <programlisting format="linespecific">
#
U 2002/09/26 02:03:09.807288 195.37.77.101:5060 -> 203.122.14.122:5060
SUBSCRIBE sip:rajesh@203.122.14.122 SIP/2.0.
Max-Forwards: 10.
Via: SIP/2.0/UDP 195.37.77.101;branch=53.b44e9693.0.
Via: SIP/2.0/UDP 203.122.14.115:16819.
From: sip:[e-mail];tag=5c7cecb3-cfa2-491d-a0eb-72195d4054c4.
To: sip:rajesh@203.122.14.122.
Call-ID: bd6c45b7-2777-4e7a-b1ae-11c9ac2c6a58@203.122.14.115.
CSeq: 2 SUBSCRIBE.
Contact: sip:203.122.14.115:16819.
User-Agent: Windows RTC/1.0.
Proxy-Authorization: Digest username="rajeshacl", realm="iptel.org", algorithm="MD5", uri="sip:rajesh@203.122.14.122", nonce="3d924fe900000000fd6227db9e565b73c465225d94b2a938", response="a855233f61d409a791f077cbe184d3e3".
Expires: 1800.
Content-Length: 0.
P-hint: OUTBOUND.			    </programlisting>
			</example>
		</para>
		</answer>
	    </qandaentry>
	</qandaset>
	</section> <!-- operational practises -->

	<section>
	    <title>HOWTOs</title>
	    <para>
		This section is a "cookbook" for dealing with common tasks,
		such as user management or controlling access
		to PSTN gateways.
	    </para>
	    <section>
		<title>User Management</title>

			<para>
			    There are two tasks related to management of SIP users:
			    maintaining user accounts and maintaining user contacts.
			    Both these jobs can be done using the 
			    <application moreinfo="none">serctl</application>
			    command-line tool. Also, the complimentary web
			    interface, <application moreinfo="none">serweb</application>,
			    can be used for this purpose as well.
			</para>
			<para>
			    If user authentication is turned on, which is a highly
			    advisable practice, user account must be created before
			    a user can log in. To create a new user account, call the
			    <command moreinfo="none">serctl add</command> utility
			    with username, password and email as parameters. It
			    is important that the environment <varname>SIP_DOMAIN</varname>
			    is set to your realm and matches realm values used in
			    your script. The realm value is used for calculation
			    of credentials stored in subscriber database, which are
			    bound permanently to this value.
			    <screen format="linespecific">
[jiri@cat gen_ha1]$ export SIP_DOMAIN=foo.bar
[jiri@cat gen_ha1]$ serctl add newuser secret [e-mail]
MySql Password: 
new user added
			    </screen>
			</para>
			<para><application moreinfo="none">serctl</application> can
			    also change user's password or remove existing accounts
			    from system permanently.
			    <screen format="linespecific">
[jiri@cat gen_ha1]$ serctl passwd newuser newpassword
MySql Password: 
password change succeeded
[jiri@cat gen_ha1]$ serctl rm newuser                
MySql Password: 
user removed
			    </screen>
			</para>
			<para>
			    User contacts are typically automatically uploaded by SIP phones
			    to server during registration process and administrators do not
			    need to worry about them. However, users
			    may wish to append permanent contacts to PSTN gateways
			    or to locations in other administrative domains. 
			    To manipulate the contacts in such cases, use
			    <application moreinfo="none">serctl ul</application>
			    tool. Note that this is the only correct way
			    to update contacts -- direct changes to back-end
			    MySql database do not affect server's memory. Also note,
			    that if persistence is turned off (usrloc "db_mode"
			    parameter set to "0"), all contacts are gone on server
			    reboot. Make sure that persistence is enabled if you
			    add permanent contacts.
			</para>
			<para>
			    To add a new permanent contact for a user, call 
			    <application moreinfo="none">serctl ul add &lt;username&gt
			    &lt;contact&gt;</application>. To delete 
			    all user's contacts, call 
			    <application>serctl ul rm &lt;username&gt;</application>.
			    <application moreinfo="none">serctl ul show &lt;username&gt;</application>
			    prints all current user's contacts.
			    <screen format="linespecific">
[jiri@cat gen_ha1]$ serctl ul add newuser sip:[e-mail]
sip:[e-mail]
200 Added to table
('newuser','sip:[e-mail]') to 'location'
[jiri@cat gen_ha1]$ serctl ul show newuser
&lt;sip:[e-mail]&gt;;q=1.00;expires=1073741812
[jiri@cat gen_ha1]$ serctl ul rm newuser  
200 user (location, newuser) deleted
[jiri@cat gen_ha1]$ serctl ul show newuser
404 Username newuser in table location not found
			    </screen>
			</para>
	    </section> <!-- user management -->
	    <section>
		<title>User Aliases</title>

			<para>
			    Frequently, it is desirable for a user to have multiple
			    addresses in a domain. For example, a user with username "john.doe" wants to be
			    reachable at a shorter address "john" or at a numerical address
			    "12335", so that PSTN callers with digits-only key-pad can reach
			    him too.
			</para>
			<para>
			    With <application moreinfo="none">ser</application>, you can maintain
			    a special user-location table and translate existing aliases to canonical
			    usernames using the <command moreinfo="none">lookup</command>
			    action from usrloc module. The following script fragment demonstrates
			    use of <command moreinfo="none">lookup</command> for this purpose.
			    <example>
				<title>Configuration of Use of Aliases</title>
				<programlisting format="linespecific">
if (!uri==myself) { # request not for our domain...
  route(1); # go somewhere else, where outbound requests are processed
  break;
};
# the request is for our domain -- process registrations first
if (method=="REGISTER") { route(3); break; };

# look now, if there is an alias in the "aliases" table; don't care
# about return value: whether there is some or not, move ahead then
lookup("aliases");

# there may be aliases which translate to other domain and for which
# local processing is not appropriate; check again, if after the
# alias translation, the request is still for us
if (!uri==myself) { route(1); break; };

# continue with processing for our domain...
...
  
				</programlisting>
			    </example>
			</para>
			<para>
			    The table with aliases is updated using the
			    <application moreinfo="none">serctl</application>
			    tool. <application moreinfo="none">
			    serctl alias add &lt;alias&gt; &lt;uri&gt;</application>
			    adds a new alias, 
			    <application moreinfo="none">serctl alias show &lt;user&gt;</application>
			    prints an existing alias, and
			    <application moreinfo="none">serctl alias rm &lt;user&gt;</application>
			    removes it.
			    <screen format="linespecific">
[jiri@cat sip_router]$ serctl alias add 1234 sip:[e-mail]
sip:[e-mail]
200 Added to table
('1234','sip:[e-mail]') to 'aliases'
[jiri@cat sip_router]$ serctl alias add john sip:[e-mail]
sip:[e-mail]
200 Added to table
('john','sip:[e-mail]') to 'aliases'
[jiri@cat sip_router]$ serctl alias show john                    
&lt;sip:[e-mail]&gt;;q=1.00;expires=1073741811
[jiri@cat sip_router]$ serctl alias rm john  
200 user (aliases, john) deleted				
			    </screen>
			</para>
			<para>
			    Note that persistence needs to be turned on in usrloc
			    module. All changes to aliases will be otherwise lost
			    on server reboot. To enable persistence, set the
			    db_mode usrloc parameter to a non-zero value.
			    <programlisting format="linespecific">
# ....load module ...
loadmodule "modules/usrloc/usrloc.so"
# ... turn on persistence -- all changes to user tables are immediately
# flushed to mysql
modparam("usrloc", "db_mode",   1)
# the SQL address:
modparam("usrloc", "db_url","mysql://ser:secret@dbhost/ser")
			    </programlisting>
			</para>
	    </section> <!-- user aliases -->
	    <section id=acl>
		<title>Access Control (PSTN Gateway)</title>
			<para>
			    It is sometimes important to exercise some sort of
			    access control. A typical use case is when 
			    <application moreinfo="none">ser</application> is used
			    to guard a PSTN gateway. If a gateway was not well guarded,
			    unauthorized users would be able to use it to terminate calls in PSTN,
			    and cause high charges to its operator.
			</para>
			<para>
			    There are few issues you need to understand when
			    configuring <application moreinfo="none">ser</application>
			    for this purpose. First, if a gateway is built or configured to
			    accept calls from anywhere, callers may easily bypass your
			    access control server and communicate with the gateway
			    directly. You then need to enforce at transport layer
			    that signaling is only accepted if coming via
			    <application moreinfo="none">ser</application> and
			    deny SIP packets coming from other hosts and port numbers.
			    Your network must be configured not to allow forged
			    IP addresses. Also, you need to turn on record-routing
			    to assure that all session requests will travel via 
			    <application moreinfo="none">ser</application>.			    
			    Otherwise, caller's devices would send subsequent SIP requests 
			    directly to your gateway, which would fail because of transport 
			    filtering.
			</para>
			<para>
			    Authorization (i.e., the process of determining who may call where)
			    is facilitated in <application moreinfo="none">ser</application>
			    using <emphasis>group membership</emphasis> concept. Scripts make 
			    decisions on whether a caller is authorized to make a call to
			    a specific destination based on user's membership in a group.
			    For example a policy may be set up to allow calls to international
			    destinations only to users, who are members of an "int" group.			    
			    Before user's group membership is checked, his identity
			    must be verified first. Without cryptographic verification of user's
			    identity, it would be impossible to assert that a caller really
			    is who he claims to be.
			</para>
			<para>
			    The following script demonstrates, how to configure <application moreinfo="none">ser</application>
			    as an access control server for a PSTN gateway. The script verifies user
			    identity using digest authentication, checks user's privileges,
			    and forces all requests to visit the server.
			    <example>
				<title>Script for Gateway Access Control</title>
				<programlisting format="linespecific">
&gatewayacl;
				</programlisting>
			    </example>
			</para>
			<para>
			    Use the <application moreinfo="none">serctl</application> tool to
			    maintain group membership. 
			    <application moreinfo="none">serctl acl grant &lt;username&gt; &lt;group&gt;</application>
			    makes a user member of a group, 
			    <application>serctl acl show &lt;username&gt;</application> shows groups
			    of which a user is member, and
			    <application>serctl acl revoke &lt;username&gt; [&lt;group&gt;]</application>
			    revokes user's membership in one or all groups.
			    <screen format="linespecific">
[jiri@cat sip_router]$ serctl acl grant john int
MySql Password: 
+------+-----+---------------------+
| user | grp | last_modified       |