reference.sgml

SIP Express Router, Linux下的SIP代理服务器,小巧实用,开发测试VoIP设备和应用的必备.

    <chapter>
	<title>Reference</title>
	<section id="coreoptions">
	    <title>Core Options</title>
	    <para>Core options are located in beginning of configuration file and
	    affect behavior of the server.</para>
	    <itemizedlist>
		<listitem>
		    <para>
			<varname>debug</varname> - Set log level, this is number between 0 and 9. Default 
			is 0.
			
		    </para>
		</listitem>
		<listitem>
		    <para>
			<varname>fork</varname> - If set to yes, the server will spawn children. If set to no, the main
			process will be processing all messages. Default is yes.
			<note>
			    <para>
				Disabling child spawning is useful mainly for
				debugging. When <varname>fork</varname> is turned off,
				some features are unavailable: 
				there is no attendant process, no pid file is generated,
				and server listens only at one address. Make sure you
				are debugging the same interface at which 
				<application moreinfo="none">ser</application> listens.
				The easiest way to do so is to set the interface using
				<varname>listen</varname> option explicitly.
				</para>
			</note>
		    </para>
		</listitem>
		<listitem>
		    <para>
			<varname>log_stderror</varname> - If set to yes, the server will print its debugging 
			information to standard error output. If set to no, <command moreinfo="none">syslog</command> 
			will be used. Default is no (printing to syslog).
		    </para>
		</listitem>
		<listitem>
		    <para>
			<varname>listen</varname> - list of all IP addresses or hostnames SER should listen on.
			<note>
				<para>
					This parameter may repeat several times, then SER will
					listen on all addresses. For example, the following
					command-line options (equivalent to "listen" config
					option) may be used: 
					<command>
						ser -l foo  -l bar -p 5061 -l x -l y 
					</command>
					will listen on foo:5060, bar:5061 & x:5061 & y:5061

				</para>
			</note>
		    </para>
		</listitem>
		<listitem>
		    <para>
			<varname>alias</varname> - Add IP addresses or hostnames to list of name aliases.
			All requests with hostname matching an alias will satisfy the condition 
			"uri==myself".
		    </para>
		</listitem>
		<listitem>
		    <para>
			<varname>dns</varname> - Uses dns to check if it is necessary to add a "received=" field to a via.
			Default is no.
		    </para>
		</listitem>
		<listitem>
		    <para>
			<varname>rev_dns</varname> - Same as dns but use reverse DNS. Default is no.
		    </para>
		</listitem>
		<listitem>
		    <para>
			<varname>port</varname> - Listens on the specified port (default 5060). It applies to the last 
			address specified in listen and to all the following that do not have a corresponding "port" option.
		    </para>
		</listitem>
		<listitem>
		    <para>
			<varname>maxbuffer</varname> - Maximum receive buffer size which will not be exceeded by 
			the auto-probing procedure even if the OS allows. Default value is MAX_RECV_BUFFER_SIZE,
			which is 256k.
		    </para>
		</listitem>
		<listitem>
		    <para>
			<varname>children</varname> - Specifies how many processes should be started
		        for each transport protocol. 
		    Running multiple children allows a server to 
			server multiple requests in parallel when request processing block (e.g., on DNS
			lookup). Note that <application>ser</application> typically spawns additional
			processes, such as timer process or FIFO server. If FIFO server is turned on,
			you can watch running processes using the <application moreinfo="none">serctl</application>
			utility.


		    </para>
		</listitem>
		<listitem>
		    <para>
			<varname>check_via</varname> - Turn on or off Via host checking when forwarding replies.
			Default is no.
		    </para>
		</listitem>
		<listitem>
		    <para>
			<varname>syn_branch</varname> - Shall the server use stateful synonym branches? It is faster but not 
			reboot-safe. Default is yes.
		    </para>
		</listitem>
		<listitem>
		    <para>
			<varname>memlog</varname> - Debugging level for final memory statistics report. Default is L_DBG --
			memory statistics are dumped only if <varname>debug</varname> is set high.
		    </para>
		</listitem>
		<listitem>
		    <para>
			<varname>sip_warning</varname> - Should replies include extensive warnings? By default yes,
			it is good for trouble-shooting.
		    </para>
		</listitem>
		<listitem>
		    <para>
			<varname>fifo</varname> - FIFO special file pathname, for example "/tmp/ser_fifo". Default is
			no filename -- no FIFO server is started then. We recommend to set it so that
			accompanying applications such as <application moreinfo="none">serweb</application> or
			<application moreinfo="none">serctl</application> can communicate with
			<application moreinfo="none">ser</application>.
		    </para>
		</listitem>
		<listitem>
		    <para>
			<varname>fifo_mode</varname> - Permissions of the FIFO special file.
		    </para>
		</listitem>
		<listitem>
		    <para>
			<varname>server_signature</varname> - Should locally-generated messages include server's signature?
			By default yes, it is good for trouble-shooting.
		    </para>
		</listitem>
		<listitem>
		    <para>
			<varname>reply_to_via</varname> - A hint to reply modules
			whether they should send reply
			to IP advertised in Via.
			Turned off by default, which means that replies are
			sent to IP address from which requests came from. 
		    </para>
		</listitem>
		<listitem>
		    <para>
			<varname>user | uid</varname> - uid to be used by the server. 
		    </para>
		</listitem>
		<listitem>
		    <para>
			<varname>group | gid</varname> - gid to be used by the server.
		    </para>
		</listitem>
		<listitem>
		    <para>
			<varname>mhomed</varname> -- enable calculation of 
			outbound interface; useful on multihomed servers,
			ser <link linkend="mhomed"></link>.
		    </para>
		</listitem>
		<listitem>
		    <para>
			<varname>loadmodule</varname> - Specifies a module to be loaded (for example "/usr/lib/ser/modules/tm.so")
		    </para>
		</listitem>
		<listitem>
		    <para>
			<varname>modparam</varname> - Module parameter configuration. The commands takes three parameters:
			<itemizedlist>
			    <listitem>
				<para>
				    <emphasis>module</emphasis> - Module in which the parameter resides.
				</para>
			    </listitem>
			    <listitem>
				<para>
				    <emphasis>parameter</emphasis> - Name of the parameter to be configured.
				</para>
			    </listitem>
			    <listitem>
				<para>
				    <emphasis>value</emphasis> - New value of the parameter.
				</para>
			    </listitem>
			</itemizedlist>
		    </para>
		</listitem>
	    </itemizedlist>
	</section>
	<section id="builtinref">
	    <title>Core Commands</title>


	    <itemizedlist id="routeblocks">
		<title>Route Blocks and Process Control</title>
		<!--<para>
		    Route block and process control keywords determine
		    the order in which SIP requests are processed.
		</para>-->
		<listitem>
		    <para>
			<command>route[number]{...}</command> - This marks a "route block" in configuration files.
			route blocks are basic building blocks of <application>ser</application> scripts. 
			Each route block contains a sequence of 
			<application>SER</application> actions enclosed in braces. Multiple route blocks
			can be included in a configuration file.
			When script execution begins on request receipt, 
			route block number 0 is entered. Other route blocks serve as a kind of sub-routines and 
			may be entered by calling the action <command>route(n)</command>, 
			where n is number of the block. The action <command>break</command>
			exits currently executed route block. It stops script execution for
			route block number 0 or returns to calling route block otherwise.
		    </para>
		    <example>
			<title>route</title>
			<programlisting format="linespecific">
