A rc.d script is installed in /usr/local/etc/rc.d/. Add the following
lines to /etc/rc.conf to start humdinger on system boot. Replace the items in
brackets with values appropriate for your system. These are the minimal
set of options you should start with. The available options are described
in the libserver manual.
humdinger_flags="-p 443 -f <config-file> -r <server-root> -u <user> -g <group> -n <min-threads> -m <max-threads>"
Start, stop, or restart humdinger, or determine if it is running with the
If you do not want humdinger started on system start, set
and use the following commands.
Humdinger is built on top of libserver and accepts the command line options
that libserver accepts. Consult the libserver manual for details.
It is important that the -m option be set to control the maximum number of
threads that can be alive at any one time so that the server does not exhaust
All other configuration is accomplished with a configuation file. The -f command
line option must be set to the filename of the configuration file. The
file must contain 6 newline-terminated lines of text. The lines describe,
- The hostname the server will recognize in TLS Server Name Indication messages.
You must use this precise hostname in all the URLs your application generates.
Adding or removing subdomains will cause SNI to fail.
- The absolute path to the file containing the servers TLS KEY.
- The TLS key password. This line can be blank if there is no password.
- The absolute path to the file containing the TLS certificate chain.
- The absolute path of the WebSocket configuration file. This line may be
empty if no WebSocket service is available.
Each line of the WebSocket configuration file contains a virtual path, one
or more tab characters, and an absolute path to a UNIX-domain socket.
WebSocket handshakes that request entities whose names begin with the
virtual path are forwarded to the WebSocket server listening on the socket.
- Humdinger performs the WebSocket handshake and then connects to the
- Humdinger sends to the server the content of the Cookie header supplied
with the request, terminated with a newline only, and then proxies data
back and forth between the server and the client. If no Cookie was
supplied by the client, then the cookie line will consist only of the
- The WebSocket server is responsible for framing and unframing data.
- Humdinger ignores Sec-WebSocket-Protocol headers. Clients must NOT
specify a sub-protocol, or handshakes may not complete successfully with
- The absolute path of the SCGI server configuration file. This line may be
empty if there are no SCGI servers available.
Each line of the SCGI configuration file contains a virtual path, one or
more tab characters, and an absolute path to a UNIX-domain socket.
Requests for entities whose name begins with the virtual path are forwarded
to the WebSocket server listening on the socket.
The following environment variables are set for the SCGI server.
The server need only supply a Content-Type or a Location header. If
present, other headers are passed to the client unmodified.
- DO NOT send a Status header. Humdinger crafts its own Status headers.
- If the SCGI server supplies a Location header, then the client will receive
a 303 See Other response. Otherwise, the client will receive a 200 OK
- If the server drops the connection, the client will receive a 500 Internal
- Do not add a Date header to responses. Humdinger always adds a date header
to all responses.
- Always send a response body unless your response header contains a Location
header, or you will hang the connection. Report errors to the user in HTML
- When an SCGI server does not send a Content-Length header, and the client
request is an HTTP/1.1 request, humdinger automatically adds the
"Transfer-Encoding: chunked" header and chunks the response body.
- There is no limit imposed on the length of SCGI response headers. You
can set big cookies, but be advised that client request headers cannot
be longer than 8192 bytes. A limit must be set to thwart malicious clients
that try to exhaust the servers memory.
Requests that are not recognized as WebSocket handshakes or SCGI requests
are assumed to be requests for files that reside in the directory specified
by the -r option. The root resource must be named index.html.
Humdinger rejects cross-origin HTTP/1.1 requests for all static resources
except those whose filenames end with .html. THIS MEANS THAT THIRD PARTIES
CANNOT LINK TO YOUR STATIC RESOURCES BEYOND HTML FILES.
Application servers can set any Content-Type header needed, but for files,
only the following suffix-to-type mappings are recognized:
html text/html; charset=utf-8
txt text/plain; charset=utf-8
When waiting for clients to send requests, humdinger drops connections
after 10 seconds of inactivity.