User Tools

Site Tools


cookbooks:devel:core

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
Next revision Both sides next revision
cookbooks:devel:core [2017/04/11 17:38]
mslehto [tcp_max_connections] tcp_conn.h -> tcp_init.h
cookbooks:devel:core [2021/04/03 08:18]
miconda [if]
Line 1: Line 1:
-====== Kamailio SIP Server v5.1.x (devel): Core Cookbook ======+====== 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 47: Line 48:
 </code> </code>
  
 +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="sip.mydomain.com";
 +</code>
 +
 +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 "dns".
 +
 +<code c>
 +listen=tcp:127.0.0.1:5060 advertise "sip.dns.example.com":5060
 +</code>
 ==== Modules Settings Section ==== ==== Modules Settings Section ====
  
Line 125: 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 198: Line 210:
 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, usually in the system logging (file).
  
 You can use also the syntax **#!include_file** or **!!include_file**. You can use also the syntax **#!include_file** or **!!include_file**.
Line 234: Line 246:
  
 Available directives: Available directives:
-  * #!define NAME - define a keyword +  * **#!define NAME** - define a keyword 
-  * #!define NAME VALUE - define a keyword with value +  * **#!define NAME VALUE** - define a keyword with value 
-  * #!ifdef NAME - check if a keyword is defined +  * **#!ifdef NAME** - check if a keyword is defined 
-  * #!ifndef - check if a keyword is not defined +  * **#!ifndef** - check if a keyword is not defined 
-  * #!else - swtich to false branch of ifdef/ifndef region +  * **#!else** switch to false branch of ifdef/ifndef region 
-  * #!endif - end ifdef/ifndef region +  * **#!endif** - end ifdef/ifndef region 
-  * #!trydef - add a define if not already defined +  * **#!trydef** - add a define if not already defined 
-  * #!redefine - force redefinition even if 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 'kamctl core.ppdefines_full' for full list.
  
 Among benefits: Among benefits:
-  * easy way to enable/disable features (e.g., see default cfg for 3.0.0 -- controlling support of nat traversal, presence, etc...)+  * easy way to enable/disable features (e.g., see default cfg -- controlling support of nat traversal, presence, etc...)
   * 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 269: Line 286:
 #!ifdef TESTBED_MODE #!ifdef TESTBED_MODE
 modparam("acc|auth_db|usrloc", "db_url", modparam("acc|auth_db|usrloc", "db_url",
- "mysql://openser:openserrw@localhost/openser_testbed")+ "mysql://kamailio:kamailiorw@localhost/kamailio_testbed")
 #!else #!else
 modparam("acc|auth_db|usrloc", "db_url", modparam("acc|auth_db|usrloc", "db_url",
- "mysql://openser:openserrw@10.0.0.2/openser_production")+ "mysql://kamailio:kamailiorw@10.0.0.2/kamailio_production")
 #!endif #!endif
  
Line 342: 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
 +</code>
 +
 +It can also be just **$!defenv ENVVAR** and the defined ID is the ENVVAR name.
 +
 +Example:
 +
 +<code c>
 +#!defenv SHELL
 +</code>
 +
 +If environment variable $SHELL is '/bin/bash', then it is like:
 +
 +<code c>
 +#!define SHELL /bin/bash
 +</code>
 +
 +Full expression variant:
 +
 +<code c>
 +#!defenv ENVSHELL=SHELL
 +</code>
 +
 +Then it is like:
 +
 +<code c>
 +#!define ENVSHELL /bin/bash
 +</code>
 +
 +It is a simplified alternative of using **#!substdef** with **$env(NAME)** in the replacement part.
 +    
 ==== subst ==== ==== subst ====
  
Line 370: Line 423:
 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 "/ID/subst/"
 +</code>
 +
 +Similar to **subst**, but in addition it adds a **#!define ID "subst"** (note the difference from #!substdef that the value for define is enclosed in double quotes, useful when the define is used in a place for a string value).
 ===== Core Keywords ===== ===== Core Keywords =====
  
-Keywords specific to SIP messages which can be used mainly in '''if''' expressions.+Keywords specific to SIP messages which can be used mainly in ''if'' expressions.
  
 ==== af ==== ==== af ====
Line 666: Line 726:
 ==== advertised_address ==== ==== advertised_address ====
  
-It can be an IP address or string and represents the address advertised in Via header and +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 679: Line 738:
     advertised_address="kamailio.org"     advertised_address="kamailio.org"
  
 +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 and other destination lumps (e.g. RR). If empty or not set (default value) the port from where the message will be sent is used. Same warnings as for 'advertised_address'.+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 'advertised_address'.
  
 Example of usage: Example of usage:
