Environment variables

A process websocketd spawns for a WebSocket connection receives the variables below, in CGI style. A process spawned for a --cgidir request receives a different set, built by Go's net/http/cgi; the differences are listed at the end of this page.

Client-controlled means the value comes from data the client sent and can therefore be anything the client chooses.

RFC 3875 variables

SERVER_NAME and SERVER_PORT come from the Host header, not from the address websocketd is bound to, which matches net/http/cgi and virtual-hosted web servers. This is settled behaviour, not a defect (issue #475).

Variables set to an empty string

Each of these is set, and set to an empty string. websocketd sets them explicitly so that a value cannot leak in from its own environment.

Non-standard variables

Not part of RFC 3875, and commonly provided by CGI-style servers.

Request headers

Every request header becomes one variable named HTTP_ followed by the header name uppercased with each - replaced by _. X-Forwarded-For becomes HTTP_X_FORWARDED_FOR. All of them are client-controlled.

Repeated headers of the same name are joined with , into one value. Carriage returns and newlines within a value are replaced with spaces, and the result is trimmed.

There is no HTTP_HOST. Go's HTTP server moves the Host header out of the header map before websocketd sees it; the host reaches the process as SERVER_NAME and SERVER_PORT instead.

One header is dropped: a request header named Proxy never becomes HTTP_PROXY. Many HTTP client libraries route outbound requests through whatever HTTP_PROXY names, so forwarding it would let a remote caller redirect a spawned program's own traffic. This is the httpoxy vulnerability, CVE-2016-5385. The comparison uses the header's canonical form, so proxy, Proxy, and PROXY are all dropped. Go's net/http/cgi drops it for the same reason.

Variables forwarded from websocketd's own environment

--passenv names, comma-separated, which of websocketd's own environment variables are copied into every spawned process. Nothing else from websocketd's environment reaches the process: on every platform except Windows, websocketd clears its own environment after reading this list.

Four facts govern the list:

• Passing --passenv replaces the default rather than adding to it. --passenv=API_KEY alone leaves the spawned process with no PATH.
• A named variable that is unset, or set to an empty string, in websocketd's environment is dropped rather than forwarded empty.
• HTTPS is skipped even when named, because that variable is websocketd's own --ssl signal.
• The list has no effect on the request-derived variables above. They are built per request and are always present.

Differences under --cgidir

A --cgidir request is handed to Go's net/http/cgi, which builds its own environment. SERVER_SOFTWARE is overridden to websocketd's value and the --passenv list is added, but the rest comes from Go.

GATEWAY_INTERFACE, SERVER_PROTOCOL, REQUEST_METHOD, QUERY_STRING, REQUEST_URI, SERVER_NAME, SERVER_PORT, REMOTE_ADDR, REMOTE_PORT, and the HTTP_<NAME> mapping carry the same meaning in both modes, and Proxy is dropped in both. These differ:

A --cgidir request path must name the script file exactly. There is no trailing path information to split off, which is why PATH_INFO is the whole path and SCRIPT_NAME is empty.

See also

• The CGI environment explains how a request becomes an environment, and where the trust boundaries fall.
• Passing data into your script compares the query string with --passenv.
• CLI flags covers --passenv, --reverselookup, --cgidir, and --dir.