Kamailio SIP Server Wiki

User Tools

Site Tools

Trace:
cookbooks:devel:core

Differences

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

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
cookbooks:devel:core [2019/05/16 15:47] – [auto_bind_ipv6] micondacookbooks:devel:core [2022/04/11 15:10] (current) – [substdefs] bkaufman
Line 1: Line 1:
-====== Kamailio SIP Server v5.3.x (devel): Core Cookbook ======+====== Core Cookbook ====== 
 + 
 +Version: Kamailio SIP Server v5.6.x (devel)
  
 ===== Overview ===== ===== Overview =====
Line 9: Line 11:
 ===== Structure ===== ===== Structure =====
  
-The structure of the kamailio.cfg can be seen as thee parts:+The structure of the kamailio.cfg can be seen as three parts:
  
   * global parameters   * global parameters
Line 136: Line 138:
  
   "this is a string value"   "this is a string value"
-  'this is another string value"+  'this is another string value'
  
 // next is a boolean // next is a boolean
Line 253: Line 255:
   * **#!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:
Line 353: Line 360:
     * text on the same line as the directive will cause problems. Keep the directive lines clean and only comment on a line before or after.      * text on the same line as the directive will cause problems. Keep the directive lines clean and only comment on a line before or after. 
  
 +==== defenv ====
 +
 +Preprocessor directive to define an ID to the value of an environment variable with the name ENVVAR.
 +
 +<code c>
 +#!defenv ID=ENVVAR
 +</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.
 +
 +==== defenvs ====
 +
 +Similar to **#!defenv**, but the value is defined in between double quotes to make it convenient to be used as a string token.
 +
 +<code c>
 +#!defenvs ENVVAR
 +#!defenvs ID=ENVVAR
 +</code>
 ==== subst ==== ==== subst ====
  
Line 388: Line 439:
  
 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). 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).
 +
 +==== trydefenv ====
 +
 +<code c>
 +#!trydefenv ID=ENVVAR
 +</code>
 +
 +Similar to **defenv**, but will not error if the environmental variable is not set.  This allows for boolean defines via system ENVVARs.  For example, using an environmental variable to toggle loading of db_mysql:
 +
 +<code c>
 +#!trydefenv WITH_MYSQL
 +
 +#!ifdef WITH_MYSQL
 +loadmodule "db_mysql.so"
 +#!ifdef
 +</code>
 +
 +==== trydefenvns ====
 +
 +Similar to **#!trydefenv**, but the value is defined in between double quotes to make it convenient to be used as a string token.
 +
 +<code c>
 +#!trydefenvs ENVVAR
 +#!trydefenvs ID=ENVVAR
 +</code>
 +
 ===== Core Keywords ===== ===== Core Keywords =====
  
Line 722: Line 799:
 ==== 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 731: Line 808:
     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 753: Line 883:
 ==== bind_ipv6_link_local ==== ==== bind_ipv6_link_local ====
  
-Try to bind link local IPv6 addresses. Default is 0.+If set to 1, try to bind also IPv6 link local addresses 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: Example:
Line 965: Line 1095:
 </code> </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 ==== ==== kemi.onsend_route_callback ====
  
Line 1006: Line 1150:
 kemi.onsend_route_callback="ksr_my_reply_route" kemi.onsend_route_callback="ksr_my_reply_route"
 </code> </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 1020: Line 1179:
 ==== 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 1030: Line 1189:
 ==== 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 1053: Line 1212:
 ==== 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 1068: Line 1227:
  
 <code c> <code c>
-    listen=udp:[2a02:1850:1:1::13]:5060+    listen=udp:[2a02:1850:1:1::18]:5060
 </code> </code>
  
