Hiawatha - ArchWiki

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

## Installation

Install the hiawatha package.

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

Note: There are two kinds of FastCGI applications:

- The first one runs as a daemon and listens to a port for incoming connections from a webserver.
- The second one is started by the webserver and communicates with the webserver via pipes.

Hiawatha only supports the first kind!

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

This article or section needs expansion.

Reason: If you use it please fill this section! (Discuss in Talk:Hiawatha#)

For some details see the FastCGI section of the HowTo.

#### Python FastCGI

This article or section needs expansion.

Reason: If you use it please fill this section! (Discuss in Talk:Hiawatha#)

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.

## See also

- Hiawatha Support page

Category:

- Web server

Hidden category:

- Pages or sections flagged with Template:Expansion