Open Mail Archiver (OMA)

The Open Mail Archive architecture is based on a central Archive Server which captures all inbound and outbound SMTP traffic of local mail servers.

The Archive Server duplicates all SMTP traffic without changing them, SMTP headers are stored into a central database, mails are stored onto the filesystem; database and mail files are
linked together via pointers.

A web interface is used to manage all Archive operations, the integrity is guaranteed by the coherence of the database and because the solution works on a copy of the original mail. Automatic archives can be launched (when needed) to write DVD or UDO medias with mail messages and local MTA logs.

As SMTP is a standard mail protocol, this archive solution is totally compatible with main mail mechanisms such as Sendmail, Openmail, Groupwise, MS Exchange, Qmail, ...

For performance reasons, it is recommended to dedicate a server to host this Mail Archive function, but this is not mandatory.
As the solution relies on SMTP, it inherits the robustness of the protocol as lost connections below 72h, ...
The Archive Server is currently supported on the following Platform:

* Unix like Operating system (because of IPC structure)
* Apache2 (should be OK with Apache 1.3 and above)
* Php5 (php4 not supported)
* Postgresql7 and above, or Mysql4 and above
* Postfix Any recent version (should be OK with other MTAs)

Note: OMA2 comes with his own MDA, ie procmail, maildrop, ... are not used.

This goal of this document is to guide you through the installation and configuration steps of Open Mail Archive (OMA)

This guide is adapted to OMA release 2.5.

Requirements
============
In order to operate an OMA system you will need the following software on your system:

