Browse code

modules_k/outbound: first draft of outbound module documentation

Peter Dunkley authored on 31/12/2012 17:11:30
Showing 2 changed files
... ...
@@ -12,32 +12,123 @@ Peter Dunkley
12 12
    1. Admin Guide
13 13
 
14 14
         1. Overview
15
+
16
+              1.1. Edge Proxy Keep-Alives (STUN)
17
+              1.2. Flow Timer
18
+
15 19
         2. Dependencies
16 20
 
17 21
               2.1. Kamailio Modules
18 22
               2.2. External Libraries or Applications
19 23
 
20 24
         3. Parameters
25
+
26
+              3.1. force_outbound_bflag (integer)
27
+              3.2. flow_token_key (string)
28
+
21 29
         4. Functions
22 30
         5. MI Commands
23 31
 
32
+   List of Examples
33
+
34
+   1.1. Compiling Kamailio with STUN support
35
+   1.2. Edge Proxy Configuration
36
+   1.3. Registrar Configuration
37
+   1.4. Set force_outbound_bflag parameter
38
+   1.5. Set flow_token_key parameter
39
+
24 40
 Chapter 1. Admin Guide
25 41
 
26 42
    Table of Contents
27 43
 
28 44
    1. Overview
45
+
46
+        1.1. Edge Proxy Keep-Alives (STUN)
47
+        1.2. Flow Timer
48
+
29 49
    2. Dependencies
30 50
 
31 51
         2.1. Kamailio Modules
32 52
         2.2. External Libraries or Applications
33 53
 
34 54
    3. Parameters
55
+
56
+        3.1. force_outbound_bflag (integer)
57
+        3.2. flow_token_key (string)
58
+
35 59
    4. Functions
36 60
    5. MI Commands
37 61
 
38 62
 1. Overview
39 63
 
40
-   ...
64
+   1.1. Edge Proxy Keep-Alives (STUN)
65
+   1.2. Flow Timer
66
+
67
+   This module provides C-API functions to enable Kamailio to be used as
68
+   an outbound Edge Proxy (see RFC 5626 section 5).
69
+
70
+   The path and rr will bind to this module if it is loaded before they
71
+   are.
72
+
73
+1.1. Edge Proxy Keep-Alives (STUN)
74
+
75
+   Outbound Edge Proxies MUST support STUN NAT keep-alives on their SIP
76
+   UDP ports. Kamailio supports this as a compile-time option that is
77
+   disabled by default.
78
+
79
+   Example 1.1. Compiling Kamailio with STUN support
80
+make FLAVOUR=kamailio cfg STUN=1
81
+make all
82
+
83
+1.2. Flow Timer
84
+
85
+   The maximum interval at which a User Agent must send a keep-alive may
86
+   be specified by the Registrar using the Flow-Timer: header in 2xx
87
+   responses to REGISTERs.
88
+
89
+   When using TCP or TLS as the SIP transport care should be taken to set
90
+   the “tcp_connection_lifetime” on the Edge Proxy to a value slightly
91
+   larger than the interval the Registrar is using for flow timer. Setting
92
+   “tcp_connection_lifetime” to less than the interval could cause
93
+   connections to be lost, and setting it to a value much larger than the
94
+   interval will keep connections open far longer than is required (which
95
+   is wasteful).
96
+
97
+   Application-layer keep-alives are optional when the underlying
98
+   transport already has a keep-alive mechanism. The WebSocket transport
99
+   has a transport-layer keep-alive. When using the WebSocket transport
100
+   the “keepalive_timeout” should be set to a value a little greater than
101
+   the Registrar flow timer interval and a little less than the
102
+   “tcp_connection_lifetime”.
103
+
104
+   Example 1.2. Edge Proxy Configuration
105
+...
106
+#!define FLOW_TIMER     20
107
+...
108
+tcp_connection_lifetime=FLOW_TIMER+10
109
+...
110
+loadmodule "websocket.so"
111
+loadmodule "outbound.so"
112
+loadmodule "rr.so"
113
+loadmodule "path.so"
114
+...
115
+modparam("websocket", "keepalive_timeout", FLOW_TIMER+5)
116
+...
117
+modparam("outbound", "flow_token_key", "!!!Kamailio rocks!!!")
118
+...
119
+###TBD###
120
+
121
+   Example 1.3. Registrar Configuration
122
+...
123
+#!define FLOW_TIMER     20
124
+...
125
+tcp_connection_lifetime=FLOW_TIMER+10
126
+...
127
+loadmodule "registrar.so"
128
+...
129
+modparam("registrar", "flow_timer", FLOW_TIMER)
130
+...
131
+###TBD###
41 132
 
