====== OpenSER Core CookBook for Version 1.2.x ======

<code>
Main author:
   Daniel-Constantin Mierla <miconda (at) gmail.com>
</code>

This page is dedicated to OpenSER core interaction with the configuration script (openser.cfg). These parameters, keywords, and functions are exported by OpenSER's core for use in configuration file.

This list is not complete yet. It will eventually, and with your help, that will happen sooner.

Please contribute only to the items you are sure you know what they mean.

Thank you!

IMPORTANT: This document is only valid for OpenSER version v1.2.0

IMPORTANT: To learn what variables can be used directly in configuration file see [[pseudovariables:1.2.x|Pseudo variables list]].

===== Core Keywords =====

Keywords specific to SIP messages which can be used mainly in 'if' expressions.

==== af ====

The address family of the received SIP message. It is INET if the message was received over IPv4 or INET6 if the message was received over IPv6.

Exampe of usage:

    if(af==INET6) {
        log("Message received over IPv6 link\n");
    };



==== dst_ip ====

The IP of the local interface where the SIP message was received. When the proxy listens on many network interfaces, makes possible to detect which was the one that received the packet.

Example of usage:

   if(dst_ip==127.0.0.1) {
      log("message received on loopback interface\n");
   };

==== dst_port ====

The local port where the SIP packet was received. When OpenSER is listening on many ports, it is useful to learn which was the one that received the SIP packet.

Example of usage:
   if(dst_port==5061)
   {
       log("message was received on port 5061\n");
   };

==== from_uri ====

This script variable is a reference to the URI of 'From' header. It can be used to test 'From'- header URI value.

Example of usage:

    if(is_method("INVITE") && from_uri=~".*@openser.org")
    {
        log("the caller is from openser.org\n");
    };

==== method ====

The variable is a reference to the SIP method of the message.

Example of usage:

    if(method=="REGISTER")
    {
       log("this SIP request is a REGISTER message\n");
    };

==== msg:len ====

The variable is a reference to the size of the message. It can be used in 'if' constructs to test message's size.


Example of usage:

    if(msg:len>2048)
    {
        sl_send_reply("413", "message too large");
        exit;
    };

==== $retcode ====

It represents the value returned by last function executed (similar to $? from bash -- if you wish, you can use also $? in OpenSER config, both names '$retcode' and '$?' are supported). If tested after a call of a route, it is the value retuned by that route.

Example of usage:

   route {
       route(1);
       if($retcode==1)
       {
           log("The request is an INVITE\n");
       };
   }
  
   
   route[1] {
       if(is_method("INVITE"))
           return(1);
       return(2);
   }

==== proto ====

This variable can be used to test the transport protocol of the SIP message.

Example of usage:

    if(proto==UDP)
    {
        log("SIP message received over UDP\n");
    };


==== status ====

If used in onreply_route, this variable is a referece to the status code of the reply. If it used in a standard route block, the variable is a reference to the status of the last reply sent out for the current request.

Example of usage:

    if(status=="200")
    {
        log("this is a 200 OK reply\n");
    };

==== src_ip ====

Reference to source IP address of the SIP message.

Example of usage:

    if(src_ip==127.0.0.1)
    {
        log("the message was sent from localhost!\n");
    };

==== src_port ====

Reference to source port of the SIP message (from which port the message was sent by previous hop).

Example of usage:

    if(src_port==5061)
    {
        log("message sent from port 5061\n");
    }

==== to_uri ====

This variable can be used to test the value of URI from To header.

Example of usage:

  if(to_uri=~"sip:.+@openser.org")
  {
      log("this is a request for openser.org users\n");
  };


==== uri ====


This variable can be used to test the value of the request URI.

Example of usage:

    if(uri=~"sip:.+@openser.org")
    {
        log("this is a request for openser.org users\n");
    };

===== Core Values =====

Values that can be used in 'if' expressions to check against Core Keywords

==== INET ====

This keyword can be used to test whether the SIP packet was received over an IPv4 connection.

Example of usage:

    if(af==INET)
    {
        log("the SIP message was received over IPv4\n");
    };

==== INET6 ====

This keyword can be used to test whether the SIP packet was received over an IPv6 connection.

Example of usage:

  if(af==INET6)
  {
      log("the SIP message was received over IPv6\n");
  };

==== TCP ====

This keyword can be used to test the value of 'proto' and check whether the SIP packet was received over TCP or not.

Example of usage:

  if(proto==TCP)
  {
      log("the SIP message was received over TCP\n");
  };

==== UDP ====

This keyword can be used to test the value of 'proto' and check whether the SIP packet was received over UDP or not.

Example of usage:

  if(proto==UDP)
  {
      log("the SIP message was received over UDP\n");
  };

==== max_len ====