route[0] {
        # call routing block number 2
	route(2);
}

route[2] {
    forward("host.foo.bar", 5060);
}
</programlisting>
		    </example>
		</listitem>
		<listitem>
		    <para>
			<command>failure_route</command> is used to restart request processing
			when a negative reply for a previously relayed request is received. It is only
			used along with tm module, which stores the original requests and
			can return to their processing later. To activate processing
			of a <command>failure_route</command> block, call the TM action
			<command>t_on_failure(route_number)</command> before calling
			<command moreinfo="none">t_relay</command>. When a negative reply
			comes back, the desired <command moreinfo="none">failure_route</command>
			will be entered and processing of the original request may
			continue. 
			</para>
		    <para>
			The set of actions applicable from within
			<command moreinfo="none">failure_route</command> blocks is limited.
			Permitted actions are URI-manipulation actions, logging and
			sending stateful replies using <command moreinfo="none">t_reply</command>.
		    </para>
		    <example>
			<title>failure_route</title>
			<programlisting format="linespecific">
failure_route[1] {
    # for some reason, the original forwarding attempt
    # failed, try at another URI
    append_branch("sip:[e-mail]");
    # if this new attempt fails too, try another failure_route
    t_on_failure("2");
	t_relay();
}
</programlisting>
		    </example>
		</listitem>

		<listitem>
		    <para>
		    	The action <command>break</command> exits currently executed route block. 
			It stops script execution for route block number 0 or returns to calling 
			route block otherwise.
			<note>
			    <para>
				We recommend to use <command moreinfo="none">break</command>
				after any request forwarding or replying. This practice
				helps to avoid erroneous scripts that 
				continue execution and mistakenly send another reply or
				forward a request to another place, resulting in
				protocol confusion.
			    </para>
			</note>
		    </para>
		    <para>
			<emphasis>Example:</emphasis> break;
		    </para>
		</listitem>

		<listitem>
		    <para>
			<command>route(n)</command> - call routing block route[n]{...};
			when the routing block n finishes processing, control is passed
			back to current block and processing continues.
		    </para>
		</listitem>

		<listitem>
		    <para>
			<command>if (condition) statement</command> - Conditional statement.
		    </para>
		    <example>
			<title>Use of <command>if</command></title>
			<programlisting format="linespecific">
