Resources.DocsCoreFcn History

Hide minor edits - Show changes to markup

April 24, 2013, at 06:27 PM by 109.99.235.212 -
Changed lines 1-1844 from:

Resources -> Documentation -> CookBooks -> Core functions and parameters - devel


(:toc-float Table of Content:) This section lists the all the parameters and functions exported by OpenSIPS core for script usage (to be used in opensips.cfg)

This document is for OpenSIPS 1.10.x / devel

  1. Core keywords
  2. Core values
  3. Core parameters
  4. Core functions

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 OpenSIPS 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=~".*@opensips.org")
    {
        log("the caller is from opensips.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 OpenSIPS 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 reference 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:.+@opensips.org")
  {
      log("this is a request for opensips.org users\n");
  };

uri

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

Example of usage:

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

(:toc-back:)


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 OpenSIPS configuration file. This lists contain the domains served by OpenSIPS.

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;

(:toc-back:)


Core parameters

Global parameters that can be set in configuration file. Accepted values are, depending on the actual parameters strings, numbers and yes/ no. If you need to specify either "yes" or "no" as part of a string, wrap this in double quotes.

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="opensips.org"

NOTE: Aside this global approach, you can also define an advertise IP and port in a per-interface manner (see the "listen" parameter). When advertise values are defined per interface, they will be used only for traffic leaving that interface only.

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

NOTE: Aside this global approach, you can also define an advertise IP and port in a per-interface manner (see the "listen" parameter). When advertise values are defined per interface, they will be used only for traffic leaving that interface only.

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=" definitions) in the alias definition otherwise the loose_route() function will not work as expected for local forwards

Example of usage:

    alias=other.domain.com:5060
    alias=another.domain.com:5060

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 reverse DNS lookup on the listen IP.

Far 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 each UDP or SCTP interface you have defined. Default value is 8.

Example of usage:

    children=16

NOTE: this global value (applicable for all UDP/SCTP interfaces) can be override if you set a different number of children in the definition of a specific interface - so actually you can define a different number of children for each interface (see the "listen" parameter for syntax).

chroot

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

Example of usage:

    chroot=/other/fakeroot

db_version_table

The name of the table version to be used by the DB API to check the version of the used tables.
Default value is "version"

Example of usage:

    db_version_table="version_1_8"

db_default_url

The default DB URL to be used by modules if no per-module URL is given. Default is NULL (not defined)

Example of usage:

    db_default_url="mysql://opensips:opensipsrw@localhost/opensips"

debug

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

Examples of usage:

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

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

Actual values are:

  • -3 - Alert level
  • -2 - Critical level
  • -1 - Error level
  • 1 - Warning level
  • 2 - Notice level
  • 3 - Info level
  • 4 - Debug level

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

Value of 'debug' parameter can also be get and set dynamically using 'debug' Core MI function.

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

disable_503_translation

If 'yes', OpenSIPS will not translate the received 503 replies into 500 replies (RFC 3261 clearly states that a proxy should never relay a 503 response, but instead it must transform it into a 500).

Default value is 'no' (do translation).

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) OpenSIPS 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 is disabled (Default value is 'yes').

Example of usage:

    disable_dns_blacklist=no

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_stateless_fwd

Can be 'yes' or 'no'. This parameter controls the handling of stateless replies:

    yes - drop stateless replies if stateless fwd functions (like forward) are not used in script
    no - forward stateless replies

Default value is '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

Global parameter to disable TLS support in the SIP server. Default value is 'yes'.

Example of usage:

    disable_tcp=no

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

Example of usage:

    dns_try_ipv6=yes

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:

   # 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 , "" )}

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)

event_pkg_threshold

A number representing the percentage threshold above which the E_CORE_PKG_THRESHOLD event is raised, warning about low amount of free private memory. It accepts integer values between 0 and 100.

Default value is 0 ( event disabled ).

Example of usage:

    event_pkg_threshold = 90

event_shm_threshold

A number representing the percentage threshold above which the E_CORE_SHM_THRESHOLD event is raised, warning about low amount of free shared memory. It accepts integer values between 0 and 100.

Default value is 0 ( event disabled ).

Example of usage:

    event_shm_threshold = 90

exec_dns_threshold

A number representing the maximum number of microseconds a DNS query is expected to last. Anything above the set number will trigger a warning message to the logging facility.

Default value is 0 ( logging disabled ).

Example of usage:

    exec_dns_threshold = 60000

exec_msg_threshold

A number representing the maximum number of microseconds the processing of a SIP msg is expected to last. Anything above the set number will trigger a warning message to the logging facility. Aside from the message and the processing time, the most time consuming function calls from the script will also be logged.

Default value is 0 ( logging disabled ).

Example of usage:

    exec_msg_threshold = 60000

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. First interface is used for listening to. OpenSIPS will only listen on UDP. Since the process is attached to the controlling terminal, not PID file will be created even if the -P command line option was specified.

Default value is 'yes'.

Example of usage:

    fork=no

group gid

The group id to run OpenSIPS.

Example of usage:

  group="opensips"

include_file

Can be called from outside route blocks to load additional routes/blocks or from inside them to simply preform more functions. The file path can be relative or absolute. If it is not an absolute path, first attempt is to locate it relative to current directory. If that fails, second try is relative to directory of the file that includes it. Will throw an error if file is not found.

Example of usage:

    include_file "proxy_regs.cfg"

import_file

Same as include_file but will not throw an error if file is not found.

Example of usage:

    import_file "proxy_regs.cfg"

listen

Set the network addresses the SIP server should listen to. It can be an IP address, hostname or network interface 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.

The listen definition may accept several optional parameters for:

  • configuring an advertise IP and port only for this interface. Syntax "AS 11.22.33.44:5060"
  • setting a different number of children for this interface only (for UDP and SCTP interfaces only). This will override the global "children" parameter. Syntax "use_children 5"

Remember that this parameters have affect only for the interface they are configured for; if not defined per interface, the global values will be used.

Example of usage:

    listen=10.10.10.10
    listen=eth1:5062
    listen=udp:10.10.10.10:5064
    listen=udp:127.0.0.1:5060 use_children 5
    listen=udp:127.0.0.1:5060 as 99.88.44.33:5060 use_children 3
    listen=127.0.0.1 use_children 3

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. Even if you specify only UDP interfaces here, the server will start the TCP engine too. If you don't want this, you need to disable the TCP support completely with the core parameter disable_tcp.

log_facility

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

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

Default value is LOG_DAEMON.

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 OpenSIPS runs in daemon mode (fork=yes), after daemonize. Default value is argv[0].

Example of usage:

    log_name="osips-5070"

log_stderror

With this parameter you can make OpenSIPS 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

max_while_loops

The parameters set the value of maximum loops that can be done within a "while". Comes as a protection to avoid infinite loops in config file execution. Default is 100.

Example of usage:

    max_while_loops=200

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

memdump | mem_dump

Log level to print memory status information (runtime and shutdown). It has to be less than the value of 'debug' parameter if you want memory info to be logged. Default: memdump=L_DBG (4)

Example of usage:

    memdump=2

NOTE that setting memlog (see below), will also set the memdump parameter - if you want different values for memlog and memdump, you need to first set memlog and then memdump.

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. Default: memlog=L_DBG (4)

Example of usage:

    memlog=2

NOTE: by setting memlog parameter, the memdump will automatically be set to the same value (see memdump docs).

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/opensips/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, OpenSIPS will try to increase its open file limit to this number. Note: OpenSIPS 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

query_buffer_size

If set to a value greater than 1, inserts to DB will not be flushed one by one. Rows to be inserted will be kept in memory until until they gather up to query_buffer_size rows, and only then they will be flushed to the database.

Example of usage:

    query_buffer_size=5

query_flush_time

If query_buffer_size is set to a value greater than 1, a timer will trigger once every query_flush_time seconds, ensuring that no row will be kept for too long in memory.

Example of usage:

     query_flush_time=10

rev_dns

This parameter controls if the SIP server should 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 OpenSIPS when it sends a request as UAS. It defaults to "OpenSIPS (<version> (<arch>/<os>))".

Example of usage:

server_header="Server: My Company SIP Proxy"

Please note that you have to add the header name "Server:", otherwise OpenSIPS will just write a header like:

My Company SIP Proxy

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: OpenSIPS (0.9.5 (i386/linux))

sip_warning

Can be 0 or 1. If set to 1 (default value is 0) a 'Warning' header is added to each reply generated by OpenSIPS. 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_listen_backlog

The backlog argument defines the maximum length to which the queue of pending connections for the TCP listeners may grow. If a connection request arrives when the queue is full, the client may receive an error with an indication of ECONNREFUSED or, if the underlying protocol supports retransmission, the request may be ignored so that a later reattempt at connection succeeds.

Default configured value is 10.

tcp_send_timeout

