GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  HUMDINGER (8)

NAME

Humdinger - Minimal HTTPS/1.1 Server

CONTENTS

Synopsis
Description
     Humdinger Supports:
     Humdinger Does Not Support:
     Start And Stop Humdinger
     Security Headers
     Percent Escapes
     Compound Requests With Pipelined Responses
     Configuration
Authors

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.
  • A custom pipelining extension described in droodpipe.8
  • Forwarding to localhost SCGI servers. A companion SCGI server library package is in devel/libdombey.
  • Forwarding to localhost WebSocket servers. A custom WebSocket server library is provided with drood and humdinger and is described in libdorrit.8.

    HUMDINGER DOES NOT SUPPORT:

  • HTTP/2.
  • 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

    PERCENT ESCAPES

In the resource names of requests, humdinger will convert every sequence of bytes consisting of a percent sign followed by two hexadecimal digits into the byte specified by the hexadecimal value. Whitespace, semicolons, and percent signs must all be percent-escaped to be recognized in resource names.

    COMPOUND REQUESTS WITH PIPELINED RESPONSES

Humdinger recognizes compound requests as described the droodpipe.8 manual and delivers pipelined responses to those requests.

    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


.An James Bailie Aq jimmy@mammothcheese.ca
http://www.mammothcheese.ca
Search for    or go to Top of page |  Section 8 |  Main Index


Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.