Line 687: Line 747:
     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 700: Line 761:
 </code> </code>
  
 +Note: the hostname has to be enclosed in between quotes if it has reserved tokens such as **forward**, **drop** ... or operators such as **-** (minus) ...
 ==== 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 (workers) to create for asynchronous execution in the group "default". These are processes that can receive tasks from various components (e.g, modules such as async, acc, sqlops) and execute them locally, which is different process than the task sender.
  
 Default: 0 (asynchronous framework is disabled). Default: 0 (asynchronous framework is disabled).
Line 711: Line 773:
     async_workers=4     async_workers=4
 </code> </code>
 +
 +==== async_nonblock ====
 +
 +Set the non-block mode for the internal sockets used by default group of async workers.
 +
 +Default: 0
 +
 +Example:
 +
 +<code>
 +    async_nonblock=1
 +</code>
 +
 +==== 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:
 +
 +<code>
 +    async_usleep=100
 +</code>
 +
 +==== async_workers_group ====
 +
 +Define groups of asynchronous worker processes.
 +
 +Prototype:
 +
 +<code>
 +async_workers_group="name=X;workers=N;nonblock=[0|1];usleep=M"
 +</code>
 +
 +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:
 +
 +<code>
 +    async_workers_group="name=reg;workers=4;nonblock=0;usleep=0"
 +</code>
 +
 +If the **name** is default, then it overwrites the value set by **async_workers**.
 +
 +See also **event_route[core:pre-routing]** and **sworker** module.
  
 ==== auto_aliases ==== ==== auto_aliases ====
Line 723: Line 838:
 ==== 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 729: Line 844:
 <code> <code>
     auto_bind_ipv6=1     auto_bind_ipv6=1
 +</code>
 +
 +==== 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:
 +
 +<code>
 +    bind_ipv6_link_local=1
 </code> </code>
 ==== check_via ==== ==== check_via ====
Line 790: Line 915:
 Examples of usage: Examples of usage:
  
-  * debug=3: print all log messages. This is only usefull for debugging of problems. Note: this produces a lot of data and therefore should not be used on production servers (on a busy server this can easily fill up your hard disk with log messages)+  * debug=3: print all log messages. This is only useful for debugging of problems. Note: this produces a lot of data and therefore should not be used on production servers (on a busy server this can easily fill up your hard disk with log messages)
   * 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 799: Line 924:
   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<=1.5: Up to Kamailio 1.5 the log level started with 4, whereas in Kamailio>=3 the log level starts with 3. Thus, if you were using debug=3 in older Kamailio/Openser, now use debug=2.+Note: There is a difference in log-levels between Kamailio 3.x and Kamailio<=1.5: Up to Kamailio 1.5 the log level started with 4, whereas in Kamailio>=3 the log level starts with 3. Thus, if you were using debug=3 in older Kamailio, now use debug=2.
  
 For configuration of logging of the memory manager see the parameters [[#memlog]] and [[#memdbg]]. For configuration of logging of the memory manager see the parameters [[#memlog]] and [[#memdbg]].
  
-Further information can also be bound at: http://www.kamailio.org/dokuwiki/doku.php/tutorials:debug-syslog-messages+Further information can also be found at: https://www.kamailio.org/wiki/tutorials/3.2.x/syslog
  
 ==== description ==== ==== description ====
Line 853: Line 978:
 ==== 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   : 1, 
 +  FLAG_TWO   : 2; 
 +... 
 +</code> 
 + 
 +(*) 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:5.2.x:core#define|#!define]] (which is also valid for branch/script flags): 
 +<code c> 
 +#!define FLAG_NAME FLAG_BIT 
 +</code> 
 + 
  
 ==== force_rport ==== ==== force_rport ====
Line 903: Line 1045:
  
   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
 +</code>
 +
 +
 +==== ipv6_hex_style ====
 +
 +Can be set to "a", "A" or "c" to specify if locally computed string representation of IPv6 addresses should be expanded lowercase, expanded uppercase or compacted lowercase hexa digits.
 +
 +Default is "c" (compacted lower hexa digits, conforming better with RFC 5952).
 +
 +"A" is preserving the behaviour before this global parameter was introduced, while "a" enables the ability to follow some of the recommendations of RFC 5952, section 4.3.
 +
 +Example of usage:
 +
 +<code c>
 +  ipv6_hex_style = "a"
 +</code>
 +==== 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 "none" to skip execution of this callback function.
 +
 +Example:
 +
 +<code c>
 +kemi.onsend_route_callback="ksr_my_onsend_route"
 +</code>
 +
 +==== kemi.received_route_callback ====
 +
 +Set the name of callback function in the KEMI script to be executed as the equivalent of `event_route[core:msg-received]` block (from the native configuration file). For execution, it also require to have the received_route_mode global parameter set to 1.
 +
 +Default value: none
 +
 +Set it to empty string or "none" to skip execution of this callback function.
 +
 +Example:
 +
 +<code c>
 +kemi.received_route_callback="ksr_my_receieved_route"
 +</code>
 +
 +==== 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 "none" to skip execution of this callback function.
 +
 +Example:
 +
 +<code c>
 +kemi.onsend_route_callback="ksr_my_reply_route"
 +</code>
 +
 +==== kemi.pre_routing_callback ====
 +
 +Set the name of callback function in the KEMI script to be executed as the equivalent of `event_route[core:pre-routing]` block (from the native configuration file).
 +
 +Default value: none
 +
 +Set it to empty string or "none" to skip execution of this callback function.
 +
 +Example:
 +
 +<code c>
 +kemi.pre_routing_callback="ksr_pre_routing"
 +</code>
  
 ==== latency_cfg_log ==== ==== latency_cfg_log ====
Line 918: Line 1144:
 ==== 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) 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.
  
 Default value is 0 (disabled). Default value is 0 (disabled).
Line 928: Line 1154:
 ==== 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) 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.
  
  
Line 951: Line 1177:
 ==== listen ==== ==== listen ====
  
-Set the network addresses the SIP server should listen to. It can be an IP address, hostname or network iterface id or combination of protocol:address:port (e.g., udp:10.10.10.10:5060). This parameter can be set multiple times in same configuration file, the server listening on all addresses specified.+Set the network addresses the SIP server should listen to. It can be an IP address, hostname or network interface id or combination of protocol:address:port (e.g., udp:10.10.10.10:5060). This parameter can be set multiple times in same configuration file, the server listening on all addresses specified.
  
 Example of usage: Example of usage:
Line 966: Line 1192:
  
 <code c> <code c>
-    listen=udp:[2a02:1850:1:1::13]:5060+    listen=udp:[2a02:1850:1:1::18]:5060
 </code> </code>
  
Line 972: Line 1198:
  
 <code c> <code c>
-    listen=udp:10.10.10.10:5060 advertise  11.11.11.11:5060+    listen=udp:10.10.10.10:5060 advertise 11.11.11.11:5060
 </code> </code>
  
Line 978: Line 1204:
  
 A typical use case for advertise address is when running SIP server behind a NAT/Firewall, when the local IP address (to be used for bind) is different than the public IP address (to be used for advertising). A typical use case for advertise address is when running SIP server behind a NAT/Firewall, when the local IP address (to be used for bind) is different than the public IP address (to be used for advertising).
 +
 +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:10.0.0.10:5060 name "s1"
 +    listen=udp:10.10.10.10:5060 advertise 11.11.11.11:5060 name "s2"
 +    listen=udp:10.10.10.20:5060 advertise "mysipdomain.com" name "s3"
 +    listen=udp:10.10.10.30:5060 advertise "mysipdomain.com" name "s4"
 +    ...
 +    $fsn = "s4";
 +    t_relay();
 +</code>
 +
 +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 984: Line 1226:
 Prototype: **loadmodule "modulepath"** Prototype: **loadmodule "modulepath"**
  
-If modulepath is only modulename or modulename.so, then Kamailio will try to search also for **modulename/modulename.so**, very useful when usining directly the version compiled in the source tree.+If modulepath is only modulename or modulename.so, then Kamailio will try to search also for **modulename/modulename.so**, very useful when using directly the version compiled in the source tree.
  
 Example of usage: Example of usage:
Line 995: Line 1237:
     loadmodule "dialplan.so"     loadmodule "dialplan.so"
 </code> </code>
 +
 +==== loadmodulex ====
 +
 +Similar to **loadmodule** with the ability to evaluate variables in its parameter.
  
 ==== loadpath ==== ==== loadpath ====
Line 1018: Line 1264:
 The proxy tries to find the modules in a smart way, e.g: loadmodule "uri" tries to find uri.so in the loadpath, but also uri/uri.so. The proxy tries to find the modules in a smart way, e.g: loadmodule "uri" tries to find uri.so in the loadpath, but also uri/uri.so.
  
 +==== 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
 +</code>
  
 ==== log_engine_data ==== ==== log_engine_data ====