Time in seconds after a TCP connection will be closed if it is not available for writing in this interval (and OpenSIPS 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 OpenSIPS. 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

tcp_no_new_conn_bflag

A branch flag to be used as marker to instruct OpenSIPS not to attempt to open a new TCP connection when delivering a request, but only to reuse an existing one (if available). If no existing conn, a generic send error will be returned.

This is intended to be used in NAT scenarios, where makes no sense to open a TCP connection towards a destination behind a NAT (like TCP connection created during registration was lost, so there is no way to contact the device until it re-REGISTER). Also this can be used to detect when a NATed registered user lost his TCP connection, so that opensips can disable his registration as useless.

Example of usage:

     tcp_no_new_conn_bflag = 6
     ....
     route{
         ....
         if( destination_behin_nat && proto==TCP )
            setbflag(6);
         ....
         t_relay("0x02"); # no auto error reply
         $var(retcode) = $rc;
         if ($var(retcode)==-6) {
             #send error
             xlog("unable to send request to destination");
             send_reply("404","Not found");
             exit;
         } else if ($var(retcode)<0) {
             sl_reply_error();
             exit;
         }
         ....
     }

tcp_threshold

A number representing the maximum number of microseconds sending of a TCP request is expected to last. Anything above the set number will trigger a warning message to the logging facility.

Default value is 0 ( logging disabled ).

Example of usage:

    tcp_threshold = 60000

tcp_keepalive

Enable / disable TCP keepalive

Example of usage:

    tcp_keepalive = 1

tcp_keepcount

Number of keepalives to send before closing the connection (Linux only)

Example of usage:

    tcp_keepcount = 5

tcp_keepidle

Amount of time before OpenSIPS will start to send keepalives if the connection is idle (Linux only)

Example of usage:

    tcp_keepidle = 30

tcp_keepinterval

Interval between keepalive probes, if the previous one failed (Linux only)

Example of usage:

    tcp_keepinterval = 10

tls_ca_list

tls_certificate

tls_ciphers_list

tls_domain

tls_handshake_timeout

tls_log

tls_method

tls_port_no

tls_private_key

tls_require_certificate

tls_send_timeout

tls_verify

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

user uid

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

Example of usage:

    user="opensips"

user_agent_header

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

Example of usage:

user_agent_header="User-Agent: My Company SIP Proxy"

Please note that you have to include the header name "User-Agent:" as OpenSIPS does not add it and you will get an erroneous header like:

My Company SIP Proxy

wdir

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

Example of usage:

     wdir="/usr/local/opensips"
     or
     wdir=/usr/opensips_wd

(:toc-back:)


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()

Similarly to t_fork_to, it extends destination set by a new entry. The difference is that current URI is taken as new entry.

Without parameter, the function copies the current URI into a new branch. Thus, leaving the main branch (the URI) for further manipulation.

With a parameter, the function copies the URI in the parameter into a new branch. Thus, the current URI is not manipulated.

Note that it's not possible to append a new branch in "on_failure_route" block if a 6XX response has been previously received (it would be against RFC 3261).

Example of usage:

    # if someone calls B, the call should be forwarded to C too.
    #
    if (method=="INVITE" && uri=~"sip:B@xx.xxx.xx ")
    {
        # copy the current branch (branches[0]) into
        # a new branch (branches[1])
        append_branch();
        # all URI manipulation functions work on branches[0]
        # thus, URI manipulation does not touch the 
        # appended branch (branches[1])
        seturi("sip:C@domain");

        # now: branch 0 = C@domain
        #      branch 1 = B@xx.xx.xx.xx

        # and if you need a third destination ...

        # copy the current branch (branches[0]) into
        # a new branch (branches[2])
        append_branch();

        # all URI manipulation functions work on branches[0]
        # thus, URI manipulation does not touch the 
        # appended branch (branches[1-2])
        seturi("sip:D@domain");

        # now: branch 0 = D@domain
        #      branch 1 = B@xx.xx.xx.xx
        #      branch 2 = C@domain

        t_relay();
        exit;
    };

    # You could also use append_branch("sip:C@domain") which adds a branch with the new URI:


    if(method=="INVITE" && uri=~"sip:B@xx.xxx.xx ") {
        # append a new branch with the second destination
        append_branch("sip:user@domain");
        # now: branch 0 = B@xx.xx.xx.xx
        # now: branch 1 = C@domain

        t_relay();
        exit;
}

cache_store( storage_id, attribute_name, attribute_name [,timeout])

This sets in a memory-cache-like-storage system a new value for an attribute. Both the attribute name and value may contain pseudo-variables. If the attribute does not already exist in the memcache, it will be inserted with the given value; if already present, its value will be replaced with the new one. The function may optionally take an extra parameter, a timeout (or lifetime) value for the attribute - after the lifetime is exceeded, the attribute is automatically purged from memcache.

Function returns true is the new attribute was successfully inserted.

cache_store("local","my_attr","$avp(i:55)",1200);

OR

modparam("cachedb_redis","cachedb_url","redis:cluster1://192.168.2.134:6379/")
...
cache_store("redis:cluster1","passwd_$tu","$var(x)");

More complex examples can be found in the Key-Value Interface Tutorial.

cache_remove( storage_id, attribute_name)

This removes an attribute from a memory-cache-like-storage system. The attribute name may contain pseudo-variables. Function returns false only if the storage_id is invalid.

cache_remove("local","my_attr");

OR

modparam("cachedb_redis","cachedb_url","redis:cluster1://192.168.2.134:6379/")
...
cache_remove("redis:cluster1","my_attr");

More complex examples can be found in the Key-Value Interface Tutorial.

cache_fetch( storage_id, attribute_name, result_pvar)

This function fetches from a memory-cache-like-storage system the value of an attribute. The attribute name may contain pseudo-variables. The result (if any) will be stored in the pseudo-variable specified by result_pvar.

Function returns true if the attribute was found and its value returned.

cache_fetch("local","my_attr", $avp(i:11) );

OR

modparam("cachedb_redis","cachedb_url","redis:cluster1://192.168.2.134:6379/")
...
cache_fetch("redis:cluster1","my_attr",$avp(i:11));

More complex examples can be found in the Key-Value Interface Tutorial.

cache_counter_fetch( storage_id, counter_attribute_name, result_avp)

This function fetches from a memory-cache-like-storage system the value of a counter. The attribute name may contain pseudo-variables. The result (if any) will be stored in the pseudo-variable specified by result_pvar.

Function returns true if the attribute was found and its value returned.

cache_counter_fetch("local","my_counter", $avp(counter_val) );

OR

modparam("cachedb_redis","cachedb_url","redis:cluster1://192.168.2.134:6379/")
...
cache_fetch("redis:cluster1","my_counter",$avp(redis_counter_val));

cache_add( storage_id, attribute_name,increment_value,expire)

This increments an attribute in a memory-cache-like-storage system that supports such an operation. The attribute name may contain pseudo-variables. If the attribute does not exit, it will be created with the increment_value. If expire > 0, the key will also expire in the specified number of seconds.

Function returns false if increment fails.


modparam("cachedb_redis","cachedb_url","redis:cluster1://192.168.2.134:6379/")
...
cache_add("redis:cluster1",5);

More complex examples can be found in the Key-Value Interface Tutorial.

cache_sub( storage_id, attribute_name,increment_value,expire)

This decrements an attribute in a memory-cache-like-storage system that supports such an operation. The attribute name may contain pseudo-variables. If expire > 0, the key will also expire in the specified number of seconds.

Function returns false if decrement fails.


modparam("cachedb_redis","cachedb_url","redis:cluster1://192.168.2.134:6379/")
...
cache_sub("redis:cluster1",5);

More complex examples can be found in the Key-Value Interface Tutorial.

cache_raw_query( storage_id, raw_query,result_avp)

The function runs the provided raw query ( in the back-end dependent language ) and returns the results ( if any ) in the provided AVP. The result_avp can be missing, if the query returns no results.

Function returns false if query fails.

...
cache_raw_query("mongodb","{ \"op\" : \"count\",\"query\": { \"username\" : $rU} }","$avp(mongo_count_result)");
...

More complex examples can be found in the Key-Value Interface Tutorial.

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.

construct_uri(proto,user,domain,port,extra,result_avp)

The function builds a valid sip uri based on the arguments it receives. The result (if any) will be stored in the result_avp AVP variable. The function accepts plain text arguments, as well as $var and $avp variables. If you want to omit a part of the sip uri, just set the respective parameter to a blank string.

Example usage:

construct_uri("$var(proto)", "vlad", "$var(domain)", "", "$var(params)",$avp(s:newuri));
xlog("Constructed URI is <$avp(s:newuri)> \n");

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, OpenSIPS 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 OpenSIPS to send the message from the specified socket (it _must_ be one of the sockets OpenSIPS 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 in stateless mode. 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();

get_timestamp(sec_avp,usec_avp)

Returns the current timestamp, seconds and microseconds of the current second, from a single system call.

Example of usage:

     get_timestamp($avp(sec),$avp(usec));

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

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

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

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");

next_branches()

Adds to the request a new destination set that includes all highest priority class contacts ('q' value based) from the serialized branches (see serialize_branches()). If called from a route block, it rewrites the request uri with first contact and adds the remaining contacts as parallel branches. If called from failure route block, adds all contacts as parallel branches. All used contacts are removes the serialized branches.

Returns true if at least one contact was added for the request's destination set - returns 1 if other branches are still pending and return 2 if no other branches are left for future processing - shortly, if 2: this is the last branch, if 1: other will follow. False is return is nothing was done (no more serialized branches).

Example of usage:

    next_branches();

prefix(string)

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

Example of usage:

    prefix("00");

pv_printf(pv, string)

Prints the formatted 'string' in the AVP 'pv'. The 'string' parameter can include any pseudo-variable defined in OpenSIPS. The 'pv' can be any writable pseudo-variable -- e.g.,: AVPs, VARs, $ru, $rU, $rd, $du, $br, $fs.

It was extended from the avp_printf(...) function exported in previous versions by the avpops module. Starting with 1.3.0, avp_printf(...) is just an alias to pv_printf(...).

Example of usage:

    pv_printf("$var(x)", "r-uri: $ru");
    pv_printf("$avp(i:3)", "from uri: $fu");

raise_event(string[, avp[, avp]])

Raises from script an event through OpenSIPS Event Interface. The first parameter is a string that indicates the event which should be raised. The next two parameters should be AVPs and they are optional. If only one is present, it should contain the values attached to the event. If both of them are specified, the first one should contain the names of the attributes, and the last one the values attached to the event.

This function triggers an event for all subscribers for that event, regardless the transport module used.

Example of usage (raises an event with no attributes):

raise_event("E_NO_PARAM");

Example of usage (raises an event with two attributes):

$avp(attr-name) = "param1";
$avp(attr-name) = "param2";
$avp(attr-val) = 1;
$avp(attr-val) = "2"
raise_event("E_TWO_PARAMS", $avp(attr-name), $avp(attr-val));

remove_branch(pv|int)

Removes a given branch. The branch to be removed can be given via an integer or a pseudovariable. Once a branch is remove, all the subsequent branches are shifted (i.e. if branch n is removed, then the old n+1 branch becomes the new n branch, the old n+2 branch becomes n+1 and so on).

Example of usage (remove all branches with URI hostname "127.0.0.1"):

$var(i) = 0;
while ($(branch(uri)[$var(i)]) != null) {
   xlog("L_INFO","$$(branch(uri)[$var(i)])=[$(branch(uri)[$var(i)])]\n");
   if ($(branch(uri)[$var(i)]{uri.host}) == "127.0.0.1") {
       xlog("L_INFO","removing branch $var(i) with URI=[$(branch(uri)[$var(i)])]\n");
       remove_branch($var(i));
   } else {
       $var(i) = $var(i) + 1;
   }
}

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.

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

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

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

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@opensips.org");

route(name [, param1 [, param2 [, ...] ] ] )

This function is used to run the code from the 'name' route, declared in the script. Optionally, it can receive several parameters (up to 7), that can be later retrieved using the '$param(idx)' pseudo-variable.

The name of the route is an identifier format, whereas the parameters can be either int, string, or a pseudo-variable.

Example of usage:

   route(HANDLE_SEQUENTIALS);
   route(HANDLE_SEQUENTIALS, 1, "param", $var(param));

script_trace( log_level, pv_format_string[, info_string])

This function start the script tracing - this helps to better understand the flow of execution in the OpenSIPS script, like what function is executed, what line it is, etc. Moreover, you can also trace the values of pseudo-variables, as script execution progresses.

The blocks of the script where script tracing is enabled will print a line for each individual action that is done (e.g. assignments, conditional tests, module functions, core functions, etc.). Multiple pseudo-variables can be monitored by specifying a pv_format_string (e.g. "$ru---$avp(var1)").

The logs produced by multiple/different traced regions of your script can be differentiated (tagged) by specifying an additional plain string - info_string - as the 3rd parameter.

To disable script tracing, just do script_trace(). Otherwise, the tracing will automatically stop at the end the end of the top route.

Example of usage:

    script_trace( 1, "$rm from $si, ruri=$ru", "me");

will produce:

    [line 578][me][module consume_credentials] -> (INVITE from 127.0.0.1 , ruri=sip:111111@opensips.org)
    [line 581][me][core setsflag] -> (INVITE from 127.0.0.1 , ruri=sip:111111@opensips.org)
    [line 583][me][assign equal] -> (INVITE from 127.0.0.1 , ruri=sip:111111@opensips.org)
    [line 592][me][core if] -> (INVITE from 127.0.0.1 , ruri=sip:tester@opensips.org)
    [line 585][me][module is_avp_set] -> (INVITE from 127.0.0.1 , ruri=sip:tester@opensips.org)
    [line 589][me][core if] -> (INVITE from 127.0.0.1 , ruri=sip:tester@opensips.org)
    [line 586][me][module is_method] -> (INVITE from 127.0.0.1 , ruri=sip:tester@opensips.org)
    [line 587][me][module trace_dialog] -> (INVITE 127.0.0.1 , ruri=sip:tester@opensips.org)
    [line 590][me][core setflag] -> (INVITE from 127.0.0.1 , ruri=sip:tester@opensips.org) 

send(destination [, headers])

Send the original SIP message to a specific destination in stateless mode. This is definied as [proto:]host[:port]. No changes are applied to received message, no Via header is added, unless headers parameter is specified. 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). The headers parameter should end in '\r\n' and can accept both plain text and pseudo variables.

Parameter is mandatory and has string format.

Example of usage:

   send("udp:10.10.10.10:5070");
   send("udp:10.10.10.10:5070", "Server: opensips\r\n");

serialize_branches(clear)

Takes all the branches added for parallel forking (with append_branch() and including the current RURI) and prepare them for serial forking. The ordering is done in increasing "q" order. The serialized branches are internally stored in AVPs - you will be able to fetch and use via the "next_branches()" function.
NOTE that (according to RFC3261), the branches with the same "q" value will still be parallel forked during a certain step in the serial forking (it will result a combination of serial with parallel forking).
NOTE that this function is not changing RURI in the messages - it is just converting from parallel to serial branches (preparing branches).

If "clear" is set to non-zero, all previous results of another "serialize_branches" (serialized branches which were not yet used) will be deleted before setting the new serialized branches.

Example of usage:

   serialize_branches(1);

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("opensips.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);

setdebug([level])

Changes the debug level of the current process from script. If called without the parameter then the debug level of the current process will be reset to the global level. If the debug level of the current process is changed then changing the global debug level (using MI function) does not affect it, so be careful and make sure to reset the process debug level when you are done. This function is very helpful if you are tracing and debugging only a specific piece of code.

Example of usage:

    debug= -1 # errors only
    .....
    {
      ......
      setdebug(4); # set the debug level of the current process to DBG
      uac_replace_from(....);
      setdebug(); # reset the debug level of the current process to the global level
      .......
    }

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

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

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);

subscribe_event(string, string [, int])

Subscribes an external application for a certain event for the OpenSIPS Event Interface. This is used for transport protocols that cannot subscribe by themselves (example event_rabbitmq). This function should be called only once in the startup_route if the subscription doesn't expire, or in a timer route if the subscription should be renewed once in a while.

The first parameter is a string represents the name of the event an external application should be notified for. The second parameter is a string that specifies the socket of the external application. Note that this socket should follow the syntax of an existing loaded Event Interface transport module (example: event_datagram, event_rabbitmq). The last parameter is optional and specifies the expire time of the subscription. If it is not present, then the subscription does not expire at all.

Example of usage (subscriber that never expires, notified by the RabbitMQ module):

startup_route {
    subscribe_event("E_PIKE_BLOCKED", "rabbitmq:127.0.0.1/pike");
}

Example of usage (subscriber expires every 5 seconds, notified through UDP):

timer_route[event_subscribe, 4] {
    subscribe_event("E_PIKE_BLOCKED", "udp:127.0.0.1:5051", 5);
}

use_blacklist(string)

Enables the DNS blacklist name received as parameter. 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).

    use_blacklist("pstn-gws");
