The light-footed Hiawatha web server

Frugal Delivery


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

Listing 1

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 =
  WebsiteRoot = /var/www/
  StartFile = index.php
  AccessLogfile = /var/www/
  ErrorLogfile = /var/www/
  TimeForCGI = 5
  UseFastCGI = PHP7
  TLScertFile = /etc/ssl/example-net.pem

Buy this article as PDF

Express-Checkout as PDF
Price $2.95
(incl. VAT)

Buy ADMIN Magazine

Get it on Google Play

US / Canada

Get it on Google Play

UK / Australia

Related content

comments powered by Disqus
Subscribe to our ADMIN Newsletters
Subscribe to our Linux Newsletters
Find Linux and Open Source Jobs

Support Our Work

ADMIN content is made possible with support from readers like you. Please consider contributing when you've found an article to be beneficial.

Learn More”>


		<div class=