Table of Contents

• Introduction
• Requirements
• Install Hiawatha
• Install Using Tuxhelp
• Install Using PPA
• Install PHP-FPM
• Configure PHP-FPM
• Database
• Install MySQL(Optional)
• Install MariaDB (Optional)
• Install Percona Server (Optional)
• Configure Hiawatha
• Test Hiawatha
• Summary

Introduction

Hiawatha is an advanced and secure webserver available for installation on a number of different operating systems. Built-in security features make Hiawatha stand out from the webserver crowd. Hiawatha can stop SQL injections, XSS, and CSRF attacks and exploit attempts. In this tutorial we will step through getting the Hiawatha webserver installed and configured. We will also review the steps necessary to install a database and PHP-FPM. At the end of this tutorial you will have a Ubuntu server configured to serve dynamic web content.

Requirements

• Familarity using the ProfitBricks Data Center Designer (DCD).
• A provisioned server running Ubuntu 14.04 LTS.
• Shell acces to the server using SSH or the DCD's remote console.

Install Hiawatha

Let's examine two different ways to get the Hiawatha webserver installed on Ubuntu 14.04. The first one will install it using the Tuxhelp software repository. The second method installs Hiawatha using a Personal Package Archive (PPA). While both methods are explained, you should choose one to follow and ignore the other. The second method takes slightly less time to complete.

Install Using the Tuxhelp Repo

First we need to import the public key (79AF54A9) of the Tuxhelp repository from the keyserver, keys.gnupg.net.

sudo apt-key adv --recv-keys --keyserver keys.gnupg.net 79AF54A9

Now that the key is imported, we need to update the sources.list file. The file /etc/apt/sources.list holds the list of repositories Ubuntu will query for available software packages. By default, some repositories are commented out in this list. We are going to add the Tuxhelp repository to the end of the list.

Open the sources.list file with the nano editor, or another of your choice:

sudo nano /etc/apt/sources.list

Add the Tuxhelp repository by adding this line to the bottom of the file:

deb http://mirror.tuxhelp.org/debian/ squeeze main

Now close nano by pressing CTRL X and answering Yes when prompted to save changes.

NOTE: An alternative method is to run:

sudo add-apt-repository 'deb http://mirror.tuxhelp.org/debian/ squeeze main'

This will add the line without requiring any manual edits to sources.list.

In the next stage, we will call apt-get update so Ubuntu can process the changes that were made to the our sources.list file.

sudo apt-get update

We call apt-get install to Hiawatha package for the installation:

sudo apt-get install hiawatha

Enter Y when prompted:

Do you want to continue? [Y/n] Y

and the installation should complete successfully.

We can quickly verify by running hiawatha -v:

/usr/sbin/hiawatha -v

Hiawatha v10.3, cache, IPv6, Monitor, reverse proxy, TLS v2.2.1, Tomahawk, URL toolkit, XSLT
Copyright (c) by Hugo Leisink <hugo@leisink.net>

Install Using a PPA

A second method is to use the Hiawatha PPA for installation and updates. We can add the PPA for Hiawatha with the following command:

sudo add-apt-repository ppa:octavhendra/hiawatha

which will produce output similar to this:

Advanced and secure webserver for Unix
Hiawatha is a webserver with the three key attributes:
secure, easy-to-use, and lightweight

Homepage: https://www.hiawatha-webserver.org/
 More info: https://launchpad.net/~octavhendra/+archive/ubuntu/hiawatha
Press [ENTER] to continue or ctrl-c to cancel adding it

gpg: keyring `/tmp/tmp78ny1u3s/secring.gpg' created
gpg: keyring `/tmp/tmp78ny1u3s/pubring.gpg' created
gpg: requesting key DAC7EB24 from hkp server keyserver.ubuntu.com
gpg: /tmp/tmp78ny1u3s/trustdb.gpg: trustdb created
gpg: key DAC7EB24: public key "Launchpad PPA for octavhendra" imported
gpg: Total number processed: 1
gpg:               imported: 1  (RSA: 1)
OK

When complete, you will have a new file on your server:

/etc/apt/sources.list.d/octavhendra-hiawatha-trusty.list

Now lets call apt-get update to process the change and get an updated list of available packages.

sudo apt-get update

And install Hiawatha:

sudo apt-get install hiawatha

Verify the installation:

hiawatha -v

Hiawatha v10.3, cache, IPv6, Monitor, reverse proxy, TLS v2.2.1, Tomahawk, URL toolkit, XSLT
Copyright (c) by Hugo Leisink <hugo@leisink.net>

Install PHP-FPM

PHP code is interpreted when the user makes a request. We can use a program called PHP FastCGI Process Manager (PHP-FPM) to run the PHP interpreter as a Unix process. Hiawatha then transfers all PHP requests to FPM using the FastCGI protocol. FPM maintains a pool of processes to handle these incoming requests according to its configuration (e.g., pm.start_servers settings).