42 133
 2. Dependencies
43 134
 
... ...
@@ -46,7 +137,8 @@ Chapter 1. Admin Guide
46 137
 
47 138
 2.1. Kamailio Modules
48 139
 
49
-   ...
140
+   The following modules must be loaded before this module:
141
+     * None
50 142
 
51 143
 2.2. External Libraries or Applications
52 144
 
... ...
@@ -56,12 +148,39 @@ Chapter 1. Admin Guide
56 148
 
57 149
 3. Parameters
58 150
 
59
-   ...
151
+   3.1. force_outbound_bflag (integer)
152
+   3.2. flow_token_key (string)
153
+
154
+3.1. force_outbound_bflag (integer)
155
+
156
+   A branch flag which, if set for a request, will force path and rr to
157
+   add flow tokens to Path: and Record-Route: headers regardless of the
158
+   request contents.
159
+
160
+   Default value is -1.
161
+
162
+   Example 1.4. Set force_outbound_bflag parameter
163
+modparam("outbound", "force_outbound_bflag", 1)
164
+
165
+3.2. flow_token_key (string)
166
+
167
+   The outbound flow token is generated using the algorithm described in
168
+   RFC 5626 section 5.2. This algorithm requires a 20 octet crypto random
169
+   key that is unique for each Edge Proxy.
170
+
171
+Note
172
+
173
+   If this 20 character string is not set Kamailio will not start.
174
+
175
+   Default value is: "".
176
+
177
+   Example 1.5. Set flow_token_key parameter
178
+modparam("outbound", "flow_token_key", "!!!Kamailio rocks!!!")
60 179
 
61 180
 4. Functions
62 181
 
63
-   ...
182
+   None
64 183
 
65 184
 5. MI Commands
66 185
 
67
-   ...
186
+   None
... ...
@@ -15,14 +15,94 @@
15 15
 	
16 16
 	<section>
17 17
 	<title>Overview</title>
18
-	<para>...</para>
18
+	<para>This module provides C-API functions to enable &kamailio; to be
19
+	used as an outbound Edge Proxy (see RFC 5626 section 5).</para>
20
+	<para>The <emphasis>path</emphasis> and <emphasis>rr</emphasis> will
21
+	bind to this module if it is loaded before they are.</para>
22
+	<section>
23
+		<title>Edge Proxy Keep-Alives (STUN)</title>
24
+		<para>Outbound Edge Proxies MUST support STUN NAT keep-alives
25
+		on their SIP UDP ports. &kamailio; supports this as a
26
+		compile-time option that is disabled by default.</para>
27
+		<example>
28
+		<title>Compiling &kamailio; with STUN support</title>
29
+		<programlisting><![CDATA[
30
+make FLAVOUR=kamailio cfg STUN=1
31
+make all
32
+]]></programlisting>
33
+		</example>
34
+	</section>
35
+	<section>
36
+		<title>Flow Timer</title>
37
+		<para>The maximum interval at which a User Agent must send a
38
+		keep-alive may be specified by the Registrar using the
39
+		Flow-Timer: header in 2xx responses to REGISTERs.</para>
40
+		<para>When using TCP or TLS as the SIP transport care should
41
+		be taken to set the <quote>tcp_connection_lifetime</quote>
42
+		on the Edge Proxy to a value slightly larger than the interval
43
+		the Registrar is using for flow timer. Setting
44
+		<quote>tcp_connection_lifetime</quote> to less than the
45
+		interval could cause connections to be lost, and setting it
46
+		to a value much larger than the interval will keep connections
47
+		open far longer than is required (which is wasteful).</para>
48
+		<para>Application-layer keep-alives are optional when the
49
+		underlying transport already has a keep-alive mechanism. The
50
+		WebSocket transport has a transport-layer keep-alive. When
51
+		using the WebSocket transport the
52
+		<quote>keepalive_timeout</quote> should be set to a value
53
+		a little greater than the Registrar flow timer interval and a
54
+		little less than the <quote>tcp_connection_lifetime</quote>.
55
+		</para>
56
+	</section>
57
+	<example>
58
+	<title>Edge Proxy Configuration</title>
59
+	<programlisting><![CDATA[
60
+...
61
+#!define FLOW_TIMER	20
62
+...
63
+tcp_connection_lifetime=FLOW_TIMER+10
64
+...
65
+loadmodule "websocket.so"
66
+loadmodule "outbound.so"
67
+loadmodule "rr.so"
68
+loadmodule "path.so"
69
+...
70
+modparam("websocket", "keepalive_timeout", FLOW_TIMER+5)
71
+...
72
+modparam("outbound", "flow_token_key", "!!!Kamailio rocks!!!")
73
+...
74
+###TBD###
75
+]]></programlisting>
76
+	</example>
77
+	<example>
78
+	<title>Registrar Configuration</title>
79
+	<programlisting><![CDATA[
80
+...
81
+#!define FLOW_TIMER	20
82
+...
83
+tcp_connection_lifetime=FLOW_TIMER+10
84
+...
85
+loadmodule "registrar.so"
86
+...
87
+modparam("registrar", "flow_timer", FLOW_TIMER)
88
+...
89
+###TBD###
90
+]]></programlisting>
91
+	</example>
19 92
 	</section>
20 93
 
21 94
 	<section>
22 95
 	<title>Dependencies</title>
23 96
 	<section>
24 97
 		<title>&kamailio; Modules</title>
25
-		<para>...</para>
98
+		<para>
99
+		The following modules must be loaded before this module:
100
+		<itemizedlist>
101
+		<listitem>
102
+		<para><emphasis>None</emphasis></para>
103
+		</listitem>
104
+		</itemizedlist>
105
+		</para>
26 106
 	</section>
27 107
 
28 108
 	<section>
... ...
@@ -42,17 +122,48 @@
42 122
 
43 123
 	<section>
44 124
 	<title>Parameters</title>
45
-	<para>...</para>
125
+	<section>
126
+		<title><varname>force_outbound_bflag</varname> (integer)</title>
127
+		<para>A branch flag which, if set for a request, will force
128
+		<emphasis>path</emphasis> and <emphasis>rr</emphasis> to add
129
+		flow tokens to Path: and Record-Route: headers regardless of
130
+		the request contents.</para>
131
+		<para><emphasis>Default value is -1.</emphasis></para>
132
+		<example>
133
+		<title>Set <varname>force_outbound_bflag</varname> parameter
134
+		</title>
135
+		<programlisting format="linespecific">
136
+modparam("outbound", "force_outbound_bflag", 1)
137
+</programlisting>
138
+		</example>
139
+	</section>
140
+	<section>
141
+		<title><varname>flow_token_key</varname> (string)</title>
142
+		<para>The outbound flow token is generated using the algorithm
143
+		described in RFC 5626 section 5.2. This algorithm requires a 20
144
+		octet crypto random key that is unique for each Edge Proxy.
145
+		</para>
146
+		<note><para>If this 20 character string is not set &kamailio;
147
+		will not start.</para></note>
148
+		<para><emphasis>Default value is: "".</emphasis></para>
149
+		<example>
150
+		<title>Set <varname>flow_token_key</varname> parameter
151
+		</title>
152
+		<programlisting format="linespecific">
153
+modparam("outbound", "flow_token_key", "!!!Kamailio rocks!!!")
154
+</programlisting>
155
+		</example>
156
+	</section>
46 157
 	</section>
47 158
 
48 159
 	<section>
49 160
 	<title>Functions</title>
50
-	<para>...</para>
161
+	<para><emphasis>None</emphasis></para>
51 162
 	</section>
52 163
 
53 164
 	<section>
54 165
 	<title>MI Commands</title>
55
-	<para>...</para>
166
+	<para><emphasis>None</emphasis></para>
56 167
 	</section>
57 168
 
58 169
 </chapter>