Line 1074: Line 1233:
  
 <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 1080: Line 1239:
  
 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.
 +
 +As of 5.6, there is now a **virtual** identifier which can be added to the end of each listen directive. This can be used in combination with any other identifier, but must be added at the end of the line.
 +
 +<code c>
 +    listen=udp:10.1.1.1:5060 virtual
 +    listen=udp:10.0.0.10:5060 name "s1" virtual
 +    listen=udp:10.10.10.10:5060 advertise 11.11.11.11:5060 virtual
 +    listen=udp:10.10.10.20:5060 advertise "mysipdomain.com" name "s3" virtual
 +</code>
 +
 +The **virtual** identifier is meant for use in situations where you have a floating/virtual IP address on your system that may not always be active on the system. It is particularly useful for active/active virtual IP situations, where otherwise things like usrloc PATH support can break due to incorrect "check_self" results.
 +
 +This identifier will change the behaviour of how "myself", "is_myself" or "check_self" matches against traffic destined to this IP address. By default, Kamailio always considers traffic destined to a listen IP as "local" regardless of if the IP is currently locally active. With this flag set, Kamailio will do an extra check to make sure the IP is currently a local IP address before considering the traffic as local. 
 +
 +This means that if Kamailio is listening on an IP that is not currently local, it will recognise that, and can relay the traffic to another Kamailio node as needed, instead of thinking it always needs to handle the traffic.
 +
 ==== loadmodule ==== ==== loadmodule ====
  
Line 1097: Line 1288:
     loadmodule "dialplan.so"     loadmodule "dialplan.so"
 </code> </code>
 +
 +==== loadmodulex ====
 +
 +Similar to **loadmodule** with the ability to evaluate variables in its parameter.
  
 ==== loadpath ==== ==== loadpath ====
Line 1120: Line 1315:
 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 1222: Line 1428:
 ==== maxbuffer ==== ==== maxbuffer ====
  
-The size in bytes not to be exceeded during the auto-probing procedure of descovering the maximum buffer size for receiving UDP messages. Default value is 262144.+The size in bytes not to be exceeded during the auto-probing procedure of discovering and increasing the maximum OS buffer size for receiving UDP messages (socket option SO_RCVBUF). Default value is 262144.
  
 Example of usage: Example of usage:
Line 1228: Line 1434:
     maxbuffer=65536     maxbuffer=65536
  
 +Note: it is not the size of the internal SIP message receive buffer.
 ==== max_branches ==== ==== max_branches ====
  
Line 1328: Line 1535:
 It can be set via config reload framework. It can be set via config reload framework.
  
-Default is 0 (disabled).+Default is 1 (enabled).
  
 <code c> <code c>
Line 1370: Line 1577:
   * 4 - summary of pkg used blocks   * 4 - summary of pkg used blocks
   * 8 - summary of shm used blocks   * 8 - summary of shm used blocks
 +  * 16 - short status
  
 If set to 0, nothing is printed. If set to 0, nothing is printed.
  
-Default value: 3+Default value: 12
  
 Example: Example:
Line 1405: Line 1613:
  
 ==== 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 1414: Line 1623:
 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 1467: Line 1679:
 <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 1506: Line 1734:
 ==== route_locks_size ==== ==== route_locks_size ====
  
