github-jwinterm/modoboa
1
0
Fork 0
mirror of https://github.com/jwinterm/modoboa.git synced 2026-10-18 05:51:26 +02:00
Code Issues Packages Projects Releases Wiki Activity

Documentation update.

Browse Source
This commit is contained in:
Antoine Nguyen
2013-05-30 14:08:48 +02:00
parent e3040a7b02
commit 1cf7280b35
10 changed files with 255 additions and 477 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.rst
+1 -1
View File
@@ -29,7 +29,7 @@ Main features
* Webmail
* Per-user Sieve filters
* Autoreply messages for Postfix
* Graphical statistics about emails traffic
* Graphical statistics about email traffic
*************
Documentation
doc/conf.py
+2 -2
View File
@@ -48,9 +48,9 @@ copyright = u'2013, Antoine Nguyen'
# built documents.
#
# The short X.Y version.
version = '0.9'
version = '1.0'
# The full version, including alpha/beta/rc tags.
release = '0.9.5'
release = '1.0.0'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
doc/extending/events.rst
+12
View File
@@ -82,6 +82,18 @@ Raised when an existing account is modified.
* ``newaccount`` is the account after the modification
ExtraAccountActions
===================
Raised when the account list is displayed. Let developers define new
actions to act on a specific user.
*Callback prototype*::
def callback(account): pass
* ``account`` is the account being listed
AdminMenuDisplay
================
doc/getting_started/configuration.rst
+117 -91
View File
@@ -20,43 +20,80 @@ corresponding to one application.
.. _admin-params:
*admin* application parameters
==============================
General parameters
==================
The *admin* application exposes several parameters, mainly to control
how mailboxes are created and how messages are stored on the file
system.
The *admin* application exposes several parameters, they are presented below:
Default values are presented below::
+--------------------+--------------------+--------------------+
|Name |Description |Default value |
+====================+====================+====================+
|Authentication type |The backend used for|Local |
| |authentication | |
+--------------------+--------------------+--------------------+
|Default password |Scheme used to crypt|crypt |
|scheme |mailbox passwords | |
+--------------------+--------------------+--------------------+
|Secret key |A key used to |random value |
| |encrypt users' | |
| |password in sessions| |
+--------------------+--------------------+--------------------+
|Handle mailboxes on |Rename or remove |no |
|filesystem |mailboxes on the | |
| |filesystem when they| |
| |get renamed or | |
| |removed within | |
| |Modoboa | |
+--------------------+--------------------+--------------------+
|Mailboxes owner |The UNIX account who|vmail |
| |owns mailboxes on | |
| |the filesystem | |
+--------------------+--------------------+--------------------+
|Automatic account |When a mailbox is |no |
|removal |removed, also remove| |
| |the associated | |
| |account | |
+--------------------+--------------------+--------------------+
|Maximum log record |The maximum age in |365 |
|age |days of a log record| |
+--------------------+--------------------+--------------------+
|Items per page |Number of displayed |30 |
| |items per page | |
+--------------------+--------------------+--------------------+
|Default top |The default |userprefs |
|redirection |redirection used | |
| |when no application | |
| |is specified | |
+--------------------+--------------------+--------------------+
The authentication type
AUTHENTICATION_TYPE = Local
.. note::
Does Modoboa need to handle the creation of directories on the file system?
CREATE_DIRECTORIES = Yes
A random secret key will be generated each time the *Parameters*
page is refreshed and until you save parameters at least once.
Where Modoboa stores mailboxes
STORAGE_PATH = /var/vmail
.. note::
Which user:group Modoboa uses to assign permissions on mailboxes
VIRTUAL_UID = vmail
VIRTUAL_GID = vmail
Specific LDAP parameters are also available, see :ref:`LDAP
authentication <ldap_auth>`.
Which format is used to store messages in a mailbox
MAILBOX_TYPE = maildir
*************
Customization
*************
If maildir is in use, tells Modoboa that mailbox content is under a
potential sub-directory
MAILDIR_ROOT = .maildir
Custom logo
===========
When a mailbox is removed, also remove the associated account
AUTO_ACCOUNT_REMOVAL = No
You have the possibility to use a custom logo instead of the default
one on the login page.
The encryption method used to store passwords
PASSWORD_SCHEME = crypt
To do so, open the *settings.py* file and add a
``MODOBOA_CUSTOM_LOGO`` variable. This variable must contain the
relative URL of your logo under ``MEDIA_URL``. For example::
The number of displayed items per page for listing pages
ITEMS_PER_PAGE = 30
MODOBOA_CUSTOM_LOGO = os.path.join(MEDIA_URL, "custom_logo.png")
Then copy your logo file into the directory indicated by
``MEDIA_ROOT``.
******************
Host configuration
@@ -64,30 +101,17 @@ Host configuration
.. note::
This section is only relevant when the ``CREATE_DIRECTORIES``
parameter is set to ``Yes``.
This section is only relevant when Modoboa handles mailboxes
renaming and removal from the filesystem.
To let Modoboa create mailboxes and store emails on the filesystem,
you must create a group and a user (UNIX ones). There is only one
group/user needed because we are in a virtual hosting configuration
(ie. users with non-UNIX accounts).
To manipulate mailboxes on the filesystem, you must allow the user who
runs Modoboa to execute commands as the user who owns mailboxes.
The following examples are based on the default values presented in
:ref:`admin-params`.
To do so, edit the */etc/sudoers* file and add the following inside::
For example, create a vmail group::
<user_that_runs_modoboa> ALL=(<mailboxes owner>) NOPASSWD: ALL
$ 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 the
*/etc/sudoers* file and add the following inside::
<user_that_runs_modoboa> ALL=(vmail) NOPASSWD: ALL
Replace values between ``<>`` by the ones you use.
.. _timezone_lang:
@@ -95,18 +119,12 @@ manipulate directories in vmail's homedir. To do so, edit the
Time zone and language
**********************
Modoboa is available in english, french, german and spanish.
Modoboa is available in many languages.
To specify the default language to use, edit the *settings.py* file
and modify the ``LANGUAGE_CODE`` variable::
LANGUAGE_CODE = 'en-US' # English
# or
LANGUAGE_CODE = 'fr-FR' # French
# or
LANGUAGE_CODE = 'de-DE' # German
# or
LANGUAGE_CODE = 'es-ES' # Spanish
LANGUAGE_CODE = 'fr' # or 'en' for english, etc.
.. note::
@@ -159,6 +177,8 @@ For example, you could setup a cron job to run this script every night::
External authentication
***********************
.. _ldap_auth:
LDAP
====
@@ -171,42 +191,58 @@ If you want to use this feature, you must first install those components::
$ pip install python-ldap django-auth-ldap
Then, all you have to do is to modify the *settings.py* file:
* Add a new authentication backend to the `AUTHENTICATION_BACKENDS`
variable, like this::
Then, all you have to do is to modify the *settings.py* file. Add a
new authentication backend to the `AUTHENTICATION_BACKENDS` variable,
like this::
AUTHENTICATION_BACKENDS = (
'modoboa.lib.authbackends.LDAPBackend',
'modoboa.lib.authbackends.SimpleBackend',
)
* Set the required parameters to establish the communication with your
LDAP server, for example::
Then, go to *Modoboa > Parameters > General* and set *Authentication
type* to LDAP.
import ldap
from django_auth_ldap.config import LDAPSearch
From there, new parameters will appear to let you configure the way
Modoboa should connect to your LDAP server. They are described just below:
AUTH_LDAP_SERVER_URI = "ldap://<ldap server address>"
AUTH_LDAP_BIND_DN = ""
AUTH_LDAP_BIND_PASSWORD = ""
LDAP_USER_BASE = "ou=users,dc=example,dc=com"
LDAP_USER_FILTER = "(mail=%(user)s)"
AUTH_LDAP_USER_SEARCH = LDAPSearch(LDAP_USER_BASE,
ldap.SCOPE_SUBTREE, LDAP_USER_FILTER)
+--------------------+--------------------+--------------------+
|Name |Description |Default value |
+====================+====================+====================+
|Server address |The IP address of |localhost |
| |the DNS name of the | |
| |LDAP server | |
+--------------------+--------------------+--------------------+
|Server port |The TCP port number |389 |
| |used by the LDAP | |
| |server | |
+--------------------+--------------------+--------------------+
|Use a secure |Use an SSL/TLS |no |
|connection |connection to access| |
| |the LDAP server | |
+--------------------+--------------------+--------------------+
|Authentication |Choose the |Direct bind |
|method |authentication | |
| |method to use | |
+--------------------+--------------------+--------------------+
|User DN template |The template used to| |
| |construct a user's | |
| |DN. It should | |
| |contain one | |
| |placeholder | |
| |(ie. ``%(user)s``) | |
+--------------------+--------------------+--------------------+
|Password attribute |The attribute used |userPassword |
| |to store user | |
| |passwords | |
+--------------------+--------------------+--------------------+
|Active Directory |Tell if the LDAP |no |
| |server is an Active | |
| |Directory one | |
+--------------------+--------------------+--------------------+
AUTH_LDAP_USER_ATTR_MAP = {
"first_name": "givenName",
"email": "mail",
"last_name": "sn"
}
You will find a detailled documentation `here
<http://packages.python.org/django-auth-ldap/>`_.
Finally, go to *Modoboa > Parameters > admin*, set the
``AUTHENTICATION_TYPE`` parameter to ``LDAP`` and click on the *Save*
blue button.
If you need additional parameters, you will find a detailled
documentation `here <http://packages.python.org/django-auth-ldap/>`_.
Once the authentication is properly configured, the users defined in
your LDAP directory will be able to connect to *Modoboa*, the associated
@@ -223,13 +259,3 @@ Modoboa.
email address change for example). Currently, the only solution is
to manually delete the Modoboa record, it will be recreated on the
next user login.
Available settings
------------------
* ``LDAP_USER_BASE`` : the distinguish name of the search base
* ``LDAP_USER_FILTER`` : the filter used to retrieve users distinguish name
* ``LDAP_PASSWORD_ATTR`` : the attribute used to store the password
(default: ``userPassword``)
* ``LDAP_ACTIVE_DIRECTORY`` : used to indicate if your directory is an
Active Directory one (default: ``False``)
doc/getting_started/install.rst
-27
View File
@@ -73,9 +73,6 @@ sure your database is using UTF8 as a default charset.
Deployment
**********
Automatic
=========
`modoboa-admin.py`, a command line tool, let you deploy a
*ready-to-use* Modoboa site using only one instruction::
@@ -89,35 +86,11 @@ Just answer the few questions and you're done. You can now go to the
The `--with-amavis` option must be set only if you intend to use
the :ref:`amavis_frontend`.
Manual
======
As Modoboa is a set of Django applications, you need to create a new
project. Just run the following commands::
$ cd /var/www
$ django-admin.py startproject modoboa_example
$ cd modoboa_example
$ rm settings.py
$ rm urls.py
$ wget http://modoboa.org/resources/settings.py
$ wget http://modoboa.org/resources/urls.py
$ mkdir media
Then, edit the freshly downloaded *settings.py* file and adjust the
database relative information. (see :ref:`database`).
.. note::
If you plan to serve Modoboa using a URL prefix, you must change the
value of the ``LOGIN_URL`` parameter to ``LOGIN_URL = '/<prefix>/accounts/login/'``.
Finally, run the following commands::
$ python manage.py collectstatic
$ python manage.py syncdb --migrate --noinput
$ python manage.py loaddata initial_users.json
.. _first_use:
*********
doc/getting_started/plugins.rst
+119 -46
View File
@@ -23,12 +23,15 @@ This plugin offers a way to define limits about how many objects
(aliases, mailboxes) a domain administrator can create.
It also brings a new administrative role: ``Reseller``. A reseller is a domain
administrator that can also manipulates domains and assign permissions
administrator that can also manipulate domains and assign permissions
to domain administrators.
If you don't want to limit a particular object type, just set the
associated value to -1.
Default limits applied to new administrators can be changed through
the *Modoboa > Parameters > Limits* page.
.. _amavis_frontend:
********************
@@ -44,6 +47,7 @@ This plugin provides a simple management frontend for `amavisd-new
will handle traffic
.. note::
The per-domain policies feature only works for new
installations. Currently, you can't use modoboa with an existing
database (ie. with data in *users* and *policies* tables).
@@ -124,17 +128,24 @@ the network.
Once *amavisd-new* is configured, just tell Modoboa where it can find
the *release server* by modifying the following parameters in the
online panel::
online 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
+--------------------+--------------------+------------------------+
|Name |Description |Default value |
+====================+====================+========================+
|Amavis connection |Mode used to access |unix |
|mode |the PDP server | |
+--------------------+--------------------+------------------------+
|PDP server address |PDP server address |localhost |
| |(if inet mode) | |
+--------------------+--------------------+------------------------+
|PDP server port |PDP server port (if | |
| |inet mode) 9998 | |
+--------------------+--------------------+------------------------+
|PDP server socket |Path to the PDP |/var/amavis/amavisd.sock|
| |server socket (if | |
| |unix mode) | |
+--------------------+--------------------+------------------------+
Deferred release
----------------
@@ -155,8 +166,26 @@ You are free to change the frequency.
.. note::
If you want to let users release their messages alone (not
recommended), change the value of the ``USER_CAN_RELEASE`` parameter
into the admin panel.
recommended), go to the admin panel.
The following parameters are available to let you customize this
feature:
+--------------------+--------------------+------------------------+
|Name |Description |Default value |
+====================+====================+========================+
|Check requests |Interval between two|30 |
|interval |release requests | |
| |checks | |
+--------------------+--------------------+------------------------+
|Allow direct release|Allow users to |no |
| |directly release | |
| |their messages | |
+--------------------+--------------------+------------------------+
|Notifications sender|The e-mail address |notification@modoboa.org|
| |used to send | |
| |notitications | |
+--------------------+--------------------+------------------------+
.. _selfservice:
@@ -181,7 +210,7 @@ notification (one per message) must embark a direct link containing
the required identifiers.
To activate this feature, go the administration panel and set the
``SELF_SERVICE`` paramater to yes.
**Enable self-service mode** parameter to yes.
The last step is to customize the notification messages *amavis*
sends. The most important is to embark a direct link. Take a look at
@@ -204,20 +233,27 @@ files (see `rrdtool <http://oss.oetiker.ch/rrdtool/>`_)and then
generates graphics in PNG format.
To use it, go to the online parameters panel and adapt the following
ones to your environnement::
ones to your environnement:
# Path to mail log file
LOGFILE = "/var/log/mail.log"
+--------------------+--------------------+--------------------------+
|Name |Description |Default value |
+====================+====================+==========================+
|Path to the log file|Path to log file |/var/log/mail.log |
| |used to collect | |
| |statistics | |
+--------------------+--------------------+--------------------------+
|Directory to store |Path to directory |/tmp/modoboa |
|RRD files |where RRD files are | |
| |stored | |
+--------------------+--------------------+--------------------------+
|Directory to store |Path to directory |<modoboa_site>/media/stats|
|PNG files |where PNG files are | |
| |stored | |
+--------------------+--------------------+--------------------------+
# Path to directory where rrd files are stored
RRD_ROOTDIR = "/tmp/modoboa"
# Path to directory where png files are stored
IMG_ROOTDIR = "<modoboa_site>/media/stats"
Make sure the directory that will contain RRD files exists
(``RRD_ROOTDIR``). If not, create it before going further. For example
(according to the previous parameters)::
Make sure the directory that will contain RRD files exists. If not,
create it before going further. For example (according to the previous
parameters)::
$ mkdir /tmp/modoboa
@@ -279,8 +315,8 @@ few questions and you're done.
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 online panel.
(86400s), you can adjust this value by modifying the **Automatic
reply timeout** parameter available in the online panel.
*************
Sieve filters
@@ -306,13 +342,25 @@ language. Don't panic, *Dovecot* supports both :-) (refer to
activated and configured.
Go the online panel and modify the following parameters in order to
communicate with the *ManageSieve* server (default values are displayed
below)::
communicate with the *ManageSieve* server:
SERVER = localhost
PORT = 2000
STARTTLS = no
AUTHENTICATION_MECH = plain
+--------------------+--------------------+--------------------+
|Name |Description |Default value |
+====================+====================+====================+
|Server address |Address of your |127.0.0.1 |
| |MANAGESIEVE server | |
+--------------------+--------------------+--------------------+
|Server port |Listening port of |4190 |
| |your MANAGESIEVE | |
| |server | |
+--------------------+--------------------+--------------------+
|Connect using |Use the STARTTLS |no |
|STARTTLS |extension | |
+--------------------+--------------------+--------------------+
|Authentication |Prefered |auto |
|mechanism |authentication | |
| |mechanism | |
+--------------------+--------------------+--------------------+
.. _webmail:
@@ -329,21 +377,46 @@ Modoboa provides a simple webmail:
* Quota display
To use it, go to the online panel and modify the following parameters
in order to communicate with your *IMAP* and *SMTP* servers (default
values are displayed below)::
to communicate with your *IMAP* server (under *IMAP settings*):
IMAP_SECURED = no
IMAP_SERVER = 127.0.0.1
IMAP_PORT = 143
+--------------------+--------------------+--------------------+
|Name |Description |Default value |
+====================+====================+====================+
|Server address |Address of your IMAP|127.0.0.1 |
| |server | |
+--------------------+--------------------+--------------------+
|Use a secured |Use a secured |no |
|connection |connection to access| |
| |IMAP server | |
+--------------------+--------------------+--------------------+
|Server port |Listening port of |143 |
| |your IMAP server | |
+--------------------+--------------------+--------------------+
SMTP_SECURED_MODE = None
SMTP_AUTHENTICATION = no
SMTP_SERVER = 127.0.0.1
SMTP_PORT = 25
Do the same to communicate with your SMTP server (under *SMTP settings*):
The size of each attachment sent with messages is limited. You can
change the default value by modifying the ``MAX_ATTACHMENT_SIZE``
parameter.
+--------------------+--------------------+--------------------+
|Name |Description |Default value |
+====================+====================+====================+
|Server address |Address of your SMTP|127.0.0.1 |
| |server | |
+--------------------+--------------------+--------------------+
|Secured connection |Use a secured |None |
|mode |connection to access| |
| |SMTP server | |
+--------------------+--------------------+--------------------+
|Server port |Listening port of |25 |
| |your SMTP server | |
+--------------------+--------------------+--------------------+
|Authentication |Server needs |no |
|required |authentication | |
+--------------------+--------------------+--------------------+
.. note::
The size of each attachment sent with messages is limited. You can
change the default value by modifying the **Maximum attachment
size** parameter.
Using CKeditor
==============
doc/getting_started/upgrade.rst
+3
View File
@@ -33,6 +33,9 @@ Finally, refer to this page to check if the version you're installing
requires specific operations. If the version you're looking for is not
present, it means nothing special is required.
1.0.0: production ready, at last
================================
0.9.4: administrative panel performance improved
================================================
doc/index.rst
+1 -2
View File
@@ -27,8 +27,7 @@ Integration with other softwares
.. toctree::
:maxdepth: 2
integration/smtp_servers
integration/imap_servers
integration/imap_and_smtp
integration/web_servers
*****************
doc/integration/imap_servers.rst
-146
View File
@@ -1,146 +0,0 @@
############
IMAP servers
############
.. _dovecot:
*******
Dovecot
*******
If you are using the *maildir* format to store mailboxes, add the
following line into Dovecot's main config file
(*/etc/dovecot/dovecot.conf*)::
mail_location = maildir:<path_to_mailboxes>/%h/.maildir
The ``.maildir`` part is the previous example must match the value of
the ``MAILDIR_ROOT`` parameter. See :ref:`admin-params`.
If you are using the mbox format, add the following::
mail_location = mbox:<path_to_mailboxes>/%h/:INBOX=<path_to_mailboxes>/%h/Inbox
To make the authentication work, edit *dovecot.conf* and add the
following content 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
}
Make sure to activate only one backend (per type) inside your configuration
(just comment the other ones).
For *MySQL* users, 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 = CRYPT
password_query = SELECT email AS user, password FROM admin_user WHERE email='%u' and is_active=1
user_query = SELECT concat(dom.name, '/', mb.path) AS home, uid, gid FROM admin_mailbox mb INNER JOIN admin_user user ON mb.user_id=user.id INNER JOIN admin_domain dom ON mb.domain_id=dom.id WHERE mb.address='%n' AND dom.name='%d' AND user.is_active=1 AND dom.enabled=1
Enable quota support
====================
Put the following lines inside the *dovecot.conf* file::
protocol imap {
mail_plugins = quota imap_quota
}
Before continuing, you need to know which quota backend must be used
(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
}
For *MySQL* users, modify the above query inside *dovecot-sql.conf* as
follow to activate per-user quotas::
user_query = SELECT concat(dom.name, '/', mb.path) AS home, uid, gid, concat('<backend>:storage=', mb.quota / 1024) AS quota FROM admin_mailbox mb INNER JOIN admin_domain dom ON mb.domain_id=dom.id WHERE mb.address='%n' AND dom.name='%d'
For version >= 1.1, put the following configuration inside the *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
}
For *MySQL* users, modify the above query inside *dovecot-sql.conf* to
activate per-user quotas::
user_query = SELECT concat(dom.name, '/', mb.path) AS home, uid, gid, concat('*:storage=', mb.quota, 'M') AS quota_rule FROM admin_mailbox mb INNER JOIN admin_domain dom ON mb.domain_id=dom.id WHERE mb.address='%n' AND dom.name='%d'
Enable ManageSieve/Sieve support
================================
.. note::
The following configuration example should work with versions
1.X. For versions >= 2, please refer to `Dovecot's wiki
<http://wiki2.dovecot.org/>`_.
Edit the */etc/dovecot/dovecot.conf* file and make the following
modifications:
* Add ``managesieve`` to the ``protocols`` variable::
protocols = imap imaps managesieve
* Uncomment the ``managesieve`` section::
protocol managesieve {
# ...
}
* Configure the ``lda`` protocol as follow::
protocol lda {
postmaster_address = postmaster@<your domain>
mail_plugins = sieve # + your other plugins
# ...
}
* In the ``plugin`` section, uncomment the following content::
plugin {
# stuff before
# Location of the active script. When ManageSieve is used this is actually
# a symlink pointing to the active script in the sieve storage directory.
sieve=~/.dovecot.sieve
#
# The path to the directory where the personal Sieve scripts are stored. For
# ManageSieve this is where the uploaded scripts are stored.
sieve_dir=~/sieve
}
Restart *Dovecot*.
.. note::
If you're using *Postfix* as MTA, you have to use *Dovecot*'s local
delivery agent otherwise your emails won't get filtered. See
:ref:`dovecot_lda` to get information on how to activate it.
doc/integration/smtp_servers.rst
-162
View File
@@ -1,162 +0,0 @@
############
SMTP servers
############
.. _postfix:
*******
Postfix
*******
This section gives an example about building a simple virtual hosting
configuration with *Postfix*. Refer to the `official documentation
<http://www.postfix.org/VIRTUAL_README.html>`_ for more explanation.
Map files
=========
You first need to create configuration files (or map files) that will
be used by *postfix* to lookup into Modoboa tables.
Automatic generation
--------------------
To automaticaly generate the requested map files and store them in a
directory, run the following command::
$ modoboa-admin.py postfix_maps --dbtype <mysql|postgres> mapfiles
`mapfiles` is the directory where the files will be stored. Answer the
few questions and you're done.
.. _manual_map_files:
Manual generation
-----------------
.. note::
The SQL queries presented below are working only with MySQL
only. To make them work with PostgreSQL, just replace (when needed)
the `concat` function call by the standard concatenation operator
(ie. `||`).
Define the following map files on your server (it 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-domain-aliases.cf``::
user = <user>
password = <password>
dbname = <database>
hosts = 127.0.0.1
query = SELECT dom.name FROM admin_domain dom INNER JOIN admin_domainalias domal ON dom.id=domal.target_id WHERE domal.name='%s' AND domal.enabled=1 AND dom.enabled=1
``/etc/postfix/sql-mailboxes.cf``::
user = <user>
password = <password>
dbname = <database>
hosts = 127.0.0.1
query = SELECT concat(dom.name, '/', mb.path, (SELECT value FROM lib_parameter WHERE name='admin.MAILDIR_ROOT'), '/') FROM admin_mailbox mb INNER JOIN admin_domain dom ON mb.domain_id=dom.id INNER JOIN admin_user user ON mb.user_id=user.id WHERE dom.enabled=1 AND dom.name='%d' AND user.is_active=1 AND mb.address='%u'
``/etc/postfix/sql-aliases.cf``::
user = <user>
password = <password>
dbname = <database>
hosts = 127.0.0.1
query = (SELECT concat(mb.address, '@', dom.name) FROM admin_mailbox mb INNER JOIN admin_domain dom ON mb.domain_id=dom.id WHERE mb.id IN (SELECT al_mb.mailbox_id FROM admin_alias_mboxes al_mb INNER JOIN admin_alias al ON al_mb.alias_id=al.id INNER JOIN admin_domain dom ON al.domain_id=dom.id WHERE dom.name='%d' AND dom.enabled=1 AND al.address='%u' AND al.enabled=1)) UNION (SELECT al.extmboxes FROM admin_alias al INNER JOIN admin_domain dom ON al.domain_id=dom.id WHERE dom.name='%d' AND dom.enabled=1 AND al.address='%u' AND al.enabled=1 AND al.extmboxes<>'')
``/etc/postfix/sql-domain-aliases-mailboxes.cf``::
user = <user>
password = <password>
dbname = <database>
hosts = 127.0.0.1
query = SELECT DISTINCT concat(mb.address, '@', dom.name) FROM admin_alias al INNER JOIN admin_domain dom ON dom.id=al.domain_id INNER JOIN admin_domainalias domal ON domal.target_id=dom.id INNER JOIN (admin_alias_mboxes almb, admin_mailbox mb) ON (almb.alias_id=al.id AND almb.mailbox_id=mb.id) WHERE domal.name='%d' AND domal.enabled=1 AND (al.address='%u' OR mb.address='%u')
``/etc/postfix/sql-email2email.cf``::
user = <user>
password = <password>
dbname = <database>
hosts = 127.0.0.1
query = SELECT concat(mb.address, '@', dom.name) FROM admin_mailbox mb INNER JOIN admin_domain dom ON mb.domain_id=dom.id INNER JOIN admin_user user ON mb.user_id=user.id WHERE dom.name='%d' AND dom.enabled=1 AND mb.address='%u' AND user.is_active=1
``/etc/postfix/sql-catchall-aliases.cf``::
user = <user>
password = <password>
dbname = <database>
hosts = 127.0.0.1
query = (SELECT concat(mb.address, '@', dom.name) FROM admin_mailbox mb INNER JOIN admin_domain dom ON mb.domain_id=dom.id WHERE mb.id IN (SELECT al_mb.mailbox_id FROM admin_alias al INNER JOIN admin_domain dom ON al.domain_id=dom.id INNER JOIN admin_alias_mboxes al_mb ON al.id=al_mb.alias_id WHERE al.enabled=1 AND al.address='*' AND dom.name='%d' AND dom.enabled=1)) UNION (SELECT al.extmboxes FROM admin_alias al INNER JOIN admin_domain dom ON al.domain_id=dom.id WHERE al.enabled='1' AND al.extmboxes<>'' AND al.address='*' AND dom.name='%d' AND dom.enabled=1)
Configuration
=============
Use the following configuration in the */etc/postfix/main.cf* file
(this is just one possible configuration)::
# Stuff before
mailbox_transport = virtual
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_alias_domains = mysql:/etc/postfix/sql-domain-aliases.cf
virtual_mailbox_maps = mysql:/etc/postfix/sql-mailboxes.cf
virtual_alias_maps = mysql:/etc/postfix/sql-aliases.cf,
mysql:/etc/postfix/sql-domain-aliases-mailboxes.cf,
mysql:/etc/postfix/sql-email2email.cf,
mysql:/etc/postfix/sql-catchall-aliases.cf
# Stuff after
.. note::
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.
.. _dovecot_lda:
Recommended: using Dovecot's LDA
================================
If you are using *Dovecot* in your environnement, we recommend to use
its LDA. Doing so, you'll will be able to use extra functionalities
such as sieve filters and more.
First, edit the */etc/postfix/main.cf* file and define (or modify if
they already exist) the following parameters::
virtual_transport = dovecot
dovecot_destination_recipient_limit = 1
Then, edit the */etc/postfix/master.cf* file and add the following
definition at the end::
dovecot unix - n n - - pipe
flags=DRhu user=vmail:vmail argv=/usr/lib/dovecot/deliver -f ${sender} -d ${recipient}
If you have followed the :ref:`manual_map_files` section to install your
environnement, you need to modify the SQL query corresponding to the
``virtual_mailbox_maps`` parameter. Edit the
*/etc/postfix/maps/sql-mailboxes.cf* and modify the ``query``
parameter as follow::
query = SELECT concat(dom.name, '/', mb.path) FROM admin_mailbox mb INNER JOIN admin_domain dom ON mb.domain_id=dom.id INNER JOIN admin_user user ON mb.user_id=user.id WHERE dom.enabled=1 AND dom.name='%d' AND user.is_active=1 AND mb.address='%u'
Restart *Postfix*.