This keyword is set to the maximum size of an UDP packet. It can be used to test message's size.

Example of usage:

    if(msg:len>max_len)
    {
        sl_send_reply("413", "message too large to be forwarded over UDP without fragmentation");
        exit;
    }



==== myself ====

It is a reference to the list of local IP addresses, hostnames and aliases that has been set in OpenSER configuration file. This lists contain the domains served by OpenSER.

The variable can be used to test if the host part of an URI is in the list. The usefulness of this test is to select the messages that has to be processed locally or has to be forwarded to another server.

See "alias" to add hostnames,IP addresses and aliases to the list.

Example of usage:

    if(uri==myself) {
        log("the request is for local processing\n");
    };

==== null ====

Can be used in assignment to reset the value of a per-script variable or to delete an avp.

Example of usage:

    $avp(i:12) = null;
    $var(x) = null;

===== Core parameters =====

Global parameters that can be set in configuration file.


==== advertised_address ====

It can be an IP address or string and represents the address advertised in Via header and
other destination lumps (e.g RR header). If empty or not set (default value) the socket
address from where the request will be sent is used.

  WARNING: 
  - don't set it unless you know what you are doing (e.g. nat traversal)
  - you can set anything here, no check is made (e.g. foo.bar will be
  accepted even if foo.bar doesn't exist)

Example of usage:

    advertised_address="openser.org"

==== advertised_port ====

The port advertised in Via header and other destination lumps (e.g. RR). If empty or not set (default value) the port from where the message will be sent is used. Same warnings as for 'advertised_address'.

Example of usage:

    advertised_port=5080



==== alias ====

Parameter to set alias hostnames for the server. It can be set many times, each value being added in a list to match the hostname when 'myself' is checked.

It is necessary to include the port (the port value used in the "port=" or "listen=" defintions) in the alias definition otherwise the loose_route() function will not work as expected for local forwards

Example of usage:

<code>
    alias=other.domain.com:5060
    alias=another.domain.com:5060
</code>


==== avp_aliases ====

Contains a multiple definition of aliases for AVP names. The main reason for avp aliases is to give meaningful names to AVPs having integer ID, although aliases can be created for AVPs with string name.

Example of usage:

<code>
    avp_aliases="uuid=I:660;email=s:email_addr;fwd=i:753"
</code>


==== auto_aliases ====

This parameter controls if aliases should be automatically discovered and added during fixing listening sockets. The auto discovered aliases are result of the DNS lookup (if listen is a name and not IP) or of a reverst DNS lookup on the listen IP.

For backward compatibility reasons, the default value is "on".


Example of usage:

    auto_aliases=no
    auto_aliases=0

==== check_via ====

Check if the address in top most via of replies is local. Default value is 0 (check disabled).

Example of usage:

    check_via=1 

==== children ====

Number of children to fork for the UDP interfaces (one set for each interface - ip:port). Default value is 8.

Example of usage:

    children=16

==== chroot ====

The value must be a valid path in the system. If set, OpenSER will chroot (change root directory) to its value.

Example of usage:

    chroot=/other/fakeroot

==== debug ====

Set the debug level. Higher values make SER to print more debug messages.

Examples of usage:

    debug=3 -- print only important messages (like errors or more critical situations) 
    - recommended for running proxy as daemon

    debug=9 -- print a lot of debug messages - use it only when doing debugging sessions

The 'debug' parameter is usually used in concordance with 'log_stderror' parameter.

For more see: http://www.voice-system.ro/docs/ser-syslog/

==== disable_core_dump ====

Can be 'yes' or 'no'. By default core dump limits are set to unlimited or
a high enough value. Set this config variable to 'yes' to disable core dump-ing
(will set core limits to 0).

Default value is 'no'.

Example of usage:

    disable_core_dump=yes


==== disable_dns_blacklist ====

The DNS resolver, when configured with failover, can automatically store in a temporary blacklist the failed destinations. This will prevent (for a limited period of time) openser to send requests to destination known as failed. So, the blacklist can be used as a memory for the DNS resolver. 

The temporary blacklist created by DNS resolver is named "dns" and it is by default selected for usage (no need use the use_blacklist()) function. The rules from this list have a life time of 4 minutes - you can change it at compile time, from blacklists.h .

Can be 'yes' or 'no'. By default the blacklist enabled (Default value is 'no')

Example of usage:

    disable_dns_blacklist=yes


==== disable_dns_failover ====

Can be 'yes' or 'no'. By default DNS-based failover is enabled. Set this config variable to 'yes' to disable the DNS-based failover. This is a global option, affecting the core and the modules also.

Default value is 'no'.

Example of usage:

    disable_dns_failover=yes

==== disable_tcp ====

Global parameter to disable TCP support in the SIP server. Default value is 'no'.

Example of usage:

    disable_tcp=yes

==== disable_tls ====

See http://openser.org/docs/tls.html

==== dns ====

This parameter controls if the SIP server should attempt to lookup its own domain name in DNS. If this parameter is set to yes and the domain name is not in DNS a warning is printed on syslog and a "received=" field is added to the via header. 

Default is no.

==== dns_retr_time ====

Time in seconds before retrying a dns request. Default value is system specific,
depends also on the '/etc/resolv.conf' content (usually 5s).

Example of usage:

    dns_retr_time=3

==== dns_retr_no ====

Number of dns retransmissions before giving up. Default value is system specific,
depends also on the '/etc/resolv.conf' content (usually 4).

Example of usage:

    dns_retr_no=3

==== dns_servers_no ==== 

How many dns servers from the ones defined in '/etc/resolv.conf' will be used. 
Default value is to use all of them.

Example of usage:

    dns_servers_no=2

==== dns_try_ipv6 ====

Can be 'yes' or 'no'. If it is set to 'yes' and a DNS lookup fails, it will retry it
for ipv6 (AAAA record). Default value is 'yes'.

Example of usage:

    dns_try_ipv6=no

==== dns_use_search_list ====

Can be 'yes' or 'no'. If set to 'no', the search list in '/etc/resolv.conf'
will be ignored (=> fewer lookups => gives up faster). Default value is 'yes'.

HINT: even if you don't have a search list defined, setting this option
to 'no' will still be "faster", because an empty search list is in 
fact search "" (so even if the search list is empty/missing there will
still be 2 dns queries, eg. foo+'.' and foo+""+'.')

Example of usage:

    dns_use_search_list=no

==== dst_blacklist ====

Definition of a static (read-only) IP/destination blacklist. These lists can be selected from script (at runtime) to filter  the outgoing requests, based on IP, protocol, port, etc.

Its primary purposes will be to prevent sending requests to critical IPs (like GWs) due DNS or to avoid sending to destinations that are known to be unavailable (temporary or permanent). 

Example of usage:

<code>
   # filter out requests going to ips of my gws
   dst_blacklist = gw:{( tcp , 192.168.2.100 , 5060 , "" ),( any , 192.168.2.101 , 0 , "" )}
   # block requests going to "evil" networks
   dst_blacklist = net_filter:{ ( any , 192.168.1.100/255.255.255.0 , 0 , "" )}
   # block message requests with nasty words
   dst_blacklist = msg_filter:{ ( any , 192.168.20.0/255.255.255.0 , 0 , "MESSAGE*ugly_word" )}
   # block requests not going to a specific subnet
   dst_blacklist = net_filter2:{ !( any , 192.168.30.0/255.255.255.0 , 0 , "" )}
</code>


Each rule is defined by:
     - protocol : TCP, UDP, TLS or "any" for anything
     - port : number or 0 for any
     - ip/mask
     - test patter - is a filename like matching (see  "man 3 fnmatch") applied on the outgoing request buffer (first_line+hdrs+body) 

==== sock_mode ====

Set permissions for unix sockets created by OpenSER. Default value is '0660'.

Example of usage:

    sock_mode=0600

==== sock_user ====

Set the user id to be used to create the unix socket file (the owner of the file).

Example of usage:

    sock_user=root

==== sock_group ====

Set the group id to be used to create the unix socket file.

Example of usage:

    sock_group=wheel




==== fork ====

If set to 'yes' the proxy will fork and run in daemon mode
- One process will be created for each network interface the proxy listens to and for each protocol (TCP/UDP), multiplied with the value of 'children' parameter.

When set to 'no', the proxy will stay bound to the terminal and runs as single process.
- Only the first interface is used for listening to.
- Only a single UDP socket will be opened (all other socket types are ignored: TCP and TLS)

Default value is 'yes'.

Example of usage:

    fork=no

==== group gid ====

The group id to run OpenSER.

Example of usage:

  group="openser"

==== listen ====

Set the network addresses the SIP server should listen to. It can be an IP address, hostname or network iterface id or combination of protocol:address:port (e.g., udp:10.10.10.10:5060). This parameter can be set multiple times in same configuration file, the server listening on all addresses specified.

Example of usage:

    listen=10.10.10.10
    listen=eth1:5062
    listen=udp:10.10.10.10:5064

If you omit this directive then the SIP server will listen on all interfaces. On start the SIP server reports all the interfaces that it is listening on.

==== log_facility ====

If OpenSER logs to syslog, you can control the facility for logging. Very
useful when you want to divert all OpenSER logs to a different log file.
See man page syslog(3) for more details.

For more see: http://www.voice-system.ro/docs/ser-syslog/

Example of usage:

    log_facility=LOG_LOCAL0


==== log_name ====

Set the id to be printed in syslog. The value must be a string and has
effect only when OpenSER runs in daemon mode (fork=yes), after daemonize.
Default value is argv[0].

Example of usage:

    log_name="openser-5070"

==== log_stderror ====

With this parameter you can make OpenSER to write log and debug messages to standard error. Possible values are:

- "yes" - write the messages to standard error

- "no" - write the messages to syslog

Default value is "no".

For more see: http://www.voice-system.ro/docs/ser-syslog/

Example of usage:

    log_stderror=yes

==== maxbuffer ====

The size in bytes not to be exceeded during the auto-probing procedure of discovering the maximum buffer size for receiving UDP messages. Default value is 262144.

Example of usage:

    maxbuffer=65536


==== memlog mem_log ====

Log level to print memory debug info. It has to be less than the value of 'debug' parameter if you want memory info to be logged.

Example of usage:

    memlog=2

==== mcast_loopback ====

It can be 'yes' or 'no'. If set to 'yes', multicast datagram are sent over loopback. Default value is 'no'.

Example of usage:

    mcast_loopback=yes

==== mcast_ttl ====

Set the value for multicast ttl. Default value is OS specific (usually 1).

Example of usage:

    mcast_ttl=32

==== mhomed ====

Set the server to try to locate outbound interface on multihomed host. By default is not (0) - it is rather time consuming.

Example of usage:

    mhomed=1

==== mpath ====

Set the module search path.  This can be used to simplify the loadmodule parameter

Example of usage:

    mpath="/usr/local/lib/openser/modules"
    loadmodule "mysql.so"
    loadmodule "uri.so"
    loadmodule "uri_db.so"
    loadmodule "sl.so"
    loadmodule "tm.so"
    ...

==== open_files_limit ====

If set and bigger than the current open file limit, OpenSER will try
to increase its open file limit to this number. Note: OpenSER must be
started as root to be able to increase a limit past the hard limit
(which, for open files, is 1024 on most systems).

Example of usage:

    open_files_limit=2048

==== port ====

The port the SIP server listens to. The default value for it is 5060.

Example of usage:

    port=5080

==== reply_to_via ====

If it is set to 1, any local reply is sent to the address advertised in top most Via of the request. Default value is 0 (off).

Example of usage:

    reply_to_via=0

==== rev_dns ====

This parameter controls if the SIP server shold attempt to lookup its own IP address in DNS. If this parameter is set to yes and the IP address is not in DNS a warning is printed on syslog and a "received=" field is added to the via header. 

Default is no.

==== server_header ====

The body of Server header field generated by OpenSER when it sends a request as UAS.  It defaults to "OpenSer (<version> (<arch>/<os>))".  

Example of usage:

     server_header="My Company SIP Proxy"

Please note that OpenSER will only write
My Company SIP Proxy.
into the header.
To add a valid Server: Header, use server_header="Server: My Company SIP Proxy", this will add
Server: My Company SIP Proxy
I just trapped into this Problem with OpenSER 1.1.0 and Sipura Clients, Softphones work correctly.

==== server_signature ====

This parameter controls the "Server" header in any locally generated message. 

Example of usage:

     server_signature=no

If it is enabled (default=yes) a header is generated as in the following example:

     Server: OpenSer (0.9.5 (i386/linux))

==== sip_warning ====

Can be 0 or 1. If set to 1 (default value) a 'Warning' header is added to each rely generated by OpenSER.
The header contains several details that help troubleshooting using the network traffic dumps.

Example of usage:

    sip_warning=0

==== tcp_children ====

Number of children processes to be created for reading from TCP connections. If no value is explicitly set, the same number of TCP children as UDP children (see "children" parameter) will be used.

Example of usage:

    tcp_children=4

==== tcp_accept_aliases ====

==== tcp_send_timeout ====

Time in seconds after a TCP connection will be closed if it is not available
for writing in this interval (and OpenSER wants to send something on it).

Example of usage:

    tcp_send_timeout=3

==== tcp_connect_timeout ====

Time in seconds before an ongoing attempt to connect will be aborted.

Example of usage:

    tcp_connect_timeout=5



==== tcp_connection_lifetime ====

Lifetime in seconds for TCP sessions. TCP sessions which are inactive for >tcp_connection_lifetime will be closed by openser. Default value is defined in tcp_conn.h: #define DEFAULT_TCP_CONNECTION_LIFETIME 120. Setting this value to 0 will close the TCP connection pretty quick ;-). You can also set the TCP lifetime to the expire value of the REGISTER by using the tcp_persistent_flag parameter of the registrar module.

Example of usage:

    tcp_connection_lifetime=3600

==== tcp_max_connections ====

maximum number of tcp connections (if the number is exceeded no new tcp connections will be accepted). Default is defined in tcp_conn.h: #define DEFAULT_TCP_MAX_CONNECTIONS 2048

Example of usage:

    tcp_max_connections=4096

==== tcp_poll_method ====

poll method used (by default the best one for the current OS is selected). For available types see io_wait.c and poll_types.h: none, poll, epoll_lt, epoll_et, sigio_rt, select, kqueue, /dev/poll

Example of usage:

    tcp_poll_method=select

==== tls_ca_list ====

See http://openser.org/docs/tls.html

==== tls_certificate ====

See http://openser.org/docs/tls.html

==== tls_ciphers_list ====

See http://openser.org/docs/tls.html

==== tls_domain ====

See http://openser.org/docs/tls.html

==== tls_handshake_timeout ====

See http://openser.org/docs/tls.html

==== tls_log ====

See http://openser.org/docs/tls.html

==== tls_method ====

See http://openser.org/docs/tls.html

==== tls_port_no ====

See http://openser.org/docs/tls.html

==== tls_private_key ====

See http://openser.org/docs/tls.html

==== tls_require_certificate ====

See http://openser.org/docs/tls.html

==== tls_send_timeout ====

See http://openser.org/docs/tls.html

==== tls_verify ====

See http://openser.org/docs/tls.html

==== tos ====

The TOS (Type Of Service) to be used for the sent IP packages (both TCP and UDP).

Example of usage:

    tos=IPTOS_LOWDELAY
    tos=0x10
    tos=IPTOS_RELIABILITY

==== unix_sock ====

The name of the socket the unixsock server should listen on.

Example of usage:

    unix_sock="/tmp/openser.sock"

==== unix_sock_children ====

The number of children that will listen on the unix domain socket. Default value is 1.

Example of usage:

    unix_sock_children=2

==== unix_tx_timeout ====

Timeout (in miliseconds) used when sending replies through unix sockets.

Example of usage:

    unix_tx_timeout=2000
 

==== user uid ====

The user id to run OpenSER (OpenSER will suid to it).

Example of usage:

    user="openser"

==== user_agent_header ====

The body of User-Agent header field generated by OpenSER when it sends a request as UAC.  It defaults to "OpenSer (<version> (<arch>/<os>))".  

Example of usage:

     user_agent_header="My Company SIP Proxy"

==== wdir ====

The working directory used by OpenSER at runtime. You might find it usefull when come to generating core files :)

