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 [2015/06/03 13:07] miconda |
cookbooks:devel:core [2021/12/13 14:47] miconda [tcp_rd_buf_size] |
||
---|---|---|---|
Line 1: | Line 1: | ||
- | ====== Kamailio SIP Server | + | ====== |
+ | |||
+ | Version: | ||
+ | |||
+ | ===== Overview | ||
This tutorial collects the functions and parameters exported by Kamailio core to configuration file. | This tutorial collects the functions and parameters exported by Kamailio core to configuration file. | ||
**Note:** The parameters on this page are **NOT** in alphabetical order. | **Note:** The parameters on this page are **NOT** in alphabetical order. | ||
+ | |||
+ | ===== Structure ===== | ||
+ | |||
+ | The structure of the kamailio.cfg can be seen as three parts: | ||
+ | |||
+ | * global parameters | ||
+ | * modules settings | ||
+ | * routing blocks | ||
+ | |||
+ | For clarity and making it easy to maintain, it is recommended to keep them in this order, although some of them can be mixed. | ||
+ | |||
+ | ==== Global Parameters Section ==== | ||
+ | |||
+ | This is the first part of the configuration file, containing the parameters for the core of kamailio and custom global parameters. | ||
+ | |||
+ | Typically this is formed by directives of the form: | ||
+ | |||
+ | < | ||
+ | name=value | ||
+ | </ | ||
+ | |||
+ | The name corresponds to a core parameter as listed in one of the next sections of this document. If a name is not matching a core parameter, then Kamailio will not start, rising an error during startup. | ||
+ | |||
+ | The value is typically an integer, boolean or a string. | ||
+ | |||
+ | Several parameters can get a complex value which is formed from a group of integer, strings or identifiers. For example, such parameter is **listen**, which can be assigned a value like **proto: | ||
+ | |||
+ | Example of content: | ||
+ | |||
+ | <code c> | ||
+ | log_facility=LOG_LOCAL0 | ||
+ | |||
+ | children=4 | ||
+ | |||
+ | disable_tcp=yes | ||
+ | |||
+ | alias=" | ||
+ | |||
+ | listen=udp: | ||
+ | </ | ||
+ | |||
+ | 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 ==== | ||
+ | |||
+ | This is the second section of the configuration file, containing the directives to load modules and set their parameters. | ||
+ | |||
+ | It contains the directives **loadmodule** and **modparam**. In the default configuration file starts with the line setting the path to modules (the assignment to **mpath** core parameter. | ||
+ | |||
+ | Example of content: | ||
+ | |||
+ | <code c> | ||
+ | loadmodule " | ||
+ | ... | ||
+ | modparam(" | ||
+ | </ | ||
+ | |||
+ | ==== Routing Blocks Section ==== | ||
+ | |||
+ | This is the last section of the configuration file, typically the biggest one, containing the routing blocks with the routing logic for SIP traffic handled by Kamailio. | ||
+ | |||
+ | The only mandatory routing block is **request_route**, | ||
+ | |||
+ | See the chapter **Routing Blocks** in this document for more details about what types of routing blocks can be used in the configuration file and their role in routing SIP traffic and Kamailio behaviour. | ||
+ | |||
+ | Example of content: | ||
+ | |||
+ | <code c> | ||
+ | request_route { | ||
+ | |||
+ | # per request initial checks | ||
+ | route(REQINIT); | ||
+ | |||
+ | ... | ||
+ | } | ||
+ | |||
+ | branch_route[MANAGE_BRANCH] { | ||
+ | xdbg(" | ||
+ | route(NATMANAGE); | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | ===== Generic Elements ===== | ||
+ | |||
+ | ==== Comments ==== | ||
+ | |||
+ | Line comments start with **#** (hash/pound character - like in shell) or **/ /** (double forward slash - like in C++/Java). | ||
+ | |||
+ | Block comments start with /* (forward slash and asterisk) and are ended by */ (sterisk and forward slash) (like in C, C++, Java). | ||
+ | |||
+ | Example: | ||
+ | |||
+ | < | ||
+ | # this is a line comment | ||
+ | | ||
+ | // this is another line comment | ||
+ | | ||
+ | /* this | ||
+ | is | ||
+ | a | ||
+ | block | ||
+ | | ||
+ | </ | ||
+ | |||
+ | Important: be aware of preprocessor directives that start with **#!** (hash/pound and exclamation) - those are no longer line comments. | ||
+ | |||
+ | ==== Values ==== | ||
+ | |||
+ | There are three types of values: | ||
+ | |||
+ | * integer - numbers of 32bit size | ||
+ | * boolean - aliases to 1 (true, on, yes) or 0 (false, off, no) | ||
+ | * string - tokens enclosed in between double or single quotes | ||
+ | |||
+ | |||
+ | Example: | ||
+ | |||
+ | <code c> | ||
+ | // next two are strings | ||
+ | |||
+ | "this is a string value" | ||
+ | 'this is another string value' | ||
+ | |||
+ | // next is a boolean | ||
+ | |||
+ | yes | ||
+ | |||
+ | // next is an integer | ||
+ | |||
+ | 64 | ||
+ | |||
+ | </ | ||
+ | |||
+ | ==== Identifiers ==== | ||
+ | |||
+ | Identifiers are tokens which are not enclosed in single or double quotes and to match the rules for integer or boolean values. | ||
+ | |||
+ | For example, the identifiers are the core parameters and functions, module functions, core keywords and statements. | ||
+ | |||
+ | Example: | ||
+ | |||
+ | <code c> | ||
+ | return | ||
+ | </ | ||
+ | |||
+ | ==== Variables ==== | ||
+ | |||
+ | The variables start with **$** (dollar character). | ||
+ | |||
+ | You can see the list with available variables in the Pseudo-Variables Cookbook. | ||
+ | |||
+ | Example: | ||
+ | |||
+ | <code c> | ||
+ | $var(x) = $rU + " | ||
+ | </ | ||
+ | |||
+ | ==== Actions ==== | ||
+ | |||
+ | An action is an element used inside routing blocks ended by **;** (semicolon). It can be an execution of a function from core or a module, a conditional or loop statement, an assignment expression. | ||
+ | |||
+ | Example: | ||
+ | |||
+ | <code c> | ||
+ | sl_send_reply(" | ||
+ | exit; | ||
+ | </ | ||
+ | |||
+ | ==== Expressions ==== | ||
+ | |||
+ | An expression is an association group of statements, variables, functions and operators. | ||
+ | |||
+ | Example: | ||
+ | |||
+ | <code c> | ||
+ | if(!t_relay()) | ||
+ | |||
+ | if($var(x)> | ||
+ | |||
+ | " | ||
+ | </ | ||
===== Config Pre-Processor Directives ===== | ===== Config Pre-Processor Directives ===== | ||
Line 17: | Line 211: | ||
The path_to_file can be relative or absolute. If it is not absolute path, first attempt is to locate it relative to current directory, and if fails, relative to directory of the file that includes it. There is no restriction where include can be used or what can contain - any part of config file is ok. There is a limit of maximum 10 includes in depth, otherwise you can use as many includes as you want. Reporting of the cfg file syntax errors prints now the file name for easier troubleshooting. | The path_to_file can be relative or absolute. If it is not absolute path, first attempt is to locate it relative to current directory, and if fails, relative to directory of the file that includes it. There is no restriction where include can be used or what can contain - any part of config file is ok. There is a limit of maximum 10 includes in depth, otherwise you can use as many includes as you want. Reporting of the cfg file syntax errors prints now the file name for easier troubleshooting. | ||
- | If the included file is not found, the config file parser throws error. | + | If the included file is not found, the config file parser throws error. You can find this error message at the logging destination, |
You can use also the syntax **# | You can use also the syntax **# | ||
Line 53: | Line 247: | ||
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 - swtich | + | |
- | * #!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: | ||
- | * easy way to enable/ | + | * easy way to enable/ |
* switch control for parts where conditional statements were not possible (e.g., global parameters, module settings) | * switch control for parts where conditional statements were not possible (e.g., global parameters, module settings) | ||
* faster by not using conditional statements inside routing blocks when switching between running environments | * faster by not using conditional statements inside routing blocks when switching between running environments | ||
Line 88: | Line 287: | ||
#!ifdef TESTBED_MODE | #!ifdef TESTBED_MODE | ||
modparam(" | modparam(" | ||
- | " | + | " |
#!else | #!else | ||
modparam(" | modparam(" | ||
- | " | + | " |
#!endif | #!endif | ||
Line 161: | Line 360: | ||
* 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 **# | ||
+ | |||
+ | ==== defenvs ==== | ||
+ | |||
+ | Similar to **# | ||
+ | |||
+ | <code c> | ||
+ | #!defenvs ENVVAR | ||
+ | #!defenvs ID=ENVVAR | ||
+ | </ | ||
==== subst ==== | ==== subst ==== | ||
Line 189: | Line 432: | ||
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 485: | Line 735: | ||
==== advertised_address ==== | ==== advertised_address ==== | ||
- | It can be an IP address or string and represents the address advertised in Via header | + | It can be an IP address or string and represents the address advertised in Via header. If empty or not set (default value) the socket |
- | 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. | address from where the request will be sent is used. | ||
Line 498: | Line 747: | ||
advertised_address=" | advertised_address=" | ||
+ | Note: this option may be deprecated and removed in the near future, it is recommended to set **advertise** option for **listen** parameter. | ||
==== advertised_port ==== | ==== advertised_port ==== | ||
- | The port advertised in Via header | + | The port advertised in Via header. If empty or not set (default value) the port from where the message will be sent is used. Same warnings as for ' |
Example of usage: | Example of usage: | ||
Line 506: | Line 756: | ||
advertised_port=5080 | advertised_port=5080 | ||
+ | Note: this option may be deprecated and removed in the near future, it is recommended to set **advertise** option for **listen** parameter. | ||
==== alias ==== | ==== alias ==== | ||
Line 519: | Line 770: | ||
</ | </ | ||
+ | Note: the hostname has to be enclosed in between quotes if it has reserved tokens such as **forward**, | ||
==== 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 |
Default: 0 (asynchronous framework is disabled). | Default: 0 (asynchronous framework is disabled). | ||
Line 530: | Line 782: | ||
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 | ||
+ | </ | ||
+ | |||
+ | ==== 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 542: | Line 847: | ||
==== 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 548: | Line 853: | ||
< | < | ||
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 609: | Line 924: | ||
Examples of usage: | Examples of usage: | ||
- | * debug=3: print all log messages. This is only usefull | + | * debug=3: print all log messages. This is only useful |
* debug=0: This will only log warning, errors and more critical messages. | * debug=0: This will only log warning, errors and more critical messages. | ||
* debug=-6: This will disable all log messages. | * debug=-6: This will disable all log messages. | ||
Line 618: | Line 933: | ||
kamcmd cfg.set_now_int core debug -- -1 | kamcmd cfg.set_now_int core debug -- -1 | ||
- | Note: There is a difference in log-levels between Kamailio 3.x and Kamailio< | + | Note: There is a difference in log-levels between Kamailio 3.x and Kamailio< |
For configuration of logging of the memory manager see the parameters [[#memlog]] and [[# | For configuration of logging of the memory manager see the parameters [[#memlog]] and [[# | ||
- | Further information can also be bound at: http:// | + | Further information can also be found at: https:// |
==== description ==== | ==== description ==== | ||
Line 672: | Line 987: | ||
==== 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 722: | Line 1054: | ||
http_reply_parse=yes | http_reply_parse=yes | ||
+ | |||
+ | ==== ip_free_bind ==== | ||
+ | |||
+ | Alias: ipfreebind, ip_nonlocal_bind | ||
+ | |||
+ | Control if Kamailio should attempt to bind to non local ip. This option is the per-socket equivalent of the system **ip_nonlocal_bind**. | ||
+ | |||
+ | Default is 0 (do not bind to non local ip). | ||
+ | |||
+ | Example of usage: | ||
+ | |||
+ | <code c> | ||
+ | ip_free_bind = 1 | ||
+ | </ | ||
+ | |||
+ | |||
+ | ==== ipv6_hex_style ==== | ||
+ | |||
+ | Can be set to " | ||
+ | |||
+ | Default is " | ||
+ | |||
+ | " | ||
+ | |||
+ | Example of usage: | ||
+ | |||
+ | <code c> | ||
+ | ipv6_hex_style = " | ||
+ | </ | ||
+ | ==== kemi.onsend_route_callback ==== | ||
+ | |||
+ | Set the name of callback function in the KEMI script to be executed as the equivalent of `onsend_route` block (from the native configuration file). | ||
+ | |||
+ | Default value: ksr_onsend_route | ||
+ | |||
+ | Set it to empty string or " | ||
+ | |||
+ | Example: | ||
+ | |||
+ | <code c> | ||
+ | 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=" | ||
+ | </ | ||
+ | |||
+ | ==== kemi.reply_route_callback ==== | ||
+ | |||
+ | Set the name of callback function in the KEMI script to be executed as the equivalent of `reply_route` block (from the native configuration file). | ||
+ | |||
+ | Default value: ksr_reply_route | ||
+ | |||
+ | Set it to empty string or " | ||
+ | |||
+ | Example: | ||
+ | |||
+ | <code c> | ||
+ | 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 ==== | ||
+ | |||
+ | If set to a log level less or equal than debug parameter, a log message with the duration in microseconds of executing request route or reply route is printed to syslog. | ||
+ | |||
+ | Default value is 3 (L_DBG). | ||
+ | |||
+ | Example: | ||
+ | |||
+ | <code c> | ||
+ | latency_cfg_log=2 | ||
+ | </ | ||
==== 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 735: | Line 1163: | ||
==== 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 758: | Line 1186: | ||
==== 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 773: | Line 1201: | ||
<code c> | <code c> | ||
- | listen=udp: | + | listen=udp: |
</ | </ | ||
Line 779: | Line 1207: | ||
<code c> | <code c> | ||
- | listen=udp: | + | listen=udp: |
</ | </ | ||
Line 785: | Line 1213: | ||
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 791: | Line 1235: | ||
Prototype: **loadmodule " | Prototype: **loadmodule " | ||
- | If modulepath is only modulename or modulename.so, | + | If modulepath is only modulename or modulename.so, |
Example of usage: | Example of usage: | ||
Line 802: | Line 1246: | ||
loadmodule " | loadmodule " | ||
</ | </ | ||
+ | |||
+ | ==== loadmodulex ==== | ||
+ | |||
+ | Similar to **loadmodule** with the ability to evaluate variables in its parameter. | ||
==== loadpath ==== | ==== loadpath ==== | ||
Line 825: | Line 1273: | ||
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 ==== | ||
+ | |||
+ | Set specific data required by the log engine. See also the **log_engine_type**. | ||
+ | |||
+ | <code c> | ||
+ | log_engine_type=" | ||
+ | log_engine_data=" | ||
+ | </ | ||
+ | |||
+ | ==== log_engine_type ==== | ||
+ | |||
+ | Specify what logging engine to be used and its initialization data. A logging engine is implemented as a module. Supported values are a matter of the module. | ||
+ | |||
+ | For example, see the readme of **log_custom** module for more details. | ||
+ | |||
+ | <code c> | ||
+ | log_engine_type=" | ||
+ | log_engine_data=" | ||
+ | </ | ||
Line 842: | Line 1320: | ||
==== log_name ==== | ==== log_name ==== | ||
- | Allows to configure a log_name prefix which will be used when printing to syslog. This is useful to filter log messages when running many instances of Kamailio on same server | + | Allows to configure a log_name prefix which will be used when printing to syslog |
< | < | ||
- | log_name=" | + | log_name=" |
</ | </ | ||
==== 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 [[# | ||
+ | |||
+ | |||
+ | 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 858: | Line 1340: | ||
</ | </ | ||
+ | ==== log_prefix_mode ==== | ||
+ | |||
+ | Control if [[# | ||
+ | |||
+ | If set to 0 (default), then log prefix is evaluated when the sip message is received and then reused (recommended if the **log_prefix** has only variables that have same value for same message). This is the current behaviour of **log_prefix** evaluation. | ||
+ | |||
+ | If set to 1, then the log prefix is evaluated before/ | ||
+ | |||
+ | Example: | ||
+ | |||
+ | < | ||
+ | log_prefix_mode=1 | ||
+ | </ | ||
==== log_stderror ==== | ==== log_stderror ==== | ||
Line 873: | Line 1368: | ||
log_stderror=yes | log_stderror=yes | ||
+ | |||
+ | ==== cfgengine ==== | ||
+ | |||
+ | Set the config interpreter engine for execution of the routing logic inside the configuration file. Default is the native interpreter. | ||
+ | |||
+ | Example of usage: | ||
+ | |||
+ | cfgengine=" | ||
+ | cfgengine " | ||
+ | |||
+ | If name is " | ||
+ | | ||
+ | The name can be the identifier of an embedded language interpreter, | ||
+ | |||
+ | cfgengine " | ||
==== 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 882: | Line 1392: | ||
maxbuffer=65536 | maxbuffer=65536 | ||
+ | Note: it is not the size of the internal SIP message receive buffer. | ||
==== max_branches ==== | ==== max_branches ==== | ||
Line 912: | Line 1423: | ||
max_while_loops=200 | max_while_loops=200 | ||
+ | |||
+ | ==== mcast ==== | ||
+ | |||
+ | This parameter can be used to set the interface that should join the multicast group. This is useful if you want to **listen** on a multicast address and don't want to depend on the kernel routing table for choosing an interface. | ||
+ | |||
+ | The parameter is reset after each **listen** parameter, so you can join the right multicast group on each interface without having to modify kernel routing beforehand. | ||
+ | |||
+ | Example of usage: | ||
+ | |||
+ | mcast=" | ||
+ | listen=udp: | ||
==== mcast_loopback ==== | ==== mcast_loopback ==== | ||
Line 971: | Line 1493: | ||
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 977: | Line 1499: | ||
</ | </ | ||
+ | To change its value at runtime, **kamcmd** needs to be used and the modules **ctl** and **cfg_rpc** loaded. Enabling it can be done with: | ||
+ | |||
+ | < | ||
+ | kamcmd cfg.set_now_int core mem_join 1 | ||
+ | </ | ||
+ | |||
+ | To disable, set its value to 0. | ||
==== mem_safety ==== | ==== mem_safety ==== | ||
- | If set to 1, memory free operation does not call abort() for double freeing a pointer or freeing an invalid address. The server still prints the alerting log messages. | + | If set to 1, memory free operation does not call abort() for double freeing a pointer or freeing an invalid address. The server still prints the alerting log messages. If set to 0, the SIP server stops by calling abort() to generate a core file. |
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> | ||
- | mem_safety=1 | + | mem_safety=0 |
+ | </ | ||
+ | |||
+ | ==== mem_status_mode ==== | ||
+ | |||
+ | If set to 1, memory status dump for qm allocator will print details about used fragments. If set to 0, the dump contains only free fragments. It can be set at runtime via cfg param framework (e.g., via kamcmd). | ||
+ | |||
+ | Default is 0. | ||
+ | |||
+ | <code c> | ||
+ | mem_status_mode=1 | ||
</ | </ | ||
Line 1031: | Line 1570: | ||
==== 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 1040: | Line 1580: | ||
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 1077: | Line 1620: | ||
==== 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 1024. | + | 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 1093: | Line 1636: | ||
< | < | ||
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 | ||
+ | </ | ||
+ | |||
+ | ==== rundir ==== | ||
+ | |||
+ | Alias: run_dir | ||
+ | |||
+ | Set the folder for creating runtime files such as MI fifo or CTL unixsocket. | ||
+ | |||
+ | Default: / | ||
+ | |||
+ | Example of usage: | ||
+ | |||
+ | < | ||
+ | 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 1102: | Line 1687: | ||
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 config script for 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 ==== | ||
- | A configurable unique server id that can be used to discriminate server instances within a cluster of servers when all other information, | + | A configurable unique server id that can be used to discriminate server instances within a cluster of servers when all other information, |
<code c> | <code c> | ||
Line 1136: | Line 1736: | ||
shm_force_alloc = yes | no (default no) | shm_force_alloc = yes | no (default no) | ||
+ | |||
+ | ==== shm_mem_size ==== | ||
+ | |||
+ | Set shared memory size (in Mb). | ||
+ | |||
+ | 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 1221: | Line 1852: | ||
+ | ==== 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 1252: | Line 1889: | ||
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 1270: | Line 1916: | ||
<code c> | <code c> | ||
user_agent_header=" | user_agent_header=" | ||
+ | </ | ||
+ | |||
+ | ==== verbose_startup ==== | ||
+ | |||
+ | Control if printing routing tree and udp probing buffer debug messages should be printed at startup. | ||
+ | |||
+ | Default is 0 (don't print); set to 1 to get those debug messages. | ||
+ | |||
+ | Example of usage: | ||
+ | |||
+ | <code c> | ||
+ | | ||
+ | </ | ||
+ | |||
+ | ==== version_table ==== | ||
+ | |||
+ | Set the name of the table holding the table version. Useful if the proxy is sharing a database within a project and during upgrades. Default value is " | ||
+ | |||
+ | Example of usage: | ||
+ | |||
+ | <code c> | ||
+ | | ||
+ | </ | ||
+ | |||
+ | ==== 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 | ||
</ | </ | ||
Line 1283: | Line 1987: | ||
or | or | ||
| | ||
+ | |||
+ | ==== xavp_via_params ==== | ||
+ | |||
+ | Set the name of the XAVP of which subfields will be added as local //Via// -header parameters. | ||
+ | |||
+ | If not set, XAVP to Via header parameter manipulation is not applied (default behaviour). | ||
+ | |||
+ | If set, local Via header gets additional parameters from defined XAVP. Core flag FL_ADD_XAVP_VIA_PARAMS needs to be set¹. | ||
+ | |||
+ | Example: | ||
+ | | ||
+ | [1] See function // | ||
+ | |||
+ | ==== xavp_via_fields ==== | ||
+ | |||
+ | Set the name of xavp from where to take Via header field: address and port. | ||
+ | Use them to build local Via header. | ||
+ | |||
+ | Example: | ||
+ | |||
+ | <code c> | ||
+ | xavp_via_fields=" | ||
+ | |||
+ | request_route { | ||
+ | ... | ||
+ | $xavp(customvia=> | ||
+ | $xavp(customvia=> | ||
+ | via_use_xavp_fields(" | ||
+ | t_relay(); | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | See function // | ||
===== 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 1306: | Line 2043: | ||
Kamailio also allows you to finetune the DNS resolver settings. | Kamailio also allows you to finetune the DNS resolver settings. | ||
- | The maximum time a dns request can take (before failing) is (if dns_try_ipv6 is yes, mutliply | + | The maximum time a dns request can take (before failing) is (if dns_try_ipv6 is yes, multiply |
(dns_retr_time*(dns_retr_no+1)*dns_servers_no)*(search_list_domains) | (dns_retr_time*(dns_retr_no+1)*dns_servers_no)*(search_list_domains) | ||
Line 1429: | Line 2166: | ||
**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 1445: | Line 2182: | ||
==== 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 1456: | Line 2193: | ||
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 1464: | Line 2201: | ||
Can be ' | Can be ' | ||
- | HINT: even if you don't have a search list defined, setting this option to ' | + | HINT: even if you don't have a search list defined, setting this option to ' |
Example of usage: | Example of usage: | ||
Line 1472: | Line 2209: | ||
==== use_dns_cache ==== | ==== use_dns_cache ==== | ||
- | Tells if DNS responses are cached - this means that the internal DNS resolver (instead of the system' | + | Tells if DNS responses are cached - this means that the internal DNS resolver (instead of the system' |
==== use_dns_failover ==== | ==== use_dns_failover ==== | ||
Line 1498: | Line 2235: | ||
Note: For NAT traversal of TCP clients it is better to not use tcp_accept_aliases but just use nathelper module and fix_nated_[contact|register] functions. | Note: For NAT traversal of TCP clients it is better to not use tcp_accept_aliases but just use nathelper module and fix_nated_[contact|register] functions. | ||
+ | |||
+ | Default is " | ||
| | ||
+ | |||
+ | ==== 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 ==== | ||
+ | |||
+ | Enable internal TCP receiving stack to accept HEP3 packets. This option has to be set to **yes** on a Kamailio instance acting as Homer SIPCapture server that is supposed to receive HEP3 packets over TCP/TLS. | ||
+ | |||
+ | Default value is **no**. | ||
+ | |||
+ | <code c> | ||
+ | tcp_accept_hep3=yes | ||
+ | </ | ||
==== tcp_accept_no_cl ==== | ==== tcp_accept_no_cl ==== | ||
Line 1512: | Line 2274: | ||
</ | </ | ||
+ | ==== 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 1550: | Line 2321: | ||
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 1560: | Line 2340: | ||
==== tcp_conn_wq_max ==== | ==== tcp_conn_wq_max ==== | ||
- | Maximum bytes queued for write allowed per connection. Attempting to queue more bytes would result in an error and in the connection being closed (too slow). If tcp_write_buf | + | Maximum bytes queued for write allowed per connection. Attempting to queue more bytes would result in an error and in the connection being closed (too slow). If tcp_buf_write |
tcp_conn_wq_max = bytes (default 32 K) | tcp_conn_wq_max = bytes (default 32 K) | ||
Line 1621: | Line 2401: | ||
==== tcp_max_connections ==== | ==== 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 | + | Maximum number of tcp connections (if the number is exceeded no new tcp connections will be accepted). Default is defined in tcp_init.h: #define DEFAULT_TCP_MAX_CONNECTIONS 2048 |
Example of usage: | Example of usage: | ||
Line 1652: | Line 2432: | ||
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 1668: | Line 2455: | ||
==== 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 1679: | Line 2478: | ||
==== tcp_wq_max ==== | ==== tcp_wq_max ==== | ||
- | Maximum bytes queued for write allowed globally. It has no effect if tcp_write_buf | + | Maximum bytes queued for write allowed globally. It has no effect if tcp_buf_write |
tcp_wq_max = bytes (default 10 Mb) | tcp_wq_max = bytes (default 10 Mb) | ||
+ | | ||
===== TLS Parameters ===== | ===== TLS Parameters ===== | ||
Line 1907: | Line 2707: | ||
- | ===== 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 1994: | Line 2794: | ||
rt_timer2_prio=< | rt_timer2_prio=< | ||
- | ===== Core functions | + | ===== Core Functions |
Functions exported by core that can be used in route blocks. | Functions exported by core that can be used in route blocks. | ||
Line 2083: | Line 2883: | ||
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: | ||
+ | < | ||
force_send_socket(10.10.10.10: | force_send_socket(10.10.10.10: | ||
+ | force_send_socket(udp: | ||
+ | </ | ||
==== force_tcp_alias ==== | ==== force_tcp_alias ==== | ||
Line 2095: | Line 2899: | ||
adds a tcp port alias for the current connection (if tcp). | adds a tcp port alias for the current connection (if tcp). | ||
- | Usefull | + | Useful |
the same connection this request came from [it could help | the same connection this request came from [it could help | ||
for firewall or nat traversal]. | for firewall or nat traversal]. | ||
Line 2125: | Line 2929: | ||
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. | 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:// | + | For more see: https:// |
Example of usage: | Example of usage: | ||
Line 2214: | Line 3018: | ||
</ | </ | ||
+ | See also the FAQ for how the function return code is evaluated: | ||
+ | |||
+ | * https:// | ||
==== revert_uri ==== | ==== revert_uri ==== | ||
Line 2270: | Line 3077: | ||
Example of usage: | Example of usage: | ||
- | rewriteuri(" | + | rewriteuri(" |
==== rewriteuserpass ==== | ==== rewriteuserpass ==== | ||
Line 2301: | Line 3108: | ||
+ | ==== 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 2308: | Line 3133: | ||
Example of usage: | Example of usage: | ||
- | set_advertised_address(" | + | set_advertised_address(" |
==== set_advertised_port ==== | ==== set_advertised_port ==== | ||
Line 2322: | Line 3147: | ||
The message will be forwarded only if there is already an existing connection to the destination. It applies only to connection oriented protocols like TCP and TLS (TODO: SCTP), for UDP it will be ignored. The behavior depends in which route block the function is called: | The message will be forwarded only if there is already an existing connection to the destination. It applies only to connection oriented protocols like TCP and TLS (TODO: SCTP), for UDP it will be ignored. The behavior depends in which route block the function is called: | ||
- | * normal request route: affects stateless forwards and tm. For tm it affects all the branches and the possible retransmissions (in fact there are no retransission | + | * normal request route: affects stateless forwards and tm. For tm it affects all the branches and the possible retransmissions (in fact there are no retransmission |
* onreply_route[0] (stateless): | * onreply_route[0] (stateless): | ||
- | * onreply_route[!=0] (tm): ignored | + | * onreply_route[!=0] |
* branch_route: | * branch_route: | ||
Line 2401: | Line 3226: | ||
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). | 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:// | + | For more see: https:// |
Example of usage: | Example of usage: | ||
Line 2436: | Line 3261: | ||
==== userphone ==== | ==== userphone ==== | ||
- | ===== Routing | + | Add "user=phone" parameter to R-URI. |
+ | |||
+ | ===== Custom Global Parameters ===== | ||
+ | |||
+ | These are parameters that can be defined by the writer of kamailio.cfg in order to be used inside routing | ||
+ | |||
+ | The definition of a custom global parameter must follow the pattern: | ||
+ | |||
+ | < | ||
+ | group.variable = value desc " | ||
+ | |||
+ | </ | ||
+ | |||
+ | The value can be a quoted string or integer number. | ||
+ | |||
+ | Example: | ||
+ | |||
+ | <code c> | ||
+ | pstn.gw_ip = " | ||
+ | </ | ||
+ | |||
+ | The custom global parameter can be accessed inside a routing block via: | ||
+ | |||
+ | < | ||
+ | $sel(cfg_get.group.variable) | ||
+ | </ | ||
+ | |||
+ | Example: | ||
+ | |||
+ | <code c> | ||
+ | $ru = " | ||
+ | </ | ||
+ | |||
+ | **Note:** Some words cannot be used as (part of) names for custom variables or groups, and if they are used a syntax error is logged | ||
+ | |||
+ | ===== Routing Blocks | ||
The routing blocks are the parts of the configuration file executed by kamailio at runtime. They can be seen as blocks of actions similar to functions (or procedures) from common programming languages. | The routing blocks are the parts of the configuration file executed by kamailio at runtime. They can be seen as blocks of actions similar to functions (or procedures) from common programming languages. | ||
Line 2442: | Line 3302: | ||
A routing block is identified by a specific token, followed by a name in between square brackets and actions in between curly braces. | A routing block is identified by a specific token, followed by a name in between square brackets and actions in between curly braces. | ||
- | < | + | < |
route_block_id[NAME] { | route_block_id[NAME] { | ||
ACTIONS | ACTIONS | ||
Line 2458: | Line 3318: | ||
Example: | Example: | ||
- | < | + | < |
request_route{ | request_route{ | ||
... | ... | ||
Line 2553: | Line 3413: | ||
} | } | ||
branch_route[OUT] { | branch_route[OUT] { | ||
- | if(uri=~" | + | if(uri=~" |
# discard branches that go to 10.10.10.10 | # discard branches that go to 10.10.10.10 | ||
drop(); | drop(); | ||
Line 2601: | Line 3461: | ||
<code c> | <code c> | ||
reply_route { | reply_route { | ||
- | if(status==" | + | if(status==" |
drop; | drop; | ||
} | } | ||
Line 2612: | Line 3472: | ||
- | 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 2643: | Line 3503: | ||
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 2670: | Line 3530: | ||
* 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: | ||
+ | |||
+ | * **event_route[core: | ||
+ | * note that due to forking, other sip workers can get faster to listening for sip traffic | ||
+ | |||
+ | <code c> | ||
+ | event_route[core: | ||
+ | xlog(" | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | * **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; | ||
+ | } | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | * **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 === | ||
+ | |||
+ | 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: | ||
<code c> | <code c> | ||
Line 2711: | Line 3628: | ||
* **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 2720: | Line 3643: | ||
} | } | ||
} | } | ||
+ | |||
</ | </ | ||
- | ===== Script | + | ===== Script |
==== if ==== | ==== if ==== | ||
Line 2753: | Line 3677: | ||
|| logical OR | || logical OR | ||
! | ! | ||
- | [ ... ] test operator - inside can be any arithmetic expression | ||
</ | </ | ||
Line 2765: | Line 3688: | ||
} | } | ||
+ | See also the FAQ for how the function return code is evaluated: | ||
+ | * https:// | ||
==== switch ==== | ==== switch ==== | ||
Line 2845: | Line 3770: | ||
} | } | ||
- | ===== Script | + | ===== Script |
Assignments together with string and arithmetic operations can be done directly in configuration file. | Assignments together with string and arithmetic operations can be done directly in configuration file. | ||
Line 2875: | Line 3800: | ||
</ | </ | ||
- | ==== String | + | ==== String |
For strings, ' | For strings, ' | ||
Line 2882: | Line 3807: | ||
$var(b) = " | $var(b) = " | ||
</ | </ | ||
- | ==== Arithmetic | + | ==== Arithmetic |
For numbers, one can use: | For numbers, one can use: | ||
Line 2894: | Line 3819: | ||
* ^ : bitwise XOR | * ^ : bitwise XOR | ||
* ~ : bitwise NOT | * ~ : bitwise NOT | ||
- | * << : bitwise left shift | + | * <nowiki><<</ |
- | * >> : bitwise right shift | + | * <nowiki>>></ |
Example: | Example: | ||
Line 2905: | Line 3831: | ||
NOTE: to ensure the priority of operands in expression evaluations do use __parenthesis__. | NOTE: to ensure the priority of operands in expression evaluations do use __parenthesis__. | ||
- | Arithmetic expressions can be used in condition expressions | + | Arithmetic expressions can be used in condition expressions. |
< | < | ||
- | if( [ $var(a) & 4 ] ) | + | if( $var(a) & 4 ) |
log(" | log(" | ||
</ | </ | ||
Line 2947: | Line 3873: | ||
| | ||
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 | ||
+ | * **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 (' | ||
+ | * **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 config for printing log message with **j** flag: | ||
+ | |||
+ | < | ||
+ | xinfo(" | ||
+ | </ | ||
+ | |||
+ | Example config for printing log messages with **p** flag: | ||
+ | |||
+ | < | ||
+ | log_prefix=", | ||
+ | </ |