Environment variables

Remote connection details

REMOTE_ADDR

IP address of remote WebSocket client.

Example:

REMOTE_ADDR=123.123.123.123

REMOTE_HOST

Reverse DNS lookup of remote WebSocket client.

Example:

REMOTE_HOST=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.

Example:

REMOTE_PORT=52696

(Non standard)

Request URL details

SERVER_PROTOCOL

The HTTP protocol, as specified by the client.

Example:

SERVER_PROTOCOL=HTTP/1.1

SERVER_NAME

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

Example:

SERVER_NAME=www.example.com

SERVER_PORT

The listening port of the server.

Example:

SERVER_PORT=8080

REQUEST_METHOD

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

Example:

REQUEST_METHOD=GET

SCRIPT_NAME

TODO

PATH_INFO

TODO

PATH_TRANSLATED

TODO

QUERY_STRING

Everything after the ? in the URL.

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

QUERY_STRING=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.

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

REQUEST_URI=/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.

Example:

SERVER_SOFTWARE=websocketd/1.0.0.0

GATEWAY_INTERFACE

The string websocketd-CGI/0.1.

Future enhancements may change the version.

Example:

GATEWAY_INTERFACE=websocketd-CGI/0.1

Authentication

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

AUTH_TYPE

Not set.

REMOTE_USER

Not set.

REMOTE_IDENT

Not set.

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

Nog set.

CONTENT_LENGTH

Not set.

SSL

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

HTTPS

Not set.

SSL_*

Not set.

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.

Example:

UNIQUE_ID=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.

Example:

HTTP_ORIGIN=https://github.com/

HTTP_COOKIE

HTTP Cookies, if present.

Example:

HTTP_COOKIE=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.

Example:

HTTP_SEC_WEBSOCKET_PROTOCOL=myprotocol, anotherprotocol