# &adminguide;

## Overview

This module provides reimplementation of a few very old functions that used to be in the core and supported only static string or integer parameters. The new versions bring support for dynamic parameters (allowing variables inside the parameters).

There are also brand new features, related to core internals, but controlled from configuration file or via control interfaces.

Contributions to this module must be done under the BSD license, to follow the requirements of the core contributions.

This module now also provides access to network input / output (nio) data through event_route[network:msg]. The raw data received from a remote host or about to be sent to a remote host is available in variable $mb. The script writer may manipulate this data and save the final result in an AVP defined by msg_avp module parameter. The content of this AVP will then be processed by SIP worker as normal, i.e. a received message will be parsed and sent to appropriate route block while a sent message is forwarded to remote host.

## Dependencies

### &kamailio; Modules

The following modules must be loaded before this module:

- None.

### External Libraries or Applications

The following libraries or applications must be installed before running &kamailio; with this module loaded:

- None

## Parameters

### `alias_subdomains` (string)

Register a domain and all its sub-domains to match the myself condition. It can be set many times. Its full format is: 'proto:domain:port', allowing to set restrictions on protocol and port as well. Protocol and port are optional.

Default value is NULL.

#### Set `alias_subdomains` parameter

    ...
    modparam("corex", "alias_subdomains", "kamailio.org")
    modparam("corex", "alias_subdomains", "udp:sip-router.org:5060")
    ...

### `dns_cache` (string)

Add A or AAAA records to internal DNS cache at startup. It can be set many times to add more than one record.

The format of the value follows the SIP params style: "attr1=val1;attr2=val2;...". The attributes can be:

- type - it can be "A" (IPv4), "AAAA" (IPv6) or "SRV"

- name - the domain name

- addr - the IP address

- ttl - TTL value

- priority - priority value for SRV record

- weight - weight value for SRV record

- port - port value for SRV record

- flags - can be: 1 - the domain is unresolvable (like blocklisted); 2 - the record is permanent (never times out, never deleted, never overwritten)

Default value is NULL.

#### Set `dns_cache` parameter

    ...
    modparam("corex", "dns_cache", "type=A;name=kamailio.org;addr=193.22.119.66;ttl=3600000;flags=0")
    modparam("corex", "dns_cache", "type=AAAA;name=kamailio.org;addr=2a00:d60:0:400::2;ttl=3600000;flags=0")
    ...

### `dns_file` (string)

Path to the file from where to load dns_cache records. It can be set many times to add more than one file.

Inside the file, the dns_cache record has to be in a single line, with the format of the dns_cache module parameter (see above). Empty lines or lines with whitespaces only are ignored. Comment lines have to start with '#'. Comments are not accepted after dns_cache records, only on separate lines.

Default value is NULL.

#### Set `dns_file` parameter

    ...
    # content of /etc/kamailio/kamailio-cache.dns

    # IPv4 record
    type=A;name=kamailio.org;addr=193.22.119.66;ttl=3600000;flags=0
    # IPv6 record
    type=AAAA;name=kamailio.org;addr=2a00:d60:0:400::2;ttl=3600000;flags=0
    ...
    ...
    modparam("corex", "dns_file", "/etc/kamailio/kamailio-cache.dns")
    ...

### `evcb_reply_out` (string)

Name of KEMI callback function to be executed instead of event_route[corex:reply-out].

Default value is NULL.

#### Set `evcb_reply_out` parameter

    ...
    modparam("corex", "evcb_reply_out", "ksr_corex_reply_out")
    ...

### `nio_intercept` (int)

If set to non-zero then raw data received from a remote host or about to be sent to a remote host is made available in event_route[network:msg]. The script writer may modify this and save to msg_avp, which will then be processed by SIP worker as normal.

Default value is 0, i.e. do not allow access to network io data.

#### Set `nio_intercept` parameter

    ...
    modparam("corex", "nio_intercept", 1)
    ...

### `nio_min_msg_len` (int)

Minimum content length of the packet to execute the event_route[network:msg]. This only works if nio_intercept parameter is set to non-zero.

Default value is 0.

