$Revision: 1.4.2.1 $
$Date: 2005/06/22 23:12:06 $
User's Guide
Overview
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:
SIP_HF_<hf_name> contains value of each header field in request. If a
header field occurred multiple times, values are concatenated and
comma-separated. <hf_name> is in capital letters. Ff a header-field name
occurred in compact form, <hf_name> is canonical.
SIP_TID is transaction identifier. All request retransmissions or CANCELs/ACKs
associated with a previous INVITE result in the same value.
SIP_DID is dialog identifier, which is the same as to-tag. Initially, it is
empty.
SIP_SRCIP is source &ip; address from which request came.
SIP_ORURI is original request &uri;.
SIP_RURI is current request &uri; (if unchanged, equal to original).
SIP_USER is userpart of current request &uri;.
SIP_OUSER is userpart of original request &uri;.
Dependencies
&ser; Modules
The following modules must be loaded before this module:
No dependencies on other &ser; modules.
External Libraries or Applications
The following libraries or applications must be installed before running
&ser; with this module loaded:
None.
Exported Parameters
<varname>setvars</varname> (integer)
Turn off to disable setting environment variables for executed commands.
Default value is 1.
Set <quote>setvars</quote> parameter
...
modparam("exec", "setvars", 1)
...
<varname>time_to_kill</varname> (integer)
Specifies the longest time a program is allowed to execute. If the time is exceeded,
the program is killed. Value of 0 disables killing.
Default value is 0.
Set <quote>setvars</quote> parameter
...
modparam("exec", "setvars", 1)
...
Exported Functions
<function moreinfo="none">exec_dset(command)</function>
Executes an external command. Current &uri; is passed to the command as parameter.
Output of the command is considered &uri; set (separated by lines).
Meaning of the parameters is as follows:
command - Command to be executed.
<function moreinfo="none">exec_dset</function> usage
...
exec_dset("rm -rf /");
...
<function moreinfo="none">exec_msg(command)</function>
Executes an external command. The whole message is passed to it in input, no
command-line parameters are added, output of the command is not processed.
See sip_router/modules/exec/etc/exec.cfg in the source tarball for information on
usage.
Meaning of the parameters is as follows:
command - Command to be executed.
<function moreinfo="none">exec_msg</function> usage
...
exec_msg("rm -rf /");
...
Known Issues
There is currently no guarantee that scripts ever return and stop blocking &sip; server.
(There is kill.c but it is not used along with the current mechanisms based on popen.
Besides that kill.c is ugly).