language: en / english
select other language

PoCoMy HowTo

A Short Introduction to the Installation, Configuration and Use of PoCoMy

Version: $Id: index.html,v 1.10 2007-09-24 14:18:03 zerwes Exp $ 
© 2007 Klaus Zerwes zero-sys.net
distributed under the terms of the GNU Free Documentation License.
See http://www.gnu.org/copyleft/fdl.html.

This HowTo refers to the current version of PoCoMy: Version 0.8
A more current version of this HowTo may be found on the project-page at sourceforge.net.
This HowTo is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY!

Table of contents:
jump to the table of contents
Preface
PoCoMy is a data base-supported software for the control and configuration of a mail system consisting of the components: Postfix, Courier and Mysql.
Features:
Explanations of the syntax conventions used in this document:
jump to the table of contents
1. Installation
1.1 Prerequisites

PoCoMy requires: On a debian-system (etch) the required software may be installed this way:
apt-get install \ postfix-mysql postfix-pcre postfix-cdb postfix \ sasl2-bin libsasl2-modules libsasl2-modules-sql \ courier-authlib-mysql courier-pop-ssl courier-pop \ courier-imap courier-imap-ssl \ libapache2-mod-php5 php5-mysql apache2 \ mysql-client mysql-server
jump to the table of contents
1.2 Installation

The current version of PoCoMy may be found here:
PoCoMy project hosted by sourceforge.net

Download the current version of PoCoMy and extract the archive into a directory accessible through your webserver. e.g. /var/www/:
tar xz -f PoCoMy-0.8.tgz -C /var/www/
n order to simplify the URL for the access of the webapplication you may create a link to the PoCoMy-0.8-directory:
ln -sv /var/www/PoCoMy-0.8/ /var/www/pocomy

Change into the PoCoMy-directory; all examples in this HowTo assume that your working directory is the newly created PoCoMy-directory.
cd /var/www/PoCoMy-0.8

Create the database:
Use the command listed below to create the database and the database-user:
mysql -u root -p < sql/pocomy.sql;
jump to the table of contents
1.3 Configuration
1.3.1 Configuring PoCoMy

Edit the file config/config.php and adjust:
POCOMY__SITENAME eloquent name of your mailsystem
POCOMY__ENABLE_USERINTERFACE false - no; true - yes; If this is set to true, the PoCoMy User-Module will be activated and the users will gain some control over their account.
see: The PoCoMy User-Module (NOTE: the user interface is not extensively tested!)
POCOMY__USERINTERFACE_URL URL pointing to the User-Module (if this remains unconfigured, the URL will be guessed)
POCOMY__ENABLE_NEWUSEREMAIL false - no; true - yes; controls if a email will be send to a newly created user
POCOMY__POSTMASTERMAIL mail of the postmaster for the system; if this remains unconfigured, the email of the admin will be used;
POCOMY__SERVERNAME_SMTP
POCOMY__SERVERNAME_POP3
POCOMY__SERVERNAME_IMAP		 Servername for the smtp, pop3 and imap server; if this remains unconfigured, the servername of the webserver running PoCoMy will be used;
jump to the table of contents
1.3.2 Configuring Postfix

