kamailio/misc/obsolete/exec/doc/exec.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<section id="exec" xmlns:xi="http://www.w3.org/2001/XInclude">
    <sectioninfo>
	<authorgroup>
	    <author>
		<firstname>Jiri</firstname>
		<surname>Kuthan</surname>
		<affiliation><orgname>FhG FOKUS</orgname></affiliation>
		<address>
		    <email>[email protected]</email>
		</address>
	    </author>
	</authorgroup>
	<copyright>
	    <year>2003</year>
	    <holder>FhG FOKUS</holder>
	</copyright>
    </sectioninfo>

    <title>Exec Module</title>

    <section id="exec.overview">
	<title>Overview</title>
	<para>
	    Exec module allows to start an external command from a ser
	    script. The commands may be any valid shell commands, the command
	    string is passed to shell using "popen" command. ser
	    passes additionally lot of information about request in environment
	    variables:
	</para>
	<itemizedlist>
	    <listitem>
		<para>
		    SIP_HF_&lt;hf_name&gt; contains value of each header field
	            in request. If a header field occurred multiple times,
	            values are concatenated and
	            comma-separated. &lt;hf_name&gt; is in capital letters. Ff
	            a header-field name occurred in compact form,
	            &lt;hf_name&gt; is canonical.
		</para>
	    </listitem>
	    <listitem>
		<para>
		    SIP_TID is transaction identifier. All request
		    retransmissions or CANCELs/ACKs associated with a previous
		    INVITE result in the same value.
		</para>
	    </listitem>
	    <listitem>
		<para>
		    SIP_DID is dialog identifier, which is the same as
		    to-tag. Initially, it is empty.
		</para>
	    </listitem>
	    <listitem>
		<para>
		    SIP_SRCIP is source IP address from which request came.
		</para>
	    </listitem>
	    <listitem>
		<para>
		    SIP_ORURI is original Request-URI.
		</para>
	    </listitem>
	    <listitem>
		<para>
		    SIP_RURI is <emphasis>current</emphasis> Request-URI (if unchanged, equal to original).
		</para>
	    </listitem>
	    <listitem>
		<para>
		    SIP_USER is userpart of <emphasis>current</emphasis> Request-URI.
		</para>
	    </listitem>
	    <listitem>
		<para>
		    SIP_OUSER is userpart of original Request-URI.
		</para>
	    </listitem>
	</itemizedlist>
    </section>

    <xi:include href="params.xml"/>
    <xi:include href="functions.xml"/>

    <section id="known_issues">
	<title>Known Issues</title>
	<para>
	    There is currently no guarantee that scripts ever return and stop
	    blocking SIP server. (There is <filename>kill.c</filename> but it
	    is not used along with the current mechanisms based on popen.
	    Besides that <filename>kill.c</filename> is ugly).
	</para>
    </section>

</section>