to:

(:redirect Documentation/Script-CoreFunctions quiet=1:)

January 29, 2013, at 05:21 PM by vlad_paiu -
Changed line 7 from:

This document is for OpenSIPS 1.9.x / devel

to:

This document is for OpenSIPS 1.10.x / devel

January 28, 2013, at 12:46 PM by vlad_paiu -
Changed line 1273 from:

cache_raw_query( storage_id, raw_query,result_avp)

to:

cache_raw_query( storage_id, raw_query,result_avp)

January 28, 2013, at 12:46 PM by vlad_paiu -
Added lines 1269-1282:

@]

More complex examples can be found in the Key-Value Interface Tutorial.

cache_raw_query( storage_id, raw_query,result_avp)

The function runs the provided raw query ( in the back-end dependent language ) and returns the results ( if any ) in the provided AVP. The result_avp can be missing, if the query returns no results.

Function returns false if query fails.

[@ ... cache_raw_query("mongodb","{ \"op\" : \"count\",\"query\": { \"username\" : $rU} }","$avp(mongo_count_result)"); ...

January 22, 2013, at 11:54 AM by razvancrainea -
Added lines 563-582:

event_pkg_threshold

A number representing the percentage threshold above which the E_CORE_PKG_THRESHOLD event is raised, warning about low amount of free private memory. It accepts integer values between 0 and 100.

Default value is 0 ( event disabled ).

Example of usage:

    event_pkg_threshold = 90

event_shm_threshold

A number representing the percentage threshold above which the E_CORE_SHM_THRESHOLD event is raised, warning about low amount of free shared memory. It accepts integer values between 0 and 100.

Default value is 0 ( event disabled ).

Example of usage:

    event_shm_threshold = 90
January 21, 2013, at 11:04 PM by bogdan -
January 21, 2013, at 11:04 PM by bogdan -
Added lines 1635-1660:

script_trace( log_level, pv_format_string[, info_string])

This function start the script tracing - this helps to better understand the flow of execution in the OpenSIPS script, like what function is executed, what line it is, etc. Moreover, you can also trace the values of pseudo-variables, as script execution progresses.

The blocks of the script where script tracing is enabled will print a line for each individual action that is done (e.g. assignments, conditional tests, module functions, core functions, etc.). Multiple pseudo-variables can be monitored by specifying a pv_format_string (e.g. "$ru---$avp(var1)").

The logs produced by multiple/different traced regions of your script can be differentiated (tagged) by specifying an additional plain string - info_string - as the 3rd parameter.

To disable script tracing, just do script_trace(). Otherwise, the tracing will automatically stop at the end the end of the top route.

Example of usage:

    script_trace( 1, "$rm from $si, ruri=$ru", "me");

will produce:

    [line 578][me][module consume_credentials] -> (INVITE from 127.0.0.1 , ruri=sip:111111@opensips.org)
    [line 581][me][core setsflag] -> (INVITE from 127.0.0.1 , ruri=sip:111111@opensips.org)
    [line 583][me][assign equal] -> (INVITE from 127.0.0.1 , ruri=sip:111111@opensips.org)
    [line 592][me][core if] -> (INVITE from 127.0.0.1 , ruri=sip:tester@opensips.org)
    [line 585][me][module is_avp_set] -> (INVITE from 127.0.0.1 , ruri=sip:tester@opensips.org)
    [line 589][me][core if] -> (INVITE from 127.0.0.1 , ruri=sip:tester@opensips.org)
    [line 586][me][module is_method] -> (INVITE from 127.0.0.1 , ruri=sip:tester@opensips.org)
    [line 587][me][module trace_dialog] -> (INVITE 127.0.0.1 , ruri=sip:tester@opensips.org)
    [line 590][me][core setflag] -> (INVITE from 127.0.0.1 , ruri=sip:tester@opensips.org) 
January 17, 2013, at 05:25 PM by bogdan -
Added lines 869-875:

tcp_listen_backlog

The backlog argument defines the maximum length to which the queue of pending connections for the TCP listeners may grow. If a connection request arrives when the queue is full, the client may receive an error with an indication of ECONNREFUSED or, if the underlying protocol supports retransmission, the request may be ignored so that a later reattempt at connection succeeds.

Default configured value is 10.

January 16, 2013, at 05:46 PM by razvancrainea -
Changed lines 1182-1185 from:

cache_fetch( storage_id, attribute_name, result_avp)

This function fetches from a memory-cache-like-storage system the value of an attribute. The attribute name may contain pseudo-variables. The result (if any) will be stored in the result_avp AVP variable.

to:

cache_fetch( storage_id, attribute_name, result_pvar)

This function fetches from a memory-cache-like-storage system the value of an attribute. The attribute name may contain pseudo-variables. The result (if any) will be stored in the pseudo-variable specified by result_pvar.

Changed line 1202 from:

This function fetches from a memory-cache-like-storage system the value of a counter. The attribute name may contain pseudo-variables. The result (if any) will be stored in the result_avp AVP variable.

to:

This function fetches from a memory-cache-like-storage system the value of a counter. The attribute name may contain pseudo-variables. The result (if any) will be stored in the pseudo-variable specified by result_pvar.

January 11, 2013, at 02:41 PM by razvancrainea -
Changed line 1617 from:

route(name [, param1])

to:

route(name [, param1 [, param2 [, ...] ] ] )

January 11, 2013, at 02:37 PM by razvancrainea -
Changed line 1617 from:

route(name [, param1 [, param2 ...]])

to:

route(name [, param1])

January 11, 2013, at 02:36 PM by razvancrainea -
Added lines 1616-1628:

route(name [, param1 [, param2 ...]])

This function is used to run the code from the 'name' route, declared in the script. Optionally, it can receive several parameters (up to 7), that can be later retrieved using the '$param(idx)' pseudo-variable.

The name of the route is an identifier format, whereas the parameters can be either int, string, or a pseudo-variable.

Example of usage:

   route(HANDLE_SEQUENTIALS);
   route(HANDLE_SEQUENTIALS, 1, "param", $var(param));
November 06, 2012, at 12:09 PM by vlad_paiu -
Added lines 1199-1214:

cache_counter_fetch( storage_id, counter_attribute_name, result_avp)

This function fetches from a memory-cache-like-storage system the value of a counter. The attribute name may contain pseudo-variables. The result (if any) will be stored in the result_avp AVP variable.

Function returns true if the attribute was found and its value returned.

cache_counter_fetch("local","my_counter", $avp(counter_val) );

OR

modparam("cachedb_redis","cachedb_url","redis:cluster1://192.168.2.134:6379/")
...
cache_fetch("redis:cluster1","my_counter",$avp(redis_counter_val));
October 02, 2012, at 03:31 PM by saghul -
Changed line 589 from:

When set to 'no', the proxy will stay bound to the terminal and runs as single process. First interface is used for listening to.

to:

When set to 'no', the proxy will stay bound to the terminal and runs as single process. First interface is used for listening to. OpenSIPS will only listen on UDP. Since the process is attached to the controlling terminal, not PID file will be created even if the -P command line option was specified.

August 07, 2012, at 10:29 PM by 67.201.69.130 -
Deleted line 1747:

}

August 07, 2012, at 10:26 PM by 67.201.69.130 -
Added lines 1740-1747:

} @]

use_blacklist(string)