To install PHP-FPM run:

sudo apt-get install php5-fpm php5-mysql php5-gd php5-curl

Answer Y when prompted:

Do you want to continue? [Y/n] Y

The final lines of output when the installation completes should be similar to this:

Processing triggers for php5-fpm (5.5.9+dfsg-1ubuntu4.19) ...
php5-fpm stop/waiting
php5-fpm start/running, process 22526

Configure PHP-FPM

Now open the php.ini file /etc/php5/fpm/php.ini with the nano editor to configure some basic settings:

nano /etc/php5/fpm/php.ini

Around line 768, find ;cgi.fix_pathinfo=1 and uncomment the line and set the value to 0, like this: cgi.fix_pathinfo=0. When set to the default value, 1, users can see your script's real path. Lets change it to 0 and avoid a potential security problem:

cgi.fix_pathinfo=0

Also we can make a change to hide our PHP version information in the http response headers. Around line 376, find and change expose_php = On to expose_php = Off:

expose_php = Off

Let us try to slightly improve our performance with the OPcache module. With the help of OPcache, as PHP code is interpreted, some of the resulting bytecode is cached. When subsequent requests for the same code are processed the cached bytecode is used. This is eliminates some of the time involved in interpreting PHP code. This results in a faster response to the website visitor.

The settings for OPcache are found around line 1827 in the [opcache] section.

To activate OPcache, uncomment and change the ;opcache.enable=0 line to opcache.enable=1:

opcache.enable=1

Let's also incease the amount of RAM that OPcache can use by changing the line ;opcache.memory_consumption=64 to opcache.memory_consumption=128:

opcache.memory_consumption=128

Now save the php.ini file and close the editor.

You can activate OPcache by running:

sudo php5enmod opcache

Now let's make a few configuration changes for FPM. As we mentioned earlier, Hiawatha transfers PHP requests to FPM using the FastCGI protocol. By default, this transfer occurs over one socket. If we want, we can use more than one socket. The /etc/php5/fpm/pool.d/www.conf file is a reference file containing the configuration for PHP-FPM. If we have more than one website, we can create multiple ".conf" files in the /etc/php5/fpm/pool.d/ directory. Each one will configure a FPM pool. This provides Hiawatha the option to use a different socket for each pool. For now we will configure one FPM pool (one socket) so we will only use the /etc/php5/fpm/pool.d/www.conf file. Hiawatha will transfer PHP requests over one socket as specifed in that file.

With nano or another editor, we open the /etc/php5/fpm/pool.d/www.conf file:

nano /etc/php5/fpm/pool.d/www.conf

We are making a change to permit the use of sockets, so uncomment this line. ;listen.mode = 0660:

listen.mode = 0660

After making the change, save and close the editor.

We restart PHP-FPM:

service php5-fpm restart

Database

Now it is time to install a database. A commonly-used database for storing content used by dynamic websites is MySQL or a MySQL-related database such as MariaDB or Percona. The filenames, paths, ports, sockets are similar between all three databases. The MySQL connectors available in PHP work with MariaDB and Percona. You can choose one of them to install. You may also skip this section entirely if you already have a database configured or do not wish to set one up at this time.

Install MySQL (Optional)

We need only enter the following command to install MySQL. During the installation we will set a MySQL password:

sudo apt-get install mysql-server

After installation completes we should run the mysql_secure_installation script. As prompted, set a password for the root user, disallow remote root logins, remove anonymous users, remove the test database, and reload the privilege tables:

mysql_secure_installation

Now that MySQL is running, go head and skip down to configure Hiawatha.

Install MariaDB (Optional)

If you prefer, you can install the MariaDB database instead of MySQL.

First we need install a repository using the following command:

sudo apt-get install python-software-properties

We can get this repository's public key from keyserver.ubuntu.com with this command:

sudo apt-key adv --recv-keys --keyserver keyserver.ubuntu.com 0xcbcb082a1bb943db

We need add MariaDB reposisitory into to our source.list with:

sudo add-apt-repository 'deb http://nwps.ws/pub/mariadb/repo/5.5/debian wheezy main'

Our sources.list can re-synchronize for MariaDB by running the following command:

sudo apt-get update

And we can install MariaDB now:

sudo apt-get install mariadb-server

After finishing the MariaDB installation, we should run the mysql_secure_installation script:

mysql_secure_installation

For our database filesystem security, we can install the tree program. With tree we can view the ownership and permissions of various MariaDB files on our filesystem. To install tree for MariaDB we can run the following command:

sudo apt-get install tree

And when you run this command, you will see permissons of the owner-user:owner-group under the this file paths:

sudo tree -puga /usr/lib*/mysql /lib*/mysql \
/etc/mysql* /etc/my.cnf* /var/lib*/mysql

