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 [2019/05/16 17:47] miconda [auto_bind_ipv6] |
cookbooks:devel:core [2020/11/26 16:28] miconda [async_workers] |
||
---|---|---|---|
Line 1: | Line 1: | ||
- | ====== | + | ====== Core Cookbook ====== |
+ | Version: Kamailio SIP Server v5.5.x (devel) | ||
===== Overview ===== | ===== Overview ===== | ||
Line 9: | Line 10: | ||
===== 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 136: | Line 137: | ||
"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 253: | Line 254: | ||
* **# | * **# | ||
* **# | * **# | ||
+ | |||
+ | Predefined keywords: | ||
+ | * **KAMAILIO_X[_Y[_Z]]** - Kamailio versions | ||
+ | * **MOD_X** - when module X has been loaded | ||
+ | See ' | ||
Among benefits: | Among benefits: | ||
Line 353: | Line 359: | ||
* text on the same line as the directive will cause problems. Keep the directive lines clean and only comment on a line before or after. | * text on the same line as the directive will cause problems. Keep the directive lines clean and only comment on a line before or after. | ||
+ | ==== defenv ==== | ||
+ | |||
+ | Preprocessor directive to define an ID to the value of an environment variable with the name ENVVAR. | ||
+ | |||
+ | <code c> | ||
+ | #!defenv ID=ENVVAR | ||
+ | </ | ||
+ | |||
+ | It can also be just **$!defenv ENVVAR** and the defined ID is the ENVVAR name. | ||
+ | |||
+ | Example: | ||
+ | |||
+ | <code c> | ||
+ | #!defenv SHELL | ||
+ | </ | ||
+ | |||
+ | If environment variable $SHELL is '/ | ||
+ | |||
+ | <code c> | ||
+ | #!define SHELL /bin/bash | ||
+ | </ | ||
+ | |||
+ | Full expression variant: | ||
+ | |||
+ | <code c> | ||
+ | #!defenv ENVSHELL=SHELL | ||
+ | </ | ||
+ | |||
+ | Then it is like: | ||
+ | |||
+ | <code c> | ||
+ | #!define ENVSHELL /bin/bash | ||
+ | </ | ||
+ | |||
+ | It is a simplified alternative of using **# | ||
+ | | ||
==== subst ==== | ==== subst ==== | ||
Line 722: | Line 764: | ||
==== async_workers ==== | ==== async_workers ==== | ||
- | Specify how many child processes to create for asynchronous execution. These are processes that can receive tasks from various components and execute them locally, which is different process than the task sender. | + | Specify how many child processes to create for asynchronous execution |
Default: 0 (asynchronous framework is disabled). | Default: 0 (asynchronous framework is disabled). | ||
Line 731: | Line 773: | ||
async_workers=4 | async_workers=4 | ||
</ | </ | ||
+ | |||
+ | ==== async_workers_group ==== | ||
+ | |||
+ | Define groups of asynchronous worker processes. | ||
+ | |||
+ | Prototype: | ||
+ | |||
+ | < | ||
+ | async_workers_group=" | ||
+ | </ | ||
+ | |||
+ | The attributes are: | ||
+ | |||
+ | * **name** - the group name (used by functions such as **sworker_task(name)**) | ||
+ | * **workers** - the number of processes to create for this group | ||
+ | * **nonblock** - set or not set the non-block flag for internal communication socket | ||
+ | * **usleep** - the number of microseconds to sleep before trying to receive next task (can be useful if nonblock=1) | ||
+ | |||
+ | Default: "" | ||
+ | |||
+ | Example: | ||
+ | |||
+ | < | ||
+ | async_workers_group=" | ||
+ | </ | ||
+ | |||
+ | If the **name** is default, then it overwrites the value set by **async_workers**. | ||
+ | |||
+ | See also **event_route[core: | ||
==== auto_aliases ==== | ==== auto_aliases ==== | ||
Line 753: | Line 824: | ||
==== bind_ipv6_link_local ==== | ==== bind_ipv6_link_local ==== | ||
- | Try to bind link local IPv6 addresses. Default is 0. | + | If set to 1, try to bind also IPv6 link local addresses |
Example: | Example: | ||
Line 965: | Line 1036: | ||
</ | </ | ||
+ | |||
+ | ==== ipv6_hex_style ==== | ||
+ | |||
+ | Can be set to " | ||
+ | |||
+ | Default is " | ||
+ | |||
+ | " | ||
+ | |||
+ | Example of usage: | ||
+ | |||
+ | <code c> | ||
+ | ipv6_hex_style = " | ||
+ | </ | ||
==== kemi.onsend_route_callback ==== | ==== kemi.onsend_route_callback ==== | ||
Line 1020: | Line 1105: | ||
==== latency_limit_action ==== | ==== latency_limit_action ==== | ||
- | Limit of latency in ms for config actions. If a config action executed by cfg interpreter takes longer than its value, a message is printed in the logs, showing config path, line and action name when it is a module function, as well as internal action id. | + | Limit of latency in us (micro-seconds) |
Default value is 0 (disabled). | Default value is 0 (disabled). | ||
Line 1030: | Line 1115: | ||
==== 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 1053: | Line 1138: | ||
==== 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 1068: | Line 1153: | ||
<code c> | <code c> | ||
- | listen=udp: | + | listen=udp: |
</ | </ | ||
Line 1074: | Line 1159: | ||
<code c> | <code c> | ||
- | listen=udp: | + | listen=udp: |
</ | </ | ||
Line 1080: | Line 1165: | ||
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 1120: | Line 1221: | ||
The proxy tries to find the modules in a smart way, e.g: loadmodule " | The proxy tries to find the modules in a smart way, e.g: loadmodule " | ||
+ | ==== local_rport ==== | ||
+ | |||
+ | Similar to **add_local_rport()** function, but done in a global scope, so the function does not have to be executed for each request. | ||
+ | |||
+ | Default: off | ||
+ | |||
+ | Example: | ||
+ | |||
+ | <code c> | ||
+ | local_rport = on | ||
+ | </ | ||
==== log_engine_data ==== | ==== log_engine_data ==== | ||
Line 1328: | Line 1440: | ||
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 1467: | Line 1579: | ||
< | < | ||
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 1506: | Line 1634: | ||
==== route_locks_size ==== | ==== 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 sequentially 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. | + | Set the number of mutex locks to be used for synchronizing the execution of config script for messages sharing the same Call-Id. In other words, enables Kamailio to execute |
- | For smaller impact on parallel processing, its value it should be at least twice the number of kamailio | + | For smaller impact on parallel processing, its value it should be at least twice the number of Kamailio |
Example: | Example: | ||
Line 1515: | Line 1643: | ||
route_locks_size = 256 | 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 1555: | Line 1685: | ||
shm_mem_size = 64 (default 64) | shm_mem_size = 64 (default 64) | ||
+ | |||
+ | ==== sip_parser_log ==== | ||
+ | |||
+ | Log level for printing debug messages for some of the SIP parsing errors. | ||
+ | |||
+ | Default: 0 (L_WARN) | ||
+ | |||
+ | <code c> | ||
+ | sip_parser_log = 1 | ||
+ | </ | ||
+ | |||
+ | ==== sip_parser_mode ==== | ||
+ | |||
+ | Control sip parser behaviour. | ||
+ | |||
+ | If set to 1, the parser is more strict in accepting messages that have invalid headers (e.g., duplicate To or From). It can make the system safer, but loses the flexibility to be able to fix invalid messages with config operations. | ||
+ | |||
+ | If set to 0, the parser is less strict on checking validity of headers. | ||
+ | |||
+ | Default: 1 | ||
+ | |||
+ | <code c> | ||
+ | sip_parser_mode = 0 | ||
+ | </ | ||
==== 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 1641: | Line 1795: | ||
+ | ==== stats_name_separator ==== | ||
+ | Specify the character used as a separator for the internal statistics' | ||
+ | Default value is " | ||
+ | Example of usage: | ||
+ | |||
+ | stats_name_separator = " | ||
==== tos ==== | ==== tos ==== | ||
Line 1672: | Line 1832: | ||
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 1982: | Line 2151: | ||
Please note that enabling this option will reject any inbound TCP connection that does not conform to the PROXY-protocol spec. | 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**. | Default value is **no**. | ||
Line 2009: | Line 2180: | ||
</ | </ | ||
+ | ==== 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 2047: | Line 2227: | ||
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 2410: | Line 2599: | ||
- | ===== Blacklist | + | ===== Blocklist |
- | ==== dst_blacklist_expire | + | ==== dst_blocklist_expire |
- | **Alias name: dst_blacklist_ttl** | + | **Alias name: dst_blocklist_ttl** |
- | How much time a blacklisted | + | How much time a blocklisted |
- | | + | |
- | ==== dst_blacklist_gc_interval | + | ==== dst_blocklist_gc_interval |
How often the garbage collection will run (eliminating old, expired entries). | How often the garbage collection will run (eliminating old, expired entries). | ||
- | | + | |
- | ==== dst_blacklist_init | + | ==== dst_blocklist_init |
- | If off, the blacklist | + | If off, the blocklist |
- | | + | |
- | ==== dst_blacklist_mem | + | ==== dst_blocklist_mem |
- | Maximum shared memory amount used for keeping the blacklisted | + | Maximum shared memory amount used for keeping the blocklisted |
- | | + | |
- | ==== use_dst_blacklist | + | ==== use_dst_blocklist |
- | Enable the destination | + | Enable the destination |
- | Note: using the blacklist | + | Note: using the blocklist |
- | See also doc/dst_blacklist.txt. | + | See also doc/dst_blocklist.txt. |
- | | + | |
===== Real-Time Parameters ===== | ===== Real-Time Parameters ===== | ||
Line 2586: | Line 2775: | ||
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 2942: | Line 3133: | ||
Add " | Add " | ||
+ | |||
===== Custom Global Parameters ===== | ===== Custom Global Parameters ===== | ||
Line 3523: | Line 3715: | ||
| | ||
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 CLI Parameter ==== | ||
+ | |||
+ | 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 " | ||
+ | |||
+ | < | ||
+ | { " | ||
+ | |||
+ | { " | ||
+ | |||
+ | </ |