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 [2019/01/02 09:19]
mslehto [onreply_route] clarify core reply_route vs. TM onreply_route
cookbooks:devel:core [2021/04/27 09:32]
miconda
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 53: Line 55:
 </code> </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 131: 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 240: Line 247:
  
 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 - switch 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:
Line 348: 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.
 +    
 ==== subst ==== ==== subst ====
  
Line 376: Line 424:
 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 710: Line 765:
 ==== 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 719: Line 774:
     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 731: Line 839:
 ==== 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 737: Line 845:
 <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 861: Line 979:
 ==== 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 926: Line 1061:
 </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 938: Line 1087:
 <code c> <code c>
 kemi.onsend_route_callback="ksr_my_onsend_route" 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> </code>
  
Line 953: Line 1116:
 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 967: Line 1145:
 ==== 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 977: Line 1155:
 ==== 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 1000: Line 1178:
 ==== 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 1015: Line 1193:
  
 <code c> <code c>
-    listen=udp:[2a02:1850:1:1::13]:5060+    listen=udp:[2a02:1850:1:1::18]:5060
 </code> </code>
  
Line 1021: Line 1199:
  
 <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 1027: Line 1205:
  
 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 1044: Line 1238:
     loadmodule "dialplan.so"     loadmodule "dialplan.so"
 </code> </code>
 +
 +==== loadmodulex ====
 +
 +Similar to **loadmodule** with the ability to evaluate variables in its parameter.
  
 ==== loadpath ==== ==== loadpath ====
Line 1067: Line 1265:
 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 1111: Line 1320:
 ==== 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 1121: Line 1334:
 ==== 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 1269: Line 1484:
 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 1346: Line 1561:
  
 ==== 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 1355: Line 1571:
 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 1392: Line 1611:
 ==== 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 1408: Line 1627:
 <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 1422: Line 1657:
 <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 1431: Line 1678:
  
     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 ====
  
Line 1471: Line 1733:
  
 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 1557: Line 1843:
  
  
 +==== 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 1588: Line 1880:
  
   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 1629: Line 1930:
    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 1898: Line 2236:
  
 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 1925: Line 2265:
 </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 1963: Line 2312:
     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 2326: Line 2684:
  
  
-===== 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 2502: Line 2860:
  
 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 2635: Line 2995:
 </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 2722: Line 3085:
  
  
 +==== 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 2858: Line 3239:
  
 Add "user=phone" parameter to R-URI. Add "user=phone" parameter to R-URI.
 +
 ===== Custom Global Parameters ===== ===== Custom Global Parameters =====
  
Line 3056: Line 3438:
 <code c> <code c>
 reply_route { reply_route {
-  if(status=="128"") {+  if(status=="128") {
     drop;     drop;
   }   }
Line 3125: Line 3507:
   * 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:
Line 3136: Line 3520:
 } }
 </code> </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.
Line 3176: Line 3605:
   * **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 3185: Line 3620:
   }   }
 } }
 +
 </code> </code>
  
Line 3218: Line 3654:
   ||      logical OR   ||      logical OR
   !       logical NOT   !       logical NOT
-  [ ... ] test operator - inside can be any arithmetic expression 
 </code> </code>
  
Line 3230: Line 3665:
     }     }
  
 +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 3413: Line 3850:
                        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