1websockify(1) USER COMMANDS websockify(1)
2
6 websockify - WebSockets to TCP socket bridge
7
10 websockify [options] [source_addr:]source_port target_addr:target_port
11 websockify [options] [source_addr:]source_port -- WRAP_COMMAND_LINE
12
15 -h, --help show this help message and exit
16 -v, --verbose verbose messages and per frame traffic
17 --record=FILE record sessions to FILE.[session_number]
18 -D, --daemon become a daemon (background process)
19 --run-once handle a single WebSocket connection and exit
20 --timeout=TIMEOUT after TIMEOUT seconds exit when not connected
21 --cert=CERT SSL certificate file
22 --key=KEY SSL key file (if separate from cert)
23 --ssl-only disallow non-encrypted connections
24 --web=DIR run webserver on same port. Serve files from DIR.
25 --wrap-mode=MODE action to take when the wrapped program exits or
26 daemonizes: exit (default), ignore, respawn
27
30 At the most basic level, websockify just translates WebSockets traffic
31 to normal TCP socket traffic. Websockify accepts the WebSockets hand‐
32 shake, parses it, and then begins forwarding traffic between the client
33 and the target in both directions.
34 websockify was formerly named wsproxy and was part of the noVNC
36 project.
37
40 WebSockets binary data
41 Websockify supports all versions of the WebSockets protocol (Hixie and
42 HyBI). The older Hixie versions of the protocol only support UTF-8 text
43 payloads. In order to transport binary data over UTF-8 an encoding must
44 used to encapsulate the data within UTF-8. Websockify uses base64 to
45 encode all traffic to and from the client. This does not affect the
46 data between websockify and the server.
47 Encrypted WebSocket connections (wss://)
50 To encrypt the traffic using the WebSocket 'wss://' URI scheme you need
51 to generate a certificate for websockify to load. By default websockify
52 loads a certificate file name self.pem but the --cert=CERT option can
53 override the file name. You can generate a self-signed certificate
54 using openssl. When asked for the common name, use the hostname of the
55 server where the proxy will be running:
56 openssl req -new -x509 -days 365 -nodes -out self.pem -keyout self.pem
58 Additional websockify features
61 These are not necessary for the basic operation.
62 * Daemonizing: When the -D option is specified, websockify runs in
65 the background as a daemon process.
66 * SSL (the wss:// WebSockets URI): This is detected automatically
69 by websockify by sniffing the first byte sent from the client
70 and then wrapping the socket if the data starts with '\x16' or
71 '\x80' (indicating SSL).
72 * Session recording: This feature that allows recording of the
75 traffic sent and received from the client to a file using the
76 --record option.
77 * Mini-webserver: websockify can detect and respond to normal web
80 requests on the same port as the WebSockets proxy. This func‐
81 tionality is activate with the --web DIR option where DIR is the
82 root of the web directory to serve.
83 * Wrap a program: see the "Wrap a Program" section below.
86 Wrap a Program
89 In addition to proxying from a source address to a target address
90 (which may be on a different system), websockify has the ability to
91 launch a program on the local system and proxy WebSockets traffic to a
92 normal TCP port owned/bound by the program.
93 The is accomplished with a small LD_PRELOAD library (rebind.so) which
95 intercepts bind() system calls by the program. The specified port is
96 moved to a new localhost/loopback free high port. websockify then prox‐
97 ies WebSockets traffic directed to the original port to the new (moved)
98 port of the program.
99 The program wrap mode is invoked by replacing the target with -- fol‐
101 lowed by the program command line to wrap.
102 `./websockify 2023 -- PROGRAM ARGS`
104 The --wrap-mode option can be used to indicate what action to take when
106 the wrapped program exits or daemonizes.
107 Here is an example of using websockify to wrap the vncserver command
109 (which backgrounds itself) for use with noVNC:
110 `./websockify 5901 --wrap-mode=ignore -- vncserver -geometry 1024x768
112 :1`
113 Here is an example of wrapping telnetd (from krb5-telnetd). telnetd
115 exits after the connection closes so the wrap mode is set to respawn
116 the command:
117 `sudo ./websockify 2023 --wrap-mode=respawn -- telnetd -debug 2023`
119 The wstelnet.html page demonstrates a simple WebSockets based telnet
121 client.
122 Use client certificate verification
125 This feature requires Python 2.7.9 or newer or Python 3.4 or newer.
126 The --verify-client option makes the server ask the client for a SSL
128 certificate. Presenting a valid (not expired and trusted by any sup‐
129 plied certificate authority) certificate is required for the client
130 connection. With -auth-plugin=ClientCertCNAuth, the client certificate
131 can be checked against a list of authorised certificate users. Non-
132 encrypted connection attempts always fail during authentication.
133 Here is an example of a vncsevrer with password-less, certificate-
135 driven authentication:
136 `./websockify 5901 --cert=fullchain.pem --key=privkey.pem --ssl-only
138 --verify-client --cafile=ca-certificates.crt --auth-plugin=ClientCertC‐
139 NAuth --auth-source='jane@example.com Joe User9824510' --web=noVNC/
140 --wrap-mode=ignore -- vncserver :1 -geometry 1024x768 -Security‐
141 Types=None`
142 The --auth-source option takes a white-space separated list of common
144 names. Depending on your clients certificates they can be verified
145 email addresses, user-names or any other string used for identifica‐
146 tion.
147 The --cafile option selects a file containing concatenated certificates
149 of authorities trusted for validating clients. If this option is omit‐
150 ted, system default list of CAs is used. Upon connect, the client
151 should supply the whole certificate chain. If your clients are known
152 not to send intermediate certificates, they can be appended to the ca-
153 file as well.
154 Note: Most browsers ask the user to select a certificate only while
156 connecting via HTTPS, not WebSockets. Connecting directly to the SSL
157 secured WebSocket may cause the browser to abort the connection. If you
158 want to connect via noVNC, the --web option should point to a copy of
159 noVNC, so it is loaded from the same host.
160
163 Joel Martin (github@martintribe.org)
164
167 https://github.com/novnc/websockify/
168 https://github.com/novnc/websockify/wiki/
170version 0.3 June 7, 2012 websockify(1)