From 1cf7280b35019d8b649501abdfd7b19e8e8bcfab Mon Sep 17 00:00:00 2001 From: Antoine Nguyen Date: Thu, 30 May 2013 14:08:48 +0200 Subject: [PATCH] Documentation update. --- README.rst | 2 +- doc/conf.py | 4 +- doc/extending/events.rst | 12 ++ doc/getting_started/configuration.rst | 208 +++++++++++++++----------- doc/getting_started/install.rst | 27 ---- doc/getting_started/plugins.rst | 165 ++++++++++++++------ doc/getting_started/upgrade.rst | 3 + doc/index.rst | 3 +- doc/integration/imap_servers.rst | 146 ------------------ doc/integration/smtp_servers.rst | 162 -------------------- 10 files changed, 255 insertions(+), 477 deletions(-) delete mode 100644 doc/integration/imap_servers.rst delete mode 100644 doc/integration/smtp_servers.rst diff --git a/README.rst b/README.rst index 0f9da83d1..5b03e136a 100644 --- a/README.rst +++ b/README.rst @@ -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 diff --git a/doc/conf.py b/doc/conf.py index e601c5eae..cb4be0a42 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -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. diff --git a/doc/extending/events.rst b/doc/extending/events.rst index deadd3f63..48b0570a7 100644 --- a/doc/extending/events.rst +++ b/doc/extending/events.rst @@ -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 ================ diff --git a/doc/getting_started/configuration.rst b/doc/getting_started/configuration.rst index 11f1d1622..d73922261 100644 --- a/doc/getting_started/configuration.rst +++ b/doc/getting_started/configuration.rst @@ -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 `. - 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:: + ALL=() 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:: - - 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://" - 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 -`_. - -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 `_. 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``) diff --git a/doc/getting_started/install.rst b/doc/getting_started/install.rst index 12195a9ec..591ba09b3 100644 --- a/doc/getting_started/install.rst +++ b/doc/getting_started/install.rst @@ -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 = '//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: ********* diff --git a/doc/getting_started/plugins.rst b/doc/getting_started/plugins.rst index 3139e45b2..5fcfcffb6 100644 --- a/doc/getting_started/plugins.rst +++ b/doc/getting_started/plugins.rst @@ -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 `_)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 |/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 = "/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 ============== diff --git a/doc/getting_started/upgrade.rst b/doc/getting_started/upgrade.rst index 589e5c95e..b886d1e21 100644 --- a/doc/getting_started/upgrade.rst +++ b/doc/getting_started/upgrade.rst @@ -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 ================================================ diff --git a/doc/index.rst b/doc/index.rst index bf5ff26bc..f4467b5e4 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -27,8 +27,7 @@ Integration with other softwares .. toctree:: :maxdepth: 2 - integration/smtp_servers - integration/imap_servers + integration/imap_and_smtp integration/web_servers ***************** diff --git a/doc/integration/imap_servers.rst b/doc/integration/imap_servers.rst deleted file mode 100644 index f4cf5c97d..000000000 --- a/doc/integration/imap_servers.rst +++ /dev/null @@ -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:/%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:/%h/:INBOX=/%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= dbname= user= 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 = :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(':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 = :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 - `_. - -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@ - 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. diff --git a/doc/integration/smtp_servers.rst b/doc/integration/smtp_servers.rst deleted file mode 100644 index f139c2d81..000000000 --- a/doc/integration/smtp_servers.rst +++ /dev/null @@ -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 -`_ 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 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 = - password = - dbname = - hosts = 127.0.0.1 - query = SELECT name FROM admin_domain WHERE name='%s' AND enabled=1 - -``/etc/postfix/sql-domain-aliases.cf``:: - - user = - password = - dbname = - 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 = - password = - dbname = - 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 = - password = - dbname = - 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 = - password = - dbname = - 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 = - password = - dbname = - 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 = - password = - dbname = - 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 = - 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_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*.