Table of Contents
keepalive_mechanism (integer)
keepalive_timeout (integer)
keepalive_processes (integer)
keepalive_interval (integer)
ping_application_data (string)
sub_protocols (integer)
cors_mode (integer)
verbose_list (int)
event_callback (str)
timer_interval (integer)
rm_delay_interval (integer)
List of Examples
keepalive_mechanism
parameterkeepalive_timeout
parameterkeepalive_processes
parameterkeepalive_interval
parameterping_application_data
parametersub_protocols
parametercors_mode
parameterverbose_list
parameterevent_callback parametertimer_interval parameterrm_delay_intervalparameterws_handle_handshake usagews_close usageevent_route[websocket:closed] usageTable of Contents
keepalive_mechanism (integer)
keepalive_timeout (integer)
keepalive_processes (integer)
keepalive_interval (integer)
ping_application_data (string)
sub_protocols (integer)
cors_mode (integer)
verbose_list (int)
event_callback (str)
timer_interval (integer)
rm_delay_interval (integer)
This module implements a WebSocket (RFC 6455) server and provides connection establishment (handshaking), management (including connection keep-alive), and framing for the SIP and MSRP WebSocket sub-protocols (RFC 7118 and RFC 7977).
The module supports WebSockets (ws) and secure WebSockets (wss) transports
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 or MSRP client has been downloaded from the
correct location.
Example 1.1. event_route[xhttp:request]
...
tcp_accept_no_cl=yes
listen=tcp:127.0.0.17:80
listen=tls:127.0.0.17:443
...
loadmodule "sl.so"
loadmodule "xhttp.so"
loadmodule "msrp.so" # Only required if using MSRP over WebSockets
loadmodule "websocket.so"
...
event_route[xhttp:request] {
set_reply_close();
set_reply_no_connect();
if ($Rp != 80
#!ifdef WITH_TLS
&& $Rp != 443
#!endif
) {
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") {
# Validate Host - make sure the client is using the correct
# alias for WebSockets
if ($hdr(Host) == $null || !is_myself("sip:" + $hdr(Host))) {
xlog("L_WARN", "Bad host $hdr(Host)\n");
xhttp_reply("403", "Forbidden", "", "");
exit;
}
# Optional... validate Origin - make sure the client is from an
# authorised website. For example,
#
# if ($hdr(Origin) != "http://communicator.MY_DOMAIN"
# && $hdr(Origin) != "https://communicator.MY_DOMAIN") {
# xlog("L_WARN", "Unauthorised client $hdr(Origin)\n");
# xhttp_reply("403", "Forbidden", "", "");
# exit;
# }
# Optional... perform HTTP authentication
# ws_handle_handshake() exits (no further configuration file
# processing of the request) when complete in case of failure.
if (ws_handle_handshake())
{
# Optional... cache some information about the
# successful connection
exit;
}
}
xhttp_reply("404", "Not found", "", "");
}
...
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.
RFC 7118 - The WebSocket Protocol as a Transport for the Session Initiation Protocol - states that SIP WebSocket Clients and the SIP registrar should implement SIP Outbound (RFC 5626) and Path header support (RFC 3327) to enable requests and responses to be correctly routed. Kamailio has a module called "Outbound" for this functionality.
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 "xhttp.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 within 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();
}
}
...
MSRP over WebSocket clients create invalid local URIs for use in Path headers (From-Path: and To-Path:) because a JavaScript stack running in a browser has no way to determine the local address from which the WebSocket connection is made. This is OK because MSRP over WebSocket clients MUST use an MSRP relay and it is the MSRP relay's responsibility to select the correct connection to the client based on the MSRP URIs that it has created (and maintains a mapping for).
The following module must be loaded before this module:
sl.
tm.
The following modules are required to make proper use of this module:
nathelper or outbound.
xhttp.
The following module is required to use the secure WebSocket (wss) scheme:
tls.
The following module is required to support MSRP over WebSockets:
msrp.
The keep-alive mechanism to use for WebSocket connections.
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)
...
The time (in seconds) after which to send a keep-alive on idle WebSocket connections.
Default value is 180.
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)
...
The number of seconds between each keep-alive process run
Default value is 1.
Example 1.6. Set keepalive_interval
parameter
...
modparam("websocket", "keepalive_interval", 2)
...
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")
...
A bitmap that allows you to control the sub-protocols supported by the WebSocket server.
1 - sip (RFC 7118)
2 - msrp (RFC 7977) - the msrp module must be loaded before the websocket module
Default value is 1 when msrp module is not loaded, 3 when msrp module is loaded.
This parameter lets you set the "Cross-origin resource sharing" behaviour of the WebSocket server.
0 - Do not add an "Access-Control-Allow-Origin:" header to the response accepting the WebSocket handshake.
1 - Add an "Access-Control-Allow-Origin: *" header to the response accepting the WebSocket handshake.
2 - Add an "Access-Control-Allow-Origin:" header containing the same body as the "Origin:" header from the request to the response accepting the WebSocket handshake. If there is no "Origin:" header in the request no header will be added to the response.
Default value is 0.
Allows to enable/disable the printing of debug messages when getting the list of websocket connections. If enabled, it prints debug messages every second for ping operations.
Default value is 0 (disabled).
The name of the function in the kemi configuration file (embedded scripting language such as Lua, Python, ...) to be executed instead of event_route[...] blocks specific for websocket module.
The function has one string parameter, the value is the name of the event_route block, respectively "websocket:closed".
Default value is 'empty' (no function is executed for events).
Example 1.11. Set event_callback parameter
...
modparam("websocket", "event_callback", "ksr_websocket_event")
...
-- event callback function implemented in Lua
function ksr_websocket_event(evname)
KSR.info("===== websocket module triggered event: " .. evname .. "\n");
return 1;
end
...
The number of seconds between each timer process run
Default value is 1.
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]).
This function returns 0, stopping all further processing of the request, when there is a problem. Otherwise, it returns 1 (or positive number) in case of success.
This function closes a WebSocket connection.
The function returns -1 if there is an error and 1 if it succeeds.
The meaning of the parameters is as follows:
status - an integer indicating the reason for closure.
reason - a string describing the reason for closure.
connection_id - the connection to close. If not specified the connection the current message arrived on will be closed.
status and reason values SHOULD correspond to the definitions in section 7.4 of RFC 6455. If these parameters are not used the defaults of "1000" and "Normal closure" will be used.
This function can be used from ANY_ROUTE.
Provides the details of the first 50 WebSocket connections.
Name: ws.dump
Parameters:
order (optional) - “id_hash”, “used_desc”, or “used_asc”.
If no parameter is provided id_hash order is used.
RPC Command Usage:
... kamcmd ws.dump used_asc ...
Starts the close handshake for the specified WebSocket connection.
Name: ws.close
Parameters:
id - WebSocket connection ID.
RPC Command Usage:
... kamcmd ws.close: 1 ...
Sends a Ping frame on the specified WebSocket connection.
Name: ws.ping
Parameters:
id - WebSocket connection ID.
RPC Command Usage:
... kamcmd ws.ping 1 ...
Sends a Pong frame on the specified WebSocket connection.
Name: ws.pong
Parameters:
id - WebSocket connection ID.
RPC Command Usage:
... kamcmd ws.pong 1 ...
Disables WebSockets preventing new connections from being established.
Name: ws.disable
Parameters: none
RPC Command Usage:
... kamcmd ws.disable ...
When defined, the module calls event_route[websocket:closed] when a connection closes. The connection may be identified using the $si and $sp pseudo-variables.
Example 1.16. event_route[websocket:closed] usage
...
event_route[websocket:closed] {
xlog("L_INFO", "WebSocket connection from $si:$sp has closed\n");
}
...