Pawel Foremski pjf@gna.org Christian Löschenkohl christian.loeschenkohl@linea7.com 2004 Pawel Foremski and Christian Löschenkohl This file is free documentation. A short installation guide of Helios qmail. 23-10-2004 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. MySQL 4 Currently only MySQL database is supported, but PostrgreSQL and ODBC support is planned to be added in the future. You will need at least version 4. Simply download it from http://www.mysql.com/downloads/mysql-4.0.html and consult it`s documentation for instructions on install proccess. PHP 5 You will need a CLI (Command Line Interface) of PHP v. 5 (it will not work with PHP 4 or CGI version) - enable it by passing --enable-cli to configure script. Other requirements are: pcntl support (--enable-pcntl) readline support (--with-readline) MySQL support (--with-mysql) You can get PHP from http://www.php.net/downloads.php. After installing PHP download and install Mail::Mime library from PEAR. Remember to add path to PEAR library dir to include_path in php.ini configuration file. Remember about MySQL support, it is very important. Helios checkpassword Get it from http://sourceforge.net/projects/helios-qmail/. ucspi-tcp Get it from http://cr.yp.to/ucspi-tcp/install.html. If compilation fails, use patch from http://www.qmail.org/moni.csi.hu/pub/glibc-2.3.1/. daemontools Get it from http://cr.yp.to/daemontools/install.html. If compilation fails, use patch from http://www.qmail.org/moni.csi.hu/pub/glibc-2.3.1/. Be sure to put it into your system`s start scripts. Consult Life with qmail on problems or use rc.daemontools script bundled with Helios qmail in extra/ dir. qmail-qfilter Get it from http://untroubled.org/qmail-qfilter/. Be sure to read it`s installation instructions. a C compiler and linker Preferably GCC and GNU ld, but any other should be right. Not needed only if you do not want to compile qmail and spp-spf module. GNU Bash 2.x Get it from http://www.gnu.org/software/bash/bash.html. standard UNIX tools For example chown, chmod, echo, sed, test, cat, patch, useradd (or pw) etc. You should already have them installed. BINC IMAP BINC IMAP enables IMAP service in Helios qmail. You can get it from http://www.bincimap.org/. stunnel 4 Enables SSL/TLS support in all Helios qmail services. Get it from http://www.stunnel.org/. libspf Enables support for SPF (Sender Policy Framework). Get it from http://www.libspf.org/. 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 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. 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. 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. 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 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. See the second chapter of the Helios qmail manual and modify your configuration files if needed. 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).