Line 1062: Line 1319:
 ==== 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 (see log_prefix_mode about when/how evaluation is done).+Specify the text to be prefixed to the log messages printed by Kamailio while processing a SIP message (that is, when executing route blocks). It can contain script variables that are evaluated at runtime
 +See [[#log_prefix_mode]] about when/how evaluation is done
 + 
 + 
 +If a log message is printed from a part of the code executed out of routing blocks actions (e.g., can be timer, evapi worker process, ...), there is no log prefix set, because this one requires a valid SIP message structure to work with.
  
 Example - prefix with message type (1 - request, 2 - response), CSeq and Call-ID: Example - prefix with message type (1 - request, 2 - response), CSeq and Call-ID:
Line 1072: Line 1333:
 ==== log_prefix_mode ==== ==== log_prefix_mode ====
  
-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.+Control if [[#log_prefix|log prefix]] is re-evaluated.
  
-If set to 1, then the log prefix is evaluated before/after each config action (needs to be set when the log_prefix has variables that are different based on the context of config execution, e.g., $cfg(line)).+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/after each config action (needs to be set when the **log_prefix** has variables that are different based on the context of config execution, e.g., $cfg(line)).
  
 Example: Example:
Line 1096: Line 1359:
  
     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="name"
 +    cfgengine "name"
 +
 +If name is "native" or "default", it expects to have in native config interpreter for routing logic.
 +    
 +The name can be the identifier of an embedded language interpreter, such as "lua" which is registered by the app_lua module:
 +
 +    cfgengine "lua"
  
 ==== maxbuffer ==== ==== maxbuffer ====
Line 1205: Line 1483:
 It can be set via config reload framework. It can be set via config reload framework.
  
-Default is (disabled).+Default is (enabled).
  
 <code c> <code c>
Line 1220: Line 1498:
 ==== 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 (disabled).+Default is (enabled).
  
 <code c> <code c>
-mem_safety=1+mem_safety=0
 </code> </code>
  
Line 1282: Line 1560:
  
 ==== 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 1291: Line 1570:
 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**, with ability to evaluate the variables in its parameters.
 ==== onsend_route_reply ==== ==== onsend_route_reply ====
  
Line 1328: Line 1610:
 ==== pv_buffer_size ==== ==== pv_buffer_size ====
  
-The size in bytes of internal buffer to print dynamic strings with pseudo-variables inside. The default value is 8192 (8kB).+The size in bytes of internal buffer to print dynamic strings with pseudo-variables inside. The default value is 8192 (8kB). Please keep in mind that for xlog messages, there is a dedicated module parameter to set the internal buffer size.
  
 Example of usage: Example of usage:
Line 1344: Line 1626:
 <code> <code>
 pv_buffer_slots=12 pv_buffer_slots=12
 +</code>
 +
 +==== pv_cache_limit ====
 +
 +The limit how many pv declarations in the cache after which an action is taken. Default value is 2048.
 +
 +<code>
 +pv_cache_limit=1024
 +</code>
 +
 +==== 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.
 +
 +<code>
 +pv_cache_action=1
 </code> </code>
  
Line 1358: Line 1656:
 <code> <code>
 rundir="/tmp" rundir="/tmp"
 +</code>
 +
 +==== received_route_mode ====
 +
 +Enable or disable the execution of event_route[core:msg-received] routing block or its corresponding Kemi callback.
 +
 +Default value: 0 (disabled)
 +
 +Example of usage:
 +
 +<code c>
 +received_route_mode=1
 </code> </code>
  
Line 1367: Line 1677:
  
     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
 +</code>
 +
 +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, such as IP addresses are the same.+A configurable unique server id that can be used to discriminate server instances within a cluster of servers when all other information, such as IP addresses are the same.
  
 <code c> <code c>
Line 1401: Line 1726:
  
 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
 +</code>
 +
 +==== 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
 +</code>
 +
 ==== sip_warning (noisy feedback) ==== ==== sip_warning (noisy feedback) ====
  
-Can be 0 or 1. If set to 1 (default value) a 'Warning' header is added to each reply generated by Kamailio.+Can be 0 or 1. If set to 1 (default value is 0) a 'Warning' header is added to each reply generated by Kamailio.
 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 1486: Line 1842:
  
  
 +==== stats_name_separator ====
  
 +Specify the character used as a separator for the internal statistics' names. 
 +Default value is "_".
  
 +Example of usage:
 +
 +    stats_name_separator = "-"
  
 ==== tos ==== ==== tos ====
Line 1517: Line 1879:
  
   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 = "_"
 +</code>
 ==== user ==== ==== user ====
  
Line 1535: Line 1906:
 <code c> <code c>
 user_agent_header="User-Agent: My Super SIP Server" user_agent_header="User-Agent: My Super SIP Server"
 +</code>
 +
 +==== 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>
 +   verbose_startup=1
 </code> </code>
  
 ==== version_table ==== ==== version_table ====
  
-Set the name of the table holding the table version. Usefull if the proxy is sharing a database within a project and during upgrades. Default value is "version".+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 "version".
  
 Example of usage: Example of usage:
Line 1546: Line 1929:
    version_table="version44"    version_table="version44"
 </code> </code>
 +
 +==== wait_worker1_mode ====
 +
 +Enable waiting for child SIP worker one to complete initialization, then create the other child worker processes.
 +
 +Default: 0 (do not wait for child worker one to complete initialization).
 +
 +Example:
 +
 +<code c>
 +wait_worker1_mode = 1
 +</code>
 +
 +==== 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
 +</code>
 +
 +==== 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
 +</code>
 +
 ==== workdir ==== ==== workdir ====
  
Line 1557: Line 1977:
      or      or
      wdir=/usr/kam_wd      wdir=/usr/kam_wd
 +
 +==== 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:
 +     xavp_via_params="via"
 +[1] See function //via_add_xavp_params()// from "corex" module.
 +
 +==== 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="customvia"
 +
 +request_route {
 +  ...
 +  $xavp(customvia=>address) = "1.2.3.4";
 +  $xavp(customvia=>port) = "5080";  # must be string
 +  via_use_xavp_fields("1");
 +  t_relay();
 +}
 +</code>
 +     
 +See function //via_use_xavp_fields()// from "corex" module.
  
 ===== DNS Parameters ===== ===== DNS Parameters =====
Line 1580: Line 2033:
 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 it again by 2; if SRV and NAPTR lookups are enabled, it can take even longer!):+The maximum time a dns request can take (before failing) is (if dns_try_ipv6 is yes, multiply it again by 2; if SRV and NAPTR lookups are enabled, it can take even longer!):
  
   (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 1738: Line 2191:
 Can be 'yes' or 'no'. If set to 'no', the search list in '/etc/resolv.conf' will be ignored (=> fewer lookups => gives up faster). Default value is 'yes'. Can be 'yes' or 'no'. If set to 'no', the search list in '/etc/resolv.conf' will be ignored (=> fewer lookups => gives up faster). Default value is 'yes'.
  
-HINT: even if you don't have a search list defined, setting this option to 'no' will still be "faster", because an empty search list is in fact search "" (so even if the search list is empty/missing there will still be 2 dns queries, eg. foo+'.' and  oo+""+'.')+HINT: even if you don't have a search list defined, setting this option to 'no' will still be "faster", because an empty search list is in fact search "" (so even if the search list is empty/missing there will still be 2 dns queries, eg. foo+'.' and foo+""+'.')
  
 Example of usage: Example of usage:
Line 1746: Line 2199:
 ==== use_dns_cache ==== ==== use_dns_cache ====
  
-Tells if DNS responses are cached - this means that the internal DNS resolver (instead of the system's stub resolver) will be used.  If set to "off", disables caching of DNS responses and, as side effect, DNS failover. Default is "on". Settings can be changed also during runtime (switch from niternal to system resolver and back).+Tells if DNS responses are cached - this means that the internal DNS resolver (instead of the system's stub resolver) will be used.  If set to "off", disables caching of DNS responses and, as side effect, DNS failover. Default is "on". Settings can be changed also during runtime (switch from internal to system resolver and back).
  
 ==== use_dns_failover ==== ==== use_dns_failover ====
Line 1776: Line 2229:
  
    tcp_accept_aliases= yes|no    tcp_accept_aliases= yes|no
 +   
 +==== 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, such as HAProxy or an AWS' ELB, and allows the load-balancer to provide connection information regarding the upstream client. This enables the use of IP-based ACLs, even behind a 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://www.haproxy.org/download/1.8/doc/proxy-protocol.txt
 +
 +Default value is **no**.
 +
 +<code c>
 +tcp_accept_haproxy=yes
 +</code>
 +
 +==== 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
 +</code>
  
 ==== tcp_accept_no_cl ==== ==== tcp_accept_no_cl ====
Line 1788: Line 2264:
 </code> </code>
  
 +==== 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
 +</code>
 ==== tcp_async ==== ==== tcp_async ====
  
Line 1826: Line 2311:
     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, attempting to lookup first the connection using also local port, not only the local IP and remote IP+port.
 +
 +Default is 0.
 +
 +<code c>
 +tcp_connection_match=1
 +</code>
 ==== tcp_connect_timeout ==== ==== tcp_connect_timeout ====
  
Line 1836: Line 2330:
 ==== 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 is not enabled, it has no effect.+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 is not enabled, it has no effect.
  
   tcp_conn_wq_max = bytes (default 32 K)   tcp_conn_wq_max = bytes (default 32 K)
Line 1955: Line 2449:
 ==== tcp_wq_max ==== ==== tcp_wq_max ====
  
-Maximum bytes queued for write allowed globally. It has no effect if tcp_write_buf is not enabled.+Maximum bytes queued for write allowed globally. It has no effect if tcp_buf_write is not enabled.
  
   tcp_wq_max = bytes (default 10 Mb)   tcp_wq_max = bytes (default 10 Mb)
Line 2189: Line 2683:
  
  
-===== Blacklist Parameters =====+===== Blocklist Parameters =====
  
-==== dst_blacklist_expire ====+==== dst_blocklist_expire ====
  
-**Alias name: dst_blacklist_ttl**+**Alias name: dst_blocklist_ttl**
  
-How much time a blacklisted destination will be kept in the blacklist (w/o any update).+How much time a blocklisted destination will be kept in the blocklist (w/o any update).
  
-  dst_blacklist_expire = time in s (default 60 s)+  dst_blocklist_expire = time in s (default 60 s)
  
-==== 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_gc_interval = time in s (default 60 s)+  dst_blocklist_gc_interval = time in s (default 60 s)
  
-==== dst_blacklist_init ==== +==== dst_blocklist_init ==== 
-If off, the blacklist is not initialized at startup and cannot be enabled runtime, that saves some memory.+If off, the blocklist is not initialized at startup and cannot be enabled runtime, that saves some memory.
  
-  dst_blacklist_init = on | off (default on)+  dst_blocklist_init = on | off (default on)
  
-==== dst_blacklist_mem ==== +==== dst_blocklist_mem ==== 
-Maximum shared memory amount used for keeping the blacklisted destinations.+Maximum shared memory amount used for keeping the blocklisted destinations.
  
-  dst_blacklist_mem = size in Kb (default 250 Kb)+  dst_blocklist_mem = size in Kb (default 250 Kb)
  
-==== use_dst_blacklist ==== +==== use_dst_blocklist ==== 
-Enable the destination blacklist: Each failed send attempt will cause the destination to be added to the blacklist. Before any send, this blacklist will be checked and if a match is found, the send is no longer attempted (an error is returned immediately). +Enable the destination blocklist: Each failed send attempt will cause the destination to be added to the blocklist. Before any send, this blocklist will be checked and if a match is found, the send is no longer attempted (an error is returned immediately). 
  
-Note: using the blacklist incurs a small performance penalty.+Note: using the blocklist incurs a small performance penalty.
  
-See also doc/dst_blacklist.txt.+See also doc/dst_blocklist.txt.
  
-  use_dst_blacklist = on | off (default off)+  use_dst_blocklist = on | off (default off)
  
 ===== Real-Time Parameters ===== ===== Real-Time Parameters =====
Line 2365: Line 2859:
  
 Force to send the message from the specified socket (it _must_ be one of the sockets specified with the "listen" directive). If the protocol doesn't match (e.g. UDP message "forced" to a TCP socket) the closest socket of the same protocol is used. Force to send the message from the specified socket (it _must_ be one of the sockets specified with the "listen" directive). If the protocol doesn't match (e.g. UDP message "forced" to a TCP socket) the closest socket of the same protocol is used.
 +
 +This function does not support pseudo-variables, use the set_send_socket function from the corex module instead.
  
 Example of usage: Example of usage:
Line 2379: Line 2875:
  
 adds a tcp port alias for the current connection (if tcp). adds a tcp port alias for the current connection (if tcp).
-Usefull if you want to send all the trafic to port_alias through+Useful if you want to send all the trafic to port_alias through
 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 2409: Line 2905:
 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://www.kamailio.org/dokuwiki/doku.php/tutorials:openser-flag-operations or [[utils:flags]].+For more see: https://www.kamailio.org/wiki/tutorials/kamailio-flag-operations.
  
 Example of usage: Example of usage:
Line 2498: Line 2994:
 </code> </code>
  
 +See also the FAQ for how the function return code is evaluated:
 +
 +  * https://www.kamailio.org/wiki/tutorials/faq/main#how_is_the_function_return_cod
 ==== revert_uri ==== ==== revert_uri ====
  
Line 2554: Line 3053:
 Example of usage: Example of usage:
  
-    rewriteuri("sip:test@openser.org");+    rewriteuri("sip:test@kamailio.org");
  
 ==== rewriteuserpass ==== ==== rewriteuserpass ====
Line 2585: Line 3084:
  
  
 +==== selval ====
  
 +Select a value based on conditional expression.
 +
 +Prototype:
 +
 +<code c>
 +selval(evalexpr, valexp1, valexpr2)
 +</code>
 +
 +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/operator
 +
 +Example:
 +
 +<code c>
 +$var(x) = selval($Ts mod 2, "true/" + $ru, "false/" + $rd);
 +</code>
 +
 +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 2592: Line 3109:
 Example of usage: Example of usage:
  
-    set_advertised_address("openser.org");+    set_advertised_address("kamailio.org");
  
 ==== set_advertised_port ==== ==== set_advertised_port ====
Line 2606: Line 3123:
 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 for tcp/tls).+  * 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 for TCP/TLS).
  
   * onreply_route[0] (stateless): equivalent to set_reply_*() (it's better to use set_reply_* though)   * onreply_route[0] (stateless): equivalent to set_reply_*() (it's better to use set_reply_* though)
Line 2685: Line 3202:
 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://www.kamailio.org/dokuwiki/doku.php/tutorials:openser-flag-operations .+For more see: https://www.kamailio.org/wiki/tutorials/kamailio-flag-operations .
  
 Example of usage: Example of usage:
Line 2719: Line 3236:
  
 ==== userphone ==== ==== userphone ====
 +
 +Add "user=phone" parameter to R-URI.
  
 ===== Custom Global Parameters ===== ===== Custom Global Parameters =====
Line 2730: Line 3249:
  
 </code> </code>
 +
 +The value can be a quoted string or integer number.
  
 Example: Example:
Line 2748: Line 3269:
 $ru = "sip:" + $rU + "@" + $sel(cfg_get.pstn.gw_ip); $ru = "sip:" + $rU + "@" + $sel(cfg_get.pstn.gw_ip);
 </code> </code>
 +
 +**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  by kamailio. These keywords are: "yes", "true", "on", "enable", "no", "false", "off", "disable", "udp", "UDP", "tcp", "TCP", "tls", "TLS", "sctp", "SCTP", "ws", "WS", "wss", "WSS", "inet", "INET", "inet6", "INET6", "sslv23", "SSLv23", "SSLV23", "sslv2", "SSLv2", "SSLV2", "sslv3", "SSLv3", "SSLV3", "tlsv1", "TLSv1", "TLSV1"
  
 ===== Routing Blocks ===== ===== Routing Blocks =====
Line 2914: Line 3437:
 <code c> <code c>
 reply_route { reply_route {
-  if(status=="128"") {+  if(status=="128") {
     drop;     drop;
   }   }
Line 2925: Line 3448:
  
  
-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 'onreply_route' must be armed for the SIP requests whose replies should be processed within it, via t_on_reply("onreply_route_index"). The 'onreply_route' must be armed for the SIP requests whose replies should be processed within it, via t_on_reply("onreply_route_index").
  
-Main 'onreply_route' block is executed before a possible tm 'onreply_route' block.+Core 'reply_route' block is executed before a possible **tm** 'onreply_route' block.
  
 <code c> <code c>
Line 2956: Line 3479:
 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, send(), log(), textops::search()). 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, send(), log(), textops::search()).
  
-In this route the final destination of the message is available an can be checked (with snd_ip, snd_port, to_ip, to_port, snd_proto, snd_af).+In this route the final destination of the message is available and can be checked (with snd_ip, snd_port, to_ip, to_port, snd_proto, snd_af).
  
 This route is executed only when forwarding requests - it is not executed for replies, retransmissions, or locally generated messages (e.g. via fifo uac). This route is executed only when forwarding requests - it is not executed for replies, retransmissions, or locally generated messages (e.g. via fifo uac).
Line 2983: Line 3506:
   * 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:worker-one-init]** - executed by core after the first udp sip worker process executed the child_init() for all modules, before starting to process sip traffic
 +    * note that due to forking, other sip workers can get faster to listening for sip traffic
 +
 +<code c>
 +event_route[core:worker-one-init] {
 +        xlog("L_INFO","Hello world\n");
 +}
 +</code>
 +
 +  * **event_route[core:msg-received]** - executed when a message is received from the network. It runs with a faked request and makes available the $rcv(key) variables to access what was received and related attribtues.
 +    * 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:msg-received] {
 +  xlog("rcv on $rcv(af)/$rcv(proto): ($rcv(len)) [$rcv(buf)] from [$rcv(srcip):$rcv(srcport)] to [$rcv(rcvip):$rcv(rcvport)]\n");
 +  if($rcv(srcip) == "1.2.3.4") {
 +    drop;
 +  }
 +}
 +</code>
 +
 +  * **event_route[core:pre-routing]** - executed by core on receiving SIP traffic before running request_route or reply_route.
 +    * 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="name=reg;workers=4"
 +...
 +event_route[core:pre-routing] {
 +    xinfo("pre-routing rules\n");
 +    if(is_method("REGISTER")) {
 +        # delegate processing of REGISTERs to a special group of workers
 +        if(sworker_task("reg")) {
 +            drop;
 +        }
 +    }
 +}
 +</code>
 +
 +  * ** event_route[core:receive-parse-error]** - executed by core on receiving a broken SIP message that can not be parsed.
 +    * 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:receive-parse-error] {
 +        xlog("got an parsing error from $si:$sp, message $mb\n");
 +}
 +
 +</code>
 +
 +=== 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:mod-init]** - executed by **htable** module after all modules have been initialised. Good for initialising values in hash tables.   * **event_route[htable:mod-init]** - executed by **htable** module after all modules have been initialised. Good for initialising values in hash tables.
 <code c> <code c>
