Hiawatha
Hiawatha is "an open source web-server with security, easy to use and lightweight as the three key features. It supports among others (Fast)CGI, IPv6, URL rewriting and reverse proxy and has security features no other webserver has, like blocking SQL injections, XSS, CSRF and exploit attempts."
Contents
Installation
Configuration
Basic Setup
The Hiawatha configuration file is: /etc/hiawatha/hiawatha.conf
. By default it should produce a 404 page.
The default configuration file suggests /srv/http/my-domain/public
as the document directory served. To test the installation, create a dummy file:
/srv/http/my-domain/public/index.html
Hello world!
Edit the VIRTUAL HOSTS section in the config file to fit your needs.
Then start/enable the hiawatha.service
and point your browser to my-domain
, where you should see the test page.
A very good example configuration file is available at /etc/hiawatha/hiawatha.conf.sample
.
For further details see the official HowTo.
CGI
Common Gateway Interface (CGI) scripts work with Hiawatha out of box, you just need to enable the CGI module.
/etc/hiawatha/hiawatha.conf
VirtualHost { ... ExecuteCGI = yes }
Make sure your chosen programming language interpreter is installed. (i.e. for python you would install python)
For further details see the official HowTo.
FastCGI
Install fcgi. Now you have Hiawatha with fcgi support.
PHP
Install php, php-cgi and php-fpm (see also PHP and LAMP).
Do not forget to enable and start php-fpm.service
.
Check that php-cgi is working php-cgi --version
PHP 7.0.2 (cgi-fcgi) (built: Jan 6 2016 11:51:03) Copyright (c) 1997-2015 The PHP Group Zend Engine v3.0.0, Copyright (c) 1998-2015 Zend Technologies
If you get a similar output then php is installed correctly.
Add one of this FastCGIserver
sections to your config file.
/etc/hiawatha/hiawatha.conf
### The following fast CGI daemon requires php-fpm using a UNIX socket and TCP port, respectively. # ACTIVATE a FastCGI server for php (using UNIX socket) FastCGIserver { FastCGIid = PHP7 ConnectTo = /run/php-fpm/php-fpm.sock Extension = php SessionTimeout = 30 }
/etc/hiawatha/hiawatha.conf
### The following fast CGI daemon requires php-fpm using a UNIX socket and TCP port, respectively. # ACTIVATE a FastCGI server for php (using IP-address and TCP port) FastCGIserver { FastCGIid = PHP5 ConnectTo = 127.0.0.1:9000 Extension = php SessionTimeout = 30 }
To use the FastCGIserver ad the following to your config file
/etc/hiawatha/hiawatha.conf
VirtualHost { ... UseFastCGI = PHP7 }
Then Reload the hiawatha.service
.
Ruby on Rails
For some details see the FastCGI section of the HowTo.
Python FastCGI
For some details see the FastCGI section of the HowTo.
SSL
For SSL/TLS support add the following Binding
to your con fig file. Then Reload the hiawatha.service
.
/etc/hiawatha/hiawatha.conf
Binding { Port = 443 TLScertFile = /etc/hiawatha/serverkey.pem }
The order of the items in serverkey.pem
is important. The order 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-----
Let's Encrypt
If you want to use Let's Encrypt with Hiawatha follow Let’s Encrypt (the manual way is recommended). Read Let's Encrypt Getting Started for detailed instructions. Afterwards, create a Hiawatha certificate bundle:
# cd /etc/letsencrypt/live/domain.tld/ # cat privkey.pem cert.pem chain.pem > /etc/hiawatha/certs/domain.tld/hiawatha.pem
and secure it:
# chmod 400 /etc/hiawatha/certs/domain.tld/hiawatha.pem
Change your Hiawatha TLScertFile paths accordingly in hiawatha.conf:
Binding { ... RequireTLS = yes TLScertFile = /etc/hiawatha/certs/domain.tld/hiawatha.pem ... } VirtualHost { ... RequireTLS = yes TLScertFile = /etc/hiawatha/certs/domain.tld/hiawatha.pem ... }
Then restart Hiawatha:
# systemctl restart hiawatha.service
For see this forum post.
For further details see the official HowTo.
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.
/etc/hiawatha/hiawatha.conf
VirtualHost { Hostname = www.website.org ... TLScertFile = website.pem }
Output Compression
Hiawatha has no support for on-the-fly GZip content encoding! But Hiawatha goes its own way with preziped contend.
For further details see the official FAQ.