if (method=="REGISTER) {
    log("register received\n");
};
</programlisting>
		    </example>
		</listitem>
		<listitem>
		    <para>
			<command>if - else</command> - If-Else Conditional statement.
		    </para>
		    <example>
			<title>Use of <command>if-else</command></title>
			<programlisting format="linespecific">
if (method=="REGISTER) {
    log("register received\n");
} else {
    log("non-register received\n");
};
</programlisting>
		    </example>
		</listitem>

	    </itemizedlist>
	    <itemizedlist>
		<title>Flag Manipulation</title>
		<listitem>
		    <para>
			<command>setflag</command> - Set flag in the message.
		    </para>
		    <para>
			<emphasis>Example:</emphasis> setflag(1);
		    </para>
		</listitem>
		<listitem>
		    <para>
			<command>resetflag</command> - Reset flag in the message.
		    </para>
		    <para>
			<emphasis>Example:</emphasis> resetflag(1);
		    </para>
		</listitem>
		<listitem>
		    <para>
			<command>isflagset</command> - Test whether a particular flag is set.
		    </para>
		    <example>
			<title>isflagset</title>
			<programlisting format="linespecific">
if (isflagset(1)) {
    ....
};
</programlisting>
		    </example>
		</listitem>
	    </itemizedlist>
	    <itemizedlist>
		<title>Manipulation of URI and Destination Set</title>
		<listitem>
		    <para>
			<command>rewritehost | sethost | seth</command> - Rewrite host part of the Request URI.
		    </para>
		    <para>
			<emphasis>Example:</emphasis> sethost("foo.bar.com");
		    </para>
		</listitem>
		<listitem>
		    <para>
			<command>rewritehostport | sethostport | sethp</command> - Rewrite host and port part of the Request URI.
		    </para>
		    <para>
			<emphasis>Example:</emphasis> sethostport("foo.bar.com:5060");
		    </para>
		</listitem>
		<listitem>
		    <para>
			<command>rewriteuser | setuser | setu</command> - Rewrite or set username part of the Request URI.
		    </para>
		    <para>
			<emphasis>Example:</emphasis> setuser("joe");
		    </para>
		</listitem>
		<listitem>
		    <para>
			<command>rewriteuserpass | setuserpass | setup</command> - Rewrite or set username and password part
			of the Request URI.
		    </para>
		    <para>
			<emphasis>Example:</emphasis> setuserpass("joe:mypass");
		    </para>
		</listitem>
		<listitem>
		    <para>
			<command>rewriteport | setport | setp</command> - Rewrite or set port of the Request URI.
		    </para>
		    <para>
			<emphasis>Example:</emphasis> setport("5060");
		    </para>
		</listitem>
		<listitem>
		    <para>
			<command>rewriteuri | seturi</command> - Rewrite or set the whole Request URI.
		    </para>
		    <para>
			<emphasis>Example:</emphasis> seturi("sip:[e-mail]:5060");
		    </para>
		</listitem>
		<listitem>
		    <para>
			<command>revert_uri</command> - Revert changes made to the Request URI and use original Request URI.
		    </para>
		    <para>
			<emphasis>Example:</emphasis> revert_uri();
		    </para>
		</listitem>
		<listitem>
		    <para>
			<command>prefix</command> - Add prefix to username in Request URI.
		    </para>
		    <para>
			<emphasis>Example:</emphasis> prefix("123");
		    </para>
		</listitem>
		<listitem>
		    <para>
			<command>strip</command> - Remove first n characters of username in Request URI.
		    </para>
		    <para>
			<emphasis>Example:</emphasis> strip(3);
		    </para>
		</listitem>
		<listitem>
		    <para>
			<command>append_branch</command> - Append a new destination to destination set of the message.
		    </para>
		    <para>
			<example>
			    <title>Use of <command>append_branch</command></title>
			    <programlisting format="linespecific">
# redirect to these two destinations: [e-mail] and [e-mail]
# 1) rewrite the current URI
rewriteuri("sip:[e-mail]");
# 2) append another entry to the destination ser
append_branch("sip:[e-mail]");
# redirect now
sl_send_reply("300", "redirection");
			    </programlisting>
			</example>
		    </para>
		</listitem>
	    </itemizedlist>
	    <itemizedlist>
		<title>Message Forwarding</title>
		<listitem>
		    <para>
			<command>forward(uri, port)</command> - Forward the request to given 
			destination statelessly.  The uri and port parameters may take special 
			values 'uri:host'
			and 'uri:port' respectively, in which case SER forwards to destination
			set in current URI. All other elements in a destination set are
			ignored by stateless forwarding.
		    </para>
		    <para>
			<emphasis>Example:</emphasis> forward("foo.bar.com"); # port defaults to 5060
		    </para>
		</listitem>
		<listitem>
		    <para>
			<command>send</command> - Send the message as is to a third party 
		    </para>
		    <para>
			<emphasis>Example:</emphasis> send("foo.bar.com");
		    </para>
		</listitem>
	    </itemizedlist>
	    <itemizedlist>
		<title>Logging</title>
		

		<listitem>