$Revision$ $Date$

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.

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[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[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. if (method=="REGISTER) { log("register received\n"); }; if - else - If-Else Conditional statement. if (method=="REGISTER) { log("register received\n"); } else { log("non-register received\n"); }; 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. 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. 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. 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. # 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"); 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"); 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. 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). # deny all requests larger in size than 1 kilobyte if (len_gt(1024)) { sl_send_reply("513", "Too big"); break; };

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.

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

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

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