$Revision$
$Date$

# Reference

## Core Options

Core options are located in beginning of configuration file and affect behavior of the server.

- `debug` - Set log level, this is number between 0 and 9. Default is 0.

- `fork` - If set to yes, the server will spawn children. If set to no, the main process will be processing all messages. Default is yes.

  Disabling child spawning is useful mainly for debugging. When `fork` 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 ser listens. The easiest way to do so is to set the interface using `listen` option explicitly.

- `log_stderror` - If set to yes, the server will print its debugging information to standard error output. If set to no, `syslog` will be used. Default is no (printing to syslog).

- `listen` - list of all IP addresses or hostnames SER should listen on.

  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: `ser -l foo -l bar -p 5061 -l x -l y` will listen on foo:5060, bar:5061 & x:5061 & y:5061

- `alias` - Add IP addresses or hostnames to list of name aliases. All requests with hostname matching an alias will satisfy the condition "uri==myself".

- `dns` - Uses dns to check if it is necessary to add a "received=" field to a via. Default is no.

- `rev_dns` - Same as dns but use reverse DNS. Default is no.

- `port` - 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.

- `maxbuffer` - 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.

- `children` - 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 ser typically spawns additional processes, such as timer process or FIFO server. If FIFO server is turned on, you can watch running processes using the serctl utility.

- `check_via` - Turn on or off Via host checking when forwarding replies. Default is no.

- `syn_branch` - Shall the server use stateful synonym branches? It is faster but not reboot-safe. Default is yes.

- `memlog` - Debugging level for final memory statistics report. Default is L_DBG -- memory statistics are dumped only if `debug` is set high.

- `sip_warning` - Should replies include extensive warnings? By default yes, it is good for trouble-shooting.

- `fifo` - 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 serweb or serctl can communicate with ser.

- `fifo_mode` - Permissions of the FIFO special file.

- `server_signature` - Should locally-generated messages include server's signature? By default yes, it is good for trouble-shooting.

- `reply_to_via` - 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.

- `user | uid` - uid to be used by the server.

- `group | gid` - gid to be used by the server.

- `mhomed` -- enable calculation of outbound interface; useful on multihomed servers, see .

- `loadmodule` - Specifies a module to be loaded (for example "/usr/lib/ser/modules/tm.so")

- `modparam` - Module parameter configuration. The commands takes three parameters:

  - module - Module in which the parameter resides.

  - parameter - Name of the parameter to be configured.

  - value - New value of the parameter.

## Core Commands

### Route Blocks and Process Control

- `route[number]{...}` - This marks a "route block" in configuration files. route blocks are basic building blocks of ser scripts. Each route block contains a sequence of SER 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 `route(n)`, where n is number of the block. The action `break` exits currently executed route block. It stops script execution for route block number 0 or returns to calling route block otherwise.

  ### route

      route[0] {
              # call routing block number 2
      	route(2);
      }

      route[2] {
          forward("host.foo.bar", 5060);
      }

- `failure_route` 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 `failure_route` block, call the TM action `t_on_failure(route_number)` before calling `t_relay`. When a negative reply comes back, the desired `failure_route` will be entered and processing of the original request may continue.

  The set of actions applicable from within `failure_route` blocks is limited. Permitted actions are URI-manipulation actions, logging and sending stateful replies using `t_reply`.

  ### failure_route

      failure_route[1] {
          # for some reason, the original forwarding attempt
          # failed, try at another URI
          append_branch("sip:nonsense@iptel.org");
          # if this new attempt fails too, try another failure_route
          t_on_failure("2");
      	t_relay();
      }

- The action `break` exits currently executed route block. It stops script execution for route block number 0 or returns to calling route block otherwise.

  We recommend to use `break` 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.

  Example: break;

- `route(n)` - call routing block route[n]{...}; when the routing block n finishes processing, control is passed back to current block and processing continues.

- `if (condition) statement` - Conditional statement.

  ### Use of `if`

      if (method=="REGISTER) {
          log("register received\n");
      };

