From c7874c4c97df760b8596f5c53a51ba0ec80942bd Mon Sep 17 00:00:00 2001 From: Antoine Nguyen Date: Wed, 27 Jun 2012 17:05:18 +0200 Subject: [PATCH] Documentation update --- doc/getting_started/configuration.rst | 43 +++++--- doc/getting_started/install.rst | 1 - doc/getting_started/integration.rst | 4 +- doc/getting_started/plugins.rst | 147 ++++++++++++++++---------- 4 files changed, 123 insertions(+), 72 deletions(-) diff --git a/doc/getting_started/configuration.rst b/doc/getting_started/configuration.rst index c72797541..5336e5eb8 100644 --- a/doc/getting_started/configuration.rst +++ b/doc/getting_started/configuration.rst @@ -6,14 +6,28 @@ Configuration Online parameters ***************** -FIXME : present the online panel +Modoboa provides online panels to modify internal parameters. There +are two available levels: -Throught the *Admin > Configuration* panel, you can customize the way -Modoboa stores mailboxes on the filesystem. Here is the list of -editable parameters with their default value:: +* Application level: global parameters, define how the application + behaves. Available at *Modoboa > Parameters* -Administration application -========================== +* User level: per user customization. Available at *User > Settings > + Preferences* + +Regardless level, parameters are displayed using tabs, each tab +corresponding to one application. + +.. _admin-params: + +*admin* application parameters +============================== + +The *admin* application exposes several parameters, mainly to control +how mailboxes are created and how messages are stored on the file +system. + +Default values are presented below:: The authentication type AUTHENTICATION_TYPE = Local @@ -56,7 +70,7 @@ group/user needed because we are in a virtual hosting configuration (ie. users with non-UNIX accounts). The following examples are based on the default values presented in -:ref:`default-conf`. +:ref:`admin-params`. For example, create a vmail group:: @@ -76,11 +90,10 @@ manipulate directories in vmail's homedir. To do so, edit the Time zone and language ********************** -FIXME : per user language +Modoboa is available in english, french, german and spanish. -Modoboa is available in english, french, german and spanish. You can choose -which language to use by modifying the ``LANGUAGE_CODE`` variable inside -*settings.py*:: +To specify the default language to use, edit the *settings.py* file +and modify the ``LANGUAGE_CODE`` variable:: LANGUAGE_CODE = 'en-US' # English # or @@ -90,8 +103,12 @@ which language to use by modifying the ``LANGUAGE_CODE`` variable inside # or LANGUAGE_CODE = 'es-ES' # Spanish -You can also specify your time zone by modifying the ``TIME_ZONE`` -variable. For example:: +.. note:: + + Each user has the possibility to define the language he prefers. + +In the same configuration file, specify the timezone to use by +modifying the ``TIME_ZONE`` variable. For example:: TIME_ZONE = 'Europe/Paris' diff --git a/doc/getting_started/install.rst b/doc/getting_started/install.rst index 0eb4a5d1a..ada6dc093 100644 --- a/doc/getting_started/install.rst +++ b/doc/getting_started/install.rst @@ -11,7 +11,6 @@ Requirements * `Python version 2.6+ `_ * `Django version 1.3+ `_ * `south version 0.7+ `_ -* `ldap python module `_ * `lxml python module `_ * `pycrypto python module `_ * `rrdtool python binding `_ diff --git a/doc/getting_started/integration.rst b/doc/getting_started/integration.rst index d07318530..51fdc29b5 100644 --- a/doc/getting_started/integration.rst +++ b/doc/getting_started/integration.rst @@ -16,9 +16,9 @@ LDAP If you want to use this feature, you must first install those components:: - $ easy_install python-ldap django-auth-ldap + $ pip install python-ldap django-auth-ldap -Then, all you have to do is to modify the `settings.py` file: +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:: diff --git a/doc/getting_started/plugins.rst b/doc/getting_started/plugins.rst index cbbf34cbe..a0bc09375 100644 --- a/doc/getting_started/plugins.rst +++ b/doc/getting_started/plugins.rst @@ -6,42 +6,46 @@ Using plugins Enable or disable a plugin ************************** -Starting with 0.8.2, Modoboa provides an online panel to control -plugins activation: +Modoboa provides an online panel to control plugins activation. You +will find it at *Modoboa > Extensions*. -* To activate a plugin, go to the *admin -> settings -> extensions* page, - check the corresponding box and click on the *Apply* button. -* To deactivate a plugin, go to the *admin -> settings -> extensions* page, - uncheck the corresponding box and click on the *Apply* button. +To activate a plugin, check the corresponding box and click on the +*Apply* button. + +To deactivate a plugin, uncheck the corresponding box and click on the +*Apply* button. **************** Per-admin limits **************** -This extension offers a way to define limits about how many objects +This plugin offers a way to define limits about how many objects (aliases, mailboxes) a domain administrator can create. -It also brings a new role: ``Reseller``. A reseller is a domain +It also brings a new administrative role: ``Reseller``. A reseller is a domain administrator that can also manipulates domains and assign permissions to domain administrators. -If you don't want to limit particular object type, just set the +If you don't want to limit a particular object type, just set the associated value to -1. ******************** Amavisd-new frontend ******************** -This plugin provides a simple management frontend for -*amavisd-new*. The supported features are: +This plugin provides a simple management frontend for `amavisd-new +`_. The supported features are: * SQL quarantine management : available to administrators or users, possibility to delete or release messages * Per domain customization (using policies): specify how amavisd-new will handle traffic -To use it, you first need to specify where the database that contains the -quarantine is. Inside *settings.py*, add a new connection to the +Database +======== + +You must specify to Modoboa where it can find the amavis +database. Inside *settings.py*, add a new connection to the ``DATABASES`` variable like this:: DATABASES = { @@ -58,10 +62,29 @@ quarantine is. Inside *settings.py*, add a new connection to the Replace values between ``<>`` with yours. -To be able to release messages, first take a look at `this page +Cleanup +------- + +Storing quarantined messages to a database can quickly become a +perfomance killer. Modoboa provides a simple script to periodically +purge the quarantine database. To use it, add the following line +inside root's crontab:: + + 0 0 * * * /manage.py qcleanup + +Replace ``modoboa_site`` with the path of your Modoboa instance. + +By default, messages older than 14 days are automatically purged. You +can modify this value by changing the ``MAX_MESSAGES_AGE`` parameter +in the online panel. + +Release messages +================ + +To release messages, first take a look at `this page `_. It explains how to configure *amavisd-new* to listen somewhere for the -AM.PDP protocol. This protocol is used to send release requests. +AM.PDP protocol. This protocol is used to send requests. Below is an example of a working configuration:: @@ -82,7 +105,7 @@ the network. Once *amavisd-new* is configured, just tell Modoboa where it can find the *release server* by modifying the following parameters in the -admin panel:: +online panel:: # "unix" or "inet" AM_PDP_MODE = "inet" @@ -94,6 +117,9 @@ admin panel:: AM_PDP_HOST = "127.0.0.1" AM_PDP_PORT = 9998 +Deferred release +---------------- + By default, simple users are not allowed to release messages themselves. They are only allowed to send release requests to administrators. @@ -107,31 +133,29 @@ example line to root's crontab:: You are free to change the frequency. -If you want to let users release their messages alone (not -recommanded), change the value of the ``USER_CAN_RELEASE`` parameter -into the admin panel. +***************** +Self-service mode +***************** -Last step: Modoboa provides a simple script that periodically purges -the quarantine database. To use it, add the following line inside -root's crontab:: +TBD - 0 0 * * * /manage.py qcleanup +.. note:: -Replace ``modoboa_site`` with the path of your Modoboa instance. - -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. + If you want to let users release their messages alone (not + recommanded), change the value of the ``USER_CAN_RELEASE`` parameter + into the admin panel. ******************** Graphical statistics ******************** This plugin collects various statistics about emails traffic on your -server. It parses log file to collect information and then generates -graphics using the PNG format. +server. It parses a log file to collect information, store it into RRD +files (see `rrdtool `_)and then +generates graphics in PNG format. -First, adapt the following parameters to your environnement:: +To use it, go to the online parameters panel and adapt the following +ones to your environnement:: # Path to mail log file LOGFILE = "/var/log/mail.log" @@ -149,12 +173,11 @@ Make sure the directory that will contain RRD files exists $ mkdir /tmp/modoboa To finish, you need to collect information periodically in order to -feed the RRD files. To do so, add the following line into root's -crontab:: +feed the RRD files. Add the following line into root's crontab:: */5 * * * * /manage.py logparser &> /dev/null -Replace ``modoboa_site`` with the path of your Modoboa instance. +Replace ```` with the path of your Modoboa instance. Graphics will be automatically created after each parsing. @@ -162,8 +185,8 @@ Graphics will be automatically created after each parsing. Postifx auto-reply messages *************************** -Allow users to define an auto-reply message. This plugin is based on -*postfix* capabilities. +This plugin let users define an auto-reply message (*vacation*). It is +based on *postfix* capabilities. The user that executes the autoreply script needs to access *settings.py*. You must apply proper permissions on this file. For @@ -187,7 +210,7 @@ configuration files as follow: ```` is the path of your Modoboa instance. -For *MySQL* users, create new map files with the following content: +Then, create new map files with the following content: ``/etc/postfix/maps/sql-transport.cf``:: @@ -209,7 +232,7 @@ For *MySQL* users, create new map files with the following content: 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. + parameter available in the online panel. ************* Sieve filters @@ -225,19 +248,17 @@ Two working modes are available: (advanced users) * An assisted mode: you create filters using an intuitive form -To use this plugin, your hosting setup must include a ManageSieve -server and your IMAP server must support the Sieve language. Don't -panic, Dovecot supports both :-) - -Refer to :ref:`dovecot` section if you want to active those -features into Dovecot. +To use this plugin, your hosting setup must include a *ManageSieve* +server and your local delivery agent must understand the *Sieve* +language. Don't panic, *Dovecot* supports both :-) (refer to +:ref:`dovecot` to know how to enable those features). .. note:: - The sieve filters plugin requires that the webmail plugin is + The sieve filters plugin requires that the :ref:`webmail` plugin is activated and configured. -Go the admin panel and modify plugin's parameters in order to -communicate with the ManageSieve server (default values are displayed +Go the online panel and modify the following parameters in order to +communicate with the *ManageSieve* server (default values are displayed below):: SERVER = localhost @@ -245,16 +266,22 @@ below):: STARTTLS = no AUTHENTICATION_MECH = plain +.. _webmail: + ******* Webmail ******* -Modoboa provides a simple webmail (you can browse, read and compose -messages). With this feature, it is possible to deploy an almost -standalone mail hosting platform just with Modoboa. +Modoboa provides a simple webmail: -To use it, go to the admin panel and modify the following parameters -in order to communicate with your IMAP and SMTP servers (default +* Browse, read and compose messages, attachments are supported +* HTML messages are supported +* `CKeditor `_ integration +* Manipulate mailboxes (create, move, remove) +* 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):: IMAP_SECURED = no @@ -266,7 +293,15 @@ values are displayed below):: SMTP_SERVER = 127.0.0.1 SMTP_PORT = 25 -The webmail supports the sending of attachments with messages. You can -limit the size of each attachment by going to the *Admin > Settings > -Parameters* page. Click on the ``webmail`` tab and modify the value of -the ``MAX_ATTACHMENT_SIZE`` parameter. +The size of each attachment sent with messages is limited. You can +change the default value by modifying the ``MAX_ATTACHMENT_SIZE`` +parameter. + +Using a rich editor +=================== + +CKeditor is supported by Modoboa. To use it, first download it from +`the official website `_, then extract the tarball:: + + $ cd + $