diff --git a/INSTALL b/INSTALL index f59679eab..f40314f0b 100644 --- a/INSTALL +++ b/INSTALL @@ -1,8 +1,8 @@ Installation -============ +************ Requirements ------------- +============ - Python version 2.6+ - `Django version 1.2+ `_ @@ -15,9 +15,10 @@ For extensions (mandatories since 0.8.2): - `pycrypto python module `_ - `rrdtool python binding `_ - `ckeditor version 3.4.1+ `_ +- `sievelib python module `_ 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 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://:8000/modoboa/admin/. +``http://: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 + `_. + +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*. + +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 +`_ (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!! diff --git a/doc/index.rst b/doc/index.rst index 076cdfdc7..3d09ec83a 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -9,7 +9,7 @@ Modoboa's documentation! Contents: .. toctree:: - :maxdepth: 2 + :maxdepth: 3 install plugin_api diff --git a/doc/plugin_api.rst b/doc/plugin_api.rst index ab28372b0..5a40e4ec3 100644 --- a/doc/plugin_api.rst +++ b/doc/plugin_api.rst @@ -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.