Hiawatha

From MineOS
Jump to: navigation, search

MineOS uses the Hiawatha webserver, which (in my opinion) is the most-simple-to-configure of all available mainstream webservers. I recommend reading about the Hiawatha webserver, as it provides invaluable information to using this server to its maximum potential.

Contents

Hiawatha Default Configuration

The default configuration of Hiawatha webserver has been slightly modified for use with MineOS. For example, Python (.py) and PHP (.php) are typically off in a new installation, but have been enabled in the sub-directory /admin for the web-ui. In addition, the CGI timeout value (TimeForCGI) has been increased to 300 seconds (to allow Minecraft mapping from within the web-ui to finish) and /admin has been password-protected.

The crypt-scrambled password is saved in: /etc/hiawatha/passwords

Hiawatha Configuration

Main configuration file

All the configuration of the server is done through a single configuration file: /etc/hiawatha/hiawatha.conf

Restarting the Hiawatha Service

Changes to the configuration file requires a webserver restart in order to take effect. To do so, execute the following:

Hosted ports

In the configuration files, the default ports used to host are :80 (for HTTP) and :443 (for HTTPS). Since many ISPs block this traffic to prevent home-hosting of websites, you may need to change this value to another, non-standard value (one that isn't blocked). In the configuration file, you'll see the following section:

# BINDING SETTINGS
# A binding is where a client can connect to.
#
Binding {
        Port = 80
#       Interface = 127.0.0.1
#       MaxKeepAlive = 30
#       TimeForRequest = 3,20
}
#
Binding {
        Port = 443
#       Interface = ::1
#       MaxKeepAlive = 30
#       TimeForRequest = 3,20
        SSLcertFile = /etc/hiawatha/serverkey.pem
}

80 and 443 can be changed to whichever values you choose, preferably over 1024. If you wish to prevent HTTPS hosting entirely, for example, you can comment out the whole bracket entry:

#Binding {
#        Port = 443
#       Interface = ::1
#       MaxKeepAlive = 30
#       TimeForRequest = 3,20
#       SSLcertFile = /etc/hiawatha/serverkey.pem
#}

Default indexpage

The index page (page that is recalled when no page is requested specifically) is index.php. This is the default filename most php-based applications, such as PhpMyAdmin or PhpBB. You can, however, set this to whatever else you like for use with other directories and start pages, like index.html.

# DEFAULT WEBSITE
# It is wise to use your IP address as the hostname of the default website
# and give it a blank webpage. By doing so, automated webscanners won't find
# your possible vulnerable website.
...
StartFile = index.php

By changing 'StartFile', anytime you type in your servers IP in to the browser or /admin, etc, Hiawatha will look for that file (e.g., index.php) in that directory. The behavior of a directory where the file is found or not found is explained in Directory Listing. Individual overwrites, like the one used for /admin are good practice.

Directory Listing

Directory listing means that if the StartFile listed above is not found, it will either display a 404 error (file not found) or display a list of ALL files in that directory. Directory listing poses no threat to the default install because the only files on the server are the password-protected web-ui interface html files. However, if you start using forums and PhpMyAdmin, you may consider turning directory listing off, so that visitors of your site's IP address can't glean any information from your directory listings, such as PhpBB versions (to look for known exploits).

# DEFAULT WEBSITE
# It is wise to use your IP address as the hostname of the default website
# and give it a blank webpage. By doing so, automated webscanners won't find
# your possible vulnerable website.
...
ShowIndex = yes

Enabling CGI

CGI means Common-Gateway-Interface and is the means for all shell scripts, python scripts and PHP scripts to be executed FROM the browser. CGI is disabled globally by default, as indicated by /etc/hiawatha/hiawatha.conf.

ExecuteCGI = no

However, due to the modular nature of the configuration file, it was enabled for /admin and all its subdirectories. This is similar to 'virtual hosts' on Apache/Lighttpd and allows you to have tremendous permissions precision.

Globally enabling CGI

For example, if you edit the the root-level ExecuteCGI attribute, you can globally (all subdirs of /var/www/hiawatha) enable CGI.

ExecuteCGI = no

changed to

ExecuteCGI = yes

Individually enabling CGI

Instead of globally enabling CGI, you can do so on a per-directory basis. This is how the /admin directory is secured by default:

# DIRECTORY SETTINGS
# You can specify some settings per directory.
#
Directory {
        Path = /var/www/hiawatha/admin
        ExecuteCGI = yes
        TimeForCGI = 300
        AccessList = pwd all
        PasswordFile = basic:/etc/hiawatha/passwords
        StartFile = index.html
}

Any attributes here override the root-level attributes. For example, if the root-level is set as StartFile = index.php, it would break the /admin default StartFile. But by adding StartFile = index.html, the entire server can use a one index file and /admin can use the original one.

Password protecting Hiawatha

The instructions for password protecting the web-ui are split into three sections, basic authentication approach, digest auth for any distro of Linux and digest auth for FreeBSD. Note, it is not required to use these steps in order to secure Hiawatha; you can do so with knowledge gained from the manpages which is my primary source of information for this. Using wigwam, you can generate the username/realm/password pair required for basic/digest authentication. These steps are just simply my prescribed method of updating the hiawatha.conf and passwords file without the use of vi and particularly copy/paste, which may not be available to admins using a keyboard at the main console.

Basic Auth approach
will@mineos-ubuntu:~$ wigwam -b will
Enter password:
will:$1$5.gL4dem$6Wltcb7QmzXQ3m65i.c07.

Copy the username/password produced after the password prompt into your existing /etc/hiawatha/passwords file.

For ALL MineOS Variants except FreeBSD

Update the hiawatha.conf config file to expect digest-type authentication.

# GENERAL SETTINGS
#
#Note, the LoginMessage below MUST match the realm name below, also indicated as 'realmname'
LoginMessage = realmname
 
# DIRECTORY SETTINGS
# You can specify some settings per directory.
#
Directory {
...
        PasswordFile = digest:/etc/hiawatha/.passwords
...
}

This step runs the wigwam binary which prompts the user for the password for the username specified by the -d parameter. Repeat the above step as many times as you wish, for addtional web-ui users.

These next steps remove all non-username/password lines produced above and remove the undesired '^M' characters from the end of each line. Finally, the .pwtemp file is deleted and Hiawatha restarted.

Notes about these steps: username should be replaced by your desired username. realmname is the "realm name" and may also be changed but must match the value in the LoginMessage = line.

For FreeBSD only

Update the hiawatha.conf config file to expect digest-type authentication.

# GENERAL SETTINGS
#
#Note, the LoginMessage below MUST match the realm name below, also indicated as 'realmname'
LoginMessage = realmname
 
# DIRECTORY SETTINGS
# You can specify some settings per directory.
#
Directory {
...
        PasswordFile = digest:/usr/local/etc/hiawatha/.passwords
...
}

This step runs the wigwam binary which prompts the user for the password for the username specified by the -d parameter. Repeat the above step as many times as you wish, for addtional web-ui users.

These next steps remove all non-username/password lines produced above and remove the undesired '^M' characters from the end of each line. Finally, the .pwtemp file is deleted and Hiawatha restarted.