Environment variables

Remote connection details

REMOTE_ADDR

IP address of remote WebSocket client.

e.g. 123.123.123.123

REMOTE_HOST

Reverse DNS lookup of remote WebSocket client.

e.g. somemachine.someisp.com.

If the reverse DNS lookup fails, or if --reverselookup=false is specified on the websocketd command line, this value will fallback to the same value of REMOTE_ADDR.

REMOTE_PORT

Source port of remote WebSocket client.

e.g. 52696

(Non standard)

---

Request URL details

SERVER_PROTOCOL

The HTTP protocol, as specified by the client.

e.g. HTTP/1.1

SERVER_NAME

The hostname of the server, as specified in the URL.

e.g. www.example.com

SERVER_PORT

The listening port of the server.

e.g. 8080

REQUEST_METHOD

The HTTP request method. For WebSockets, this is always GET.

SCRIPT_NAME

TODO

PATH_INFO

TODO

PATH_TRANSLATED

TODO

QUERY_STRING

Everything after the ? in the URL.

e.g. If the requested WebSocket URL is ws://localhost:1234/somedir/myscript.py?name=me&msg=hello%20world, then the QUERY_STRING will be name=me&msg=hello%20world.

REQUEST_URI

The original request URI, as sent by the WebSocket client. This does not include scheme, host or port.

e.g. If the requested WebSocket URL is ws://localhost:1234/somedir/myscript.py?name=me&msg=hello%20world, then the REQUEST_URI will be /somedir/myscript.py?name=me&msg=hello%20world.

(Non standard)

Server details

SERVER_SOFTWARE

The string websocketd/x.x.x.x, where x.x.x.x is the version of the websocketd program.

GATEWAY_INTERFACE

The string websocketd-CGI/0.1.

Future enhancements may change the version.

---

Authentication

websocketd does not perform any authentication, so these variables are never set. Programs are responsible for their own authentication.

AUTH_TYPE

Never set by websocketd.

REMOTE_USER

Never set by websocketd.

REMOTE_IDENT

Never set by websocketd.

---

HTTP Body

WebSockets do not allow a HTTP body to be posted as part of the request, so these variables are never set.

CONTENT_TYPE

Never set by websocketd.

CONTENT_LENGTH

Never set by websocketd.

---

SSL

websocketd does not support HTTPS, so these variables are never set.

HTTPS

Never set by websocketd.

SSL_*

Never set by websocketd.

---

Diagnostics

UNIQUE_ID

A unique string associated with each WebSocket connection. It can be used for logging and debugging purposes.

The ID should be treated as an opaque payload. It must be treated as a string, not a number. The implementation may change over time.

The ID is only guaranteed to unique within a single websocketd process.

e.g. 45462465645449101442

(Non standard)

---

HTTP Headers

Per the CGI specification, all HTTP headers will be set as environment variables. The header name will be transformed:

• String converted to upper-case
• Dashes - converted to underscores _
• Prefixed with HTTP_

e.g. If the HTTP header Sec-WebSocket-Version: 13 is present, it shall be made available to the program using the environment variable HTTP_SEC_WEBSOCKET_VERSION=13.

Although all HTTP headers are made available, these are some commonly used WebSocket related headers:

HTTP_ORIGIN

The base URL of the origin site that initiated the WebSocket.

e.g. https://github.com/

HTTP_COOKIE

HTTP Cookies, if present.

e.g. session=1234; prefs=foo

HTTP_SEC_WEBSOCKET_PROTOCOL

If a custom protocol(s) are specified when calling the JavaScript WebSocket constructor in the browser, these shall be listed here.

e.g. myprotocol, anotherprotocol