Enables the DNS blacklist name received as parameter. 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). [@

    use_blacklist("pstn-gws");
March 22, 2012, at 12:53 PM by vlad_paiu -
Changed line 7 from:

This document is for OpenSIPS 1.8.x / devel

to:

This document is for OpenSIPS 1.9.x / devel

March 14, 2012, at 06:05 PM by vlad_paiu -
Added lines 950-981:

tcp_keepalive

Enable / disable TCP keepalive

Example of usage:

    tcp_keepalive = 1

tcp_keepcount

Number of keepalives to send before closing the connection (Linux only)

Example of usage:

    tcp_keepcount = 5

tcp_keepidle

Amount of time before OpenSIPS will start to send keepalives if the connection is idle (Linux only)

Example of usage:

    tcp_keepidle = 30

tcp_keepinterval

Interval between keepalive probes, if the previous one failed (Linux only)

Example of usage:

    tcp_keepinterval = 10
March 13, 2012, at 04:16 PM by vlad_paiu -
Added lines 604-623:

include_file

Can be called from outside route blocks to load additional routes/blocks or from inside them to simply preform more functions. The file path can be relative or absolute. If it is not an absolute path, first attempt is to locate it relative to current directory. If that fails, second try is relative to directory of the file that includes it. Will throw an error if file is not found.

Example of usage:

    include_file "proxy_regs.cfg"

import_file

Same as include_file but will not throw an error if file is not found.

Example of usage:

    import_file "proxy_regs.cfg"
March 08, 2012, at 01:06 PM by vlad_paiu -
Added line 577:

Aside from the message and the processing time, the most time consuming function calls from the script will also be logged.

March 08, 2012, at 12:52 PM by bogdan -
March 08, 2012, at 12:52 PM by bogdan -
Added line 298:
Changed lines 309-311 from:

NOTE: Aside this global approach, you can also define an advertise IP and port in a per-interface manner (see the "listen" parameter). When advertise values are defined per interface, they will be used only for traffic leaving that interface only.

to:

NOTE: Aside this global approach, you can also define an advertise IP and port in a per-interface manner (see the "listen" parameter). When advertise values are defined per interface, they will be used only for traffic leaving that interface only.

Changed lines 326-335 from:

avp_aliases

Contains a multiple definition of aliases for AVP names.

Example of usage:

    avp_aliases="uuid=I:660;email=s:email_addr;fwd=i:753"
to:
Changed line 335 from:
to:

[@

Changed lines 338-339 from:
to:

@]

Changed lines 350-351 from:

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

to:

Number of children to fork for each UDP or SCTP interface you have defined. Default value is 8.

Changed line 353 from:
to:

[@

Changed lines 355-358 from:
to:

@]

NOTE: this global value (applicable for all UDP/SCTP interfaces) can be override if you set a different number of children in the definition of a specific interface - so actually you can define a different number of children for each interface (see the "listen" parameter for syntax).

Changed lines 374-376 from:
    db_version_table="version_1_5"
to:
    db_version_table="version_1_8"
Changed line 393 from:
    debug=3 -- print only important messages (like errors or more critical situations) 
to:
    debug=1 -- print only important messages (like errors or more critical situations) 
Changed line 396 from:
    debug=9 -- print a lot of debug messages - use it only when doing debugging sessions
to:
    debug=4 -- print a lot of debug messages - use it only when doing debugging sessions
Added lines 398-408:

Actual values are:

  • -3 - Alert level
  • -2 - Critical level
  • -1 - Error level
  • 1 - Warning level
  • 2 - Notice level
  • 3 - Info level
  • 4 - Debug level
March 08, 2012, at 12:40 PM by bogdan -
Changed line 289 from:
  WARNING: 
to:

WARNING:

Changed line 295 from:
to:

[@

Changed lines 297-299 from:

NOTE: Aside this global approach, you can also define an advertise IP and port in a per-interface manner (see the "listen" parameter). When advertise values are defined per interface, they will be used only for traffic leaving that interface only.

to:

@] NOTE: Aside this global approach, you can also define an advertise IP and port in a per-interface manner (see the "listen" parameter). When advertise values are defined per interface, they will be used only for traffic leaving that interface only.

Changed line 305 from:
to:

[@

Changed line 307 from:
to:

@]

March 08, 2012, at 12:38 PM by bogdan - children
March 08, 2012, at 12:38 PM by bogdan -
Added lines 298-299:

NOTE: Aside this global approach, you can also define an advertise IP and port in a per-interface manner (see the "listen" parameter). When advertise values are defined per interface, they will be used only for traffic leaving that interface only.

Added line 308:

NOTE: Aside this global approach, you can also define an advertise IP and port in a per-interface manner (see the "listen" parameter). When advertise values are defined per interface, they will be used only for traffic leaving that interface only.

March 08, 2012, at 12:36 PM by bogdan -
Added lines 597-601:

The listen definition may accept several optional parameters for:

  • configuring an advertise IP and port only for this interface. Syntax "AS 11.22.33.44:5060"
  • setting a different number of children for this interface only (for UDP and SCTP interfaces only). This will override the global "children" parameter. Syntax "use_children 5"

Remember that this parameters have affect only for the interface they are configured for; if not defined per interface, the global values will be used.

Added lines 608-610:
    listen=udp:127.0.0.1:5060 use_children 5
    listen=udp:127.0.0.1:5060 as 99.88.44.33:5060 use_children 3
    listen=127.0.0.1 use_children 3
March 05, 2012, at 04:52 PM by vlad_paiu -
Changed lines 902-903 from:
to:

tcp_threshold

A number representing the maximum number of microseconds sending of a TCP request is expected to last. Anything above the set number will trigger a warning message to the logging facility.

Default value is 0 ( logging disabled ).

Example of usage:

    tcp_threshold = 60000
October 07, 2011, at 01:05 PM by vlad_paiu -
Changed lines 1122-1125 from:

cache_add( storage_id, attribute_name,increment_value)

This increments an attribute in a memory-cache-like-storage system that supports such an operation. The attribute name may contain pseudo-variables. If the attribute does not exit, it will be created with the increment_value.

to:

cache_add( storage_id, attribute_name,increment_value,expire)

This increments an attribute in a memory-cache-like-storage system that supports such an operation. The attribute name may contain pseudo-variables. If the attribute does not exit, it will be created with the increment_value. If expire > 0, the key will also expire in the specified number of seconds.

Changed lines 1137-1139 from:

cache_sub( storage_id, attribute_name,increment_value)

This decrements an attribute in a memory-cache-like-storage system that supports such an operation. The attribute name may contain pseudo-variables.

to:

cache_sub( storage_id, attribute_name,increment_value,expire)

This decrements an attribute in a memory-cache-like-storage system that supports such an operation. The attribute name may contain pseudo-variables. If expire > 0, the key will also expire in the specified number of seconds.

October 05, 2011, at 04:16 PM by vlad_paiu -
Deleted lines 1070-1071:

As these functions (memcache) are just part of a generic memcache interface, you need to specify what memcache implementation you want to use via this command -> the storage_id points the memcache implementation. Currently there is only one available, "local", provided by the localcache module.

Changed lines 1075-1080 from:

cache_store("local","passwd_$tu","$var(x)");

to:

OR

modparam("cachedb_redis","cachedb_url","redis:cluster1://192.168.2.134:6379/") ... cache_store("redis:cluster1","passwd_$tu","$var(x)");

Changed lines 1083-1085 from:

A more complex example can be found in the MemCache Tutorial.

to:

More complex examples can be found in the Key-Value Interface Tutorial.

Deleted lines 1088-1090:

As these functions (memcache) are just part of a generic memcache interface, you need to specify what memcache implementation you want to use via this command -> the storage_id points the memcache implementation. Currently there is only one available, "local", provided by the localcache module.

Changed lines 1093-1098 from:

cache_remove("local","passwd_$tu");

to:

OR

modparam("cachedb_redis","cachedb_url","redis:cluster1://192.168.2.134:6379/") ... cache_remove("redis:cluster1","my_attr");

Changed lines 1101-1103 from:

A more complex example can be found in the MemCache Tutorial.

to:

More complex examples can be found in the Key-Value Interface Tutorial.

Deleted lines 1107-1108:

As these functions (memcache) are just part of a generic memcache interface, you need to specify what memcache implementation you want to use via this command -> the storage_id points the memcache implementation. Currently there is only one available, "local", provided by the localcache module.

Changed lines 1112-1117 from:

cache_fetch("local","passwd_$tu", $var(x) );

to:

OR

modparam("cachedb_redis","cachedb_url","redis:cluster1://192.168.2.134:6379/") ... cache_fetch("redis:cluster1","my_attr",$avp(i:11));

Changed lines 1120-1122 from:

A more complex example can be found in the MemCache Tutorial.

to:

More complex examples can be found in the Key-Value Interface Tutorial.

cache_add( storage_id, attribute_name,increment_value)

This increments an attribute in a memory-cache-like-storage system that supports such an operation. The attribute name may contain pseudo-variables. If the attribute does not exit, it will be created with the increment_value.

Function returns false if increment fails.


modparam("cachedb_redis","cachedb_url","redis:cluster1://192.168.2.134:6379/")
...
cache_add("redis:cluster1",5);

More complex examples can be found in the Key-Value Interface Tutorial.

cache_sub( storage_id, attribute_name,increment_value)

This decrements an attribute in a memory-cache-like-storage system that supports such an operation. The attribute name may contain pseudo-variables.

Function returns false if decrement fails.


modparam("cachedb_redis","cachedb_url","redis:cluster1://192.168.2.134:6379/")
...
cache_sub("redis:cluster1",5);

More complex examples can be found in the Key-Value Interface Tutorial.

October 03, 2011, at 02:38 PM by razvancrainea -
Changed line 1607 from:

subscribe_event(string, string, [, int])

to:

subscribe_event(string, string [, int])

October 03, 2011, at 02:38 PM by razvancrainea -
Changed lines 1311-1317 from:

remove_branch(pv|int)

Removes a given branch. The branch to be removed can be given via an integer or a pseudovariable. Once a branch is remove, all the subsequent branches are shifted (i.e. if branch n is removed, then the old n+1 branch becomes the new n branch, the old n+2 branch becomes n+1 and so on).

Example of usage (remove all branches with URI hostname "127.0.0.1"):

to:

raise_event(string[, avp[, avp]])

Raises from script an event through OpenSIPS Event Interface. The first parameter is a string that indicates the event which should be raised. The next two parameters should be AVPs and they are optional. If only one is present, it should contain the values attached to the event. If both of them are specified, the first one should contain the names of the attributes, and the last one the values attached to the event.

This function triggers an event for all subscribers for that event, regardless the transport module used.

Example of usage (raises an event with no attributes):

Changed lines 1320-1329 from:

$var(i) = 0; while ($(branch(uri)[$var(i)]) != null) {

   xlog("L_INFO","$$(branch(uri)[$var(i)])=[$(branch(uri)[$var(i)])]\n");
   if ($(branch(uri)[$var(i)]{uri.host}) == "127.0.0.1") {
       xlog("L_INFO","removing branch $var(i) with URI=[$(branch(uri)[$var(i)])]\n");
       remove_branch($var(i));
   } else {
       $var(i) = $var(i) + 1;
   }

}

to:

raise_event("E_NO_PARAM");

Changed lines 1323-1336 from:

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.

return(0) is same as "exit()";

In bool expressions:

  * Negative and ZERO is FALSE
  * Positive is TRUE

Example usage:

to:

Example of usage (raises an event with two attributes):

Changed lines 1326-1332 from:

route {

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

}

to:

$avp(attr-name) = "param1"; $avp(attr-name) = "param2"; $avp(attr-val) = 1; $avp(attr-val) = "2" raise_event("E_TWO_PARAMS", $avp(attr-name), $avp(attr-val));

Added lines 1332-1339:

remove_branch(pv|int)

Removes a given branch. The branch to be removed can be given via an integer or a pseudovariable. Once a branch is remove, all the subsequent branches are shifted (i.e. if branch n is removed, then the old n+1 branch becomes the new n branch, the old n+2 branch becomes n+1 and so on).

Example of usage (remove all branches with URI hostname "127.0.0.1"):

Changed lines 1341-1348 from:

route[2] {

  if (is_method("INVITE")) {
    return(1);
  } else if (is_method("REGISTER")) {
    return(-1);
  } else {
    return(0);
  };
to:

$var(i) = 0; while ($(branch(uri)[$var(i)]) != null) {

   xlog("L_INFO","$$(branch(uri)[$var(i)])=[$(branch(uri)[$var(i)])]\n");
   if ($(branch(uri)[$var(i)]{uri.host}) == "127.0.0.1") {
       xlog("L_INFO","removing branch $var(i) with URI=[$(branch(uri)[$var(i)])]\n");
       remove_branch($var(i));
   } else {
       $var(i) = $var(i) + 1;
   }
Added lines 1353-1387:

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.

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);
  };
}
Changed lines 1607-1627 from:
to:

