</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.0Via: SIP/2.0/UDP 192.168.2.33:5060From: sip:113311@192.168.2.16To: sip:113311@192.168.2.16Call-ID: 00036bb9-0fd305e2-7daec266-212e5ec9@192.168.2.33Date: Thu, 27 Feb 2003 15:10:52 GMTCSeq: 101 REGISTERUser-Agent: CSCO/4Contact: sip:113311@192.168.2.33:5060Content-Length: 0Expires: 600                                 					    </programlisting>					    <programlisting format="linespecific">[jiri@cat sip_router]$ ./ser -f examples/logging.cfg Listening on               192.168.2.16 [192.168.2.16]::5060Aliases: 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:5060SUBSCRIBE 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:rajeshacl@iptel.org;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 newuser@foo.barMySql 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 newpasswordMySql 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:666@gateway.foo.barsip:666@gateway.foo.bar200 Added to table('newuser','sip:666@gateway.foo.bar') to 'location'[jiri@cat gen_ha1]$ serctl ul show newuser&lt;sip:666@gateway.foo.bar&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 newuser404 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 firstif (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 thenlookup("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 usif (!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:john.doe@foo.barsip:john.doe@foo.bar200 Added to table('1234','sip:john.doe@foo.bar') to 'aliases'[jiri@cat sip_router]$ serctl alias add john sip:john.doe@foo.barsip:john.doe@foo.bar200 Added to table('john','sip:john.doe@foo.bar') to 'aliases'[jiri@cat sip_router]$ serctl alias show john                    &lt;sip:john.doe@foo.bar&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 mysqlmodparam("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 intMySql Password: +------+-----+---------------------+| user | grp | last_modified       |