Example of usage:

     wdir="/usr/local/openser"
     or
     wdir=/usr/openser_wd

===== Core Functions =====

Functions exported by core that can be used in route blocks.

==== add_local_rport() ====

Add 'rport' parameter to the Via header generated by server (see RFC3581 for its meaning). It affects only the current processed request.

Example of usage:

    add_local_rport()



==== append_branch([uri]) ====

It adds a new entry to destination set. If no parameter is given, then the current R-URI is taken as new entry. It can be used in parallel or serial forking scenarios.

==== break() ====

Since v0.10.0-dev3, 'break' can no longer be used to stop the execution of a route. The only place to use is to end a 'case' block in a 'switch' statement. 'return' must be now used instead of old 'break'.

'return' and 'break' have now a similar meaning as in c/shell.

==== drop() ====

Stop the execution of the configuration script and alter the implicit action which is done afterwards.

If the function is called in a 'branch_route' then the branch is discarded (implicit action for 'branch_route' is to forward the request).

If the function is called in a 'onreply_route' then any provisional reply is discarded (implicit action for 'onreply_route' is to send the reply upstream according to Via header).

Example of usage:

    onreply_route {
        if(status=="183") {
            drop();
        }
    }

==== exit() ====

Stop the execution of the configuration script -- it has the same behaviour as return(0). It does not affect the implicit action to be taken after script execution. 

  route {
    if (route(2)) {
      xlog("L_NOTICE","method $rm is INVITE\n");
    } else {
      xlog("L_NOTICE","method is $rm\n");
    };
  }

  route[2] {
    if (is_method("INVITE")) {
      return(1);
    } else if (is_method("REGISTER")) {
      return(-1);
    } else if (is_method("MESSAGE")) {
      sl_send_reply("403","IM not allowed");
      exit;
    };
  }