#### Set `nio_min_msg_len` parameter

    ...
    modparam("corex", "nio_min_msg_len", 32)
    ...

### `nio_msg_avp` (string)

AVP name to store modified content to be set in the packet. If not set in event_route[network:msg], then all changes are lost and original contents are used. This only works if nio_intercept parameter is to set non-zero.

Default value is empty.

#### Set `nio_msg_avp` parameter

    ...
    modparam("corex", "nio_msg_avp", "$avp(msg)")
    ...

## Functions

### `append_branch([ uri, [ q ] ])`

Append a new branch to the destination set, useful to build the set of destination addresses for parallel forking or redirect replies.

Both parameters are optional, If no uri parameter is provided, then the address from request URI (r-uri) is used to build the new branch.

Meaning of the parameters is as follows:

- uri - SIP address of the branch to be used as R-URI in the outgoing request.

- q - the Q value to set the priority of the branch based on Contact address specifications

This function can be used from REQUEST_ROUTE or FAILURE_ROUTE.

#### `append_branch` usage

    ...
        append_branch();
        append_branch("$avp(uri)", "0.5");
    ...

### `send_udp([ host [ :port ] ])`

Send the original SIP message to a specific destination in stateless mode. No changes are applied to received message, no Via header is added. Host can be an IP address or hostname. Port is optional and defaults to 5060. Used protocol: UDP.

The parameter is optional and defaults to the destination URI from the SIP message if left out. Otherwise it's a string parameter (supporting pseudo-variables) in format "hostname" or "hostname:port", where hostname" can also be a numeric IP address.

This function can be used from REQUEST_ROUTE or FAILURE_ROUTE.

#### `send_udp` usage

    ...
    	send_udp();
    	send_udp("10.20.15.10");
    	send_udp("sip.example.com:5070");
    	send_udp("$var(res)");
    ...

### `send_tcp([ host [ :port ] ])`

This function is identical to send_udp() described above, except that it sends the SIP message using the TCP protocol instead of UDP.

#### `send_tcp` usage

    ...
    	send_tcp();
    	send_tcp("10.20.15.10");
    	send_tcp("sip.example.com:5070");
    	send_tcp("$var(res)");
    ...

### `send_data(uri, data)`

Send the data to address specified by uri. Both parameters can contain pseudo-variables. The uri parameter has to be a valid SIP URI. The data parameter can by any arbitrary content.

This function can be used from ANY_ROUTE.

#### `send_data` usage

    ...
    	send_data("sip:example.com:5070;transport=sctp", "Message at $Ts");
    ...

### `sendx(uri, sock, data)`

Send the data to address specified by uri using a specific local socket. All parameters can contain pseudo-variables. The uri parameter has to be a valid SIP URI. The sock parameter has to be a valid socket specifier (like values assigned to $fs). The data parameter can by any arbitrary content.

This function can be used from ANY_ROUTE.

#### `sendx` usage

    ...
    sendx("sip:example.com:5070;transport=sctp", "sctp:2.3.4.5:5060", "Message at $Ts");
    ...

### `is_incoming()`

Returns true if contents of message buffer $mb are the data received from remote host, otherwise false indicating that the contents of $mb are data that is about to be sent out to remote host. This only works if nio_intercept parameter is set to non-zero.

This function can be used from event_route[network:msg].

#### `is_incoming` usage

    ...
    event_route[network:msg] {
        if (is_incoming()) {
            xlog("L_INFO", "Received message '$mb' \n");
            $avp(msg) = $mb;
        } else {
            xlog("L_INFO", "Sending message '$mb' \n");
            $avp(msg) = $mb;
        };
    }
    ...

### `msg_iflag_set(flagname)`

Set internal SIP message flag. The parameter flagname can be: USE_UAC_FROM, USE_UAC_TO, UAC_AUTH, MSG_APPLY_CHANGES or a number from 0 to 64 (the meaning of each value can be found in source code).

This functions should not be used in configuration file for (re)setting the internal flags, those are done by various functions internally, however, in very particular cases they might be useful (e.g., changing From/To via textops functions, or during testing of C code development).

This function can be used from ANY_ROUTE.

#### `msg_iflag_set` usage

    ...
        msg_iflag_set("UAC_AUTH");
    ...

### `msg_iflag_reset(flagname)`

Reset the internal flag given as parameter.

This function can be used from ANY_ROUTE.

#### `msg_iflag_reset` usage

    ...
        msg_iflag_reset("UAC_AUTH");
    ...

### `msg_iflag_is_set(flagname)`

Test if the internal flag given as parameter is set.

This function can be used from ANY_ROUTE.

#### `msg_iflag_is_set` usage

    ...
        if(msg_iflag_is_set("UAC_AUTH")) { ... }
    ...

### `file_read(fpath, var)`

Read content of a text file into a variable.

This function can be used from ANY_ROUTE.

#### `file_read` usage

    ...
    if(file_read("/tmp/data.txt", "$var(data)")) { ... }
    ...

### `file_write(fpath, content)`

Write content of parameter to a text file.

This function can be used from ANY_ROUTE.

#### `file_write` usage

    ...
    if(file_write("/tmp/data.txt", "Data is: $var(data)")) { ... }
    ...

### `setxflag(flag)`

Set the extended message (transaction) flag.

Meaning of the parameters is as follows:

- flag - the index of the flag to be set. Can be integer or pseudo-variable with integer value (range 0-63).

This function can be used from ANY_ROUTE.

#### `setxflag` usage

    ...
    setxflag("1");
    ...
    $var(flag) = 11;
    setxflag("$var(flag)");
    ...

### `isxflagset(flag)`

Return true if the extended message (transaction) flag is set.

Meaning of the parameters is as follows:

- flag - the index of the flag to be tested. Can be integer or pseudo-variable with integer value (range 0-63).

This function can be used from ANY_ROUTE.

#### `isxflagset` usage

    ...
    if(isxflagset("1"))
    {
        ...
    }
    ...

### `resetxflag(flag)`

Reset the extended message (transaction) flag.

Meaning of the parameters is as follows:

- flag - the index of the flag to be reset. Can be integer or pseudo-variable with integer value (range 0-63).

This function can be used from ANY_ROUTE.

#### `resetxflag` usage

    ...
    resetxflag("1");
    ...

### `set_send_socket(saddr)`

Set the socket for sending out.

Meaning of the parameters is as follows:

- saddr - the address of the local socket (listen address). Can be a static string or contain pseudo-variable.

This function can be used from ANY_ROUTE.

#### `set_send_socket` usage

    ...
    set_send_socket("udp:127.0.0.1:5060");
    ...

### `set_send_socket_name(sname)`

Set the socket for sending out.

Meaning of the parameters is as follows:

- sname - the name of the local socket (listen address). Can be a static string or contain pseudo-variable.

This function can be used from ANY_ROUTE.

#### `set_send_socket_name` usage

    ...
    set_send_socket_name("sock1");
    ...

### `set_recv_socket(saddr)`

Switch local socket used for receiving the message.

Meaning of the parameters is as follows:

- saddr - the address of the local socket (listen address). Can be a static string or contain pseudo-variable.

This function can be used from ANY_ROUTE.

#### `set_recv_socket` usage

    ...
    set_recv_socket("udp:127.0.0.1:5060");
    ...

### `set_recv_socket_name(sname)`

Switch local socket used for receiving the message.

Meaning of the parameters is as follows:

- sname - the name of the local socket (listen address). Can be a static string or contain pseudo-variable.

This function can be used from ANY_ROUTE.

#### `set_recv_socket_name` usage

    ...
    set_recv_socket_name("sock1");
    ...

### `set_source_address(saddr)`

Set the source address for the message.

Meaning of the parameters is as follows:

- saddr - the source address in socket format. Can be a static string or contain pseudo-variable.

This function can be used from ANY_ROUTE.

#### `set_source_address` usage

    ...
    set_source_address("udp:127.0.0.1:5080");
    ...

### `via_add_srvid(flags)`

Control if srvid parameter is added or not to local Via. If yes, the value is server_id, added only if it is different than 0.

Meaning of the parameters is as follows:

- flags: 1 - add srvid parameter; 0 - do not add srvid parameter.

This function can be used from ANY_ROUTE.

#### `via_add_srvid` usage

    ...
    via_add_srv("1");
    ...

### `via_add_xavp_params(flags)`

Control if fields of the xavp with the name specified by xavp_via_params global parameter are added or not to local Via.

Meaning of the parameters is as follows:

- flags: 1 - add xavp parameters; 0 - do not add xavp parameters.

This function can be used from ANY_ROUTE.

#### `via_add_xavp_params` usage

    ...
    xavp_via_params="xvia"
    ...
    request_route {
        ...
    	$xavp(xvia=>srvid) = "1";
    	$xavp(xvia[0]=>myval) = "xyz";
        via_add_xavp_params("1");
        ...
    }
    ...

### `via_use_xavp_fields(flags)`

Control if fields of the xavp with the name specified by xavp_via_fields global parameter are used or not to build local Via.

Meaning of the parameters is as follows:

- flags: 1 - use xavp fields; 0 - do not use xavp fields.

This function can be used from ANY_ROUTE.

#### `via_use_xavp_fields` usage

    ...
    xavp_via_fields="mvia"
    ...
    request_route {
        ...
    	$xavp(mvia=>address) = "10.10.10.10";
    	$xavp(mvia[0]=>port) = "5060";
        via_use_xavp_fields("1");
        ...
    }
    ...

### `via_reply_add_xavp_params(flags)`

Control if fields of the xavp with the name specified by xavp_via_reply_params global parameter are added or not to the top Via of replies.

Meaning of the parameters is as follows:

- flags: 1 - add xavp parameters; 0 - do not add xavp parameters.

This function can be used from ANY_ROUTE.

#### `via_reply_add_xavp_params` usage

    ...
    xavp_via_reply_params="xviarpl"
    ...
    request_route {
        ...
    	$xavp(xviarpl=>srvid) = "1";
    	$xavp(xviarpl[0]=>myval) = "xyz";
        via_reply_add_xavp_params("1");
        ...
    }
    ...

### `is_faked_msg()`

Returns 1 (native config true) if the SIP message under processing is the internal faked msg structure. Returns -1 (native config false) if the SIP message under processing is received from the network.

The function should be useful in event route blocks or async route blocks where it can be processed either a message from the network or the internal faked message.

This function can be used in ANY_ROUTE.

#### `is_faked_msg` usage

    ...
    event_route[dispatcher:dst-down] {
        if (is_faked_msg()) {
            xinfo("Running with faked message\n");
        }
    }
    ...

### `is_socket_name(sockname)`

Returns 1 (native config true) if the parameter matches a local socket name, otherwise -1 (native config false). The parameter can contain variables.

This function can be used in ANY_ROUTE.

#### `is_socket_name` usage

    ...
        if (is_socket_name("socktls")) {
            xinfo("matched local socket name\n");
        }
    ...

### `forward_uac()`

Forward received request with a single Via header, the one added by &kamailio;, the other ones being removed. Useful in cases when its reply should not be sent back (e.g., the reply was already sent out from &kamailio;).

This function can be used in REQUEST_ROUTE.

#### `forward_uac` usage

    ...
    request_route {
        ...
        sl_send_reply("200", "OK");
        $du = "sip:mirror.com:5080";
        forward_uac();
        ...
    }
    ...

### `forward_uac_uri(vuri)`

Similar to forward_uac() with the posibility to provide the target address as a SIP URI via the parameter vuri. The parameter vuri can contain variables.

This function can be used in REQUEST_ROUTE.

#### `forward_uac` usage

    ...
    request_route {
        ...
        sl_send_reply("200", "OK");
        forward_uac_uri("sip:mirror.com:5080");
        ...
    }
    ...

### `forward_reply()`

Forward received reply on demand.

This function can be used in CORE_ONREPLY_ROUTE.

#### `forward_reply` usage

    ...
    route[reply] {
        forward_reply();
    }
    ...

