diff --git a/INSTALL b/INSTALL deleted file mode 100644 index b9304054d..000000000 --- a/INSTALL +++ /dev/null @@ -1,1308 +0,0 @@ -============== - Installation -============== - -Requirements -============ - -- `Python version 2.6+ `_ -- `Django version 1.3+ `_ -- `south version 0.7+ `_ -- `ldap python module `_ - -For extensions (mandatories since 0.8.2): - -- `mysqldb python module `_ -- `lxml python module `_ -- `pycrypto python module `_ -- `rrdtool python binding `_ -- `sievelib python module `_ -- `ckeditor version 3.4.1+ `_ - -.. _howtoinstall: - -How to install -============== - -You can choose between two options to install Modoboa: - -* Use the Python package available on the `PyPI `_ -* Download the sources tarball - -The easiest one is to install it from the *PyPI*. Just run the -following command and you're done:: - - $ pip install modoboa - -If you prefer to use the tarball, download the latest one and run the -following procedure:: - - $ tar xzf modoboa-.tar.gz - $ cd modoboa- - $ python setup.py install - -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 - $ wget http://modoboa.org/resources/settings.py - $ wget http://modoboa.org/resources/urls.py - $ python manage.py collectstatic - $ mkdir media - -Then, edit the freshly downloaded *settings.py* file and adjust the -database relative information. You must choose which backend to use -between *MySQL*, *PostgreSQL* or *sqlite*, other types are not -supported by major email projects like *postfix* or *dovecot*. - -Create a database with the name you specified in *settings.py*. Make -sure your database is using UTF8 as a default charset. If not, you -will surely have problems (with *MySQL* at least). You will probably -need to install a python database backend (like *MySQLdb*). - -Initialize the database by running the following command:: - - $ python manage.py syncdb --migrate --noinput - -At the end of this command, a default super administrator is -available: - -* Username: admin -* Password: password - -It is **strongly** recommanded to change this password the first time -you log into Modoboa. - -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 -*settings.py*:: - - LANGUAGE_CODE = 'en-US' # English - # or - LANGUAGE_CODE = 'fr-FR' # French - # or - LANGUAGE_CODE = 'de-DE' # German - # or - LANGUAGE_CODE = 'es-ES' # Spanish - -You can also specify your time zone by modifying the ``TIME_ZONE`` -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:: - - The authentication type - AUTHENTICATION_TYPE = Local - - Does Modoboa need to handle the creation of directories on the file system? - CREATE_DIRECTORIES = Yes - - 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 - - The encryption method used to store passwords - PASSWORD_SCHEME = crypt - - The number of displayed items per page for listing pages - ITEMS_PER_PAGE = 30 - -Host configuration ------------------- - -.. note:: - - You can skip this part in case you set the ``CREATE_DIRECTORIES`` - parameter to ``No``. - -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). Following examples are based on -default values presented in :ref:`default-conf`. - -For example, create a vmail group:: - - $ 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 - -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:: - - $ python manage.py runserver - -You will be able to play with Modoboa by looking at -``http://:8000/modoboa/admin/``. - -External authentication backend -=============================== - -LDAP ----- - -*Modoboa* supports external LDAP authentication using the following extra components: - -* `Python LDAP client `_ -* `Django LDAP authentication backend `_ - -If you want to use this feature, you must first install those components:: - - $ easy_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:: - - AUTHENTICATION_BACKENDS = ( - 'django_auth_ldap.backend.LDAPBackend', - 'modoboa.lib.authbackends.SimpleBackend', - 'django.contrib.auth.backends.ModelBackend', - ) - -* Set the required parameters to establish the communication with your - LDAP server, for example:: - - import ldap - from django_auth_ldap.config import LDAPSearch - - 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) - -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 -domain and mailboxes will be automatically created if needed. - -Users will also be able to update their LDAP password directly from -Modoboa. - -.. note:: - - Modoboa doesn't provide any synchronization mechanism once a user - is registered into the database. Any modification done from the - directory to a user account will not be reported to Modoboa (an - 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``) - - -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. - -.. note:: - Before executing a schema/data migration, I recommend that you make - a copy of your existing database. - -0.9: global UI refactoring, new *limits* extension and more ------------------------------------------------------------ - -.. note:: - This version requires at least django 1.3. Make sure to update your - version before starting to migrate. - -.. note:: - Many files have been renamed/removed for this version. I recommend - that you backup important files (*settings.py*, etc.) elsewhere - (ie. */tmp* for example). Then, remove the *modoboa* directory, - extract the new tarball at the same place, rename the new directory - to *modoboa* and copy the files you've just backup into it. - -.. note:: - If the first super administrator you created is named ``admin``, - its password will be changed to ``password`` at the end of this - upgrade. Don't forget to modify it! - -#. Edit the *settings.py* file and update the following variables - (just copy/paste their new content):: - - MIDDLEWARE_CLASSES = ( - 'django.middleware.common.CommonMiddleware', - 'django.contrib.sessions.middleware.SessionMiddleware', - 'django.contrib.auth.middleware.AuthenticationMiddleware', - 'django.contrib.messages.middleware.MessageMiddleware', - 'django.middleware.locale.LocaleMiddleware', - 'modoboa.lib.middleware.AjaxLoginRedirect', - 'modoboa.lib.middleware.CommonExceptionCatcher', - 'modoboa.lib.middleware.ExtControlMiddleware', - ) - - AUTHENTICATION_BACKENDS = ( - 'modoboa.lib.authbackends.SimpleBackend', - 'django.contrib.auth.backends.ModelBackend', - ) - -#. Add ``django.contrib.staticfiles`` to ``INSTALLED_APPS`` - -#. Add the following new variables:: - - STATIC_ROOT = os.path.join(MODOBOA_DIR, 'sitestatic') - STATIC_URL = '/sitestatic/' - -#. Update the following variables (just copy/paste their new values):: - - MEDIA_ROOT = os.path.join(MODOBOA_DIR, 'media') - MEDIA_URL = '/media/' - -#. **For MySQL users only**, add the following option to your database - configuration:: - - DATABASES = { - "default" : { - # ... - # MySQL users only - "OPTIONS" : { - "init_command" : "SET foreign_key_checks = 0;", - }, - } - } - -#. Add ``'modoboa.extensions.limits'`` to ``INSTALLED_APPS`` - -#. Update your database (make sure to create a backup before launching - the following command):: - - $ ./manage.py syncdb --migrate - -#. Run the following command to initialize the directory that contains - static files:: - - $ ./manage.py collectstatic - -#. If you are using the *stats* extension, please rename the - */static/stats* directory to */media/stats* - and change the value of the ``IMG_ROOTDIR`` parameter (go to the adminstration panel) - -#. Restart the python instance(s) that serve *Modoboa* - -#. Log into Modoboa, go to *Modoboa > Extensions*, uncheck all - extensions, save. Then, check the extensions you want to use and - save again - -#. Update your webserver configuration to make static files available - (see :ref:`webserver`) - -#. **For Dovecot users only**, you need to modify the - ``password_query`` (file */etc/dovecot/dovecot-sql.conf* by default - on a Debian system) like this:: - - password_query = SELECT email AS user, password FROM auth_user WHERE email='%u' - -0.8.8: CSV import feature and minor fixes ------------------------------------------ - -#. Edit the *settings.py* file and add - ``'modoboa.lib.middleware.AjaxLoginRedirect'`` to the - ``MIDDLEWARE_CLASSES`` variable like this:: - - MIDDLEWARE_CLASSES = ( - 'django.middleware.common.CommonMiddleware', - 'django.contrib.sessions.middleware.SessionMiddleware', - 'django.contrib.auth.middleware.AuthenticationMiddleware', - 'django.contrib.messages.middleware.MessageMiddleware', - 'django.middleware.locale.LocaleMiddleware', - 'modoboa.lib.middleware.AjaxLoginRedirect', - 'modoboa.lib.middleware.ExtControlMiddleware', - 'modoboa.extensions.webmail.middleware.WebmailErrorMiddleware', - ) - -#. Still inside *settings.py*, modify the ``DATABASE_ROUTERS`` - variable like this:: - - DATABASE_ROUTERS = ["modoboa.extensions.amavis_quarantine.dbrouter.AmavisRouter"] - - -0.8.7: per-user language selection ----------------------------------- - -#. Edit the *settings.py* file and add the - ``'django.middleware.locale.LocaleMiddleware'`` middleware to the - ``MIDDLEWARE_CLASSES`` variable like this:: - - MIDDLEWARE_CLASSES = ( - 'django.middleware.common.CommonMiddleware', - 'django.contrib.sessions.middleware.SessionMiddleware', - 'django.contrib.auth.middleware.AuthenticationMiddleware', - 'django.contrib.messages.middleware.MessageMiddleware', - 'django.middleware.locale.LocaleMiddleware', - 'modoboa.lib.middleware.ExtControlMiddleware', - 'modoboa.extensions.webmail.middleware.WebmailErrorMiddleware', - ) - -#. To select a custom language, go to *Options > Preferences* and - select the ``general`` section. Choose a value, save and disconnect - from Modoboa. On the next login, the desired language will be used. - -0.8.6.1: maintenance release ----------------------------- - -#. If you have tried to create a new mailbox and if you have - encountered the following `issue - `_, you must run the - ``dbcleanup.py`` script in order to remove orphan records:: - - $ cd - $ PYTHONPATH=$PWD/.. DJANGO_SETTINGS_MODULE=modoboa.settings ./admin/scripts/dbcleanup.py - -0.8.6: Quarantine plugin refactoring (using Django's ORM) ---------------------------------------------------------- - -#. Just update your configuration if you are using the quarantine - plugin. Open *settings.py*, move the database configuration from - the ``DB_CONNECTIONS`` variable to the ``DATABASES`` variable, like - this:: - - DATABASES = { - "default" : { - # The default database configuration - }, - # ... - "amavis": { - "ENGINE" : "", - "HOST" : "", - "NAME" : "", - "USER" : "", - "PASSWORD" : "" - } - } - -#. Add the new following variable somewhere in the file:: - - DATABASE_ROUTERS = ["modoboa.extensions.amavis_quarantine.dbrouter.AmavisRouter"] - -#. Remove the deprecated ``DB_CONNECTIONS`` variable from *settings.py*. - -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*:: - - MIDDLEWARE_CLASSES = ( - 'django.middleware.common.CommonMiddleware', - 'django.contrib.sessions.middleware.SessionMiddleware', - 'django.contrib.auth.middleware.AuthenticationMiddleware', - 'django.contrib.messages.middleware.MessageMiddleware', - 'modoboa.lib.middleware.ExtControlMiddleware', - 'modoboa.extensions.webmail.middleware.WebmailErrorMiddleware', - ) - -#. Go the *Settings/Extensions* panel, deactivate and activate your - extensions, it will update all the symbolic links to the new format. - -#. Optional: update the ``DATABASES`` and ``TEMPLATE_LOADERS`` - variables in *settings.py* to remove warning messages (appearing with - Django 1.3):: - - DATABASES = { - "default" : { - "ENGINE" : "", - "NAME" : "modoboa", - "USER" : "", - "PASSWORD" : "", - "HOST" : "", - "PORT" : "" - } - } - - TEMPLATE_LOADERS = ( - 'django.template.loaders.filesystem.Loader', - 'django.template.loaders.app_directories.Loader', - ) - -0.8.3: admin application refactoring and more ---------------------------------------------- - -#. Migrate the *admin* application:: - - $ python manage.py migrate admin - -#. Update SQL queries used in your environnement (see - :ref:`postfix-label` or :ref:`dovecot-label`). - -#. Update *postfix* configuration so that it can handle domain aliases - (see :ref:`postfix-label`). - - -0.8.2: ckeditor integration and more ------------------------------------- - -#. Migrate the admin applicaton:: - - $ python manage.py migrate admin - -#. Update your config file and add all extensions to ``INSTALLED_APPS`` - (even those you are not going to use). -#. Inside the */templates/* directory, remove all symbolic links. -#. Download the latest release of ckeditor and extract it into */static/js/*. It should create a new directory named *ckeditor*. -#. Update the following variables inside *settings.py*:: - - MEDIA_ROOT = os.path.join(MODOBOA_DIR, 'static') - MEDIA_URL = '/static/' - -#. Then, add the following variable: ``MODOBOA_WEBPATH = 'modoboa/'`` -#. Delete the following variables: ``STATIC_ROOTDIR`` and - ``TEMPLATE_CONTEXT_PROCESSORS``. -#. Finally, add ``modoboa.lib.middleware.ExtControlMiddleware`` to - ``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*. -#. Edit *settings.py* and replace all occurences of mailng by - modoboa. Make sure you don't modify the ``DATABASE`` section as you're - not going to rename your database. -#. Rename the ``MAILNG_DIR`` variable to ``MODOBOA_DIR``. -#. Add ``'django.contrib.messages.middleware.MessageMiddleware'`` to - ``MIDDLEWARE_CLASSES`` and ``'django.contrib.messages'`` to - ``INSTALLED_APPS``. Save your modifications. -#. Run the following command:: - - $ python manage.py syncdb - -#. For all activated extensions, run the following command:: - - $ export PYTHONPATH=/..= - $ DJANGO_SETTINGS_MODULE=modoboa.settings /scripts/extension.py on - -#. 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:: - - INSTALLED_APPS = ( - # Django's stuff before - - 'south', - 'mailng', - 'mailng.lib', - 'mailng.admin', - 'mailng.userprefs', - ) - -Starting with 0.8, mailng.main doesn't exist anymore. You must remove -it from your ``INSTALLED_APPS``. - -Finally, run the following commands:: - - $ python manage.py syncdb - $ python manage.py convert_to_south - $ python manage.py migrate --all 0001 --fake - $ python manage.py migrate --all 0002 - -0.7 : Nothing to do -------------------- - -0.6 : Nothing to do -------------------- - -Integrating Modoboa with other softwares -======================================== - -.. _postfix-label: - -Postfix -------- - -For *MySQL* users, 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 auth_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 concat(mb.address, '@', dom.name) FROM admin_domain dom INNER JOIN admin_domainalias domal ON dom.id=domal.target_id INNER JOIN admin_mailbox mb ON dom.id=mb.domain_id WHERE domal.name='%d' AND domal.enabled=1 AND mb.address='%u' - -Then, 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 - # 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. - -Optional : 'catchall' aliases -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Modoboa supports 'catchall' aliases creation. In the case you would -like to use this feature, you'll need to add specific queries to -*postfix* configuration. - -First, create the following new maps (*MySQL* users): - -``/etc/postfix/sql-email2email.cf``:: - - user = - password = - dbname = - hosts = 127.0.0.1e - query = SELECT concat(mb.address, '@', dom.name) FROM admin_mailbox mb INNER JOIN admin_domain dom ON mb.domain_id=dom.id INNER JOIN auth_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) - -Once done, edit the *main.cf* configuration file and add the new maps -to the ``virtual_alias_maps`` parameter like this:: - - virtual_alias_maps = mysql:/etc/postfix/sql-aliases.cf, - mysql:/etc/postfix/sql-domain-aliases-mailboxes.cf, - mysql:/etc/postfix/sql-email2email.cf, # new - mysql:/etc/postfix/sql-catchall-aliases.cf # new - -Reload *postfix*. - -.. _dovecot_lda: - -Optional: using Dovecot's LDA -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If you are using *Dovecot* in your environnement, I 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:`postfix-label` 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 auth_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*. - -.. _dovecot-label: - -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:`default-conf`. - -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 auth_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 auth_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 quotas 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 will 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 this. - -Migrating from other softwares -============================== - -PostfixAdmin ------------- - -Since version 0.8.5, Modoboa provides a simple script to migrate an -existing `PostfixAdmin (version 2.3.3+) -`_ database to a Modoboa one. - -.. note:: - This script is only suitable for a new installation. - -First, you must follow the :ref:`howtoinstall` step to create a fresh -Modoboa database. - -Once done, edit the *setting.py* file. First, add a new database -connection named ``pfxadmin`` into the ``DATABASES`` variable -corresponding to your PostfixAdmin setup:: - - DATABASES = { - "default" : { - # default connection definition - }, - "pfxadmin" : { - "ENGINE" : "", - "NAME" : "", - "USER" : "", - "PASSWORD" : "", - } - } - -This connection should correspond to the one defined in PostfixAdmin's -configuration file. - -You are now ready to start the migration. Enter Modoboa's root -directory and execute the following command:: - - $ PYTHONPATH=$PWD/.. DJANGO_SETTINGS_MODULE=modoboa.settings \ - ./tools/pfxadmin_migrate/migrate.py -r -p - -Depending on how many domains/mailboxes your existing setup contains, -the migration can be long. Just wait for the script's ending. - -Once the migration has succeed, go the *Admin > Configuration* panel, -click on the *admin* row and modify the value of ``MAILDIR_ROOT`` as -follow:: - - MAILDIR_ROOT = - -The corresponding field must be empty. Don't touch other fields except -``PASSWORD_SCHEME``, if needed. (set it to the same method as the one -used by PostfixAdmin, check its configuration file if you're not sure) - -Click on the *Save* button. - -The procedure is over, edit the *settings.py* file and: - -* remove the ``pfxadmin`` database connection from the ``DATABASES`` - variable -* remove the ``'modoboa.tools.pfxadmin_migrate',`` from the - ``INSTALLED_APPS`` variable - -You should be able to connect to Modoboa using the same credentials -you were using to connect to PostfixAdmin. - -.. _webserver: - -How to serve Modoboa behind a webserver -======================================= - -Apache 2 --------- - -First, make sure that both *apache2* and *mod_python* are installed on -your server. - -Create a new virtualhost in your Apache configuration and put the -following inside:: - - - - SetHandler mod_python - PythonHandler django.core.handlers.modpython - PythonPath "[''] + sys.path" - SetEnv DJANGO_SETTINGS_MODULE modoboa.settings - - Alias "/sitestatic" "/sitestatic" - - SetHandler None - - Alias "/media" "/media" - - SetHandler None - - - -This is one possible configuration. Note that you will certainly need more -configuration in order to launch Apache. - -Nginx ------ - -`Nginx `_ is a really fast HTTP server. Associated -with `Green Unicorn `_, it gives you one of the -best setup to serve python/Django applications. Modoboa's -performances are really good with this configuration. - -To use this setup, first download and install those softwares -(`Install gunicorn `_ and `install -nginx `_). - -Then, use the following sample *gunicorn* configuration (create a new -file named *gunicorn.conf.py* inside Modoboa's root dir):: - - backlog = 2048 - bind = "unix:/var/run/gunicorn/modoboa.sock" - pidfile = "/var/run/gunicorn/modoboa.pid" - daemon = True - debug = False - workers = 2 - logfile = "/var/log/gunicorn/modoboa.log" - loglevel = "info" - -To start gunicorn, execute the following commands:: - - $ cd - $ gunicorn_django -c gunicorn.conf.py - -Now the *nginx* part. Just create a new virtual host and use the -following configuration:: - - upstream modoboa { - server unix:/var/run/gunicorn/modoboa.sock fail_timeout=0; - } - - server { - listen 443; - server_name ; - root ; - - access_log /var/log/nginx/.access.log; - error_log /var/log/nginx/.error.log; - - location /sitestatic/ { - autoindex on; - } - - location /media/ { - autoindex on; - } - - location / { - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - proxy_set_header Host $http_host; - proxy_redirect off; - proxy_set_header X-Forwarded-Protocol ssl; - - if (!-f $request_filename) { - proxy_pass http://modoboa; - break; - } - } - } - -Paste this content to your configuration (replace values between -``<>`` with yours), restart *nginx* and enjoy a really fast -application! - -Using default plugins -===================== - -Enable or disable a plugin --------------------------- - -Starting with 0.8.2, Modoboa provides an online panel to control -plugins activation: - -* 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. - -Per-admin limits ----------------- - -This extension 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 -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 -associated value to -1. - -Amavisd-new quarantine ----------------------- - -This plugin allows you and your users to handle *amavisd-new* SQL -quarantine. You can consult messages and/or release or delete them. - -First, you need to specify where the database that contains the -quarantine is. Inside *settings.py*, add a new connection to the -``DATABASES`` variable like this:: - - DATABASES = { - # Stuff before - # - "amavis": { - "ENGINE" : "", - "HOST" : "", - "NAME" : "", - "USER" : "", - "PASSWORD" : "" - } - } - -Replace values between ``<>`` with yours. - -When viewing messages, you can choose to display links (addresses, -images). In order to display images correctly, you need to create a -*tmp* directory under *static/* for storing them. For example:: - - $ mkdir /static/tmp - -To be able 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. - -Below is an example of a working configuration:: - - $interface_policy{'SOCK'} = 'AM.PDP-SOCK'; - $interface_policy{'9998'} = 'AM.PDP-INET'; - - $policy_bank{'AM.PDP-SOCK'} = { - protocol => 'AM.PDP', - auth_required_release => 0, - }; - $policy_bank{'AM.PDP-INET'} = { - protocol => 'AM.PDP', - inet_acl => [qw( 127.0.0.1 [::1] )], - }; - -Don't forget to update the ``inet_acl`` list if you plan to release from -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:: - - # "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 - -Last point, Modoboa provides a simple script that periodically purges -the quarantine database. If you want to use it, you can add the -following line inside root's crontab:: - - 0 0 * * * PYTHONPATH= \ - DJANGO_SETTINGS_MODULE=modoboa.settings \ - /extensions/amavis_quarantine/cleanup.py - -Replace ``modoboa_dir`` with the installation path of Modoboa. - -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. - -Graphical statistics --------------------- - -This plugin allows you to collect various statistics about emails -traffic on your server. It parses log file to collect information and -then generates graphics using the PNG format. - -First, adapt the following parameters to your environnement:: - - # Path to mail log file - LOGFILE = "/var/log/mail.log" - - # 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 those files exist. If not, -create it before going further. For example (according to the previous -parameters):: - - $ mkdir /tmp/modoboa - -To finish, you need to collect information periodically in order to -feed the rrd files. To do so, just add the following line into root's -crontab:: - - */5 * * * * PYTHONPATH= DJANGO_SETTINGS_MODULE=modoboa.settings /scripts/stats/logparser.py - -Replace ``modoboa_dir`` with the installation path of Modoboa. - -Graphics will be automatically created after each parsing. - -Postifx auto-reply messages ---------------------------- - -Since version 0.6, mail users can define an auto-reply message with Modoboa. - -Then run the following commands to update Modoboa SQL schema and content:: - - $ python manage.py syncdb - $ python manage.py migrate postfix-autoreply - -The user that executes the autoreply script needs to access -*settings.py*. You must apply proper permissions on this file. For -example, if *settings.py* belongs to *www-data:www-data*, you can add the -*vmail* user to the *www-data* group and set the read permission for the -group. - -To make Postfix understand this feature, you need to update your configuration -files as follow: - -``/etc/postfix/main.cf``:: - - transport_maps = mysql:/etc/postfix/maps/sql-transport.cf - virtual_alias_maps = mysql:/etc/postfix/maps/sql-aliases.cf - mysql:/etc/postfix/maps/sql-autoreplies.cf - -``/etc/postfix/master.cf``:: - - autoreply unix - n n - - pipe - flags= user=vmail: argv=/scripts/postfix_autoreply/autoreply $sender $mailbox - -For *MySQL* users, create new map files with the following content: - -``/etc/postfix/maps/sql-transport.cf``:: - - user = - password = - dbname = - hosts = 127.0.0.1 - query = SELECT method FROM postfix_autoreply_transport WHERE domain='%s' - -``/etc/postfix/maps/sql-autoreplies.cf``:: - - user = - password = - dbname = - hosts = 127.0.0.1 - query = SELECT full_address, autoreply_address FROM postfix_autoreply_alias WHERE full_address='%s' - -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) - -.. 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. - -.. 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 -------- - -Modoboa provides a simple webmail component (you can browse, read and -compose messages). With this feature, it is possible to deploy an almost -standalone emails platform just with Modoboa. - -Sometimes, inline images are integrated inside emails. To display -them, Modoboa stores images into a temporary directory. Make sure the -following path exists. If not, create it:: - - $ mkdir /static/tmp - -The user that is running Modoboa will need the write permission inside -this directory. - -Next, go to the admin panel and modify the following parameters in -order to communicate with your IMAP and SMTP servers:: - - IMAP_SECURED = no - IMAP_SERVER = 127.0.0.1 - IMAP_PORT = 143 - - SMTP_SECURED = no - SMTP_AUTHENTICATION = no - SMTP_SERVER = 127.0.0.1 - SMTP_PORT = 25 - -Since version 0.8.7, 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`` -section and modify the value of the ``MAX_ATTACHMENT_SIZE`` parameter. diff --git a/MANIFEST.in b/MANIFEST.in index 6eb4f194b..e43a860b2 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1,3 +1,3 @@ -include INSTALL COPYING requirements.txt +include README.rst COPYING requirements.txt recursive-include modoboa *.html *.js *.css *.png *.po recursive-include doc * \ No newline at end of file diff --git a/README b/README deleted file mode 100644 index 70da757d7..000000000 --- a/README +++ /dev/null @@ -1,21 +0,0 @@ -Modoboa is a light web messaging solution. It provides different tools that -facilitate virtual domains hosting. It is designed to be integrated with email -servers like postfix (http://www.postfix.org/) and/or dovecot -(http://www.dovecot.org/). - -Available components: - * Administration panel, - * Amavisd-new quarantine manager, - * Postfix auto-reply component, - * Graphical statistics about emails traffic, - * webmail, - * Per-user SIEVE filters. - -Django is needed to use Modoboa (http://www.djangoproject.com/) - -The following external tools are provided with Modoboa: - * jQuery version 1.7.1 (http://www.jquery.org/) - * jQuery-UI 1.8+ (http://jqueryui.com/) - * Bootstrap, from Twitter version 2.0.3 (http://twitter.github.com/bootstrap/) - * Bootstrap datepicker (https://bitbucket.org/eternicode/bootstrap-datepicker) - diff --git a/README.rst b/README.rst new file mode 100644 index 000000000..f291d636d --- /dev/null +++ b/README.rst @@ -0,0 +1,50 @@ +####### +Modoboa +####### + +Modoboa is a mail hosting and management platform including a modern +and simplified Web User Interface. It provides useful components such +as an administration panel or a webmail. + +Modoboa integrates with well known software such as `Postfix +`_ or `Dovecot `_. A SQL +database (`MySQL `_, `PostgreSQL +`_ or `SQLite `_) +is used as a central point of communication between all components. + +Modoboa is developed with modularity in mind, expanding it is really +easy. Actually, all current features are extensions. + +It is written in Python and uses the `Django +`_, `jQuery `_ and +`Bootstap, from Twitter `_ +frameworks. + +************* +Main features +************* + + * Administration panel + * `Amavisd-new `_ frontend + * Webmail + * Per-user Sieve filters + * Autoreply messages for Postfix + * Graphical statistics about emails traffic + +************* +Documentation +************* + +A detailled `documentation `_ will help you +to install, use or extend Modoboa. + +************* +External code +************* + +The following external libraries are provided with Modoboa: + + * jQuery version 1.7.1 (http://www.jquery.org/) + * jQuery-UI 1.8+ (http://jqueryui.com/) + * Bootstrap, from Twitter version 2.0.3 (http://twitter.github.com/bootstrap/) + * Bootstrap datepicker (https://bitbucket.org/eternicode/bootstrap-datepicker) diff --git a/doc/additional/migrating.rst b/doc/additional/migrating.rst new file mode 100644 index 000000000..beaaa66c1 --- /dev/null +++ b/doc/additional/migrating.rst @@ -0,0 +1,67 @@ +############################# +Migrating from other software +############################# + +************ +PostfixAdmin +************ + +Since version 0.8.5, Modoboa provides a simple script to migrate an +existing `PostfixAdmin (version 2.3.3+) +`_ database to a Modoboa one. + +.. note:: + This script is only suitable for a new installation. + +First, you must follow the :ref:`installation` step to create a fresh +Modoboa database. + +Once done, edit the *setting.py* file. First, add a new database +connection named ``pfxadmin`` into the ``DATABASES`` variable +corresponding to your PostfixAdmin setup:: + + DATABASES = { + "default" : { + # default connection definition + }, + "pfxadmin" : { + "ENGINE" : "", + "NAME" : "", + "USER" : "", + "PASSWORD" : "", + } + } + +This connection should correspond to the one defined in PostfixAdmin's +configuration file. + +You are now ready to start the migration. Enter Modoboa's root +directory and execute the following command:: + + $ PYTHONPATH=$PWD/.. DJANGO_SETTINGS_MODULE=modoboa.settings \ + ./tools/pfxadmin_migrate/migrate.py -r -p + +Depending on how many domains/mailboxes your existing setup contains, +the migration can be long. Just wait for the script's ending. + +Once the migration has succeed, go the *Admin > Configuration* panel, +click on the *admin* row and modify the value of ``MAILDIR_ROOT`` as +follow:: + + MAILDIR_ROOT = + +The corresponding field must be empty. Don't touch other fields except +``PASSWORD_SCHEME``, if needed. (set it to the same method as the one +used by PostfixAdmin, check its configuration file if you're not sure) + +Click on the *Save* button. + +The procedure is over, edit the *settings.py* file and: + +* remove the ``pfxadmin`` database connection from the ``DATABASES`` + variable +* remove the ``'modoboa.tools.pfxadmin_migrate',`` from the + ``INSTALLED_APPS`` variable + +You should be able to connect to Modoboa using the same credentials +you were using to connect to PostfixAdmin. diff --git a/doc/virtualmachine.rst b/doc/additional/virtualmachine.rst similarity index 100% rename from doc/virtualmachine.rst rename to doc/additional/virtualmachine.rst diff --git a/doc/additional/webserver.rst b/doc/additional/webserver.rst new file mode 100644 index 000000000..a5472cc83 --- /dev/null +++ b/doc/additional/webserver.rst @@ -0,0 +1,105 @@ +.. _webserver: + +####################################### +How to serve Modoboa behind a webserver +####################################### + +******** +Apache 2 +******** + +First, make sure that both *apache2* and *mod_python* are installed on +your server. + +Create a new virtualhost in your Apache configuration and put the +following inside:: + + + + SetHandler mod_python + PythonHandler django.core.handlers.modpython + PythonPath "[''] + sys.path" + SetEnv DJANGO_SETTINGS_MODULE modoboa.settings + + Alias "/sitestatic" "/sitestatic" + + SetHandler None + + Alias "/media" "/media" + + SetHandler None + + + +This is one possible configuration. Note that you will certainly need more +configuration in order to launch Apache. + +***** +Nginx +***** + +`Nginx `_ is a really fast HTTP server. Associated +with `Green Unicorn `_, it gives you one of the +best setup to serve python/Django applications. Modoboa's +performances are really good with this configuration. + +To use this setup, first download and install those softwares +(`Install gunicorn `_ and `install +nginx `_). + +Then, use the following sample *gunicorn* configuration (create a new +file named *gunicorn.conf.py* inside Modoboa's root dir):: + + backlog = 2048 + bind = "unix:/var/run/gunicorn/modoboa.sock" + pidfile = "/var/run/gunicorn/modoboa.pid" + daemon = True + debug = False + workers = 2 + logfile = "/var/log/gunicorn/modoboa.log" + loglevel = "info" + +To start gunicorn, execute the following commands:: + + $ cd + $ gunicorn_django -c gunicorn.conf.py + +Now the *nginx* part. Just create a new virtual host and use the +following configuration:: + + upstream modoboa { + server unix:/var/run/gunicorn/modoboa.sock fail_timeout=0; + } + + server { + listen 443; + server_name ; + root ; + + access_log /var/log/nginx/.access.log; + error_log /var/log/nginx/.error.log; + + location /sitestatic/ { + autoindex on; + } + + location /media/ { + autoindex on; + } + + location / { + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header Host $http_host; + proxy_redirect off; + proxy_set_header X-Forwarded-Protocol ssl; + + if (!-f $request_filename) { + proxy_pass http://modoboa; + break; + } + } + } + +Paste this content to your configuration (replace values between +``<>`` with yours), restart *nginx* and enjoy a really fast +application! diff --git a/doc/conf.py b/doc/conf.py index 5733e4059..a886dcbff 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -48,9 +48,9 @@ copyright = u'2012, Antoine Nguyen' # built documents. # # The short X.Y version. -version = '0.9' +version = '0.9.1' # The full version, including alpha/beta/rc tags. -release = '0.9' +release = '0.9.1' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/doc/plugin_api.rst b/doc/extending/plugin_api.rst similarity index 100% rename from doc/plugin_api.rst rename to doc/extending/plugin_api.rst diff --git a/doc/getting_started/configuration.rst b/doc/getting_started/configuration.rst new file mode 100644 index 000000000..c72797541 --- /dev/null +++ b/doc/getting_started/configuration.rst @@ -0,0 +1,97 @@ +############# +Configuration +############# + +***************** +Online parameters +***************** + +FIXME : present the online panel + +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:: + +Administration application +========================== + + The authentication type + AUTHENTICATION_TYPE = Local + + Does Modoboa need to handle the creation of directories on the file system? + CREATE_DIRECTORIES = Yes + + 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 + + The encryption method used to store passwords + PASSWORD_SCHEME = crypt + + The number of displayed items per page for listing pages + ITEMS_PER_PAGE = 30 + +****************** +Host configuration +****************** + +.. note:: + + This section is only relevant when the ``CREATE_DIRECTORIES`` + parameter is set to ``Yes``. + +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). + +The following examples are based on the default values presented in +:ref:`default-conf`. + +For example, create a vmail group:: + + $ 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 + +********************** +Time zone and language +********************** + +FIXME : per user language + +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*:: + + LANGUAGE_CODE = 'en-US' # English + # or + LANGUAGE_CODE = 'fr-FR' # French + # or + LANGUAGE_CODE = 'de-DE' # German + # or + LANGUAGE_CODE = 'es-ES' # Spanish + +You can also specify your time zone 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 new file mode 100644 index 000000000..0eb4a5d1a --- /dev/null +++ b/doc/getting_started/install.rst @@ -0,0 +1,96 @@ +.. _installation: + +############ +Installation +############ + +************ +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 `_ +* `sievelib python module `_ + +Optional +======== + +* `ckeditor version 3.4.1+ `_ + +*********** +Get Modoboa +*********** + +You can choose between two options: + +* Use the Python package available on the `PyPI `_ +* Download the sources tarball + +The easiest one is to install it from the *PyPI*. Just run the +following command and you're done:: + + $ pip install modoboa + +If you prefer to use the tarball, download the latest one and run the +following procedure:: + + $ tar xzf modoboa-.tar.gz + $ cd modoboa- + $ python setup.py install + +.. _database: + +******** +Database +******** + +Thanks to *django*, Modoboa supports several databases. Depending on +the one you will use, you must install the appropriate python package: + +* `MySQL `_: `mysqldb `_ +* `PostgreSQL `_ : `psycopg2 `_ +* `SQLite `_: already shipped with *Python* + +Then, create a user and a database that will be used by Modoboa. Make +sure your database is using UTF8 as a default charset. + +********** +Deployment +********** + +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 + $ 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 + +At the end of this command, a default super administrator is +available: + +* Username: ``admin`` +* Password: ``password`` + +It is **strongly** recommanded to change this password the first time +you log into Modoboa. diff --git a/doc/getting_started/integration.rst b/doc/getting_started/integration.rst new file mode 100644 index 000000000..d07318530 --- /dev/null +++ b/doc/getting_started/integration.rst @@ -0,0 +1,354 @@ +################################# +Integration with other components +################################# + +*********************** +External authentication +*********************** + +LDAP +==== + +*Modoboa* supports external LDAP authentication using the following extra components: + +* `Python LDAP client `_ +* `Django LDAP authentication backend `_ + +If you want to use this feature, you must first install those components:: + + $ easy_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:: + + AUTHENTICATION_BACKENDS = ( + 'django_auth_ldap.backend.LDAPBackend', + 'modoboa.lib.authbackends.SimpleBackend', + 'django.contrib.auth.backends.ModelBackend', + ) + +* Set the required parameters to establish the communication with your + LDAP server, for example:: + + import ldap + from django_auth_ldap.config import LDAPSearch + + 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) + +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 +domain and mailboxes will be automatically created if needed. + +Users will also be able to update their LDAP password directly from +Modoboa. + +.. note:: + + Modoboa doesn't provide any synchronization mechanism once a user + is registered into the database. Any modification done from the + directory to a user account will not be reported to Modoboa (an + 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``) + +.. _postfix: + +******* +Postfix +******* + +For *MySQL* users, 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 auth_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 concat(mb.address, '@', dom.name) FROM admin_domain dom INNER JOIN admin_domainalias domal ON dom.id=domal.target_id INNER JOIN admin_mailbox mb ON dom.id=mb.domain_id WHERE domal.name='%d' AND domal.enabled=1 AND mb.address='%u' + +Then, 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 + # 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. + +Optional : 'catchall' aliases +============================= + +Modoboa supports 'catchall' aliases creation. In the case you would +like to use this feature, you'll need to add specific queries to +*postfix* configuration. + +First, create the following new maps (*MySQL* users): + +``/etc/postfix/sql-email2email.cf``:: + + user = + password = + dbname = + hosts = 127.0.0.1e + query = SELECT concat(mb.address, '@', dom.name) FROM admin_mailbox mb INNER JOIN admin_domain dom ON mb.domain_id=dom.id INNER JOIN auth_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) + +Once done, edit the *main.cf* configuration file and add the new maps +to the ``virtual_alias_maps`` parameter like this:: + + virtual_alias_maps = mysql:/etc/postfix/sql-aliases.cf, + mysql:/etc/postfix/sql-domain-aliases-mailboxes.cf, + mysql:/etc/postfix/sql-email2email.cf, # new + mysql:/etc/postfix/sql-catchall-aliases.cf # new + +Reload *postfix*. + +.. _dovecot_lda: + +Optional: using Dovecot's LDA +============================= + +If you are using *Dovecot* in your environnement, I 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:`postfix` 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 auth_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*. + +.. _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 auth_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 auth_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 quotas 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 will 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 this. diff --git a/doc/getting_started/plugins.rst b/doc/getting_started/plugins.rst new file mode 100644 index 000000000..cbbf34cbe --- /dev/null +++ b/doc/getting_started/plugins.rst @@ -0,0 +1,272 @@ +############# +Using plugins +############# + +************************** +Enable or disable a plugin +************************** + +Starting with 0.8.2, Modoboa provides an online panel to control +plugins activation: + +* 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. + +**************** +Per-admin limits +**************** + +This extension 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 +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 +associated value to -1. + +******************** +Amavisd-new frontend +******************** + +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 +``DATABASES`` variable like this:: + + DATABASES = { + # Stuff before + # + "amavis": { + "ENGINE" : "", + "HOST" : "", + "NAME" : "", + "USER" : "", + "PASSWORD" : "" + } + } + +Replace values between ``<>`` with yours. + +To be able 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. + +Below is an example of a working configuration:: + + $interface_policy{'SOCK'} = 'AM.PDP-SOCK'; + $interface_policy{'9998'} = 'AM.PDP-INET'; + + $policy_bank{'AM.PDP-SOCK'} = { + protocol => 'AM.PDP', + auth_required_release => 0, + }; + $policy_bank{'AM.PDP-INET'} = { + protocol => 'AM.PDP', + inet_acl => [qw( 127.0.0.1 [::1] )], + }; + +Don't forget to update the ``inet_acl`` list if you plan to release from +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:: + + # "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 + +By default, simple users are not allowed to release messages +themselves. They are only allowed to send release requests to +administrators. + +As administrators are not always available or logged into Modoboa, a +notification tool is available. It sends reminder e-mails to every +administrators or domain administrators. To use it, add the following +example line to root's crontab:: + + 0 12 * * * /manage.py amnotify --baseurl='' + +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. + +Last step: Modoboa provides a simple script that periodically purges +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 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. + +First, adapt the following parameters to your environnement:: + + # Path to mail log file + LOGFILE = "/var/log/mail.log" + + # 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):: + + $ 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:: + + */5 * * * * /manage.py logparser &> /dev/null + +Replace ``modoboa_site`` with the path of your Modoboa instance. + +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. + +The user that executes the autoreply script needs to access +*settings.py*. You must apply proper permissions on this file. For +example, if *settings.py* belongs to *www-data:www-data*, you can add +the *vmail* user to the *www-data* group and set the read permission +for the group. + +To make *postfix* use this feature, you need to update your +configuration files as follow: + +``/etc/postfix/main.cf``:: + + transport_maps = mysql:/etc/postfix/maps/sql-transport.cf + virtual_alias_maps = mysql:/etc/postfix/maps/sql-aliases.cf + mysql:/etc/postfix/maps/sql-autoreplies.cf + +``/etc/postfix/master.cf``:: + + autoreply unix - n n - - pipe + flags= user=vmail: argv=/manage.py autoreply $sender $mailbox + +```` is the path of your Modoboa instance. + +For *MySQL* users, create new map files with the following content: + +``/etc/postfix/maps/sql-transport.cf``:: + + user = + password = + dbname = + hosts = 127.0.0.1 + query = SELECT method FROM postfix_autoreply_transport WHERE domain='%s' + +``/etc/postfix/maps/sql-autoreplies.cf``:: + + user = + password = + dbname = + hosts = 127.0.0.1 + query = SELECT full_address, autoreply_address FROM postfix_autoreply_alias WHERE full_address='%s' + +.. 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. + +************* +Sieve filters +************* + +This plugin let users create server-side message filters, using the +`sievelib module `_ (which +provides Sieve and ManageSieve clients). + +Two working modes are available: + +* A raw mode: you create filters using the Sieve language directly + (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. + +.. 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 +******* + +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. + +To use it, go to the admin panel and modify the following parameters +in order to communicate with your IMAP and SMTP servers (default +values are displayed below):: + + IMAP_SECURED = no + IMAP_SERVER = 127.0.0.1 + IMAP_PORT = 143 + + SMTP_SECURED_MODE = None + SMTP_AUTHENTICATION = no + 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. diff --git a/doc/getting_started/upgrade.rst b/doc/getting_started/upgrade.rst new file mode 100644 index 000000000..e4a195be1 --- /dev/null +++ b/doc/getting_started/upgrade.rst @@ -0,0 +1,339 @@ +################################## +Upgrading an existing installation +################################## + +This section regroups all the upgrade procedures required to use +newest versions of Modoboa. + +************** +Latest version +************** + +FIXME + +************** +Modoboa <= 0.9 +************** + +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. + +.. note:: + Before executing a schema/data migration, I recommend that you make + a copy of your existing database. + +0.9: global UI refactoring, new *limits* extension and more +=========================================================== + +.. note:: + This version requires at least django 1.3. Make sure to update your + version before starting to migrate. + +.. note:: + Many files have been renamed/removed for this version. I recommend + that you backup important files (*settings.py*, etc.) elsewhere + (ie. */tmp* for example). Then, remove the *modoboa* directory, + extract the new tarball at the same place, rename the new directory + to *modoboa* and copy the files you've just backup into it. + +.. note:: + If the first super administrator you created is named ``admin``, + its password will be changed to ``password`` at the end of this + upgrade. Don't forget to modify it! + +#. Edit the *settings.py* file and update the following variables + (just copy/paste their new content):: + + MIDDLEWARE_CLASSES = ( + 'django.middleware.common.CommonMiddleware', + 'django.contrib.sessions.middleware.SessionMiddleware', + 'django.contrib.auth.middleware.AuthenticationMiddleware', + 'django.contrib.messages.middleware.MessageMiddleware', + 'django.middleware.locale.LocaleMiddleware', + 'modoboa.lib.middleware.AjaxLoginRedirect', + 'modoboa.lib.middleware.CommonExceptionCatcher', + 'modoboa.lib.middleware.ExtControlMiddleware', + ) + + AUTHENTICATION_BACKENDS = ( + 'modoboa.lib.authbackends.SimpleBackend', + 'django.contrib.auth.backends.ModelBackend', + ) + +#. Add ``django.contrib.staticfiles`` to ``INSTALLED_APPS`` + +#. Add the following new variables:: + + STATIC_ROOT = os.path.join(MODOBOA_DIR, 'sitestatic') + STATIC_URL = '/sitestatic/' + +#. Update the following variables (just copy/paste their new values):: + + MEDIA_ROOT = os.path.join(MODOBOA_DIR, 'media') + MEDIA_URL = '/media/' + +#. **For MySQL users only**, add the following option to your database + configuration:: + + DATABASES = { + "default" : { + # ... + # MySQL users only + "OPTIONS" : { + "init_command" : "SET foreign_key_checks = 0;", + }, + } + } + +#. Add ``'modoboa.extensions.limits'`` to ``INSTALLED_APPS`` + +#. Update your database (make sure to create a backup before launching + the following command):: + + $ ./manage.py syncdb --migrate + +#. Run the following command to initialize the directory that contains + static files:: + + $ ./manage.py collectstatic + +#. If you are using the *stats* extension, please rename the + */static/stats* directory to */media/stats* + and change the value of the ``IMG_ROOTDIR`` parameter (go to the adminstration panel) + +#. Restart the python instance(s) that serve *Modoboa* + +#. Log into Modoboa, go to *Modoboa > Extensions*, uncheck all + extensions, save. Then, check the extensions you want to use and + save again + +#. Update your webserver configuration to make static files available + (see :ref:`webserver`) + +#. **For Dovecot users only**, you need to modify the + ``password_query`` (file */etc/dovecot/dovecot-sql.conf* by default + on a Debian system) like this:: + + password_query = SELECT email AS user, password FROM auth_user WHERE email='%u' + +0.8.8: CSV import feature and minor fixes +========================================= + +#. Edit the *settings.py* file and add + ``'modoboa.lib.middleware.AjaxLoginRedirect'`` to the + ``MIDDLEWARE_CLASSES`` variable like this:: + + MIDDLEWARE_CLASSES = ( + 'django.middleware.common.CommonMiddleware', + 'django.contrib.sessions.middleware.SessionMiddleware', + 'django.contrib.auth.middleware.AuthenticationMiddleware', + 'django.contrib.messages.middleware.MessageMiddleware', + 'django.middleware.locale.LocaleMiddleware', + 'modoboa.lib.middleware.AjaxLoginRedirect', + 'modoboa.lib.middleware.ExtControlMiddleware', + 'modoboa.extensions.webmail.middleware.WebmailErrorMiddleware', + ) + +#. Still inside *settings.py*, modify the ``DATABASE_ROUTERS`` + variable like this:: + + DATABASE_ROUTERS = ["modoboa.extensions.amavis_quarantine.dbrouter.AmavisRouter"] + + +0.8.7: per-user language selection +================================== + +#. Edit the *settings.py* file and add the + ``'django.middleware.locale.LocaleMiddleware'`` middleware to the + ``MIDDLEWARE_CLASSES`` variable like this:: + + MIDDLEWARE_CLASSES = ( + 'django.middleware.common.CommonMiddleware', + 'django.contrib.sessions.middleware.SessionMiddleware', + 'django.contrib.auth.middleware.AuthenticationMiddleware', + 'django.contrib.messages.middleware.MessageMiddleware', + 'django.middleware.locale.LocaleMiddleware', + 'modoboa.lib.middleware.ExtControlMiddleware', + 'modoboa.extensions.webmail.middleware.WebmailErrorMiddleware', + ) + +#. To select a custom language, go to *Options > Preferences* and + select the ``general`` section. Choose a value, save and disconnect + from Modoboa. On the next login, the desired language will be used. + +0.8.6.1: maintenance release +============================ + +#. If you have tried to create a new mailbox and if you have + encountered the following `issue + `_, you must run the + ``dbcleanup.py`` script in order to remove orphan records:: + + $ cd + $ PYTHONPATH=$PWD/.. DJANGO_SETTINGS_MODULE=modoboa.settings ./admin/scripts/dbcleanup.py + +0.8.6: Quarantine plugin refactoring (using Django's ORM) +========================================================= + +#. Just update your configuration if you are using the quarantine + plugin. Open *settings.py*, move the database configuration from + the ``DB_CONNECTIONS`` variable to the ``DATABASES`` variable, like + this:: + + DATABASES = { + "default" : { + # The default database configuration + }, + # ... + "amavis": { + "ENGINE" : "", + "HOST" : "", + "NAME" : "", + "USER" : "", + "PASSWORD" : "" + } + } + +#. Add the new following variable somewhere in the file:: + + DATABASE_ROUTERS = ["modoboa.extensions.amavis_quarantine.dbrouter.AmavisRouter"] + +#. Remove the deprecated ``DB_CONNECTIONS`` variable from *settings.py*. + +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*:: + + MIDDLEWARE_CLASSES = ( + 'django.middleware.common.CommonMiddleware', + 'django.contrib.sessions.middleware.SessionMiddleware', + 'django.contrib.auth.middleware.AuthenticationMiddleware', + 'django.contrib.messages.middleware.MessageMiddleware', + 'modoboa.lib.middleware.ExtControlMiddleware', + 'modoboa.extensions.webmail.middleware.WebmailErrorMiddleware', + ) + +#. Go the *Settings/Extensions* panel, deactivate and activate your + extensions, it will update all the symbolic links to the new format. + +#. Optional: update the ``DATABASES`` and ``TEMPLATE_LOADERS`` + variables in *settings.py* to remove warning messages (appearing with + Django 1.3):: + + DATABASES = { + "default" : { + "ENGINE" : "", + "NAME" : "modoboa", + "USER" : "", + "PASSWORD" : "", + "HOST" : "", + "PORT" : "" + } + } + + TEMPLATE_LOADERS = ( + 'django.template.loaders.filesystem.Loader', + 'django.template.loaders.app_directories.Loader', + ) + +0.8.3: admin application refactoring and more +============================================= + +#. Migrate the *admin* application:: + + $ python manage.py migrate admin + +#. Update SQL queries used in your environnement (see + :ref:`postfix` or :ref:`dovecot`). + +#. Update *postfix* configuration so that it can handle domain aliases + (see :ref:`postfix`). + + +0.8.2: ckeditor integration and more +==================================== + +#. Migrate the admin applicaton:: + + $ python manage.py migrate admin + +#. Update your config file and add all extensions to ``INSTALLED_APPS`` + (even those you are not going to use). +#. Inside the */templates/* directory, remove all symbolic links. +#. Download the latest release of ckeditor and extract it into */static/js/*. It should create a new directory named *ckeditor*. +#. Update the following variables inside *settings.py*:: + + MEDIA_ROOT = os.path.join(MODOBOA_DIR, 'static') + MEDIA_URL = '/static/' + +#. Then, add the following variable: ``MODOBOA_WEBPATH = 'modoboa/'`` +#. Delete the following variables: ``STATIC_ROOTDIR`` and + ``TEMPLATE_CONTEXT_PROCESSORS``. +#. Finally, add ``modoboa.lib.middleware.ExtControlMiddleware`` to + ``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*. +#. Edit *settings.py* and replace all occurences of mailng by + modoboa. Make sure you don't modify the ``DATABASE`` section as you're + not going to rename your database. +#. Rename the ``MAILNG_DIR`` variable to ``MODOBOA_DIR``. +#. Add ``'django.contrib.messages.middleware.MessageMiddleware'`` to + ``MIDDLEWARE_CLASSES`` and ``'django.contrib.messages'`` to + ``INSTALLED_APPS``. Save your modifications. +#. Run the following command:: + + $ python manage.py syncdb + +#. For all activated extensions, run the following command:: + + $ export PYTHONPATH=/..= + $ DJANGO_SETTINGS_MODULE=modoboa.settings /scripts/extension.py on + +#. 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:: + + INSTALLED_APPS = ( + # Django's stuff before + + 'south', + 'mailng', + 'mailng.lib', + 'mailng.admin', + 'mailng.userprefs', + ) + +Starting with 0.8, mailng.main doesn't exist anymore. You must remove +it from your ``INSTALLED_APPS``. + +Finally, run the following commands:: + + $ python manage.py syncdb + $ python manage.py convert_to_south + $ python manage.py migrate --all 0001 --fake + $ python manage.py migrate --all 0002 + diff --git a/doc/index.rst b/doc/index.rst index 39a0f880e..76893df00 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -6,14 +6,41 @@ Modoboa's documentation! ======================== -Contents: +This documentation refers to version |release|. + +*************** +Getting started +*************** .. toctree:: - :maxdepth: 3 + :maxdepth: 2 + + getting_started/install + getting_started/upgrade + getting_started/configuration + getting_started/integration + getting_started/plugins + +***************** +Extending Modoboa +***************** + +.. toctree:: + :maxdepth: 2 + + extending/plugin_api + +******************* +Additional resource +******************* + +.. toctree:: + :maxdepth: 2 + + additional/webserver + additional/migrating + additional/virtualmachine - install - virtualmachine - plugin_api Indices and tables ================== diff --git a/doc/install.rst b/doc/install.rst deleted file mode 100644 index 3b7ce1b69..000000000 --- a/doc/install.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../INSTALL diff --git a/example/settings.py b/example/settings.py index 99d31dc92..916cd6552 100644 --- a/example/settings.py +++ b/example/settings.py @@ -41,7 +41,7 @@ DATABASES = { # } } -DATABASE_ROUTERS = ["modoboa.extensions.amavis_quarantine.dbrouter.AmavisRouter"] +DATABASE_ROUTERS = ["modoboa.extensions.amavis.dbrouter.AmavisRouter"] # Local time zone for this installation. Choices can be found here: # http://en.wikipedia.org/wiki/List_of_tz_zones_by_name @@ -100,7 +100,7 @@ MIDDLEWARE_CLASSES = ( 'modoboa.lib.middleware.ExtControlMiddleware', ) -ROOT_URLCONF = 'modoboa.urls' +ROOT_URLCONF = 'urls' TEMPLATE_DIRS = ( # Put strings here, like "/home/html/django_templates" or "C:/www/django/templates". diff --git a/modoboa/admin/forms.py b/modoboa/admin/forms.py index f11ef85ae..b7b895eb4 100644 --- a/modoboa/admin/forms.py +++ b/modoboa/admin/forms.py @@ -134,7 +134,7 @@ class DlistForm(forms.ModelForm, DynamicForm): ) recipients = forms.EmailField( label=ugettext_lazy("Recipients"), required=False, - help_text=ugettext_lazy("Mailbox(es) this alias will point to") + help_text=ugettext_lazy("Mailbox(es) this alias will point to. Indicate only one address per input, press ENTER to add a new input.") ) class Meta: diff --git a/setup.py b/setup.py index 7d49787c3..e7b8a043e 100644 --- a/setup.py +++ b/setup.py @@ -53,8 +53,8 @@ setup(name="modoboa", version='0.9', url='http://modoboa.org/', license='MIT', - description="Modular domains & mailboxes hosting", - long_description=read('README'), + description="Mail hosting made simple", + long_description=read('README.rst'), author='Antoine Nguyen', author_email='tonio@ngyn.org', packages=find_packages(),