Helios qmail manual

Helios qmail is an advanced, top integrated and feature rich distribution of qmail based on qmail-sql project. It has been created because stock qmail is quite useless these days - this project collects many popular patches, tools and extensions and links them using easy-to-adapt scripts and APIs. Helios qmail can be treated as an MTA which combines security, stability and reliability of qmail with flexibility, modern functionality and ease of use.

As of 0.9.0 release, Helios qmail supports:

If you are wondering why script language has been chosen to extend qmail, the answer is simple - to ease adaption of the system and to make it flexible. PHP has been chosen for such function because it is one of the most advanced and top-level script languages and to make Helios qmail easy to integrate with web applications.

Helios qmail has been designed also to make it`s extending easy. Want an example? Here is a short PHP code (a spp module) which implements checking for maximal number of recipients:

#!/usr/local/bin/php
<!php

if( $_ENV['SMTPRCPTCOUNT'] >= $_ENV['MAXRECIPIENTS'] ) {
    echo("550 sorry, too many recipients (#5.7.1)\r\n");
    exit(1);
}
exit(0);

?>

You do not know PHP? No problem, here is a bash implementation:

#!/bin/bash

if [ $SMTPRCPTCOUNT -ge $MAXRECIPIENTS ]; then
  echo "550 sorry, too many recipients (#5.7.1)"
  exit 1
fi

exit 0

Such module can be written also in any other language. Helios qmail supports extending many of it`s elements in such (easy) way.

Helios qmail is intended to be used by users who have already successfuly installed qmail and have been using it for some time. In other words, it is not recommended for qmail beginners, because of one reason - they probably will not benefit of most of it`s features. If you are a beginner, try stock qmail first and read some more documentation about it, like Life with qmail.

If you are an advanced user you will gain from it`s flexibility and many integrated features. Probably the most important advantage of Helios qmail is that it is database driven - it causes speed improvement and easier managment of users and domains.

If you are a power user, almost a "qmail hacker", you will probably love it`s extensibility - API, spp plugins, advanced content scanning, etc... It`s just made for buliding big mail systems, integrating it with other applications and making any adaptions.

You will not find installation instructions here - you can find them in document called “Helios qmail installation guide”, which is bundled with Helios qmail package and available for download in several formats from http://helios-qmail.sourceforge.net/#DOCS.

The main configuration file is located in /var/qmail/control/qmailconfig (it is a symbolic link to sqlserver file for compatibility with qmail-sql). It is divided into three parts: "System configuration", "Database configuration" and "Advanced options".

Helios qmail has an advanced content scanner (a qmail-qfilter filter) which scans mail message before it is accepted for delivery. It delays SMTP session, but queue scanner has many advantages - eg. it allows you to deny mail without bouncing it (for example if it is a virus message). Helios qmail once has delivery time scanners, but it was a waste of system resources to eg. scan mail to x recipients x times.

Helios qmail has support for most of modern spam prevention techniques - eg. RBL, SPF, content scanning, tarpitting. This section describes how to enable and use some of them. Also the next section (regarding spp plugins) and the previous section (regarding content scanning) contain some information about Helios qmail features that can be used to prevent spam.