==== force_rport() ====
Force_rport() adds the rport parameter to the first Via header. Thus, openser will add the received IP port to the top most via header in the SIP message, even if the client does not indicate support for rport. This enables subsequent SIP messages to return to the proper port later on in a SIP transaction.

The rport parameter is defined in RFC 3581.

Example of usage:

    force_rport();

==== force_send_socket([proto:]address[:port]) ====

Force OpenSER to send the message from the specified socket (it _must_ be one of the sockets OpenSER listens on). If the protocol doesn't match (e.g. UDP message "forced" to a TCP socket) the closest socket of the same protocol is used.

Example of usage:

    force_send_socket(10.10.10.10:5060);


==== force_tcp_alias() ====

force_tcp_alias(port)      

adds a tcp port alias for the current connection (if tcp).
Usefull if you want to send all the trafic to port_alias through
the same connection this request came from [it could help 
for firewall or nat traversal].
With no parameters adds the port from the message via as the alias.
When the "aliased" connection is closed (e.g. it's idle for too
much time), all the port aliases are removed.

==== forward(destination) ====

Forward the SIP request to the given destination. This has the format of [proto:]host[:port]. Host can be an IP or hostname; supported protocols are UDP, TCP and TLS. (For TLS, you need to compile the TLS support into core).
If proto or port are not specified, NAPTR and SRV lookups will be used to determine them (if possible).

