HOWTO: Normal and TLS bindings

Bindings

A binding is where a client can connect to (a port on an interface). Almost every webserver uses port 80 for HTTP requests and port 443 for HTTPS (HTTP encrypted via TLS) requests. How to use TLS is explained in the next paragraph. First, we focus on creating a 'normal' binding. Bindings are created via a Binding section:

Binding {
    Port = 80
}

This makes Hiawatha listen on port 80 on every available interface. If you want Hiawatha to listen only on a specific interface, specify it via the Interface option. Use the IP address of the interface you want Hiawatha to listen on.

Binding {
    ...
    Interface = 192.168.0.1
}

To keep a client from having a connection open for too long, you can set a timeout via the TimeForRequest option. RequestTimeout takes one parameter, which is the timeout for every request, or two comma separated parameters, where the first parameter is the timeout for the first request and the second parameter is the timeout for all the following requests for that connection. The timeout is in seconds.

Another option to protect your webserver is the MaxRequestSize option. Via this option, you limit the size of a request sent by a client. A request uses memory. Sending very large requests can be used to DoS a server, which we want to prevent. The request size is specified in kilobytes.

Binding {
    ...
    TimeForRequest = 5, 30
    MaxRequestSize = 512
}

TLS bindings

The first thing you need before you can use TLS, is a X.509 SSL/TLS certificate. You can obtain one from a certificate authority (CA). There are many commercial CA's, but also several free CA's like Let's Encrypt. Hiawatha comes with a script to easily obtain a Let's Encrypt certificate. The script can be found in the source package in the directory extra/letsencrypt. Read the README.txt in that directory for further instructions.

When you have obtained a TLS certificate, move this file to your Hiawatha configuration directory (probably /etc/hiawatha or /usr/local/etc/hiawatha) and make sure it's only readable for root (file mode 400). Configure Hiawatha to use this certificate for HTTPS connections.

Binding {
    Port = 443
    TLScertFile = /etc/hiawatha/tls/certificate.pem
}

The order of the items in certificate.pem is important. The order is as follows:

If you want certain websites to be visited only via HTTPS, you can force users to use HTTPS.

VirtualHost {
    ...
    RequireTLS = yes
}

Server Name Indication

Hiawatha has support for SNI, which allows you to serve multiple TLS websites via one IP address. Just configure a TLS binding as explained above. For each virtual host that has its own SSL/TLS certificate, simply use the TLScertFile option inside the virtual host block. The certificate specified via Binding{} is used when a website is requested for which no virtual host has been defined.

Binding {
    Port = 443
    TLScertFile = certificate.pem
}

VirtualHost {
    Hostname = www.website.org
    ...
    TLScertFile = website.pem
}

Back