Installation ============ Requirements ------------ - Python version 2.6+ - Django version 1.2+ (http://docs.djangoproject.com/en/dev/intro/install/#intro-install) - south version 0.7+ (http://south.aeracode.org/) How to install -------------- Download Modoboa's tarball and extract it:: # tar xzf modoboa-.tar.gz # mv modoboa- modoboa Then, enter the modoboa 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. Make sure your database is using UTF8 as a default charset. If not, you will surely have problems (with MySQL at least). You will probably need to install a python database backend (like MySQLdb). Initialise the database by running the following command:: # python manage.py syncdb Create the super admin account (just follow the procedure). Since version 0.8, Modoboa is using south to handle schema migration. In order to finish the database creation, you must run the first migration like this:: # python manage.py migrate How to upgrade -------------- First, decompress the new tarball at the same location than your current installation. Then, check if the new version you're installing requires a migration:: 0.8 -> 0.8.1 : project renamed. * First, rename your mailng folder to modoboa and copy all the content from modoboa-0.8.1 to modoboa. * Edit your settings.py and replace all occurences of mailng by modoboa. Make sure you don't modify the DATABASE section as you're not going to rename your database. * Rename the MAILNG_DIR variable to MODOBOA_DIR. * Add 'django.contrib.messages.middleware.MessageMiddleware' to MIDDLEWARE_CLASSES and 'django.contrib.messages' to INSTALLED_APPS. Save your modifications. * Run the following command:: # python manage.py syncdb * For all activated extensions, run the following command:: # export PYTHONPATH=/.. # DJANGO_SETTINGS_MODULE=modoboa.settings \ /scripts/extension.py on * Update your webserver configuration and restart it. 0.7 -> 0.8 : SQL migration needed. Before you start migration, make sure you have updated your INSTALLED_APPS variable and that it contains at least:: INSTALLED_APPS = ( # Django's stuff before 'south', 'modoboa', 'modoboa.lib', 'modoboa.admin', 'modoboa.userprefs', ) Starting with 0.8, modoboa.main doesn't exist anymore. You need to remove it from your INSTALLED_APPS. NB: Before doing this migration, I recommend that you make a copy of your existing database. Finally, run the following commands: # python manage.py syncdb # python manage.py convert_to_south # python manage.py migrate --all 0001 --fake # python manage.py migrate --all 0002 0.6 -> 0.7 : no SQL modifications. 0.5 -> 0.6 : no SQL modifications. Time zone and language ---------------------- Modoboa is available in english, french and german. You can choose which language to use by modifying the LANGUAGE_CODE variable inside settings.py:: LANGUAGE_CODE = 'en-US' # English # or LANGUAGE_CODE = 'fr-FR' # French # or LANGUAGE_CODE = 'de-DE' # German You can also specify your time zone by modifying the TIME_ZONE variable. For example:: TIME_ZONE = 'Europe/Paris' Host configuration ------------------ Before testing Modoboa, 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 modoboa will need permissions to manipulate directories in vmail's homedir. To do so, edit your /etc/sudoers file and add the following inside:: ALL=(vmail) NOPASSWD: ALL Testing installation -------------------- As a typical Django application, Modoboa 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 Modoboa by looking at http://:8000/modoboa/admin/. Tips to link Modoboa with postfix -------------------------------- First, define following maps on your server (this should work with Postfix versions >= 2.2):: # /etc/postfix/sql-domains.cf user = password = dbname = hosts = 127.0.0.1 query = SELECT name FROM admin_domain WHERE name='%s' AND enabled='1' # /etc/postfix/sql-mailboxes.cf user = password = dbname = hosts = 127.0.0.1 query = SELECT path FROM admin_mailbox WHERE full_address = '%s' # /etc/postfix/sql-aliases.cf user = password = dbname = hosts = 127.0.0.1 query = SELECT t3.full_address FROM admin_alias AS t1, admin_alias_mboxes AS t2, admin_mailbox AS t3 WHERE t1.full_address='%s' AND t1.id=t2.alias_id AND t2.mailbox_id=t3.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 = virtual_gid_maps = static: virtual_uid_maps = static: 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: Modoboa supports both maildir and mbox formats. You can specify which format to use by modifying the MAILBOX_TYPE parameter available in the admin panel. Tips to activate auto-reply messages in Postifx ----------------------------------------------- Since version 0.6, mail users can define an auto-reply message with Modoboa. To activate the extension, edit your settings.py and add the following line inside the INSTALLED_APPS variable:: 'modoboa.extensions.postfix_autoreply', Run the following command to activate the component:: # export PYTHONPATH=/.. # DJANGO_SETTINGS_MODULE=modoboa.settings \ /scripts/extension.py postfix-autoreply on Then run the following commands to update Modoboa SQL schema and content:: # python manage.py syncdb # python manage.py migrate postfix-autoreply # export PYTHONPATH=$PWD/.. # DJANGO_SETTINGS_MODULE=modoboa.settings ./scripts/postfix_autoreply/upgrade_autoreply.py The user that executes the autoreply script needs to access settings.py. You must apply proper permissions on this file. For example, if settings.py belongs to www-data:www-data, you can add the vmail user to the www-data group and set the read permission for the group. 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=vmail: argv=/scripts/postfix_autoreply/autoreply $sender $mailbox Then, create new map files with the following content:: # /etc/postfix/maps/sql-transport.cf user = password = dbname = hosts = 127.0.0.1 query = SELECT method FROM postfix_autoreply_transport WHERE domain='%s' # /etc/postfix/maps/sql-autoreplies.cf user = password = dbname = 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 modoboa 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 parameter available in the admin panel. NB: Be sure that both 'autoreply' and 'autoreply.py' scripts (located inside the 'scripts/postfix_autoreply' directory) have good permissions (ie. 0755). Tips to link Modoboa 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:/%d/%n/.maildir If you are using 'mbox' format, put the following:: mail_location = mbox:/%d/%n/:INBOX=/%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= dbname= user= password= default_pass_scheme = CRYPT 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 imap_quota } 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 = :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(':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 = :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 Modoboa 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:: SetHandler mod_python PythonHandler django.core.handlers.modpython PythonPath "[''] + sys.path" SetEnv DJANGO_SETTINGS_MODULE modoboa.settings Alias "/static" "/static" SetHandler None 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:: 'modoboa.extensions.amavis_quarantine', Then run the following command to activate the component:: # export PYTHONPATH=/.. # DJANGO_SETTINGS_MODULE=modoboa.settings \ /scripts/extension.py amavis-quarantine on 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" : "", "dbname" : "", "login" : "", "password" : ""} } Replace values between <> with yours. When viewing messages, you can choose to display links (addresses, images). In order to display images correctly, you need to create a tmp directory under static/ for storing them. For example:: # mkdir /static/tmp 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 Modoboa where it can find the "release server" by modifying following parameters in the admin panel:: # "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, Modoboa 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= \ DJANGO_SETTINGS_MODULE=modoboa.settings \ /extensions/amavis_quarantine/cleanup.py Replace modoboa_dir with the installation path of Modoboa. By default, messages older than 14 days are automatically purged. You can modify this value by changing the MAX_MESSAGES_AGE parameter in the admin panel. Using the statistics plugin --------------------------- This plugin allows you to collect various statistics about emails traffic on your server. It parses log file to collect information and then generates graphics in PNG format. If you plan to use it, first make sure to have those requirements installed on your server:: - rrdtool python binding (http://oss.oetiker.ch/rrdtool/) To activate the extension, edit your settings.py and add the following line inside the INSTALLED_APPS variable:: 'modoboa.extensions.stats', Then run the following command to activate the component:: # export PYTHONPATH=/.. # DJANGO_SETTINGS_MODULE=modoboa.settings \ /scripts/extension.py stats on Then, adapt the following parameters to your environnement:: # Path to mail log file LOGFILE = "/var/log/mail.log" # Path to directory where rrd files are stored RRD_ROOTDIR = "/tmp/modoboa" # Path to directory where png files are stored IMG_ROOTDIR = "/static/graphs" Make sure the directories that will contain those files exist. If not, create them before going further. For example (according to previous parameters):: $ mkdir /tmp/modoboa $ mkdir /static/graphs To finish, you need to collect information periodically in order to feed rrd files. To do so, just add the following lines into root's crontab:: */5 * * * * PYTHONPATH= DJANGO_SETTINGS_MODULE=modoboa.settings /scripts/stats/logparser.py Replace modoboa_dir with the installation path of Modoboa. Graphics are automatically created after each new parsing. Using the webmail component --------------------------- Modoboa provides a simple webmail component (you can browse, read and compose messages). With this feature, it is possible to deploy an almost standalone emails platform just with Modoboa. The following requirements are needed before going further:: - lxml python module (http://codespeak.net/lxml/) - pycrypto python module (http://www.dlitz.net/software/pycrypto/) Just run the following command to activate the component:: # export PYTHONPATH=/.. # DJANGO_SETTINGS_MODULE=modoboa.settings \ /scripts/extension.py webmail on Sometimes, inline images are integrated inside emails. To display them, Modoboa stores them inside a temporary folder. Make sure the following path exists, otherwise create it:: # mkdir /static/tmp The user that is running Modoboa will need the write permission inside this folder. Next, go to the admin panel and modify the following parameters in order to communicate with your IMAP and SMTP servers:: IMAP_SECURED = no IMAP_SERVER = 127.0.0.1 IMAP_PORT = 143 SMTP_SECURED = no SMTP_AUTHENTICATION = no SMTP_SERVER = 127.0.0.1 SMTP_PORT = 25 Last but not least, modify the SECRET_KEY parameter and choose a new value (exactly 16 characters). This key is really important, it is used to encrypt/decrypt user passwords stored inside sessions. Do not communicate this key to anyone!!