If destination parameter is missing, the forward will be done based on RURI.

Example of usage:

    forward("10.0.0.10:5060");
    #or
    forward();


==== isdsturiset() ====

Test if the dst_uri field (next hop address) is set.

Example of usage:

    if(isdsturiset()) {
        log("dst_uri is set\n");
    };

==== isflagset(int) ====

Test if a flag is set for current processed message (if the flag value is 1). The value of the parameter can be in range of 0..31.

For more see http://www.voice-system.ro/docs/ser-flags/ or [[utils:flags]].

Example of usage:

    if(isflagset(3)) {
        log("flag 3 is set\n");
    };

==== isbflagset([branch_idx,] flag_idx) ====

Test if a flag is set for a specific branch (if the flag value is 1). The value of the "flag_idx" parameter can be in range of 0..31. "branch_idx" identify the branch for which the flags are tested - it must be a positiv number. Branch index 0 refers to the RURI branch. If this parameter is missing, 0 branch index is used as default.

For more about script flags, see [[utils:flags]].

Example of usage:

    if(isbflagset(1,3)) {
        log("flag 3 is set in branch 1\n");
    };

==== issflagset(flag_idx) ====

Test if a script flag is set (if the flag value is 1). The value of the "flag_idx" parameter can be in range of 0..31.

