Abstract
This document is a guide to install Quica and make it interoperate with Courier Mail Server.
Table of Contents
I recommend to take a quick view to this document to make an idea of the overall process. Knowledge of UNIX is assumed. I think that Quica works on any system that can meet the requirements pointed in chapter Requirements. Good luck!
Quica is a frontend to the Courier's virtual user system. That means that user accounts don't need to be UNIX accounts. Metadata is stored in a relational database and messages in the filesystem. The web interface use PHP interpreted language and the 'Set Up' scripts are written in python. The web interface runs some scripts as other user, that is the reason that sudo program is needed. You don't needed this information to make quica work, but I tell this to figure what happened in the case of something going wrong with the installation. In this document are described only the minimum settings to make Quica work with courier. Please go to courier-mta.org for more resources on courier-mta.
This chapter presents the software requirements of Quica. Each platform has a way to install a piece of software, so if your system is Linux, FreeBSD or FlavorX you should know how to install some of the requirements. I will describe how to install some software, but you that are more intelligent than this static piece of text can follow other ways and try RPM, dpkg, Ports, etc.
General Requirements
Courier MTA - courier-mta.org
Apache Web Server - httpd.apache.org
Python > 2.0 - python.org
Sudo - www.courtesan.com/sudo/
PHP with PEAR libraries - php.net, pear.php.net
GNU Make - www.gnu.org/software/make/make.html
Depending of wich database you choose the requirements to follow:
PostgreSQL
PostgreSQL 7 - postgresql.org
psycopg DB Python adapter - initd.org/software/initd/psycopg
PHP with PostgreSQL support
MySQL
MySQL 3, 4? - mysql.com
MySQL DB Python adapter - sourceforge.net/projects/mysql-python
PHP with MySQL support
Python should come with your UNIX system so the compilation can be avoided. Take care of one thing. The python executable may be named python or python2 depending of the version. You need Python 2.0 or greater. You can execute python -V to see the version number.
Quica need the PEAR's Database Abstraction Layer. If your PHP version is less than PHP 4.3 is probable that you don't have it. Refer to Getting the PEAR package manager to install the pakage manager. Then, you could add the DB library with it. See how I do it:
pear install DB
Table of Contents
Now, you must decide wich database of the supported ones to use. Read the section that matches your selection.
Keep in mind that these are examples, replace passwords, and think in the security of your database configuration. I am not a database expert.
Configure who and where can connect
These examples are for a database running in the same computer that courier and Quica. You should have a line like this in your /var/lib/pgsql/data/pg_hba.conf:
host quica quica 127.0.0.1 255.255.255.255 password
Syntax can vary with your PostgreSQL version. Finnaly, accept TCP/IP connections changing postgresql.conf usually in /var/lib/pgsql/data/ directory.
tcpip_socket = true
Reload the database daemon to take these changes.
Create a database to hold the data and a user to access it
I use these commands to do the work (as postgres superuser):
CREATE USER quica WITH PASSWORD 'ytumamatambien';
CREATE DATABASE quica;
Issue the commands in a PostgreSQL shell (psql) connected to the created database
In the /dbload/ of the package root directory is a file called PostgreSQL.sql that contains the commands to create the database layout. You need to input these commands to the database as the user you created in the previus step.
Courier package has a file with similar commands. Quica uses a superset of this file. In other words, Quica defined more fields in the database. Use the Quica file, not courier's.
The command line I use
psql -U quica -h localhost -W < ./dbload/PostgreSQL.sql
Here is a print of these commands, but the mentioned file can be more accurate:
CREATE TABLE accounts (
id varchar(128) NOT NULL PRIMARY KEY,
crypt varchar(128) DEFAULT '',
clear varchar(128) DEFAULT '',
name varchar(128) DEFAULT '',
uid int DEFAULT 65534,
gid int DEFAULT 65534,
home varchar(255) NOT NULL,
maildir varchar(128) DEFAULT '',
quota varchar(128) DEFAULT '',
account_type varchar(32) NOT NULL,
creation_operator varchar(64) NOT NULL,
lastmodify_operator varchar(64) NOT NULL,
creation_time timestamp DEFAULT now(),
modify_time timestamp DEFAULT now(),
notes varchar(1024) DEFAULT '',
serial_nr serial
);
CREATE TABLE forwards (
id varchar(128) NOT NULL,
recipient varchar(128) NOT NULL,
serial_nr serial
);
CREATE INDEX forwards_id_idx ON forwards (id);
CREATE TABLE limits (
domain varchar(64) NOT NULL PRIMARY KEY,
maxAccounts int,
maxAccountSize int,
maxAccountCount int,
maxForwards int,
maxForwardsRcpt int,
serial_nr serial
);
GRANT ALL ON accounts TO quica;
GRANT ALL ON accounts_serial_nr_seq TO quica;
GRANT ALL ON forwards TO quica;
GRANT ALL ON forwards_serial_nr_seq TO quica;
GRANT ALL ON limits TO quica;
GRANT ALL ON limits_serial_nr_seq TO quica;
QUICA uses the DB API 2.0 for python. I use the psycopg adapter. The adapter depends on some python libraries called egenix-mx-base(http://www.egenix.com/files/python/mxDateTime.html). See how I compile this library:
python setup.py install
Here is how I compile the adapter:
./configure --with-postgres-includes=/usr/include/pgsql/server \
--with-postgres-libraries=/usr/lib/ \
--with-mxdatetime-includes=/usr/lib/python2.2/site-packages/mx/DateTime/mxDateTime \
--with-python=/usr/bin/python
make
make install
Keep in mind that these are examples, replace passwords, and think in the security of your database configuration. I am not a database expert.
Create a database to hold the data and a user to access it
These examples are for a database running in the same computer that courier and Quica. Issue these commands in a MySQL shell (mysql).
CREATE DATABASE quica;
GRANT SELECT,INSERT,UPDATE,DELETE,CREATE ON quica.* TO quica@localhost
IDENTIFIED by 'ytumamatambien';
Issue the commands in a MySQL shell (mysql) connected to the created database
In the /dbload/ of the package root directory is a file called MySQL.sql that contains the commands to create the database layout. You can to input these commands to the database as the user you created in the previus step.
Courier package has a file with similar commands. Quica uses a superset of this file. In other words, Quica defined more fields in the database. Use the Quica file, not courier's.
Here is the command line I used:
mysql -h localhost -u root -p < ./dbload/MySQL.sql
QUICA uses the DB API 2.0 for python.
Download an adapter from http://sourceforge.net/projects/mysql-python, compile and install it.
Maybe you are using Debian, so just install it using apt-get:
apt-get install python-mysqldb
If you are using RedHat install the package named 'MySQL-python':
rpm -ivh MySQL-python
Quica uses GNU Make to setup the PHP and Python scripts. So now we take a look to the Makefile to see how customize quica to suit your system. Keep in mind that this document can be outdated, look the real Makefile. See the top of the Makefile:
OS = Linux
#OS = FreeBSD
ifeq ($(OS),Linux)
# Defaults for Linux
BASEDIR = /usr/local
MAILUSER = mailuser
MAILHOME = /var/quica
SITEDIR = /var/www/html/quica
WEBSERVERUID = apache
PYTHON = /usr/bin/python
VARDIR = ${BASEDIR}/var
BINDIR = ${BASEDIR}/sbin
PYLIBDIR = ${BASEDIR}/lib/quica/pylib
ETCDIR = ${BASEDIR}/etc/quica
LIBEXECDIR = ${BASEDIR}/libexec/quica
LOCALEDIR = ${BASEDIR}/share/locale
SUDOLOG = ${VARDIR}/log/quica.sudo
COURIERETCDIR = /etc/courier
COURIERLIBDIR = /usr/lib/courier
MAKEHOSTEDDOMAINS = ${COURIERLIBDIR}/sbin/makehosteddomains
MAKEACCEPTMAILFOR = ${COURIERLIBDIR}/sbin/makeacceptmailfor
SCHEDRESTART = ${COURIERLIBDIR}/sbin/courier restart
else
# Defaults for FreeBSD
BASEDIR = /usr/local
MAILUSER = mailuser
MAILHOME = /var/quica
SITEDIR = /usr/local/www/data
WEBSERVERUID = www
PYTHON = /usr/local/bin/python
VARDIR = /var
BINDIR = ${BASEDIR}/sbin
PYLIBDIR = ${BASEDIR}/lib/quica/pylib
ETCDIR = ${BASEDIR}/etc/quica
LIBEXECDIR = ${BASEDIR}/libexec/quica
LOCALEDIR = ${BASEDIR}/share/locale
SUDOLOG = ${VARDIR}/log/quica.sudo
COURIERETCDIR = ${BASEDIR}/etc/courier
MAKEHOSTEDDOMAINS = ${BASEDIR}/sbin/makehosteddomains
MAKEACCEPTMAILFOR = ${BASEDIR}/sbin/makeacceptmailfor
SCHEDRESTART = ${BASEDIR}/sbin/courier restart
endif
You see what I see?, two sets of options right?. These two have what I think are the best options for Linux or FreeBSD. Set OS variable to 'Linux' or 'FreeBSD' to use one of the defaults. I won't explain here all the options, these are self described. Take these advices:
MAILUSER is the user who owns the maildirs, in the next chapter you will be creating this system user.
WEBSERVERUID is the system user that Apache runs under.
SITEDIR is the path where you want the PHP scripts run.
PYTHON is the full path of your python executable. Do you read Some facts about ... section?
Now run make. All went right? Perfect. If not copy the output and mail the author. Before runing make install we need to create the system user referenced in the MAILUSER variable. This user must follow the 'User private group' scheme, the username = groupname. See how I do it in Linux:
useradd mailuser
And in FreeBSD:
pw user add mailuser
If you now run make install the scripts will be copied to the defined paths in the Makefile and some files will be generated to later use. Run it.
Do you know how sudo works?, if not you should. Try: man sudo. The make command you run in the previus chapter bring to life a new file: ./sudo/sudoers. This file has directives to let the web server run some programs as other user. Take a look a it. Now paste the contents of this file to the configuration file sudo use in your system, usually /etc/sudoers. Sudo generates a log of its operations with Quica, the path of the file is what was defined in SUDOLOG variable in the Makefile. You should rotate this file sometimes if it grows up very much.
I recommend to setup a dedicated machine to host QUICA. The safe_mode PHP option must be Off. Think in the consequences of this for your system. QUICA needs some PHP settings that may don't be the defaults, the make you prevously run generates a file named quica.apache.conf in the ./site directory with some php directives. Review it and paste the contents in the main httpd.conf file. Alternatively you can put the quica.apache.conf file in the directory from where apache reads other configuration directives (Like /etc/httpd/conf.d/ in some systems). These directives also can be written inside a VirtualHost statement for a 'domain only' effect. Remeber to restart Apache to take these changes.
RedHat 8.0 ships with a little buggy Apache, the directives php_flag should be replaced with php_value. So, 'php_flag magic_quotes_gpc off', becomes 'php_value magic_quotes_gpc 0'. Maybe some update correct this, take a look.
A good practice is to serve the quica pages from a secure http server. Remember that passwords will be flowing from the user to your web server.
The complete Courier-mta suite is very extensive, here is covered only the minimum settings to make QUICA work with Courier-mta.
Set the authenticaction module list to "authuserdb authpgsql" in the courier's file authdaemonrc if you use PostgreSQL or "authuserdb authmysql" for MySQL.
The file authpgsqlrc instructs courier's authdaemon how to use the database if PostgreSQL is used. Should have these variables defined:
PGSQL_HOST localhost
PGSQL_PORT 5432
PGSQL_USERNAME quica
PGSQL_PASSWORD ytumamatambien
PGSQL_DATABASE quica
PGSQL_USER_TABLE accounts
PGSQL_CRYPT_PWFIELD crypt
PGSQL_CLEAR_PWFIELD clear
PGSQL_UID_FIELD uid
PGSQL_GID_FIELD gid
PGSQL_LOGIN_FIELD id
PGSQL_HOME_FIELD home
PGSQL_NAME_FIELD name
PGSQL_QUOTA_FIELD quota
If you use MySQL edit the authmysqlrc instead of authpgsqlrc.
The vacation functionality needs that your defaultdelivery be maildrop. Also you maildrop executable need to be compiled with GDBM extensions enabled. Check this running maildrop -v
A quota warning is a nice option for your users. Your defaultdelivery must be maildrop with the -w switch. Note that maildrop must be compiled with Maildir quota extension, check this with maildrop -v. See my defaultdelivery line in courierd file to enable the quota warning:
DEFAULTDELIVERY="| /usr/lib/courier/bin/maildrop -w 90"
Also put a quotawarnmsg warning message in your courier directory.
The Quica configuration file is a "INI" file format. In the section 'database' put the information of the database and select wich type (pgsql or mysql) to use. In the 'general' section there is a 'locallowercase' attribute that should be set to '1' if your courier installation lowercase the local username part of an address. See my file as an example:
[general] locallowercase = 1 [database] dbtype = pgsql ;dbtype = mysql host = localhost user = quica password = ytumamatambien dbname = quica ;port = 5432
The default installation put one file like this in /usr/local/etc/quica.
You have Courier-mta, Apache and PostgreSQL(or MySQL) running. OK, it's time for a test. The following described commands need root privileges. First we add a domain (Please use 'example.com' for this test, see RFC 2606). The command adddomain is for this purpose. Search it in the directory defined with the BINDIR variable of the Makefile. See how I add a domain:
[root@pepa sbin]# ./adddomain.py example.com Postmaster Password: Confirm Password: Maximum number of accounts: [10]: Maximum size of accuount in(MB): [10]: Maximum number of messages per account: [2048]: Maximum number of forwards: [10]: Maximum number of recipients by forward: [20]:
Now we have a domain to let Quica manage. Open a browser and point it to where you installed the quica PHP files (SITEDIR variable of the Makefile). You now should see a a page prompting for a username and a password. Enter postmaster@example.com as username and the password that you just input to adddomain. Create some accounts and forwards (this is described in more depth in the Administration guide). Delete the domain with deldomain. If some of these steps fails contact the author.