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

modules/websocket/README

@@ -0,0 +1,462 @@
+WebSocket Module
+
+Peter Dunkley
+
+   Crocodile RCS Ltd
+
+   Copyright © 2012 Crocodile RCS Ltd
+     __________________________________________________________________
+
+   Table of Contents
+
+   1. Admin Guide
+
+        1. Overview
+        2. How it works
+
+              2.1. Initiating a connection
+              2.2. SIP message routing
+
+        3. Dependencies
+
+              3.1. Kamailio Modules
+              3.2. External Libraries or Applications
+
+        4. Parameters
+
+              4.1. keepalive_mechanism (integer)
+              4.2. keepalive_timeout (integer)
+              4.3. keepalive_processes (integer)
+              4.4. keepalive_interval (integer)
+              4.5. ping_application_data (string)
+
+        5. Functions
+
+              5.1. ws_handle_handshake()
+
+        6. MI Commands
+
+              6.1. ws.dump
+              6.2. ws.close
+              6.3. ws.ping
+              6.4. ws.pong
+              6.5. ws.disable
+              6.6. ws.enable
+
+   List of Examples
+
+   1.1. event_route[xhttp:request]
+   1.2. WebSocket SIP Routing
+   1.3. Set keepalive_mechanism parameter
+   1.4. Set keepalive_timeout parameter
+   1.5. Set keepalive_processes parameter
+   1.6. Set keepalive_interval parameter
+   1.7. Set ping_application_data parameter
+   1.8. ws_handle_handshake usage
+
+Chapter 1. Admin Guide
+
+   Table of Contents
+
+   1. Overview
+   2. How it works
+
+        2.1. Initiating a connection
+        2.2. SIP message routing
+
+   3. Dependencies
+
+        3.1. Kamailio Modules
+        3.2. External Libraries or Applications
+
+   4. Parameters
+
+        4.1. keepalive_mechanism (integer)
+        4.2. keepalive_timeout (integer)
+        4.3. keepalive_processes (integer)
+        4.4. keepalive_interval (integer)
+        4.5. ping_application_data (string)
+
+   5. Functions
+
+        5.1. ws_handle_handshake()
+
+   6. MI Commands
+
+        6.1. ws.dump
+        6.2. ws.close
+        6.3. ws.ping
+        6.4. ws.pong
+        6.5. ws.disable
+        6.6. ws.enable
+
+1. Overview
+
+   This module implements a WebSocket (RFC 6455) server and provides
+   connection establishment (handshaking), management (including
+   connection keep-alive), and framing for the SIP WebSocket sub-protocol
+   (ietf-draft-sipcore-sip-websocket).
+
+   The module supports WebSockets (ws) and secure WebSockets (wss)
+
+2. How it works
+
+   2.1. Initiating a connection
+   2.2. SIP message routing
+
+2.1. Initiating a connection
+
+   A WebSocket connection is initiated with an HTTP GET. The xhttp module
+   is used to handle this GET and call the Section 5.1, “
+   ws_handle_handshake() ” exported function.
+
+   event_route[xhttp:request] should perform some validation of the HTTP
+   headers before calling Section 5.1, “ ws_handle_handshake() ”. The
+   event_route can also be used to make sure the HTTP GET has the correct
+   URI, perform HTTP authentication on the WebSocket connection, and check
+   the Origin header (RFC 6454) to ensure a browser-based SIP UA has been
+   downloaded from the correct location.
+
+   Example 1.1. event_route[xhttp:request]
+...
+loadmodule "sl.so"
+loadmodule "xhttp.so"
+loadmodule "websocket.so"
+...
+event_route[xhttp:request] {
+        set_reply_close();
+        set_reply_no_connect();
+
+        if ($Rp != 80 && $Rp != 443) {
+                xlog("L_WARN", "HTTP request received on $Rp\n");
+                xhttp_reply("403", "Forbidden", "", "");
+                exit;
+        }
+
+        xlog("L_DBG", "HTTP Request Received\n");
+
+        if ($hdr(Upgrade)=~"websocket"
+                        && $hdr(Connection)=~"Upgrade"
+                        && $rm=~"GET") {
+                xlog("L_DBG", "WebSocket\n");
+                xlog("L_DBG", " Host: $hdr(Host)\n");
+                xlog("L_DBG", " Origin: $hdr(Origin)\n");
+
+                if ($hdr(Host) == $null || !is_myself($hdr(Host))) {
+                        xlog("L_WARN", "Bad host $hdr(Host)\n");
+                        xhttp_reply("403", "Forbidden", "", "");
+                        exit;
+                }
+
+                # Optional... validate Origin
+                # Optional... perform HTTP authentication
+
+                # ws_handle_handshake() exits (no further configuration file
+                # processing of the request) when complete.
+                ws_handle_handshake();
+        }
+
+        xhttp_reply("404", "Not found", "", "");
+}
+...
+
+2.2. SIP message routing
+
+   SIP over WebSockets uses invalid URIs in routing headers (Contact:,
+   Record-Route:, and Via:) because a JavaScript stack running in a
+   browser has no way to determine the local address from which the
+   WebSocket connection is made. This means that the routing headers
+   cannot be used for request or response routing in the normal manner.
+
+   ietf-draft-sipcore-sip-websocket states that SIP WebSocket Clients and
+   the SIP registrar should implement Outbound (RFC 5626) and Path (RFC
+   3327) to enable requests and responses to be correctly routed. However,
+   Kamailio does not currently support Outbound and it may not be possible
+   to guarantee all SIP WebSocket clients will support Outbound and Path.
+
+   The nathelper module functions (nat_uac_test(), fix_nated_register(),
+   add_contact_alias(), and handle_ruri_alias()) and the Kamailio core
+   force_rport() can be used to ensure correct routing of SIP WebSocket
+   requests without using Outbound and Path.
+
+   Example 1.2. WebSocket SIP Routing
+...
+loadmodule "sl.so"
+loadmodule "tm.so"
+...
+loadmodule "websocket.so"
+...
+request_route {
+
+        # per request initial checks
+        route(REQINIT);
+
+        if (nat_uac_test(64)) {
+                # Do NAT traversal stuff for requests from a WebSocket
+                # connection - even if it is not behind a NAT!
+                # This won't be needed in the future if Kamailio and the
+                # WebSocket client support Outbound and Path.
+                force_rport();
+                if (is_method("REGISTER"))
+                        fix_nated_register();
+                else {
+                        if (!add_contact_alias()) {
+                                xlog("L_ERR", "Error aliasing contact <$ct>\n");
+                                sl_send_reply("400", "Bad Request");
+                                exit;
+                        }
+                }
+        }
+
+        if (!is_method("REGISTER"))
+                t_on_reply("WS_REPLY");
+...
+# Handle requests within SIP dialogs
+route[WITHINDLG] {
+        if (has_totag()) {
+                # sequential request withing a dialog should
+                # take the path determined by record-routing
+                if (loose_route()) {
+                        if ($du == "") {
+                                if (!handle_ruri_alias()) {
+                                        xlog("L_ERR", "Bad alias <$ru>\n");
+                                        sl_send_reply("400", "Bad Request");
+                                        exit;
+                                }
+                        }
+                        route(RELAY);
+                } else {
+                        if ( is_method("ACK") ) {
+...
+onreply_route[WS_REPLY] {
+        if (nat_uac_test(64)) {
+                # Do NAT traversal stuff for replies to a WebSocket connection
+                # - even if it is not behind a NAT!
+                # This won't be needed in the future if Kamailio and the
+                # WebSocket client support Outbound and Path.
+                add_contact_alias();
+        }
+}
+...
+
+3. Dependencies
+
+   3.1. Kamailio Modules
+   3.2. External Libraries or Applications
+
+3.1. Kamailio Modules
+
+   The following module must be loaded before this module:
+     * sl.
+
+   The following modules are required to make proper use of this module:
+     * nathelper.
+     * tm.
+     * xhttp.
+
+   The following module is required to use the secure WebSocket (wss)
+   scheme:
+     * tls.
+
+3.2. External Libraries or Applications
+
+   The following libraries must be installed before running Kamailio with
+   this module loaded:
+     * OpenSSL.
+     * GNU libunistring.
+
+4. Parameters
+
+   4.1. keepalive_mechanism (integer)
+   4.2. keepalive_timeout (integer)
+   4.3. keepalive_processes (integer)
+   4.4. keepalive_interval (integer)
+   4.5. ping_application_data (string)
+
+4.1. keepalive_mechanism (integer)
+
+   The keep-alive mechanism to use for WebSocket connections.
+
+Note
+
+   If nathelper is only being used for WebSocket connections then
+   nathelper NAT pinging is not required. If nathelper is used for
+   WebSocket connections and TCP/TLS aliasing/NAT-traversal then WebSocket
+   keep-alives are not required.
+
+     * 0 - no WebSocket keep-alives
+     * 1 - Ping WebSocket keep-alives
+     * 2 - Pong WebSocket keep-alives
+
+   Default value is 1.
+
+   Example 1.3. Set keepalive_mechanism parameter
+...
+modparam("websocket", "keepalive_mechanism", 0)
+...
+
+4.2. keepalive_timeout (integer)
+
+   The time (in seconds) after which to send a keep-alive on idle
+   WebSocket connections.
+
+   Default value is 180.
+
+   Example 1.4. Set keepalive_timeout parameter
+...
+modparam("websocket", "keepalive_timeout", 30)
+...
+
+4.3. keepalive_processes (integer)
+
+   The number of processes to start to perform WebSocket connection
+   keep-alives.
+
+   Default value is 1.
+
+   Example 1.5. Set keepalive_processes parameter
+...
+modparam("websocket", "keepalive_processes", 2)
+...
+
+4.4. keepalive_interval (integer)
+
+   The number of seconds between each keep-alice process run
+
+   Default value is 1.
+
+   Example 1.6. Set keepalive_interval parameter
+...
+modparam("websocket", "keepalive_interval", 2)
+...
+
+4.5. ping_application_data (string)
+
+   The application data to use in keep-alive Ping and Pong frames.
+
+   Default value is Kamailio Server: header content
+
+   Example 1.7. Set ping_application_data parameter
+...
+modparam("websocket", "ping_application_data", "WebSockets rock")
+...
+
+5. Functions
+
+   5.1. ws_handle_handshake()
+
+5.1.  ws_handle_handshake()
+
+   This function checks an HTTP GET request for the required headers and
+   values, and (if successful) upgrades the connection from HTTP to
+   WebSocket.
+
+   This function can be used from ANY_ROUTE (but will only work in
+   event_route[xhttp:request]).
+
+Note
+
+   This function always returns 0, stopping all further processing of the
+   request.
+
+   Example 1.8. ws_handle_handshake usage
+...
+ws_handle_handshake();
+...
+
+6. MI Commands
+
+   6.1. ws.dump
+   6.2. ws.close
+   6.3. ws.ping
+   6.4. ws.pong
+   6.5. ws.disable
+   6.6. ws.enable
+
+6.1. ws.dump
+
+   Provides the details of the first 50 WebSocket connections.
+
+   Name: ws.dump
+
+   Parameters:
+     * order (optional) - “id_hash”, “used_desc”, or “used_asc”.
+
+Note
+
+   If no parameter is provided id_hash order is used.
+
+   MI FIFO Command Format:
+                        :ws.dump:fifo_reply
+                        used_asc
+                        _empty_line_
+
+6.2. ws.close
+
+   Starts the close handshake for the specified WebSocket connection.
+
+   Name: ws.close
+
+   Parameters:
+     * id - WebSocket connection ID.
+
+   MI FIFO Command Format:
+                        :ws.close:fifo_reply
+                        1
+                        _empty_line_
+
+6.3. ws.ping
+
+   Sends a Ping frame on the specified WebSocket connection.
+
+   Name: ws.ping
+
+   Parameters:
+     * id - WebSocket connection ID.
+
+   MI FIFO Command Format:
+                        :ws.ping:fifo_reply
+                        1
+                        _empty_line_
+
+6.4. ws.pong
+
+   Sends a Pong frame on the specified WebSocket connection.
+
+   Name: ws.pong
+
+   Parameters:
+     * id - WebSocket connection ID.
+
+   MI FIFO Command Format:
+                        :ws.pong:fifo_reply
+                        1
+                        _empty_line_
+
+6.5. ws.disable
+
+   Disables WebSockets preventing new connections from being established.
+
+   Name: ws.disable
+
+   Parameters: none
+
+   MI FIFO Command Format:
+                        :ws.disable:fifo_reply
+                        _empty_line_
+
+6.6. ws.enable
+
+   Enables WebSockets allowing new connections to be established.
+
+Note
+
+   WebSockets are enabled at start-up.
+
+   Name: ws.enable
+
+   Parameters: none
+
+   MI FIFO Command Format:
+                        :ws.enable:fifo_reply
+                        _empty_line_

modules/websocket/doc/Makefile

@@ -0,0 +1,4 @@
+docs = websocket.xml
+
+docbook_dir = ../../../docbook
+include $(docbook_dir)/Makefile.module

modules/websocket/doc/websocket.xml

@@ -0,0 +1,33 @@
+<?xml version="1.0" encoding='ISO-8859-1'?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
+
+<!-- Include general documentation entities -->
+<!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
+%docentities;
+
+]>
+
+<book xmlns:xi="http://www.w3.org/2001/XInclude">
+	<bookinfo>
+	<title>WebSocket Module</title>
+	<productname class="trade">&kamailioname;</productname>
+	<authorgroup>
+		<author>
+		<firstname>Peter</firstname>
+		<surname>Dunkley</surname>
+		<affiliation><orgname>Crocodile RCS Ltd</orgname></affiliation>
+		<address>
+			<email>[email protected]</email>
+		</address>
+		</author>
+	</authorgroup>
+	<copyright>
+		<year>2012</year>
+		<holder>Crocodile RCS Ltd</holder>
+	</copyright>
+	</bookinfo>
+	<toc></toc>
+	
+	<xi:include href="websocket_admin.xml"/>
+</book>

modules/websocket/doc/websocket_admin.xml

@@ -0,0 +1,472 @@
+<?xml version="1.0" encoding='ISO-8859-1'?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
+
+<!-- Include general documentation entities -->
+<!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
+%docentities;
+
+]>
+<!-- Module User's Guide -->
+
+<chapter>
+	
+	<title>&adminguide;</title>
+	
+	<section>
+	<title>Overview</title>
+	<para>This module implements a WebSocket (RFC 6455) server and provides
+	connection establishment (handshaking), management (including
+	connection keep-alive), and framing for the SIP WebSocket sub-protocol
+	(ietf-draft-sipcore-sip-websocket).</para>
+	<para>The module supports WebSockets (ws) and secure WebSockets (wss)
+	</para>
+	</section>
+
+	<section>
+	<title>How it works</title>
+	<section>
+	<title>Initiating a connection</title>
+	<para>A WebSocket connection is initiated with an HTTP GET.  The
+	<emphasis>xhttp</emphasis> module is used to handle this GET and
+	call the <xref linkend="ws_handle_handshake"/> exported function.
+	</para>
+	<para><emphasis>event_route[xhttp:request]</emphasis> should perform
+	some validation of the HTTP headers before calling
+	<xref linkend="ws_handle_handshake"/>.  The event_route can also be
+	used to make sure the HTTP GET has the correct URI, perform HTTP
+	authentication on the WebSocket connection, and check the
+	<emphasis>Origin</emphasis> header (RFC 6454) to ensure a
+	browser-based SIP UA has been downloaded from the correct location.
+	</para>
+	<example>
+	<title>event_route[xhttp:request]</title>
+	<programlisting><![CDATA[
+...
+loadmodule "sl.so"
+loadmodule "xhttp.so"
+loadmodule "websocket.so"
+...
+event_route[xhttp:request] {
+        set_reply_close();
+        set_reply_no_connect();
+
+        if ($Rp != 80 && $Rp != 443) {
+                xlog("L_WARN", "HTTP request received on $Rp\n");
+                xhttp_reply("403", "Forbidden", "", "");
+                exit;
+        }
+
+        xlog("L_DBG", "HTTP Request Received\n");
+
+        if ($hdr(Upgrade)=~"websocket"
+                        && $hdr(Connection)=~"Upgrade"
+                        && $rm=~"GET") {
+                xlog("L_DBG", "WebSocket\n");
+                xlog("L_DBG", " Host: $hdr(Host)\n");
+                xlog("L_DBG", " Origin: $hdr(Origin)\n");
+
+                if ($hdr(Host) == $null || !is_myself($hdr(Host))) {
+                        xlog("L_WARN", "Bad host $hdr(Host)\n");
+                        xhttp_reply("403", "Forbidden", "", "");
+                        exit;
+                }
+
+                # Optional... validate Origin
+                # Optional... perform HTTP authentication
+
+                # ws_handle_handshake() exits (no further configuration file
+                # processing of the request) when complete.
+                ws_handle_handshake();
+        }
+
+        xhttp_reply("404", "Not found", "", "");
+}
+...
+]]></programlisting>
+	</example>
+	</section>
+
+	<section>
+	<title>SIP message routing</title>
+	<para> SIP over WebSockets uses invalid URIs in routing headers
+	(Contact:, Record-Route:, and Via:) because a JavaScript stack running
+	in a browser has no way to determine the local address from which the
+	WebSocket connection is made.  This means that the routing headers
+	cannot be used for request or response routing in the normal manner.
+	</para>
+	<para>ietf-draft-sipcore-sip-websocket states that SIP WebSocket
+	Clients and the SIP registrar should implement Outbound (RFC 5626) and
+	Path (RFC 3327) to enable requests and responses to be correctly
+	routed.  However, &kamailio; does not currently support Outbound and
+	it may not be possible to guarantee all SIP WebSocket clients will
+	support Outbound and Path.</para>
+	<para>The <emphasis>nathelper</emphasis> module functions
+	(<emphasis>nat_uac_test()</emphasis>, 
+	<emphasis>fix_nated_register()</emphasis>,
+	<emphasis>add_contact_alias()</emphasis>, and
+	<emphasis>handle_ruri_alias()</emphasis>) and the Kamailio core
+	<emphasis>force_rport()</emphasis> can be used to ensure correct
+	routing of SIP WebSocket requests without using Outbound and Path.
+	</para>
+	<example>
+	<title>WebSocket SIP Routing</title>
+	<programlisting><![CDATA[
+...
+loadmodule "sl.so"
+loadmodule "tm.so"
+...
+loadmodule "websocket.so"
+...
+request_route {
+
+        # per request initial checks
+        route(REQINIT);
+
+        if (nat_uac_test(64)) {
+                # Do NAT traversal stuff for requests from a WebSocket
+                # connection - even if it is not behind a NAT!
+                # This won't be needed in the future if Kamailio and the
+                # WebSocket client support Outbound and Path.
+                force_rport();
+                if (is_method("REGISTER"))
+                        fix_nated_register();
+                else {
+                        if (!add_contact_alias()) {
+                                xlog("L_ERR", "Error aliasing contact <$ct>\n");
+                                sl_send_reply("400", "Bad Request");
+                                exit;
+                        }
+                }
+        }
+
+        if (!is_method("REGISTER"))
+                t_on_reply("WS_REPLY");
+...
+# Handle requests within SIP dialogs
+route[WITHINDLG] {
+        if (has_totag()) {
+                # sequential request withing a dialog should
+                # take the path determined by record-routing
+                if (loose_route()) {
+                        if ($du == "") {
+                                if (!handle_ruri_alias()) {
+                                        xlog("L_ERR", "Bad alias <$ru>\n");
+                                        sl_send_reply("400", "Bad Request");
+                                        exit;
+                                }
+                        }
+                        route(RELAY);
+                } else {
+                        if ( is_method("ACK") ) {
+...
+onreply_route[WS_REPLY] {
+        if (nat_uac_test(64)) {
+                # Do NAT traversal stuff for replies to a WebSocket connection
+		# - even if it is not behind a NAT!
+                # This won't be needed in the future if Kamailio and the
+		# WebSocket client support Outbound and Path.
+                add_contact_alias();
+        }
+}
+...
+]]></programlisting>
+	</example>
+
+	</section>
+	</section>
+
+	<section>
+	<title>Dependencies</title>
+	<section>
+		<title>&kamailio; Modules</title>
+		<para>
+		The following module must be loaded before this module:
+		<itemizedlist>
+		<listitem>
+		<para><emphasis>sl</emphasis>.</para>
+		</listitem>
+		</itemizedlist>
+		</para>
+		<para>
+		The following modules are required to make proper use of this
+		module:
+		<itemizedlist>
+		<listitem>
+		<para><emphasis>nathelper</emphasis>.</para>
+		</listitem>
+		<listitem>
+		<para><emphasis>tm</emphasis>.</para>
+		</listitem>
+		<listitem>
+		<para><emphasis>xhttp</emphasis>.</para>
+		</listitem>
+		</itemizedlist>
+		</para>
+		<para>
+		The following module is required to use the secure WebSocket
+		(wss) scheme:
+		<itemizedlist>
+		<listitem>
+		<para><emphasis>tls</emphasis>.</para>
+		</listitem>
+		</itemizedlist>
+		</para>
+	</section>
+
+	<section>
+		<title>External Libraries or Applications</title>
+		<para>
+		The following libraries must be installed before running
+		&kamailio; with this module loaded:
+		<itemizedlist>
+		<listitem>
+		<para><emphasis>OpenSSL</emphasis>.</para>
+		</listitem>
+		<listitem>
+		<para><emphasis>GNU libunistring</emphasis>.</para>
+		</listitem>
+		</itemizedlist>
+		</para>
+	</section>
+	</section>
+
+
+	<section>
+	<title>Parameters</title>
+	<section>
+		<title><varname>keepalive_mechanism</varname> (integer)</title>
+		<para>The keep-alive mechanism to use for WebSocket connections.
+		</para>
+		<note><para>If <emphasis>nathelper</emphasis> is only being used
+		for WebSocket connections then <emphasis>nathelper NAT
+		pinging</emphasis> is not required.  If
+		<emphasis>nathelper</emphasis> is used for WebSocket connections
+		and TCP/TLS aliasing/NAT-traversal then WebSocket keep-alives
+		are not required.</para></note>
+		<para>
+		<itemizedlist>
+		<listitem><para> 0 - no WebSocket keep-alives</para></listitem>
+		<listitem><para> 1 - Ping WebSocket
+		keep-alives</para></listitem>
+		<listitem><para> 2 - Pong WebSocket
+		keep-alives</para></listitem>
+		</itemizedlist>
+		</para>
+		<para><emphasis>Default value is 1.</emphasis></para>
+		<example>
+		<title>Set <varname>keepalive_mechanism</varname>
+		parameter</title>
+		<programlisting format="linespecific">
+...
+modparam("websocket", "keepalive_mechanism", 0)
+...
+</programlisting>
+		</example>
+	</section>
+
+	<section>
+		<title><varname>keepalive_timeout</varname> (integer)</title>
+		<para>The time (in seconds) after which to send a keep-alive on
+		idle WebSocket connections.</para>
+		<para><emphasis>Default value is 180.</emphasis></para>
+		<example>
+		<title>Set <varname>keepalive_timeout</varname>
+		parameter</title>
+		<programlisting format="linespecific">
+...
+modparam("websocket", "keepalive_timeout", 30)
+...
+</programlisting>
+		</example>
+	</section>
+
+	<section>
+		<title><varname>keepalive_processes</varname> (integer)</title>
+		<para>The number of processes to start to perform WebSocket
+		connection keep-alives.</para>
+		<para><emphasis>Default value is 1.</emphasis></para>
+		<example>
+		<title>Set <varname>keepalive_processes</varname>
+		parameter</title>
+		<programlisting format="linespecific">
+...
+modparam("websocket", "keepalive_processes", 2)
+...
+</programlisting>
+		</example>
+	</section>
+
+	<section>
+		<title><varname>keepalive_interval</varname> (integer)</title>
+		<para>The number of seconds between each keep-alice process run
+		</para>
+		<para><emphasis>Default value is 1.</emphasis></para>
+		<example>
+		<title>Set <varname>keepalive_interval</varname>
+		parameter</title>
+		<programlisting format="linespecific">
+...
+modparam("websocket", "keepalive_interval", 2)
+...
+</programlisting>
+		</example>
+	</section>
+
+	<section>
+		<title><varname>ping_application_data</varname> (string)</title>
+		<para>The application data to use in keep-alive Ping and Pong
+		frames.</para>
+		<para><emphasis>Default value is &kamailio; Server: header
+		content</emphasis></para>
+		<example>
+		<title>Set <varname>ping_application_data</varname>
+		parameter</title>
+		<programlisting format="linespecific">
+...
+modparam("websocket", "ping_application_data", "WebSockets rock")
+...
+</programlisting>
+		</example>
+	</section>
+
+	</section>
+
+	<section>
+	<title>Functions</title>
+	<section id="ws_handle_handshake">
+		<title>
+		<function moreinfo="none">ws_handle_handshake()</function>
+		</title>
+		<para>This function checks an HTTP GET request for the required
+		headers and values, and (if successful) upgrades the connection
+		from HTTP to WebSocket.</para>
+		<para>This function can be used from ANY_ROUTE (but will only
+		work in <emphasis>event_route[xhttp:request]</emphasis>).</para>
+		<note><para>This function always returns 0, stopping all further
+		processing of the request.</para></note>
+		<example>
+		<title><function>ws_handle_handshake</function> usage</title>
+		<programlisting format="linespecific">
+...
+ws_handle_handshake();
+...
+</programlisting>
+		</example>
+	</section>
+	</section>
+
+	<section>
+	<title>MI Commands</title>
+	<section>
+		<title><function moreinfo="none">ws.dump</function></title>
+		<para>Provides the details of the first 50 WebSocket
+		connections.</para>
+		<para>Name: <emphasis>ws.dump</emphasis></para>
+		<para>Parameters:</para>
+		<itemizedlist>
+			<listitem>
+				<para>order (optional) -
+				<quote>id_hash</quote>,
+				<quote>used_desc</quote>, or
+				<quote>used_asc</quote>.</para>
+			</listitem>
+		</itemizedlist>
+		<note><para>If no parameter is provided id_hash order is
+		used.</para></note>
+		<para>MI FIFO Command Format:</para>
+		<programlisting  format="linespecific">
+			:ws.dump:fifo_reply
+			used_asc
+			_empty_line_
+</programlisting>
+	</section>
+
+	<section>
+		<title><function moreinfo="none">ws.close</function></title>
+		<para>Starts the close handshake for the specified
+		WebSocket connection.</para>
+		<para>Name: <emphasis>ws.close</emphasis></para>
+		<para>Parameters:</para>
+		<itemizedlist>
+			<listitem>
+				<para>id - WebSocket connection ID.</para>
+			</listitem>
+		</itemizedlist>
+		<para>MI FIFO Command Format:</para>
+		<programlisting  format="linespecific">
+			:ws.close:fifo_reply
+			1
+			_empty_line_
+</programlisting>
+	</section>
+
+	<section>
+		<title><function moreinfo="none">ws.ping</function></title>
+		<para>Sends a Ping frame on the specified WebSocket
+		connection.</para>
+		<para>Name: <emphasis>ws.ping</emphasis></para>
+		<para>Parameters:</para>
+		<itemizedlist>
+			<listitem>
+				<para>id - WebSocket connection ID.</para>
+			</listitem>
+		</itemizedlist>
+		<para>MI FIFO Command Format:</para>
+		<programlisting  format="linespecific">
+			:ws.ping:fifo_reply
+			1
+			_empty_line_
+</programlisting>
+	</section>
+
+	<section>
+		<title><function moreinfo="none">ws.pong</function></title>
+		<para>Sends a Pong frame on the specified WebSocket
+		connection.</para>
+		<para>Name: <emphasis>ws.pong</emphasis></para>
+		<para>Parameters:</para>
+		<itemizedlist>
+			<listitem>
+				<para>id - WebSocket connection ID.</para>
+			</listitem>
+		</itemizedlist>
+		<para>MI FIFO Command Format:</para>
+		<programlisting  format="linespecific">
+			:ws.pong:fifo_reply
+			1
+			_empty_line_
+</programlisting>
+	</section>
+
+	<section>
+		<title><function moreinfo="none">ws.disable</function></title>
+		<para>Disables WebSockets preventing new connections from
+		being established.</para>
+		<para>Name: <emphasis>ws.disable</emphasis></para>
+		<para>Parameters: <emphasis>none</emphasis></para>
+		<para>MI FIFO Command Format:</para>
+		<programlisting  format="linespecific">
+			:ws.disable:fifo_reply
+			_empty_line_
+</programlisting>
+	</section>
+
+	<section>
+		<title><function moreinfo="none">ws.enable</function></title>
+		<para>Enables WebSockets allowing new connections to be
+		established.</para>
+		<note><para>WebSockets are enabled at start-up.</para></note>
+		<para>Name: <emphasis>ws.enable</emphasis></para>
+		<para>Parameters: <emphasis>none</emphasis></para>
+		<para>MI FIFO Command Format:</para>
+		<programlisting  format="linespecific">
+			:ws.enable:fifo_reply
+			_empty_line_
+</programlisting>
+	</section>
+
+
+	</section>
+</chapter>
+

modules/websocket/example/kamailio.cfg

@@ -140,7 +140,7 @@ request_route {
 		# Do NAT traversal stuff for requests from a WebSocket
 		# connection - even if it is not behind a NAT!
 		# This won't be needed in the future if Kamailio and the
-		# WebSocket client support outbound.
+		# WebSocket client support Outbound and Path.
 		force_rport();
 		if (is_method("REGISTER"))
 			fix_nated_register();
@@ -301,10 +301,10 @@ route[AUTH] {
 #!ifdef WITH_WEBSOCKETS
 onreply_route[WS_REPLY] {
 	if (nat_uac_test(64)) {
-		# Do NAT traversal stuff for replies to a WebSocket connection - even
-		# if it is not behind a NAT!
-		# This won't be needed in the future if Kamailio and the WebSocket
-		# client support outbound.
+		# Do NAT traversal stuff for replies to a WebSocket connection
+		# - even if it is not behind a NAT!
+		# This won't be needed in the future if Kamailio and the
+		# WebSocket client support Outbound and Path.
 		add_contact_alias();
 	}
 }

pkg/kamailio/fedora/16/kamailio.spec

@@ -904,7 +904,7 @@ fi
 
 %files websocket
 %defattr(-,root,root)
-#%doc %{_docdir}/kamailio/modules/README.websocket
+%doc %{_docdir}/kamailio/modules/README.websocket
 %{_libdir}/kamailio/modules/websocket.so
 
 
@@ -956,6 +956,8 @@ fi
 
 
 %changelog
+* Tue Jul 3 2012 Peter Dunkley <[email protected]>
+  - Updates to websocket module
 * Sat Jun 30 2012 Peter Dunkley <[email protected]>
   - Updated rel to dev1
   - Removed %_sharedir and replaced with standard macro %_datadir