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
cookbooks:devel:core [2020/04/09 10:59]
miconda [Operators]
cookbooks:devel:core [2021/04/27 09:32] (current)
miconda
Line 1: Line 1:
-====== Kamailio SIP Server v5.4.x (devel): Core Cookbook ======+====== Core Cookbook ====== 
 + 
 +Version: Kamailio SIP Server v5.6.x (devel)
  
 ===== Overview ===== ===== Overview =====
Line 358: 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 727: 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 736: 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 970: 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 1011: 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 1025: 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 1118: 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 1141: 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 1426: 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 1435: 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 1543: Line 1682:
 ==== 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 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.+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). For smaller impact on parallel processing, its value it should be at least twice the number of Kamailio processes (all children processes).
Line 1594: 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) ====
Line 1680: 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 1761: 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 2478: 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 2789: 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 2876: 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 3306: Line 3533:
 } }
 </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 3399: Line 3654:
   ||      logical OR   ||      logical OR
   !       logical NOT   !       logical NOT
-  [ ... ] test operator - inside can be any arithmetic expression 
 </code> </code>
  
Line 3411: 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 3678: Line 3934:
     -W type      poll method (depending on support in OS, it can be: poll,     -W type      poll method (depending on support in OS, it can be: poll,
                   epoll_lt, epoll_et, sigio_rt, select, kqueue, /dev/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> </code>
cookbooks/devel/core.1586422796.txt.gz · Last modified: 2020/04/09 10:59 by miconda