modules: readme files regenerated - websocket ...
[sip-router] / src / modules / websocket / README
1 WebSocket Module
2
3 Peter Dunkley
4
5    Crocodile RCS Ltd
6
7    Copyright © 2012-2013 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               2.3. MSRP message routing
20
21         3. Dependencies
22
23               3.1. Kamailio Modules
24               3.2. External Libraries or Applications
25
26         4. Parameters
27
28               4.1. keepalive_mechanism (integer)
29               4.2. keepalive_timeout (integer)
30               4.3. keepalive_processes (integer)
31               4.4. keepalive_interval (integer)
32               4.5. ping_application_data (string)
33               4.6. sub_protocols (integer)
34               4.7. cors_mode (integer)
35               4.8. verbose_list (int)
36
37         5. Functions
38
39               5.1. ws_handle_handshake()
40               5.2. ws_close([status, reason[, connection_id]])
41
42         6. RPC Commands
43
44               6.1. ws.dump
45               6.2. ws.close
46               6.3. ws.ping
47               6.4. ws.pong
48               6.5. ws.disable
49               6.6. ws.enable
50
51         7. Event routes
52
53               7.1. websocket:closed
54
55         8. Exported Pseudo Variables
56
57               8.1. $ws_conid
58
59    List of Examples
60
61    1.1. event_route[xhttp:request]
62    1.2. WebSocket SIP Routing
63    1.3. Set keepalive_mechanism parameter
64    1.4. Set keepalive_timeout parameter
65    1.5. Set keepalive_processes parameter
66    1.6. Set keepalive_interval parameter
67    1.7. Set ping_application_data parameter
68    1.8. Set sub_protocols parameter
69    1.9. Set cors_mode parameter
70    1.10. Set verbose_list parameter
71    1.11. ws_handle_handshake usage
72    1.12. ws_close usage
73    1.13. event_route[websocket:closed] usage
74    1.14. $ws_conid usage
75
76 Chapter 1. Admin Guide
77
78    Table of Contents
79
80    1. Overview
81    2. How it works
82
83         2.1. Initiating a connection
84         2.2. SIP message routing
85         2.3. MSRP message routing
86
87    3. Dependencies
88
89         3.1. Kamailio Modules
90         3.2. External Libraries or Applications
91
92    4. Parameters
93
94         4.1. keepalive_mechanism (integer)
95         4.2. keepalive_timeout (integer)
96         4.3. keepalive_processes (integer)
97         4.4. keepalive_interval (integer)
98         4.5. ping_application_data (string)
99         4.6. sub_protocols (integer)
100         4.7. cors_mode (integer)
101         4.8. verbose_list (int)
102
103    5. Functions
104
105         5.1. ws_handle_handshake()
106         5.2. ws_close([status, reason[, connection_id]])
107
108    6. RPC Commands
109
110         6.1. ws.dump
111         6.2. ws.close
112         6.3. ws.ping
113         6.4. ws.pong
114         6.5. ws.disable
115         6.6. ws.enable
116
117    7. Event routes
118
119         7.1. websocket:closed
120
121    8. Exported Pseudo Variables
122
123         8.1. $ws_conid
124
125 1. Overview
126
127    This module implements a WebSocket (RFC 6455) server and provides
128    connection establishment (handshaking), management (including
129    connection keep-alive), and framing for the SIP and MSRP WebSocket
130    sub-protocols (RFC 7118 and RFC 7977).
131
132    The module supports WebSockets (ws) and secure WebSockets (wss)
133    transports
134
135 2. How it works
136
137    2.1. Initiating a connection
138    2.2. SIP message routing
139    2.3. MSRP message routing
140
141 2.1. Initiating a connection
142
143    A WebSocket connection is initiated with an HTTP GET. The xhttp module
144    is used to handle this GET and call the Section 5.1, “
145    ws_handle_handshake() ” exported function.
146
147    event_route[xhttp:request] should perform some validation of the HTTP
148    headers before calling Section 5.1, “ ws_handle_handshake() ”. The
149    event_route can also be used to make sure the HTTP GET has the correct
150    URI, perform HTTP authentication on the WebSocket connection, and check
151    the Origin header (RFC 6454) to ensure a browser-based SIP UA or MSRP
152    client has been downloaded from the correct location.
153
154    Example 1.1. event_route[xhttp:request]
155 ...
156 loadmodule "sl.so"
157 loadmodule "xhttp.so"
158 loadmodule "msrp.so"  # Only required if using MSRP over WebSockets
159 loadmodule "websocket.so"
160 ...
161 event_route[xhttp:request] {
162         set_reply_close();
163         set_reply_no_connect();
164
165         if ($Rp != 80
166 #!ifdef WITH_TLS
167             && $Rp != 443
168 #!endif
169         ) {
170
171                 xlog("L_WARN", "HTTP request received on $Rp\n");
172                 xhttp_reply("403", "Forbidden", "", "");
173                 exit;
174         }
175
176         xlog("L_DBG", "HTTP Request Received\n");
177
178         if ($hdr(Upgrade)=~"websocket"
179                         && $hdr(Connection)=~"Upgrade"
180                         && $rm=~"GET") {
181
182                 # Validate Host - make sure the client is using the correct
183                 # alias for WebSockets
184                 if ($hdr(Host) == $null || !is_myself("sip:" + $hdr(Host))) {
185                         xlog("L_WARN", "Bad host $hdr(Host)\n");
186                         xhttp_reply("403", "Forbidden", "", "");
187                         exit;
188                 }
189
190                 # Optional... validate Origin - make sure the client is from an
191                 # authorised website.  For example,
192                 #
193                 # if ($hdr(Origin) != "http://communicator.MY_DOMAIN"
194                 #     && $hdr(Origin) != "https://communicator.MY_DOMAIN") {
195                 #       xlog("L_WARN", "Unauthorised client $hdr(Origin)\n");
196                 #       xhttp_reply("403", "Forbidden", "", "");
197                 #       exit;
198                 # }
199
200                 # Optional... perform HTTP authentication
201
202                 # ws_handle_handshake() exits (no further configuration file
203                 # processing of the request) when complete.
204                 if (ws_handle_handshake())
205                 {
206                         # Optional... cache some information about the
207                         # successful connection
208                         exit;
209                 }
210         }
211
212         xhttp_reply("404", "Not found", "", "");
213 }
214 ...
215
216 2.2. SIP message routing
217
218    SIP over WebSockets uses invalid URIs in routing headers (Contact:,
219    Record-Route:, and Via:) because a JavaScript stack running in a
220    browser has no way to determine the local address from which the
221    WebSocket connection is made. This means that the routing headers
222    cannot be used for request or response routing in the normal manner.
223
224    RFC 7118 - The WebSocket Protocol as a Transport for the Session
225    Initiation Protocol - states that SIP WebSocket Clients and the SIP
226    registrar should implement SIP Outbound (RFC 5626) and Path header
227    support (RFC 3327) to enable requests and responses to be correctly
228    routed. Kamailio has a module called "Outbound" for this functionality.
229
230    The nathelper module functions (nat_uac_test(), fix_nated_register(),
231    add_contact_alias(), and handle_ruri_alias()) and the Kamailio core
232    force_rport() can be used to ensure correct routing of SIP WebSocket
233    requests without using Outbound and Path.
234
235    Example 1.2. WebSocket SIP Routing
236 ...
237 loadmodule "sl.so"
238 loadmodule "tm.so"
239 ...
240 loadmodule "websocket.so"
241 ...
242 request_route {
243
244         # per request initial checks
245         route(REQINIT);
246
247         if (nat_uac_test(64)) {
248                 # Do NAT traversal stuff for requests from a WebSocket
249                 # connection - even if it is not behind a NAT!
250                 # This won't be needed in the future if Kamailio and the
251                 # WebSocket client support Outbound and Path.
252                 force_rport();
253                 if (is_method("REGISTER"))
254                         fix_nated_register();
255                 else {
256                         if (!add_contact_alias()) {
257                                 xlog("L_ERR", "Error aliasing contact <$ct>\n");
258                                 sl_send_reply("400", "Bad Request");
259                                 exit;
260                         }
261                 }
262         }
263
264         if (!is_method("REGISTER"))
265                 t_on_reply("WS_REPLY");
266 ...
267 # Handle requests within SIP dialogs
268 route[WITHINDLG] {
269         if (has_totag()) {
270                 # sequential request withing a dialog should
271                 # take the path determined by record-routing
272                 if (loose_route()) {
273                         if ($du == "") {
274                                 if (!handle_ruri_alias()) {
275                                         xlog("L_ERR", "Bad alias <$ru>\n");
276                                         sl_send_reply("400", "Bad Request");
277                                         exit;
278                                 }
279                         }
280                         route(RELAY);
281                 } else {
282                         if ( is_method("ACK") ) {
283 ...
284 onreply_route[WS_REPLY] {
285         if (nat_uac_test(64)) {
286                 # Do NAT traversal stuff for replies to a WebSocket connection
287                 # - even if it is not behind a NAT!
288                 # This won't be needed in the future if Kamailio and the
289                 # WebSocket client support Outbound and Path.
290                 add_contact_alias();
291         }
292 }
293 ...
294
295 2.3. MSRP message routing
296
297    MSRP over WebSocket clients create invalid local URIs for use in Path
298    headers (From-Path: and To-Path:) because a JavaScript stack running in
299    a browser has no way to determine the local address from which the
300    WebSocket connection is made. This is OK because MSRP over WebSocket
301    clients MUST use an MSRP relay and it is the MSRP relay's
302    responsibility to select the correct connection to the client based on
303    the MSRP URIs that it has created (and maintains a mapping for).
304
305 3. Dependencies
306
307    3.1. Kamailio Modules
308    3.2. External Libraries or Applications
309
310 3.1. Kamailio Modules
311
312    The following module must be loaded before this module:
313      * sl.
314      * tm.
315
316    The following modules are required to make proper use of this module:
317      * nathelper or outbound.
318      * xhttp.
319
320    The following module is required to use the secure WebSocket (wss)
321    scheme:
322      * tls.
323
324    The following module is required to support MSRP over WebSockets:
325      * msrp.
326
327 3.2. External Libraries or Applications
328
329    The following libraries must be installed before running Kamailio with
330    this module loaded:
331      * OpenSSL.
332      * GNU libunistring.
333
334 4. Parameters
335
336    4.1. keepalive_mechanism (integer)
337    4.2. keepalive_timeout (integer)
338    4.3. keepalive_processes (integer)
339    4.4. keepalive_interval (integer)
340    4.5. ping_application_data (string)
341    4.6. sub_protocols (integer)
342    4.7. cors_mode (integer)
343    4.8. verbose_list (int)
344
345 4.1. keepalive_mechanism (integer)
346
347    The keep-alive mechanism to use for WebSocket connections.
348
349 Note
350
351    If nathelper is only being used for WebSocket connections then
352    nathelper NAT pinging is not required. If nathelper is used for
353    WebSocket connections and TCP/TLS aliasing/NAT-traversal then WebSocket
354    keep-alives are not required.
355
356      * 0 - no WebSocket keep-alives
357      * 1 - Ping WebSocket keep-alives
358      * 2 - Pong WebSocket keep-alives
359
360    Default value is 1.
361
362    Example 1.3. Set keepalive_mechanism parameter
363 ...
364 modparam("websocket", "keepalive_mechanism", 0)
365 ...
366
367 4.2. keepalive_timeout (integer)
368
369    The time (in seconds) after which to send a keep-alive on idle
370    WebSocket connections.
371
372    Default value is 180.
373
374    Example 1.4. Set keepalive_timeout parameter
375 ...
376 modparam("websocket", "keepalive_timeout", 30)
377 ...
378
379 4.3. keepalive_processes (integer)
380
381    The number of processes to start to perform WebSocket connection
382    keep-alives.
383
384    Default value is 1.
385
386    Example 1.5. Set keepalive_processes parameter
387 ...
388 modparam("websocket", "keepalive_processes", 2)
389 ...
390
391 4.4. keepalive_interval (integer)
392
393    The number of seconds between each keep-alive process run
394
395    Default value is 1.
396
397    Example 1.6. Set keepalive_interval parameter
398 ...
399 modparam("websocket", "keepalive_interval", 2)
400 ...
401
402 4.5. ping_application_data (string)
403
404    The application data to use in keep-alive Ping and Pong frames.
405
406    Default value is Kamailio Server: header content
407
408    Example 1.7. Set ping_application_data parameter
409 ...
410 modparam("websocket", "ping_application_data", "WebSockets rock")
411 ...
412
413 4.6. sub_protocols (integer)
414
415    A bitmap that allows you to control the sub-protocols supported by the
416    WebSocket server.
417      * 1 - sip (RFC 7118)
418      * 2 - msrp (RFC 7977) - msrp.so must be loaded before websocket.so
419
420    Default value is 1 when msrp.so is not loaded 3 when msrp.so is loaded.
421
422    Example 1.8. Set sub_protocols parameter
423 ...
424 modparam("websocket", "sub_protocols", 2)
425 ...
426
427 4.7. cors_mode (integer)
428
429    This parameter lets you set the "Cross-origin resource sharing"
430    behaviour of the WebSocket server.
431      * 0 - Do not add an "Access-Control-Allow-Origin:" header to the
432        response accepting the WebSocket handshake.
433      * 1 - Add a "Access-Control-Allow-Origin: *" header to the response
434        accepting the WebSocket handshake.
435      * 2 - Add a "Access-Control-Allow-Origin:" header containing the same
436        body as the "Origin:" header from the request to the response
437        accepting the WebSocket handshake. If there is no "Origin:" header
438        in the request no header will be added to the response.
439
440    Default value is 0.
441
442    Example 1.9. Set cors_mode parameter
443 ...
444 modparam("websocket", "cors_mode", 2)
445 ...
446
447 4.8. verbose_list (int)
448
449    Allows to enable/disable the printing of debug messages when getting
450    the list of websocket connections. If enabled, it prints debug messages
451    every second for ping operations.
452
453    Default value is 0 (disabled).
454
455    Example 1.10. Set verbose_list parameter
456 ...
457 modparam("websocket", "verbose_list", 1)
458 ...
459
460 5. Functions
461
462    5.1. ws_handle_handshake()
463    5.2. ws_close([status, reason[, connection_id]])
464
465 5.1.  ws_handle_handshake()
466
467    This function checks an HTTP GET request for the required headers and
468    values, and (if successful) upgrades the connection from HTTP to
469    WebSocket.
470
471    This function can be used from ANY_ROUTE (but will only work in
472    event_route[xhttp:request]).
473
474 Note
475
476    This function returns 0, stopping all further processing of the
477    request, when there is a problem.
478
479    Example 1.11. ws_handle_handshake usage
480 ...
481 ws_handle_handshake();
482 ...
483
484 5.2.  ws_close([status, reason[, connection_id]])
485
486    This function closes a WebSocket connection.
487
488    The function returns -1 if there is an error and 1 if it succeeds.
489
490    The meaning of the parameters is as follows:
491      * status - an integer indicating the reason for closure.
492      * reason - a string describing the reason for closure.
493      * connection_id - the connection to close. If not specified the
494        connection the current message arrived on will be closed.
495
496 Note
497
498    status and reason values SHOULD correspond to the definitions in
499    section 7.4 of RFC 6455. If these parameters are not used the defaults
500    of "1000" and "Normal closure" will be used.
501
502    This function can be used from ANY_ROUTE.
503
504    Example 1.12. ws_close usage
505 ...
506 ws_close(4000, "Because I say so");
507 ...
508
509 6. RPC Commands
510
511    6.1. ws.dump
512    6.2. ws.close
513    6.3. ws.ping
514    6.4. ws.pong
515    6.5. ws.disable
516    6.6. ws.enable
517
518 6.1. ws.dump
519
520    Provides the details of the first 50 WebSocket connections.
521
522    Name: ws.dump
523
524    Parameters:
525      * order (optional) - “id_hash”, “used_desc”, or “used_asc”.
526
527 Note
528
529    If no parameter is provided id_hash order is used.
530
531    RPC Command Usage:
532 ...
533 kamcmd ws.dump used_asc
534 ...
535
536 6.2. ws.close
537
538    Starts the close handshake for the specified WebSocket connection.
539
540    Name: ws.close
541
542    Parameters:
543      * id - WebSocket connection ID.
544
545    RPC Command Usage:
546 ...
547 kamcmd ws.close: 1
548 ...
549
550 6.3. ws.ping
551
552    Sends a Ping frame on the specified WebSocket connection.
553
554    Name: ws.ping
555
556    Parameters:
557      * id - WebSocket connection ID.
558
559    RPC Command Usage:
560 ...
561 kamcmd ws.ping 1
562 ...
563
564 6.4. ws.pong
565
566    Sends a Pong frame on the specified WebSocket connection.
567
568    Name: ws.pong
569
570    Parameters:
571      * id - WebSocket connection ID.
572
573    RPC Command Usage:
574 ...
575 kamcmd ws.pong 1
576 ...
577
578 6.5. ws.disable
579
580    Disables WebSockets preventing new connections from being established.
581
582    Name: ws.disable
583
584    Parameters: none
585
586    RPC Command Usage:
587 ...
588 kamcmd ws.disable
589 ...
590
591 6.6. ws.enable
592
593    Enables WebSockets allowing new connections to be established.
594
595 Note
596
597    WebSockets are enabled at start-up.
598
599    Name: ws.enable
600
601    Parameters: none
602
603    RPC Command Format:
604 ...
605 kamcmd ws.enable
606 ...
607
608 7. Event routes
609
610    7.1. websocket:closed
611
612 7.1.  websocket:closed
613
614    When defined, the module calls event_route[websocket:closed] when a
615    connection closes. The connection may be identified using the the $si
616    and $sp pseudo-variables.
617
618    Example 1.13. event_route[websocket:closed] usage
619 ...
620 event_route[websocket:closed] {
621         xlog("L_INFO", "WebSocket connection from $si:$sp has closed\n");
622 }
623 ...
624
625 8. Exported Pseudo Variables
626
627    8.1. $ws_conid
628
629 8.1. $ws_conid
630
631    Connection id of closed websocket connection. Can only be used in
632    websocket:closed event route.
633
634    Example 1.14. $ws_conid usage
635 ...
636 event_route[websocket:closed] {
637         xlog("L_INFO", "WebSocket connection with id $ws_conid has closed\n");
638 }
639 ...