github-jwinterm/modoboa
1
0
Fork 0
mirror of https://github.com/jwinterm/modoboa.git synced 2026-10-20 06:08:35 +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
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
================================================