- `if - else` - If-Else Conditional statement.

  ### Use of `if-else`

      if (method=="REGISTER) {
          log("register received\n");
      } else {
          log("non-register received\n");
      };

### Flag Manipulation

- `setflag` - Set flag in the message.

  Example: setflag(1);

- `resetflag` - Reset flag in the message.

  Example: resetflag(1);

- `isflagset` - Test whether a particular flag is set.

  ### isflagset

      if (isflagset(1)) {
          ....
      };

- `setavpflag(avp, flag_id)` - Sets a flag in the AVP(s). The command simply set custom flag of AVP. The flags may be used in script using `isavpflagset` or in a module to perform specific operation on marked AVPs. Flag identifier must be declared via avpflags statement.

  ### setavpflag

      avpflags
      	my_flag,
      	your_flag;
      ....
      setavpflag($avp[1], "my_flag");
      ....
      if (isavpflagset($avp2, "your_flag")) {

      }

- `resetavpflag(avp, flag_id)` - Same as command `setavpflag` - only resetavpflag will be called instead of setavpflag.

- `isavpflagset(avp, flag_id)` - Test if the avp flag is set or not.

### Manipulation of URI and Destination Set

- `rewritehost | sethost | seth` - Rewrite host part of the Request URI.

  Example: sethost("foo.bar.com");

- `rewritehostport | sethostport | sethp` - Rewrite host and port part of the Request URI.

  Example: sethostport("foo.bar.com:5060");

- `rewriteuser | setuser | setu` - Rewrite or set username part of the Request URI.

  Example: setuser("joe");

- `rewriteuserpass | setuserpass | setup` - Rewrite or set username and password part of the Request URI.

  Example: setuserpass("joe:mypass");

- `rewriteport | setport | setp` - Rewrite or set port of the Request URI.

  Example: setport("5060");

- `rewriteuri | seturi` - Rewrite or set the whole Request URI.

  Example: seturi("sip:joe@foo.bar.com:5060");

- `revert_uri` - Revert changes made to the Request URI and use original Request URI.

  Example: revert_uri();

- `prefix` - Add prefix to username in Request URI.

  Example: prefix("123");

- `strip` - Remove first n characters of username in Request URI.

  Example: strip(3);

- `append_branch` - Append a new destination to destination set of the message.

  ### Use of `append_branch`

      # redirect to these two destinations: a@foo.bar and b@foo.bar
      # 1) rewrite the current URI
      rewriteuri("sip:a@foo.bar");
      # 2) append another entry to the destination ser
      append_branch("sip:b@foo.bar");
      # redirect now
      sl_send_reply("300", "redirection");

### Message Forwarding

- `forward(uri, port)` - 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.

  Example: forward("foo.bar.com"); # port defaults to 5060

- `send` - Send the message as is to a third party

  Example: send("foo.bar.com");

### Logging

- `log([level], message)` - Log a message.

  Example: log(1, "This is a message with high log-level set to 1\n");

  Logging is very useful for troubleshooting or attracting administrator's attention to unusual situations. ser reports log messages to syslog facility unless it is configured to print them to `stderr` with the `log_stderr` configuration option. Log messages are only issued if their log level exceeds threshold set with the `debug` configuration option. If log level is omitted, messages are issued at log level 4.

### Miscellaneous

- `len_gt` - If length of the message is greater than value given as parameter, the command will return 1 (indicating true). Otherwise -1 (indicating false) will be returned. It may take 'max_len' as parameter, in which case message size is limited to internal buffer size BUF_SIZE (3040 by default).

  ### Use of `len_gt`

      # deny all requests larger in size than 1 kilobyte
      if (len_gt(1024)) {
          sl_send_reply("513", "Too big");
          break;
      };

## Command Line Parameters

Command-Line parameters may be overridden by configuration file options which take precedence over them.

- -h - Displays a short usage description, including all available options.

- -c - Performs loop checks and computes branches.

- -r - Uses dns to check if it is necessary to add a "received=" field to a via.

- -R - Same as -r but uses reverse dns.

- -v - Turns on via host checking when forwarding replies.

