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

Documentation update.

Browse Source
This commit is contained in:
Antoine Nguyen
2011-06-23 16:55:25 +02:00
parent f68e17bf51
commit da1cb6888b
3 changed files with 228 additions and 80 deletions
Download Patch File Download Diff File Expand all files Collapse all files
INSTALL
+182 -37
View File
@@ -1,8 +1,8 @@
Installation
============
************
Requirements
------------
============
- Python version 2.6+
- `Django version 1.2+ <http://docs.djangoproject.com/en/dev/intro/install/#intro-install>`_
@@ -15,9 +15,10 @@ For extensions (mandatories since 0.8.2):
- `pycrypto python module <http://www.dlitz.net/software/pycrypto/>`_
- `rrdtool python binding <http://oss.oetiker.ch/rrdtool/>`_
- `ckeditor version 3.4.1+ <http://ckeditor.com/>`_
- `sievelib python module <http://pypi.python.org/pypi/sievelib>`_
How to install
--------------
==============
Download the latest Modoboa's tarball and extract it::
@@ -40,15 +41,15 @@ Initialize the database by running the following command::
$ python manage.py syncdb
It will let you create the default super administrator.
Since version 0.8, Modoboa is using *south* to handle schema
S
ince version 0.8, Modoboa is using *south* to handle schema
migrations. To finish the database initialization, you must
apply existing migrations like this::
$ python manage.py migrate
Time zone and language
^^^^^^^^^^^^^^^^^^^^^^
----------------------
Modoboa is available in english, french, german and spanish. You can choose
which language to use by modifying the ``LANGUAGE_CODE`` variable inside
@@ -67,13 +68,40 @@ variable. For example::
TIME_ZONE = 'Europe/Paris'
.. _default-conf:
Default configuration
---------------------
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::
Where Modoboa stores mailboxes
STORAGE_PATH = /var/vmail
Which user:group Modoboa uses to assign permissions on mailboxes
VIRTUAL_UID = vmail
VIRTUAL_GID = vmail
Which format is used to store messages in a mailbox
MAILBOX_TYPE = maildir
If maildir is in use, tells Modoboa that mailbox content is under a
potential sub-directory
MAILDIR_ROOT = .maildir
Which encryption method is used to store passwords
PASSWORD_SCHEME = crypt
Host configuration
^^^^^^^^^^^^^^^^^^
------------------
Before using Modoboa, you must create a group and a user that will be
used to store emails on the host filesystem. There is only one
group/user needed because we are in a virtual hosting configuration
(ie. users with non-UNIX accounts).
(ie. users with non-UNIX accounts). Following examples are based on
default values presented in :ref:`default-conf`.
For example, create a vmail group::
@@ -89,8 +117,24 @@ manipulate directories in vmail's homedir. To do so, edit the
<user_that_runs_modoboa> ALL=(vmail) NOPASSWD: ALL
Secret key used to encrypt passwords in sessions
------------------------------------------------
Since version 0.8.5, the SECRET_KEY parameter was moved from the
``webmail`` plugin to the ``auth`` application. The reason is simple :
multiple plugins need to store the user password in the current
session. This parameter needed to be centralised.
In the *Admin > Configuration*, click on the *Auth* section and modify
the SECRET_KEY parameter. Choose a new value (exactly 16
characters). This key is really important, it is used to
encrypt/decrypt user passwords stored inside sessions.
.. note::
Do not communicate this key to anyone!!
Testing installation
^^^^^^^^^^^^^^^^^^^^
--------------------
As a typical Django application, Modoboa can be tested using a simple web
server. Just run this command to start it::
@@ -98,20 +142,35 @@ server. Just run this command to start it::
$ python manage.py runserver
You will be able to play with Modoboa by looking at
http://<youraddress>:8000/modoboa/admin/.
``http://<youraddress>:8000/modoboa/admin/``.
How to upgrade
--------------
==============
First, decompress the new tarball at the same location than your
current installation. Then, check if the new version you're installing
requires a migration.
**NB: Before executing a schema migration, I recommend that you make a copy of your
existing database.**
.. note::
Before executing a schema/data migration, I recommend that you make
a copy of your existing database.
0.8.5: new "Sieve filters" plugin, improved admin app
------------------------------------------------------
#. Migrate the ``lib`` and ``admin`` applications::
$ python manage.py migrate lib
$ python manage.py migrate admin
#. Add ``modoboa.auth`` and ``modoboa.extensions.sievefilters`` to the
``INSTALLED_APPS`` variable in *settings.py*.
#. Go the *Settings/Extensions* panel, deactivate and activate your
extensions, it will update all the symbolic links.
0.8.4: folders manipulation support (webmail) and bugfixes
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
----------------------------------------------------------
#. Update the ``MIDDLEWARE_CLASSES`` variable in *settings.py*::
@@ -145,7 +204,7 @@ existing database.**
)
0.8.3: admin application refactoring and more
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
---------------------------------------------
#. Migrate the *admin* application::
@@ -157,7 +216,7 @@ existing database.**
0.8.2: ckeditor integration and more
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
------------------------------------
#. Migrate the admin applicaton::
@@ -179,7 +238,7 @@ existing database.**
``MIDDLEWARE_CLASSES``.
0.8.1 : project renamed
^^^^^^^^^^^^^^^^^^^^^^^
-----------------------
#. First, rename the *mailng* directory to *modoboa* and copy all the
content from *modoboa-0.8.1* to *modoboa*.
@@ -202,7 +261,7 @@ existing database.**
#. Update your webserver configuration and restart it.
0.8 : SQL migration needed
^^^^^^^^^^^^^^^^^^^^^^^^^^
--------------------------
Before you start the migration, make sure you have updated your
``INSTALLED_APPS`` variable and that it contains at least::
@@ -227,11 +286,11 @@ Finally, run the following commands::
$ python manage.py migrate --all 0001 --fake
$ python manage.py migrate --all 0002
0.7 : Nothing to do
^^^^^^^^^^^^^^^^^^^
0.7 : Nothing to do
-------------------
0.6 : Nothing to do
^^^^^^^^^^^^^^^^^^^
-------------------
Integrating Modoboa with other softwares
========================================
@@ -313,9 +372,10 @@ Then, use the following configuration in the */etc/postfix/main.cf* file
mysql:/etc/postfix/sql-domain-aliases-mailboxes.cf
# Stuff after
NB: Modoboa supports both maildir and mbox formats. You can specify
which format to use by modifying the MAILBOX_TYPE parameter available
in the admin panel.
.. 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.
Optional : 'catchall' aliases
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -449,6 +509,61 @@ activate per-user quotas::
user_query = SELECT concat(t2.name, '/', t1.path) AS home, uid, gid, concat('*:storage=', t1.quota, 'M') AS quota_rule FROM admin_mailbox AS t1, admin_domain AS t2 WHERE t1.domain_id=t2.id AND t1.address='%n' AND t2.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*.
Migrating from other softwares
==============================
PostfixAdmin
------------
Since version 0.8.5, Modoboa provides a simple script to migrate an
existing PostfixAdmin database to a Modoboa one.
How to serve Modoboa behind a webserver
=======================================
@@ -721,14 +836,50 @@ Finally, edit the *autoreply* shell script located inside the
*scripts* directory and change the value of ``BASEDIR``. (just put absolute path
of the directory where Modoboa is installed)
NB: auto-reply messages are just sent one time per sender for a
pre-defined time period. By default, this period is equal to 1 day
(86400s), you can adjust this value by modifying the AUTOREPLY_TIMEOUT
parameter available in the admin panel.
.. note::
Auto-reply messages are just sent one time per sender for a
pre-defined time period. By default, this period is equal to 1 day
(86400s), you can adjust this value by modifying the AUTOREPLY_TIMEOUT
parameter available in the admin panel.
NB: Make sure that both *autoreply* and *autoreply.py* scripts (located
inside the *scripts/postfix_autoreply* directory) have good
permissions (ie. 0755).
.. note::
Make sure that both *autoreply* and *autoreply.py* scripts (located
inside the *scripts/postfix_autoreply* directory) have good
permissions (ie. 0755).
Sieve filters
-------------
Since version 0.8.5, Modoboa provides a plugin to easily create
server-side message filters, using the `sievelib module
<http://pypi.python.org/pypi/sievelib>`_ (which provides Sieve and
ManageSieve clients).
Two working modes are available to users:
* A raw mode: you create filters using the Sieve language directly
(advanced users)
* An assisted mode: you create filters using an intuitive form
To be able to use this plugin, your server 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-label` section if you want to active those
features into Dovecot.
.. note::
The sieve filters plugin requires that the 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
below)::
SERVER = localhost
PORT = 2000
STARTTLS = no
AUTHENTICATION_MECH = plain
Webmail
-------
@@ -757,9 +908,3 @@ order to communicate with your IMAP and SMTP servers::
SMTP_AUTHENTICATION = no
SMTP_SERVER = 127.0.0.1
SMTP_PORT = 25
Last but not least, modify the SECRET_KEY parameter and choose a new
value (exactly 16 characters). This key is really important, it is
used to encrypt/decrypt user passwords stored inside sessions.
Do not communicate this key to anyone!!
doc/index.rst
+1 -1
View File
@@ -9,7 +9,7 @@ Modoboa's documentation!
Contents:
.. toctree::
:maxdepth: 2
:maxdepth: 3
install
plugin_api
doc/plugin_api.rst
+45 -42
View File
@@ -1,23 +1,23 @@
Extending Modoboa
=================
*****************
Introduction
------------
============
Modoboa offers a plugin API to expand its capabilities. The current
implementation provides the following possibilities:
* Expand navigation by adding entry points to your plugin inside the GUI
* Access and modify administrative objects (domains, mailboxes, etc.)
* Register callback actions for specific events
* Expand navigation by adding entry points to your plugin inside the GUI
* Access and modify administrative objects (domains, mailboxes, etc.)
* Register callback actions for specific events
Plugins are nothing more than Django applications with an extra file
called ``main.py``. This file contains a complete description of the
plugin:
* Admin and user parameters
* Registered events
* Custom menu entries
* Admin and user parameters
* Registered events
* Custom menu entries
The communication between both applications is provided by
events. Modoboa offers some kind of hooks to let plugin add custom
@@ -27,14 +27,14 @@ The following subsections describe plugin architecture and explain
how you can create your own plugin.
Adding a custom plugin
----------------------
======================
All Modoboa plugins must be located inside the ``extensions``
directory. To create a new plugin, execute the following steps:
* Run ``python manage.py startapp`` to get some basefiles for your plugin,
* Move the resulting directory inside the ``extensions`` one,
* Create a file called ``main.py`` inside your plugin's directory.
* Run ``python manage.py startapp`` to get some basefiles for your plugin,
* Move the resulting directory inside the ``extensions`` one,
* Create a file called ``main.py`` inside your plugin's directory.
The last file you created (ie. ``main.py``) must follow a specific
structure in order to be interpreted by Modoboa. The following
@@ -84,16 +84,16 @@ same format as other plugins). Eventually, run ``python manage.py
syncdb`` if your plugin provides custom tables.
Events
------
======
Playing with events
^^^^^^^^^^^^^^^^^^^
-------------------
Modoboa provides a simple API to interact with events. It understands
two kinds of events:
* Those that return a value,
* Those that return nothing.
* Those that return a value,
* Those that return nothing.
Listening to a specific event is achieved as follow::
@@ -119,14 +119,14 @@ The parameters are the same as those used with ``register``.
Read further to get a complete list and description of the available events.
UserLogin
^^^^^^^^^
---------
Raised when a user logs in. This event provides a ``request`` argument
that corresponds to the ``Request`` object used inside the associated
view function.
UserLogout
^^^^^^^^^^
__________
Raised when a user logs out. This event provides a ``request`` argument
that corresponds to the ``Request`` object used inside the associated
@@ -135,14 +135,14 @@ view function.
.. _usermenudisplay:
UserMenuDisplay
^^^^^^^^^^^^^^^
---------------
Raised when a user menu is about to be displayed. It provides a
``target`` argument that indicates which menu is being
displayed. Possible values are:
* ``uprefs_menu`` : corresponds to the menu bar available inside the *User preferences* page
* ``top_menu`` : corresponds to the top blue bar
* ``uprefs_menu`` : corresponds to the menu bar available inside the *User preferences* page
* ``top_menu`` : corresponds to the top blue bar
All callbacks that listen to this event must return a list of
dictionnaries (corresponding to menu entries). Each dictionnary must
@@ -154,44 +154,44 @@ contain at least the following keys::
"img" : static_url("your_pic")} # can be set to ""
AdminMenuDisplay
^^^^^^^^^^^^^^^^
----------------
Raised when an admin menu is about to be displayed. It provides a
``target`` argument that indicates which menu is being
displayed. Possible values are:
* ``admin_menu_box`` : corresponds to the menu bar available inside administration pages
* ``top_menu`` : corresponds to the *Admin* dropdown menu located inside the top blue bar
* ``admin_menu_box`` : corresponds to the menu bar available inside administration pages
* ``top_menu`` : corresponds to the *Admin* dropdown menu located inside the top blue bar
See :ref:`usermenudisplay` for a description of what callbacks that
listen to this event must return.
CreateDomain
^^^^^^^^^^^^
------------
Raised when a new domain is created. The new domain object is
available inside the ``dom`` argument.
DeleteDomain
^^^^^^^^^^^^
------------
Raised when an existing domain is about to be deleted. The domain
object is available inside the ``dom`` argument.
CreateMailbox
^^^^^^^^^^^^^
-------------
Raised when a new mailbox is created. The new mailbox object is
available inside the ``mbox`` argument.
DeleteMailbox
^^^^^^^^^^^^^
-------------
Raised when an existing mailbox is about to be deleted. The mailbox
object is available inside the ``mbox`` argument.
ModifyMailbox
^^^^^^^^^^^^^
-------------
Raised when an existing mailbox is modified. The old mailbox and the
new mailbox objects are respectively available inside the ``oldmbox``
@@ -200,7 +200,7 @@ and ``mbox`` arguments.
.. _permsgettables:
PermsGetTables
^^^^^^^^^^^^^^
--------------
Raised when the different permission lists (one per role) are about to
be displayed. The current *User* object is available inside the
@@ -223,7 +223,7 @@ For ``content``, replace *MyPermClass* with the appropriate name.
.. _permsgetclass:
PermsGetClass
^^^^^^^^^^^^^
-------------
Raised to retrieve the class (inheriting from ``Permissions``)
implementing a specific role. This event is used to add or delete or
@@ -234,14 +234,15 @@ Callbacks listening to this event must return the class object
corresponding to the given ``role`` argument.
Parameters
----------
==========
A plugin can declare its own parameters. There are two levels available:
* 'Administration' parameters : used to configure the plugin, editable inside the *Admin > Settings > Parameters* page,
* 'User' parameters : per-user parameters (or preferences), editable inside the *Options > Preferences* page.
* 'Administration' parameters : used to configure the plugin, editable inside the *Admin > Settings > Parameters* page,
* 'User' parameters : per-user parameters (or preferences), editable inside the *Options > Preferences* page.
Playing with parameters
^^^^^^^^^^^^^^^^^^^^^^^
-----------------------
To declare a new administration parameter, use the following function::
@@ -254,10 +255,11 @@ To declare a new user parameter, use the following function::
parameter.register_user(name, **kwargs)
Both functions accept extra arguments listed here:
* ``type`` : parameter's type, possible values are : ``int``, ``string``, ``list``, ``list_yesno``,
* ``deflt`` : default value,
* ``help`` : help text,
* ``values`` : list of possible values if ``type`` is ``list``.
* ``type`` : parameter's type, possible values are : ``int``, ``string``, ``list``, ``list_yesno``,
* ``deflt`` : default value,
* ``help`` : help text,
* ``values`` : list of possible values if ``type`` is ``list``.
To undeclare parameters (for example when a plugin is disabled is
disabled from the interface), use the following function::
@@ -268,14 +270,15 @@ disabled from the interface), use the following function::
directory containing the source code.
Custom permission levels
------------------------
========================
Custom permissions roles can be added to Modoboa. If you to want to
integrate the default permissions panel (*Admin > Permissions*), each
role you add must inherit from the ``Permissions`` (file
``admin/permissions.py``) class and implement all its methods.
See :ref:`permsgettables` and :ref:`permsgetclass` to learn how to
integrate your custom roles.
.. note::
See :ref:`permsgettables` and :ref:`permsgetclass` to learn how to
integrate your custom roles.