qmail-spp (see http://qmail-spp.sourceforge.net/ for more iformation) is a small patch for qmail which allows you to enhance it`s functionality using external modules (written independently, in any programming language) without necessity of recompiling it or even restarting. Helios qmail comes with it and lets you for easy enabling and disabling several spp plugins by editing /var/qmail/control/smtpplugins file. Here is a list of modules bundled with Helios qmail with short description. If you want to write your own module, see section called "spp plugins" in chapter 4.

There are also more things that can be configured. Here is a short list of /var/qmail/control/ files that can be used to change these settings. For more information consult documentation of qmail.

Helios qmail comes with simple scripts for adding and deleting domains, users and aliases. They are located in /var/qmail/helios/ directory and called helios-(add|del)(domain|user|alias).php, eg. helios-adddomain.php, helios-deluser.php, helios-delalias.php and so on. Their usage is very intuitive, so they will not be described extensively here - simply execute such script with --help option to print short information on using it.

There is only one important thing - when you are adding a domain (using helios-adddomain.php script) be sure that you will not create a loop postmaster alias - such situation can be caused by adding your main domain (usually this from /var/qmail/control/me file) without -p option. This will cause that a postmaster@YOUR-MAIN-DOMAIN alias pointing to host postmaster, which is set to postmaster@YOUR-MAIN-DOMAIN by default, will be created, which will lead to mail loops.

You can change user password using /var/qmail/helios/helios-passwd.php script. Execute it with --help option for usage information. For example type /var/qmail/helios/helios-passwd.php login domain foo to set login@domain`s password to "foo". You can also type only /var/qmail/helios/helios-passwd.php login domain to read user`s password from the keyboard.

To set user`s .qmail file use /var/qmail/helios/helios-setdotqmail.php script. Simply pass it`s contents on standard input (eg. using redirection of echo command output) and give login, domain and optional extension as script arguments. For example type echo "./Maildir/" | /var/qmail/helios/helios-passwd.php johny domain.org ext to set johny-ext@domain.org`s .qmail to "./Maildir/".

If you want to delete user`s .qmail file use /var/qmail/helios/helios-deldotqmail.php script.

One of the most unique features of Helios qmail is it`s support for prevention of e-mail addresses spoofing. It is similar to SPF, but it deal only with local domains, which allows for more precise controlling of rights to specified local e-mail address. It is basing on SMTP authorization and allows you to specify which SMTP user is allowed to mail from given e-mail address. Antispoof in conjunction with SPF creates a complete system for stopping envelope sender forgeries.

Helios qmail comes with antispoof disabled by default, because it is important to know how to use it before enabling it. You can turn it on by editing /var/qmail/control/smtpplugins file (see section 5 in previous chapter for details).

You can edit each user`s list of permitted addresses by using /var/qmail/helios/helios-antispoofadmin.php script (execute it with --help option for usage information). You can also edit following virtual wildcard users for matching a wider group of users:

Such list should contain e-mail addresses (one per line) which user can use as envelope sender address. But there are also some useful strings which you can use as login and/or domain name. Below are the lists of such special strings.

List of strings which can be used as e-mail address:

List of strings which can be used as login:

List of strings which can be used as domain name:

You can also use exclamation mark as first character to negate matching, eg. "! [:any:]@[:my domains:]" allows mailing from any foreign address.

Helios qmail comes with following antispoof settings by default:

If the user is not allowed to mail from given e-mail address (but he tries to do this), and he is not authorized, he gets "530 authentication required (#4.7.1)" error, but if he has already authorized, he gets "550 permission denied (#5.7.0)" error. All such tries are logged.

Helios qmail supports notifying about new mails through Jabber protocol. This allows you to send notifications to your mobile phone, other instant messaging communicators, etc. using Jabber transports, so it can be really useful (for example when you are waiting for an important e-mail).

New mail notification works as follows: when new mail arrives, it is passed to /var/qmail/helios/helios-notify.php script (see default .qmail file in /var/qmail/control/defaultdelivery). Then, it reads the message and creates a notify message containing some information about mail, like sender, subject and beginning of text of the message. Next, it logs on a Jabber server using user`s JID and password (there is no system-wide account for sending Jabber notifications) and sends notify message to the given Jabber address (called "send-to").

To set up a new mail notification for specified user (or a group of users - wildcard string "[:all:]" can be used as login and/or domain name) use /var/qmail/helios/helios-notifyadmin.php script (execute it with --help option for usage information).

There are two scripts for getting information about users in your Helios qmail system. It`s usage is trivial, so they will not be described much here. For more information, execute them with --help option.

If you want to use Helios qmail API you should be an experienced PHP programmer. There is no extensive documentation of it, because it is no problem for such person to look at the source code and just use it. However, such documentation may be written some day, but now there are only few notes about it.

First of all, main Helios qmail API consist of four libraries: low-level - QmailSql.php and QmailSqlUser.php and high-level - QmailHelios.php and QmailHeliosUser.php. It can also be divided in another way: system-oriented - QmailSql.php and QmailHelios.php and user-oriented - QmailSqlUser.php and QmailHeliosUser.php. All libraries are located in /var/qmail/helios/lib directory.

If you will have problems with using the API look at the /var/qmail/helios/helios-*.php scripts and user-oriented classes - they are all like a one big example.

Please take a look at qmail-spp documentation for more information.