This shows you the differences between two versions of the page.
Both sides previous revision Previous revision Next revision | Previous revision Next revision Both sides next revision | ||
cookbooks:5.2.x:core [2019/01/02 09:11] mslehto [onreply_route] |
cookbooks:5.2.x:core [2019/10/30 00:16] joelsdc |
||
---|---|---|---|
Line 47: | Line 47: | ||
</ | </ | ||
+ | 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=" | ||
+ | </ | ||
+ | |||
+ | 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 " | ||
+ | |||
+ | <code c> | ||
+ | listen=tcp: | ||
+ | </ | ||
==== Modules Settings Section ==== | ==== Modules Settings Section ==== | ||
Line 725: | Line 736: | ||
==== 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 value is off. |
Example: | Example: | ||
Line 855: | Line 866: | ||
==== 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 | ||
+ | FLAG_TWO | ||
+ | ... | ||
+ | </ | ||
+ | |||
+ | (*) 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: | ||
+ | <code c> | ||
+ | #!define FLAG_NAME FLAG_BIT | ||
+ | </ | ||
==== force_rport ==== | ==== force_rport ==== | ||
Line 971: | Line 998: | ||
==== 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) |
Line 1386: | Line 1413: | ||
==== 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 1425: | Line 1452: | ||
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 messages sharing the same Call-Id. In other words, enables Kamailio to execute sequentially the requests and replies received within the same dialog -- a new message received within the same dialog waits until the previous one is routed out. | ||
+ | |||
+ | For smaller impact on parallel processing, its value it should be at least twice the number of kamailio processes (children | ||
+ | |||
+ | Example: | ||
+ | |||
+ | <code c> | ||
+ | route_locks_size = 256 | ||
+ | </ | ||
==== server_id ==== | ==== server_id ==== | ||
Line 2974: | Line 3013: | ||
The sub-route blocks allow to make the configuration file modular, simplifying the logic and helping to avoid duplication of actions. | The sub-route blocks allow to make the configuration file modular, simplifying the logic and helping to avoid duplication of actions. | ||
- | ==== branch_route ==== | ||
- | |||
- | Request' | ||
- | |||
- | Example of usage: | ||
- | |||
- | <code c> | ||
- | request_route { | ||
- | lookup(" | ||
- | t_on_branch(" | ||
- | if(!t_relay()) { | ||
- | sl_send_reply(" | ||
- | } | ||
- | } | ||
- | branch_route[OUT] { | ||
- | if(uri=~" | ||
- | # discard branches that go to 10.10.10.10 | ||
- | drop(); | ||
- | } | ||
- | } | ||
- | </ | ||
- | |||
- | ==== failure_route ==== | ||
- | |||
- | Failed transaction routing block. It contains a set of actions to be taken each transaction that received only negative replies (>=300) for all branches. The ' | ||
- | |||
- | Note that in ' | ||
- | |||
- | |||
- | Example of usage: | ||
- | |||
- | <code c> | ||
- | request_route { | ||
- | lookup(" | ||
- | t_on_failure(" | ||
- | if(!t_relay()) { | ||
- | sl_send_reply(" | ||
- | } | ||
- | } | ||
- | failure_route[TOVOICEMAIL] { | ||
- | if(is_method(" | ||
- | # call failed - relay to voice mail | ||
- | | ||
- | } | ||
- | } | ||
- | </ | ||
- | |||
- | ==== reply_route ==== | ||
- | |||
- | Main SIP response (reply) handling block - it contains a set of actions to be executed for SIP replies. It is executed for all replies received from the network. | ||
- | |||
- | It does not have a name and it is executed by the core, before any other module handling the SIP reply. It is triggered only by SIP replies received on the network. | ||
- | |||
- | There is no network route that can be enforced for a SIP reply - it is sent based on Via header, according to SIP RFC3261 - therefore no dedicated actions for forwarding the reply must be used in this block. | ||
- | |||
- | This routing block is optional, if missing, the SIP reply is sent to the address in 2nd Via header. | ||
- | |||
- | One can decide to drop a SIP reply by using **drop** action. | ||
- | |||
- | Example: | ||
- | |||
- | <code c> | ||
- | reply_route { | ||
- | if(status==" | ||
- | drop; | ||
- | } | ||
- | } | ||
- | </ | ||
- | |||
- | <fc # | ||
- | |||
- | ==== onreply_route ==== | ||
- | |||
- | |||
- | 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 ' | ||
- | |||
- | Main ' | ||
- | |||
- | <code c> | ||
- | request_route { | ||
- | lookup(" | ||
- | t_on_reply(" | ||
- | if(!t_relay()) { | ||
- | sl_send_reply(" | ||
- | } | ||
- | } | ||
- | |||
- | reply_route { | ||
- | if(!t_check_trans()) { | ||
- | drop; | ||
- | } | ||
- | } | ||
- | |||
- | onreply_route[LOGRPL] { | ||
- | if(status=~" | ||
- | | ||
- | } | ||
- | } | ||
- | </ | ||
- | ==== onsend_route ==== | ||
- | |||
- | 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, | ||
- | |||
- | 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, | ||
- | |||
- | Example: | ||
- | |||
- | <code c> | ||
- | onsend_route { | ||
- | if(to_ip==1.2.3.4 && !isflagset(12)){ | ||
- | log(1, " | ||
- | drop; | ||
- | } | ||
- | } | ||
- | </ | ||
- | |||
- | * snd_ip, snd_port - behave like src_ip/ | ||
- | * to_ip, to_port - like above, but contain the ip/port the message will be sent to (not to be confused with dst_ip/ | ||
- | * snd_proto, snd_af - behave like proto/af but contain the protocol/ | ||
- | * msg:len - when used in an onsend_route, | ||
- | |||
- | ==== event_route ==== | ||
- | |||
- | Generic type of route executed when specific events happen. | ||
- | |||
- | Prototype: event_route[groupid: | ||
- | * groupid - should be the name of the module that triggers the event | ||
- | * eventid - some meaningful short text describing the event | ||
- | |||
- | Implementations: | ||
- | |||
- | * **event_route[core: | ||
- | * note that due to forking, other sip workers can get faster to listening for sip traffic | ||
- | |||
- | <code c> | ||
- | event_route[core: | ||
- | xlog(" | ||
- | } | ||
- | </ | ||
- | |||
- | * **event_route[htable: | ||
- | <code c> | ||
- | modparam(" | ||
- | |||
- | event_route[htable: | ||
- | $sht(a=> | ||
- | $sht(a=> | ||
- | } | ||
- | |||
- | request_route { | ||
- | if(is_method(" | ||
- | { | ||
- | switch($rd) { | ||
- | case " | ||
- | lock(" | ||
- | $sht(a=> | ||
- | $sht(a=> | ||
- | unlock(" | ||
- | if($sht(a=> | ||
- | { | ||
- | | ||
- | exit; | ||
- | } | ||
- | break; | ||
- | ... | ||
- | } | ||
- | } | ||
- | } | ||
- | </ | ||
- | * **event_route [tm: | ||
- | <code c> | ||
- | event_route [tm: | ||
- | xlog(" | ||
- | t_set_fr(10000, | ||
- | } | ||
- | </ | ||
- | |||
- | * **event_route [tm: | ||
- | <code c> | ||
- | event_route [tm: | ||
- | xlog(" | ||
- | if (t_check_status(" | ||
- | unregister(" | ||
- | if (t_next_contact_flow()) { | ||
- | t_relay(); | ||
- | } | ||
- | } | ||
- | } | ||
- | </ | ||
- | |||
- | ===== Script Statements ===== | ||
- | |||
- | ==== if ==== | ||
- | IF-ELSE statement | ||
- | |||
- | Prototype: | ||
- | |||
- | < | ||
- | if(expr) { | ||
- | | ||
- | } else { | ||
- | | ||
- | } | ||
- | </ | ||
- | |||
- | The ' | ||
- | |||
- | The logical operators that can be used in ' | ||
- | |||
- | < | ||
- | == equal | ||
- | != not equal | ||
- | =~ regular expression matching: Note: Posix regular expressions will be used, e.g. use [[: | ||
- | !~ regular expression not-matching (NOT PORTED from Kamailio 1.x, use '!(x =~ y)') | ||
- | > | ||
- | >= greater or equal | ||
- | < less | ||
- | <= less or equal | ||
- | && | ||
- | || logical OR | ||
- | ! | ||
- | [ ... ] test operator - inside can be any arithmetic expression | ||
- | </ | ||
- | |||
- | Example of usage: | ||
- | |||
- | if(is_method(" | ||
- | { | ||
- | log(" | ||
- | } else { | ||
- | log(" | ||
- | } | ||
- | |||
- | |||
- | ==== switch ==== | ||
- | |||
- | SWITCH statement - it can be used to test the value of a pseudo-variable. | ||
- | |||
- | IMPORTANT NOTE: ' | ||
- | |||
- | |||
- | Example of usage: | ||
- | < | ||
- | route { | ||
- | route(1); | ||
- | switch($retcode) | ||
- | { | ||
- | case -1: | ||
- | log(" | ||
- | break; | ||
- | case 1: | ||
- | log(" | ||
- | break; | ||
- | case 2: | ||
- | case 3: | ||
- | log(" | ||
- | break; | ||
- | default: | ||
- | log(" | ||
- | } | ||
- | |||
- | # switch of R-URI username | ||
- | switch($rU) | ||
- | { | ||
- | case " | ||
- | log(" | ||
- | break; | ||
- | case " | ||
- | log(" | ||
- | break; | ||
- | case " | ||
- | case " | ||
- | log(" | ||
- | break; | ||
- | default: | ||
- | log(" | ||
- | } | ||
- | } | ||
- | |||
- | route[1]{ | ||
- | if(is_method(" | ||
- | { | ||
- | return(-1); | ||
- | }; | ||
- | if(is_method(" | ||
- | return(1); | ||
- | } | ||
- | if(is_method(" | ||
- | return(2); | ||
- | } | ||
- | if(is_method(" | ||
- | return(3); | ||
- | } | ||
- | return(-2); | ||
- | } | ||
- | </ | ||
- | |||
- | NOTE: take care while using ' | ||
- | |||
- | |||
- | ==== while ==== | ||
- | |||
- | while statement | ||
- | |||
- | Example of usage: | ||
- | | ||
- | $var(i) = 0; | ||
- | while($var(i) < 10) | ||
- | { | ||
- | xlog(" | ||
- | $var(i) = $var(i) + 1; | ||
- | } | ||
- | |||
- | ===== Script Operations ===== | ||
- | |||
- | Assignments together with string and arithmetic operations can be done directly in configuration file. | ||
- | ==== Assignment ==== | ||
- | |||
- | Assignments can be done like in C, via ' | ||
- | * Unordered List Item AVPs - to set the value of an AVP | ||
- | * script variables ($var(...)) - to set the value of a script variable | ||
- | * shared variables ($shv(...)) | ||
- | * $ru - to set R-URI | ||
- | * $rd - to set domain part of R-URI | ||
- | * $rU - to set user part of R-URI | ||
- | * $rp - to set the port of R-URI | ||
- | * $du - to set dst URI | ||
- | * $fs - to set send socket | ||
- | * $br - to set branch | ||
- | * $mf - to set message flags value | ||
- | * $sf - to set script flags value | ||
- | * $bf - to set branch flags value | ||
- | |||
- | < | ||
- | $var(a) = 123; | ||
- | </ | ||
- | |||
- | For avp's there a way to remove all values and assign a single value in one statement (in other words, delete existing AVPs with same name, add a new one with the right side value). This replaces the := assignment operator from kamailio < 3.0. | ||
- | < | ||
- | $(avp(i: | ||
- | $(avp(i: | ||
- | </ | ||
- | |||
- | ==== String Operations ==== | ||
- | For strings, ' | ||
- | |||
- | < | ||
- | $var(a) = " | ||
- | $var(b) = " | ||
- | </ | ||
- | ==== Arithmetic Operations ==== | ||
- | |||
- | For numbers, one can use: | ||
- | * + : plus | ||
- | * - : minus | ||
- | * / : divide | ||
- | * * : multiply | ||
- | * % : modulo (Kamailio uses ' | ||
- | * | : bitwise OR | ||
- | * & : bitwise AND | ||
- | * ^ : bitwise XOR | ||
- | * ~ : bitwise NOT | ||
- | * < | ||
- | * < | ||
- | |||
- | Example: | ||
- | |||
- | < | ||
- | $var(a) = 4 + ( 7 & ( ~2 ) ); | ||
- | </ | ||
- | |||
- | NOTE: to ensure the priority of operands in expression evaluations do use __parenthesis__. | ||
- | |||
- | Arithmetic expressions can be used in condition expressions. | ||
- | |||
- | < | ||
- | if( $var(a) & 4 ) | ||
- | log(" | ||
- | </ | ||
- | |||
- | ===== Operators ===== | ||
- | |||
- | - type casts operators: (int), (str). | ||
- | - string comparison: eq, ne | ||
- | - integer comparison: ieq, ine | ||
- | |||
- | Note: The names are not yet final (use them at your own risk). Future version might use ==/!= only for ints (ieq/ine) and eq/ne for strings (under debate). They are almost equivalent to == or !=, but they force the conversion of their operands (eq to string and ieq to int), allowing among other things better type checking on startup and more optimizations. | ||
- | |||
- | Non equiv. examples: | ||
- | |||
- | 0 == "" | ||
- | |||
- | " | ||
- | |||
- | Note: internally == and != are converted on startup to eq/ | ||
- | |||
- | - Kamailio tries to guess what the user wanted when operators that support multiple types are used on different typed operands. In general convert the right operand to the type of the left operand and then perform the operation. Exception: the left operand is undef. This applies to the following operators: +, == and !=. | ||
- | | ||
- | For +: undef + expr -> undef is converted to string => "" | ||
- | For == and !=: undef == expr -> undef is converted to type_of expr. | ||
- | If expr is undef, then undef == undef is true (internally is converted | ||
- | to string). | ||
- | |||
- | - expression evaluation changes: Kamailio will auto-convert to integer or string in function of the operators: | ||
- | | ||
- | | ||
- | |||
- | - script operators for dealing with empty/ | ||
- | defined expr - returns true if expr is defined, and false if not. | ||
- | Note: only a standalone avp or pvar can be | ||
- | | ||
- | strlen(expr) - returns the lenght of expr evaluated as string. | ||
- | strempty(expr) - returns true if expr evaluates to the empty | ||
- | | ||
- | Example: if (defined $v && !strempty($v)) $len=strlen($v); |