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 [2020/11/26 16:28] miconda [async_workers] |
cookbooks:devel:core [2022/01/24 10:05] rhys Added documentation for new virtual listen identifier in 5.6 |
||
---|---|---|---|
Line 1: | Line 1: | ||
====== Core Cookbook ====== | ====== Core Cookbook ====== | ||
- | Version: Kamailio SIP Server v5.5.x (devel) | + | Version: Kamailio SIP Server v5.6.x (devel) |
===== Overview ===== | ===== Overview ===== | ||
Line 394: | Line 395: | ||
It is a simplified alternative of using **# | It is a simplified alternative of using **# | ||
- | | + | |
+ | ==== defenvs ==== | ||
+ | |||
+ | Similar to **# | ||
+ | |||
+ | <code c> | ||
+ | #!defenvs ENVVAR | ||
+ | #!defenvs ID=ENVVAR | ||
+ | </ | ||
==== subst ==== | ==== subst ==== | ||
Line 764: | Line 773: | ||
==== async_workers ==== | ==== async_workers ==== | ||
- | Specify how many child processes to create for asynchronous execution in the group " | + | Specify how many child processes |
Default: 0 (asynchronous framework is disabled). | Default: 0 (asynchronous framework is disabled). | ||
Line 772: | Line 781: | ||
< | < | ||
async_workers=4 | async_workers=4 | ||
+ | </ | ||
+ | |||
+ | ==== async_nonblock ==== | ||
+ | |||
+ | Set the non-block mode for the internal sockets used by default group of async workers. | ||
+ | |||
+ | Default: 0 | ||
+ | |||
+ | Example: | ||
+ | |||
+ | < | ||
+ | async_nonblock=1 | ||
+ | </ | ||
+ | |||
+ | ==== async_usleep ==== | ||
+ | |||
+ | Set the number of microseconds to sleep before trying to receive next task (can be useful when async_nonblock=1). | ||
+ | |||
+ | Default: 0 | ||
+ | |||
+ | Example: | ||
+ | |||
+ | < | ||
+ | async_usleep=100 | ||
</ | </ | ||
Line 1091: | Line 1124: | ||
kemi.onsend_route_callback=" | kemi.onsend_route_callback=" | ||
</ | </ | ||
+ | |||
+ | ==== kemi.pre_routing_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.pre_routing_callback=" | ||
+ | </ | ||
+ | |||
==== latency_cfg_log ==== | ==== latency_cfg_log ==== | ||
Line 1181: | Line 1229: | ||
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. | 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. | ||
+ | |||
+ | As of 5.6, there is now a **virtual** identifier which can be added to the end of teach listen directive. This can be used in combination with any other identifier, but must be added at the end of the line. | ||
+ | |||
+ | <code c> | ||
+ | listen=udp: | ||
+ | listen=udp: | ||
+ | listen=udp: | ||
+ | listen=udp: | ||
+ | </ | ||
+ | |||
+ | The **virtual** identifier is meant for use in situations where you have a floating/ | ||
+ | |||
+ | This identifier will change the behaviour of how " | ||
+ | |||
+ | This means that if Kamailio is listening on an IP that is not currently local, it will recognise that, and can relay the traffic to another Kamailio node as needed, instead of thinking it always needs to handle the traffic. | ||
+ | |||
==== loadmodule ==== | ==== loadmodule ==== | ||
Line 1198: | Line 1262: | ||
loadmodule " | loadmodule " | ||
</ | </ | ||
+ | |||
+ | ==== loadmodulex ==== | ||
+ | |||
+ | Similar to **loadmodule** with the ability to evaluate variables in its parameter. | ||
==== loadpath ==== | ==== loadpath ==== | ||
Line 1334: | Line 1402: | ||
==== maxbuffer ==== | ==== maxbuffer ==== | ||
- | The size in bytes not to be exceeded during the auto-probing procedure of descovering | + | The size in bytes not to be exceeded during the auto-probing procedure of discovering and increasing |
Example of usage: | Example of usage: | ||
Line 1340: | Line 1408: | ||
maxbuffer=65536 | maxbuffer=65536 | ||
+ | Note: it is not the size of the internal SIP message receive buffer. | ||
==== max_branches ==== | ==== max_branches ==== | ||
Line 1517: | Line 1586: | ||
==== modparam ==== | ==== modparam ==== | ||
+ | |||
The modparam command will be used to set the options of the modules. | The modparam command will be used to set the options of the modules. | ||
Line 1526: | Line 1596: | ||
See the documenation of the respective module to find out the available options. | See the documenation of the respective module to find out the available options. | ||
+ | ==== modparamx ==== | ||
+ | |||
+ | Similar to **modparam**, | ||
==== onsend_route_reply ==== | ==== onsend_route_reply ==== | ||
Line 1882: | Line 1955: | ||
| | ||
</ | </ | ||
+ | |||
+ | ==== wait_worker1_mode ==== | ||
+ | |||
+ | Enable waiting for child SIP worker one to complete initialization, | ||
+ | |||
+ | Default: 0 (do not wait for child worker one to complete initialization). | ||
+ | |||
+ | Example: | ||
+ | |||
+ | <code c> | ||
+ | wait_worker1_mode = 1 | ||
+ | </ | ||
+ | |||
+ | ==== wait_worker1_time ==== | ||
+ | |||
+ | How long to wait for child worker one to complete the initialization. In micro-seconds. | ||
+ | |||
+ | Default: 4000000 (micro-seconds = 4 seconds). | ||
+ | |||
+ | Example: | ||
+ | |||
+ | <code c> | ||
+ | wait_worker1_time = 1000000 | ||
+ | </ | ||
+ | |||
+ | ==== wait_worker1_usleep ==== | ||
+ | |||
+ | How long to wait for child worker one to complete the initialization. In micro-seconds. | ||
+ | |||
+ | Default: 100000 (micro-seconds = 0.1 seconds). | ||
+ | |||
+ | Example: | ||
+ | |||
+ | <code c> | ||
+ | wait_worker1_usleep = 50000 | ||
+ | </ | ||
+ | |||
==== workdir ==== | ==== workdir ==== | ||
Line 1929: | Line 2039: | ||
===== DNS Parameters ===== | ===== DNS Parameters ===== | ||
- | Note: See also file doc/dns.txt for details about Kamailio' | + | Note: See also file doc/tutorials/dns.txt for details about Kamailio' |
Kamailio has an internal DNS resolver with caching capabilities. If this caching resolver is activated (default setting) then the system' | Kamailio has an internal DNS resolver with caching capabilities. If this caching resolver is activated (default setting) then the system' | ||
Line 2072: | Line 2182: | ||
**Alias name: dns_srv_loadbalancing** | **Alias name: dns_srv_loadbalancing** | ||
- | Enable dns srv weight based load balancing (see doc/ | + | Enable dns srv weight based load balancing (see doc/tutorials/dns.txt) |
dns_srv_lb = yes | no (default no) | dns_srv_lb = yes | no (default no) | ||
Line 2088: | Line 2198: | ||
==== dns_try_naptr ==== | ==== dns_try_naptr ==== | ||
- | Enable NAPTR support according to RFC 3263 (see doc/dns.txt for more info) | + | Enable NAPTR support according to RFC 3263 (see doc/tutorials/dns.txt for more info) |
| | ||
dns_try_naptr = yes | no (default no) | dns_try_naptr = yes | no (default no) | ||
Line 2099: | Line 2209: | ||
dns_tls_pref=10 and dns_sctp_pref=20. To use the remote site preferences set all dns_*_pref to the same positive value (e.g. dns_udp_pref=1, | dns_tls_pref=10 and dns_sctp_pref=20. To use the remote site preferences set all dns_*_pref to the same positive value (e.g. dns_udp_pref=1, | ||
dns_tcp_pref=1, | dns_tcp_pref=1, | ||
- | preference to -1 (or any other negative number). (see doc/dns.txt for more info) | + | preference to -1 (or any other negative number). (see doc/tutorials/dns.txt for more info) |
dns_{udp, | dns_{udp, | ||
Line 2338: | Line 2448: | ||
tcp_rd_buf_size=65536 | tcp_rd_buf_size=65536 | ||
</ | </ | ||
+ | |||
+ | ==== tcp_reuse_port ==== | ||
+ | |||
+ | Allows reuse of TCP ports. This means,for example, that the same TCP ports on which Kamailio is listening on, can be used as source ports of new TCP connections when acting as an UAC. Kamailio must have been compiled in a system implementing SO_REUSEPORT (Linux > 3.9.0, FreeBSD, OpenBSD, NetBSD, MacOSX). This parameter takes effect only if also the system on which Kamailio is running on supports SO_REUSEPORT. | ||
+ | |||
+ | tcp_reuse_port = yes (default no) | ||
+ | |||
==== tcp_send_timeout ==== | ==== tcp_send_timeout ==== | ||
Line 2354: | Line 2471: | ||
==== tcp_syncnt ==== | ==== tcp_syncnt ==== | ||
+ | |||
Number of SYN retransmissions before aborting a connect attempt (see linux tcp(7) TCP_SYNCNT). Linux only. | Number of SYN retransmissions before aborting a connect attempt (see linux tcp(7) TCP_SYNCNT). Linux only. | ||
tcp_syncnt = number of syn retr. (default not set) | tcp_syncnt = number of syn retr. (default not set) | ||
+ | |||
+ | |||
+ | ==== tcp_wait_data ==== | ||
+ | |||
+ | Specify how long to wait (in milliseconds) to wait for data on tcp connections in certain cases. Now applies when reading on tcp connection for haproxy protocol. | ||
+ | |||
+ | Default: 5000ms (5secs) | ||
+ | |||
+ | <code c> | ||
+ | tcp_wait_data = 10000 | ||
+ | </ | ||
==== tcp_wq_blk_size ==== | ==== tcp_wq_blk_size ==== | ||
Line 2369: | Line 2498: | ||
tcp_wq_max = bytes (default 10 Mb) | tcp_wq_max = bytes (default 10 Mb) | ||
| | ||
- | ==== tcp_reuse_port ==== | ||
- | |||
- | Allows reuse of TCP ports. This means,for example, that the same TCP ports on which Kamailio is listening on, can be used as source ports of new TCP connections when acting as an UAC. Kamailio must have been compiled in a system implementing SO_REUSEPORT (Linux > 3.9.0, FreeBSD, OpenBSD, NetBSD, MacOSX). This parameter takes effect only if also the system on which Kamailio is running on supports SO_REUSEPORT. | ||
- | |||
- | tcp_reuse_port = yes (default no) | ||
===== TLS Parameters ===== | ===== TLS Parameters ===== | ||
Line 2910: | Line 3034: | ||
</ | </ | ||
+ | See also the FAQ for how the function return code is evaluated: | ||
+ | |||
+ | * https:// | ||
==== revert_uri ==== | ==== revert_uri ==== | ||
Line 2997: | Line 3124: | ||
+ | ==== selval ==== | ||
+ | |||
+ | Select a value based on conditional expression. | ||
+ | |||
+ | Prototype: | ||
+ | |||
+ | <code c> | ||
+ | selval(evalexpr, | ||
+ | </ | ||
+ | |||
+ | This is a core statement that return the 2nd parameter if the 1st parameter is evaluated to true, or 3rd parameter if the 1st parameter is evaluated to false. It can be considered a core function that is equivalent of ternary condition/ | ||
+ | |||
+ | Example: | ||
+ | |||
+ | <code c> | ||
+ | $var(x) = selval($Ts mod 2, " | ||
+ | </ | ||
+ | The first parameter is a conditional expression, like those used for IF, the 2nd and 3rd parameters can be expressions like those used in the right side of assignments. | ||
==== set_advertised_address ==== | ==== set_advertised_address ==== | ||
Line 3427: | Line 3572: | ||
} | } | ||
</ | </ | ||
+ | |||
+ | * **event_route[core: | ||
+ | * if drop is used, then the message is not processed further with request_route or reply_route in the same process. This can be useful together with sworker module which can delegate the processing to another worker. | ||
+ | |||
+ | <code c> | ||
+ | async_workers_group=" | ||
+ | ... | ||
+ | event_route[core: | ||
+ | xinfo(" | ||
+ | if(is_method(" | ||
+ | # delegate processing of REGISTERs to a special group of workers | ||
+ | if(sworker_task(" | ||
+ | drop; | ||
+ | } | ||
+ | } | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | * ** event_route[core: | ||
+ | * note that the SIP message is broken in this case, but it gets access to source and local socket addresses (ip, port, proto, af) as well as the whole message buffer and its size | ||
+ | |||
+ | <code c> | ||
+ | event_route[core: | ||
+ | xlog(" | ||
+ | } | ||
+ | |||
+ | </ | ||
+ | |||
=== Module Event Routes === | === Module Event Routes === | ||
Line 3520: | Line 3693: | ||
|| logical OR | || logical OR | ||
! | ! | ||
- | [ ... ] test operator - inside can be any arithmetic expression | ||
</ | </ | ||
Line 3532: | Line 3704: | ||
} | } | ||
+ | See also the FAQ for how the function return code is evaluated: | ||
+ | * https:// | ||
==== switch ==== | ==== switch ==== | ||
Line 3814: | Line 3988: | ||
* **A** - do not add log prefix | * **A** - do not add log prefix | ||
* **c** - add Call-ID (when available) as a dedicated JSON attribute | * **c** - add Call-ID (when available) as a dedicated JSON attribute | ||
+ | * **j** - the log prefix and message fields are printed in JSON structure format, detecting if they are enclosed in between **{ }** or adding them as a **text** field | ||
* **M** - strip EOL (' | * **M** - strip EOL (' | ||
* **N** - do not add EOL at the end of JSON document | * **N** - do not add EOL at the end of JSON document | ||
+ | * **p** - the log prefix is printed as it is in the root json document, it has to start with comma (**,**) and be a valid set of json fields | ||
+ | * **U** - CEE (Common Event Expression) schema format - https:// | ||
Example of JSON logs when running Kamailio with " | Example of JSON logs when running Kamailio with " | ||
Line 3823: | Line 4000: | ||
{ " | { " | ||
+ | </ | ||
+ | Example config for printing log message with **j** flag: | ||
+ | |||
+ | < | ||
+ | xinfo(" | ||
+ | </ | ||
+ | |||
+ | Example config for printing log messages with **p** flag: | ||
+ | |||
+ | < | ||
+ | log_prefix=", | ||
</ | </ |