modoboa/INSTALL

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

Requirements
------------

- Python version 2.5+
- Django version 1.0+ (http://docs.djangoproject.com/en/dev/intro/install/#intro-install)

How to install
--------------

Download Mailng's tarball and extract it::

  tar xzf mailng-<version>.tar.gz
  mv mailng-<version> mailng

Settings file

  Enter the mailng directory, create a settings.py file (you can use
  settings-sample.py as a model).
  Specify database relative informations.
  You must choose between mysql and postgresql, other types are not supported by
  major email projects like postfix or dovecot.
  Create a database with the name you specified in settings.py.
  you will probably need python database module backend like MySQLdb.
  Modify TEMPLATE_DIRS.

Initialise the database by running the following command::

  python manage.py syncdb

Create the super admin account (just follow the procedure).

Run the initialisation script. It will insert needed data into the database :

  export PYTHONPATH=$PWD/..
  DJANGO_SETTINGS_MODULE=mailng.settings ./scripts/populate.py

How to upgrade
--------------

0.6 -> 0.7 : no SQL modifications.
0.5 -> 0.6 : no SQL modifications.

If no modifications have been made to the core SQL schema, juste
decompress the new tarball at the same location than your current
installation.

Host configuration
------------------

Before testing Mailng, you must create a group and a user that will be
used to store mails on the host filesystem. There is only one
group/user needed because we are in a virtual hosting configuration
(ie. users with non-UNIX accounts).

For example, create a vmail group::

  groupadd vmail

Then create a vmail user::

  useradd -g vmail -d /var/vmail -m vmail

At last, the system user used to run mailng will need permissions to
manipulate directories in vmail's homedir. To do that, edit your /etc/sudoers
file and add the following inside::

  www-data ALL=(vmail) NOPASSWD: ALL

Testing installation
--------------------

As a typical Django application, Mailng can be tested using a simple web 
server. Just run this command to start it::

  python manage.py runserver

You will be able to play with mailng by looking at 
http://<youraddress>:8000/mailng/admin/.

Tips to link Mailng with postfix
--------------------------------

First, define following maps on your server (this should work with
Postfix versions >= 2.2)::

# /etc/postfix/sql-domains.cf
  user = <user>
  password = <password>
  dbname = <database>
  hosts = 127.0.0.1
  query = SELECT name FROM admin_domain WHERE name='%s' AND enabled='1'

# /etc/postfix/sql-mailboxes.cf
  user = <user>
  password = <password>
  dbname = <database>
  hosts = 127.0.0.1
  query = SELECT path FROM admin_mailbox WHERE full_address = '%s'

# /etc/postfix/sql-aliases.cf
  user = <user>
  password = <password>
  dbname = <database>
  hosts = 127.0.0.1
  query = SELECT t2.full_address FROM admin_alias AS t1, admin_mailbox AS t2 WHERE t1.full_address='%s' AND t1.mbox_id=t2.id AND t1.enabled='1'

Then, use the following configuration in your /etc/postfix/main.cf file
(this is one possible configuration)::

  # Stuff before
  mailbox_transport = virtual
  home_mailbox = .maildir/ 
  maildrop_destination_recipient_limit = 1
  virtual_minimum_uid = <vmail user id> 
  virtual_gid_maps = static:<vmail group id>
  virtual_uid_maps = static:<vmail user id>
  virtual_mailbox_base = /var/vmail

  relay_domains = 
  virtual_mailbox_domains = mysql:/etc/postfix/sql-domains.cf
  virtual_mailbox_maps = mysql:/etc/postfix/sql-mailboxes.cf
  virtual_alias_maps = mysql:/etc/postfix/sql-aliases.cf
  # Stuff after

NB: Mailng supports both maildir and mbox formats. You can specify
which format to use by modifying the MAILBOX_TYPE variable located
inside 'settings.py'.

Tips to activate auto-reply messages in Postifx
-----------------------------------------------

Since version 0.6, mail users can define an auto-reply message with MailNG.

To activate the extension, edit your settings.py and add the following
line inside the INSTALLED_APPS variable::

  'mailng.extensions.postfix_autoreply',

Then run the following commands to update MailNG SQL schema and content::

  # python manage.py syncdb
  # export PYTHONPATH=$PWD/..
  # DJANGO_SETTINGS_MODULE=mailng.settings ./scripts/upgrade_autoreply.py

To make Postfix understand this feature, you need to update your configuration
files as follow::

 # /etc/postfix/main.cf
  transport_maps = mysql:/etc/postfix/maps/sql-transport.cf
  virtual_alias_maps = mysql:/etc/postfix/maps/sql-aliases.cf
          mysql:/etc/postfix/maps/sql-autoreplies.cf

 # /etc/postfix/master.cf
  autoreply unix        -       n       n       -       -       pipe
            flags= user=nobody argv=<path_to_mailng>/scripts/autoreply $sender $mailbox

Then, create new map files with the following content::

 # /etc/postfix/maps/sql-transport.cf
  user = <user>
  password = <password>
  dbname = <database>
  hosts = 127.0.0.1
  query = SELECT method FROM postfix_autoreply_transport WHERE domain='%s'

 # /etc/postfix/maps/sql-autoreplies.cf
  user = <user>
  password = <password>
  dbname = <database>
  hosts = 127.0.0.1
  query = SELECT full_address, autoreply_address FROM postfix_autoreply_alias WHERE full_address='%s'

Finally, edit the shell script 'autoreply' located inside the
'scripts' directory and change the value of BASEDIR. (just put absolute path
of the directory where mailng is installed)

NB: auto-reply messages are just sent one time per sender for a
pre-defined time period. By default, this period is equal to 1 day
(86400s), you can adjust this value by modifying the AUTOREPLY_TIMEOUT
variable located inside 'settings.py'.

NB: Be sure that both 'autoreply' and 'autoreply.py' scripts (located
inside the 'scripts' directory) have good permissions (ie. 0755).

Tips to link Mailng with dovecot
--------------------------------

If you are using 'maildir' format to store mailboxes, add the
following line inside your main Dovecot config file
(/etc/dovecot/dovecot.conf)::

  mail_location = maildir:<path_to_mailboxes>/%d/%n/.maildir

If you are using 'mbox' format, put the following::
  
  mail_location = mbox:<path_to_mailboxes>/%d/%n/:INBOX=<path_to_mailboxes>/%d/%n/Inbox

To make the authentication work, edit 'dovecot.conf' and add the
following inside::

  auth default {
    # ... stuff before

    passdb sql {
      # Path for SQL configuration file, see /etc/dovecot/dovecot-sql.conf for
      #  example
      args = /etc/dovecot/dovecot-sql.conf
    }
    
    userdb sql {
      # Path for SQL configuration file
      args = /etc/dovecot/dovecot-sql.conf
    }

    # ... stuff after
  }

Be sure to activate only one backend (per type) inside your configuration
(comment other ones).

Then, edit your /etc/dovecot/dovecot-sql.conf and modify following lines::

  driver = mysql
  connect = host=<mysqld socket> dbname=<database> user=<user> password=<password>
  default_pass_scheme = PLAIN-MD5
  password_query = SELECT full_address AS user, password FROM admin_mailbox WHERE full_address = '%u'
  user_query = SELECT path AS home, uid, gid FROM admin_mailbox WHERE full_address = '%u'

Enable quotas with Dovecot
--------------------------

Put the following lines inside your dovecot.conf file::

    protocol imap {
      mail_plugins = quota quota_imap
    }

Before continuing, you need to know which quota backend must be user
(function of mailboxes format):: 
 * 'mbox' : backend=dirsize,
 * 'maildir' : backend=maildir.

If you use version prior to 1.1, add also the following configuration::

  plugin {
    # 10 MB default quota limit
    quota = <backend>:storage=10240
  }

Then modify the above user_query inside dovecot-sql.conf file like
that to activate per user quotas::

  user_query = SELECT path AS home, uid, gid, concat('<backend>:storage=', quota / 1024) AS quota FROM admin_mailbox WHERE full_address = '%u'

For version >= 1.1, put the following configuration inside dovecot.conf file::

  plugin {
    # Default 10M storage limit with an extra 5M limit when saving to Trash.
    quota = <backend>:User quota
    quota_rule = *:storage=10M
    quota_rule2 = Trash:storage=5M
  }

Then modify the above user_query inside dovecot-sql.conf to activate
user quotas::

  user_query = SELECT path AS home, uid, gid, concat('*:storage=', quota, 'M') AS quota_rule FROM admin_mailbox WHERE full_address = '%u'

Tips to serve Mailng behind Apache2
------------------------------------

First, be sure to have apache2 and mod_python installed on your
server.

Create a new virtualhost in your Apache configuration and put the
following inside::

  <VirtualHost *:80>
    <Location "/">
      SetHandler mod_python
      PythonHandler django.core.handlers.modpython
      PythonPath "['<path to directory that contains mailng dir>'] + sys.path"
      SetEnv DJANGO_SETTINGS_MODULE mailng.settings
    </Location>
    Alias "/static" "<path to mailng dir>/static"
    <Location "/static/">
      SetHandler None
    </Location>
  </VirtualHost>

This is one possible configuration. Note that you will certainly need more
configuration in order to launch Apache.

Using the amavisd-new quarantine plugin
---------------------------------------

This plugin allows you and your users to handle amavisd-new SQL
quarantine. You can consult messages and/or release or delete them.

If you plan to use it, first make sure to have those requirements
installed on your server::

- mysqldb python module (http://mysql-python.sourceforge.net/)
- lxml python module (http://codespeak.net/lxml/)

To activate the extension, edit your settings.py and add the following
line inside the INSTALLED_APPS variable::

  'mailng.extensions.amavis_quarantine',

Just run the following command to update MailNG SQL schema::
  
  # python manage.py syncdb

Then, you need to specify where is the database that contains the
quarantine. Inside settings.py, add a new connection to the
DB_CONNECTIONS variable like this::

  DB_CONNECTIONS = (
    {"amavis_quarantine" : {"driver"   : "mysql",
                            "host"     : "<your_host>",
                            "dbname"   : "<amavis_dbname>",
                            "login"    : "<user>",
                            "password" : "<password>"}
     }
    )

Replace values between <> with yours.

Finally, create a symbolic link to the templates directory inside the
main templates directory::

  # ln -s extensions/amavis_quarantine/templates templates/amavis_quarantine

To be able to release messages, first take a look at this page::

http://www.ijs.si/software/amavisd/amavisd-new-docs.html#quar-release

It shows how to configure amavisd-new to listen somewhere for the
AM.PDP protocol. This protocol is used to send release requests.

Below is an example of a working configuration::

  $interface_policy{'SOCK'} = 'AM.PDP-SOCK';
  $interface_policy{'9998'} = 'AM.PDP-INET';

  $policy_bank{'AM.PDP-SOCK'} = {
    protocol => 'AM.PDP',
    auth_required_release => 0,
  };
  $policy_bank{'AM.PDP-INET'} = {
    protocol => 'AM.PDP',
    inet_acl => [qw( 127.0.0.1 [::1] )],
  };

Don't forget to update the inet_acl list if you plan to release from
the network.

Once amavisd-new is configured, just tell MailNG where it can find the
"release server" by modifying following variables inside settings.py::

  # "unix" or "inet"
  AM_PDP_MODE = "inet"

  # "unix" mode only
  AM_PDP_SOCKET = "/var/amavis/amavisd.sock"

  # "inet" mode only
  AM_PDP_HOST = "127.0.0.1"
  AM_PDP_PORT = 9998

Last point, MailNG provides a simple script that periodically purge
the amavisd-new quarantine database. If you plan to use it, you can
add the following line inside root's crontab::

  0 0 * * * PYTHONPATH=<mailng_dir/..> \
    DJANGO_SETTINGS_MODULE=mailng.settings \
    <mailng_dir>/extensions/amavis_quarantine/cleanup.py

Replace mailng_dir with the installation path of MailNG.

By default, messages older than 14 days are automatically purged. You
can modify this value by changing the variable MAX_MESSAGES_AGE inside
settings.py.

Statistics plugin setup
-----------------------

Early version of that plugin only support parsing of postfix log as syslog format.
Please make sure you have a valid /var/log/maillog postfix log file.
Don't forget to create a link from /templates/stats to extensions/stats/template
FIXME : 
Parsing for domain is not fully supported, soon in a next version.
User priviledges are not handled properly. So you understand 
it is a really eraly pluggin  version!! Enjoy