Helios qmail installation guide

Pawel Foremski

Christian Löschenkohl

This file is free documentation.



A short installation guide of Helios qmail.

1. Introduction
2. Requirements
2.1. Required software
2.2. Optional software
3. Installing Helios qmail
3.1. The configure script
3.2. The install script
3.3. Post-install steps after first installation
3.3.1. Database initialization
3.3.2. Providing a server certificate
3.3.3. tcpserver`s rules
3.3.4. Configuration
3.4. Starting Helios qmail

1. Introduction

Helios qmail has been tested on GNU/Linux and FreeBSD systems and it is possible that it will work also on any other UNIX like systems. If you have successfully installed Helios qmail on such platform, please mail me.

If you are unfamiliar with qmail, please read Life with qmail before trying to use Helios qmail.

2. Requirements

2.1. Required software

2.2. Optional software

3. Installing Helios qmail

If you are ready for the install proccess, run configure script found in Helios qmail package. It will check your system for dependencies and report any problems if they occurs, then it will generate install script, which can be run to finally install Helios qmail on your system.


Build system of Helios qmail supports VPATH-like builds

3.1. The configure script

configure has several options, but usually you should care only about following switches:

  • --with-me=DOMAIN

    Tells Helios qmail the FQDN (Fully Qualified Domain Name) of the machine your are installing it on.

  • --with-ips=IP1[,IP2,...] and --without-ips=IP1[,IP2,...]

    qmail tries to find IP addresses of machine it is running on automatically by getting them from all network interfaces. However, if you are behind firewall and/or have some port forwarding, you should let it know about it by passing your additional IP addresses in --with-ips option. If you want some IPs to not be treated as local, pass them in --without-ips option.

You can get list of all configure options by invoking it with --help option.

If configure will run without any errors, it will print out a summary and generate the install script in the current directory. If everything will be OK, go further.

3.2. The install script

install script is generated by configure and it builds the whole system and installs it on your hard drive. During run it creates tmp dir in the current directory, so if you do not want to clutter your source code, you can cd into other, more adequate directory.

It will extract, patch and compile qmail source (if you did not pass --without-qmail to configure), install all scripts, libraries and configuration files and build spp-spf module if you have chosen to enable it. If you have installed Helios qmail before, and already have some configuration files, it will add .new extension to all new configuration files to prevent your old configuration from overwriting. However, it will overwrite all old programs and scripts.

If you are ready, simply run install script.

3.3. Post-install steps after first installation

3.3.1. Database initialization

You will have to init your database with correct data structure before using Helios qmail. A correct schema is provided in setup/dbschema.sql, but you can also use setup/initdb-mysql script to do it for you.

Probably you will be interested in using these options of init script:

  • -p, --password=PASSWORD

    It will be the password of user with read access to the database which Helios qmail will use eg. for getting user information. Default: secret.

  • -P, --adminpassword=PASSWORD

    It will be the password of user with full access to the database which Helios qmail will use eg. for writing lastlogin IP and time. Default: secret.

  • -a, --mysqladminpassword=PASSWORD

    Password of MySQL administrator (default: root). If you do not have password, do not use this option.

You can get list of all initdb-mysql options by invoking it with --help option.

After initializing your database check it`s connectivity and modify connectionstring and popconnectionstring in /var/qmail/control/qmailconfig file.

3.3.2. Providing a server certificate

If you have chosen to enable SSL/TLS support (using stunnel), you will have to provide a server certificate and key in /var/qmail/control/servercert.pem file. Simply copy it there, if you have such, or use setup/servercert-gen script to generate self-signed certificate. You can see it`s options by invoking it with --help option.


servercert.pem should be should be owned by qmaild:nofiles and has permissions set to 640

3.3.3. tcpserver`s rules

You will have to compile /var/qmail/control/smtp-tcprules file into a .cdb file to provide rules for SMTP service served by tcpserver. Simply edit this file (only if you want) and type /var/qmail/helios/qmailctl.sh cdb.

3.3.4. Configuration

See the second chapter of the Helios qmail manual and modify your configuration files if needed.

3.4. Starting Helios qmail

If you are absolutely sure that your Helios qmail is properly installed and configured, you can link all directories from /var/qmail/supervise/ to /service/ eg. by typing ln -s /var/qmail/supervise/* /service/. If daemontools is running, Helios qmail should be started automatically in max. 5 seconds. Otherwise try to restart daemontools manually.

If something goes wrong, see system logs (usually /var/log/maillog) or output of ps aux | more (look for readproctitle service errors, where readproctitle service errors: ................................... is good and e.g. readproctitle service errors: Mutlilog cannot write is bad).