Postfix
MySQL > 4.0
APACHE > 2.0
PHP > 5.2.0 (module apache + php-cli extensions mysql + sockets + php-ldap if authent with ldap + mb_string)
m4 (used by the installation script)
mailparse extension (#pecl install mailparse)
formail (#apt-get install procmail)

Installation
============

1/ Download OMA (Open Mail Archive)
-----------------------------------
You can always find the latest version of OMA

2/ Run the installation script
---------------------------
-Extract the content of the archive
root@linux:/usr/src# tar zxvf oma-X.Y.Z.tar.gz
root@linux:/usr/src# cd oma-X.Y.Z

-Run the installation script as root
root@linux:/usr/src/oma-2.0.1# ./install.sh
Please enter installation directory ? (/usr/local/oma):
Please enter web directory for oma web interface ? (/var/www/oma):
Please enter oma data directory ? (/oma_data):
Please specify your OMA root web url ? (http://localhost/oma):
Please specify your mysql server ? (localhost):
Please enter apache process user? (www-data):

[Create oma user]
user oma created

[Mysql configuration]
Please enter root password for mysql ?Enter password:

[Copy files]
Create directory /usr/local/oma
Create directory /oma_data
Create directory /oma_data/mails
Create directory /oma_data/logs
Create directory /oma_data/tmp
Install oma in /usr/local/oma
copying directory etc
copying directory lib
copying directory bin
copying web interfaces in directory /var/www/oma

[Clean all m4 files]
[Set user permissions]

3/ Edit configuration file
--------------------------
Next, edit the configuration file and adjust the configuration parameters.
The configuration file is located in your installation directory "/usr/local/oma/etc/oma.conf". Its syntax is the same as the one used in a php.ini file, and it has been preconfigured for you by the installation script.

4/ Check mail insertion
-----------------------
At this point it is possible to verify that mails get inserted correctly in the database.

!!! WARNING: do not run this script as root !!!:
!!! WARNING : if you didn't configured your postfix yet, you must set postfix_smtp_after_relay = false in /usr/local/oma/etc/oma.conf

root@linux:/usr/src/oma-2.0.1# su oma
$cat misc/mail_test | /usr/local/oma/bin/oma_filter.php userfrom@email.tld userto@email.tld
$tail /oma_data/logs/_mail_delivery.log
29/08/2007 11:50 [INFO] Write file /oma_data/mails//200708d/o200708291188381014750457_mail
29/08/2007 11:50 [INFO] Inserting new message from (userfrom@email.tld),
ID:0aa80fa5341e8ccac6165fa64f33a56093c4eb5b9794941ac3709def5df90f0b

Postfix configuration
=====================

1/ OMA daemon filter
---------------------------
Add "oma_filter" as a postfix filter by adding the following line to "/etc/postfix/master.cf" (be carefull with white spaces before "flags") :
oma_filter unix - n n - 1 pipe
flags=Rhu user=oma argv=/usr/local/oma/bin/oma_filter.php $ $

2/ SMTP post filter
-------------------
Add a second SMTP in postfix configuration "/etc/postfix/master.cf" by adding these lines :
127.0.0.1:10027 inet n - n - - smtpd
-o content_filter=
-o local_recipient_maps=
-o relay_recipient_maps=
-o smtpd_restriction_classes=
-o smtpd_client_restrictions=
-o smtpd_helo_restrictions=
-o smtpd_sender_restrictions=
-o smtpd_recipient_restrictions=permit_mynetworks,reject
-o mynetworks=127.0.0.0/8
-o strict_rfc821_envelopes=yes
-o smtpd_error_sleep_time=0
-o smtpd_soft_error_limit=1001
-o smtpd_hard_error_limit=1000

3/ Before filter definition
---------------------------
Edit "/etc/postfix/main.cf" and add this line :
content_filter = oma_filter

3/ Postfix restart
------------------
Restart postfix : sudo /etc/init.d/postfix reload

4/ Test postfix
---------------
It is now possible to verify that postfix is configured correctly by sending an email to the MTA. For example using telnet:

$telnet localhost 25
>helo host.mydomain
>mail from: user@mydomain
>rcpt to: user2@mydomain
>data
>From: user@mydomain
>To: user2@mydomain
>Subject: test
>Test mail
>.

The test is successfull if your "/oma_data/logs/_mail_delivery.log" contains a line similar to the following:
29/08/2007 16:20 [INFO] Write file /oma_data/mails//200708d/o20070829118839721217007_mail
29/08/2007 16:20 [INFO] Inserting new message from (user@mydomain),
ID:0aa80fa5341e8ccac6165fa64f33a56093c4eb5b9794941ac3709def5df90f0b

In case of failure check the postfix logs or /var/log/syslog.

Configuring authentication
==========================
OMA can be configured to use either the password_file or password_ldap authentication plugins . This is done by changing the value of "auth_plugin" in OMA's configuration file (/usr/local/oma/etc/oma.conf)
auth_plugin= "password_file" ; authenticate against a plain text password file
auth_plugin= "ldap" ; authenticate using AD or LDAP

By default the "password_file" authentication plugin is used and during the installation, a user "admin" with password "admin" is created

A/ Text file based authentication
---------------------------------
The password file is in "/var/www/oma" and has the following structure
username:0|1:md5 crypted password
for example:
username@domain.tld:1:764b9c698569b4e77fd69db363fef414

The user is an administrator if the number between the two colons is 1.

You can generate a new password line useing the "oma_passline" command that is installed in "/usr/local/oma/bin/".
for example:

root@linux:/usr/local/oma/bin# ./oma_passline.php username@domain.tld mypassword 1
username@domain.tld:1:764b9c698569b4e77fd69db363fef414

B/ LDAP/Active directory based authentication
---------------------------------------------
LDAP configuration is done in "/usr/local/oma/lib/plugin/auth/ldap/ldap.conf".

Apache configuration
====================
The ideal solution is to create a virtual host:

ServerAdmin admin@yourdomain
ServerName oma.yourdomain
DocumentRoot /var/www/oma
Options Indexes FollowSymLinks
AllowOverride all
Order allow,deny
allow from all
You will of course need to add an entry in your dns for oma.yourdomain.

Installing and configuring the daemon
=====================================

1/ Edit "/usr/local/oma/etc/oma.conf" and adjust the parameters
---------------------------------------------------------------

2/ Install the startup script
-----------------------------
- debian/ubuntu :
/usr/src/oma-X.Y.Z/misc# sudo cp oma_startscript.debian /etc/init.d/oma

edit /etc/init.d/oma and update the value of "BASE_OMA_DIR" .

-redhat/fedora :
use "oma_startscript.fedora" instead

3/ Configure sudoers
--------------------
sudo is used to permit the web interfaces to lauch the OMA daemon.

Add the following line to "/etc/sudoers":
www-data ALL=NOPASSWD:/etc/init.d/oma

Troubleshootings :
==================
"postfix pipe command output permission denied" in your mail log
- edit /etc/selinux/config :
SELINUX=permissive
- restart computer

"sorry, you must have a tty to run sudo ; TTY=unknown" in your secure log
- edit /etc/sudoers and comment :
#Defaults requiretty

Bugs or known issues
====================
Report bugs or issues to http://www.octant.org

Authentication

By pointing your web browser at "http://oma_server" ,you should get to the login page.

Identify yourself with your email address and the password that was given to you.
If these identifiers are correct, you will be taken to the query page.

Querying

First choose whether you want to search in your send or recieved mails.

Next you can refine your search using different criteriums.

Expediteur: Enter the complete or part of the email address of the sender. For example support, or support@octant-fr.com
Destinatire: Enter the complete or part of the reievers email address
Subject:A word of the emails subject
Date: Give a time period or a single date to search mails of that day according to the this format: (dd/mm/aaaa , dd-mm-aaaa)
Taille

Once you have filled in the different search criteria, click the "search" button. The system will then display the matching emails.