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 [2018/02/24 11:15]
miconda [userphone]
cookbooks:devel:core [2020/07/17 08:10]
miconda [Kamailio SIP Server v5.5.x (devel): Core Cookbook]
Line 1: Line 1:
-====== Kamailio SIP Server v5.2.x (devel): Core Cookbook ======+====== Core Cookbook ======
  
 +Version: Kamailio SIP Server v5.5.x (devel)
 ===== Overview ===== ===== Overview =====
  
Line 9: Line 10:
 ===== Structure ===== ===== Structure =====
  
-The structure of the kamailio.cfg can be seen as thee parts:+The structure of the kamailio.cfg can be seen as three parts:
  
   * global parameters   * global parameters
Line 47: Line 48:
 </code> </code>
  
 +Usually setting a parameter is ended by end of line, but it can be also ended with **;** (semicolon). This should be used when the grammar of a parameter allows values on multiple lines (like **listen** or **alias**) and the next line creates a conflict by being swallowed as part of value for previous parameter.
 +
 +<code c>
 +alias="sip.mydomain.com";
 +</code>
 +
 +If you want to use a reserved config keyword as part of a parameter, you need to enclose it in quotes. See the example below for the keyword "dns".
 +
 +<code c>
 +listen=tcp:127.0.0.1:5060 advertise "sip.dns.example.com":5060
 +</code>
 ==== Modules Settings Section ==== ==== Modules Settings Section ====
  
Line 125: Line 137:
  
   "this is a string value"   "this is a string value"
-  'this is another string value"+  'this is another string value'
  
 // next is a boolean // next is a boolean
Line 198: Line 210:
 The path_to_file can be relative or absolute. If it is not absolute path, first attempt is to locate it relative to current directory, and if fails, relative to directory of the file that includes it. There is no restriction where include can be used or what can contain - any part of config file is ok. There is a limit of maximum 10 includes in depth, otherwise you can use as many includes as you want. Reporting of the cfg file syntax errors prints now the file name for easier troubleshooting.  The path_to_file can be relative or absolute. If it is not absolute path, first attempt is to locate it relative to current directory, and if fails, relative to directory of the file that includes it. There is no restriction where include can be used or what can contain - any part of config file is ok. There is a limit of maximum 10 includes in depth, otherwise you can use as many includes as you want. Reporting of the cfg file syntax errors prints now the file name for easier troubleshooting. 
  
-If the included file is not found, the config file parser throws error.+If the included file is not found, the config file parser throws error. You can find this error message at the logging destination, usually in the system logging (file).
  
 You can use also the syntax **#!include_file** or **!!include_file**. You can use also the syntax **#!include_file** or **!!include_file**.
Line 234: Line 246:
  
 Available directives: Available directives:
-  * #!define NAME - define a keyword +  * **#!define NAME** - define a keyword 
-  * #!define NAME VALUE - define a keyword with value +  * **#!define NAME VALUE** - define a keyword with value 
-  * #!ifdef NAME - check if a keyword is defined +  * **#!ifdef NAME** - check if a keyword is defined 
-  * #!ifndef - check if a keyword is not defined +  * **#!ifndef** - check if a keyword is not defined 
-  * #!else - swtich to false branch of ifdef/ifndef region +  * **#!else** switch to false branch of ifdef/ifndef region 
-  * #!endif - end ifdef/ifndef region +  * **#!endif** - end ifdef/ifndef region 
-  * #!trydef - add a define if not already defined +  * **#!trydef** - add a define if not already defined 
-  * #!redefine - force redefinition even if already defined+  * **#!redefine** - force redefinition even if already defined 
 + 
 +Predefined keywords: 
 +  * **KAMAILIO_X[_Y[_Z]]** - Kamailio versions 
 +  * **MOD_X** - when module X has been loaded 
 +See 'kamctl core.ppdefines_full' for full list.
  
 Among benefits: Among benefits:
-  * easy way to enable/disable features (e.g., see default cfg for 3.0.0 -- controlling support of nat traversal, presence, etc...)+  * easy way to enable/disable features (e.g., see default cfg -- controlling support of nat traversal, presence, etc...)
   * switch control for parts where conditional statements were not possible (e.g., global parameters, module settings)   * switch control for parts where conditional statements were not possible (e.g., global parameters, module settings)
   * faster by not using conditional statements inside routing blocks when switching between running environments   * faster by not using conditional statements inside routing blocks when switching between running environments
