modules/outbound/README
82de81e6
 Outbound Module
 
 Peter Dunkley
 
    Crocodile RCS Ltd
 
f474e856
    Copyright © 2012 Crocodile RCS Ltd
82de81e6
      __________________________________________________________________
 
    Table of Contents
 
    1. Admin Guide
 
         1. Overview
4a418276
 
               1.1. Edge Proxy Keep-Alives (STUN)
               1.2. Flow Timer
 
82de81e6
         2. Dependencies
 
               2.1. Kamailio Modules
               2.2. External Libraries or Applications
 
         3. Parameters
4a418276
 
a117147b
               3.1. force_outbound_flag (integer)
4a418276
 
82de81e6
         4. Functions
         5. MI Commands
 
4a418276
    List of Examples
 
e090a714
    1.1. Edge Proxy Configuration
    1.2. Registrar Configuration
    1.3. Set force_outbound_flag parameter
4a418276
 
82de81e6
 Chapter 1. Admin Guide
 
    Table of Contents
 
    1. Overview
4a418276
 
         1.1. Edge Proxy Keep-Alives (STUN)
         1.2. Flow Timer
 
82de81e6
    2. Dependencies
 
         2.1. Kamailio Modules
         2.2. External Libraries or Applications
 
    3. Parameters
4a418276
 
a117147b
         3.1. force_outbound_flag (integer)
4a418276
 
82de81e6
    4. Functions
    5. MI Commands
 
 1. Overview
 
4a418276
    1.1. Edge Proxy Keep-Alives (STUN)
    1.2. Flow Timer
 
    This module provides C-API functions to enable Kamailio to be used as
    an outbound Edge Proxy (see RFC 5626 section 5).
 
    The path and rr will bind to this module if it is loaded before they
    are.
 
 1.1. Edge Proxy Keep-Alives (STUN)
 
    Outbound Edge Proxies MUST support STUN NAT keep-alives on their SIP
e090a714
    UDP ports. Kamailio supports this though the “stun” module.
4a418276
 
 1.2. Flow Timer
 
    The maximum interval at which a User Agent must send a keep-alive may
    be specified by the Registrar using the Flow-Timer: header in 2xx
    responses to REGISTERs.
 
    When using TCP or TLS as the SIP transport care should be taken to set
f474e856
    the “tcp_connection_lifetime” on the Edge Proxy to a value slightly
4a418276
    larger than the interval the Registrar is using for flow timer. Setting
f474e856
    “tcp_connection_lifetime” to less than the interval could cause
4a418276
    connections to be lost, and setting it to a value much larger than the
    interval will keep connections open far longer than is required (which
    is wasteful).
 
    Application-layer keep-alives are optional when the underlying
    transport already has a keep-alive mechanism. The WebSocket transport
    has a transport-layer keep-alive. When using the WebSocket transport
f474e856
    the “keepalive_timeout” should be set to a value a little greater than
4a418276
    the Registrar flow timer interval and a little less than the
f474e856
    “tcp_connection_lifetime”.
4a418276
 
e090a714
    Example 1.1. Edge Proxy Configuration
60953cd8
 #!KAMAILIO
 #
 # Edge proxy configuration
 #
 
 #!subst "/REGISTRAR_IP/192.168.122.3/"
 #!subst "/REGISTRAR_PORT/5060/"
 #!substdef "/FLOW_TIMER/20/"
 
 ####### Global Parameters #########
 
 debug=2
 log_stderror=no
 log_facility=LOG_LOCAL0
 fork=yes
 children=4
 alias="example.com"
 mpath="/usr/lib64/kamailio/modules"
 tcp_connection_lifetime=30 # FLOW_TIMER + 10
 
 
 ####### Modules Section ########
 
 loadmodule "tm.so"
 loadmodule "sl.so"
4a418276
 loadmodule "outbound.so"
 loadmodule "rr.so"
 loadmodule "path.so"
60953cd8
 loadmodule "pv.so"
 loadmodule "maxfwd.so"
 loadmodule "xlog.so"
 loadmodule "sanity.so"
 loadmodule "ctl.so"
 loadmodule "mi_rpc.so"
 loadmodule "mi_fifo.so"
 loadmodule "textops.so"
 loadmodule "siputils.so"
030d591a
 loadmodule "stun.so"
9f636841
 
60953cd8
 # ----------------- setting module-specific parameters ---------------
9f636841
 
60953cd8
 # ----- mi_fifo params -----
 modparam("mi_fifo", "fifo_name", "/tmp/kamailio_fifo")
9f636841
 
60953cd8
 # ----- tm params -----
 modparam("tm", "failure_reply_mode", 3)
 
 # ----- rr params -----
 modparam("rr", "append_fromtag", 0)
 
 
 ####### Routing Logic ########
 
 request_route {
         route(REQINIT);
 
         if (is_method("CANCEL")) {
                 if (t_check_trans()) {
                         route(RELAY);
9f636841
                 }
60953cd8
                 exit;
         }
 
         route(WITHINDLG);
 
         t_check_trans();
82303dfa
 
60953cd8
         if (is_method("REGISTER")) {
                 remove_hf("Route");
a117147b
                 add_path();
60953cd8
                 $du = "sip:REGISTRAR_IP:REGISTRAR_PORT";
         } else {
                 if (is_method("INVITE|SUBSCRIBE"))
                         record_route();
 
                 if ($si == "REGISTRAR_IP" && $sp == "REGISTRAR_PORT") {
                         if (!loose_route()) {
                                 switch($rc) {
                                 case -2:
                                         sl_send_reply("403", "Forbidden");
                                         exit;
                                 default:
                                         sl_reply_error();
                                         exit;
                                 }
                         }
 
                         t_on_failure("FAIL_OUTBOUND");
                 } else {
                         if ($rU == $null) {
                                 sl_send_reply("484", "Address Incomplete");
                                 exit;
                         }
                         remove_hf("Route");
                         $du = "sip:REGISTRAR_IP:REGISTRAR_PORT";
9f636841
                 }
         }
60953cd8
 
         route(RELAY);
9f636841
 }
 
 route[RELAY] {
         if (!t_relay()) {
60953cd8
                 sl_reply_error();
9f636841
         }
         exit;
 }