The directory etc/postfix contains a example configuration for postfix. Copy the files to /etc/postfix (please backup the original files)
cp -r etc/postfix/* /etc/postfix
On some systems you must create a symbolic link for SASL:
ln -sv /etc/postfix/sasl/smtpd.conf /usr/lib/sasl2/smtpd.conf
NOTE: the provided file main.cf is only a example configuration. Use at your own risk! You must edit at least the variable myhostname! Please edit the file with care!
jump to the table of contents
1.3.3 Configuring Courier

The directory etc/courier contains a example configuration for courier. Copy the files to /etc/courier (please backup the original files)
cp -r etc/courier/* /etc/courier
NOTE: The provided files contain only a sample working configuration. Use at your own risk and edit the files with care!
jump to the table of contents
1.3.4 Configuring the Mailstore

Mails are stored by default in /srv/mail.
If you like to change this setting, you must change the value of virtual_mailbox_base in the file /etc/postfix/main AND the value of MYSQL_MAILDIR_FIELD and MYSQL_HOME_FIELD in the file /etc/courier/authmysqlrc!
 
User- and Group-ID for the mailstore are preconfigured to 101:8 (postfix:mail). Please check if the UID and GID match the one used on your system!
grep postfix /etc/passwd | mawk -F : '{print $3}'; grep mail /etc/group | mawk -F : '{print $3}';

If you like to change this settings, you have to change the value of virtual_uid_maps and / or virtual_gid_maps in the file /etc/postfix/main AND the values of MYSQL_UID_FIELD and / or MYSQL_GID_FIELD in the file /etc/courier/authmysqlrc!
 
Use the following commands to create and configure the mailstore:
mkdir /srv/mail; chown postfix:mail /srv/mail; chmod 770 /srv/mail;
jump to the table of contents
1.3.5 Configuring the Directory Structure of the Mailstore

The directory structure of the mailstore is configurable. Some examples may be found in the configuration file mysql-virtual-mailbox-maps in the select_field section. If you like to change the directory strukture, please consider that the changes must be accomplished for both parts: postfix and courier:
file setting
/etc/postfix/mysql-virtual-mailbox-maps select_field
/etc/courier/authmysqlrc MYSQL_MAILDIR_FIELD
jump to the table of contents
1.3.6 Notes about the Database-Users

PoCoMy is using 2 database accounts:
  1. pocomyweb for the webinterface configured in config/config.php section // database connection
  2. pocomymail for postfix and courier configured in
    • /etc/courier/authmysqlrc sections MYSQL_SERVER MYSQL_USERNAME MYSQL_PASSWORD MYSQL_DATABASE
    • /etc/postfix/mysql-* sections user password dbname hosts
This enables a good separation of the access-rights and increases the scalability of the system.
jump to the table of contents
1.4 Adjusting File Rights

Files containing sensitive informations should be secured by assigning them restrictive user rights:
chown root.postfix /etc/postfix/mysql-* ; chmod 640 /etc/postfix/mysql-* ; chown root.postfix /etc/postfix/sasl/smtpd.conf ; chmod 640 /etc/postfix/sasl/smtpd.conf ; chown daemon.daemon /etc/courier/* ; chmod 640 /etc/courier/* ;
jump to the table of contents
1.5 Restart Services

In order to apply the changes, the corresponding services must be restarted:
for i in /etc/init.d/postfix /etc/init.d/courier-*; do $i restart; done;
jump to the table of contents
2. Using the PoCoMy Admin-Module
2.1 First Login

The URL pointing to the Admin-Module is http://SERVERNAME/pocomy/admin.html
For the first time you login into the PoCoMy Admin-Module please use the following account data:
username: pocomy
password: admin
Change the username and / or password for the admin ASAP!!!
jump to the table of contents
2.2 Mail-System

The link "Mail-System" will direct you to the configuration menu for the PoCoMy-Mail-System.
2.2.1 Create a New Domain

Using the menu link "new domain" you can create a new domain for the system. (For this you need the authorization level SUPERADMIN or DOMAINADMIN).
jump to the table of contents
2.2.2 Domain-List

Using the menu link "domain-list" you may view a list of all configured domains according to your authorization.
jump to the table of contents
2.2.3 Create and Configure Mailaccounts

Using the action link " create new mail-account" (available in the domain-list and the domain view) you can create a new mail account.
A short explanation of the most important fields:
  • email: Email address without the domain part
  • language: select one of the available languages.
  • name: Name of the account owner
  • firstname: firstname of the account owner (optional)
  • quota: Quota in MB
  • forward: List of forwarding (email addresses) (see details below)
  • keep a local copy if forward: yes / no
  • allow web-administration: allow this user to use the User-Module?
  • allow POP3: permit POP3 access
  • allow IMAP: permit IMAP access
  • maximum number of aliases: maximum number of aliases the user may configure (Administrators may exceed this number)
  • allow configuration of aliases: yes / no
  • maximum number of sender-aliases: see "maximum number of aliases"
  • allow configuration of sender-aliases: yes / no
  • password: password (requirements: min. 5 characters long, contain at least one letter and a number!)
  • repeat password: confirm password
jump to the table of contents
2.2.4 Create and Configure Forwarding, Aliases and Senderaliases

Here a short explanation concerning the configuration possibilities for forwardings, aliases and senderaliases.
2.2.4.1 Forwardings

You may configure PoCoMy / postfix to forward incoming emails for an account to one or more emails. In order to do this, enter a list of all email addresses to forward into the corresponding field (use ; as a separator for multiple emails). The email addresses may be external!
example:
user1@domain1.de; user2@domain1.de; userx@domainx.de

Corresponding to the setting "keep a local copy if forward" you can configure if a copy of the message should be delivered to the original recipient.
jump to the table of contents
2.2.4.2 Aliases

You could regard Aliases as "nicknames" for email address. Therefore only local domains are permitted for aliases. All emails that have a configured alias as recipient will be delivered to the corresponding user.
jump to the table of contents
2.2.4.3 Senderaliases

User are allowed to send mails after they authenticate with their email address as username and their password AND if the sender of the email is equal to the users email address or is a valid alias for the user.
Senderaliases allow user to use spacial sender for their emails. Enter the the full email address into the senderalias form input.
jump to the table of contents
2.2.5 Search for Email

With the help of this menu link you can perform a search for email and alias owners. Enter the email or alias name without the domain part into the form.
jump to the table of contents
2.3 Useradministration

For the majority of the user administrative tasks you need the authorization level SUPERADMIN. Administrators without this authorization level can only change their own password.
2.3.1 List Admins

Using this menu link you may view a list of all configured admin accounts. Using the action links in the list you may view / edit / delete accounts.
jump to the table of contents
2.3.2 Create and Configure Admins

A short explanation to available form fields:
language Select one of the available languages.
username the username is the login name for the admin
name name of the admin
firstname firstname of the admin (optional)
enabled yes / no (disabled admins can not log in!)
email email address of the admin
administrative rights see Notes About Administrative Rights
domain-competence Administrators without authorization level SUPERADMIN or DOMAINADMIN can only configure domains for which they where configured here as responsible.
see: Notes About Administrative Rights
jump to the table of contents
2.3.3 Notes About Administrative Rights

Only administrators with the privilege level SUPERADMIN can perform configuration tasks regarding user administration.
 
Administrators with the privilege level SUPERADMIN or DOMAINADMIN may configure all domains. Additionally they have the right to create new domains. Other administrators have only the right to configure domains they where configured as responsible for (domain-competence).
jump to the table of contents
3. The PoCoMy User-Module

The URL pointing to the User-Module: http://SERVERNAME/pocomy/
The user module can be en- / disabled using the variable POCOMY__ENABLE_USERINTERFACE in the file config/config.php!
A per-user access can be configured using the setting "allow web-administration"!
If the user module is enabled, a user must fulfill 2 conditions to gain access to the user-module:
  1. user must be enabled
  2. user must have access according the setting allow web-administration
If these conditions are fulfilled, a user can log in into the user-module using his email address and password and perform following configuration tasks:
jump to the table of contents
4. Epilog
Configure your mailserver carefully! Wrong configured mailservers can be a cause for Spam and attacks!
Test your configuration extensively! An external test can be initiated by you from your mailserver:
telnet relay-test.mail-abuse.org
Links:
If you like to translate this document and / or extend the language-list of PoCoMy: volunteers are welcome!
Please use the Tracker-System at the projects page
jump to the table of contents
PoCoMy hosted by: