intro.sgml

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

                proxy_challenge("foo.bar", "0");
                break;
        };
        forward(192.168.0.10,5060);
}

		    </programlisting>
		</example>
	    </para>
	</section>

	<section>
	    <title>Writing Scripts</title>
	    <para>
		This section demonstrates simple examples
		how to configure server's behavior using the
		<application moreinfo="none">ser</application>
		request routing language. All configuration scripts follow the 
		<application moreinfo="none">ser</application> language 
		syntax, which dictates the following section ordering:
		<itemizedlist>
		    <listitem>
			<para>
			    <emphasis>global configuration parameters</emphasis> --
			    these value affect behavior of the server such as port
			    number at which it listens, number of spawned children
			    processes, and log-level. See <xref linkend="coreoptions">
			    for a list of available options.
			</para>
		    </listitem>

		    <listitem>
			<para>
			    <emphasis>module loading</emphasis> -- these statements
			    link external modules, such as transaction management
			    (tm) or stateless UA server (sl)  dynamically. See
			    <xref linkend="modulereference"> for a list of modules
			    included in <application moreinfo="none">ser</application>
			    distribution.
			</para>
			<note>
				<para>
					If modules depend on each other, than the depending
					modules must be loaded after modules on which they
					depend. We recommend to load first modules
					<command>tm</command> and <command>sl</command>
					because many other modules (authentication, user
					location, accounting, etc.) depend on these.
				</para>
			</note>
		    </listitem>
		    <listitem>
			<para>
			    <emphasis>module-specific parameters</emphasis> -- determine
			    how modules behave; for example, it is possible to configure
			    database to be used by authentication module.
			</para>
		    </listitem>
		    <listitem>
			<para>
			    one or more <emphasis>route blocks</emphasis> containing the
			    request processing logic, which includes built-in actions
			    as well as actions exported by modules. See <xref linkend="builtinref">
			    for a list of built-in actions.
			</para>
		    </listitem>
		    <listitem>
			<para>
			    optionally, if modules supporting reply
			    processing (currently only TM) are loaded,
			    one or more <emphasis>failure_route blocks</emphasis> containing
			    logic triggered by received replies. Restrictions on use of
			    actions within <command moreinfo="none">failure_route</command>
			    blocks apply -- see <xref linkend="builtinref"> for more
			    information.
			</para>
		    </listitem>
		</itemizedlist>
	    </para>

	    <section id="defaultscript">
		<title>Default Configuration Script</title>		
		<para>
		    The configuration script, <filename moreinfo="none">ser.cfg</filename>,
		    is a part of every <application moreinfo="none">ser</application>
		    distribution and defines default behavior. It allows users
		    to register with the server and have requests proxied to each
		    other.
		</para>
		<para>
		    After performing
		    routine checks, the script looks whether incoming request is for
		    served domain. If so and the request is "REGISTER", <application moreinfo="none">ser</application>
		    acts as SIP registrar and updates database of user's contacts.
		    Optionally, it verifies user's identity first to avoid
		    unauthorized contact manipulation.
		</para>
		<para>
		    Non-REGISTER requests for served domains are then processed using
		    user location database. If a contact is found for requested URI,
		    script execution proceeds to stateful forwarding, a negative 404
		    reply is generated otherwise. Requests outside served domain
		    are always statefully forwarded.
		</para>
		<para>
		    Note that this simple script features several limitations:
		    <itemizedlist>
			<listitem>			    
			    <para>
				By default, authentication is turned off to avoid
				dependency on mysql. Unless it it turned on, anyone
				can register using any name and "steal" someone else's
				calls.
			    </para>
			</listitem>
			<listitem>
			    <para>
				Even it authentication is turned on, there is no relationship
				between authentication username and address of record. That
				means that for example a user authenticating himself correctly
				with "john.doe" id may register contacts for "gw.bush".
				Site policy may wish to mandate authentication id to be equal
				to username claimed in To header field. <action moreinfo="none">check_to</action>
				action from auth module can be used to enforce such a policy.
			    </para>
			</listitem>
			<listitem>
			    <para>
				There is no dialing plan implemented. All users are supposed to
				be reachable via user location database. See <xref linkend="numberingplans">
				for more information.
			    </para>
			</listitem>
			<listitem>
			    <para>
				The script assumes users will be using server's name as a part of
				their address of record. If users wish to use another name (domain
				name for example), this must be set using the <varname>alias</varname>
				options. See <xref linkend="domainmatching"> for more information.
			    </para>
			</listitem>
			<listitem>
			    <para>
				If authentication is turned on by uncommenting related configuration
				options, clear-text user passwords will by assumed in back-end database.
			    </para>
			</listitem>
		    </itemizedlist>
		</para>
		<example>
		    <title>Default Configuration Script</title>
		    <programlisting format="linespecific">
&defscr;			
		    </programlisting>
		</example>
	    </section>

	    <section id="statefulua">
		<title>Stateful User Agent Server</title>
		<para>
		    This examples shows how to make ser act as a stateful user
		    agent (UA). Ability to act as as a stateful UA is essential
		    to many applications which terminate a SIP path. These
		    applications wish to focus on their added value. They
		    do not wish to be involved in all SIP gory details, such
		    as request and reply retransmission, reply formatting, etc.
		    For example, we use the UA functionality to shield 
		    SMS gateway and instant message store from SIP transactional
		    processing.
		    The simple example bellow issues a log report on receipt
		    of a new transaction. 
		    If we did not use a stateful UA, every single request retransmission
		    would cause the application to be re-executed which would result in
		    duplicated SMS messages, instant message in message store or 
		    log reports.
		</para>
		<para>
		    The most important actions are <command moreinfo="none">
			t_newtran</command> and <command moreinfo="none">
			t_reply</command>. <command moreinfo="none">
			
		    t_newtran</command> shields subsequent code from retransmissions.
		    It returns success and continues when a new request arrived.
		    It exits current route block immediately on receipt of
		    a retransmission. It only returns a negative value when
		    a serious error, such as lack of memory, occurs.
		</para>
		<para>
		    <command moreinfo="none">t_reply</command> generates
		    a reply for a request. It generates the reply statefully,
		    i.e., it is kept for future retransmissions in memory.
		</para>
		<note>
			<para>
				Applications that do not need stateful processing
				may act as stateless UA Server too. They just use
				the <command>sl_send_reply</command> action to
				send replies to requests without keeping any
				state. The benefit is memory cannot run out,
				the drawback is that each retransmission needs to
				be processed as a new request. An example of use
				of a stateless server is shown in
		    	<xref linkend="redirectserver"> and
		    	<xref linkend="executingscript">.
			</para>
		</note>
		<example>
		    <title>Stateful UA Server</title>
		    <programlisting format="linespecific">
			<!-- ../../examples/uas.cfg -->
			&statefuluaexample;
		    </programlisting>
		</example>
	    </section> <!-- Stateful UAS -->

	    <section id="redirectserver">
		<title>Redirect Server</title>
		<para>
		    The redirect example shows how to redirect a request
		    to multiple destination using 3xx reply. Redirecting
		    requests as opposed to proxying them is essential to
		    various scalability scenarios. Once a message is
		    redirected, <application moreinfo="none">ser</application>
		    discards all related state and is no more involved
		    in subsequent SIP transactions (unless the redirection
		    addresses point to the same server again).
		</para>
		<para>
		    The key <application>ser</application> actions in this example 
		    are <command moreinfo="none">append_branch</command> and 
		    <command moreinfo="none">sl_send_reply</command> (sl module).
		</para>
		<para>
		    <command moreinfo="none">append_branch</command> adds
		    a new item to the destination set. The destinations set always
		    includes the current URI and may be enhanced up to
		    <constant>MAX_BRANCHES</constant> items.
		    <command moreinfo="none">sl_send_reply</command> command, 
		    if passed SIP reply code 3xx, takes all values in current 
		    destination set and adds them to Contact header field in 
		    the reply being  sent.
		</para>
		<example id="redirectexample">
		    <title>Redirect Server</title>
		    <programlisting format="linespecific">
			<!-- ../../examples/redirect.cfg -->
			&redirectexample;
		    </programlisting>
		</example>
	    </section> <!-- redirect server-->
	    
	    <section id="executingscript">
		<title>Executing External Script</title>
		<para>
		    Like in the previous example, we show how to
		    make <application>ser</application> act as a redirect server. The difference is 
		    that we do not use redirection addresses hardwired in
		    <application moreinfo="none">ser</application> script but
		    get them from external shell commands. We also use
		    ser's ability to execute shell commands to log
		    source IP address of incoming SIP requests.
		</para>
		<para>
		    The new commands introduced in this example are
		    <command moreinfo="none">exec_msg</command> and
		    <command moreinfo="none">exec_dset</command>.
		    <command moreinfo="none">exec_msg</command> takes
		    current requests, starts an external command, and
		    passes the requests to the command's standard input.
		    It also passes request's source IP address in
		    environment variable named <constant>SRCIP</constant>.
		</para>
		<para>
		    <command moreinfo="none">exec_dset</command> serves
		    for URI rewriting by external applications.  The
		    <command moreinfo="none">exec_dset</command> action
		    passes current URI to the called external program, 
		    and rewrites current destination
		    set with the program's output. An example use would
		    be an implementation of a Least-Cost-Router, software which
		    returns URI of the cheapest PSTN provider for a given
		    destination based on some pricing tables. <xref linkend="execscript">
		    is much easier: it prints fixed URIs on its output using
		    shell script <command moreinfo="none">echo</command> command.
		</para>
		<note>
			<para>
				This script works statelessly -- it uses this action for
				stateless replying, <command>sl_send_reply</command>.
				No transaction is kept in memory and each request retransmission
				is processed as a brand-new request. That may be a particular
				concern if the server logic (<command>exec</command> actions
				in this example) is too expensive. See 
		    	<xref linkend="statefulua"> for instructions on how
				to make server logic stateful, so that retransmissions
				are absorbed and do not cause re-execution of the logic.
			
			</para>
		</note>
		<example id="execscript">
		    <title>Executing External Script</title>
		    <programlisting format="linespecific">
			<!-- ../../examples/exec.cfg -->
			&execexample;
		    </programlisting>
		</example>
	    </section> <!-- exec example -->
	    
	    <section id="replyprocessingsection">
		<title>On-Reply Processing (Forward on Unavailable)</title>
		<para>
		    Many services depend on status of messages relayed
		    downstream: <emphasis>forward on busy</emphasis> and 
		    <emphasis>forward on no reply</emphasis> to name the
		    most well-known ones. To support implementation of
		    such services, <application moreinfo="none">ser</application>
		    allows to return to request processing when request
		    forwarding failed. When a request is reprocessed,
		    new request branches may be initiated or the transaction
		    can be completed at discretion of script writer.
		</para>
		<para>
		    The primitives used are <command moreinfo="none">t_on_failure(r)</command>
		    and <command moreinfo="none">failure_route[r]{}.</command> If
		    <command>t_on_failure</command> is called before
		    a request is statefully forwarded and a forwarding failure occurs, 
		    <application moreinfo="none">ser</application>
		    will return to request processing in a <command moreinfo="none">failure_route</command>
		    block. Failures include receipt of a SIP error
		    (status code >= 300 ) from downstream or not receiving
		    any final reply within final response period.
		</para>
		<para>
		    The length of the timer is governed by parameters of the
		    tm module. <varname>fr_timer</varname> is the length of
		    timer set for non-INVITE transactions and INVITE transactions
		    for which no provisional response is received. If a timer
		    hits, it indicates that a downstream server is unresponsive.
		    <varname>fr_inv_timer</varname> governs time to wait for 
		    a final reply for an INVITE. It is typically longer than
		    <varname>fr_timer</varname> because final reply may take
		    long time until callee (finds a mobile phone in a pocket and)
		    answers the call.
		</para>
		<para>
		    In <xref linkend="replyprocessing">, <command moreinfo="none">failure_route[1]</command>
		    is set to be entered on error using the <command moreinfo="none">t_on_failure(1)</command>
		    action. Within this reply block, <application moreinfo="none">ser</application>
		    is instructed to initiate a new branch and try to reach called party
		    at another destination (sip:[e-mail]). To deal with the case when neither the alternate
		    destination succeeds, <application moreinfo="none">t_on_failure</application>
		    is set again. If the case really occurs, <command moreinfo="none">failure_route[2]</command>
		    is entered and a last resort destination (sip:[e-mail]) is tried.
		</para>
		<example id="replyprocessing">
		    <title>On-Reply Processing</title>
		    <programlisting format="linespecific">
			<!-- ../../examples/onr.cfg -->
			&replyexample;
		    </programlisting>

		</example>
	    </section> <!-- reply processing -->
	</section> <!-- examples -->
    </chapter>