subscribe_event(string, string, [, int])

Subscribes an external application for a certain event for the OpenSIPS Event Interface. This is used for transport protocols that cannot subscribe by themselves (example event_rabbitmq). This function should be called only once in the startup_route if the subscription doesn't expire, or in a timer route if the subscription should be renewed once in a while.

The first parameter is a string represents the name of the event an external application should be notified for. The second parameter is a string that specifies the socket of the external application. Note that this socket should follow the syntax of an existing loaded Event Interface transport module (example: event_datagram, event_rabbitmq). The last parameter is optional and specifies the expire time of the subscription. If it is not present, then the subscription does not expire at all.

Example of usage (subscriber that never expires, notified by the RabbitMQ module):

startup_route {
    subscribe_event("E_PIKE_BLOCKED", "rabbitmq:127.0.0.1/pike");
}

Example of usage (subscriber expires every 5 seconds, notified through UDP):

timer_route[event_subscribe, 4] {
    subscribe_event("E_PIKE_BLOCKED", "udp:127.0.0.1:5051", 5);
}
September 08, 2011, at 01:58 PM by razvancrainea -
Changed lines 1465-1468 from:

send(destination)

Send the original SIP message to a specific destination in stateless mode. 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).

to:

send(destination [, headers])

Send the original SIP message to a specific destination in stateless mode. This is definied as [proto:]host[:port]. No changes are applied to received message, no Via header is added, unless headers parameter is specified. 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). The headers parameter should end in '\r\n' and can accept both plain text and pseudo variables.

Added line 1474:
   send("udp:10.10.10.10:5070", "Server: opensips\r\n");
July 12, 2011, at 06:50 PM by bogdan -
Changed line 7 from:

This document is for OpenSIPS 1.7.x / devel

to:

This document is for OpenSIPS 1.8.x / devel

July 06, 2011, at 10:16 AM by bogdan -
Added lines 375-384:

db_default_url

The default DB URL to be used by modules if no per-module URL is given. Default is NULL (not defined)

Example of usage:

    db_default_url="mysql://opensips:opensipsrw@localhost/opensips"
June 24, 2011, at 05:38 PM by vlad_paiu -
Added lines 1203-1210:

get_timestamp(sec_avp,usec_avp)

Returns the current timestamp, seconds and microseconds of the current second, from a single system call.

Example of usage:

     get_timestamp($avp(sec),$avp(usec));
June 24, 2011, at 01:15 PM by bogdan -
Added lines 862-893:

tcp_no_new_conn_bflag

A branch flag to be used as marker to instruct OpenSIPS not to attempt to open a new TCP connection when delivering a request, but only to reuse an existing one (if available). If no existing conn, a generic send error will be returned.

This is intended to be used in NAT scenarios, where makes no sense to open a TCP connection towards a destination behind a NAT (like TCP connection created during registration was lost, so there is no way to contact the device until it re-REGISTER). Also this can be used to detect when a NATed registered user lost his TCP connection, so that opensips can disable his registration as useless.

Example of usage:

     tcp_no_new_conn_bflag = 6
     ....
     route{
         ....
         if( destination_behin_nat && proto==TCP )
            setbflag(6);
         ....
         t_relay("0x02"); # no auto error reply
         $var(retcode) = $rc;
         if ($var(retcode)==-6) {
             #send error
             xlog("unable to send request to destination");
             send_reply("404","Not found");
             exit;
         } else if ($var(retcode)<0) {
             sl_reply_error();
             exit;
         }
         ....
     }
June 22, 2011, at 10:35 AM by vlad_paiu -
Added lines 746-762:

query_buffer_size

If set to a value greater than 1, inserts to DB will not be flushed one by one. Rows to be inserted will be kept in memory until until they gather up to query_buffer_size rows, and only then they will be flushed to the database.

Example of usage:

    query_buffer_size=5

query_flush_time

If query_buffer_size is set to a value greater than 1, a timer will trigger once every query_flush_time seconds, ensuring that no row will be kept for too long in memory.

Example of usage:

     query_flush_time=10
May 03, 2011, at 04:25 PM by osas - document remove_branch()
Added lines 1243-1262:

remove_branch(pv|int)

Removes a given branch. The branch to be removed can be given via an integer or a pseudovariable. Once a branch is remove, all the subsequent branches are shifted (i.e. if branch n is removed, then the old n+1 branch becomes the new n branch, the old n+2 branch becomes n+1 and so on).

Example of usage (remove all branches with URI hostname "127.0.0.1"):

$var(i) = 0;
while ($(branch(uri)[$var(i)]) != null) {
   xlog("L_INFO","$$(branch(uri)[$var(i)])=[$(branch(uri)[$var(i)])]\n");
   if ($(branch(uri)[$var(i)]{uri.host}) == "127.0.0.1") {
       xlog("L_INFO","removing branch $var(i) with URI=[$(branch(uri)[$var(i)])]\n");
       remove_branch($var(i));
   } else {
       $var(i) = $var(i) + 1;
   }
}
February 21, 2011, at 04:14 PM by vlad_paiu -
Added lines 547-552:

Default value is 0 ( logging disabled ).

Example of usage:

    exec_dns_threshold = 60000
Added lines 556-561:

Default value is 0 ( logging disabled ).

Example of usage:

    exec_msg_threshold = 60000
February 21, 2011, at 03:56 PM by vlad_paiu -
Added lines 543-549:

exec_dns_threshold

A number representing the maximum number of microseconds a DNS query is expected to last. Anything above the set number will trigger a warning message to the logging facility.

exec_msg_threshold

A number representing the maximum number of microseconds the processing of a SIP msg is expected to last. Anything above the set number will trigger a warning message to the logging facility.

October 15, 2010, at 02:37 PM by vlad_paiu -
Added lines 1043-1052:

construct_uri(proto,user,domain,port,extra,result_avp)

The function builds a valid sip uri based on the arguments it receives. The result (if any) will be stored in the result_avp AVP variable. The function accepts plain text arguments, as well as $var and $avp variables. If you want to omit a part of the sip uri, just set the respective parameter to a blank string.

Example usage:

construct_uri("$var(proto)", "vlad", "$var(domain)", "", "$var(params)",$avp(s:newuri));
xlog("Constructed URI is <$avp(s:newuri)> \n");
October 08, 2010, at 01:31 PM by bogdan -
Added lines 394-399:

disable_503_translation

If 'yes', OpenSIPS will not translate the received 503 replies into 500 replies (RFC 3261 clearly states that a proxy should never relay a 503 response, but instead it must transform it into a 500).

Default value is 'no' (do translation).

October 06, 2010, at 04:56 PM by bogdan -
Changed line 1183 from:

Returns true if at least one contact was added for the request's destination set. False is return is nothing was done (no more serialized branches).

to:

Returns true if at least one contact was added for the request's destination set - returns 1 if other branches are still pending and return 2 if no other branches are left for future processing - shortly, if 2: this is the last branch, if 1: other will follow. False is return is nothing was done (no more serialized branches).

September 16, 2010, at 02:05 AM by osas - Add disable_stateless_fwd
Added lines 429-437:

disable_stateless_fwd

Can be 'yes' or 'no'. This parameter controls the handling of stateless replies:

    yes - drop stateless replies if stateless fwd functions (like forward) are not used in script
    no - forward stateless replies

Default value is 'yes'.

March 23, 2010, at 12:56 AM by 187.65.195.249 -
Changed line 752 from:

Can be 0 or 1. If set to 1 (default value) a 'Warning' header is added to each rely generated by OpenSIPS.

to:

Can be 0 or 1. If set to 1 (default value is 0) a 'Warning' header is added to each reply generated by OpenSIPS.

October 13, 2009, at 11:32 PM by bogdan -
Changed line 7 from:

This document is for OpenSIPS 1.6.x / devel

to:

This document is for OpenSIPS 1.7.x / devel

August 20, 2009, at 09:28 AM by bogdan -
Added lines 367-374:

db_version_table

The name of the table version to be used by the DB API to check the version of the used tables.
Default value is "version"

Example of usage:

    db_version_table="version_1_5"
August 20, 2009, at 09:16 AM by bogdan -
Changed lines 615-618 from:

memlog

Log level to print memory debug info. It has be less than the value of 'debug' parameter if you want memory info to be logged. Default: memlog=L_DBG (4)

to:

memdump | mem_dump

Log level to print memory status information (runtime and shutdown). It has to be less than the value of 'debug' parameter if you want memory info to be logged. Default: memdump=L_DBG (4)

Added lines 622-632:
    memdump=2

NOTE that setting memlog (see below), will also set the memdump parameter - if you want different values for memlog and memdump, you need to first set memlog and then memdump.

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. Default: memlog=L_DBG (4)

Example of usage:

Added lines 634-635:

NOTE: by setting memlog parameter, the memdump will automatically be set to the same value (see memdump docs).

April 23, 2009, at 10:25 AM by bogdan -
Added lines 186-187:

Changed lines 274-276 from:
to:

(:toc-back:)


Changed lines 876-878 from:
to:

(:toc-back:)


April 23, 2009, at 10:24 AM by bogdan -
Changed lines 2-3 from:
to:

Added line 15:

April 23, 2009, at 10:20 AM by bogdan -
Changed lines 1-3 from:

Resources -> Documentation -> CookBooks -> Core functions and parameters v1.5

to:

Resources -> Documentation -> CookBooks -> Core functions and parameters - devel

Changed line 7 from:

This document is for OpenSIPS 1.5.x

to:

This document is for OpenSIPS 1.6.x / devel

January 30, 2009, at 06:40 PM by 81.180.102.217 -
Added lines 960-993:

