Outbound Module

Peter Dunkley

   Crocodile RCS Ltd

   Copyright © 2012 Crocodile RCS Ltd
     __________________________________________________________________

   Table of Contents

   1. Admin Guide

        1. Overview

              1.1. Edge Proxy Keep-Alives (STUN)
              1.2. Flow Timer

        2. Dependencies

              2.1. Kamailio Modules
              2.2. External Libraries or Applications

        3. Parameters

              3.1. force_outbound_flag (integer)
              3.2. flow_token_key (string)

        4. Functions
        5. MI Commands

   List of Examples

   1.1. Compiling Kamailio with STUN support
   1.2. Edge Proxy Configuration
   1.3. Registrar Configuration
   1.4. Set force_outbound_flag parameter
   1.5. Set flow_token_key parameter

Chapter 1. Admin Guide

   Table of Contents

   1. Overview

        1.1. Edge Proxy Keep-Alives (STUN)
        1.2. Flow Timer

   2. Dependencies

        2.1. Kamailio Modules
        2.2. External Libraries or Applications

   3. Parameters

        3.1. force_outbound_flag (integer)
        3.2. flow_token_key (string)

   4. Functions
   5. MI Commands

1. Overview

   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
   UDP ports. Kamailio supports this as a compile-time option that is
   disabled by default.

   Example 1.1. Compiling Kamailio with STUN support
make FLAVOUR=kamailio cfg STUN=1
make all

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
   the "tcp_connection_lifetime" on the Edge Proxy to a value slightly
   larger than the interval the Registrar is using for flow timer. Setting
   "tcp_connection_lifetime" to less than the interval could cause
   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
   the "keepalive_timeout" should be set to a value a little greater than
   the Registrar flow timer interval and a little less than the
   "tcp_connection_lifetime".

   Example 1.2. Edge Proxy Configuration
...
#!define FLOW_TIMER     20
...
tcp_connection_lifetime=FLOW_TIMER+10
...
loadmodule "websocket.so"
loadmodule "outbound.so"
loadmodule "rr.so"
loadmodule "path.so"
...
modparam("websocket", "keepalive_timeout", FLOW_TIMER+5)
...
modparam("outbound", "flow_token_key", "!!!Kamailio rocks!!!")
...
route {
        route(REQINIT);
        ...
        t_check_trans();

        if (is_method("INVITE|SUBSCRIBE")) {
                record_route();

                if ($rU==$null) {
                        sl_send_reply("484", "Address Incomplete");
                        exit;
                }

                if (!loose_route()) {
                        switch($rc) {
                        case -2:
                                # Flow-token has been tampered with
                                sl_send_reply("403", "Forbidden");
                                exit;
                        case -1:
                                # Handle -1 here if all dialog forming requests
                                # must be outbound routed
                        }
                }

                t_on_failure("FAIL_OUTBOUND");
                route(RELAY);
        } else if (is_method("REGISTER")) {
                add_path();
                if (!t_relay("### Registrar ###")) {
                        sl_reply_error();
                }
                exit;
        }
}

route[RELAY] {
        if (!t_relay()) {
                sl_send_reply("430", "Flow Failed");
        }
        exit;
}
...
route[WITHINDLG] {
        if (has_totag()) {
                if (!loose_route()) {
                        switch($rc) {
                        case -2:
                                sl_send_reply("403", "Forbidden");
                                exit;
                        case -1:
                                if (is_method("ACK")) {
                                        if (t_check_trans()) {
                                                t_relay();
                                                exit;
                                        } else {
                                                exit;
                                        }
                                }
                                sl_send_reply("404", "Not Found");
                        }
                } else {
                        route(RELAY);
                }
                exit;
        }
}
...
onreply_route {
        if (!t_check_trans()) {
                drop;
        }

        if ($rm == "REGISTER" && $rs >= 200 && $rs <= 299)
        {
                if ($(hdr(Require)[*])=~"outbound")
                        insert_hf("Flow-Timer: FLOW_TIMER\r\n", "Call-ID");
        }

...
}

failure_route[FAIL_OUTBOUND] {
        if (t_branch_timeout() || !t_branch_replied()) {
                send_reply("430", "Flow Failed");
        }
}
...

   Example 1.3. Registrar Configuration
...
loadmodule "tm.so"
...
loadmodule "registrar.so"
...
modparam("tm", "contacts_avp", "tm_contacts")
modparam("tm", "contact_flows_avp", "tm_contact_flows")
...
modparam("registrar", "use_path", 1)
modparam("registrar", "path_mode", 2)
modparam("registrar", "outbound_mode", 2)
...
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;
        }

        t_on_failure("FAIL_OUTBOUND");
...
}
...
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;
        }

        t_on_failure("FAIL_OUTBOUND");
        route(RELAY);
}
...

2. Dependencies

   2.1. Kamailio Modules
   2.2. External Libraries or Applications

2.1. Kamailio Modules

   The following modules must be loaded before this module:
     * None

2.2. External Libraries or Applications

   The following libraries must be installed before running Kamailio with
   this module loaded:
     * OpenSSL.

3. Parameters

   3.1. force_outbound_flag (integer)
   3.2. flow_token_key (string)

3.1. force_outbound_flag (integer)

   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.

   Default value is -1.

   Example 1.4. Set force_outbound_flag parameter
...
modparam("outbound", "force_outbound_flag", 1)
...

3.2. flow_token_key (string)

   The outbound flow token is generated using the algorithm described in
   RFC 5626 section 5.2. This algorithm requires a 20 octet crypto random
   key that is unique for each Edge Proxy.

Note

   If this 20 character string is not set Kamailio will not start.

   Default value is: "".

   Example 1.5. Set flow_token_key parameter
...
modparam("outbound", "flow_token_key", "!!!Kamailio rocks!!!")
...

4. Functions

   None

5. MI Commands

   None
