The light-footed Hiawatha web server
Frugal Delivery
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.
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.
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 = 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 }
Buy this article as PDF
(incl. VAT)