cache_remove( storage_id, attribute_name)

This removes an attribute from a memory-cache-like-storage system. The attribute name may contain pseudo-variables.

As these functions (memcache) are just part of a generic memcache interface, you need to specify what memcache implementation you want to use via this command -> the storage_id points the memcache implementation. Currently there is only one available, "local", provided by the localcache module.

Function returns false only if the storage_id is invalid.

cache_remove("local","my_attr");
cache_remove("local","passwd_$tu");

A more complex example can be found in the MemCache Tutorial.

cache_fetch( storage_id, attribute_name, result_avp)

This function fetches from a memory-cache-like-storage system the value of an attribute. The attribute name may contain pseudo-variables. The result (if any) will be stored in the result_avp AVP variable.

As these functions (memcache) are just part of a generic memcache interface, you need to specify what memcache implementation you want to use via this command -> the storage_id points the memcache implementation. Currently there is only one available, "local", provided by the localcache module.

Function returns true if the attribute was found and its value returned.

cache_fetch("local","my_attr", $avp(i:11) );
cache_fetch("local","passwd_$tu", $var(x) );

A more complex example can be found in the MemCache Tutorial.

January 30, 2009, at 06:31 PM by 81.180.102.217 -
Changed lines 425-426 from:

disable_tls

to:

disable_tls

Changed lines 945-946 from:

cache_store( storage_id, attribute_name, attribute_name [,timeout])

to:

cache_store( storage_id, attribute_name, attribute_name [,timeout])

Changed lines 949-950 from:

As these functions (memcache) are just part of a generic memcache interface, you need to specify what memcache implementation you want to use via this command -> the storage_id points the memcache implementation. Currently there is only one available, "local", provided by the [http://www.opensips.org/html/docs/modules/devel/localcache.html|localcache module].

to:

As these functions (memcache) are just part of a generic memcache interface, you need to specify what memcache implementation you want to use via this command -> the storage_id points the memcache implementation. Currently there is only one available, "local", provided by the localcache module.

Changed lines 958-959 from:

A more complex example can be found in the [[Resources.DocsTutMemcache | MemCache Tutorial].

to:

A more complex example can be found in the MemCache Tutorial.

January 30, 2009, at 06:29 PM by 81.180.102.217 -
Changed line 935 from:
        # append a new branch with the second destionation
to:
        # append a new branch with the second destination
Added lines 945-959:

cache_store( storage_id, attribute_name, attribute_name [,timeout])

This sets in a memory-cache-like-storage system a new value for an attribute. Both the attribute name and value may contain pseudo-variables. If the attribute does not already exist in the memcache, it will be inserted with the given value; if already present, its value will be replaced with the new one. The function may optionally take an extra parameter, a timeout (or lifetime) value for the attribute - after the lifetime is exceeded, the attribute is automatically purged from memcache.

As these functions (memcache) are just part of a generic memcache interface, you need to specify what memcache implementation you want to use via this command -> the storage_id points the memcache implementation. Currently there is only one available, "local", provided by the [http://www.opensips.org/html/docs/modules/devel/localcache.html|localcache module].

Function returns true is the new attribute was successfully inserted.

cache_store("local","my_attr","$avp(i:55)",1200);
cache_store("local","passwd_$tu","$var(x)");

A more complex example can be found in the [[Resources.DocsTutMemcache | MemCache Tutorial].

January 30, 2009, at 05:51 PM by 81.180.102.217 -
Changed lines 1-3 from:

Resources -> Documentation -> CookBooks -> Core functions and parameters

to:

Resources -> Documentation -> CookBooks -> Core functions and parameters v1.5

Changed lines 7-8 from:
to:

This document is for OpenSIPS 1.5.x

October 10, 2008, at 10:05 AM by 81.180.102.217 -
Changed lines 1124-1127 from:

You can test the value returned by a route using $retcode? variable.

return(0) is same as exit()?;

to:

You can test the value returned by a route using "$retcode" variable.

return(0) is same as "exit()";

October 10, 2008, at 10:02 AM by 81.180.102.217 -
Changed lines 1047-1048 from:

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

to:

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

Changed lines 1059-1060 from:

For more about script flags, see utils:flags?.

to:

For more about script flags, see Flags Documentation.

Changed lines 1071-1072 from:

For more about script flags, see utils:flags?.

to:

For more about script flags, see Flags Documentation.

Changed lines 1168-1169 from:

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

to:

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

Changed lines 1178-1179 from:

For more about script flags, see utils:flags?.

to:

For more about script flags, see Flags Documentation.

Changed lines 1193-1194 from:

For more about script flags, see utils:flags?.

to:

For more about script flags, see Flags Documentation.

Changed lines 1337-1338 from:

For more about script flags, see utils:flags?.

to:

For more about script flags, see Flags Documentation.

Changed lines 1352-1353 from:

For more about script flags, see utils:flags?.

to:

For more about script flags, see Flags Documentation.

October 10, 2008, at 09:58 AM by 81.180.102.217 -
Changed lines 1090-1093 from:

prefix(string)

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

to:

next_branches()

Adds to the request a new destination set that includes all highest priority class contacts ('q' value based) from the serialized branches (see serialize_branches()). If called from a route block, it rewrites the request uri with first contact and adds the remaining contacts as parallel branches. If called from failure route block, adds all contacts as parallel branches. All used contacts are removes the serialized branches.

Returns true if at least one contact was added for the request's destination set. False is return is nothing was done (no more serialized branches).

Added lines 1099-1107:
    next_branches();

prefix(string)

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

Example of usage:

October 10, 2008, at 09:50 AM by 81.180.102.217 -
Changed lines 1255-1258 from:

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.

to:

serialize_branches(clear)

Takes all the branches added for parallel forking (with append_branch() and including the current RURI) and prepare them for serial forking. The ordering is done in increasing "q" order. The serialized branches are internally stored in AVPs - you will be able to fetch and use via the "next_branches()" function.
NOTE that (according to RFC3261), the branches with the same "q" value will still be parallel forked during a certain step in the serial forking (it will result a combination of serial with parallel forking).
NOTE that this function is not changing RURI in the messages - it is just converting from parallel to serial branches (preparing branches).

If "clear" is set to non-zero, all previous results of another "serialize_branches" (serialized branches which were not yet used) will be deleted before setting the new serialized branches.

Added lines 1265-1274:
   serialize_branches(1);

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:

October 07, 2008, at 08:23 PM by 81.180.102.217 -
Changed lines 1-3 from:

Resources -> Documentation -> CookBooks? -> Core functions and parameters

to:

Resources -> Documentation -> CookBooks -> Core functions and parameters

October 07, 2008, at 08:22 PM by 81.180.102.217 -
Changed lines 1-3 from:

Resources -> Documentation -> Core functions and parameters

to:

Resources -> Documentation -> CookBooks? -> Core functions and parameters

October 03, 2008, at 12:49 PM by 81.180.102.217 -
October 03, 2008, at 12:41 PM by 81.180.102.217 -
Added line 4:

(:toc-float Table of Content:)

Deleted line 13:

(:toc-float Table of Content:)

October 03, 2008, at 12:41 PM by 81.180.102.217 -
Changed lines 3-4 from:

(:toc-float Table of Content:)

to:
Added line 13:

(:toc-float Table of Content:)

October 03, 2008, at 12:38 PM by 81.180.102.217 -
Changed lines 182-183 from:
to:

(:toc-back:)

October 03, 2008, at 12:35 PM by 81.180.102.217 -
Changed lines 3-4 from:

(:toc-float:)

to:

(:toc-float Table of Content:)

October 03, 2008, at 12:34 PM by 81.180.102.217 -
Added lines 3-4:

(:toc-float:)

Changed lines 7-8 from:

(:toc-float:)

to:
October 03, 2008, at 12:34 PM by 81.180.102.217 -
Added lines 5-6:

(:toc-float:)

Changed lines 12-13 from:

(:toc-float:)

to:
October 03, 2008, at 12:33 PM by 81.180.102.217 -
Changed lines 10-11 from:

(:toc:)

to:

(:toc-float:)

October 03, 2008, at 12:27 PM by 81.180.102.217 -
Changed lines 10-11 from:

(:htoc:)

to:

(:toc:)

October 03, 2008, at 12:25 PM by 81.180.102.217 -
Changed lines 10-11 from:

(:toc:)

to:

(:htoc:)

October 03, 2008, at 12:24 PM by 81.180.102.217 -
Changed lines 10-11 from:

(:toc init=hide:)

to:

(:toc:)

October 03, 2008, at 12:23 PM by 81.180.102.217 -
Changed lines 10-11 from:

(:toc:)

to:

(:toc init=hide:)

October 03, 2008, at 12:20 PM by 81.180.102.217 -
Changed lines 10-11 from:

(:toc-hide:)

to:

(:toc:)

October 03, 2008, at 12:18 PM by 81.180.102.217 -
Changed lines 10-11 from:

(:toc:)

to:

(:toc-hide:)

October 03, 2008, at 12:15 PM by 81.180.102.217 -
Changed lines 13-14 from:

Core Keywords

to:

Core Keywords

Changed lines 17-18 from:

af

to:

af

October 03, 2008, at 12:11 PM by 81.180.102.217 -
Changed lines 10-11 from:
to:

(:toc:)

July 21, 2008, at 04:14 PM by 81.180.102.217 -
Changed lines 1-2 from:

OpenSIPS Core CookBook

to:

Resources -> Documentation -> Core functions and parameters

July 19, 2008, at 08:06 PM by 81.180.102.217 -
Changed lines 391-392 from:

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.

to:

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) OpenSIPS to send requests to destination known as failed. So, the blacklist can be used as a memory for the DNS resolver.

Changed line 547 from:

If OpenSER logs to syslog, you can control the facility for logging. Very

to:

If OpenSIPS logs to syslog, you can control the facility for logging. Very

Changed lines 569-571 from:
    log_name="openser-5070"
to:
    log_name="osips-5070"
Changed line 644 from:
    mpath="/usr/local/lib/openser/modules"
to:
    mpath="/usr/local/lib/opensips/modules"
Changed lines 758-759 from:

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.

to:

Lifetime in seconds for TCP sessions. TCP sessions which are inactive for >tcp_connection_lifetime will be closed by OpenSIPS. 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.

Changed lines 836-841 from:
    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>))".

to:
    user="opensips"

user_agent_header

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

Changed line 845 from:

<code>

to:

[@

Changed lines 847-850 from:

</code>

Please note that you have to include the header name "User-Agent:" as OpenSER does not add it and you will get an erroneous header like: <code>

to:

@]

Please note that you have to include the header name "User-Agent:" as OpenSIPS does not add it and you will get an erroneous header like: [@

Changed lines 852-858 from:

</code>

==== wdir ====

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

to:

@]

wdir

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

Changed lines 860-861 from:
     wdir="/usr/local/openser"
to:

[@

     wdir="/usr/local/opensips"
Changed lines 863-866 from:
     wdir=/usr/openser_wd

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

to:
     wdir=/usr/opensips_wd

@]

Core Functions

Changed lines 872-873 from:

==== add_local_rport() ====

to:

add_local_rport()

Changed lines 880-881 from:

==== append_branch() ====

to:

append_branch()

Changed line 891 from:

<code>

to:

[@

Changed lines 938-941 from:

</code>

==== break() ====

to:

@]

break()

Changed lines 946-947 from:

==== drop() ====

to:

drop()

Changed lines 962-963 from:

==== exit() ====

to:

exit()

Changed lines 985-987 from:

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

to:

force_rport()

Force_rport() adds the rport parameter to the first Via header. Thus, OpenSIPS 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.

Changed lines 994-997 from:

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

to:

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

Force OpenSIPS to send the message from the specified socket (it _must_ be one of the sockets OpenSIPS 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.

Changed lines 1003-1004 from:

==== force_tcp_alias() ====

to:

force_tcp_alias()

Changed lines 1015-1016 from:

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

to:

forward(destination)

Changed lines 1029-1030 from:

==== isdsturiset() ====

to:

isdsturiset()

Changed lines 1039-1040 from:

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

to:

isflagset(int)

Changed lines 1051-1052 from:

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

to:

isbflagset([branch_idx,] flag_idx)

Changed lines 1063-1064 from:

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

to:

issflagset(flag_idx)

Changed lines 1075-1076 from:

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

to:

log([level,] string)

Changed lines 1086-1087 from:

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

to:

prefix(string)

Changed lines 1094-1097 from:

==== pv_printf(pv, string) ====

Prints the formatted 'string' in the AVP 'pv'. The 'string' parameter can include any pseudo-variable defined in OpenSER. The 'pv' can be any writable pseudo-variable -- e.g.,: AVPs, VARs, $ru, $rU, $rd, $du, $br, $fs.

to:

pv_printf(pv, string)

Prints the formatted 'string' in the AVP 'pv'. The 'string' parameter can include any pseudo-variable defined in OpenSIPS. The 'pv' can be any writable pseudo-variable -- e.g.,: AVPs, VARs, $ru, $rU, $rd, $du, $br, $fs.

Changed lines 1105-1106 from:

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

to:

return(int)

Changed line 1119 from:

<code>

to:

[@

Changed lines 1127-1128 from:

</code> <code>

to:

@] [@

Changed lines 1138-1141 from:

</code>

==== resetdsturi() ====

to:

@]

resetdsturi()

Changed lines 1148-1149 from:

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

to:

resetflag(int)

Changed lines 1158-1159 from:

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

to:

resetbflag([branch_idx,] flag_idx)

Changed line 1165 from:
to:

[@

Changed lines 1169-1174 from:

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

to:

@]

resetsflag(flag_idx)

Changed lines 1183-1184 from:

==== revert_uri() ====

to:

revert_uri()

Changed lines 1191-1192 from:

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

to:

rewritehost() / sethost()

Changed lines 1199-1200 from:

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

to:

rewritehostport() / sethostport()

Changed lines 1207-1208 from:

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

to:

rewriteuser(string) / setuser(string)

Changed lines 1215-1216 from:

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

to:

rewriteuserpass() / setuserpass()

Changed lines 1223-1224 from:

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

to:

rewriteport() / setport()

Changed lines 1231-1232 from:

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

to:

rewriteuri(str) / seturi(str)

Changed lines 1237-1240 from:
    rewriteuri("sip:test@openser.org");

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

to:
    rewriteuri("sip:test@opensips.org");

send(destination)

Changed lines 1251-1252 from:

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

to:

set_advertised_address(ip|string)

Changed lines 1257-1260 from:
    set_advertised_address("openser.org");

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

to:
    set_advertised_address("opensips.org");

set_advertised_port(int)

Changed lines 1268-1269 from:

==== setdebug([level]) ====

to:

setdebug([level])

Changed lines 1284-1285 from:

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

to:

setdsturi(string)

Changed lines 1292-1293 from:

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

to:

setflag(int)

Changed lines 1303-1304 from:

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

to:

setbflag([branch_idx,] flag_idx)

Changed lines 1318-1319 from:

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

to:

setsflag(flag_idx)

Changed lines 1328-1329 from:

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

to:

strip(int)

Changed lines 1336-1337 from:

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

to:

strip_tail(int)

Deleted lines 1344-1673:

===== Core MI Functions ==

==== debug [level] =====

Gets or sets value of debug core variable.

Examples of usage:

    openserctl fifo debug
    openserctl fifo debug 1

===== 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();
    }

Note that if a 'route(X)' is called from a 'branch_route[Y]' then in 'route[X]' is just processed each separate branch instead of all branches together as occurs in main route.

==== 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_to_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

Prototype:

<code>

    if(expr) {
       actions;
    } else {
       actions;
    }

</code>

The 'expr' should be a valid logical expression.

The logical operators that can be used in 'expr':

  • == - equal
  • != - not equal
  • =~ - regular expression matching
  • !~ - regular expression not-matching
  • > - greater
  • >= - greater or equal
  • < - less
  • <= - less or equal
  • && - logical AND
  • || - logical OR
  • ! - logical NOT
  • [ ... ] - test operator - inside can be any arithmetic expression

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.

==== while ====

while statement

Example of usage:

    $var(i) = 0;
    while($var(i) < 10)
    {
        xlog("counter: $var(i)\n");
        $var(i) = $var(i) + 1;
    }

===== 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 ($var(...)) - to set the value of a script variable
  • shared variables ($shv(...))
  • $ru - to set R-URI
  • $rd - to set domain part of R-URI
  • $rU - to set user part of R-URI
  • $rp - to set the port of R-URI
  • $du - to set dst URI
  • $fs - to set send socket
  • $br - to set branch
  • $mf - to set message flags value
  • $sf - to set script flags value
  • $bf - to set branch flags value

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

There is a special assign operator ':=' (colon equal) that can be used with AVPs. If the right value is 'null', all AVPs with that name are deleted. If different, the new value will overwrite any existing values for the AVPs with than name (on other words, delete existing AVPs with same name, add a new one with the right side value).

<code> $avp(i:3) := 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
  • << : bitwise left shift
  • >> : bitwise right shift

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>

July 19, 2008, at 07:51 PM by 81.180.102.217 -
Changed lines 377-378 from:

==== disable_core_dump ====

to:

disable_core_dump

Changed lines 389-390 from:

==== disable_dns_blacklist ====

to:

disable_dns_blacklist

Changed lines 402-403 from:

==== disable_dns_failover ====

to:

disable_dns_failover

Changed lines 412-413 from:

==== disable_tcp ====

to:

disable_tcp

Changed lines 420-425 from:

==== disable_tls ====

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

==== dns ====

to:

disable_tls

Global parameter to disable TLS support in the SIP server. Default value is 'yes'.

Example of usage:

    disable_tcp=no

dns

Changed lines 434-435 from:

==== dns_retr_time ====

to:

dns_retr_time

Changed lines 443-444 from:

==== dns_retr_no ====

to:

dns_retr_no

Changed lines 452-453 from:

==== dns_servers_no ====

to:

dns_servers_no

Changed lines 461-462 from:

==== dns_try_ipv6 ====

to:

dns_try_ipv6

Changed lines 470-471 from:

==== dns_use_search_list ====

to:

dns_use_search_list

Changed lines 484-485 from:

==== dst_blacklist ====

to:

dst_blacklist

Changed line 492 from:

<code>

to:

[@

Changed lines 501-503 from:

</code>

to:

@]

Changed lines 505-521 from:
     - 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) 