-Set the number of mutex locks to be used for synchronizing the execution of messages sharing the same Call-Id. In other words, enables Kamailio to execute sequentially the requests and replies received within the same dialog -- a new message received within the same dialog waits until the previous one is routed out.+Set the number of mutex locks to be used for synchronizing the execution of config script for messages sharing the same Call-Id. In other words, enables Kamailio to execute 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 (children+For smaller impact on parallel processing, its value it should be at least twice the number of Kamailio processes (all children processes).
  
 Example: Example:
Line 1515: Line 1743:
 route_locks_size = 256 route_locks_size = 256
 </code> </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 ====
  
Line 1555: Line 1785:
  
 shm_mem_size = 64 (default 64) shm_mem_size = 64 (default 64)
 +
 +==== sip_parser_log ====
 +
 +Log level for printing debug messages for some of the SIP parsing errors.
 +
 +Default: 0 (L_WARN)
 +
 +<code c>
 +sip_parser_log = 1
 +</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 1641: Line 1895:
  
  
 +==== 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 1672: Line 1932:
  
   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 1713: Line 1982:
    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 1760: Line 2066:
 ===== DNS Parameters ===== ===== DNS Parameters =====
  
-Note: See also file doc/dns.txt for details about Kamailio's DNS client.+Note: See also file doc/tutorials/dns.txt for details about Kamailio's DNS client.
  
 Kamailio has an internal DNS resolver with caching capabilities. If this caching resolver is activated (default setting) then the system's stub resolver won't be used. Thus, also local name resolution configuration like /etc/hosts entries will not be used. If the DNS cache is deactivated (use_dns_cache=no), then system's resolver will be used. The DNS failover functionality in the tm module references directly records in the DNS cache (which saves a lot of memory) and hence DNS based failover only works if the internal DNS cache is enabled. Kamailio has an internal DNS resolver with caching capabilities. If this caching resolver is activated (default setting) then the system's stub resolver won't be used. Thus, also local name resolution configuration like /etc/hosts entries will not be used. If the DNS cache is deactivated (use_dns_cache=no), then system's resolver will be used. The DNS failover functionality in the tm module references directly records in the DNS cache (which saves a lot of memory) and hence DNS based failover only works if the internal DNS cache is enabled.
Line 1903: Line 2209:
 **Alias name: dns_srv_loadbalancing** **Alias name: dns_srv_loadbalancing**
  
-Enable dns srv weight based load balancing (see doc/dns.txt)+Enable dns srv weight based load balancing (see doc/tutorials/dns.txt)
  
   dns_srv_lb = yes | no (default no)   dns_srv_lb = yes | no (default no)
Line 1919: Line 2225:
  
 ==== dns_try_naptr ==== ==== dns_try_naptr ====
-Enable NAPTR support according to RFC 3263 (see doc/dns.txt for more info)+Enable NAPTR support according to RFC 3263 (see doc/tutorials/dns.txt for more info)
          
   dns_try_naptr = yes | no (default no)   dns_try_naptr = yes | no (default no)
Line 1930: Line 2236:
 dns_tls_pref=10 and dns_sctp_pref=20. To use the remote site preferences set all dns_*_pref to the same positive value (e.g. dns_udp_pref=1, dns_tls_pref=10 and dns_sctp_pref=20. To use the remote site preferences set all dns_*_pref to the same positive value (e.g. dns_udp_pref=1,
 dns_tcp_pref=1, dns_tls_pref=1, dns_sctp_pref=1). To completely ignore NAPTR records for a specific protocol, set the corresponding protocol  dns_tcp_pref=1, dns_tls_pref=1, dns_sctp_pref=1). To completely ignore NAPTR records for a specific protocol, set the corresponding protocol 
-preference to -1 (or any other negative number). (see doc/dns.txt for more info)+preference to -1 (or any other negative number). (see doc/tutorials/dns.txt for more info)
  
   dns_{udp,tcp,tls,sctp}_pref = number   dns_{udp,tcp,tls,sctp}_pref = number
Line 1982: Line 2288:
  
 Please note that enabling this option will reject any inbound TCP connection that does not conform to the PROXY-protocol spec. Please note that enabling this option will reject any inbound TCP connection that does not conform to the PROXY-protocol spec.
 +
 +For reference: A PROXY protocol - https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt
  
 Default value is **no**. Default value is **no**.
Line 2009: Line 2317:
 </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 2047: Line 2364:
     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 2149: Line 2475:
 tcp_rd_buf_size=65536 tcp_rd_buf_size=65536
 </code> </code>
 +
 +==== tcp_reuse_port ====
 +
 +Allows reuse of TCP ports. This means,for example, that the same TCP ports on which Kamailio is listening on, can be used as source ports of new TCP connections when acting as an UAC. Kamailio must have been compiled in a system implementing SO_REUSEPORT (Linux > 3.9.0, FreeBSD, OpenBSD, NetBSD, MacOSX). This parameter takes effect only if also the system on which Kamailio is running on supports SO_REUSEPORT.
 +
 +  tcp_reuse_port = yes (default no)
 +
 +==== tcp_script_mode ====
 +
 +Specify if connection should be closed (set to CONN_ERROR) if processing the received message results in error (that can also be due to negative return code from a configuration script main route block). If set to 1, the processing continues with the connection open.
 +
 +Default 0 (close connection)
 +
 +<code>
 +tcp_script_mode = 1
 +</code>
 +
 ==== tcp_send_timeout ==== ==== tcp_send_timeout ====
  
Line 2165: Line 2508:
  
 ==== tcp_syncnt ==== ==== tcp_syncnt ====
 +
 Number of SYN retransmissions before aborting a connect attempt (see linux tcp(7) TCP_SYNCNT). Linux only. Number of SYN retransmissions before aborting a connect attempt (see linux tcp(7) TCP_SYNCNT). Linux only.
  
   tcp_syncnt = number of syn retr. (default not set)   tcp_syncnt = number of syn retr. (default not set)
 +
 +
 +==== tcp_wait_data ====
 +
 +Specify how long to wait (in milliseconds) to wait for data on tcp connections in certain cases. Now applies when reading on tcp connection for haproxy protocol.
 +
 +Default: 5000ms (5secs)
 +
 +<code c>
 +tcp_wait_data = 10000
 +</code>
  
 ==== tcp_wq_blk_size ==== ==== tcp_wq_blk_size ====
Line 2180: Line 2535:
   tcp_wq_max = bytes (default 10 Mb)   tcp_wq_max = bytes (default 10 Mb)
      
-==== tcp_reuse_port ==== 
- 
-Allows reuse of TCP ports. This means,for example, that the same TCP ports on which Kamailio is listening on, can be used as source ports of new TCP connections when acting as an UAC. Kamailio must have been compiled in a system implementing SO_REUSEPORT (Linux > 3.9.0, FreeBSD, OpenBSD, NetBSD, MacOSX). This parameter takes effect only if also the system on which Kamailio is running on supports SO_REUSEPORT. 
- 
-  tcp_reuse_port = yes (default no) 
  
 ===== TLS Parameters ===== ===== TLS Parameters =====
Line 2410: Line 2760:
  
  
-===== 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 2586: Line 2936:
  
 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 2719: Line 3071:
 </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 2806: Line 3161:
  
  
 +==== 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 2942: Line 3315:
  
 Add "user=phone" parameter to R-URI. Add "user=phone" parameter to R-URI.
 +
 ===== Custom Global Parameters ===== ===== Custom Global Parameters =====
  
Line 3235: Line 3609:
 } }
 </code> </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 === === Module Event Routes ===
  