### `msg_vbflag_set(flag)`

Set the via-body flag.

Meaning of the parameters is as follows:

- flag - the index of the flag to be set. Can be integer or pseudo-variable with integer value (range 0-31).

This function can be used from ANY_ROUTE.

#### `msg_vbflag_set` usage

    ...
    msg_vbflag_set("1");
    ...
    $var(flag) = 11;
    msg_vbflag_set("$var(flag)");
    ...

### `msg_vbflag_is_set(flag)`

Return true if the via-body flag is set.

Meaning of the parameters is as follows:

- flag - the index of the flag to be tested. Can be integer or pseudo-variable with integer value (range 0-31).

This function can be used from ANY_ROUTE.

#### `msg_vbflag_is_set` usage

    ...
    if(msg_vbflag_is_set("1"))
    {
        ...
    }
    ...

### `msg_vbflag_reset(flag)`

Reset the via-body flag.

Meaning of the parameters is as follows:

- flag - the index of the flag to be reset. Can be integer or pseudo-variable with integer value (range 0-31).

This function can be used from ANY_ROUTE.

#### `msg_vbflag_reset` usage

    ...
    msg_vbflag_reset("1");
    ...

### `add_tcp_alias(port)`

Add an alias to the TCP connection with the port parameter. If the port is 0, then the port of the first Via-header is used. The parameter can also be a variable holding an integer port value.

This function can be used from ANY_ROUTE.

#### `add_tcp_alias` usage

    ...
        add_tcp_alias("5062");
    ...
        add_tcp_alias("$sp");
    ...

## RPC Commands

### `corex.debug`

Set or get the global log level (the value for global parameter 'debug'). To set the debug, provide an integer parameter. If no parameter is provided, then the current value is returned.

Example:

    		&kamctl; rpc corex.debug
    		&kamctl; rpc corex.debug 2

### `corex.list_sockets`

Print the list of sockets the application is listening on.

Example:

    		&sercmd; corex.list_sockets

### `corex.list_aliases`

Print the list of hostname aliases used to match the myself condition.

Example:

    		&sercmd; corex.list_aliases

### `corex.shm_status`

Trigger shm status dump to syslog.

Example:

    		&sercmd; corex.shm_status

### `corex.shm_summary`

Trigger shm summary dump to syslog.

Example:

    		&sercmd; corex.shm_summary

### `corex.pkg_summary`

Trigger pkg summary dump to syslog for a specific pid or process index. It has two parameters: first to specify what matching type is desired (can be 'pid' or 'idx'); second to specify the value for desired match.

The dump is happening when the selected process is doing a runtime handling (e.g., processing a sip message).

Example:

    		&sercmd; corex.pkg_summary pid 2345
    		&sercmd; corex.pkg_summary idx 1

### `corex.shm.info`

Return shared memory manager details.

Example:

    		&kamcli; rpc shm.info

### `corex.shm.report`

Return shared memory manager usage report.

Example:

    		&kamcli; rpc shm.report

### `corex.shm.stats`

Return shared memory statistics (values are in bytes).

Example:

    		&kamcli; rpc shm.stats

### `corex.shm.rprint`

Shared memory usage status report printed to file upon filter match with the file of allocation.

It takes two parameters: the path to file where to write the report; the string to match the allocation file (the match is done as value included in the path fo the allocation file).

Example:

    			&kamcli; rpc shm.rprint /tmp/kamailioshm.txt dns_cache.c

## Event Routes

### `event_route[network:msg]`

Event route block to be executed when new data is received from network or the data that is about to be sent to a remote host by a SIP worker process.

The kamailio script writer can check which type of data triggered this event route using is_incoming method.

After executing of this event route, if msg_avp was defined and set then its value is used for further processing, otherwise, original value of $mb is used. If message was received from remote host, then it is parsed and proceeds to appropriate route. Otherwise if message set to send out, then is sent to remote host per configured SIP timers in config script.

Please note this event route is meant to prepare the message for on-wire communication, e.g. to do custom encryption or decryption, compression/decompression etc. of the message sent to or received from remote host. Therefore, except text operations, no module functions or pseudo variables are available in this event route.

