Differences

This shows you the differences between two versions of the page.

--- cookbooks:devel:core [2019/10/18 09:35]
jih
+++ cookbooks:devel:core [2019/10/30 18:17]
henningw
@@ Line 9: / Line 9: @@
 ===== 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
@@ Line 2992: / Line 2992: @@
 Add "user=phone" parameter to R-URI.
 ===== Custom Global Parameters =====
-These are parameters that can be defined by the writer of kamailio.cfg in order to be used inside routing blocks.
+These are parameters that can be defined by the writer of kamailio.cfg in order to be used inside routing blocks. One of the important properties for custom global parameters is that their value can be changed at runtime via RPC commands, without restarting Kamailio.
+The definition of a custom global parameter must follow the pattern:
+<code>
+group.variable = value desc "description"
+</code>
+The value can be a quoted string or integer number.
+Example:
+<code c>
+pstn.gw_ip = "1.2.3.4" desc "PSTN GW Address"
+</code>
+The custom global parameter can be accessed inside a routing block via:
+<code>
+$sel(cfg_get.group.variable)
+</code>
+Example:
+<code c>
+$ru = "sip:" + $rU + "@" + $sel(cfg_get.pstn.gw_ip);
+</code>
+**Note:** Some words cannot be used as (part of) names for custom variables or groups, and if they are used a syntax error is logged  by kamailio. These keywords are: "yes", "true", "on", "enable", "no", "false", "off", "disable", "udp", "UDP", "tcp", "TCP", "tls", "TLS", "sctp", "SCTP", "ws", "WS", "wss", "WSS", "inet", "INET", "inet6", "INET6", "sslv23", "SSLv23", "SSLV23", "sslv2", "SSLv2", "SSLV2", "sslv3", "SSLv3", "SSLV3", "tlsv1", "TLSv1", "TLSV1"
+===== Routing Blocks =====
+The routing blocks are the parts of the configuration file executed by kamailio at runtime. They can be seen as blocks of actions similar to functions (or procedures) from common programming languages.
+A routing block is identified by a specific token, followed by a name in between square brackets and actions in between curly braces.
+<code c>
+route_block_id[NAME] {
+  ACTIONS
+}
+</code>
+The name can be any alphanumeric string, with specific routing blocks enforcing a particular format.
+<fc #4682b4>Note: route(number) is equivalent to route("number").</fc>
+Route blocks can be executed on network events (e.g., receiving a SIP message), timer events (e.g., retransmission timeout) or particular events specific to modules.
+There can be so called sub-route blocks, which can be invoked from another route blocks, like a function. Invocation is done with 'route' followed by the name of sub-route to execute, enclosed in between parentheses.
+Example:
+<code c>
+  request_route{
+    ...
+    route("test");
+    ...
+  }
+  route["test"]{
+    ...
+  }
+</code>
+==== request_route ====
+Request routing block -  is executed for each SIP request.
+It contains a set of actions to be executed for SIP requests received from the network. It is the equivalent of *main()* function for handling the SIP requests.
+<fc #4682b4>For backward compatibility reasons, the main request 'route' block can be identified by 'route{...}' or 'route[0]{...}'.</fc>
+The implicit action after execution of the main route block is to drop the SIP request. To send a reply or forward the request, explicit actions (e.g., sl_send_reply(), forward(), t_relay()) must be called inside the route block.
+Example of usage:
+<code c>
+    request_route {
+         if(is_method("OPTIONS")) {
+            # send reply for each options request
+            sl_send_reply("200", "ok");
+            exit();
+         }
+         route(FWD);
+    }
+    route[FWD] {
+         # forward according to uri
+         forward();
+    }
+</code>
+==== route ====
+This block is used to define 'sub-routes' - group of actions that can be executed from another routing block. Originally targeted as being executed from 'request_route', it can be executed now from all the other blocks. Be sure you put there the actions valid for the root routing block executing the sub-route.
+The definition of the sub-route block follows the general rules, with a name in between square brackets and actions between curly braces. A sub-route can return an integer value back to the routing block that executed it. The return code can be retrieved via $rc variables.
+Evaluation of the return of a subroute is done with following rules:
+  * negative value is evaluated as false
+  * 0 - is interpreted as **exit**
+  * positive value is evaluated as true
+<code c>
+request_route {
+  if(route(POSITIVE)) {
+    xlog("return number is positive\n");
+  }
+  if( ! route(NEGATIVE)) {
+    xlog("return number is negative\n");
+  }
+  if( route(ZERO)) {
+    xlog("this log message does not appear\n");
+  }
+}
+route[POSITIVE] {
+  return 10;
+}
+route[NEGATIVE] {
+  return -8;
+}
+route[ZERO] {
+  return 0;
+}
+</code>
+A sub-route can execute another sub-route. There is a limit to the number of recursive levels, avoiding ending up in infinite loops -- see **max_recursive_level** global parameter.
+The sub-route blocks allow to make the configuration file modular, simplifying the logic and helping to avoid duplication of actions.
+==== branch_route ====
+Request's branch routing block. It contains a set of actions to be taken for each branch of a SIP request. It is executed only by TM module after it was armed via t_on_branch("branch_route_index").
+Example of usage:
+<code c>
+    request_route {
+        lookup("location");
+        t_on_branch("OUT");
+        if(!t_relay()) {
+            sl_send_reply("500", "relaying failed");
+        }
+    }
+    branch_route[OUT] {
+        if(uri=~"10\.10\.10\.10") {
+            # discard branches that go to 10.10.10.10
+            drop();
+        }
+    }
+</code>
+==== failure_route ====
+Failed transaction routing block. It contains a set of actions to be taken each transaction

Kamailio SIP Server Wiki

User Tools

Site Tools

Differences

Page Tools