Hiawatha
Hiawatha is an open source web-server with security, ease of use and lightweight as its three key features. It supports among others CGI, FastCGI, IPv6, URL rewriting and reverse proxy and has security features no other webserver has, like blocking SQL injections, XSS, CSRF and exploit attempts.
Installation
Configuration
Directory structure
First, to give an overview of the overall directory structure of Hiawatha, the hierarchy suggested by the default configuration is shown below:
-
/etc/hiawatha
- program configuration files -
/etc/hiawatha/tls
- website TLS certificate -
/srv/http/hiawatha
- root for the default blank website associated with the IP address -
/var/log/hiawatha
- log files for the program and the default website -
/srv/http/my-domain/public
- website root -
/srv/http/my-domain/log
- website log files
Basic webserver setup
The Hiawatha configuration file is /etc/hiawatha/hiawatha.conf
. A configuration file example /etc/hiawatha/hiawatha.conf.sample
is provided.
In the sample setup, there is one default website attached to the IP address of the domain, it is a dummy one directing to a blank html page. This is the page IP scanning robots and hackers will face.
Then, the working webservers are defined with VirtualHost
sections. Hiawatha can serve more than one webserver and each of these sections describes a different one. For initial testing purpose, you can create one VirtualHost
for my-domain and save in its root directory /srv/http/my-domain/public
a dummy index.html
start file.
Next, enable and start hiawatha.service
and point your browser to http://my-domain
. At that stage you should be able to load the website start page.
For further details see the official HowTo.
/var/lib/hiawatha/gzipped
. Every time the file is requested again, the already gzipped version from disk will be used. It will notice (timestamp and size) file changes and the cache is cleared upon restart.CGI
Common Gateway Interface (CGI) scripts work with Hiawatha out of the box, the CGI module in the VirtualHost
section just needs to be enabled as follows:
/etc/hiawatha/hiawatha.conf
VirtualHost { ... ExecuteCGI = yes }
Interpreters for CGI scripts
To use CGI scripts in your website, you have to specify the common script file extension and the location of the binary that can run them. This is indicated in the main body of the configuration file:
CGIhandler = /usr/bin/php5-cgi:php,php5 CGIhandler = /usr/bin/perl:pl CGIhandler = /usr/bin/python:py
For further details see the official HowTo.
FastCGI
Hiawatha supports two different methods to send information to the FastCGI process: the webserver can communicate over either a Unix domain socket or a TCP connection. The communication type is defined in the FastCGIServer
section via the field ConnectTo
.
Enable SSL/TLS
First, you need a X.509 SSL/TLS certificate to use TLS. If you do not, you can use a #Self-signed certificate or use one for free from #Let's Encrypt certificate certificate authority.
The order of the items in the certificate file is important and has to be as follows:
serverkey.pem
-----BEGIN RSA PRIVATE KEY----- [webserver private key] -----END RSA PRIVATE KEY----- -----BEGIN CERTIFICATE----- [webserver certificate] -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- [optional intermediate CA certificate] -----END CERTIFICATE-----
For SSL/TLS support, the following Binding
section that configures Hiawatha to use a certificate for HTTPS connections should be added:
/etc/hiawatha/hiawatha.conf
Binding { Port = 443 TLScertFile = /etc/hiawatha/tls/serverkey.pem }
Once it is done, restart hiawatha.service
.
TLScertFile
setting inside the VirtualHost
block for each virtual host that has its own SSL/TLS certificate. The certificate specified in the Binding
section is used whenever no virtual host has been defined for a website.
/etc/hiawatha/hiawatha.conf
VirtualHost { Hostname = www.website.org ... TLScertFile = website.pem }
Reverse proxy
This example shows a reverse proxy configuration which forwards requests to https://service.domain.net
to another local running web service on port 8181
:
/etc/hiawatha/hiawatha.conf
VirtualHost { Hostname = service.domain.net WebsiteRoot = /var/www/domain StartFile = index.html ReverseProxy .* http://127.0.0.1:8181/ RequireTLS = yes }
Certificates
Self-signed certificate
If you only need a local self-signed certificate for webdevelopment eg. you can easily do this with:
# cd /etc/hiawatha/tls # openssl req -new -x509 -nodes -newkey rsa:4096 -keyout serverkey.pem -out serverkey.pem -days 1095 # chmod 400 serverkey.pem
Make sure you did add the SSL bundle path to your hiawatha.conf
as stated in #Enable SSL/TLS.
As this solution doesn't use an official certificate authority (CA), you will have to add a security exception the first time you connect to your website.
Let's Encrypt certificate
Install
Hiawatha provides a script to obtain a Let’s Encrypt certificate in an automated fashion. The script is available in /usr/share/hiawatha/letsencrypt.tar.gz
and should be unarchived into your preferred location, for example /root
.
Obtain a certificate
The detailed instructions are described in README.txt
and the tool configuration is defined in letsencrypt.conf
. In short, there are two steps to get a certificate:
- Register an account with the Let's Encrypt certificate authority (CA). An account key file will be created.
$ ./letsencrypt register
- Request a website certificate: www.my-domain.org must be the first hostname of a
VirtualHost
. Any following webserver's hostname will be used as an alternative hostname for the certificate. The filewww.my-domain.org.pem
will be created.# ./letsencrypt request www.my-domain.org
If the above succeeds, you can switch from the testing to the production CA by changing the LE_CA_HOSTNAME
setting in the configuration file and go through the two steps above again.
Auto renewal
The following command can be used to renew the certificate and restart the server upon renewal:
# /path/to/letsencrypt renew restart
The certificate will be renewed whenever it has less than 7 days to go and written to the directory indicated in HIAWATHA_CERT_DIR
. The number of days before renewal is controlled via the RENEWAL_EXPIRE_THRESHOLD
setting if necessary.
A daily schedule of this script is appropriate as no action will be taken anyway before the threshold is reached. This daily automation can be achieved using either cron or systemd/Timers:
Automation with cron
In order to automate the renewal of the certificate, schedule a cronjob for the root user to run the command line above.
Automation with a systemd timer
A systemd timer can be used for the repetition of the renewal process, both service and timer unit files need to be created:
/etc/systemd/system/letsencrypt-renew.service
[Unit] Description=Renew Let's Encrypt certificates [Service] Type=oneshot ExecStart=/path/to/letsencrypt renew restart
/etc/systemd/system/letsencrypt-renew.timer
[Unit] Description=Daily renewal of Let's Encrypt's certificates [Timer] OnCalendar=daily # Be kind to the Let's Encrypt servers: add a random delay of 0–3600 seconds RandomizedDelaySec=3600 Persistent=true [Install] WantedBy=timers.target
start and enable the newly created letsencrypt-renew.timer
.