diff --git a/doc/conf.py b/doc/conf.py index 44f06ec80..741a149d7 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -25,7 +25,9 @@ import sys, os # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = [] +extensions = [ + 'sphinx.ext.intersphinx', +] # Add any paths that contain templates here, relative to this directory. templates_path = ['.templates'] @@ -41,7 +43,7 @@ master_doc = 'index' # General information about the project. project = u'Modoboa' -copyright = u'2014, Antoine Nguyen' +copyright = u'2015, Antoine Nguyen' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the @@ -219,3 +221,7 @@ man_pages = [ ('index', 'modoboa', u'Modoboa Documentation', [u'Antoine Nguyen'], 1) ] + +intersphinx_mapping = { + 'amavis': ('http://modoboa-amavis.readthedocs.org/en/latest/', None) +} diff --git a/doc/getting_started/upgrade.rst b/doc/getting_started/upgrade.rst index 230ad644a..eacf67fce 100644 --- a/doc/getting_started/upgrade.rst +++ b/doc/getting_started/upgrade.rst @@ -105,7 +105,7 @@ If you plan to use the Radicale extension: A new feature allows administrators and users to manually train SpamAssassin in order to customize its behaviour. -Check :ref:`sa_manual_learning` to know more about this feature. +Check :ref:`amavis:sa_manual_learning` to know more about this feature. 1.1.6: Few bugfixes =================== diff --git a/doc/plugins/amavis.rst b/doc/plugins/amavis.rst index fb5b043c9..268448917 100644 --- a/doc/plugins/amavis.rst +++ b/doc/plugins/amavis.rst @@ -4,304 +4,4 @@ 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 - -.. note:: - - The per-domain policies feature only works for new - installations. Currently, you can't use modoboa with an existing - database (ie. with data in ``users`` and ``policies`` tables). - -.. note:: - - This plugin requires amavisd-new version **2.7.0** or higher. If - you're planning to use the :ref:`selfservice`, you'll need version - **2.8.0**. - -Quick Amavis setup -================== - -By default, amavis doesn't use a database. To configure this -behaviour, you first need to create a dedicated database. This step is a -bit manual since no *ready-to-use* SQL schema is provided by -amavis. The information is located inside README files, one for `MySQL -`_ and one for `PostgreSQL -`_. - -Then, you must tell amavis to use this database for lookups and -quarantined messages storing. Here is a working configuration sample:: - - @lookup_sql_dsn = - (['DBI::database=;host=;port=', '', ']']); - - @storage_sql_dsn = - (['DBI::database=;host=;port=', '', ']']); - - # PostgreSQL users NEED this parameter! - # MySQL users only need this parameter is email addresses are stored - # using the VARBINARY type. - $sql_allow_8bit_address = 1; - - $virus_quarantine_method = 'sql:'; - $spam_quarantine_method = 'sql:'; - $banned_files_quarantine_method = 'sql:'; - $bad_header_quarantine_method = 'sql:'; - - $virus_quarantine_to = 'virus-quarantine'; - $banned_quarantine_to = 'banned-quarantine'; - $bad_header_quarantine_to = 'bad-header-quarantine'; - $spam_quarantine_to = 'spam-quarantine'; - -Replace values between ``<>`` by yours. To know how to configure -amavis to allow quarantined messages release, read this :ref:`section -`. - -.. note:: - - Amavis configuration allows for separate lookup and storage - databases but Modoboa doesn't support it yet. - -Connect Modoboa and Amavis -========================== - -You must tell to Modoboa where it can find the amavis -database. Inside :file:`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. - -Cleanup -------- - -Storing quarantined messages to a database can quickly become a -perfomance killer. Modoboa provides a simple script to periodically -purge the quarantine database. To use it, add the following line -inside root's crontab:: - - 0 0 * * * /manage.py qcleanup - # - # Or like this if you use a virtual environment: - # 0 0 * * * /manage.py qcleanup - -Replace ``modoboa_site`` with the path of your Modoboa instance. - -By default, messages older than 14 days are automatically purged. You -can modify this value by changing the ``MAX_MESSAGES_AGE`` parameter -in the online panel. - -.. _amavis_release: - -Release messages -================ - -To release messages, first take a look at `this page -`_. It -explains how to configure amavisd-new to listen somewhere for the -AM.PDP protocol. This protocol is used to send 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 -online panel: - -+--------------------+--------------------+------------------------+ -|Name |Description |Default value | -+====================+====================+========================+ -|Amavis connection |Mode used to access |unix | -|mode |the PDP server | | -+--------------------+--------------------+------------------------+ -|PDP server address |PDP server address |localhost | -| |(if inet mode) | | -+--------------------+--------------------+------------------------+ -|PDP server port |PDP server port (if | | -| |inet mode) 9998 | | -+--------------------+--------------------+------------------------+ -|PDP server socket |Path to the PDP |/var/amavis/amavisd.sock| -| |server socket (if | | -| |unix mode) | | -+--------------------+--------------------+------------------------+ - -Deferred release ----------------- - -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='' - # - # Or like this if you use a virtual environment: - # 0 12 * * * /manage.py amnotify --baseurl='' - -You are free to change the frequency. - -.. note:: - - If you want to let users release their messages alone (not - recommended), go to the admin panel. - -The following parameters are available to let you customize this -feature: - -+--------------------+--------------------+------------------------+ -|Name |Description |Default value | -+====================+====================+========================+ -|Check requests |Interval between two|30 | -|interval |release requests | | -| |checks | | -+--------------------+--------------------+------------------------+ -|Allow direct release|Allow users to |no | -| |directly release | | -| |their messages | | -+--------------------+--------------------+------------------------+ -|Notifications sender|The e-mail address |notification@modoboa.org| -| |used to send | | -| |notitications | | -+--------------------+--------------------+------------------------+ - -.. _selfservice: - -Self-service mode -================= - -The *self-service* mode lets users act on quarantined messages without -beeing authenticated. They can: - -* View messages -* Remove messages -* Release messages (or send release requests) - -To access a specific message, they only need the following information: - -* Message's unique identifier -* Message's secret identifier - -This information is controlled by *amavis*, which is in charge of -notifying users when new messages are put into quarantine. Each -notification (one per message) must embark a direct link containing -the required identifiers. - -To activate this feature, go the administration panel and set the -**Enable self-service mode** parameter to yes. - -The last step is to customize the notification messages amavis -sends. The most important is to embark a direct link. Take a look at -the `README.customize `_ file to -learn what you're allowed to do. - -Here is a link example:: - - http:///quarantine/%i/?rcpt=%R&secret_id=[:secret_id] - -.. _sa_manual_learning: - -Manual SpamAssassin learning -============================ - -It is possible to manually train `SpamAssassin -`_ using the quarantine's content. By -train, we mean: - -* Mark message(s) as spam (false negative(s)) - -* Mark message(s) as non-spam (false positive(s)) - -This feature is available to all users (from super administrators to -simple users) but not enabled by default. - -SpamAssassin configuration --------------------------- - -For better performance and to enable the per-user level, SpamAssassin -must store bayes information into a SQL database. - -Create a new database and a new user/password (using your favorite -database server) and edit the default configuration file -(:file:`/etc/spamassassin/local.cf`) to add the following lines -inside: - -.. sourcecode:: perl - - bayes_store_module Mail::SpamAssassin::BayesStore:: - bayes_sql_dsn - bayes_sql_username - bayes_sql_password - -Replace values between ``<>`` by yours. Possible values for ``Driver`` -are ``PgSQL`` or ``MySQL`` (non exhaustive list). The syntax for -``DSN`` depends on the driver you choose. Please consult the official -documentation. - -Enable the feature through Modoboa ----------------------------------- - -Manual learning is disabled by default. You can activate it through -the administration panel (*Modoboa > Paremeters > Amavis*). There two -learning levels: - -#. Global: available to administrators only. A single (global) bayes - database is shared between everyone. - -#. Per domain: available to administrators and domain - administrators. Each domain can have a dedicated database. - -#. Per user: each user can create its own database to customize the - way SpamAssassin will detect spam. - -The domain and user levels are not activated by default, dedicated -parameters are available through the panel. - -.. note:: - - Domain and user databases are only created the first time someone - calls the learning feature through the quarantine. - -.. warning:: - - A bayes database needs to reach pre-defined thresholds before it - can be used by SpamAssassin. The default values are **200** spams - and **200** hams. - -You will find other paramaters related to this feature. You won't need -to change them most of the time, unless SpamAssassin is hosted on a -different machine than Modoboa. (in this case, ``spamc`` will be used -instead of ``sa-learn``). +`Official documentation `_. diff --git a/doc/plugins/limits.rst b/doc/plugins/limits.rst index 94b6b240a..e190b6c28 100644 --- a/doc/plugins/limits.rst +++ b/doc/plugins/limits.rst @@ -2,15 +2,4 @@ Per-admin limits ################ -This plugin offers a way to define limits about how many objects -(aliases, mailboxes) a domain administrator can create. - -It also brings a new administrative role: ``Reseller``. A reseller is a domain -administrator that can also manipulate domains and assign permissions -to domain administrators. - -If you don't want to limit a particular object type, just set the -associated value to -1. - -Default limits applied to new administrators can be changed through -the *Modoboa > Parameters > Limits* page. +`Official documentation `_. diff --git a/doc/plugins/postfix_autoreply.rst b/doc/plugins/postfix_autoreply.rst index 0e87414b0..e1683a6b6 100644 --- a/doc/plugins/postfix_autoreply.rst +++ b/doc/plugins/postfix_autoreply.rst @@ -4,48 +4,4 @@ Postfix auto-reply messages ########################### -This plugin let users define an auto-reply message (*vacation*). It is -based on Postfix capabilities. - -The user that executes the autoreply script needs to access -:file:`settings.py`. You must apply proper permissions on this file. For -example, if :file:`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 follows: - -``/etc/postfix/main.cf``:: - - transport_maps = :/etc/postfix/sql-autoreplies-transport.cf - virtual_alias_maps = :/etc/postfix/sql-aliases.cf - :/etc/postfix/sql-domain-aliases-mailboxes.cf, - :/etc/postfix/sql-autoreplies.cf, - :/etc/postfix/sql-catchall-aliases.cf - -.. note:: - - The order used to define alias maps is important, please respect it - -``/etc/postfix/master.cf``:: - - autoreply unix - n n - - pipe - flags= user=vmail: argv=python /manage.py autoreply $sender $mailbox - -Replace ```` by the name of the database you -use. ```` is the path of your Modoboa instance. - -Then, create the requested map files:: - - $ modoboa-admin.py postfix_maps mapfiles --categories autoreply - -`mapfiles` is the directory where the files will be stored. Answer the -few questions and you're done. - -.. 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 **Automatic - reply timeout** parameter available in the online panel. +`Official documentation `_. diff --git a/doc/plugins/postfix_relay_domains.rst b/doc/plugins/postfix_relay_domains.rst index 5034f8ef9..7a7c8c7e5 100644 --- a/doc/plugins/postfix_relay_domains.rst +++ b/doc/plugins/postfix_relay_domains.rst @@ -2,39 +2,4 @@ Postfix relay domains support ############################# -This plugin adds the support for relay domains using postfix. You can -use it when the MTA managed by Modoboa is not the final destination of -one or several domains. - -If activated, two new objects will be available from the *Domains* -listing page: *relay domain* and *relay domain alias*. - -The extension is compatible with the *amavis* and *limits* -ones. Resellers will be able to create both new objects. - -Replace by the name of the database you use.To tell Postfix this feature exists, you must generate two new map -files and then update your configuration. - -To generate the map files, run the following command:: - - $ modoboa-admin.py postfix_maps --categories relaydomains --dbtype - -Replace values between ``<>`` by yours. - -Edit the :file:`/etc/postfix/main.cf` file and copy the following -lines inside:: - - relay_domains = :/etc/postfix/sql-relaydomains.cf - transport_maps = - :/etc/postfix/sql-relaydomains-transport.cf - :/etc/postfix/sql-relaydomain-aliases-transport.cf - - smtpd_recipient_restrictions = - permit_mynetworks - reject_unauth_destination - check_recipient_access - :/etc/postfix/sql-relay-recipient-verification.cf - -Replace ```` by the name of the database you use. - -Reload postfix. +`Official documentation `_. diff --git a/doc/plugins/radicale.rst b/doc/plugins/radicale.rst index 511f71aaf..456529d41 100644 --- a/doc/plugins/radicale.rst +++ b/doc/plugins/radicale.rst @@ -2,45 +2,4 @@ Radicale frontend ################# -This plugin provides a simple management frontend for `Radicale -`_, a complete CalDAV (calendar) and CardDAV -(contact) server solution. - -Features currently supported are: - -* Private calendar creation (available for simple users) -* Rights management for private calendars -* Shared calendar creation by domain (available for domain administrators) - -.. note:: - - This plugin requires Radicale 0.9 or higher. - -Setup -===== - -Once `Radicale is installed -`_ on your server, you must -tell Modoboa where it can find the file used to store rules. - -Go to the *Modoboa > Parameters > Radicale* panel and fill the -**Radicale rights file path** setting (an absolute path is required). - -When the configuration is done, Modoboa will completly handles the -file's content. It means every manual modification you could made on -this file would be overriden. - -To do so, a new cron job must be created. You can use the following -example:: - - */2 * * * * /manage.py generate_rights - # - # Or like this if you use a virtual environment: - # */2 * * * * /manage.py generate_rights - -.. note:: - - In some cases, the modifications you make on Modoboa may not be - applied to the rights file. In order to force the generation, - manually run the ``generate_rights`` command using the ``--force`` - option. +`Official documentation `_. diff --git a/doc/plugins/sievefilters.rst b/doc/plugins/sievefilters.rst index 77f77d2f3..0d714afc9 100644 --- a/doc/plugins/sievefilters.rst +++ b/doc/plugins/sievefilters.rst @@ -2,42 +2,4 @@ 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 local delivery agent must understand the *Sieve* -language. Don't panic, Dovecot supports both :-) (refer to -:ref:`dovecot` to know how to enable those features). - -.. note:: - The sieve filters plugin requires that the :ref:`webmail` plugin is - activated and configured. - -Go the online panel and modify the following parameters in order to -communicate with the *ManageSieve* server: - -+--------------------+--------------------+--------------------+ -|Name |Description |Default value | -+====================+====================+====================+ -|Server address |Address of your |127.0.0.1 | -| |MANAGESIEVE server | | -+--------------------+--------------------+--------------------+ -|Server port |Listening port of |4190 | -| |your MANAGESIEVE | | -| |server | | -+--------------------+--------------------+--------------------+ -|Connect using |Use the STARTTLS |no | -|STARTTLS |extension | | -+--------------------+--------------------+--------------------+ -|Authentication |Prefered |auto | -|mechanism |authentication | | -| |mechanism | | -+--------------------+--------------------+--------------------+ +`Official documentation `_. diff --git a/doc/plugins/statistics.rst b/doc/plugins/statistics.rst index 57e821747..50fd452b0 100644 --- a/doc/plugins/statistics.rst +++ b/doc/plugins/statistics.rst @@ -4,44 +4,4 @@ Graphical statistics #################### -This plugin collects various statistics about emails traffic on your -server. It parses a log file to collect information, store it into RRD -files (see `rrdtool `_) and then -generates graphics in PNG format. - -To use it, go to the online parameters panel and adapt the following -ones to your environment: - -+--------------------+--------------------+--------------------------+ -|Name |Description |Default value | -+====================+====================+==========================+ -|Path to the log file|Path to log file |/var/log/mail.log | -| |used to collect | | -| |statistics | | -+--------------------+--------------------+--------------------------+ -|Directory to store |Path to directory |/tmp/modoboa | -|RRD files |where RRD files are | | -| |stored | | -+--------------------+--------------------+--------------------------+ -|Directory to store |Path to directory |/media/stats| -|PNG files |where PNG files are | | -| |stored | | -+--------------------+--------------------+--------------------------+ - -Make sure the directory that will contain RRD files exists. If not, -create it before going further. For example (according to the previous -parameters):: - - $ mkdir /tmp/modoboa - -To finish, you need to collect information periodically in order to -feed the RRD files. Add the following line into root's crontab:: - - */5 * * * * /manage.py logparser &> /dev/null - # - # Or like this if you use a virtual environment: - # 0/5 * * * * /manage.py logparser &> /dev/null - -Replace ```` with the path of your Modoboa instance. - -Graphics will be automatically created after each parsing. +`Official documentation `_. diff --git a/doc/plugins/webmail.rst b/doc/plugins/webmail.rst index 6e5bc8de1..b9df5e984 100644 --- a/doc/plugins/webmail.rst +++ b/doc/plugins/webmail.rst @@ -4,68 +4,4 @@ Webmail ####### -Modoboa provides a simple webmail: - -* Browse, read and compose messages, attachments are supported -* HTML messages are supported -* `CKeditor `_ integration -* Manipulate mailboxes (create, move, remove) -* Quota display - -To use it, go to the online panel and modify the following parameters -to communicate with your *IMAP* server (under *IMAP settings*): - -+--------------------+--------------------+--------------------+ -|Name |Description |Default value | -+====================+====================+====================+ -|Server address |Address of your IMAP|127.0.0.1 | -| |server | | -+--------------------+--------------------+--------------------+ -|Use a secured |Use a secured |no | -|connection |connection to access| | -| |IMAP server | | -+--------------------+--------------------+--------------------+ -|Server port |Listening port of |143 | -| |your IMAP server | | -+--------------------+--------------------+--------------------+ - -Do the same to communicate with your SMTP server (under *SMTP settings*): - -+--------------------+--------------------+--------------------+ -|Name |Description |Default value | -+====================+====================+====================+ -|Server address |Address of your SMTP|127.0.0.1 | -| |server | | -+--------------------+--------------------+--------------------+ -|Secured connection |Use a secured |None | -|mode |connection to access| | -| |SMTP server | | -+--------------------+--------------------+--------------------+ -|Server port |Listening port of |25 | -| |your SMTP server | | -+--------------------+--------------------+--------------------+ -|Authentication |Server needs |no | -|required |authentication | | -+--------------------+--------------------+--------------------+ - -.. note:: - - The size of each attachment sent with messages is limited. You can - change the default value by modifying the **Maximum attachment - size** parameter. - -Using CKeditor -============== - -Modoboa supports CKeditor to compose HTML messages. To use it, first -download it from `the official website `_, then -extract the tarball:: - - $ cd - $ tar xzf /path/to/ckeditor/tarball.tag.gz -C sitestatic/js/ - -And you're done! - -Now, each user has the possibility to choose between CKeditor and the -raw text editor to compose their messages. (see *User > Settings > -Preferences > Webmail*) +`Official documentation `_.