Now that MariaDB is running, go head and skip down to configure Hiawatha.

Install Percona Server (Optional)

Percona Server is another database that is compatible with MySQL. A special feature of Percona is its available storage engine called Xtradb. Xtradb offers better performance than some other database engines. At the same time I would say it is more efficient in terms of resource consumption.

To import the public key, you can run the following command:

sudo apt-key adv --keyserver keys.gnupg.net --recv-keys 1C4CBDCDCD2EFD2A

First we need to learn which distribution version we are using by running the lsb_release -c command:

lsb_release -c

Our distribution is "trusty". We can open sources.list file /etc/apt/sources.list with nano or another editor:

nano /etc/apt/sources.list

And we need to add the following lines and making sure to replace YOURDIST with your distribution name (wheezy, trusty, etc.):

deb http://repo.percona.com/apt trusty main
deb-src http://repo.percona.com/apt trusty main

Save the changes in sources.list and close your editor.

Now we create a new preference file for APT with use the following commands:

touch /etc/apt/preferences.d/00percona.pref

We should "pin" the Percona packages to avoid conflicts with other repositories. This can be done by creating a 00percona.pref file and adding a few directives.

Open /etc/apt/preferences.d/00percona.pref with nano or another editor:

nano /etc/apt/preferences.d/00percona.pref

Add the following lines:

Package: *
Pin: release o=Percona Development Team
Pin-Priority: 1001

NOTE: Pin-Priority values higher than 1000 are mainly used in the downgrade or upgrade process. When the priority value is set as 1001, it forces apt to ONLY use packages from Percona's repository.

Now Save the changes in 00percona.pref and close your editor.

Re-synchronize the package index files from their sources:

sudo apt-get update

Install Percona server using the following command:

sudo apt-get install percona-server-server

Now that Percona is running, we can move ahead and configure Hiawatha.

Configure Hiawatha

Let's do some basic configuration of our Hiawatha webserver. The Hiawatha configuration file, hiawatha.conf, is stored in the directory /etc/hiawatha/.

Open /etc/hiawatha/hiawatha.conf using nano or another editor:

nano /etc/hiawatha/hiawatha.conf

We need to uncomment the line #CGIhandler = /usr/bin/php-cgi:php; in the # COMMON GATEWAY INTERFACE (CGI) SETTINGS section:

CGIhandler = /usr/bin/php-cgi:php

Uncomment the five "FastCGIserver" lines and replace /var/lib/hiawatha/php-fcgi.sock with /var/run/php5-fpm.sock; to use PHP-FPM. If we want, we can define the IP and socket number and we can do all of your settings in hiawatha.conf file. And it should look like this:

FastCGIserver {
    FastCGIid = PHP5
    ConnectTo = /var/run/php5-fpm.sock
    Extension = php
}

Modify the "VirtualHost" section to use a domain name you control. We'll use yourdomain.com in this tutorial. We will also enable the options to prevent cross-site scripting, request forgery, and SQL-injection attacks:

VirtualHost {
    Hostname = www.yourdomain.com
    WebsiteRoot = /var/www/yourdomain.com/public_html
    StartFile = index.php
    AccessLogfile = /var/www/yourdomain.com/logs/access.log
    ErrorLogfile = /var/www/yourdomain.com/logs/error.log
    TimeForCGI = 5
    UseFastCGI = PHP5
    PreventXSS = yes
    PreventCSRF = yes
    PreventSQLi = yes
}

After all the changes are made, we save hiawatha.conf file and close our editor.

Create directory for yourdomain.com using the following commands:

mkdir -p /var/www/yourdomain.com/public_html

mkdir /var/www/yourdomain.com/logs

Now restart the webserver with using the following command:

service hiawatha restart

Hiawatha should now be listening for incoming HTTP connections on port 80 of the IP address assigned to your webserver.

Test Hiawatha

If you'd like to test it out but don't have access to DNS for the value you set for yourdomain.com above, remember that you can change the hosts file on your local system. That allows your browser to resolve yourdomain.com to the IP address of your server.

Your web content, either static or dynamic can be placed in /var/www/yourdomain.com/public_html.

Here is a basic "Hello World" PHP script you can test with:

<?php
  echo "<html><head><title>Hiawatha PHP Test</title></head><body>";
  echo "<h1>Hello World!</h1><br>";
  echo "</body></html>";
?>

Save that content as index.php in the public_html directory and use your browser to check it out.

If things aren't working as expected, take a look at the system log files in /var/log/, the log files for Hiawatha in /var/log/hiawatha/, and the log files for your vhost in /var/www/yourdomain.com/logs/. One of those locations should contain log entries that will provide some clues as to what is going wrong.

Summary

Thanks for reading through and following this tutorial on configuring Hiawatha with support for PHP!

Please leave feedback in the comments section below. If you run into any issues with the tutorial we may be able to provide some direction or clarification to assist in resolution.