60953cd8
 
 route[REQINIT] {
         if (!mf_process_maxfwd_header("10")) {
                 sl_send_reply("483","Too Many Hops");
                 exit;
         }
 
         if(!sanity_check("1511", "7"))
         {
                 xlog("Malformed SIP message from $si:$sp\n");
                 exit;
         }
 }
 
9f636841
 route[WITHINDLG] {
         if (has_totag()) {
                 if (!loose_route()) {
                         switch($rc) {
                         case -2:
                                 sl_send_reply("403", "Forbidden");
                                 exit;
60953cd8
                         default:
9f636841
                                 if (is_method("ACK")) {
60953cd8
                                         if ( t_check_trans() ) {
                                                 route(RELAY);
9f636841
                                                 exit;
                                         } else {
                                                 exit;
                                         }
                                 }
60953cd8
                                 sl_send_reply("404","Not Found");
9f636841
                         }
                 } else {
60953cd8
                         if (is_method("NOTIFY")) {
                                 record_route();
                         }
9f636841
                         route(RELAY);
                 }
                 exit;
         }
a117147b
 }
60953cd8
 
a117147b
 onreply_route {
         if (!t_check_trans()) {
                 drop;
         }
 
60953cd8
         if ($rm == "REGISTER" && $rs >= 200 && $rs <= 299) {
                 remove_hf("Flow-Timer");
a117147b
                 if ($(hdr(Require)[*])=~"outbound")
                         insert_hf("Flow-Timer: FLOW_TIMER\r\n", "Call-ID");
         }
 }
 
60953cd8
 failure_route[FAIL_OUTBOUND]{
9f636841
         if (t_branch_timeout() || !t_branch_replied()) {
                 send_reply("430", "Flow Failed");
         }
 }
 
e090a714
    Example 1.2. Registrar Configuration
4a418276
 ...
82303dfa
 loadmodule "tm.so"
 ...
4a418276
 loadmodule "registrar.so"
 ...
82303dfa
 modparam("tm", "contacts_avp", "tm_contacts")
 modparam("tm", "contact_flows_avp", "tm_contact_flows")
 ...
 modparam("registrar", "use_path", 1)
 modparam("registrar", "path_mode", 2)
e7bb3af6
 modparam("registrar", "outbound_mode", 2)
82303dfa
 ...
 route[LOCATION] {
 ...
         if (!lookup("location")) {
                 $var(rc) = $rc;
                 route(TOVOICEMAIL);
                 t_newtran();
                 switch ($var(rc)) {
                         case -1:
                         case -3:
                                 send_reply("404", "Not Found");
                                 exit;
                         case -2:
                                 send_reply("405", "Method Not Allowed");
                                 exit;
                 }
         }
 
         if (!t_load_contacts()) {
                 send_reply("500", "Server Internal Error");
                 exit;
         }
 
         if (!t_next_contacts()) {
                 send_reply("500", "Server Internal Error");
                 exit;
         }
 
e4ffcaf6
         t_on_failure("FAIL_OUTBOUND");
82303dfa
 ...
 }
 ...
 failure_route[FAIL_OUTBOUND] {
         if (t_check_status("408|430")) {
                 if (!t_next_contact_flows() && !t_next_contacts()) {
                         send_reply("500", "Server Internal Error");
                         exit;
                 }
         } else if (!t_next_contacts()) {
                 send_reply("500", "Server Internal Error");
                 exit;
         }
 
e4ffcaf6
         t_on_failure("FAIL_OUTBOUND");
         route(RELAY);
82303dfa
 }
4a418276
 ...
82de81e6
 
 2. Dependencies
 
    2.1. Kamailio Modules
    2.2. External Libraries or Applications
 
 2.1. Kamailio Modules
 
4a418276
    The following modules must be loaded before this module:
      * None
82de81e6
 
 2.2. External Libraries or Applications
 
    The following libraries must be installed before running Kamailio with
    this module loaded:
      * OpenSSL.
 
 3. Parameters
 
a117147b
    3.1. force_outbound_flag (integer)
4a418276
 
a117147b
 3.1. force_outbound_flag (integer)
4a418276
 
a117147b
    A flag which, if set for a request, will force path and rr to add flow
    tokens to Path: and Record-Route: headers regardless of the request
    contents.
4a418276
 
    Default value is -1.
 
e090a714
    Example 1.3. Set force_outbound_flag parameter
66560d5a
 ...
a117147b
 modparam("outbound", "force_outbound_flag", 1)
66560d5a
 ...
4a418276
 
82de81e6
 4. Functions
 
4a418276
    None
82de81e6
 
 5. MI Commands
 
4a418276
    None