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 [2021/01/04 10:53]
miconda [loadmodule]
cookbooks:devel:core [2022/04/11 17:10] (current)
bkaufman [substdefs]
Line 1: Line 1:
 ====== Core Cookbook ====== ====== Core Cookbook ======
  
-Version: Kamailio SIP Server v5.5.x (devel)+Version: Kamailio SIP Server v5.6.x (devel) 
 ===== Overview ===== ===== Overview =====
  
Line 394: Line 395:
  
 It is a simplified alternative of using **#!substdef** with **$env(NAME)** in the replacement part. 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 430: 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 1220: Line 1255:
  
 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. 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 1377: 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 1383: Line 1434:
     maxbuffer=65536     maxbuffer=65536
  
 +Note: it is not the size of the internal SIP message receive buffer.
 ==== max_branches ==== ==== max_branches ====
  
Line 1525: 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 1929: 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 1976: 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 2119: 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 2135: 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 2146: 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 2385: 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 2401: 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 2416: 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 2957: 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 3044: 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 3490: Line 3625:
     }     }
 } }
 +</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> </code>
  
Line 3585: Line 3730:
   ||      logical OR   ||      logical OR
   !       logical NOT   !       logical NOT
-  [ ... ] test operator - inside can be any arithmetic expression 
 </code> </code>
  
Line 3597: 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 3879: Line 4025:
       * **A** - do not add log prefix       * **A** - do not add log prefix
       * **c** - add Call-ID (when available) as a dedicated JSON attribute       * **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       * **M** - strip EOL ('\n') from the value of the log message field
       * **N** - do not add EOL at the end of JSON document       * **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**" : Example of JSON logs when running Kamailio with "**--log-engine=json:M**" :
Line 3888: Line 4037:
  
 { "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]" } { "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> </code>
cookbooks/devel/core.1609754007.txt.gz · Last modified: 2021/01/04 10:53 by miconda