Line 3024: Line 3604:
   * **event_route [tm:branch-failure]** - executed on all failure responses.   * **event_route [tm:branch-failure]** - executed on all failure responses.
 <code c> <code c>
-event_route [tm:failure-branch] { # Handle failure response+request_route { 
 +    ... 
 +    t_on_branch_failure("myroute"); 
 +    t_relay(); 
 +
 + 
 +event_route[tm:branch-failure:myroute] {
   xlog("L_INFO", "Handling $T_reply_code response to $rm to <$ru>\n");   xlog("L_INFO", "Handling $T_reply_code response to $rm to <$ru>\n");
   if (t_check_status("430")) { # Outbound flow failed   if (t_check_status("430")) { # Outbound flow failed
Line 3033: Line 3619:
   }   }
 } }
 +
 </code> </code>
  
Line 3066: Line 3653:
   ||      logical OR   ||      logical OR
   !       logical NOT   !       logical NOT
-  [ ... ] test operator - inside can be any arithmetic expression 
 </code> </code>
  
Line 3078: Line 3664:
     }     }
  
 +See also the FAQ for how the function return code is evaluated:
  
 +  * https://www.kamailio.org/wiki/tutorials/faq/main#how_is_the_function_return_cod
 ==== switch ==== ==== switch ====
  
Line 3207: Line 3795:
   * ^ : bitwise XOR   * ^ : bitwise XOR
   * ~ : bitwise NOT   * ~ : bitwise NOT
-  * << : bitwise left shift +  * <nowiki><<</nowiki> : bitwise left shift 
-  * >> : bitwise right shift+  * <nowiki>>></nowiki> : bitwise right shift 
  
 Example: Example:
Line 3260: Line 3849:
                        string (equivalent to expr=="").                        string (equivalent to expr=="").
       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**:
 +
 +<code>
 +# kamailio -h
 +
 +version: kamailio 5.4.0-dev4 (x86_64/darwin) 8c1864
 +Usage: kamailio [options]
 +Options:
 +    -a mode      Auto aliases mode: enable with yes or on,
 +                  disable with no or off
 +    --alias=val  Add an alias, the value has to be '[proto:]hostname[:port]'
 +                  (like for 'alias' global parameter)
 +    -A define    Add config pre-processor define (e.g., -A WITH_AUTH,
 +                  -A 'FLT_ACC=1', -A 'DEFVAL="str-val"')
 +    -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           Debugging mode (multiple -d increase the level)
 +    -D           Control how daemonize is done:
 +                  -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: /usr/local/etc/kamailio/kamailio.cfg)
 +    -g gid       Change gid (group id)
 +    -G file      Create a pgid file
 +    -h           This help message
 +    --help       Long option for `-h`
 +    -I           Print more internal compile flags and options
 +    -K           Turn on "via:" host checking when forwarding replies
 +    -l address   Listen on the specified address/interface (multiple -l
 +                  mean listening on more addresses). The address format is
 +                  [proto:]addr_lst[:port][/advaddr],
 +                  where proto=udp|tcp|tls|sctp,
 +                  addr_lst= addr|(addr, addr_lst),
 +                  addr=host|ip_address|interface_name and
 +                  advaddr=addr[:port] (advertised address).
 +                  E.g: -l localhost, -l udp:127.0.0.1:5080, -l eth0:5062,
 +                  -l udp:127.0.0.1:5080/1.2.3.4:5060,
 +                  -l "sctp:(eth0)", -l "(eth0, eth1, 127.0.0.1):5065".
 +                  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: /usr/local/lib64/kamailio/modules)
 +    -m nr        Size of shared memory allocated in Megabytes
 +    --modparam=modname:paramname:type:value set the module parameter
 +                  type has to be 's' for string value and 'i' for int value,
 +                  example: --modparam=corex:alias_subdomains:s:kamailio.org
 +    -M nr        Size of private memory allocated, in Megabytes
 +    -n processes Number of child processes to fork per interface
 +                  (default: 8)
 +    -N           Number of tcp child processes (default: equal to `-n')
 +    -O nr        Script optimization level (debugging option)
 +    -P file      Create a pid file
 +    -Q           Number of sctp child processes (default: equal to `-n')
 +    -r           Use dns to check if is necessary to add a "received="
 +                  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           disable sctp
 +    -t dir       Chroot to "dir"
 +    -T           Disable tcp
 +    -u uid       Change uid (user id)
 +    -v           Version number
 +    --version    Long option for `-v`
 +    -V           Alternative for `-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       Runtime dir path
 +    -w dir       Change the working directory to "dir" (default: "/")
 +    -W type      poll method (depending on support in OS, it can be: poll,
 +                  epoll_lt, epoll_et, sigio_rt, select, kqueue, /dev/poll)
 +</code>
 +
 +==== 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:data**.
 +
 +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') from the value of the log message field
 +      * **N** - do not add EOL at the end of JSON document
 +
 +Example of JSON logs when running Kamailio with "**--log-engine=json:M**" :
 +
 +<code>
 +{ "idx": 1, "pid": 18239, "level": "DEBUG", "module": "maxfwd", "file": "mf_funcs.c", "line": 74, "function": "is_maxfwd_present", "logprefix": "{1 1 OPTIONS 715678756@192.168.188.20} ", "message": "value = 70 " }
 +
 +{ "idx": 1, "pid": 18239, "level": "DEBUG", "module": "core", "file": "core/socket_info.c", "line": 644, "function": "grep_sock_info", "logprefix": "{1 1 OPTIONS 715678756@192.168.188.20} ", "message": "checking if host==us: 9==9 && [127.0.0.1] == [127.0.0.1]" }
 +
 +</code>
cookbooks/devel/core.txt · Last modified: 2022/04/11 17:10 by bkaufman