Line 370: Line 387:
 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 725: Line 749:
 ==== 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 731: Line 755:
 <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 792: Line 826:
 Examples of usage: Examples of usage:
  
-  * debug=3: print all log messages. This is only usefull for debugging of problems. Note: this produces a lot of data and therefore should not be used on production servers (on a busy server this can easily fill up your hard disk with log messages)+  * debug=3: print all log messages. This is only useful for debugging of problems. Note: this produces a lot of data and therefore should not be used on production servers (on a busy server this can easily fill up your hard disk with log messages)
   * debug=0: This will only log warning, errors and more critical messages.   * debug=0: This will only log warning, errors and more critical messages.
   * debug=-6: This will disable all log messages.   * debug=-6: This will disable all log messages.
Line 855: Line 889:
 ==== 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 918: Line 969:
 <code c> <code c>
   ip_free_bind = 1   ip_free_bind = 1
 +</code>
 +
 +==== kemi.onsend_route_callback ====
 +
 +Set the name of callback function in the KEMI script to be executed as the equivalent of `onsend_route` block (from the native configuration file).
 +
 +Default value: ksr_onsend_route
 +
 +Set it to empty string or "none" to skip execution of this callback function.
 +
 +Example:
 +
 +<code c>
 +kemi.onsend_route_callback="ksr_my_onsend_route"
 +</code>
 +
 +==== kemi.received_route_callback ====
 +
 +Set the name of callback function in the KEMI script to be executed as the equivalent of `event_route[core:msg-received]` block (from the native configuration file). For execution, it also require to have the received_route_mode global parameter set to 1.
 +
 +Default value: none
 +
 +Set it to empty string or "none" to skip execution of this callback function.
 +
 +Example:
 +
 +<code c>
 +kemi.received_route_callback="ksr_my_receieved_route"
 +</code>
 +
 +==== kemi.reply_route_callback ====
 +
 +Set the name of callback function in the KEMI script to be executed as the equivalent of `reply_route` block (from the native configuration file).
 +
 +Default value: ksr_reply_route
 +
 +Set it to empty string or "none" to skip execution of this callback function.
 +
 +Example:
 +
 +<code c>
 +kemi.onsend_route_callback="ksr_my_reply_route"
 </code> </code>
 ==== latency_cfg_log ==== ==== latency_cfg_log ====
Line 943: Line 1036:
 ==== 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 966: Line 1059:
 ==== 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 981: Line 1074:
  
 <code c> <code c>
-    listen=udp:[2a02:1850:1:1::13]:5060+    listen=udp:[2a02:1850:1:1::18]:5060
 </code> </code>
  
Line 987: Line 1080:
  
 <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 993: Line 1086:
  
 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 1077: Line 1186:
 ==== 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 1087: Line 1200:
 ==== 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 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)).+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 1111: Line 1226:
  
     log_stderror=yes     log_stderror=yes
 +
 +==== cfgengine ====
 +
 +Set the config interpreter engine for execution of the routing logic inside the configuration file. Default is the native interpreter.
 +
 +Example of usage:
 +
 +    cfgengine="name"
 +    cfgengine "name"
 +
 +If name is "native" or "default", it expects to have in native config interpreter for routing logic.
 +    
 +The name can be the identifier of an embedded language interpreter, such as "lua" which is registered by the app_lua module:
 +
 +    cfgengine "lua"
  
 ==== maxbuffer ==== ==== maxbuffer ====
Line 1220: Line 1350:
 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 1343: Line 1473:
 ==== 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 1359: Line 1489:
 <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 1373: Line 1519:
 <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 1382: Line 1540:
  
     reply_to_via=0     reply_to_via=0
 +    
 +
 +==== route_locks_size ====
 +
 +Set the number of mutex locks to be used for synchronizing the execution of config script for messages sharing the same Call-Id. In other words, enables Kamailio to execute the config script sequentially for the requests and replies received within the same dialog -- a new message received within the same dialog waits until the previous one is routed out.
 +
 +For smaller impact on parallel processing, its value it should be at least twice the number of Kamailio processes (all children processes).
 +
 +Example:
 +
 +<code c>
 +route_locks_size = 256
 +</code>
 +
 +Note that ordering of the SIP messages can still be changed by network transmission (quite likely for UDP, especially on long distance paths) or CPU allocation for processes when executing pre-config and post-config tasks (very low chance, but not to be ruled out completely).
 ==== server_id ==== ==== server_id ====
  