==== fork ====

to:
  • 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)

fork

Changed lines 523-526 from:

==== group gid ====

The group id to run OpenSER.

to:

group gid

The group id to run OpenSIPS.

Changed lines 529-534 from:
  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.

to:
  group="opensips"

listen

Set the network addresses the SIP server should listen to. It can be an IP address, hostname or network interface 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.

Added line 537:

[@

Changed lines 541-545 from:

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. Even if you specify only UDP interfaces here, the server will start the TCP engine too. If you don't want this, you need to disable the TCP support completly with the core parameter disable_tcp.

==== log_facility ====

to:

@]

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. Even if you specify only UDP interfaces here, the server will start the TCP engine too. If you don't want this, you need to disable the TCP support completely with the core parameter disable_tcp.

log_facility

Changed line 548 from:

useful when you want to divert all OpenSER logs to a different log file.

to:

useful when you want to divert all OpenSIPS logs to a different log file.

Changed lines 561-562 from:

==== log_name ====

to:

log_name

Changed line 564 from:

effect only when OpenSER runs in daemon mode (fork=yes), after daemonize.

to:

effect only when OpenSIPS runs in daemon mode (fork=yes), after daemonize.

Changed lines 572-575 from:

==== log_stderror ====

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

to:

log_stderror

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

Changed lines 588-589 from:

==== max_while_loops ====

to:

max_while_loops

Changed lines 596-599 from:

==== maxbuffer ====

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

to:

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.

Changed lines 605-606 from:

==== memlog ====

to:

memlog

Changed lines 613-614 from:

==== mcast_loopback ====

to:

mcast_loopback

Changed lines 621-622 from:

==== mcast_ttl ====

to:

mcast_ttl

Changed lines 629-630 from:

==== mhomed ====

to:

mhomed

Changed lines 637-638 from:

==== mpath ====

to:

mpath

Added line 643:

[@

Changed lines 651-655 from:

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

to:

@]

open_files_limit

If set and bigger than the current open file limit, OpenSIPS will try to increase its open file limit to this number. Note: OpenSIPS must be

Changed lines 665-666 from:

==== port ====

to:

port

Changed lines 673-674 from:

==== reply_to_via ====

to:

reply_to_via

Changed lines 681-684 from:

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

to:

rev_dns

This parameter controls if the SIP server should 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.

Changed lines 688-692 from:

==== 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>))".

to:

server_header

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

Changed line 695 from:

<code>

to:

[@

Changed lines 697-701 from:

</code>

Please note that you have to add the header name "Server:", otherwise OpenSER will just write a header like:

<code>

to:

@]

Please note that you have to add the header name "Server:", otherwise OpenSIPS will just write a header like:

[@

Changed lines 703-707 from:

</code>

==== server_signature ====

to:

@]

server_signature

Changed lines 716-720 from:
     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.

to:
     Server: OpenSIPS (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 OpenSIPS.

Changed lines 727-728 from:

==== tcp_children ====

to:

tcp_children

Changed lines 735-738 from:

==== tcp_accept_aliases ====

==== tcp_send_timeout ====

to:

tcp_accept_aliases

tcp_send_timeout

Changed lines 740-741 from:

for writing in this interval (and OpenSER wants to send something on it).

to:

for writing in this interval (and OpenSIPS wants to send something on it).

Changed lines 746-747 from:

==== tcp_connect_timeout ====

to:

tcp_connect_timeout

Changed lines 756-757 from:

==== tcp_connection_lifetime ====

to:

tcp_connection_lifetime!!!!

Changed lines 764-765 from:

==== tcp_max_connections ====

to:

tcp_max_connections

Changed lines 772-773 from:

==== tcp_poll_method ====

to:

tcp_poll_method

Changed lines 780-829 from:

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

to:

tls_ca_list

tls_certificate

tls_ciphers_list

tls_domain

tls_handshake_timeout

tls_log

tls_method

tls_port_no

tls_private_key

tls_require_certificate

tls_send_timeout

tls_verify

tos

Added line 822:

[@

Changed lines 826-839 from:

==== user uid ====

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

to:

@]

user uid

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

July 19, 2008, at 07:34 PM by 81.180.102.217 -
Changed lines 38-41 from:

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

to:

dst_port

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

Changed lines 47-50 from:

// The code is original copy

==== from_uri ====

to:

from_uri

Changed line 55 from:
    if(is_method("INVITE") && from_uri=~".*@openser.org")
to:
    if(is_method("INVITE") && from_uri=~".*@opensips.org")
Changed line 57 from:
        log("the caller is from openser.org\n");
to:
        log("the caller is from opensips.org\n");
Changed lines 60-61 from:

==== method ====

to:

method

Changed lines 72-73 from:

==== msg:len ====

to:

msg:len

Deleted line 76:
Changed lines 85-88 from:

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

to:

$retcode

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

Changed lines 107-108 from:

==== proto ====

to:

proto

Changed lines 120-123 from:

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

to:

status

If used in onreply_route, this variable is a reference 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.

Changed lines 131-132 from:

==== src_ip ====

to:

src_ip

Changed lines 142-143 from:

==== src_port ====

to:

src_port

Changed lines 154-155 from:

==== to_uri ====

to:

to_uri

Changed line 161 from:
  if(to_uri=~"sip:.+@openser.org")
to:
  if(to_uri=~"sip:.+@opensips.org")
Changed line 163 from:
      log("this is a request for openser.org users\n");
to:
      log("this is a request for opensips.org users\n");
Changed lines 167-169 from:

==== uri ====

to:

uri

Changed line 174 from:
    if(uri=~"sip:.+@openser.org")
to:
    if(uri=~"sip:.+@opensips.org")
Changed line 176 from:
        log("this is a request for openser.org users\n");
to:
        log("this is a request for opensips.org users\n");
Changed lines 185-186 from:

==== INET ====

to:

INET

Changed lines 196-197 from:

==== INET6 ====

to:

INET6

Changed lines 207-208 from:

==== TCP ====

to:

TCP

Changed lines 218-219 from:

==== UDP ====

to:

UDP

Changed lines 229-230 from:

==== max_len ====

to:

max_len

Changed lines 243-246 from:

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

to:

myself

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

Changed lines 257-258 from:

==== null ====

to:

null

Changed lines 266-267 from:

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

to:

Core parameters

Changed lines 273-274 from:

==== advertised_address ====

to:

advertised_address

Changed lines 286-289 from:
    advertised_address="openser.org"

==== advertised_port ====

to:
    advertised_address="opensips.org"

advertised_port

Changed lines 298-299 from:

==== alias ====

to:

alias

Changed lines 302-303 from:

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

to:

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

Changed line 306 from:

<code>

to:

[@

Changed lines 309-312 from:

</code>

==== avp_aliases ====

to:

@]

avp_aliases

Changed line 317 from:

<code>

to:

[@

Changed lines 319-322 from:

</code>

==== auto_aliases ====

to:

@]

auto_aliases

Changed lines 333-334 from:

==== check_via ====

to:

check_via

Changed lines 341-342 from:

==== children ====

to:

children

Changed lines 349-352 from:

==== chroot ====

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

to:

chroot

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

Changed lines 358-361 from:

==== debug ====

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

to:

debug

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

Added line 364:

[@

Changed lines 369-370 from:
to:

@]

Changed lines 375-376 from:

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

to:

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

July 19, 2008, at 07:24 PM by 81.180.102.217 -
Changed lines 5-10 from:
  1. . [#keywords| Core keywords]
  2. . [#parameters| Core parameters]
  3. . [#functions | Core functions]

[#keywords]

to:
Changed lines 174-175 from:

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

to:

Core Values

July 19, 2008, at 07:23 PM by 81.180.102.217 -
Added lines 1-1675:

OpenSIPS Core CookBook

This section lists the all the parameters and functions exported by OpenSIPS core for script usage (to be used in opensips.cfg)

  1. . [#keywords| Core keywords]
  2. . [#parameters| Core parameters]
  3. . [#functions | Core functions]

[#keywords]

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");
   };

// The code is original copy

==== 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. Accepted values are, depending on the actual parameters strings, numbers and yes/ no. If you need to specify either "yes" or "no" as part of a string, wrap this in double quotes.

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

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 reverse DNS lookup on the listen IP.

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

Value of 'debug' parameter can also be get and set dynamically using 'debug' Core MI function.

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 is disabled (Default value is 'yes').

Example of usage:

    disable_dns_blacklist=no

==== 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 'no'.

Example of usage:

    dns_try_ipv6=yes

==== 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) 

==== 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. First interface is used for listening to.

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. Even if you specify only UDP interfaces here, the server will start the TCP engine too. If you don't want this, you need to disable the TCP support completly with the core parameter disable_tcp.

==== 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 the man page syslog(3) for more details.

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

Default value is LOG_DAEMON.

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

==== max_while_loops ====

The parameters set the value of maximum loops that can be done within a "while". Comes as a protection to avoid infinite loops in config file execution. Default is 100.

Example of usage:

    max_while_loops=200

==== maxbuffer ====

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

Example of usage:

    maxbuffer=65536

==== memlog ====

Log level to print memory debug info. It has be less than the value of 'debug' parameter if you want memory info to be logged. Default: memlog=L_DBG (4)

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:

<code> server_header="Server: My Company SIP Proxy" </code>

Please note that you have to add the header name "Server:", otherwise OpenSER will just write a header like:

<code> My Company SIP Proxy </code>

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

==== 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:

<code> user_agent_header="User-Agent: My Company SIP Proxy" </code>

Please note that you have to include the header name "User-Agent:" as OpenSER does not add it and you will get an erroneous header like: <code> My Company SIP Proxy </code>

==== 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() ====

Similarly to t_fork_to, it extends destination set by a new entry. The difference is that current URI is taken as new entry.

Without parameter, the function copies the current URI into a new branch. Thus, leaving the main branch (the URI) for further manipulation.

With a parameter, the function copies the URI in the parameter into a new branch. Thus, the current URI is not manipulated.

Note that it's not possible to append a new branch in "on_failure_route" block if a 6XX response has been previously received (it would be against RFC 3261).

Example of usage: <code>

    # if someone calls B, the call should be forwarded to C too.
    #
    if (method=="INVITE" && uri=~"sip:B@xx.xxx.xx ")
    {
        # copy the current branch (branches[0]) into
        # a new branch (branches[1])
        append_branch();
        # all URI manipulation functions work on branches[0]
        # thus, URI manipulation does not touch the 
        # appended branch (branches[1])
        seturi("sip:C@domain");

        # now: branch 0 = C@domain
        #      branch 1 = B@xx.xx.xx.xx

        # and if you need a third destination ...

        # copy the current branch (branches[0]) into
        # a new branch (branches[2])
        append_branch();

        # all URI manipulation functions work on branches[0]
        # thus, URI manipulation does not touch the 
        # appended branch (branches[1-2])
        seturi("sip:D@domain");

        # now: branch 0 = D@domain
        #      branch 1 = B@xx.xx.xx.xx
        #      branch 2 = C@domain

        t_relay();
        exit;
    };

    # You could also use append_branch("sip:C@domain") which adds a branch with the new URI:


    if(method=="INVITE" && uri=~"sip:B@xx.xxx.xx ") {
        # append a new branch with the second destionation
        append_branch("sip:user@domain");
        # now: branch 0 = B@xx.xx.xx.xx
        # now: branch 1 = C@domain

        t_relay();
        exit;

} </code>

==== 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 in stateless mode. 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");

==== pv_printf(pv, string) ====

Prints the formatted 'string' in the AVP 'pv'. The 'string' parameter can include any pseudo-variable defined in OpenSER. The 'pv' can be any writable pseudo-variable -- e.g.,: AVPs, VARs, $ru, $rU, $rd, $du, $br, $fs.

It was extended from the avp_printf(...) function exported in previous versions by the avpops module. Starting with 1.3.0, avp_printf(...) is just an alias to pv_printf(...).

Example of usage:

    pv_printf("$var(x)", "r-uri: $ru");
    pv_printf("$avp(i:3)", "from uri: $fu");

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

return(0) is same as exit()?;

In bool expressions:

  * Negative and ZERO is FALSE
  * Positive is TRUE

Example usage:

<code> route {

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

} </code> <code> route[2] {

  if (is_method("INVITE")) {
    return(1);
  } else if (is_method("REGISTER")) {
    return(-1);
  } else {
    return(0);
  };

} </code>

==== 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 in stateless mode. 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).

Parameter 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);

==== setdebug([level]) ====

Changes the debug level of the current process from script. If called without the parameter then the debug level of the current process will be reset to the global level. If the debug level of the current process is changed then changing the global debug level (using MI function) does not affect it, so be careful and make sure to reset the process debug level when you are done. This function is very helpful if you are tracing and debugging only a specific piece of code.

Example of usage:

    debug= -1 # errors only
    .....
    {
      ......
      setdebug(4); # set the debug level of the current process to DBG
      uac_replace_from(....);
      setdebug(); # reset the debug level of the current process to the global level
      .......
    }

==== 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);

===== Core MI Functions ==

==== debug [level] =====

Gets or sets value of debug core variable.

Examples of usage:

    openserctl fifo debug
    openserctl fifo debug 1

===== 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();
    }

Note that if a 'route(X)' is called from a 'branch_route[Y]' then in 'route[X]' is just processed each separate branch instead of all branches together as occurs in main route.

==== 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_to_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

Prototype:

<code>

    if(expr) {
       actions;
    } else {
       actions;
    }

</code>

The 'expr' should be a valid logical expression.

The logical operators that can be used in 'expr':

  • == - equal
  • != - not equal
  • =~ - regular expression matching
  • !~ - regular expression not-matching
  • > - greater
  • >= - greater or equal
  • < - less
  • <= - less or equal
  • && - logical AND
  • || - logical OR
  • ! - logical NOT
  • [ ... ] - test operator - inside can be any arithmetic expression

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.

==== while ====

while statement

Example of usage:

    $var(i) = 0;
    while($var(i) < 10)
    {
        xlog("counter: $var(i)\n");
        $var(i) = $var(i) + 1;
    }

===== 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 ($var(...)) - to set the value of a script variable
  • shared variables ($shv(...))
  • $ru - to set R-URI
  • $rd - to set domain part of R-URI
  • $rU - to set user part of R-URI
  • $rp - to set the port of R-URI
  • $du - to set dst URI
  • $fs - to set send socket
  • $br - to set branch
  • $mf - to set message flags value
  • $sf - to set script flags value
  • $bf - to set branch flags value

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

There is a special assign operator ':=' (colon equal) that can be used with AVPs. If the right value is 'null', all AVPs with that name are deleted. If different, the new value will overwrite any existing values for the AVPs with than name (on other words, delete existing AVPs with same name, add a new one with the right side value).

<code> $avp(i:3) := 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
  • << : bitwise left shift
  • >> : bitwise right shift

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>


Page last modified on April 24, 2013, at 06:27 PM