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 [2020/06/19 10:35]
linuxmaniac [Kamailio SIP Server v5.4.x (devel): Core Cookbook]
Line 1: Line 1:
-====== Kamailio SIP Server v5.1.x (devel): Core Cookbook ======+====== Kamailio SIP Server v5.5.x (devel): Core Cookbook ======
  
 ===== Overview ===== ===== Overview =====
Line 9: Line 9:
 ===== Structure ===== ===== Structure =====
  
-The structure of the kamailio.cfg can be seen as thee parts:+The structure of the kamailio.cfg can be seen as three parts:
  
   * global parameters   * global parameters
Line 47: Line 47:
 </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 136:
  
   "this is a string value"   "this is a string value"
-  'this is another string value"+  'this is another string value'
  
 // next is a boolean // next is a boolean
Line 198: Line 209:
 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 245:
  
 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 285:
 #!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 370: Line 386:
 Similar to **subst**, but in addition it adds a **#!define ID subst**. Similar to **subst**, but in addition it adds a **#!define ID subst**.
  
 +==== substdefs ====
 +
 +<code c>
 +#!substdefs "/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 689:
 ==== 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 701:
     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 710:
     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 724:
 </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 ====
  
Line 723: Line 748:
 ==== auto_bind_ipv6 ==== ==== auto_bind_ipv6 ====
  
-When turned on, Kamailio will automatically bind to all IPv6 addresses (much like the default behaviour for IPv4).+When turned on, Kamailio will automatically bind to all IPv6 addresses (much like the default behaviour for IPv4). Default is 0.
  
 Example: Example:
Line 729: Line 754:
 <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 825:
 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 834:
   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 888:
 ==== flags ==== ==== flags ====
  
-**Alias name: bool**+SIP message (transaction) flags can have string names.  
 +The //name// for flags cannot be used for **branch** or **script flags**(*) 
 + 
 + 
 +<code c> 
 +... 
 +flags 
 +  FLAG_ONE   : 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 904: Line 956:
   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>
 +
 +==== 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>
 ==== latency_cfg_log ==== ==== latency_cfg_log ====
  
Line 928: Line 1035:
 ==== latency_limit_db ==== ==== latency_limit_db ====
  
-Limit of latency in ms for db operations. If a db operation executed via DB API v1 takes longer that its value, a message is printed in the logs, showing the first 50 characters of the db query.+Limit of latency in us (micro-seconds) 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 1058:
 ==== 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 1073:
  
 <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 1079:
  
 <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 1085:
  
 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 1107:
 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 1062: Line 1185:
 ==== log_prefix ==== ==== log_prefix ====
  
-Specify the text to be prefixed to the log messages printed by Kamailio while processing a SIP message. It can contain script variables that are evaluated at runtime (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 1199:
 ==== 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 1225:
  
     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 1349:
 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 1364:
 ==== 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 1328: Line 1472:
 ==== pv_buffer_size ==== ==== pv_buffer_size ====
  
-The size in bytes of internal buffer to print dynamic strings with pseudo-variables inside. The default value is 8192 (8kB).+The size in bytes of internal buffer to print dynamic strings with pseudo-variables inside. The default value is 8192 (8kB). Please keep in mind that for xlog messages, there is a dedicated module parameter to set the internal buffer size.
  
 Example of usage: Example of usage:
Line 1344: Line 1488:
 <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 1518:
 <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 1539:
  
     reply_to_via=0     reply_to_via=0
 +    
 +
 +==== route_locks_size ====
 +
 +Set the number of mutex locks to be used for synchronizing the execution of 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 1588:
  
 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_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 1680:
  
  
 +==== 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 1717:
  
   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 1744:
 <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 1557: Line 1778:
      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 1834:
 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 1992:
 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 2000:
 ==== 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 2030:
  
    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 2065:
 </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 2112:
     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 2131:
 ==== 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 2250:
 ==== 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 2365: Line 2660:
  
 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 2676:
  
 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 2706:
 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 2554: Line 2851:
 Example of usage: Example of usage:
  
-    rewriteuri("sip:test@openser.org");+    rewriteuri("sip:test@kamailio.org");
  
 ==== rewriteuserpass ==== ==== rewriteuserpass ====
Line 2592: Line 2889:
 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 2903:
 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 2982:
 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 3016:
  
 ==== userphone ==== ==== userphone ====
 +
 +Add "user=phone" parameter to R-URI.
  
 ===== Custom Global Parameters ===== ===== Custom Global Parameters =====
Line 2730: Line 3029:
  
 </code> </code>
 +
 +The value can be a quoted string or integer number.
  
 Example: Example:
Line 2748: Line 3049:
 $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 3217:
 <code c> <code c>
 reply_route { reply_route {
-  if(status=="128"") {+  if(status=="128") {
     drop;     drop;
   }   }
Line 2925: Line 3228:
  
  
-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 3259:
 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 3286:
   * 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>
 +=== 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 3356:
   * **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 3371:
   }   }
 } }
 +
 </code> </code>
  
Line 3207: Line 3546:
   * ^ : 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 3600:
                        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: 2020/08/13 14:59 by miconda