-A configurable unique server id that can be used to discriminate server instances within a cluster of servers when all other  information, such as IP addresses are the same.+A configurable unique server id that can be used to discriminate server instances within a cluster of servers when all other information, such as IP addresses are the same.
  
 <code c> <code c>
Line 1425: Line 1598:
 ==== 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 1508: Line 1681:
  
  
 +==== 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 1539: Line 1718:
  
   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 1573: Line 1761:
 ==== version_table ==== ==== version_table ====
  
-Set the name of the table holding the table version. Usefull if the proxy is sharing a database within a project and during upgrades. Default value is "version".+Set the name of the table holding the table version. Useful if the proxy is sharing a database within a project and during upgrades. Default value is "version".
  
 Example of usage: Example of usage:
Line 1591: Line 1779:
      or      or
      wdir=/usr/kam_wd      wdir=/usr/kam_wd
 +
 +==== xavp_via_params ====
 +
 +Set the name of the XAVP of which subfields will be added as local //Via// -header parameters.
 +
 +If not set, XAVP to Via header parameter manipulation is not applied (default behaviour).
 +
 +If set, local Via header gets additional parameters from defined XAVP. Core flag FL_ADD_XAVP_VIA_PARAMS needs to be set¹.
 +
 +Example:
 +     xavp_via_params="via"
 +[1] See function //via_add_xavp_params()// from "corex" module.
 +
 +==== xavp_via_fields ====
 +
 +Set the name of xavp from where to take Via header field: address and port.
 +Use them to build local Via header.
 +
 +Example:
 +
 +<code c>
 +xavp_via_fields="customvia"
 +
 +request_route {
 +  ...
 +  $xavp(customvia=>address) = "1.2.3.4";
 +  $xavp(customvia=>port) = "5080";  # must be string
 +  via_use_xavp_fields("1");
 +  t_relay();
 +}
 +</code>
 +     
 +See function //via_use_xavp_fields()// from "corex" module.
  
 ===== DNS Parameters ===== ===== DNS Parameters =====
Line 1614: Line 1835:
 Kamailio also allows you to finetune the DNS resolver settings. Kamailio also allows you to finetune the DNS resolver settings.
  
-The maximum time a dns request can take (before failing) is (if dns_try_ipv6 is yes, mutliply it again by 2; if SRV and NAPTR lookups are enabled, it can take even longer!):+The maximum time a dns request can take (before failing) is (if dns_try_ipv6 is yes, multiply it again by 2; if SRV and NAPTR lookups are enabled, it can take even longer!):
  
   (dns_retr_time*(dns_retr_no+1)*dns_servers_no)*(search_list_domains)   (dns_retr_time*(dns_retr_no+1)*dns_servers_no)*(search_list_domains)
Line 1810: Line 2031:
  
    tcp_accept_aliases= yes|no    tcp_accept_aliases= yes|no
 +   
 +==== tcp_accept_haproxy ====
  
 +Enable the internal TCP stack to expect a PROXY-protocol-formatted header as the first message of the connection. Both the human-readable (v1) and binary-encoded (v2) variants of the protocol are supported. This option is typically useful if you are behind a TCP load-balancer, such as HAProxy or an AWS' ELB, and allows the load-balancer to provide connection information regarding the upstream client. This enables the use of IP-based ACLs, even behind a load-balancer.
 +
 +Please note that enabling this option will reject any inbound TCP connection that does not conform to the PROXY-protocol spec.
 +
 +For reference: A PROXY protocol - https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt
 +
 +Default value is **no**.
 +
 +<code c>
 +tcp_accept_haproxy=yes
 +</code>
  
 ==== tcp_accept_hep3 ==== ==== tcp_accept_hep3 ====
  
-Enable internal TCP receiving stack to accept HEP3 packets. This option has to be set to **yes** on a Kamailio instance acting as Home SIPCapture server that is supposed to receive HEP3 packets over TCP/TLS.+Enable internal TCP receiving stack to accept HEP3 packets. This option has to be set to **yes** on a Kamailio instance acting as Homer SIPCapture server that is supposed to receive HEP3 packets over TCP/TLS.
  
 Default value is **no**. Default value is **no**.
