This shows you the differences between two versions of the page.
Both sides previous revision Previous revision Next revision | Previous revision Next revision Both sides next revision | ||
cookbooks:devel:core [2018/11/23 11:51] miconda |
cookbooks:devel:core [2020/04/09 11:15] miconda [Command Line Parameters] |
||
---|---|---|---|
Line 1: | Line 1: | ||
- | ====== Kamailio SIP Server v5.3.x (devel): Core Cookbook ====== | + | ====== Kamailio SIP Server v5.4.x (devel): Core Cookbook ====== |
===== Overview ===== | ===== Overview ===== | ||
Line 9: | Line 9: | ||
===== Structure ===== | ===== Structure ===== | ||
- | The structure of the kamailio.cfg can be seen as thee parts: | + | The structure of the kamailio.cfg can be seen as three parts: |
* global parameters | * global parameters | ||
Line 47: | Line 47: | ||
</ | </ | ||
+ | Usually setting a parameter is ended by end of line, but it can be also ended with **;** (semicolon). This should be used when the grammar of a parameter allows values on multiple lines (like **listen** or **alias**) and the next line creates a conflict by being swallowed as part of value for previous parameter. | ||
+ | |||
+ | <code c> | ||
+ | alias=" | ||
+ | </ | ||
+ | |||
+ | If you want to use a reserved config keyword as part of a parameter, you need to enclose it in quotes. See the example below for the keyword " | ||
+ | |||
+ | <code c> | ||
+ | listen=tcp: | ||
+ | </ | ||
==== Modules Settings Section ==== | ==== Modules Settings Section ==== | ||
Line 125: | Line 136: | ||
"this is a string value" | "this is a string value" | ||
- | 'this is another string value" | + | 'this is another string value' |
// next is a boolean | // next is a boolean | ||
Line 234: | Line 245: | ||
Available directives: | Available directives: | ||
- | * #!define NAME - define a keyword | + | |
- | * #!define NAME VALUE - define a keyword with value | + | |
- | * #!ifdef NAME - check if a keyword is defined | + | |
- | * #!ifndef - check if a keyword is not defined | + | |
- | * #!else - switch to false branch of ifdef/ | + | |
- | * #!endif - end ifdef/ | + | |
- | * #!trydef - add a define if not already defined | + | |
- | * #!redefine - force redefinition even if already defined | + | |
+ | |||
+ | Predefined keywords: | ||
+ | * **KAMAILIO_X[_Y[_Z]]** - Kamailio versions | ||
+ | * **MOD_X** - when module X has been loaded | ||
+ | See ' | ||
Among benefits: | Among benefits: | ||
Line 370: | Line 386: | ||
Similar to **subst**, but in addition it adds a **#!define ID subst**. | Similar to **subst**, but in addition it adds a **#!define ID subst**. | ||
+ | ==== substdefs ==== | ||
+ | |||
+ | <code c> | ||
+ | #!substdefs "/ | ||
+ | </ | ||
+ | |||
+ | Similar to **subst**, but in addition it adds a **#!define ID " | ||
===== Core Keywords ===== | ===== Core Keywords ===== | ||
- | Keywords specific to SIP messages which can be used mainly in ''' | + | Keywords specific to SIP messages which can be used mainly in '' |
==== af ==== | ==== af ==== | ||
Line 725: | Line 748: | ||
==== auto_bind_ipv6 ==== | ==== auto_bind_ipv6 ==== | ||
- | When turned on, Kamailio will automatically bind to all IPv6 addresses (much like the default behaviour for IPv4). | + | When turned on, Kamailio will automatically bind to all IPv6 addresses (much like the default behaviour for IPv4). Default is 0. |
Example: | Example: | ||
Line 731: | Line 754: | ||
< | < | ||
auto_bind_ipv6=1 | auto_bind_ipv6=1 | ||
+ | </ | ||
+ | |||
+ | ==== bind_ipv6_link_local ==== | ||
+ | |||
+ | If set to 1, try to bind also IPv6 link local addresses by discovering the scope of the interface. This apply for UDP socket for now, to be added for the other protocols. Default is 0. | ||
+ | |||
+ | Example: | ||
+ | |||
+ | < | ||
+ | bind_ipv6_link_local=1 | ||
</ | </ | ||
==== check_via ==== | ==== check_via ==== | ||
Line 855: | Line 888: | ||
==== flags ==== | ==== flags ==== | ||
- | **Alias name: bool** | + | SIP message (transaction) flags can have string names. |
+ | The //name// for flags cannot be used for **branch** or **script flags**(*) | ||
+ | |||
+ | |||
+ | <code c> | ||
+ | ... | ||
+ | flags | ||
+ | FLAG_ONE | ||
+ | FLAG_TWO | ||
+ | ... | ||
+ | </ | ||
+ | |||
+ | (*) The named flags feature was propagated from the source code merge back in 2008 and is not extensively tested. The recommended way of defining flags is using [[cookbooks: | ||
+ | <code c> | ||
+ | #!define FLAG_NAME FLAG_BIT | ||
+ | </ | ||
+ | |||
==== force_rport ==== | ==== force_rport ==== | ||
Line 932: | Line 982: | ||
<code c> | <code c> | ||
kemi.onsend_route_callback=" | kemi.onsend_route_callback=" | ||
+ | </ | ||
+ | |||
+ | ==== kemi.received_route_callback ==== | ||
+ | |||
+ | Set the name of callback function in the KEMI script to be executed as the equivalent of `event_route[core: | ||
+ | |||
+ | Default value: none | ||
+ | |||
+ | Set it to empty string or " | ||
+ | |||
+ | Example: | ||
+ | |||
+ | <code c> | ||
+ | kemi.received_route_callback=" | ||
</ | </ | ||
Line 971: | Line 1035: | ||
==== latency_limit_db ==== | ==== latency_limit_db ==== | ||
- | Limit of latency in ms for db operations. If a db operation executed via DB API v1 takes longer that its value, a message is printed in the logs, showing the first 50 characters of the db query. | + | Limit of latency in us (micro-seconds) |
Line 994: | Line 1058: | ||
==== listen ==== | ==== listen ==== | ||
- | Set the network addresses the SIP server should listen to. It can be an IP address, hostname or network | + | Set the network addresses the SIP server should listen to. It can be an IP address, hostname or network |
Example of usage: | Example of usage: | ||
Line 1009: | Line 1073: | ||
<code c> | <code c> | ||
- | listen=udp: | + | listen=udp: |
</ | </ | ||
Line 1015: | Line 1079: | ||
<code c> | <code c> | ||
- | listen=udp: | + | listen=udp: |
</ | </ | ||
Line 1021: | Line 1085: | ||
A typical use case for advertise address is when running SIP server behind a NAT/ | A typical use case for advertise address is when running SIP server behind a NAT/ | ||
+ | |||
+ | A unique name can be set for sockets to simplify the selection of the socket for sending out. For example, the rr and path modules can use the socket name to advertise it in header URI parameter and use it as a shortcut to select the corresponding socket for routing subsequent requests. | ||
+ | |||
+ | The name has to be provided as a string enclosed in between quotes after the **name** identifier. | ||
+ | |||
+ | <code c> | ||
+ | listen=udp: | ||
+ | listen=udp: | ||
+ | listen=udp: | ||
+ | listen=udp: | ||
+ | ... | ||
+ | $fsn = " | ||
+ | t_relay(); | ||
+ | </ | ||
+ | |||
+ | Note that there is no internal check for uniqueness of the socket names, the admin has to ensure it in order to be sure the desired socket is selected, otherwise the first socket with a matching name is used. | ||
==== loadmodule ==== | ==== loadmodule ==== | ||
Line 1105: | Line 1185: | ||
==== log_prefix ==== | ==== log_prefix ==== | ||
- | Specify the text to be prefixed to the log messages printed by Kamailio while processing a SIP message. It can contain script variables that are evaluated at runtime | + | Specify the text to be prefixed to the log messages printed by Kamailio while processing a SIP message |
+ | See [[#log_prefix_mode]] about when/how evaluation is done. | ||
+ | |||
+ | |||
+ | If a log message is printed from a part of the code executed out of routing blocks actions (e.g., can be timer, evapi worker process, ...), there is no log prefix set, because this one requires a valid SIP message structure to work with. | ||
Example - prefix with message type (1 - request, 2 - response), CSeq and Call-ID: | Example - prefix with message type (1 - request, 2 - response), CSeq and Call-ID: | ||
Line 1115: | Line 1199: | ||
==== log_prefix_mode ==== | ==== log_prefix_mode ==== | ||
- | If set to 0 (default), then log_prefix | + | Control if [[# |
+ | |||
+ | If set to 0 (default), then log prefix | ||
- | If set to 1, then the log prefix is evaluated before/ | + | If set to 1, then the log prefix is evaluated before/ |
Example: | Example: | ||
Line 1263: | Line 1349: | ||
It can be set via config reload framework. | It can be set via config reload framework. | ||
- | Default is 0 (disabled). | + | Default is 1 (enabled). |
<code c> | <code c> | ||
Line 1386: | Line 1472: | ||
==== pv_buffer_size ==== | ==== pv_buffer_size ==== | ||
- | The size in bytes of internal buffer to print dynamic strings with pseudo-variables inside. The default value is 8192 (8kB). | + | The size in bytes of internal buffer to print dynamic strings with pseudo-variables inside. The default value is 8192 (8kB). Please keep in mind that for xlog messages, there is a dedicated module parameter to set the internal buffer size. |
Example of usage: | Example of usage: | ||
Line 1402: | Line 1488: | ||
< | < | ||
pv_buffer_slots=12 | pv_buffer_slots=12 | ||
+ | </ | ||
+ | |||
+ | ==== pv_cache_limit ==== | ||
+ | |||
+ | The limit how many pv declarations in the cache after which an action is taken. Default value is 2048. | ||
+ | |||
+ | < | ||
+ | pv_cache_limit=1024 | ||
+ | </ | ||
+ | |||
+ | ==== pv_cache_action ==== | ||
+ | |||
+ | Specify what action to be done when the size of pv cache is exceeded. If 0, print an warning log message when the limit is exceeded. If 1, warning log messages is printed and the cache systems tries to drop a $sht(...) declaration. Default is 0. | ||
+ | |||
+ | < | ||
+ | pv_cache_action=1 | ||
</ | </ | ||
Line 1416: | Line 1518: | ||
< | < | ||
rundir="/ | rundir="/ | ||
+ | </ | ||
+ | |||
+ | ==== received_route_mode ==== | ||
+ | |||
+ | Enable or disable the execution of event_route[core: | ||
+ | |||
+ | Default value: 0 (disabled) | ||
+ | |||
+ | Example of usage: | ||
+ | |||
+ | <code c> | ||
+ | received_route_mode=1 | ||
</ | </ | ||
Line 1425: | Line 1539: | ||
reply_to_via=0 | reply_to_via=0 | ||
+ | | ||
+ | |||
+ | ==== route_locks_size ==== | ||
+ | |||
+ | Set the number of mutex locks to be used for synchronizing the execution of messages sharing the same Call-Id. In other words, enables Kamailio to execute the config script sequentially for the requests and replies received within the same dialog -- a new message received within the same dialog waits until the previous one is routed out. | ||
+ | |||
+ | For smaller impact on parallel processing, its value it should be at least twice the number of Kamailio processes (all children processes). | ||
+ | |||
+ | Example: | ||
+ | |||
+ | <code c> | ||
+ | route_locks_size = 256 | ||
+ | </ | ||
+ | |||
+ | Note that ordering of the SIP messages can still be changed by network transmission (quite likely for UDP, especially on long distance paths) or CPU allocation for processes when executing pre-config and post-config tasks (very low chance, but not to be ruled out completely). | ||
==== server_id ==== | ==== server_id ==== | ||
Line 1468: | Line 1597: | ||
==== sip_warning (noisy feedback) ==== | ==== sip_warning (noisy feedback) ==== | ||
- | Can be 0 or 1. If set to 1 (default value) a ' | + | Can be 0 or 1. If set to 1 (default value is 0) a ' |
The header contains several details that help troubleshooting using the network traffic dumps, but might reveal details of your network infrastructure and internal SIP routing. | The header contains several details that help troubleshooting using the network traffic dumps, but might reveal details of your network infrastructure and internal SIP routing. | ||
Line 1582: | Line 1711: | ||
udp_mtu_try_proto = TCP|TLS|SCTP|UDP | udp_mtu_try_proto = TCP|TLS|SCTP|UDP | ||
+ | |||
+ | |||
+ | ==== uri_host_extra_chars ==== | ||
+ | |||
+ | Specify additional chars that should be allowed in the host part of URI. | ||
+ | |||
+ | <code c> | ||
+ | uri_host_extra_chars = " | ||
+ | </ | ||
==== user ==== | ==== user ==== | ||
Line 1886: | Line 2024: | ||
| | ||
+ | |||
+ | ==== tcp_accept_haproxy ==== | ||
+ | Enable the internal TCP stack to expect a PROXY-protocol-formatted header as the first message of the connection. Both the human-readable (v1) and binary-encoded (v2) variants of the protocol are supported. This option is typically useful if you are behind a TCP load-balancer, | ||
+ | |||
+ | Please note that enabling this option will reject any inbound TCP connection that does not conform to the PROXY-protocol spec. | ||
+ | |||
+ | For reference: A PROXY protocol - https:// | ||
+ | |||
+ | Default value is **no**. | ||
+ | |||
+ | <code c> | ||
+ | tcp_accept_haproxy=yes | ||
+ | </ | ||
==== tcp_accept_hep3 ==== | ==== tcp_accept_hep3 ==== | ||
Line 1908: | Line 2059: | ||
</ | </ | ||
+ | ==== tcp_accept_unique ==== | ||
+ | |||
+ | If set to 1, reject duplicate connections coming from same source IP and port. | ||
+ | |||
+ | Default set to 0. | ||
+ | |||
+ | <code c> | ||
+ | tcp_accept_unique = 1 | ||
+ | </ | ||
==== tcp_async ==== | ==== tcp_async ==== | ||
Line 1946: | Line 2106: | ||
tcp_connection_lifetime=3605 | tcp_connection_lifetime=3605 | ||
+ | ==== tcp_connection_match ==== | ||
+ | |||
+ | If set to 1, try to be more strict in matching outbound TCP connections, | ||
+ | |||
+ | Default is 0. | ||
+ | |||
+ | <code c> | ||
+ | tcp_connection_match=1 | ||
+ | </ | ||
==== tcp_connect_timeout ==== | ==== tcp_connect_timeout ==== | ||
Line 2485: | Line 2654: | ||
Force to send the message from the specified socket (it _must_ be one of the sockets specified with the " | Force to send the message from the specified socket (it _must_ be one of the sockets specified with the " | ||
+ | |||
+ | This function does not support pseudo-variables, | ||
Example of usage: | Example of usage: | ||
Line 2841: | Line 3012: | ||
Add " | Add " | ||
+ | |||
===== Custom Global Parameters ===== | ===== Custom Global Parameters ===== | ||
Line 2851: | Line 3023: | ||
</ | </ | ||
+ | |||
+ | The value can be a quoted string or integer number. | ||
Example: | Example: | ||
Line 3037: | Line 3211: | ||
<code c> | <code c> | ||
reply_route { | reply_route { | ||
- | if(status==" | + | if(status==" |
drop; | drop; | ||
} | } | ||
Line 3048: | Line 3222: | ||
- | SIP reply routing block executed by **tm** module. It contains a set of actions to be taken for SIP replies in the contect of an active transaction.. | + | SIP reply routing block executed by **tm** module. It contains a set of actions to be taken for SIP replies in the contect of an active transaction. |
The ' | The ' | ||
- | Main 'onreply_route' block is executed before a possible tm ' | + | Core 'reply_route' block is executed before a possible |
<code c> | <code c> | ||
Line 3079: | Line 3253: | ||
The route is executed in when a SIP request is sent out. Only a limited number of commands are allowed (drop, if + all the checks, msg flag manipulations, | The route is executed in when a SIP request is sent out. Only a limited number of commands are allowed (drop, if + all the checks, msg flag manipulations, | ||
- | In this route the final destination of the message is available | + | In this route the final destination of the message is available |
This route is executed only when forwarding requests - it is not executed for replies, retransmissions, | This route is executed only when forwarding requests - it is not executed for replies, retransmissions, | ||
Line 3106: | Line 3280: | ||
* groupid - should be the name of the module that triggers the event | * groupid - should be the name of the module that triggers the event | ||
* eventid - some meaningful short text describing the event | * eventid - some meaningful short text describing the event | ||
+ | |||
+ | === Core Event Routes === | ||
Implementations: | Implementations: | ||
Line 3117: | Line 3293: | ||
} | } | ||
</ | </ | ||
+ | |||
+ | * **event_route[core: | ||
+ | * it has to be enabled with received_route_mode global parameter. For usage via Kemi, set kemi.received_route_callback global parameter. | ||
+ | * if drop is executed, the received message is no longer processed | ||
+ | |||
+ | <code c> | ||
+ | event_route[core: | ||
+ | xlog(" | ||
+ | if($rcv(srcip) == " | ||
+ | drop; | ||
+ | } | ||
+ | } | ||
+ | </ | ||
+ | === Module Event Routes === | ||
+ | |||
+ | Here are only a few examples, to see if a module exports event_route blocks and when they are executed, check the readme of the module. | ||
+ | |||
* **event_route[htable: | * **event_route[htable: | ||
Line 3157: | Line 3350: | ||
* **event_route [tm: | * **event_route [tm: | ||
<code c> | <code c> | ||
- | event_route [tm:failure-branch] { # Handle failure response | + | request_route { |
+ | ... | ||
+ | t_on_branch_failure(" | ||
+ | t_relay(); | ||
+ | } | ||
+ | |||
+ | event_route[tm: | ||
xlog(" | xlog(" | ||
if (t_check_status(" | if (t_check_status(" | ||
Line 3166: | Line 3365: | ||
} | } | ||
} | } | ||
+ | |||
</ | </ | ||
Line 3340: | Line 3540: | ||
* ^ : bitwise XOR | * ^ : bitwise XOR | ||
* ~ : bitwise NOT | * ~ : bitwise NOT | ||
- | * << : bitwise left shift | + | * <nowiki><<</ |
- | * >> : bitwise right shift | + | * <nowiki>>></ |
Example: | Example: | ||
Line 3393: | Line 3594: | ||
| | ||
Example: if (defined $v && !strempty($v)) $len=strlen($v); | Example: if (defined $v && !strempty($v)) $len=strlen($v); | ||
+ | |||
+ | ===== Command Line Parameters ===== | ||
+ | |||
+ | Kamailio can be started with a set of command line parameters, providing more flexibility to control what is doing at runtime. Some of them can be quite useful when running on containerised environments. | ||
+ | |||
+ | To see the the available command line parameters, run **kamailio -h**: | ||
+ | |||
+ | < | ||
+ | # kamailio -h | ||
+ | |||
+ | version: kamailio 5.4.0-dev4 (x86_64/ | ||
+ | Usage: kamailio [options] | ||
+ | Options: | ||
+ | -a mode Auto aliases mode: enable with yes or on, | ||
+ | disable with no or off | ||
+ | --alias=val | ||
+ | (like for ' | ||
+ | -A define | ||
+ | -A ' | ||
+ | -b nr Maximum receive buffer size which will not be exceeded by | ||
+ | auto-probing procedure even if OS allows | ||
+ | -c Check configuration file for syntax errors | ||
+ | -d | ||
+ | -D | ||
+ | -D..do not fork (almost) anyway; | ||
+ | -DD..do not daemonize creator; | ||
+ | -DDD..daemonize (default) | ||
+ | -e Log messages printed in terminal colors (requires -E) | ||
+ | -E Log to stderr | ||
+ | -f file Configuration file (default: / | ||
+ | -g gid | ||
+ | -G file Create a pgid file | ||
+ | -h This help message | ||
+ | --help | ||
+ | -I Print more internal compile flags and options | ||
+ | -K Turn on " | ||
+ | -l address | ||
+ | mean listening on more addresses). The address format is | ||
+ | [proto: | ||
+ | where proto=udp|tcp|tls|sctp, | ||
+ | addr_lst= addr|(addr, addr_lst), | ||
+ | addr=host|ip_address|interface_name and | ||
+ | advaddr=addr[: | ||
+ | E.g: -l localhost, -l udp: | ||
+ | -l udp: | ||
+ | -l " | ||
+ | The default behaviour is to listen on all the interfaces. | ||
+ | --loadmodule=name load the module specified by name | ||
+ | --log-engine=log engine name and data | ||
+ | -L path Modules search path (default: / | ||
+ | -m nr Size of shared memory allocated in Megabytes | ||
+ | --modparam=modname: | ||
+ | type has to be ' | ||
+ | example: --modparam=corex: | ||
+ | -M nr Size of private memory allocated, in Megabytes | ||
+ | -n processes Number of child processes to fork per interface | ||
+ | (default: 8) | ||
+ | -N | ||
+ | -O nr Script optimization level (debugging option) | ||
+ | -P file Create a pid file | ||
+ | -Q | ||
+ | -r Use dns to check if is necessary to add a " | ||
+ | field to a via | ||
+ | -R Same as `-r` but use reverse dns; | ||
+ | (to use both use `-rR`) | ||
+ | --server-id=num set the value for server_id | ||
+ | --subst=exp set a subst preprocessor directive | ||
+ | --substdef=exp set a substdef preprocessor directive | ||
+ | --substdefs=exp set a substdefs preprocessor directive | ||
+ | -S | ||
+ | -t dir | ||
+ | -T | ||
+ | -u uid | ||
+ | -v | ||
+ | --version | ||
+ | -V | ||
+ | -x name Specify internal manager for shared memory (shm) | ||
+ | - can be: fm, qm or tlsf | ||
+ | -X name Specify internal manager for private memory (pkg) | ||
+ | - if omitted, the one for shm is used | ||
+ | -Y dir | ||
+ | -w dir | ||
+ | -W type poll method (depending on support in OS, it can be: poll, | ||
+ | epoll_lt, epoll_et, sigio_rt, select, kqueue, /dev/poll) | ||
+ | </ | ||
+ | |||
+ | ==== Log Engine ==== | ||
+ | |||
+ | The **--log-engine** parameter allows to specify what logging engine to be used, which is practically about the format of the log messages. If not set at all, then Kamailio does the classic style of line-based plain text log messages. | ||
+ | |||
+ | The value of this parameter can be **--log-engine=name** or **--log-engine=name: | ||
+ | |||
+ | The name of the log engine can be: | ||
+ | |||
+ | * **json** - write logs in structured JSON format | ||
+ | * the **data** for **json** log engine can be a set of character flags: | ||
+ | * **a** - add log prefix as a special field | ||
+ | * **A** - do not add log prefix | ||
+ | * **c** - add Call-ID (when available) as a dedicated JSON attribute | ||
+ | * **M** - strip EOL (' | ||
+ | * **N** - do not add EOL at the end of JSON document | ||
+ | |||
+ | Example of JSON logs when running Kamailio with **--log-engine=json: | ||
+ | |||
+ | < | ||
+ | { " | ||
+ | |||
+ | { " | ||
+ | |||
+ | </ |