DragonFly On-Line Manual Pages

humdinger(8) DragonFly System Manager's Manual humdinger(8)

NAME
Humdinger - Minimal HTTPS/1.1 Server

SYNOPSIS
humdinger [see the libserver manual for options]

DESCRIPTION
Humdinger is a minimal, secure, multithreaded web server based on
libserver. Humdinger is designed to be the frontend of a local SCGI web
application. Humdinger DOES NOT accept unencrypted connections.

HUMDINGER SUPPORTS:
* IPv4 and IPv6 clients.

* TLS encrypted connections ONLY, with:

* TLS >= 1.0

* Session resumption.

* OCSP stapling.

* Perfect forward secrecy.

* HEAD, GET, and POST request methods.

* HTTP/1.1 persistent connections.

* Forwarding to localhost SCGI servers.

* Forwarding to localhost WebSocket servers.

HUMDINGER DOES NOT SUPPORT:
* Name-based virtual hosting.

* Plain CGI.

* Access authentication.

* Content negotiation beyond "Accept-Encoding", "If-Modified-Since",
"If-Unmodified-Since", and The only content encoding supported is
gzip.

* Etags

* Directory listings.

* The ~user notation in URLS.

* Logging of any kind (beyond syslogging errors). Application servers
are responsible for logging.

START AND STOP HUMDINGER
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_enable="YES"
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
following commands.

/usr/local/etc/rc.d/humdinger start
/usr/local/etc/rc.d/humdinger stop
/usr/local/etc/rc.d/humdinger restart
/usr/local/etc/rc.d/humdinger status

If you do not want humdinger started on system start, set

humdinger_enable="NO"

and use the following commands.

/usr/local/etc/rc.d/humdinger forcestart
/usr/local/etc/rc.d/humdinger forcestop
/usr/local/etc/rc.d/humdinger forcerestart
/usr/local/etc/rc.d/humdinger forcestatus

SECURITY HEADERS
Humdinger adds the following 3 headers to every response it generates.
These can only be altered by modifying the source code and recompiling.

Strict-Transport-Security: max-age=31536000
X-XSS-Protection: 1; mode=block
X-Frame-Options: SAMEORIGIN

CONFIGURATION
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 memory.

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, in order:

1. 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.

2. The absolute path to the file containing the server's TLS KEY.

3. The TLS key password. This line can be blank if there is no
password.

4. The absolute path to the file containing the TLS certificate chain.

5. 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 WebSocket server.

* 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 newline character.

* 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 all browsers.

6. 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.

CONTENT_TYPE
CONTENT_LENGTH
REQUEST_METHOD
SCRIPT_NAME
QUERY_STRING
HTTP_COOKIE
HTTP_REFERRER
HTTP_ORIGIN
REMOTE_ADDR

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 response.

* If the server drops the connection, the client will receive a 500
Internal Error response.

* 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 responses.

* 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 server's 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
css text/css
js application/x-javascript

png image/png
jpg image/jpeg
gif image/gif
ico image/vnd.microsoft.icon
svg image/svg+xml

ttf font/opentype
appcache text/cache-manifest
txt text/plain; charset=utf-8

When waiting for clients to send requests, humdinger drops connections
after 10 seconds of inactivity.

AUTHORS
James Bailie <jimmy@mammothcheese.ca>
http://www.mammothcheese.ca

June 2, 2015