Line 1832: Line 2066:
 </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 1870: Line 2113:
     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 1880: Line 2132:
 ==== tcp_conn_wq_max ==== ==== tcp_conn_wq_max ====
  
-Maximum bytes queued for write allowed per connection. Attempting to queue more bytes would result in an error and in the connection being closed (too slow). If tcp_write_buf is not enabled, it has no effect.+Maximum bytes queued for write allowed per connection. Attempting to queue more bytes would result in an error and in the connection being closed (too slow). If tcp_buf_write is not enabled, it has no effect.
  
   tcp_conn_wq_max = bytes (default 32 K)   tcp_conn_wq_max = bytes (default 32 K)
Line 1999: Line 2251:
 ==== tcp_wq_max ==== ==== tcp_wq_max ====
  
-Maximum bytes queued for write allowed globally. It has no effect if tcp_write_buf is not enabled.+Maximum bytes queued for write allowed globally. It has no effect if tcp_buf_write is not enabled.
  
   tcp_wq_max = bytes (default 10 Mb)   tcp_wq_max = bytes (default 10 Mb)
Line 2409: Line 2661:
  
 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 2423: Line 2677:
  
 adds a tcp port alias for the current connection (if tcp). adds a tcp port alias for the current connection (if tcp).
-Usefull if you want to send all the trafic to port_alias through+Useful if you want to send all the trafic to port_alias through
 the same connection this request came from [it could help  the same connection this request came from [it could help 
 for firewall or nat traversal]. for firewall or nat traversal].
Line 2765: Line 3019:
  
 Add "user=phone" parameter to R-URI. Add "user=phone" parameter to R-URI.
 +
 ===== Custom Global Parameters ===== ===== Custom Global Parameters =====
  
Line 2775: Line 3030:
  
 </code> </code>
 +
 +The value can be a quoted string or integer number.
  
 Example: Example:
Line 2961: Line 3218:
 <code c> <code c>
 reply_route { reply_route {
-  if(status=="128"") {+  if(status=="128") {
     drop;     drop;
   }   }
Line 2972: Line 3229:
  
  
-SIP reply routing block executed by **tm** module. It contains a set of actions to be taken for SIP replies in the contect of an active transaction..+SIP reply routing block executed by **tm** module. It contains a set of actions to be taken for SIP replies in the contect of an active transaction.
  
 The 'onreply_route' must be armed for the SIP requests whose replies should be processed within it, via t_on_reply("onreply_route_index"). The 'onreply_route' must be armed for the SIP requests whose replies should be processed within it, via t_on_reply("onreply_route_index").
  
-Main 'onreply_route' block is executed before a possible tm 'onreply_route' block.+Core 'reply_route' block is executed before a possible **tm** 'onreply_route' block.
  
 <code c> <code c>
Line 3003: Line 3260:
 The route is executed in when a SIP request is sent out. Only a limited number of commands are allowed (drop, if + all the checks, msg flag manipulations, send(), log(), textops::search()). The route is executed in when a SIP request is sent out. Only a limited number of commands are allowed (drop, if + all the checks, msg flag manipulations, send(), log(), textops::search()).
  
-In this route the final destination of the message is available an can be checked (with snd_ip, snd_port, to_ip, to_port, snd_proto, snd_af).+In this route the final destination of the message is available and can be checked (with snd_ip, snd_port, to_ip, to_port, snd_proto, snd_af).
  
 This route is executed only when forwarding requests - it is not executed for replies, retransmissions, or locally generated messages (e.g. via fifo uac). This route is executed only when forwarding requests - it is not executed for replies, retransmissions, or locally generated messages (e.g. via fifo uac).
Line 3030: Line 3287:
   * 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 3041: Line 3300:
 } }
 </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>
 +=== 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 3081: Line 3357:
   * **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 3090: Line 3372:
   }   }
 } }
 +
 </code> </code>
  
Line 3264: Line 3547:
   * ^ : bitwise XOR   * ^ : bitwise XOR
   * ~ : bitwise NOT   * ~ : bitwise NOT
-  * << : bitwise left shift +  * <nowiki><<</nowiki> : bitwise left shift 
-  * >> : bitwise right shift+  * <nowiki>>></nowiki> : bitwise right shift 
  
 Example: Example:
Line 3317: Line 3601:
                        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