- -d - Turns on debugging, multiple -d increase debugging level.

- -D - Runs ser in the foreground (it doesn't fork into daemon mode).

- -E - Sends all the log messages to stderr.

- -V - Displays the version number.

- -f config-file - Reads the configuration from "config-file" (default ./ser.cfg).

- -l address - Listens on the specified address. Multiple -l mean listening on multiple addresses. The default behavior is to listen on all the ipv4 interfaces.

- -p port - Listens on the specified port (default 5060). It applies to the last address specified with -l and to all the following that do not have a corresponding -p.

- -n processes-no - Specifies the number of children processes forked per interface (default 8).

- -b max_rcv_buf_size - Maximum receive buffer size which will not be exceeded by the auto-probing procedure even if the OS allows.

- -m shared_mem_size - Size of the shared memory which will be allocated (in Megabytes).

- -w working-dir - Specifies the working directory. In the very improbable event that will crash, the core file will be generated here.

- -t chroot-dir - Forces ser to chroot after reading the config file.

- -u uid - Changes the user id under which ser runs.

- -g gid - Changes the group id under which ser runs.

- -P pid-file - Creates a file containing the pid of the main ser process.

- -i fifo-path - Creates a fifo, useful for monitoring ser status.

## Modules

Module description is currently located in READMEs of respective module directories. `README-MODULES` lists all available modules, including their maturity status. In the current ser distribution, there are the following modules:

- acc -- call accounting using syslog facility. RADIUS and mysql support can be compiled in. Depends on tm.

- auth, auth_db, auth_radius -- digest authentication. Depends on sl and mysql.

- domain -- checks URIs whether they belong in a list of served domains or not.

- ENUM -- E.164 phone number resolution using ENUM.

- exec -- execution of shell programs.

- group, group_radius -- checks membership of users in groups

- jabber -- gateway between SIMPLE and Jabber instant messaging. Depends on tm and mysql.

- maxfwd -- checking max-forwards header field.

- msilo

  -- message silo. Store for undelivered instant messages. Depends on tm and mysql.

- mysql -- mysql database back-end.

- nathelper -- facilitates NAT traversal for symmetric SIP phones such as ATA.

- pa -- presence agent

- registrar, usrloc -- User Location database. Works in in-memory mode or with mysql persistence support. Depends on sl, and on mysql if configured for use with mysql.

- rr -- Record Routing (strict and loose)

- sl -- stateless User Agent server.

- sms -- SIMPLE/SMS gateway. Depends on tm. Takes special hardware.

- textops -- textual database back-end.

- tm -- transaction manager (stateful processing).

- uri, uri_radius -- checks digest identity against header URIs or a database list

The most frequently used actions exported by modules are summarized in . For a full explanation of module actions, see documentation in respective module directories in source distribution of ser.

### Frequently Used Module Actions

Command | Modules | Parameters | Comments
--- | --- | --- | ---
append_hf | textops | header field | append a header field to the end of request's header
check_from | uri | none | check if username in from header field matches authentication id
check_to | uri | none | check if username in To header field matched authentication id
exec_dset | exec | command name | execute an external command and replace destination set with its output
exec_msg | exec | command name | execute an external command and pass received SIP request to its input
is_user | uri | user id | returns true if request credentials belong to a user
is_user_in | auth | user, group | check if user is member of a group; user can be gained from request URI ("Request-URI"), To header field ("To"), From header field ("From") or digest credentials ("Credentials")
lookup | usrloc | table name | attempt to translate request URI using user location database; returns false if no contact for user found;
loose_route | rr | none | process loose routes in requests
mf_process_maxfwd_header | maxfwd | default max_forwards value | return true, if request's max_forwards value has not reached zero yet; if none is included in the request, set it to value in parameter
proxy_authorize | auth | realm, subscriber table | returns true if requests contains proper credentials, false otherwise
proxy_challenge | auth | realm, qop | challenge user to submit digest credentials; qop may be turned off for backwards compatibility with elderly implementations
record_route | rr | none | record-route a request
replace | textops | RegExp, Substitute | find the first occurrence of a string matching the regular expression in header or body and replace it with a substitute
replace_all | textops | RegExp, Substitute | find all occurrences of a string matching the regular expression in header or body and replace it with a substitute
save | usrloc | table name | for use in registrar: save content of Contact header fields in user location database and reply with 200
search | textops | regular expression | search for a regular expression match in request header of body
sl_send_reply | sl | status code, reason phrase | reply a request statelessly
t_relay | tm | none | stateful forwarding to locations in current destination set
t_on_failure | tm | failure_route number | set failure_route block which shall be entered if stateful forwarding fails
t_replicate | tm | host, port number | replicate a request to a destination

## FIFO Commands Reference

This section lists currently supported FIFO commands. Some of them are built-in in ser core, whereas others are exported by modules. The most important exporters are now tm and usrloc module. tm FIFO commands allow users to initiate transactions without knowledge of underlying SIP stack. usrloc FIFO commands allow users to access in-memory user-location database. Note that that is the only way how to affect content of the data-base in real-time. Changes to MySql database do not affect in-memory table unless ser is restarted.

### FIFO Commands

Command | Module | Parameters | Comments
--- | --- | --- | ---
ps | core | none | prints running ser processes
which | core | none | prints list of available FIFO commands
arg | core | none | prints list of command-line arguments with which ser was started
pwd | core | none | prints ser's working directory
version | core | none | prints version of ser
uptime | core | none | prints ser's running time
sl_stats | sl | none | prints statistics for sl module
t_stats | tm | none | print statistics for tm module
t_hash | tm | none | print occupation of transaction table (mainly for debugging)

t_uac_dlg

tm

method, request URI, outbound URI (if none, empty line with a single dot), dot-line-terminated header fields, optionally dot-line terminated message body.

initiate a transaction. From and To header fields must be present in header field list, so does Content-Type if body is present. If CSeq, CallId and From-tag are not present, ephemeral values are generated. Content_length is calculated automatically if body present.

ul_stats | usrloc | none | print usrloc statistics
ul_rm | usrloc | table name, user name | remove all user's contacts from user-location database
ul_rm_contact | usrloc | table name, user name, contact | remove a user's contact from user-location database
ul_dump | usrloc | none | print content of in-memory user-location database
ul_flush | usrloc | none | flush content of in-memory user-location cache in persistent database (MySQL)
ul_add | usrloc | table name, user name, contact, expiration, priority (q) | insert a contact address in user-location database
ul_show_contact | usrloc | table, user name | show user's contact addresses in user-location database

## Used Database Tables

ser includes MySQL support to guarantee data persistence across server reboots and storage of users' web environment. The data stored in the database include user profiles, access control lists, user location, etc. Note that users are not supposed to alter the data directly, as it could introduce inconsistency between data on persistence storage and in server's memory. The following list enumerates used tables and explains their purpose.

- subscriber -- table of users. It includes user names and security credentials, as well as additional user information.

- reserved -- reserved user names. serweb does not permit creation of accounts with name on this list.

- phonebook -- user's personal phonebooks. Accessible via serweb.

- pending -- table of unconfirmed subscription requests. Used by serweb.

- missed_calls -- table of missed calls. Can be fed by acc modules if mysql support is turned on. Displayed by serweb.

- location -- user contacts. Typically updated through ser'r registrar functionality.

- grp -- group membership. Used by auth module to determine whether a user belongs to a group.

- event -- allows users to subscribe to additional services. Currently unused.

- aliases -- keeps track of alternative user names.

- active_sessions -- keeps track of currently active web sessions. For use by serweb.

- acc -- keeps track of accounted calls. Can be fed by acc module if mysql support is turned on. Displayed by serweb.

- config -- maintains attribute-value pairs for keeping various information. Currently not used.

- silo -- message store for instant messages which could not have been delivered.

- version -- keeps version number of each table definition.

- domain -- maintains list of served domains.

- server_monitoring-* -- reserved for persistent monitoring of server's operation

- uri -- used to keep lists of URIs "owned" by a user (as identified by digest identity); good for some PSTN interworking scenarios