Line 3328: Line 3730:
   ||      logical OR   ||      logical OR
   !       logical NOT   !       logical NOT
-  [ ... ] test operator - inside can be any arithmetic expression 
 </code> </code>
  
Line 3340: Line 3741:
     }     }
  
 +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 3523: Line 3926:
                        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
 +      * **j** - the log prefix and message fields are printed in JSON structure format, detecting if they are enclosed in between **{ }** or adding them as a **text** field
 +      * **M** - strip EOL ('\n') from the value of the log message field
 +      * **N** - do not add EOL at the end of JSON document
 +      * **p** - the log prefix is printed as it is in the root json document, it has to start with comma (**,**) and be a valid set of json fields
 +      * **U** - CEE (Common Event Expression) schema format - https://cee.mitre.org/language/1.0-beta1/core-profile.html
 +
 +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>
 +
 +Example config for printing log message with **j** flag:
 +
 +<code>
 +xinfo("{ \"src_ip\": \"$si\", \"method\": \"$rm\", \"text\": \"request received\" }");
 +</code>
 +
 +Example config for printing log messages with **p** flag:
 +
 +<code>
 +log_prefix=", \"src_ip\": \"$si\", \"tv\": $TV(Sn), \"mt\": $mt, \"ua\": \"$(ua{s.escape.common})\", \"cseq\": \"$hdr(CSeq)\""
 +</code>
cookbooks/devel/core.1558021655.txt.gz · Last modified: 2019/05/16 15:47 by miconda
Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki