Browse code

modules/websocket and pkg/kamailio/fedora: Added websocket module documentation

Peter Dunkley authored on 03/07/2012 22:59:22
Showing 6 changed files
1 1
new file mode 100644
... ...
@@ -0,0 +1,462 @@
1
+WebSocket Module
2
+
3
+Peter Dunkley
4
+
5
+   Crocodile RCS Ltd
6
+
7
+   Copyright © 2012 Crocodile RCS Ltd
8
+     __________________________________________________________________
9
+
10
+   Table of Contents
11
+
12
+   1. Admin Guide
13
+
14
+        1. Overview
15
+        2. How it works
16
+
17
+              2.1. Initiating a connection
18
+              2.2. SIP message routing
19
+
20
+        3. Dependencies
21
+
22
+              3.1. Kamailio Modules
23
+              3.2. External Libraries or Applications
24
+
25
+        4. Parameters
26
+
27
+              4.1. keepalive_mechanism (integer)
28
+              4.2. keepalive_timeout (integer)
29
+              4.3. keepalive_processes (integer)
30
+              4.4. keepalive_interval (integer)
31
+              4.5. ping_application_data (string)
32
+
33
+        5. Functions
34
+
35
+              5.1. ws_handle_handshake()
36
+
37
+        6. MI Commands
38
+
39
+              6.1. ws.dump
40
+              6.2. ws.close
41
+              6.3. ws.ping
42
+              6.4. ws.pong
43
+              6.5. ws.disable
44
+              6.6. ws.enable
45
+
46
+   List of Examples
47
+
48
+   1.1. event_route[xhttp:request]
49
+   1.2. WebSocket SIP Routing
50
+   1.3. Set keepalive_mechanism parameter
51
+   1.4. Set keepalive_timeout parameter
52
+   1.5. Set keepalive_processes parameter
53
+   1.6. Set keepalive_interval parameter
54
+   1.7. Set ping_application_data parameter
55
+   1.8. ws_handle_handshake usage
56
+
57
+Chapter 1. Admin Guide
58
+
59
+   Table of Contents
60
+
61
+   1. Overview
62
+   2. How it works
63
+
64
+        2.1. Initiating a connection
65
+        2.2. SIP message routing
66
+
67
+   3. Dependencies
68
+
69
+        3.1. Kamailio Modules
70
+        3.2. External Libraries or Applications
71
+
72
+   4. Parameters
73
+
74
+        4.1. keepalive_mechanism (integer)
75
+        4.2. keepalive_timeout (integer)
76
+        4.3. keepalive_processes (integer)
77
+        4.4. keepalive_interval (integer)
78
+        4.5. ping_application_data (string)
79
+
80
+   5. Functions
81
+
82
+        5.1. ws_handle_handshake()
83
+
84
+   6. MI Commands
85
+
86
+        6.1. ws.dump
87
+        6.2. ws.close
88
+        6.3. ws.ping
89
+        6.4. ws.pong
90
+        6.5. ws.disable
91
+        6.6. ws.enable
92
+
93
+1. Overview
94
+
95
+   This module implements a WebSocket (RFC 6455) server and provides
96
+   connection establishment (handshaking), management (including
97
+   connection keep-alive), and framing for the SIP WebSocket sub-protocol
98
+   (ietf-draft-sipcore-sip-websocket).
99
+
100
+   The module supports WebSockets (ws) and secure WebSockets (wss)
101
+
102
+2. How it works
103
+
104
+   2.1. Initiating a connection
105
+   2.2. SIP message routing
106
+
107
+2.1. Initiating a connection
108
+
109
+   A WebSocket connection is initiated with an HTTP GET. The xhttp module
110
+   is used to handle this GET and call the Section 5.1, “
111
+   ws_handle_handshake() ” exported function.
112
+
113
+   event_route[xhttp:request] should perform some validation of the HTTP
114
+   headers before calling Section 5.1, “ ws_handle_handshake() ”. The
115
+   event_route can also be used to make sure the HTTP GET has the correct
116
+   URI, perform HTTP authentication on the WebSocket connection, and check
117
+   the Origin header (RFC 6454) to ensure a browser-based SIP UA has been
118
+   downloaded from the correct location.
119
+
120
+   Example 1.1. event_route[xhttp:request]
121
+...
122
+loadmodule "sl.so"
123
+loadmodule "xhttp.so"
124
+loadmodule "websocket.so"
125
+...
126
+event_route[xhttp:request] {
127
+        set_reply_close();
128
+        set_reply_no_connect();
129
+
130
+        if ($Rp != 80 && $Rp != 443) {
131
+                xlog("L_WARN", "HTTP request received on $Rp\n");
132
+                xhttp_reply("403", "Forbidden", "", "");
133
+                exit;
134
+        }
135
+
136
+        xlog("L_DBG", "HTTP Request Received\n");
137
+
138
+        if ($hdr(Upgrade)=~"websocket"
139
+                        && $hdr(Connection)=~"Upgrade"
140
+                        && $rm=~"GET") {
141
+                xlog("L_DBG", "WebSocket\n");
142
+                xlog("L_DBG", " Host: $hdr(Host)\n");
143
+                xlog("L_DBG", " Origin: $hdr(Origin)\n");
144
+
145
+                if ($hdr(Host) == $null || !is_myself($hdr(Host))) {
146
+                        xlog("L_WARN", "Bad host $hdr(Host)\n");
147
+                        xhttp_reply("403", "Forbidden", "", "");
148
+                        exit;
149
+                }
150
+
151
+                # Optional... validate Origin
152
+                # Optional... perform HTTP authentication
153
+
154
+                # ws_handle_handshake() exits (no further configuration file
155
+                # processing of the request) when complete.
156
+                ws_handle_handshake();
157
+        }
158
+
159
+        xhttp_reply("404", "Not found", "", "");
160
+}
161
+...
162
+
163
+2.2. SIP message routing
164
+
165
+   SIP over WebSockets uses invalid URIs in routing headers (Contact:,
166
+   Record-Route:, and Via:) because a JavaScript stack running in a
167
+   browser has no way to determine the local address from which the
168
+   WebSocket connection is made. This means that the routing headers
169
+   cannot be used for request or response routing in the normal manner.
170
+
171
+   ietf-draft-sipcore-sip-websocket states that SIP WebSocket Clients and
172
+   the SIP registrar should implement Outbound (RFC 5626) and Path (RFC
173
+   3327) to enable requests and responses to be correctly routed. However,
174
+   Kamailio does not currently support Outbound and it may not be possible
175
+   to guarantee all SIP WebSocket clients will support Outbound and Path.
176
+
177
+   The nathelper module functions (nat_uac_test(), fix_nated_register(),
178
+   add_contact_alias(), and handle_ruri_alias()) and the Kamailio core
179
+   force_rport() can be used to ensure correct routing of SIP WebSocket
180
+   requests without using Outbound and Path.
181
+
182
+   Example 1.2. WebSocket SIP Routing
183
+...
184
+loadmodule "sl.so"
185
+loadmodule "tm.so"
186
+...
187
+loadmodule "websocket.so"
188
+...
189
+request_route {
190
+
191
+        # per request initial checks
192
+        route(REQINIT);
193
+
194
+        if (nat_uac_test(64)) {
195
+                # Do NAT traversal stuff for requests from a WebSocket
196
+                # connection - even if it is not behind a NAT!
197
+                # This won't be needed in the future if Kamailio and the
198
+                # WebSocket client support Outbound and Path.
199
+                force_rport();
200
+                if (is_method("REGISTER"))
201
+                        fix_nated_register();
202
+                else {
203
+                        if (!add_contact_alias()) {
204
+                                xlog("L_ERR", "Error aliasing contact <$ct>\n");
205
+                                sl_send_reply("400", "Bad Request");
206
+                                exit;
207
+                        }
208
+                }
209
+        }
210
+
211
+        if (!is_method("REGISTER"))
212
+                t_on_reply("WS_REPLY");
213
+...
214
+# Handle requests within SIP dialogs
215
+route[WITHINDLG] {
216
+        if (has_totag()) {
217
+                # sequential request withing a dialog should
218
+                # take the path determined by record-routing
219
+                if (loose_route()) {
220
+                        if ($du == "") {
221
+                                if (!handle_ruri_alias()) {
222
+                                        xlog("L_ERR", "Bad alias <$ru>\n");
223
+                                        sl_send_reply("400", "Bad Request");
224
+                                        exit;
225
+                                }
226
+                        }
227
+                        route(RELAY);
228
+                } else {
229
+                        if ( is_method("ACK") ) {
230
+...
231
+onreply_route[WS_REPLY] {
232
+        if (nat_uac_test(64)) {
233
+                # Do NAT traversal stuff for replies to a WebSocket connection
234
+                # - even if it is not behind a NAT!
235
+                # This won't be needed in the future if Kamailio and the
236
+                # WebSocket client support Outbound and Path.
237
+                add_contact_alias();
238
+        }
239
+}
240
+...
241
+
242
+3. Dependencies
243
+
244
+   3.1. Kamailio Modules
245
+   3.2. External Libraries or Applications
246
+
247
+3.1. Kamailio Modules
248
+
249
+   The following module must be loaded before this module:
250
+     * sl.
251
+
252
+   The following modules are required to make proper use of this module:
253
+     * nathelper.
254
+     * tm.
255
+     * xhttp.
256
+
257
+   The following module is required to use the secure WebSocket (wss)
258
+   scheme:
259
+     * tls.
260
+
261
+3.2. External Libraries or Applications
262
+
263
+   The following libraries must be installed before running Kamailio with
264
+   this module loaded:
265
+     * OpenSSL.
266
+     * GNU libunistring.
267
+
268
+4. Parameters
269
+
270
+   4.1. keepalive_mechanism (integer)
271
+   4.2. keepalive_timeout (integer)
272
+   4.3. keepalive_processes (integer)
273
+   4.4. keepalive_interval (integer)
274
+   4.5. ping_application_data (string)
275
+
276
+4.1. keepalive_mechanism (integer)
277
+
278
+   The keep-alive mechanism to use for WebSocket connections.
279
+
280
+Note
281
+
282
+   If nathelper is only being used for WebSocket connections then
283
+   nathelper NAT pinging is not required. If nathelper is used for
284
+   WebSocket connections and TCP/TLS aliasing/NAT-traversal then WebSocket
285
+   keep-alives are not required.
286
+
287
+     * 0 - no WebSocket keep-alives
288
+     * 1 - Ping WebSocket keep-alives
289
+     * 2 - Pong WebSocket keep-alives
290
+
291
+   Default value is 1.
292
+
293
+   Example 1.3. Set keepalive_mechanism parameter
294
+...
295
+modparam("websocket", "keepalive_mechanism", 0)
296
+...
297
+
298
+4.2. keepalive_timeout (integer)
299
+
300
+   The time (in seconds) after which to send a keep-alive on idle
301
+   WebSocket connections.
302
+
303
+   Default value is 180.
304
+
305
+   Example 1.4. Set keepalive_timeout parameter
306
+...
307
+modparam("websocket", "keepalive_timeout", 30)
308
+...
309
+
310
+4.3. keepalive_processes (integer)
311
+
312
+   The number of processes to start to perform WebSocket connection
313
+   keep-alives.
314
+
315
+   Default value is 1.
316
+
317
+   Example 1.5. Set keepalive_processes parameter
318
+...
319
+modparam("websocket", "keepalive_processes", 2)
320
+...
321
+
322
+4.4. keepalive_interval (integer)
323
+
324
+   The number of seconds between each keep-alice process run
325
+
326
+   Default value is 1.
327
+
328
+   Example 1.6. Set keepalive_interval parameter
329
+...
330
+modparam("websocket", "keepalive_interval", 2)
331
+...
332
+
333
+4.5. ping_application_data (string)
334
+
335
+   The application data to use in keep-alive Ping and Pong frames.
336
+
337
+   Default value is Kamailio Server: header content
338
+
339
+   Example 1.7. Set ping_application_data parameter
340
+...
341
+modparam("websocket", "ping_application_data", "WebSockets rock")
342
+...
343
+
344
+5. Functions
345
+
346
+   5.1. ws_handle_handshake()
347
+
348
+5.1.  ws_handle_handshake()
349
+
350
+   This function checks an HTTP GET request for the required headers and
351
+   values, and (if successful) upgrades the connection from HTTP to
352
+   WebSocket.
353
+
354
+   This function can be used from ANY_ROUTE (but will only work in
355
+   event_route[xhttp:request]).
356
+
357
+Note
358
+
359
+   This function always returns 0, stopping all further processing of the
360
+   request.
361
+
362
+   Example 1.8. ws_handle_handshake usage
363
+...
364
+ws_handle_handshake();
365
+...
366
+
367
+6. MI Commands
368
+
369
+   6.1. ws.dump
370
+   6.2. ws.close
371
+   6.3. ws.ping
372
+   6.4. ws.pong
373
+   6.5. ws.disable
374
+   6.6. ws.enable
375
+
376
+6.1. ws.dump
377
+
378
+   Provides the details of the first 50 WebSocket connections.
379
+
380
+   Name: ws.dump
381
+
382
+   Parameters:
383
+     * order (optional) - “id_hash”, “used_desc”, or “used_asc”.
384
+
385
+Note
386
+
387
+   If no parameter is provided id_hash order is used.
388
+
389
+   MI FIFO Command Format:
390
+                        :ws.dump:fifo_reply
391
+                        used_asc
392
+                        _empty_line_
393
+
394
+6.2. ws.close
395
+
396
+   Starts the close handshake for the specified WebSocket connection.
397
+
398
+   Name: ws.close
399
+
400
+   Parameters:
401
+     * id - WebSocket connection ID.
402
+
403
+   MI FIFO Command Format:
404
+                        :ws.close:fifo_reply
405
+                        1
406
+                        _empty_line_
407
+
408
+6.3. ws.ping
409
+
410
+   Sends a Ping frame on the specified WebSocket connection.
411
+
412
+   Name: ws.ping
413
+
414
+   Parameters:
415
+     * id - WebSocket connection ID.
416
+
417
+   MI FIFO Command Format:
418
+                        :ws.ping:fifo_reply
419
+                        1
420
+                        _empty_line_
421
+
422
+6.4. ws.pong
423
+
424
+   Sends a Pong frame on the specified WebSocket connection.
425
+
426
+   Name: ws.pong
427
+
428
+   Parameters:
429
+     * id - WebSocket connection ID.
430
+
431
+   MI FIFO Command Format:
432
+                        :ws.pong:fifo_reply
433
+                        1
434
+                        _empty_line_
435
+
436
+6.5. ws.disable
437
+
438
+   Disables WebSockets preventing new connections from being established.
439
+
440
+   Name: ws.disable
441
+
442
+   Parameters: none
443
+
444
+   MI FIFO Command Format:
445
+                        :ws.disable:fifo_reply
446
+                        _empty_line_
447
+
448
+6.6. ws.enable
449
+
450
+   Enables WebSockets allowing new connections to be established.
451
+
452
+Note
453
+
454
+   WebSockets are enabled at start-up.
455
+
456
+   Name: ws.enable
457
+
458
+   Parameters: none
459
+
460
+   MI FIFO Command Format:
461
+                        :ws.enable:fifo_reply
462
+                        _empty_line_
0 463
new file mode 100644
... ...
@@ -0,0 +1,4 @@
1
+docs = websocket.xml
2
+
3
+docbook_dir = ../../../docbook
4
+include $(docbook_dir)/Makefile.module
0 5
new file mode 100644
... ...
@@ -0,0 +1,33 @@
1
+<?xml version="1.0" encoding='ISO-8859-1'?>
2
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3
+"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
4
+
5
+<!-- Include general documentation entities -->
6
+<!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
7
+%docentities;
8
+
9
+]>
10
+
11
+<book xmlns:xi="http://www.w3.org/2001/XInclude">
12
+	<bookinfo>
13
+	<title>WebSocket Module</title>
14
+	<productname class="trade">&kamailioname;</productname>
15
+	<authorgroup>
16
+		<author>
17
+		<firstname>Peter</firstname>
18
+		<surname>Dunkley</surname>
19
+		<affiliation><orgname>Crocodile RCS Ltd</orgname></affiliation>
20
+		<address>
21
+			<email>peter.dunkley@crocodile-rcs.com</email>
22
+		</address>
23
+		</author>
24
+	</authorgroup>
25
+	<copyright>
26
+		<year>2012</year>
27
+		<holder>Crocodile RCS Ltd</holder>
28
+	</copyright>
29
+	</bookinfo>
30
+	<toc></toc>
31
+	
32
+	<xi:include href="websocket_admin.xml"/>
33
+</book>
0 34
new file mode 100644
... ...
@@ -0,0 +1,472 @@
1
+<?xml version="1.0" encoding='ISO-8859-1'?>
2
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3
+"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
4
+
5
+<!-- Include general documentation entities -->
6
+<!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
7
+%docentities;
8
+
9
+]>
10
+<!-- Module User's Guide -->
11
+
12
+<chapter>
13
+	
14
+	<title>&adminguide;</title>
15
+	
16
+	<section>
17
+	<title>Overview</title>
18
+	<para>This module implements a WebSocket (RFC 6455) server and provides
19
+	connection establishment (handshaking), management (including
20
+	connection keep-alive), and framing for the SIP WebSocket sub-protocol
21
+	(ietf-draft-sipcore-sip-websocket).</para>
22
+	<para>The module supports WebSockets (ws) and secure WebSockets (wss)
23
+	</para>
24
+	</section>
25
+
26
+	<section>
27
+	<title>How it works</title>
28
+	<section>
29
+	<title>Initiating a connection</title>
30
+	<para>A WebSocket connection is initiated with an HTTP GET.  The
31
+	<emphasis>xhttp</emphasis> module is used to handle this GET and
32
+	call the <xref linkend="ws_handle_handshake"/> exported function.
33
+	</para>
34
+	<para><emphasis>event_route[xhttp:request]</emphasis> should perform
35
+	some validation of the HTTP headers before calling
36
+	<xref linkend="ws_handle_handshake"/>.  The event_route can also be
37
+	used to make sure the HTTP GET has the correct URI, perform HTTP
38
+	authentication on the WebSocket connection, and check the
39
+	<emphasis>Origin</emphasis> header (RFC 6454) to ensure a
40
+	browser-based SIP UA has been downloaded from the correct location.
41
+	</para>
42
+	<example>
43
+	<title>event_route[xhttp:request]</title>
44
+	<programlisting><![CDATA[
45
+...
46
+loadmodule "sl.so"
47
+loadmodule "xhttp.so"
48
+loadmodule "websocket.so"
49
+...
50
+event_route[xhttp:request] {
51
+        set_reply_close();
52
+        set_reply_no_connect();
53
+
54
+        if ($Rp != 80 && $Rp != 443) {
55
+                xlog("L_WARN", "HTTP request received on $Rp\n");
56
+                xhttp_reply("403", "Forbidden", "", "");
57
+                exit;
58
+        }
59
+
60
+        xlog("L_DBG", "HTTP Request Received\n");
61
+
62
+        if ($hdr(Upgrade)=~"websocket"
63
+                        && $hdr(Connection)=~"Upgrade"
64
+                        && $rm=~"GET") {
65
+                xlog("L_DBG", "WebSocket\n");
66
+                xlog("L_DBG", " Host: $hdr(Host)\n");
67
+                xlog("L_DBG", " Origin: $hdr(Origin)\n");
68
+
69
+                if ($hdr(Host) == $null || !is_myself($hdr(Host))) {
70
+                        xlog("L_WARN", "Bad host $hdr(Host)\n");
71
+                        xhttp_reply("403", "Forbidden", "", "");
72
+                        exit;
73
+                }
74
+
75
+                # Optional... validate Origin
76
+                # Optional... perform HTTP authentication
77
+
78
+                # ws_handle_handshake() exits (no further configuration file
79
+                # processing of the request) when complete.
80
+                ws_handle_handshake();
81
+        }
82
+
83
+        xhttp_reply("404", "Not found", "", "");
84
+}
85
+...
86
+]]></programlisting>
87
+	</example>
88
+	</section>
89
+
90
+	<section>
91
+	<title>SIP message routing</title>
92
+	<para> SIP over WebSockets uses invalid URIs in routing headers
93
+	(Contact:, Record-Route:, and Via:) because a JavaScript stack running
94
+	in a browser has no way to determine the local address from which the
95
+	WebSocket connection is made.  This means that the routing headers
96
+	cannot be used for request or response routing in the normal manner.
97
+	</para>
98
+	<para>ietf-draft-sipcore-sip-websocket states that SIP WebSocket
99
+	Clients and the SIP registrar should implement Outbound (RFC 5626) and
100
+	Path (RFC 3327) to enable requests and responses to be correctly
101
+	routed.  However, &kamailio; does not currently support Outbound and
102
+	it may not be possible to guarantee all SIP WebSocket clients will
103
+	support Outbound and Path.</para>
104
+	<para>The <emphasis>nathelper</emphasis> module functions
105
+	(<emphasis>nat_uac_test()</emphasis>, 
106
+	<emphasis>fix_nated_register()</emphasis>,
107
+	<emphasis>add_contact_alias()</emphasis>, and
108
+	<emphasis>handle_ruri_alias()</emphasis>) and the Kamailio core
109
+	<emphasis>force_rport()</emphasis> can be used to ensure correct
110
+	routing of SIP WebSocket requests without using Outbound and Path.
111
+	</para>
112
+	<example>
113
+	<title>WebSocket SIP Routing</title>
114
+	<programlisting><![CDATA[
115
+...
116
+loadmodule "sl.so"
117
+loadmodule "tm.so"
118
+...
119
+loadmodule "websocket.so"
120
+...
121
+request_route {
122
+
123
+        # per request initial checks
124
+        route(REQINIT);
125
+
126
+        if (nat_uac_test(64)) {
127
+                # Do NAT traversal stuff for requests from a WebSocket
128
+                # connection - even if it is not behind a NAT!
129
+                # This won't be needed in the future if Kamailio and the
130
+                # WebSocket client support Outbound and Path.
131
+                force_rport();
132
+                if (is_method("REGISTER"))
133
+                        fix_nated_register();
134
+                else {
135
+                        if (!add_contact_alias()) {
136
+                                xlog("L_ERR", "Error aliasing contact <$ct>\n");
137
+                                sl_send_reply("400", "Bad Request");
138
+                                exit;
139
+                        }
140
+                }
141
+        }
142
+
143
+        if (!is_method("REGISTER"))
144
+                t_on_reply("WS_REPLY");
145
+...
146
+# Handle requests within SIP dialogs
147
+route[WITHINDLG] {
148
+        if (has_totag()) {
149
+                # sequential request withing a dialog should
150
+                # take the path determined by record-routing
151
+                if (loose_route()) {
152
+                        if ($du == "") {
153
+                                if (!handle_ruri_alias()) {
154
+                                        xlog("L_ERR", "Bad alias <$ru>\n");
155
+                                        sl_send_reply("400", "Bad Request");
156
+                                        exit;
157
+                                }
158
+                        }
159
+                        route(RELAY);
160
+                } else {
161
+                        if ( is_method("ACK") ) {
162
+...
163
+onreply_route[WS_REPLY] {
164
+        if (nat_uac_test(64)) {
165
+                # Do NAT traversal stuff for replies to a WebSocket connection
166
+		# - even if it is not behind a NAT!
167
+                # This won't be needed in the future if Kamailio and the
168
+		# WebSocket client support Outbound and Path.
169
+                add_contact_alias();
170
+        }
171
+}
172
+...
173
+]]></programlisting>
174
+	</example>
175
+
176
+	</section>
177
+	</section>
178
+
179
+	<section>
180
+	<title>Dependencies</title>
181
+	<section>
182
+		<title>&kamailio; Modules</title>
183
+		<para>
184
+		The following module must be loaded before this module:
185
+		<itemizedlist>
186
+		<listitem>
187
+		<para><emphasis>sl</emphasis>.</para>
188
+		</listitem>
189
+		</itemizedlist>
190
+		</para>
191
+		<para>
192
+		The following modules are required to make proper use of this
193
+		module:
194
+		<itemizedlist>
195
+		<listitem>
196
+		<para><emphasis>nathelper</emphasis>.</para>
197
+		</listitem>
198
+		<listitem>
199
+		<para><emphasis>tm</emphasis>.</para>
200
+		</listitem>
201
+		<listitem>
202
+		<para><emphasis>xhttp</emphasis>.</para>
203
+		</listitem>
204
+		</itemizedlist>
205
+		</para>
206
+		<para>
207
+		The following module is required to use the secure WebSocket
208
+		(wss) scheme:
209
+		<itemizedlist>
210
+		<listitem>
211
+		<para><emphasis>tls</emphasis>.</para>
212
+		</listitem>
213
+		</itemizedlist>
214
+		</para>
215
+	</section>
216
+
217
+	<section>
218
+		<title>External Libraries or Applications</title>
219
+		<para>
220
+		The following libraries must be installed before running
221
+		&kamailio; with this module loaded:
222
+		<itemizedlist>
223
+		<listitem>
224
+		<para><emphasis>OpenSSL</emphasis>.</para>
225
+		</listitem>
226
+		<listitem>
227
+		<para><emphasis>GNU libunistring</emphasis>.</para>
228
+		</listitem>
229
+		</itemizedlist>
230
+		</para>
231
+	</section>
232
+	</section>
233
+
234
+
235
+	<section>
236
+	<title>Parameters</title>
237
+	<section>
238
+		<title><varname>keepalive_mechanism</varname> (integer)</title>
239
+		<para>The keep-alive mechanism to use for WebSocket connections.
240
+		</para>
241
+		<note><para>If <emphasis>nathelper</emphasis> is only being used
242
+		for WebSocket connections then <emphasis>nathelper NAT
243
+		pinging</emphasis> is not required.  If
244
+		<emphasis>nathelper</emphasis> is used for WebSocket connections
245
+		and TCP/TLS aliasing/NAT-traversal then WebSocket keep-alives
246
+		are not required.</para></note>
247
+		<para>
248
+		<itemizedlist>
249
+		<listitem><para> 0 - no WebSocket keep-alives</para></listitem>
250
+		<listitem><para> 1 - Ping WebSocket
251
+		keep-alives</para></listitem>
252
+		<listitem><para> 2 - Pong WebSocket
253
+		keep-alives</para></listitem>
254
+		</itemizedlist>
255
+		</para>
256
+		<para><emphasis>Default value is 1.</emphasis></para>
257
+		<example>
258
+		<title>Set <varname>keepalive_mechanism</varname>
259
+		parameter</title>
260
+		<programlisting format="linespecific">
261
+...
262
+modparam("websocket", "keepalive_mechanism", 0)
263
+...
264
+</programlisting>
265
+		</example>
266
+	</section>
267
+
268
+	<section>
269
+		<title><varname>keepalive_timeout</varname> (integer)</title>
270
+		<para>The time (in seconds) after which to send a keep-alive on
271
+		idle WebSocket connections.</para>
272
+		<para><emphasis>Default value is 180.</emphasis></para>
273
+		<example>
274
+		<title>Set <varname>keepalive_timeout</varname>
275
+		parameter</title>
276
+		<programlisting format="linespecific">
277
+...
278
+modparam("websocket", "keepalive_timeout", 30)
279
+...
280
+</programlisting>
281
+		</example>
282
+	</section>
283
+
284
+	<section>
285
+		<title><varname>keepalive_processes</varname> (integer)</title>
286
+		<para>The number of processes to start to perform WebSocket
287
+		connection keep-alives.</para>
288
+		<para><emphasis>Default value is 1.</emphasis></para>
289
+		<example>
290
+		<title>Set <varname>keepalive_processes</varname>
291
+		parameter</title>
292
+		<programlisting format="linespecific">
293
+...
294
+modparam("websocket", "keepalive_processes", 2)
295
+...
296
+</programlisting>
297
+		</example>
298
+	</section>
299
+
300
+	<section>
301
+		<title><varname>keepalive_interval</varname> (integer)</title>
302
+		<para>The number of seconds between each keep-alice process run
303
+		</para>
304
+		<para><emphasis>Default value is 1.</emphasis></para>
305
+		<example>
306
+		<title>Set <varname>keepalive_interval</varname>
307
+		parameter</title>
308
+		<programlisting format="linespecific">
309
+...
310
+modparam("websocket", "keepalive_interval", 2)
311
+...
312
+</programlisting>
313
+		</example>
314
+	</section>
315
+
316
+	<section>
317
+		<title><varname>ping_application_data</varname> (string)</title>
318
+		<para>The application data to use in keep-alive Ping and Pong
319
+		frames.</para>
320
+		<para><emphasis>Default value is &kamailio; Server: header
321
+		content</emphasis></para>
322
+		<example>
323
+		<title>Set <varname>ping_application_data</varname>
324
+		parameter</title>
325
+		<programlisting format="linespecific">
326
+...
327
+modparam("websocket", "ping_application_data", "WebSockets rock")
328
+...
329
+</programlisting>
330
+		</example>
331
+	</section>
332
+
333
+	</section>
334
+
335
+	<section>
336
+	<title>Functions</title>
337
+	<section id="ws_handle_handshake">
338
+		<title>
339
+		<function moreinfo="none">ws_handle_handshake()</function>
340
+		</title>
341
+		<para>This function checks an HTTP GET request for the required
342
+		headers and values, and (if successful) upgrades the connection
343
+		from HTTP to WebSocket.</para>
344
+		<para>This function can be used from ANY_ROUTE (but will only
345
+		work in <emphasis>event_route[xhttp:request]</emphasis>).</para>
346
+		<note><para>This function always returns 0, stopping all further
347
+		processing of the request.</para></note>
348
+		<example>
349
+		<title><function>ws_handle_handshake</function> usage</title>
350
+		<programlisting format="linespecific">
351
+...
352
+ws_handle_handshake();
353
+...
354
+</programlisting>
355
+		</example>
356
+	</section>
357
+	</section>
358
+
359
+	<section>
360
+	<title>MI Commands</title>
361
+	<section>
362
+		<title><function moreinfo="none">ws.dump</function></title>
363
+		<para>Provides the details of the first 50 WebSocket
364
+		connections.</para>
365
+		<para>Name: <emphasis>ws.dump</emphasis></para>
366
+		<para>Parameters:</para>
367
+		<itemizedlist>
368
+			<listitem>
369
+				<para>order (optional) -
370
+				<quote>id_hash</quote>,
371
+				<quote>used_desc</quote>, or
372
+				<quote>used_asc</quote>.</para>
373
+			</listitem>
374
+		</itemizedlist>
375
+		<note><para>If no parameter is provided id_hash order is
376
+		used.</para></note>
377
+		<para>MI FIFO Command Format:</para>
378
+		<programlisting  format="linespecific">
379
+			:ws.dump:fifo_reply
380
+			used_asc
381
+			_empty_line_
382
+</programlisting>
383
+	</section>
384
+
385
+	<section>
386
+		<title><function moreinfo="none">ws.close</function></title>
387
+		<para>Starts the close handshake for the specified
388
+		WebSocket connection.</para>
389
+		<para>Name: <emphasis>ws.close</emphasis></para>
390
+		<para>Parameters:</para>
391
+		<itemizedlist>
392
+			<listitem>
393
+				<para>id - WebSocket connection ID.</para>
394
+			</listitem>
395
+		</itemizedlist>
396
+		<para>MI FIFO Command Format:</para>
397
+		<programlisting  format="linespecific">
398
+			:ws.close:fifo_reply
399
+			1
400
+			_empty_line_
401
+</programlisting>
402
+	</section>
403
+
404
+	<section>
405
+		<title><function moreinfo="none">ws.ping</function></title>
406
+		<para>Sends a Ping frame on the specified WebSocket
407
+		connection.</para>
408
+		<para>Name: <emphasis>ws.ping</emphasis></para>
409
+		<para>Parameters:</para>
410
+		<itemizedlist>
411
+			<listitem>
412
+				<para>id - WebSocket connection ID.</para>
413
+			</listitem>
414
+		</itemizedlist>
415
+		<para>MI FIFO Command Format:</para>
416
+		<programlisting  format="linespecific">
417
+			:ws.ping:fifo_reply
418
+			1
419
+			_empty_line_
420
+</programlisting>
421
+	</section>
422
+
423
+	<section>
424
+		<title><function moreinfo="none">ws.pong</function></title>
425
+		<para>Sends a Pong frame on the specified WebSocket
426
+		connection.</para>
427
+		<para>Name: <emphasis>ws.pong</emphasis></para>
428
+		<para>Parameters:</para>
429
+		<itemizedlist>
430
+			<listitem>
431
+				<para>id - WebSocket connection ID.</para>
432
+			</listitem>
433
+		</itemizedlist>
434
+		<para>MI FIFO Command Format:</para>
435
+		<programlisting  format="linespecific">
436
+			:ws.pong:fifo_reply
437
+			1
438
+			_empty_line_
439
+</programlisting>
440
+	</section>
441
+
442
+	<section>
443
+		<title><function moreinfo="none">ws.disable</function></title>
444
+		<para>Disables WebSockets preventing new connections from
445
+		being established.</para>
446
+		<para>Name: <emphasis>ws.disable</emphasis></para>
447
+		<para>Parameters: <emphasis>none</emphasis></para>
448
+		<para>MI FIFO Command Format:</para>
449
+		<programlisting  format="linespecific">
450
+			:ws.disable:fifo_reply
451
+			_empty_line_
452
+</programlisting>
453
+	</section>
454
+
455
+	<section>
456
+		<title><function moreinfo="none">ws.enable</function></title>
457
+		<para>Enables WebSockets allowing new connections to be
458
+		established.</para>
459
+		<note><para>WebSockets are enabled at start-up.</para></note>
460
+		<para>Name: <emphasis>ws.enable</emphasis></para>
461
+		<para>Parameters: <emphasis>none</emphasis></para>
462
+		<para>MI FIFO Command Format:</para>
463
+		<programlisting  format="linespecific">
464
+			:ws.enable:fifo_reply
465
+			_empty_line_
466
+</programlisting>
467
+	</section>
468
+
469
+
470
+	</section>
471
+</chapter>
472
+
... ...
@@ -140,7 +140,7 @@ request_route {
140 140
 		# Do NAT traversal stuff for requests from a WebSocket
141 141
 		# connection - even if it is not behind a NAT!
142 142
 		# This won't be needed in the future if Kamailio and the
143
-		# WebSocket client support outbound.
143
+		# WebSocket client support Outbound and Path.
144 144
 		force_rport();
145 145
 		if (is_method("REGISTER"))
146 146
 			fix_nated_register();
... ...
@@ -301,10 +301,10 @@ route[AUTH] {
301 301
 #!ifdef WITH_WEBSOCKETS
302 302
 onreply_route[WS_REPLY] {
303 303
 	if (nat_uac_test(64)) {
304
-		# Do NAT traversal stuff for replies to a WebSocket connection - even
305
-		# if it is not behind a NAT!
306
-		# This won't be needed in the future if Kamailio and the WebSocket
307
-		# client support outbound.
304
+		# Do NAT traversal stuff for replies to a WebSocket connection
305
+		# - even if it is not behind a NAT!
306
+		# This won't be needed in the future if Kamailio and the
307
+		# WebSocket client support Outbound and Path.
308 308
 		add_contact_alias();
309 309
 	}
310 310
 }
... ...
@@ -904,7 +904,7 @@ fi
904 904
 
905 905
 %files websocket
906 906
 %defattr(-,root,root)
907
-#%doc %{_docdir}/kamailio/modules/README.websocket
907
+%doc %{_docdir}/kamailio/modules/README.websocket
908 908
 %{_libdir}/kamailio/modules/websocket.so
909 909
 
910 910
 
... ...
@@ -956,6 +956,8 @@ fi
956 956
 
957 957
 
958 958
 %changelog
959
+* Tue Jul 3 2012 Peter Dunkley <peter@dunkley.me.uk>
960
+  - Updates to websocket module
959 961
 * Sat Jun 30 2012 Peter Dunkley <peter@dunkley.me.uk>
960 962
   - Updated rel to dev1
961 963
   - Removed %_sharedir and replaced with standard macro %_datadir