Compiling

Hiawatha uses Cmake and doesn't have many parameters for the admin to specify when building. The recommendation is to build a Hiawatha package yourself instead of compiling the software on your production systems. To do so, first download the source code from the Hiawatha website. The compilation process then consists of the commands

mkdir build
cd build
cmake ..
sudo make install/strip

A quick look at the INSTALL file in the source code reveals which parameters Cmake basically supports for Hiawatha (Figure 2). Primarily, this means the paths on the filesystem you want Hiawatha to use, but you can also specify whether Tomahawk should be built, and support for TLS should be added, along with whether Hiawatha needs the extension to operate as a reverse proxy. Most parameters default to ON, which activates the respective function. However, you are free to change the values to your own liking – a feature you don't need in the first place doesn't have to bloat the Hiawatha binary unnecessarily.

Figure 2: Whereas other HTTP servers divide their configuration files into many individual parts, Hiawatha is content with a fairly small number of essential lines.

After completing the build, it's time for the configuration. The following example assumes that /etc is set as the CONFIG_DIR – that is, that Hiawatha expects its configuration file to be in /etc/hiawatha/hiawatha.conf. It also requires that /var/www/ be set as WEBROOT_DIR, where Hiawatha looks for the web content at build time (although the parameter can be changed later by configuration).

The Simplest Web Server

If you only want Hiawatha to listen on port 443 with an SSL certificate, your configuration file will be very simple.

Binding {
  Port = 443
  TLScertFile = /etc/ssl/www-certificate.pem
}

Unlike Apache, Hiawatha expects all components belonging to the SSL certificate to be in the same file. The referenced ssl-certificate.pem must therefore contain both the SSL certificate itself and the SSL key belonging to it, as well as any required secure sockets layer (SSL) certificate authority (CA) and SSL intermediate CA certificates. The order is important: First the file must contain the private key, then the certificate, and then additional CA or intermediate certificates. Once all of this is in place, the configuration is complete, and whatever is in WEBROOT_DIR can be retrieved by Hiawatha.

Admittedly, this basic configuration might not make most admins very happy – a few parameters are probably still needed for regular operation. For example, you will not usually want to run the web server with the root rights of the system administrator, but as a less privileged user account that you can specify with ServerId in the configuration file. SystemLogFile and GarbageLogFile let you define the logfiles that Hiawatha uses.

Virtual Hosts

One of the most used Apache features might be virtual hosts. The idea behind this is to have many web addresses point to one IP address. The web server then delivers the correct website according to the URL called. Hiawatha also offers this feature, and it is comparatively easy to set up.

In addition to the Binding statement used earlier, the section from Listing 1 is all you need to define a VirtualHost that can execute PHP files in Hiawatha for www.example.net . Most important is that the TLScertFile statement is shifted from the Binding to the VirtualHost statement to allow Hiawatha to use different SSL certificates for different virtual hosts.

CGIhandler = /usr/bin/perl:pl
CGIhandler = /usr/bin/php-cgi:php
CGIhandler = /usr/bin/python:py
CGIhandler = /usr/bin/ruby:rb
CGIhandler = /usr/bin/ssi-cgi:shtml
CGIextension = cgi
FastCGIserver {
  FastCGIid = PHP7
  ConnectTo = /run/php/php7.0-fpm.sock
  Extension = php
}
VirtualHost {
  Hostname = www.example.net
  WebsiteRoot = /var/www/example.net/public
  StartFile = index.php
  AccessLogfile = /var/www/example.net/log/access.log
  ErrorLogfile = /var/www/example.net/log/error.log
  TimeForCGI = 5
  UseFastCGI = PHP7
  TLScertFile = /etc/ssl/example-net.pem
}