[sr-dev] git:pd/outbound: modules_k/outbound: first draft of outbound module documentation

Peter Dunkley peter.dunkley at crocodile-rcs.com
Mon Dec 31 18:11:21 CET 2012


Module: sip-router
Branch: pd/outbound
Commit: 4a418276b50212feb3ef4d659c42e6772fc9fcd7
URL:    http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=4a418276b50212feb3ef4d659c42e6772fc9fcd7

Author: Peter Dunkley <peter.dunkley at crocodile-rcs.com>
Committer: Peter Dunkley <peter.dunkley at crocodile-rcs.com>
Date:   Mon Dec 31 17:11:30 2012 +0000

modules_k/outbound: first draft of outbound module documentation

---

 modules_k/outbound/README                 |  129 +++++++++++++++++++++++++++-
 modules_k/outbound/doc/outbound_admin.xml |  121 ++++++++++++++++++++++++++-
 2 files changed, 240 insertions(+), 10 deletions(-)

diff --git a/modules_k/outbound/README b/modules_k/outbound/README
index 7feab22..438ebb3 100644
--- a/modules_k/outbound/README
+++ b/modules_k/outbound/README
@@ -12,32 +12,123 @@ Peter Dunkley
    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_bflag (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_bflag 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_bflag (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!!!")
+...
+###TBD###
+
+   Example 1.3. Registrar Configuration
+...
+#!define FLOW_TIMER     20
+...
+tcp_connection_lifetime=FLOW_TIMER+10
+...
+loadmodule "registrar.so"
+...
+modparam("registrar", "flow_timer", FLOW_TIMER)
+...
+###TBD###
 
 2. Dependencies
 
@@ -46,7 +137,8 @@ Chapter 1. Admin Guide
 
 2.1. Kamailio Modules
 
-   ...
+   The following modules must be loaded before this module:
+     * None
 
 2.2. External Libraries or Applications
 
@@ -56,12 +148,39 @@ Chapter 1. Admin Guide
 
 3. Parameters
 
-   ...
+   3.1. force_outbound_bflag (integer)
+   3.2. flow_token_key (string)
+
+3.1. force_outbound_bflag (integer)
+
+   A branch 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_bflag parameter
+modparam("outbound", "force_outbound_bflag", 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
diff --git a/modules_k/outbound/doc/outbound_admin.xml b/modules_k/outbound/doc/outbound_admin.xml
index 0a08053..de3e3d3 100644
--- a/modules_k/outbound/doc/outbound_admin.xml
+++ b/modules_k/outbound/doc/outbound_admin.xml
@@ -15,14 +15,94 @@
 	
 	<section>
 	<title>Overview</title>
-	<para>...</para>
+	<para>This module provides C-API functions to enable &kamailio; to be
+	used as an outbound Edge Proxy (see RFC 5626 section 5).</para>
+	<para>The <emphasis>path</emphasis> and <emphasis>rr</emphasis> will
+	bind to this module if it is loaded before they are.</para>
+	<section>
+		<title>Edge Proxy Keep-Alives (STUN)</title>
+		<para>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.</para>
+		<example>
+		<title>Compiling &kamailio; with STUN support</title>
+		<programlisting><![CDATA[
+make FLAVOUR=kamailio cfg STUN=1
+make all
+]]></programlisting>
+		</example>
+	</section>
+	<section>
+		<title>Flow Timer</title>
+		<para>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.</para>
+		<para>When using TCP or TLS as the SIP transport care should
+		be taken to set the <quote>tcp_connection_lifetime</quote>
+		on the Edge Proxy to a value slightly larger than the interval
+		the Registrar is using for flow timer. Setting
+		<quote>tcp_connection_lifetime</quote> 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).</para>
+		<para>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
+		<quote>keepalive_timeout</quote> should be set to a value
+		a little greater than the Registrar flow timer interval and a
+		little less than the <quote>tcp_connection_lifetime</quote>.
+		</para>
+	</section>
+	<example>
+	<title>Edge Proxy Configuration</title>
+	<programlisting><![CDATA[
+...
+#!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!!!")
+...
+###TBD###
+]]></programlisting>
+	</example>
+	<example>
+	<title>Registrar Configuration</title>
+	<programlisting><![CDATA[
+...
+#!define FLOW_TIMER	20
+...
+tcp_connection_lifetime=FLOW_TIMER+10
+...
+loadmodule "registrar.so"
+...
+modparam("registrar", "flow_timer", FLOW_TIMER)
+...
+###TBD###
+]]></programlisting>
+	</example>
 	</section>
 
 	<section>
 	<title>Dependencies</title>
 	<section>
 		<title>&kamailio; Modules</title>
-		<para>...</para>
+		<para>
+		The following modules must be loaded before this module:
+		<itemizedlist>
+		<listitem>
+		<para><emphasis>None</emphasis></para>
+		</listitem>
+		</itemizedlist>
+		</para>
 	</section>
 
 	<section>
@@ -42,17 +122,48 @@
 
 	<section>
 	<title>Parameters</title>
-	<para>...</para>
+	<section>
+		<title><varname>force_outbound_bflag</varname> (integer)</title>
+		<para>A branch flag which, if set for a request, will force
+		<emphasis>path</emphasis> and <emphasis>rr</emphasis> to add
+		flow tokens to Path: and Record-Route: headers regardless of
+		the request contents.</para>
+		<para><emphasis>Default value is -1.</emphasis></para>
+		<example>
+		<title>Set <varname>force_outbound_bflag</varname> parameter
+		</title>
+		<programlisting format="linespecific">
+modparam("outbound", "force_outbound_bflag", 1)
+</programlisting>
+		</example>
+	</section>
+	<section>
+		<title><varname>flow_token_key</varname> (string)</title>
+		<para>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.
+		</para>
+		<note><para>If this 20 character string is not set &kamailio;
+		will not start.</para></note>
+		<para><emphasis>Default value is: "".</emphasis></para>
+		<example>
+		<title>Set <varname>flow_token_key</varname> parameter
+		</title>
+		<programlisting format="linespecific">
+modparam("outbound", "flow_token_key", "!!!Kamailio rocks!!!")
+</programlisting>
+		</example>
+	</section>
 	</section>
 
 	<section>
 	<title>Functions</title>
-	<para>...</para>
+	<para><emphasis>None</emphasis></para>
 	</section>
 
 	<section>
 	<title>MI Commands</title>
-	<para>...</para>
+	<para><emphasis>None</emphasis></para>
 	</section>
 
 </chapter>




More information about the sr-dev mailing list