### `event_route[corex:reply-out]`

Event route block to be executed when a SIP reply is sent out.

## Examples of Usage

To use network event_route[network:msg] the remote SIP UA must also implement and understand the encoding / decoding done in this event route. It is up to &kamailio; config script writer to define and implement how encoding and decoding is done. Any language module such as app_perl or app_lua can be called in in event_route[network:msg] to implement desired logic.

The most simple use case is to compress the SIP packet on-wire. As SIP is a text based protocol, so it is highly compressable. Using this module, one can compress entire SIP message, including headers and message body before sending it to remote host using any compression algorithm of choice, thus saving significant bandwidth on mobile data networks.

A useful case is to use this function between SIP edge proxy and SIP application server. The SIP messages received from end-user at SIP edge proxy may be decrypted and sent to SIP application server at remote location unencrypted, where they are processed as normal. One the way back, the messages received from SIP application server at edge proxy can be encrypted before being sent to actual destination. The edge proxy can check whether received message came from end-user or SIP application server by using simple regular expressions.

Another use case is to implement a virtual HTTP tunnel for SIP messages. The SIP client app can convert SIP message to binary e.g. by doing XOR, Base64 etc., then prepend some fake HTTP headers to make it look like an HTTP request before sending it to kamailio over SIP TCP socket. At kamailio, the fake headers are removed and data is decoded back to normal SIP and processed per config script logic. For the data that is to be sent to SIP client app, one can prepend fake HTTP reply headers to encoded data before sending it to client app.

More advance use cases may involve custom encryption algorithms such as ITV encryption algorithm,

For example, the client app running on Android or iPhone, may send device UUID along with ITV key, encrypted using RSA or AES256 with pre-shared secret, as first packet, which is set as cookie by server in e.g. memcache. This cookie is referred by client app in each next packet, so server can retrieve encryption key from cache and use that for decryption. Same can be done for server at client app side, so messages encrypted by server can be decrypted at client app.

Next is a basic usage example where encoding and decoding is done using PERL.

### `event_route[network:msg]` use cases

    ...
    loadmodule "app_perl.so"
    loadmodule "corex.so"
    ...
    # ----- app_perl params -----
    modparam("app_perl", "filename", "/usr/local/etc/kamailio/custom_compress.pl")
    modparam("app_perl", "modpath", "/usr/local/lib64/kamailio/perl")

    # ----- corex params -----
    modparam("corex", "nio_intercept", 32)
    modparam("corex", "nio_min_msg_len", 32)
    modparam("corex", "nio_msg_avp", "$avp(msg)")
    ...
    event_route[network:msg] {
    	if (is_incoming()) {
    		if (perl_exec_simple("do_uncompress", "" + $mb + "")) {
    			xlog("L_INFO", "Received message '$avp(msg)' \n");
    		} else {
    			xlog("L_INFO", "Received message '$mb' \n");
    			$avp(msg) = $mb;
    		};
    	} else {
    		xlog("L_INFO", "Sending message '$mb' \n");
    		if (!perl_exec_simple("do_compress", "" + $mb + "")) {
    			$avp(msg) = $mb;
    		};
    	};
    }
    ...

### Sample PERL code for do_compress and do_uncompress

    ...
    use strict;
    use warnings;
    use IO::Compress::Gzip qw(gzip $GzipError) ;
    use IO::Uncompress::Gunzip qw(gunzip $GunzipError) ;

    sub do_compress() {
    	my $input = shift;
    	my $output;

    	gzip \$input => \$output
    		or eval {
    			Kamailio::log(L_WARN, "GZIP failed: $GzipError\n");
    			$output = $input;
    		};

    	Kamailio::AVP::add("msg", $output);
    }

    sub do_uncompress() {
    	my $input = shift;
    	my $output;

    	gunzip \$input => \$output
    		or eval {
    			Kamailio::log(L_WARN, "GUNZIP failed: $GzipError\n");
    			$output = $input;
    		};

    	Kamailio::AVP::add("msg", $output);
    }
    ...