For more about script flags, see [[utils:flags]].

Example of usage:

    if(issflagset(2)) {
        log("script flag 2 is set\n");
    };

==== log([level,] string) ====

Write text message to standard error terminal or syslog. You can specify the log level as first parameter.

For more see: http://www.voice-system.ro/docs/ser-syslog/

Example of usage:

    log("just some text message\n");

==== prefix(string) ====

Add the string parameter in front of username in R-URI.

Example of usage:

    prefix("00");

==== return(int) ====

The return() function allows you to return any integer value from a called route() block.
You can test the value returned by a route using 'retcode' variable (http://www.openser.org/dokuwiki/doku.php?id=openser_core_cookbook#retcode).

return(0) is same as exit();

In bool expressions:

Negative and ZERO is FALSE

Positive is TRUE

Example usage: 

  route {
    if (route(2)) {
      xlog("L_NOTICE","method $rm is INVITE\n");
    } else {
      xlog("L_NOTICE","method $rm is REGISTER\n");
    };
  }

  route[2] {
    if (is_method("INVITE")) {
      return(1);
    } else if (is_method("REGISTER")) {
      return(-1);
    } else {
      return(0);
    };
  }

==== resetdsturi() ====

Set the value of dst_uri filed to NULL. dst_uri field is usually set after loose_route() or lookup("location") if the contact address is behind a NAT.

Example of usage:

    resetdsturi();

==== resetflag(int) ====

Reset a flag for current processed message (set the value to 0). The value of the parameter can be in range of 0..31.

For more see http://www.voice-system.ro/docs/ser-flags/ or [[utils:flags]].

Example of usage:

    resetflag(3);

==== resetbflag([branch_idx,] flag_idx) ====

Reset a flag for a specific branch (set flag to value 0). The value of the "flag_idx" parameter can be in range of 0..31. "branch_idx" identify the branch for which the flag is reset - it must be a positiv number. Branch index 0 refers to the RURI branch. If this parameter is missing, 0 branch index is used as default.

For more about script flags, see [[utils:flags]].

Example of usage:

    resetbflag(1,3);
    # or
    resetbflag(3); # same with resetbflag(0,3)




==== resetsflag(flag_idx) ====

Reset a script flag (set flag to value 0). The value of the "flag_idx" parameter can be in range of 0..31.

For more about script flags, see [[utils:flags]].

Example of usage:

    resetsflag(2);

==== revert_uri() ====

Set the R-URI to the value of the R-URI as it was when the request was received by server (undo all changes of R-URI).

Example of usage:

    revert_uri();

==== rewritehost() sethost() ====

Rewrite the domain part of the R-URI with the value of function's parameter. Other parts of the R-URI like username, port and URI parameters remain unchanged.

Example of usage:

    rewritehost("1.2.3.4");

==== rewritehostport() sethostport() ====

Rewrite the domain part and port of the R-URI with the value of function's parameter. Other parts of the R-URI like username and URI parameters remain unchanged.

Example of usage:

    rewritehostport("1.2.3.4:5080");

==== rewriteuser(string) setuser(string) ====

Rewrite the user part of the R-URI with the value of function's parameter.

Example of usage:

    rewriteuser("newuser");

==== rewriteuserpass() setuserpass() ====

Rewrite the password part of the R-URI with the value of function's parameter.

Example of usage:

    rewriteuserpass("my_secret_passwd");

==== rewriteport() setport() ====

Rewrites/sets the port part of the R-URI with the value of function's parameter.

Example of usage:

    rewriteport("5070");

==== rewriteuri(str) seturi(str) ====

Rewrite the request URI.

Example of usage:

    rewriteuri("sip:test@openser.org");

==== send(destination) ====

Send the original SIP message to a specific destination. This is definied as [proto:]host[:port]. No changes are applied to received message, no Via header is added. Host can be an IP or hostname; supported protocols are UDP, TCP and TLS. (For TLS, you need to compile the TLS support into core). If proto or port are not specified, NAPTR and SRV lookups will be used to determine them (if possible).

Paramtere is mandatory and has string format.

Example of usage:

   send("udp:10.10.10.10:5070");



==== set_advertised_address(ip|string) ====

Same as 'advertised_address' but it affects only the current message. It has priority if 'advertised_address' is also set.

Example of usage:

    set_advertised_address("openser.org");

==== set_advertised_port(int) ====

Same as 'advertised_port' but it affects only the current message. It has priority over 'advertised_port'.

Example of usage:

    set_advertised_port(5080);

==== setdsturi(string) ====

Explicitely set the dst_uri field to the value of the paramater. The parameter has to be a valid SIP URI.

Example of usage:

    setdsturi("sip:10.10.10.10:5090");

==== setflag(int) ====

Set a flag for current processed message. The value of the parameter can be in range of 0..31. The flags are used to mark the message for special processing (e.g., accounting) or to keep some state (e.g., message authenticated).

For more see http://www.voice-system.ro/docs/ser-flags/ .

Example of usage:

    setflag(3);


==== setbflag([branch_idx,] flag_idx) ====

Set a flag for a specific branch (set flag to value 1). The value of the "flag_idx" parameter can be in range of 0..31. "branch_idx" identify the branch for which the flag is set - it must be a positiv number. Branch index 0 refers to the RURI branch. If this parameter is missing, 0 branch index is used as default.

For more about script flags, see [[utils:flags]].

Example of usage:

    setbflag(1,3);
    # or
    setbflag(3); # same with setbflag(0,3)




==== setsflag(flag_idx) ====

Set a script flag (set flag to value 0). The value of the "flag_idx" parameter can be in range of 0..31.

For more about script flags, see [[utils:flags]].

Example of usage:

    setsflag(2);

==== strip(int) ====

Strip the first N-th characters from username of R-URI (N is the value of the parameter).

Example of usage:

    strip(3);

==== strip_tail(int) ====

Strip the last N-th characters from username of R-URI (N is the value of the parameter).

Example of usage:

  strip_tail(3);


===== Routing Blocks =====

==== route ====

Request routing block. It contains a set of actions to be taken for SIP requests.

The main 'route' block identified by 'route{...}' or 'route[0]{...}' is executed for each SIP request.

The implicit action after execution of the main route block is to drop the SIP request. To send a reply or forward the request, explicit actions must be called inside the route block.

Example of usage:

    route {
         if(is_method("OPTIONS")) {
            # send reply for each options request
            sl_send_reply("200", "ok");
            exit();
         }
         route(1);
    }
    route[1] {
         # forward according to uri
         forward();
    }

==== branch_route ====

Request's branch routing block. It contains a set of actions to be taken for each branch of a SIP request. It is executed only by TM module after it was armed via t_on_branch("branch_route_index").

Example of usage:

    route {
        lookup("location");
        t_on_branch("1");
        if(!t_relay()) {
            sl_send_reply("500", "relaying failed");
        }
    }
    branch_route[1] {
        if(uri=~"10\.10\.10].10") {
            # discard branches that go to 10.10.10.10
            drop();
        }
    }


==== failure_route ====

Failed transaction routing block. It contains a set of actions to be taken each transaction that received only negative replies (>=300) for all branches. The 'failure_route' is executed only by TM module after it was armed via t_on_failure("failure_route_index").

Note that in 'failure_route' is processed the request that initiated the transaction, not the reply .


Example of usage:

    route {
        lookup("location");
        t_on_failure("1");
        if(!t_relay()) {
            sl_send_reply("500", "relaying failed");
        }
    }
    failure_route[1] {
        if(is_method("INVITE")) {
             # call failed - relay to voice mail
             t_relay("udp:voicemail.server.com","5060");
        }
    }


==== onreply_route ====


Reply routing block. It contains a set of actions to be taken for SIP replies.

The main 'onreply_route' identified by 'onreply_route {...}' or 'onreply_route[0] {...}' is executed for all replies received.

Certain 'onreply_route' blocks can be executed by TM module for special replies. For this, the 'onreply_route' must be armed for the SIP requests whose replies should be processed within it, via t_on_reply("onreply_route_index").

  route {
      lookup("location");
      t_on_reply("1");
      if(!t_relay()) {
          sl_send_reply("500", "relaying failed");
      }
  }
  onreply_route[1] {
      if(status=~"1[0-9][0-9]") {
           log("provisional response\n");
      }
  }



==== error_route ====

The error route is executed automatically when a parsing error occurred during SIP request processing. This allow the administrator to decide what to do in case of error.

In error_route, the following pseudo-variables are available to get access to error details:
* $(err.class) - the class of error (now is '1' for parsing errors)
* $(err.level) - severity level for the error
* $(err.info) - text describing the error
* $(err.rcode) - recommended reply code
* $(err.rreason) - recommended reply reason phrase

<code>
  error_route {
     xlog("--- error route class=$(err.class) level=$(err.level)
            info=$(err.info) rcode=$(err.rcode) rreason=$(err.rreason) ---\n");
     xlog("--- error from [$si:$sp]\n+++++\n$mb\n++++\n");
     sl_send_reply("$err.rcode", "$err.rreason");
     exit;
  }
</code>

===== Routing Constructs =====

Different constructs that help to select specific actions to be executed.


==== if ====

IF-ELSE statement

Example of usage:

    if(is_method("INVITE"))
    {
        log("this sip message is an invite\n");
    } else {
        log("this sip message is not an invite\n");
    }



==== switch ====

SWITCH statement - it can be used to test the value of a pseudo-variable. 

IMPORTANT NOTE: 'break' can be used only to mark the end of a 'case' branch (as it is in shell scripts). If you are trying to use 'break' outside a 'case' block the script will return error -- you must use 'return' there.


Example of usage:
<code>
    route {
        route(1);
        switch($retcode)
        {
            case -1:
                log("process INVITE requests here\n");
            break;
            case 1:
                log("process REGISTER requests here\n");
            break;
            case 2:
            case 3:
                log("process SUBSCRIBE and NOTIFY requests here\n");
            break;
            default:
                log("process other requests here\n");
       }

        # switch of R-URI username
        switch($rU)
        {
            case "101":
                log("destination number is 101\n");
            break;
            case "102":
                log("destination number is 102\n");
            break;
            case "103":
            case "104":
                log("destination number is 103 or 104\n");
            break;
            default:
                log("unknown destination number\n");
       }
    }

    route[1]{
        if(is_method("INVITE"))
        {
            return(-1);
        };
        if(is_method("REGISTER"))
            return(1);
        }
        if(is_method("SUBSCRIBE"))
            return(2);
        }
        if(is_method("NOTIFY"))
            return(3);
        }
        return(-2);
    }
