websockify

Common errors

• OSError: [Errno 10048] Only one usage of each socket address (protocol/network address/port) is normally permitted / Address already in use

  cause The specified `source_port` for websockify is already in use by another process, or websockify was not properly shut down from a previous run.
  fix Choose a different `source_port` that is not in use, or ensure that any previous websockify instances or other applications are fully terminated before restarting.

• Exception: rebind.so not found, perhaps you need to run make

  cause This error occurs when using `websockify` in `--wrap-mode` on Linux, indicating that the `rebind.so` library (used for intercepting `bind()` system calls) was not found or not built.
  fix Navigate to the `websockify` source directory and run `make` to compile `rebind.so`. If it's compiled but still not found, check if `rebind.so` is in the expected `websockify/websockify/` directory, and move it there if necessary.

• code 400, message Client must support 'binary' or 'base64' protocol

  cause An older WebSocket client is attempting to connect to `websockify` using a protocol that requires explicit 'binary' or 'base64' support, or expects Base64 encoding for binary data, which is no longer the default/supported method in recent `websockify` versions.
  fix Ensure the WebSocket client is updated to a modern version that explicitly supports the 'binary' WebSocket sub-protocol as per HyBi/IETF 6455. Avoid older clients that implicitly rely on Base64 encoding.

• WebSocket connection failed: Error during WebSocket handshake

  cause This generic error can be caused by various issues during the WebSocket handshake, including invalid or missing upgrade headers, authentication/authorization failures, TLS certificate problems (for `wss://`), or network intermediaries (firewalls, proxies) blocking the handshake.
  fix Check server logs for specific HTTP status codes (e.g., 400, 401, 403, 404) that might indicate the root cause. Verify the WebSocket URL (ws:// vs wss://), firewall rules, authentication credentials, and ensure correct SSL certificate configuration.

Warnings

• breaking Python 2.x and older Python 3 versions are no longer supported. Version 0.13.0 dropped support for Python < 3.6. Earlier versions (0.10.0) required Python 3.4+.
  Fix: Ensure you are running websockify with Python 3.6 or newer.
• breaking Older WebSocket protocol versions (Hixie) and Base64 encoding for binary data are no longer supported. Only the HyBi / IETF 6455 WebSocket protocol with binary message frames is supported.
  Fix: Update WebSocket clients to use the HyBi/IETF 6455 protocol and send binary data directly (not Base64 encoded). Clients must explicitly support 'binary' protocol.
• breaking The internal API for subclassing `WebsocketProxy` was significantly refactored. Custom implementations extending this class will likely break.
  Fix: Refer to the websockify GitHub release notes for v0.6.0 (specifically pull requests #110 and #111) for guidance on updating custom `WebsocketProxy` subclasses.
• gotcha When using `wss://` (encrypted WebSockets) with self-signed SSL certificates, browsers typically do not prompt to accept the certificate directly from a WebSocket connection. This can lead to connection failures.
  Fix: First, navigate to the HTTPS equivalent of your websockify server's address (e.g., `https://your_server_ip:8080`) in your browser and explicitly accept the self-signed certificate. Then, try the `wss://` connection. For production, use a trusted certificate authority.

Install

• pip install websockify Install with pip

Imports

• WebSocketProxy

  from websockify.websocketproxy import WebSocketProxy

  Primarily used for embedding websockify's core logic within another Python application. Most users interact via the command-line tool.

Quickstart

The primary way to use websockify is as a command-line tool to establish a WebSocket-to-TCP proxy. The first example proxies an existing TCP server (like VNC). The second example demonstrates 'wrap mode', where websockify launches and manages a target program, proxying to its standard I/O or a designated port.

# Start websockify to proxy WebSocket connections on port 8080 to a VNC server on localhost:5901
websockify 8080 localhost:5901

# Or, to wrap a program (e.g., a simple telnet server) and proxy to it
# This example assumes 'nc' (netcat) is available and listening on port 2000
# In one terminal: nc -lk 2000 # (for Linux)
# In another terminal, start websockify wrapping nc:
websockify 2023 --wrap-mode=respawn -- nc -lk 2000

# Access via a WebSocket client (e.g., noVNC) pointing to ws://your_server_ip:8080 or ws://your_server_ip:2023