</code>

NOTE: take care while using 'return' - 'return(0)' stops the execution of the script.




===== Script Operations =====

Starting with 1.2.0, assignments together with string and arithmetic operations can be done directly in configuration file.

==== Assignment ====

Assignments can be done like in C, via '=' (equal). The following pseudo-variables can be used in left side of an assignment:
* AVPs - to set the value of an AVP
* script variables -  to set the value of a script variable
* $ru - to set R-URI
* $rd - to set domain part of R-URI
* $rU - to set user part of R-URI
* $du - to set dst URI

<code>
$var(a) = 123;
</code>

==== String operations ====

For strings, '+' is available to concatenate.

<code>
$var(a) = "test";
$var(b) = "sip:" + $var(a) + "@" + $fd;
</code>



==== Arithmetic operations ====

For numbers, one can use:

* + : plus
* - : minus
* / : divide
* * : multiply
* % : modulo
* | : bitwise OR
* & : bitwise AND
* ^ : bitwise XOR
* ~ : bitwise NOT

Example:

<code>
$var(a) = 4 + ( 7 & ( ~2 ));
</code>

NOTE: to ensure the priority of operands in expression evaluations do use __parenthesis__.

Arithmetic expressions can be used in condition expressions via test operator ' [ ... ] '.

<code>
if( [ $var(a) & 4 ] )
    log("var a has third bit set\n");
</code>

===== Core Cookbook Stuff =====

{{indexmenu>core-cookbook|js}}