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

Merge pull request #3884 from modoboa/remove-old-doc

Browse Source 
Removed old documentation
This commit is contained in:
Antoine Nguyen
2026-01-16 14:39:48 +01:00
committed by GitHub
parent 82b9313d74 0067d23548
commit a5a10bf7f0
28 changed files with 1 additions and 5864 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/workflows/documentation.yml
-2
View File
@@ -4,13 +4,11 @@ on:
paths-ignore:
- 'modoboa/**'
- 'frontend/**'
- 'doc/**'
pull_request:
branches: [ master ]
paths-ignore:
- 'modoboa/**'
- 'frontend/**'
- 'doc/**'
jobs:
cache-and-install:
.github/workflows/modoboa.yml
-2
View File
@@ -9,7 +9,6 @@ on:
paths-ignore:
- 'modoboa/**.po'
- 'frontend/**'
- 'doc/**'
- 'doc-ng/**'
- '.editorconfig'
- '.readthedocs.yml'
@@ -20,7 +19,6 @@ on:
paths-ignore:
- 'modoboa/**.po'
- 'frontend/**'
- 'doc/**'
- 'doc-ng/**'
- '.editorconfig'
- '.readthedocs.yml'
.gitignore
-3
View File
@@ -3,9 +3,6 @@
*.mo
*.db
modoboa.egg-info
doc/.build
doc/.static
doc/.templates
DEV
.idea
.ropeproject
MANIFEST.in
+1 -1
View File
@@ -4,4 +4,4 @@ recursive-include modoboa/frontend_dist *
recursive-include modoboa *.html *.js *.css *.png *.po *.mo *.json *.gif *.ttf *.woff *.woff2
recursive-include modoboa/core/templates *.tpl
recursive-include modoboa/core/commands/templates *.tpl
recursive-include doc *
recursive-include doc-ng *
doc/Makefile
-130
View File
@@ -1,130 +0,0 @@
# Makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
PAPER =
BUILDDIR = .build
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest
help:
@echo "Please use \`make <target>' where <target> is one of"
@echo " html to make standalone HTML files"
@echo " dirhtml to make HTML files named index.html in directories"
@echo " singlehtml to make a single large HTML file"
@echo " pickle to make pickle files"
@echo " json to make JSON files"
@echo " htmlhelp to make HTML files and a HTML help project"
@echo " qthelp to make HTML files and a qthelp project"
@echo " devhelp to make HTML files and a Devhelp project"
@echo " epub to make an epub"
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
@echo " latexpdf to make LaTeX files and run them through pdflatex"
@echo " text to make text files"
@echo " man to make manual pages"
@echo " changes to make an overview of all changed/added/deprecated items"
@echo " linkcheck to check all external links for integrity"
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
clean:
-rm -rf $(BUILDDIR)/*
html:
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
dirhtml:
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
singlehtml:
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
@echo
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
pickle:
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
@echo
@echo "Build finished; now you can process the pickle files."
json:
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
@echo
@echo "Build finished; now you can process the JSON files."
htmlhelp:
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
@echo
@echo "Build finished; now you can run HTML Help Workshop with the" \
".hhp project file in $(BUILDDIR)/htmlhelp."
qthelp:
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
@echo
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Modoboa.qhcp"
@echo "To view the help file:"
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Modoboa.qhc"
devhelp:
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
@echo
@echo "Build finished."
@echo "To view the help file:"
@echo "# mkdir -p $$HOME/.local/share/devhelp/Modoboa"
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Modoboa"
@echo "# devhelp"
epub:
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
@echo
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
latex:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
@echo "Run \`make' in that directory to run these through (pdf)latex" \
"(use \`make latexpdf' here to do that automatically)."
latexpdf:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through pdflatex..."
make -C $(BUILDDIR)/latex all-pdf
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
text:
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
@echo
@echo "Build finished. The text files are in $(BUILDDIR)/text."
man:
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
@echo
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
changes:
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
@echo
@echo "The overview file is in $(BUILDDIR)/changes."
linkcheck:
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
@echo
@echo "Link check complete; look for any errors in the above output " \
"or in $(BUILDDIR)/linkcheck/output.txt."
doctest:
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
@echo "Testing of doctests in the sources finished, look at the " \
"results in $(BUILDDIR)/doctest/output.txt."
doc/_static/api_access_form.png
Vendored
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 17 KiB

doc/_static/modoboa_logo.png
Vendored
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 7.1 KiB

doc/conf.py
-226
View File
@@ -1,226 +0,0 @@
#
# Modoboa documentation build configuration file, created by
# sphinx-quickstart on Mon Jan 3 22:29:25 2011.
#
# This file is execfile()d with the current directory set to its containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
from unittest.mock import Mock as MagicMock
import sys
class Mock(MagicMock):
@classmethod
def __getattr__(cls, name):
return MagicMock()
MOCK_MODULES = ["rrdtool"]
sys.modules.update((mod_name, Mock()) for mod_name in MOCK_MODULES)
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
# sys.path.insert(0, os.path.abspath('.'))
# -- General configuration -----------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
# needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = [
"sphinx.ext.intersphinx",
"sphinx_rtd_theme",
]
# Add any paths that contain templates here, relative to this directory.
templates_path = [".templates"]
# The suffix of source filenames.
source_suffix = ".rst"
# The encoding of source files.
# source_encoding = 'utf-8-sig'
# The master toctree document.
master_doc = "index"
# General information about the project.
project = "Modoboa"
copyright = "2026, Antoine Nguyen" # NOQA:A001
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = "2.5.0"
# The full version, including alpha/beta/rc tags.
release = "2.5.0"
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
# language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
# today = ''
# Else, today_fmt is used as the format for a strftime call.
# today_fmt = '%B %d, %Y'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = [".build"]
# The reST default role (used for this markup: `text`) to use for all documents.
# default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
# add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
# add_module_names = True
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
# show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = "sphinx"
# A list of ignored prefixes for module index sorting.
# modindex_common_prefix = []
# -- Options for HTML output ---------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = "sphinx_rtd_theme"
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
# html_theme_options = {}
# Add any paths that contain custom themes here, relative to this directory.
# html_theme_path = []
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
# html_title = None
# A shorter title for the navigation bar. Default is the same as html_title.
# html_short_title = None
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
# html_logo = None
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
# html_favicon = None
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ["_static"]
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
# html_last_updated_fmt = '%b %d, %Y'
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
# html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
# html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
# html_additional_pages = {}
# If false, no module index is generated.
# html_domain_indices = True
# If false, no index is generated.
# html_use_index = True
# If true, the index is split into individual pages for each letter.
# html_split_index = False
# If true, links to the reST sources are added to the pages.
# html_show_sourcelink = True
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
# html_show_sphinx = True
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
# html_show_copyright = True
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
# html_use_opensearch = ''
# This is the file name suffix for HTML files (e.g. ".xhtml").
# html_file_suffix = None
# Output file base name for HTML help builder.
htmlhelp_basename = "Modoboadoc"
# -- Options for LaTeX output --------------------------------------------------
# The paper size ('letter' or 'a4').
# latex_paper_size = 'letter'
# The font size ('10pt', '11pt' or '12pt').
# latex_font_size = '10pt'
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, documentclass [howto/manual]).
latex_documents = [
("index", "Modoboa.tex", "Modoboa Documentation", "Antoine Nguyen", "manual"),
]
# The name of an image file (relative to this directory) to place at the top of
# the title page.
# latex_logo = None
# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
# latex_use_parts = False
# If true, show page references after internal links.
# latex_show_pagerefs = False
# If true, show URL addresses after external links.
# latex_show_urls = False
# Additional stuff for the LaTeX preamble.
# latex_preamble = ''
# Documents to append as an appendix to all manuals.
# latex_appendices = []
# If false, no module index is generated.
# latex_domain_indices = True
# -- Options for manual page output --------------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [("index", "modoboa", "Modoboa Documentation", ["Antoine Nguyen"], 1)]
doc/configuration.rst
-645
View File
@@ -1,645 +0,0 @@
#############
Configuration
#############
*****************
Online parameters
*****************
Modoboa provides online panels to modify internal parameters. There
are two available levels:
* Application level: global parameters, define how the application
behaves. Available at *Modoboa > Parameters*
* User level: per user customization. Available at *User > Settings >
Preferences*
Regardless level, parameters are displayed using tabs, each tab
corresponding to one application.
.. _admin-params:
General parameters
==================
The *admin* application exposes several parameters, they are presented below:
+--------------------+---------------------+-------------------------------+--------------------+
|Name |Tab |Description |Default value |
+====================+=====================+===============================+====================+
|Authentication type |General |The backend used for |Local |
| | |authentication | |
+--------------------+---------------------+-------------------------------+--------------------+
|Default password |General |Scheme used to crypt |sha512crypt |
|scheme | |mailbox passwords | |
+--------------------+---------------------+-------------------------------+--------------------+
|Rounds |General |Number of rounds (only used by |70000 |
| | |`sha256crypt` and | |
| | |`sha512crypt`). Must be between| |
| | |1000 and 999999999, inclusive. | |
| | | | |
+--------------------+---------------------+-------------------------------+--------------------+
|Secret key |General |A key used to |random value |
| | |encrypt users' | |
| | |password in sessions | |
+--------------------+---------------------+-------------------------------+--------------------+
|Sender address |General |Email address used to send | |
| | |notifications. | |
| | | | |
| | | | |
| | | | |
| | | | |
+--------------------+---------------------+-------------------------------+--------------------+
|Enable communication|General |Enable communication with |yes |
| | |Modoboa public API | |
| | | | |
| | | | |
| | | | |
| | | | |
+--------------------+---------------------+-------------------------------+--------------------+
|Check new versions |General |Automatically checks if a newer|yes |
| | |version is available | |
| | | | |
| | | | |
| | | | |
| | | | |
+--------------------+---------------------+-------------------------------+--------------------+
|Send statistics |General |Send statistics to Modoboa |yes |
| | |public API (counters and used | |
| | |extensions) | |
| | | | |
| | | | |
| | | | |
+--------------------+---------------------+-------------------------------+--------------------+
|Top notifications |General |Interval between two top |30 |
|check interval | |notification checks (in | |
| | |seconds) | |
+--------------------+---------------------+-------------------------------+--------------------+
|Maximum log record |General |The maximum age in |365 |
|age | |days of a log record | |
+--------------------+---------------------+-------------------------------+--------------------+
|Items per page |General |Number of displayed |30 |
| | |items per page | |
+--------------------+---------------------+-------------------------------+--------------------+
|Default top |General |The default |userprefs |
|redirection | |redirection used | |
| | |when no application | |
| | |is specified | |
+--------------------+---------------------+-------------------------------+--------------------+
|Enable MX checks |Admin |Check that every domain has a |yes |
| | |valid MX record | |
| | | | |
| | | | |
+--------------------+---------------------+-------------------------------+--------------------+
|Valid MXs |Admin |A list of IP or network address| |
| | |every MX should match. A | |
| | |warning will be sent if a | |
| | |record does not respect this | |
| | |it. | |
+--------------------+---------------------+-------------------------------+--------------------+
|Enable DNSBL checks |Admin |Check every domain against |yes |
| | |major DNSBL providers | |
| | | | |
| | | | |
+--------------------+---------------------+-------------------------------+--------------------+
|DKIM keys storage |Admin |Path to a directory where DKIM | |
|directory | | generated keys will be stored | |
| | | | |
| | | | |
| | | | |
| | | | |
+--------------------+---------------------+-------------------------------+--------------------+
|Default DKIM key |Admin |The default size (in bits) for |2048 |
|length | |new keys | |
| | | | |
| | | | |
| | | | |
| | | | |
+--------------------+---------------------+-------------------------------+--------------------+
|Handle mailboxes on |Admin |Rename or remove |no |
|filesystem | |mailboxes on the | |
| | |filesystem when they | |
| | |get renamed or | |
| | |removed within | |
| | |Modoboa | |
+--------------------+---------------------+-------------------------------+--------------------+
|Mailboxes owner |Admin |The UNIX account who |vmail |
| | |owns mailboxes on | |
| | |the filesystem | |
+--------------------+---------------------+-------------------------------+--------------------+
|Default domain quota|Admin |Default quota (in MB) applied |0 |
| | |to freshly created domains with| |
| | |no value specified. A value of | |
| | |0 means no quota. | |
+--------------------+---------------------+-------------------------------+--------------------+
|Automatic account |Admin |When a mailbox is |no |
|removal | |removed, also remove | |
| | |the associated | |
| | |account | |
+--------------------+---------------------+-------------------------------+--------------------+
|Automatic |Admin |Create a domain and a mailbox |yes |
|domain/mailbox | |when an account is | |
|creation | |automatically created | |
| | | | |
+--------------------+---------------------+-------------------------------+--------------------+
.. warning::
If Dovecot is not running on the same host than Modoboa, you will have
to define which password schemes are supported. To do so, open the
:file:`settings.py` file and add a ``DOVECOT_SUPPORTED_SCHEMES``
variable with the output of the command: ``doveadm pw -l``.
.. note::
If you are not familiar with virtual domain hosting, you should
take a look at `postfix's documentation
<http://www.postfix.org/VIRTUAL_README.html>`_. This `How to
<https://help.ubuntu.com/community/PostfixVirtualMailBoxClamSmtpHowto>`_
also contains useful information.
.. note::
A random secret key will be generated each time the *Parameters*
page is refreshed and until you save parameters at least once.
.. note::
Specific LDAP parameters are also available, see :ref:`LDAP
authentication <ldap_auth>`.
***********
Media files
***********
Modoboa uses a specific directory to upload files (ie. when the
webmail is in use) or to create ones (ex: graphical statistics). This
directory is named ``media`` and is located inside modoboa's
installation directory (called ``modoboa_site`` in this
documentation).
To work properly, the system user which runs modoboa (``www-data``,
``apache``, whatever) must have write access to this directory.
.. _customization:
*************
Customization
*************
Custom logo
===========
You have the possibility to use a custom logo instead of the default
one on the login page and inside generated PDF documents.
To do so, open the :file:`settings.py` file and add a
``MODOBOA_CUSTOM_LOGO`` variable. This variable must contain the
relative URL of your logo under ``MEDIA_URL``. For example::
MODOBOA_CUSTOM_LOGO = os.path.join(MEDIA_URL, "custom_logo.png")
Then copy your logo file into the directory indicated by
``MEDIA_ROOT``.
You can also customize the logo(s) used in the frontend application
(left menu and creation forms).
To do so, copy the corresponding files inside the frontend directory
directly (defaults to ``/srv/modoboa/instance/frontend``).
Then, edit the :file:`config.json` file located in this very same
directory and add the following variables::
"MENU_LOGO_PATH": "/cusrtom_logo.png",
"CREATION_FORM_LOGO_PATH": "/custom_logo2.png"
******************
Host configuration
******************
.. note::
This section is only relevant when Modoboa handles mailboxes
renaming and removal from the filesystem, which requires that
Dovecot is installed and running on this host. If it is installed
at a non-standard directory, paths to its binaries can be set in the
:file:`settings.py` file with the ``DOVECOT_LOOKUP_PATH`` and
``DOVEADM_LOOKUP_PATH`` variables.
To manipulate mailboxes on the filesystem, you must allow the user who
runs Modoboa to execute commands as the user who owns mailboxes.
To do so, edit the :file:`/etc/sudoers` file and add the following inside::
<user_that_runs_modoboa> ALL=(<mailboxes owner>) NOPASSWD: ALL
Replace values between ``<>`` by the ones you use.
.. _timezone_lang:
**********************
Time zone and language
**********************
Modoboa is available in many languages.
To specify the default language to use, edit the :file:`settings.py` file
and modify the ``LANGUAGE_CODE`` variable::
LANGUAGE_CODE = 'fr' # or 'en' for english, etc.
.. note::
Each user has the possibility to define the language he prefers.
In the same configuration file, specify the timezone to use by
modifying the ``TIME_ZONE`` variable. For example::
TIME_ZONE = 'Europe/Paris'
*******************
Sessions management
*******************
Modoboa uses `Django's session framework
<https://docs.djangoproject.com/en/dev/topics/http/sessions/?from=olddocs>`_
to store per-user information.
Few parameters need to be set in the :file:`settings.py` configuration
file to make Modoboa behave as expected::
SESSION_EXPIRE_AT_BROWSER_CLOSE = False # Default value
This parameter is optional but you must ensure it is set to ``False``
(the default value).
The default configuration file provided by the ``modoboa-admin.py``
command is properly configured.
**********************
Logging authentication
**********************
To trace login attempts to the web interface, Modoboa uses python
`SysLogHandler <https://docs.python.org/3/library/logging.handlers.html#logging.handlers.SysLogHandler>`_
so you can see them in your syslog authentication log file
(`/var/log/auth.log` in most cases).
Depending on your configuration, you may have to edit the :file:`settings.py` file
and add `'address': '/dev/log'` to the logging section::
'syslog-auth': {
'class': 'logging.handlers.SysLogHandler',
'facility': SysLogHandler.LOG_AUTH,
'address': '/dev/log',
'formatter': 'syslog'
},
***********************
External authentication
***********************
.. _ldap_auth:
LDAP
====
Modoboa supports external LDAP authentication using the following extra components:
* `Python LDAP client <http://www.python-ldap.org/>`_
* `Django LDAP authentication backend <http://pypi.python.org/pypi/django-auth-ldap>`_
If you want to use this feature, you must first install those components::
$ pip install python-ldap django-auth-ldap
Then, all you have to do is to modify the :file:`settings.py` file. Add a
new authentication backend to the `AUTHENTICATION_BACKENDS` variable,
like this::
AUTHENTICATION_BACKENDS = (
'modoboa.lib.authbackends.LDAPBackend',
# 'modoboa.lib.authbackends.LDAPSecondaryBackend', # Useful for a fallback mechanism
'django.contrib.auth.backends.ModelBackend',
)
Finally, go to *Modoboa > Parameters > General* and set *Authentication
type* to LDAP.
From there, new parameters will appear to let you configure the way
Modoboa should connect to your LDAP server. They are described just below:
+--------------------+---------------------------------+--------------------+
|Name |Description |Default value |
+====================+=================================+====================+
|Server address |The IP address of |localhost |
| |the DNS name of the | |
| |LDAP server | |
+--------------------+---------------------------------+--------------------+
|Server port |The TCP port number |389 |
| |used by the LDAP | |
| |server | |
+--------------------+---------------------------------+--------------------+
|Use a secure |Use an SSL/TLS |no |
|connection |connection to access | |
| |the LDAP server | |
+--------------------+---------------------------------+--------------------+
|Authentication |Choose the |Direct bind |
|method |authentication | |
| |method to use | |
+--------------------+---------------------------------+--------------------+
|User DN template |The template used to | |
|(direct bind mode) |construct a user's | |
| |DN. It should | |
| |contain one | |
| |placeholder | |
| |(ie. ``%(user)s``) | |
+--------------------+---------------------------------+--------------------+
|Bind BN |The distinguished | |
| |name to use when | |
| |binding to the LDAP | |
| |server. Leave empty | |
| |for an anonymous | |
| |bind | |
+--------------------+---------------------------------+--------------------+
|Bind password |The password to use | |
| |when binding to the | |
| |LDAP server (with | |
| |'Bind DN') | |
+--------------------+---------------------------------+--------------------+
|Search base |The distinguished | |
| |name of the search | |
| |base | |
+--------------------+---------------------------------+--------------------+
|Search filter |An optional filter string |(mail=%(user)s) |
| |(e.g. '(objectClass=person)'). In| |
| |order to be valid, it must be | |
| |enclosed in parentheses. | |
+--------------------+---------------------------------+--------------------+
|Password attribute |The attribute used |userPassword |
| |to store user | |
| |passwords | |
+--------------------+---------------------------------+--------------------+
|Active Directory |Tell if the LDAP |no |
| |server is an Active | |
| |Directory one | |
+--------------------+---------------------------------+--------------------+
|Administrator groups|Members of those LDAP Posix | |
| |groups will be created ad domain | |
| |administrators. Use ';' | |
| |characters to separate groups. | |
+--------------------+---------------------------------+--------------------+
|Group type |The type of group used by your |PosixGroup |
| |LDAP directory. | |
| | | |
| | | |
+--------------------+---------------------------------+--------------------+
|Groups search base |The distinguished name of the | |
| |search base used to find groups | |
| | | |
| | | |
+--------------------+---------------------------------+--------------------+
|Domain/mailbox |Automatically create a domain and|yes |
|creation |a mailbox when a new user is | |
| |created just after the first | |
| |successful authentication. You | |
| |will generally want to disable | |
| |this feature when the relay | |
| |domains extension is in use | |
+--------------------+---------------------------------+--------------------+
If you need additional parameters, you will find a detailed
documentation `here <http://packages.python.org/django-auth-ldap/>`_.
Once the authentication is properly configured, the users defined in
your LDAP directory will be able to connect to Modoboa, the associated
domain and mailboxes will be automatically created if needed.
The first time a user connects to Modoboa, a local account is created
if the LDAP username is a valid email address. By default, this
account belongs to the *SimpleUsers* group and it has a mailbox.
To automatically create domain administrators, you can use the
**Administrator groups** setting. If a LDAP user belongs to one the
listed groups, its local account will belong to the *DomainAdmins*
group. In this case, the username is not necessarily an email address.
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.
.. _smtp_auth:
SMTP
====
It is possible to use an existing SMTP server as an authentication
source. To enable this feature, edit the :file:`settings.py` file and
change the following setting:
.. sourcecode:: python
AUTHENTICATION_BACKENDS = (
'modoboa.lib.authbackends.SMTPBackend',
'django.contrib.auth.backends.ModelBackend',
)
SMTP server location can be customized using the following settings:
.. sourcecode:: python
AUTH_SMTP_SERVER_ADDRESS = 'localhost'
AUTH_SMTP_SERVER_PORT = 25
AUTH_SMTP_SECURED_MODE = None # 'ssl' or 'starttls' are accepted
.. _ldap_sync:
********************
LDAP synchronization
********************
Modoboa can synchronize accounts with an LDAP directory (tested with
OpenLDAP) but this feature is not enabled by default. To activate it,
add ``modoboa.ldapsync`` to ``MODOBOA_APPS`` in the
:file:`settings.py` file::
MODOBOA_APPS = (
'modoboa',
'modoboa.core',
'modoboa.lib',
'modoboa.admin',
'modoboa.transport',
'modoboa.relaydomains',
'modoboa.limits',
'modoboa.parameters',
'modoboa.dnstools',
'modoboa.ldapsync',
)
and enable it from the admin panel.
.. warning::
Make sure to install additional :ref:`requirements <ldap_auth>`
otherwise it won't work.
The following parameters are available and must be filled:
+--------------------+---------------------------------+--------------------+
|Name |Description |Default value |
+====================+=================================+====================+
|Enable LDAP |Control LDAP synchronization |no |
|synchronization |state | |
| | | |
+--------------------+---------------------------------+--------------------+
|Bind DN |The DN of a user with write | |
| |permission to create/update | |
| |accounts | |
+--------------------+---------------------------------+--------------------+
|Bind password |The associated password | |
| | | |
| | | |
+--------------------+---------------------------------+--------------------+
|Account DN template |The template used to build | |
| |account DNs (must contain a | |
| |%(user)s placeholder | |
+--------------------+---------------------------------+--------------------+
********************
Database maintenance
********************
Cleaning the logs table
=======================
Modoboa logs administrator specific actions into the database. A
clean-up script is provided to automatically remove oldest
records. The maximum log record age can be configured through the
online panel.
To use it, you can setup a cron job to run every night::
0 0 * * * <modoboa_site>/manage.py cleanlogs
#
# Or like this if you use a virtual environment:
# 0 0 * * * <virtualenv path/bin/python> <modoboa_site>/manage.py cleanlogs
Cleaning the session table
==========================
Django does not provide automatic purging. Therefore, it's your job to
purge expired sessions on a regular basis.
Django provides a sample clean-up script: ``django-admin.py
clearsessions``. That script deletes any session in the session table
whose ``expire_date`` is in the past.
For example, you could setup a cron job to run this script every night::
0 0 * * * <modoboa_site>/manage.py clearsessions
#
# Or like this if you use a virtual environment:
# 0 0 * * * <virtualenv path/bin/python> <modoboa_site>/manage.py clearsessions
.. _inactive_accounts:
Cleaning inactive accounts
==========================
Thanks to :ref:`lastlogin`, it is now possible to monitor inactive
accounts. An account is considered inactive if no login has been
recorded for the last 30 days (this value can be changed through the
admin panel).
A management command is available to disable or delete inactive
accounts. For example, you could setup a cron job to run it every
night::
0 0 * * * <modoboa_site>/manage.py clean_inactive_accounts
#
# Or like this if you use a virtual environment:
# 0 0 * * * <virtualenv path/bin/python> <modoboa_site>/manage.py clean_inactive_accounts
The default behaviour is to disable accounts. You can delete them
using the ``--delete`` option.
*************
DMARC reports
*************
.. _dmarcdoc:
A set of tools to use DMARC through Modoboa.
This feature is still in BETA stage, for now it only parses XML aggregated
reports and generate visual reports on a per-domain basis.
Installation
============
.. note::
modoboa-installer can automatically set it up for you.
Make sure to install the following additional system package according to your distribution:
+-----------------+
| Debian / Ubuntu |
+=================+
| libmagic1 |
+-----------------+
+------------+
| CentOS |
+============+
| file-devel |
+------------+
Integration with Postfix
========================
A management command is provided to automatically parse DMARC
aggregated reports (rua) and feed the database. The execution of this
command can be automated with the definition of a postfix service and
a custom transport table.
First, declare a new service in ``/etc/postfix/master.cf``::
dmarc-rua-parser unix - n n - - pipe
flags= user=vmail:vmail argv=<path to python> <path to modoboa instance>/manage.py import_aggregated_report --pipe
Define a new transport table inside ``/etc/postfix/main.cf``::
transport_maps =
hash:/etc/postfix/dmarc_transport
# other transport maps...
Create a file called ``/etc/postfix/dmarc_transport`` with the following content::
<email address your declared in your DNS record> dmarc-rua-parser:
.. note::
You must not declare this email address as an identity (user account or alias), else DMARC reports will be directed to your mailbox and won't be parsed.
Hash the file using the following command::
$ postmap /etc/postfix/dmarc_transport
Finally, reload postfix::
$ service postfix reload
doc/contributing.rst
-24
View File
@@ -1,24 +0,0 @@
#################
How to contribute
#################
Contributions are always welcome. If you want to submit a patch,
please respect the following rules:
- Open a pull request on the appropriate repository
- Respect `PEP8 <https://www.python.org/dev/peps/pep-0008/>`_
- Document your patch and respect `PEP 257 <https://www.python.org/dev/peps/pep-0257/>`_
- Add unit tests and make sure the global coverage does not decrease
If all those steps are validated, your contribution will generally be
integrated.
Table of contents
=================
.. toctree::
:maxdepth: 1
contributing/getting_started
contributing/plugin_api
contributing/translation
doc/contributing/getting_started.rst
-131
View File
@@ -1,131 +0,0 @@
###############
Getting started
###############
You would like to work on Modoboa but you don't know where to start?
You're at the right place! Browse this page to learn useful tips.
With Docker
===========
A docker image is available for developers. To use it, you must
install `docker <https://docs.docker.com/install/>`_ and
`docker-compose <https://docs.docker.com/compose/install/>`_ first.
If not already done, clone the repo and open it::
$ git clone https://github.com/modoboa/modoboa.git
$ cd modoboa
Then, just run the following command::
$ docker-compose up
Then if not done already, run this command to create an OIDC application
in order to be able to log in from the frontend:
.. sourcecode:: bash
$ docker exec modoboa-api '/bin/sh -c python3 /code/test_project/manage.py createapplication --name frontend --client-id "LVQbfIIX3khWR3nDvix1u9yEGHZUxcx53bhJ7FlD" --user 1 --algorithm RS256 --redirect-uris 'https://localhost:3000/login/logged' public authorization-code'
$ docker exec modoboa-api '/bin/sh -c python3 /code/test_project/manage.py createapplication --name Dovecot --skip-authorization --client-id=dovecot --client-secret=Toto12345 confidential client-credentials'
It will start the docker environment and make a Modoboa instance
available at ``https://localhost:8000`` and the new admin interface at ``https://localhost:3000``.
If you don't want to use docker or need a more complex development
setup, go to the next section.
Without Docker
==============
Prepare a virtual environment
-----------------------------
A `virtual environment
<https://docs.python.org/fr/3/library/venv.html>`_ is a good way to
setup a development environment on your machine.
To do so, run the following commands::
$ python3 -m venv <path>
$ source <path>/bin/activate
$ git clone https://github.com/modoboa/modoboa.git
$ cd modoboa
$ pip install -e .[dev]
This will create a symbolic link to your local copy so
any modification you make will be automatically available in your
environment, no need to copy them.
Deploy an instance for development
----------------------------------
.. warning::
Make sure to :ref:`create a database <database>` before running
this step. The format of the database url is also described in this
page.
Now that you have setup a development environment, you can deploy a
test instance and run it::
$ cd <path>
$ modoboa-admin.py deploy --dburl default:<database url> --domain localhost --devel instance
$ python manage.py runserver
You're ready to go! You should be able to access Modoboa at
``http://localhost:8000`` using ``admin:password`` as credentials.
Frontend
========
The 2.0 version of Modoboa introduces a completely new interface written
with the `Vue.js <https://vuejs.org/>`_ framework. The source files are
located in the :file:`frontend/` directory.
To set it up, you will need to install NodeJS and Yarn - to manage the
dependencies. Then, navigate to the :file:`frontend/` directory and run::
$ yarn install
You can now build it and serve it - while running your instance too to
serve the API - with::
$ yarn serve
Tests
=====
If you deployed an instance for development, you can launch the tests
from it with::
$ python manage.py test modoboa
You could also test just some them, i.e.::
$ python manage.py test modoboa.core.tests.test_authentication
Alternatively, you can use `tox <https://tox.readthedocs.io>`_ from
the repository to run all the tests and check the coverage with::
$ tox
You could limit the environment to a specific Python version with the
``-e py<version>`` argument.
Note that it is also possible to quickly run a test instance without
any deployment - e.g. to preview some changes - by running::
$ tox -e serve
Documentation
=============
The source files are located in the file:`doc/` folder and are written
in reStructuredText (reST). They are formatted in HTML and compiled
thanks to `Sphinx <https://www.sphinx-doc.org/en/master/>`_.
To build it and see the result, run::
$ tox -e doc
$ open .tox/doc/tmp/html/index.html
doc/contributing/plugin_api.rst
-205
View File
@@ -1,205 +0,0 @@
###################
Create a new plugin
###################
************
Introduction
************
Modoboa offers a plugin API to expand its capabilities. The current
implementation provides the following possibilities:
* Expand navigation by adding entry points to your plugin inside the GUI
* Access and modify administrative objects (domains, mailboxes, etc.)
* Register callback actions for specific events
Plugins are nothing more than Django applications with an extra piece
of code that integrates them into Modoboa. The
:file:`modo_extension.py` file will contain a complete description of
the plugin:
* Admin and user parameters
* Custom menu entries
The communication between both applications is provided by `Django
signals
<https://docs.djangoproject.com/en/2.2/topics/signals/>`_.
The following subsections describe the plugin architecture and explain
how you can create your own.
*****************
The required glue
*****************
To create a new plugin, just start a new django application like
this (into Modoboa's directory)::
$ python manage.py startapp
Then, you need to register this application using the provided
API. Just copy/paste the following example into the :file:`modo_extension.py` file
of the future extension::
from modoboa.core.extensions import ModoExtension, exts_pool
class MyExtension(ModoExtension):
"""My custom Modoboa extension."""
name = "myext"
label = "My Extension"
version = "0.1"
description = "A description"
url = "myext_root_location" # optional, name is used if not defined
def load(self):
"""This method is called when Modoboa loads available and activated plugins.
Declare parameters and register events here.
"""
pass
def load_initial_data(self):
"""Optional: provide initial data for your extension here."""
pass
exts_pool.register_extension(MyExtension)
Once done, simply add your extension's module name to the
``MODOBOA_APPS`` variable located inside :file:`settings.py`. Finally,
run the following commands::
$ python manage.py migrate
$ python manage.py load_initial_data
$ python manage.py collectstatic
**********
Parameters
**********
A plugin can declare its own parameters. There are two levels available:
* 'Global' parameters : used to configure the plugin, editable
inside the *Admin > Settings > Parameters* page
* 'User' parameters : per-user parameters (or preferences), editable
inside the *Options > Preferences* page
Playing with parameters
=======================
Parameters are defined using `Django forms
<https://docs.djangoproject.com/en/1.9/topics/forms/>`_ and Modoboa
adds two special forms you can inherit depending on the level of
parameter(s) you want to add:
* ``modoboa.parameters.forms.AdminParametersForm``: for general parameters
* ``modoboa.parameters.forms.UserParametersForm``: for user parameters
To register new parameters, add the following line into the ``load``
method of your plugin class::
from modoboa.parameters import tools as param_tools
param_tools.registry.add(
LEVEL, YourForm, ugettext_lazy("Title"))
Replace ``LEVEL`` by ``"global"`` or ``"user"``.
***********************
Custom role permissions
***********************
Modoboa uses Django's internal permission system. Administrative roles
are nothing more than groups (``Group`` instances).
An extension can add new permissions to a group by listening to the
``extra_role_permissions`` signal. Here is an example:
.. sourcecode:: python
from django.dispatch import receiver
from modoboa.core import signals as core_signals
PERMISSIONS = {
"Resellers": [
("relaydomains", "relaydomain", "add_relaydomain"),
("relaydomains", "relaydomain", "change_relaydomain"),
("relaydomains", "relaydomain", "delete_relaydomain"),
("relaydomains", "service", "add_service"),
("relaydomains", "service", "change_service"),
("relaydomains", "service", "delete_service")
]
}
@receiver(core_signals.extra_role_permissions)
def extra_role_permissions(sender, role, **kwargs):
"""Add permissions to the Resellers group."""
return constants.PERMISSIONS.get(role, [])
*********************
Extending admin forms
*********************
The forms used to edit objects (account, domain, etc.) through the admin
panel are composed of tabs. You can extend them (ie. add new
tabs) in a pretty easy way thanks to custom signals.
Account
=======
To add a new tab to the account edition form, define new listeners
(handlers) for the following signals:
* ``modoboa.admin.signals.extra_account_forms``
* ``modoboa.admin.signals.get_account_form_instances``
* ``modoboa.admin.signals.check_extra_account_form`` (optional)
Example:
.. sourcecode:: python
from django.dispatch import receiver
from modoboa.admin import signals as admin_signals
@receiver(admin_signals.extra_account_forms)
def extra_account_form(sender, user, account, **kwargs):
return [
{"id": "tabid", "title": "Title", "cls": MyFormClass}
]
@receiver(admin_signals.get_account_form_instances)
def fill_my_tab(sender, user, account, **kwargs):
return {"id": my_instance}
Domain
======
To add a new tab to the domain edition form, define new listeners
(handlers) for the following signals:
* ``modoboa.admin.signals.extra_domain_forms``
* ``modoboa.admin.signals.get_domain_form_instances``
Example:
.. sourcecode:: python
from django.dispatch import receiver
from modoboa.admin import signals as admin_signals
@receiver(admin_signals.extra_domain_forms)
def extra_account_form(sender, user, domain, **kwargs):
return [
{"id": "tabid", "title": "Title", "cls": MyFormClass}
]
@receiver(admin_signals.get_domain_form_instances)
def fill_my_tab(sender, user, domain, **kwargs):
return {"id": my_instance}
doc/contributing/translation.rst
-18
View File
@@ -1,18 +0,0 @@
###########
Translation
###########
Modoboa needs you to translate the project ! Feel free to join the translation team.
The project is using Transifex. To start with translation, you will need to create an account and join `modoboa's team <https://app.transifex.com/tonio/modoboa/dashboard/>`_
.. _translation:
Frontend
========
When editing the frontend, you may need to update localization files for transifex to pick up your changes.
To do so, after finishing editing, go to the frontend directory and run the following command::
$ make makemessages
doc/contributors.rst
-9
View File
@@ -1,9 +0,0 @@
Contributors
============
.. Add yourself
- `Antidot <http://antidot.com>`_
- `Bearstech <http://bearstech.com>`_
- `CAP-REL <https://cap-rel.fr/>`_
- `Dalnix <https://www.dalnix.se/>`_
doc/index.rst
-43
View File
@@ -1,43 +0,0 @@
.. Modoboa documentation master file, created by
sphinx-quickstart on Mon Jan 3 22:29:25 2011.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Modoboa documentation
=====================
.. image:: _static/modoboa_logo.png
:align: center
Overview
--------
Modoboa is a mail hosting and management platform including a modern
and simplified Web User Interface designed to work with `Postfix
<http://www.postfix.org>`_ and `Dovecot <http://www.dovecot.org>`_.
And it is extensible by nature and comes with a lot of additional extensions:
+---------------------------------------------------------+-------------------------+------------------------------------------------------+
|Name |Description |Documentation |
| | | |
| | | |
| | | |
+---------------------------------------------------------+-------------------------+------------------------------------------------------+
|`modoboa-pfxadmin-migrate |A tool to migrate from |https://github.com/modoboa/modoboa-pfxadmin-migrate |
|<https://github.com/modoboa/modoboa-pfxadmin-migrate>`_ |Postfixadmin | |
+---------------------------------------------------------+-------------------------+------------------------------------------------------+
Table of contents
-----------------
.. toctree::
:maxdepth: 1
installation
upgrade
configuration
moving
rest_api
contributing
contributors
doc/installation.rst
-101
View File
@@ -1,101 +0,0 @@
############
Installation
############
Requirements
===============
You will need a Server to perform well with at least:
* CPU: 2
* RAM: 2GB
* Disk: 10GB
* Python 3.8+
* Postgres 12+ or MariaDB 10.4+ or MySQL 8+ or sqlite3 or LDAP
.. note:: **👀 Heads up for modoboa versions 1.15 and later**
Python 2 support has been dropped with modoboa version 1.15.
If you still have Python 2 installed on your system either uninstall it
or force modoboa user to run with Python 3.
If you want to run virus scan on your server you will need **4GB** of RAM.
Recommended way
===============
If you start from scratch and want to deploy a complete mail server,
you will love the `modoboa installer
<https://github.com/modoboa/modoboa-installer>`_! It is the easiest
and the quickest way to setup a fully functional server (modoboa,
postfix, dovecot, amavis and more) on one machine.
.. warning::
For now, only Debian based Linux distributions are
supported. We do our best to improve compatibility but if you use
another Linux or a UNIX system, you will have to install Modoboa
:ref:`manually <by_hand>`.
To use it, just run the following commands in your terminal:
.. sourcecode:: bash
> git clone https://github.com/modoboa/modoboa-installer
> cd modoboa-installer
> sudo ./run.py <your domain>
if you get this warning - '/usr/bin/env: ‘python’: No such file or directory', do make sure sure python is installed on your server. Sometimes python is installed but the installer can't detect it or which python version to run, especially on a debian based system. Then run this command first.
.. sourcecode:: bash
> sudo apt-get install python3-virtualenv python3-pip
For the sake of simplicity, you can also install the ``python-is-python3`` package.
It allows you to use ``python`` command.
Wait a few minutes and you're done \o/
.. _by_hand:
Manual installation
===================
For those who need a manual installation or who just want to setup a
specific part, here are the steps you must follow:
.. toctree::
:maxdepth: 1
manual_installation/modoboa
manual_installation/webserver
manual_installation/dovecot
manual_installation/postfix
manual_installation/opendkim
manual_installation/radicale
manual_installation/amavis
Extensions
----------
Only few commands are needed to add a new extension to your setup.
In case you use a dedicated user and/or a virtualenv, do not forget to
use them:
.. sourcecode:: bash
> sudo -u <modoboa_user> -i bash
> source <virtuenv_path>/bin/activate
Then, run the following commands:
.. sourcecode:: bash
> pip install <EXTENSION>==<VERSION>
> cd <modoboa_instance_dir>
> python manage.py migrate
> python manage.py collectstatic
> python manage.py check --deploy
Then, restart your web server.
doc/manual_installation/amavis.rst
-292
View File
@@ -1,292 +0,0 @@
######
Amavis
######
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
<http://www.amavis.org/README.sql-mysql.txt>`_ and one for `PostgreSQL
<http://www.amavis.org/README.sql-pg.txt>`_.
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:<driver>:database=<database>;host=<dbhost>;port=<dbport>', '<dbuser>', '<password>]']);
@storage_sql_dsn =
(['DBI:<driver>:database=<database>;host=<dbhost>;port=<dbport>', '<dbuser>', '<password>]']);
# 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
<amavis_release>`.
.. note::
Amavis configuration allows for separate lookup and storage
databases but Modoboa doesn't support it yet.
.. note::
``$sql_partition_tag`` should remain undefined in ``amavisd.conf``. Modoboa
does not support the use of ``sql_partition_tag``, setting this value can
result in quarantined messages not showing or the wrong messages being
released or learnt as ham/spam.
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" : "<your value>",
"HOST" : "<your value>",
"NAME" : "<your value>",
"USER" : "<your value>",
"PASSWORD" : "<your value>"
}
}
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 * * * <modoboa_site>/manage.py qcleanup
#
# Or like this if you use a virtual environment:
# 0 0 * * * <virtualenv path/bin/python> <modoboa_site>/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
<http://www.ijs.si/software/amavisd/amavisd-new-docs.html#quar-release>`_. 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 * * * <modoboa_site>/manage.py amnotify --baseurl='<modoboa_url>'
#
# Or like this if you use a virtual environment:
# 0 12 * * * <virtualenv path/bin/python> <modoboa_site>/manage.py amnotify --baseurl='<modoboa_url>'
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 <http://amavis.org/README.customize.txt>`_ file to
learn what you're allowed to do.
Here is a link example::
https://<modoboa_url>/user/selfquarantine/%i/%R?secret_id=[:secret_id]
.. _sa_manual_learning:
Manual SpamAssassin learning
============================
It is possible to manually train `SpamAssassin
<http://spamassassin.apache.org/>`_ 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::<Driver>
bayes_sql_dsn <DSN>
bayes_sql_username <db username>
bayes_sql_password <db 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``).
doc/manual_installation/dovecot.rst
-602
View File
@@ -1,602 +0,0 @@
.. _dovecot:
#######
Dovecot
#######
Modoboa requires Dovecot 2+ to work so the following documentation is
suitable for this combination.
In this section, we assume dovecot's configuration resides in
:file:`/etc/dovecot`, all pathes will be relative to this directory.
You can find configuration documentation `here <https://doc.dovecot.org/configuration_manual/>`_.
This proposed configuration is the one you can find with modoboa-installer. For up to date configuration, `take a look here <https://github.com/modoboa/modoboa-installer/tree/master/modoboa_installer/scripts/files/dovecot/conf.d>`_
Packages
========
For debian and derivative, recommended packages are::
apt install dovecot-imapd dovecot-lmtpd dovecot-managesieved dovecot-sieve
Mailboxes
=========
First, edit the :file:`conf.d/10-mail.conf` and set the ``mail_location``
variable::
# maildir
mail_location = maildir:~/Maildir
Then, edit the ``inbox`` namespace and add the following line::
inbox = yes
In order for dovecot to automaticaly create usual folders on account creation, edit the ``inbox`` namespace of :file:`15-mailboxes.conf`::
mailbox Drafts {
auto = subscribe
special_use = \Drafts
}
mailbox Junk {
auto = subscribe
special_use = \Junk
}
mailbox Sent {
auto = subscribe
special_use = \Sent
}
mailbox Trash {
auto = subscribe
special_use = \Trash
}
Starting dovecot 2.2.20+, you can add ``autoexpunge`` parameter to delete older message, for instance::
mailbox Trash {
auto = subscribe
special_use = \Trash
autoexpunge=30d
}
With dovecot 2.1+, it ensures all the special mailboxes will be
automaticaly created for new accounts.
For dovecot 2.0 and older, use the `autocreate
<http://wiki2.dovecot.org/Plugins/Autocreate>`_ plugin.
.. _fs_operations:
Operations on the file system
-----------------------------
.. warning::
Modoboa needs to access the ``dovecot`` binary to check its
version. To find the binary path, we use the ``which`` command
first and then try known locations (:file:`/usr/sbin/dovecot` and
:file:`/usr/local/sbin/dovecot`). If you installed dovecot in a
custom location, please tell us where the binary is by using the
``DOVECOT_LOOKUP_PATH`` setting (see :file:`settings.py`).
Three operation types are considered:
#. Mailbox creation
#. Mailbox renaming
#. Mailbox deletion
The first one is managed by Dovecot. The last two ones may be managed
by Modoboa if it can access the file system where the mailboxes are
stored (see :ref:`admin-params` to activate this feature).
Those operations are treated asynchronously by a cron script. For
example, when you rename an e-mail address through the web UI, the
associated mailbox on the file system is not modified
directly. Instead of that, a *rename* order is created for this
mailbox. The mailbox will be considered unavailable until the order is
executed (see :ref:`Postfix configuration <postfix_config>`).
Edit the crontab of the user who owns the mailboxes on the file system::
$ crontab -u <vmail_user> -e
And add the following line inside::
* * * * * python <modoboa_instance>/manage.py handle_mailbox_operations
.. warning::
The cron script must be executed by the system user owning the mailboxes.
.. warning::
The user running the cron script must have access to the
:file:`settings.py` file of the modoboa instance.
The result of each order is recorded into Modoboa's log. Go to
*Modoboa > Logs* to consult them.
.. _dovecot_authentication:
Authentication
==============
To make the authentication work, edit the :file:`conf.d/10-auth.conf` and
uncomment the following line at the end::
#!include auth-system.conf.ext
!include auth-sql.conf.ext
#!include auth-ldap.conf.ext
#!include auth-passwdfile.conf.ext
#!include auth-checkpassword.conf.ext
#!include auth-vpopmail.conf.ext
#!include auth-static.conf.ext
Then, edit the :file:`conf.d/auth-sql.conf.ext` file and add the following
content inside::
passdb sql {
driver = sql
# Path for SQL configuration file, see example-config/dovecot-sql.conf.ext
args = /etc/dovecot/dovecot-sql.conf.ext
}
userdb sql {
driver = sql
args = /etc/dovecot/dovecot-sql.conf.ext
}
Make sure to activate only one backend (per type) inside your configuration
(just comment the other ones).
Edit the :file:`dovecot-sql.conf.ext` and modify the configuration according
to your database engine.
.. _dovecot_mysql_queries:
MySQL users
-----------
For debian and derivative, you need to install mysql connector for dovecot::
sudo apt install dovecot-mysql
::
driver = mysql
connect = host=<mysqld socket> dbname=<database> user=<user> password=<password>
default_pass_scheme = CRYPT
user_query = \
SELECT '%{home_dir}/%%d/%%n' AS home, %mailboxes_owner_uid as uid, \
%mailboxes_owner_gid as gid, \
CONCAT('*:bytes=', mb.quota, 'M') AS quota_rule \
FROM admin_mailbox mb \
INNER JOIN admin_domain dom ON mb.domain_id=dom.id \
INNER JOIN core_user u ON u.id=mb.user_id \
WHERE (mb.is_send_only=0 OR '%s' NOT IN ('imap', 'pop3', 'lmtp')) \
AND mb.address='%%n' AND dom.name='%%d'
password_query = \
SELECT email AS user, password, '%{home_dir}/%%d/%%n' AS userdb_home, \
%mailboxes_owner_uid AS userdb_uid, %mailboxes_owner_gid AS userdb_gid, \
CONCAT('*:bytes=', mb.quota, 'M') AS userdb_quota_rule \
FROM core_user u \
INNER JOIN admin_mailbox mb ON u.id=mb.user_id \
INNER JOIN admin_domain dom ON mb.domain_id=dom.id \
WHERE (mb.is_send_only=0 OR '%s' NOT IN ('imap', 'pop3')) \
AND u.email='%%u' AND u.is_active=1 AND dom.enabled=1
iterate_query = SELECT email AS user FROM core_user WHERE is_active
.. _dovecot_pg_queries:
PostgreSQL users
----------------
For debian and derivative, you need to install postgres connector for dovecot::
sudo apt install dovecot-pgsql
::
driver = pgsql
connect = host=<postgres socket> dbname=<database> user=<user> password=<password>
default_pass_scheme = CRYPT
user_query = \
SELECT '%{home_dir}/%%d/%%n' AS home, %mailboxes_owner_uid as uid, \
%mailboxes_owner_gid as gid, '*:bytes=' || mb.quota || 'M' AS quota_rule \
FROM admin_mailbox mb \
INNER JOIN admin_domain dom ON mb.domain_id=dom.id \
INNER JOIN core_user u ON u.id=mb.user_id \
WHERE (mb.is_send_only IS NOT TRUE OR '%s' NOT IN ('imap', 'pop3', 'lmtp')) \
AND mb.address='%%n' AND dom.name='%%d'
password_query = \
SELECT email AS user, password, '%{home_dir}/%%d/%%n' AS userdb_home, \
%mailboxes_owner_uid AS userdb_uid, %mailboxes_owner_gid AS userdb_gid, \
CONCAT('*:bytes=', mb.quota, 'M') AS userdb_quota_rule \
FROM core_user u \
INNER JOIN admin_mailbox mb ON u.id=mb.user_id \
INNER JOIN admin_domain dom ON mb.domain_id=dom.id \
WHERE (mb.is_send_only IS NOT TRUE OR '%s' NOT IN ('imap', 'pop3'))\
AND email='%%u' AND is_active AND dom.enabled
iterate_query = SELECT email AS user FROM core_user WHERE is_active
SQLite users
------------
For debian and derivative, you need to install sqlite connector for dovecot::
sudo apt install dovecot-sqlite
::
driver = sqlite
connect = <path to the sqlite db file>
default_pass_scheme = CRYPT
password_query = SELECT email AS user, password FROM core_user u INNER JOIN admin_mailbox mb ON u.id=mb.user_id INNER JOIN admin_domain dom ON mb.domain_id=dom.id WHERE u.email='%Lu' AND u.is_active=1 AND dom.enabled=1
user_query = SELECT '<mailboxes storage directory>/%Ld/%Ln' AS home, <uid> as uid, <gid> as gid, ('*:bytes=' || mb.quota || 'M') AS quota_rule FROM admin_mailbox mb INNER JOIN admin_domain dom ON mb.domain_id=dom.id WHERE mb.address='%Ln' AND dom.name='%Ld'
iterate_query = SELECT email AS user FROM core_user
.. note::
Replace values between ``<>`` with yours.
.. _dovecot_oauth2:
OAuth 2 authentication
======================
You first need to register Dovecot as an authorized consumer of the
OAuth2 authentication service provided by Modoboa. To do so, create an
application with the following commands:
.. sourcecode:: bash
> cd <modoboa_instance_path>
> python manage.py createapplication --name=Dovecot --skip-authorization --client-id=dovecot confidential client-credentials
On success, you should see an output similar to::
New application Dovecot created successfully.
client_secret: XXXX
To enable OAuth2 authentication in Dovecot, edit the :file:`conf.d/10-auth.conf`
file and update the auth_mechanisms line as follows::
auth_mechanisms = plain login oauthbearer xoauth2
Then, add the following line at the end::
!include auth-oauth2.conf.ext
Then, create a file named :file:`conf.d/auth-oauth2.conf.ext` with the
following content::
passdb {
driver = oauth2
mechanisms = xoauth2 oauthbearer
args = /etc/dovecot/conf.d/dovecot-oauth2.conf.ext
}
Finally, create a file named :file:`conf.d/dovecot-oauth2.conf.ext` with the
following content::
introspection_mode = post
introspection_url = https://dovecot:<client_secret>@<hostname of your server>/api/o/introspect/
username_attribute = username
tls_ca_cert_file = /etc/ssl/certs/ca-certificates.crt
active_attribute = active
active_value = true
Replace ``<client_secret>`` with the value you obtained earlier.
LDAP
====
To make the LDAP authentication work, edit the :file:`conf.d/10-auth.conf` and
uncomment the following line at the end::
!include auth-ldap.conf.ext
Then edit the :file:`conf.d/auth-ldap.conf.ext` and edit the passdb section as following.
You should comment the userdb section, which will be managed by SQL with modoboa database.::
passdb {
driver = ldap
# Path for LDAP configuration file, see example-config/dovecot-ldap.conf.ext
args = /etc/dovecot/dovecot-ldap.conf.ext
}
#userdb {
#driver = ldap
#args = /etc/dovecot/dovecot-ldap.conf.ext
# Default fields can be used to specify defaults that LDAP may override
#default_fields = home=/home/virtual/%u
#}
Your own dovecot LDAP configuration file is now :file:`/etc/dovecot/dovecot-ldap.conf.ext`.
You can add your default LDAP conf in it, following the `official documentation <https://doc.dovecot.org/configuration_manual/authentication/ldap/>`_.
Synchronize dovecot LDAP conf with modoboa LDAP conf
----------------------------------------------------
To make dovecot LDAP configuration synchronized with modoboa LDAP configuration, you should create a dedicated dovecot conf file.
At the end of your dovecot configuration file (:file:`dovecot-ldap.conf.ext`), add the following line::
!include_try dovecot-modoboa.conf.ext
Then, set modoboa parameter *Enable Dovecot LDAP sync* to *Yes*.
Then set the *Dovecot LDAP config file* following the previous step (*/etc/dovecot/dovecot-modoboa.conf.ext* in the example)
The last step is to add the command **update_dovecot_conf** to the cron job of modoboa.
Then, each time your modoboa LDAP configuration is updated, your dovecot LDAP configuration will also be.
LMTP
====
`Local Mail Transport Protocol
<http://en.wikipedia.org/wiki/Local_Mail_Transfer_Protocol>`_ is used
to let Postfix deliver messages to Dovecot.
First, make sure the protocol is activated by looking at the
``protocols`` setting (generally inside
:file:`dovecot.conf`). It should be similar to the following example::
protocols = imap pop3 lmtp
Then, open the :file:`conf.d/10-master.conf`, look for ``lmtp``
service definition and add the following content inside::
service lmtp {
# stuff before
unix_listener /var/spool/postfix/private/dovecot-lmtp {
mode = 0600
user = postfix
group = postfix
}
# stuff after
}
We assume here that Postfix is *chrooted* within
:file:`/var/spool/postfix`.
Finally, open the :file:`conf.d/20-lmtp.conf` and modify it as follows::
protocol lmtp {
postmaster_address = postmaster@<domain>
mail_plugins = $mail_plugins quota sieve
}
Replace ``<domain>`` by the appropriate value.
.. note::
If you don't plan to apply quota or to use filters, just adapt the
content of the ``mail_plugins`` setting.
.. _dovecot_quota:
Quota
=====
Modoboa lets adminstrators define per-domain and/or per-account limits
(quota). It also lists the current quota usage of each account. Those
features require Dovecot to be configured in a specific way.
Inside :file:`conf.d/10-mail.conf`, add the ``quota`` plugin to the default
activated ones::
mail_plugins = quota
Inside :file:`conf.d/10-master.conf`, update the ``dict`` service to set
proper permissions::
service dict {
# If dict proxy is used, mail processes should have access to its socket.
# For example: mode=0660, group=vmail and global mail_access_groups=vmail
unix_listener dict {
mode = 0600
user = <user owning mailboxes>
#group =
}
}
Inside :file:`conf.d/20-imap.conf`, activate the ``imap_quota`` plugin::
protocol imap {
# ...
mail_plugins = $mail_plugins imap_quota
# ...
}
Inside :file:`dovecot.conf`, activate the quota SQL dictionary backend::
dict {
quota = <driver>:/etc/dovecot/dovecot-dict-sql.conf.ext
}
Inside :file:`conf.d/90-quota.conf`, activate the *quota dictionary* backend::
plugin {
quota = dict:User quota::proxy::quota
}
It will tell Dovecot to keep quota usage in the SQL dictionary.
Finally, edit the :file:`dovecot-dict-sql.conf.ext` file and put the
following content inside::
connect = host=<db host> dbname=<db name> user=<db user> password=<password>
# SQLite users
# connect = /path/to/the/database.db
map {
pattern = priv/quota/storage
table = admin_quota
username_field = username
value_field = bytes
}
map {
pattern = priv/quota/messages
table = admin_quota
username_field = username
value_field = messages
}
*PostgreSQL* users
------------------
Database schema update
^^^^^^^^^^^^^^^^^^^^^^
The ``admin_quota`` table is created by Django but unfortunately it
doesn't support ``DEFAULT`` constraints (it only simulates them when the
ORM is used). As PostgreSQL is a bit strict about constraint
violations, you must execute the following query manually::
db=> ALTER TABLE admin_quota ALTER COLUMN bytes SET DEFAULT 0;
db=> ALTER TABLE admin_quota ALTER COLUMN messages SET DEFAULT 0;
Trigger
^^^^^^^
As indicated on `Dovecot's wiki
<http://wiki2.dovecot.org/Quota/Dict>`_, you need a trigger to
properly update the quota.
A working copy of this trigger is available on `Github <https://raw.githubusercontent.com/modoboa/modoboa-installer/master/modoboa_installer/scripts/files/dovecot/install_modoboa_postgres_trigger.sql>`_.
Download this file and copy it on the server running postgres. Then,
execute the following commands::
$ su - postgres
$ psql [modoboa database] < /path/to/modoboa_postgres_trigger.sql
$ exit
Replace ``[modoboa database]`` by the appropriate value.
Forcing recalculation
---------------------
For existing installations, *Dovecot* (> 2) offers a command to
recalculate the current quota usages. For example, if you want to
update all usages, run the following command::
$ doveadm quota recalc -A
Be carefull, it can take a while to execute.
ManageSieve/Sieve
=================
Modoboa lets users define filtering rules from the web interface. To
do so, it requires *ManageSieve* to be activated on your server.
Inside :file:`conf.d/20-managesieve.conf`, make sure the following lines are
uncommented::
protocols = $protocols sieve
service managesieve-login {
# ...
}
service managesieve {
# ...
}
protocol sieve {
# ...
}
Finally, configure the ``sieve`` plugin by editing the
:file:`conf.d/90-sieve.conf` file. Put the follwing caontent inside::
plugin {
# 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.
Now, you can go to the :ref:`postfix` section to finish the installation.
.. _lastlogin:
Last-login tracking
===================
To update the ``last_login`` attribute of an account after a succesful
IMAP or POP3 login, you can configure a `post-login script
<https://wiki.dovecot.org/PostLoginScripting>`_.
Open :file:`conf.d/10-master.conf` add the following configuration
(``imap`` and ``pop3`` services are already defined, you just need to
update them)::
service imap {
executable = imap postlogin
}
service pop3 {
executable = pop3 postlogin
}
service postlogin {
executable = script-login /usr/local/bin/postlogin.sh
user = modoboa
unix_listener postlogin {
}
}
Then, you must create a script named
:file:`/usr/local/bin/postlogin.sh`. According to your database
engine, the content will differ.
PostgreSQL
----------
.. sourcecode:: bash
#!/bin/sh
psql -c "UPDATE core_user SET last_login=now() WHERE username='$USER'" > /dev/null
exec "$@"
MySQL
-----
.. sourcecode:: bash
#!/bin/sh
DBNAME=XXX
DBUSER=XXX
DBPASSWORD=XXX
echo "UPDATE core_user SET last_login=now() WHERE username='$USER'" | mysql -u $DBUSER -p$DBPASSWORD $DBNAME
exec "$@"
doc/manual_installation/modoboa.rst
-326
View File
@@ -1,326 +0,0 @@
.. _modoboa_manual_install:
#######
Modoboa
#######
This section describes the installation of the web interface (a
`Django <https://www.djangoproject.com/>`_ project).
This proposed configuration is the one you can find with modoboa-installer. For up to date configuration, `take a look here <https://github.com/modoboa/modoboa-installer/tree/master/modoboa_installer/scripts/files/modoboa/>`_
Prepare the system
------------------
First of all, we recommend the following context:
* A dedicated system user
* A `virtual environment
<https://packaging.python.org/tutorials/installing-packages/#creating-virtual-environments>`_
to install the application because it will isolate it (and its
dependencies) from the rest of your system
The following example illustrates how to realize this on Debian-based
distributions using `virtualenv <https://virtualenv.pypa.io/en/stable/>`_:
.. code-block:: console
# apt-get install virtualenv python3-pip
# useradd modoboa # create a dedicated user
# sudo -u modoboa -i bash # log in as the newly created user
$ virtualenv --python python3 ./env # create the virtual environment
$ source ./env/bin/activate # activate the virtual environment
Modoboa depends on external tools and some of them require compilation
so you need a compiler and a few C libraries. Make sure to install the
following system packages according to your distribution:
+-------------------------------+
| Debian / Ubuntu |
+===============================+
| build-essential python3-dev |
| libxml2-dev libxslt-dev |
| libjpeg-dev librrd-dev |
| rrdtool libffi-dev libssl-dev |
| pkg-config libcairo2-dev |
+-------------------------------+
+-----------------------------+
| CentOS |
+=============================+
| gcc gcc-c++ python3-devel |
| libxml2-devel libxslt-devel |
| libjpeg-turbo-devel |
| rrdtool-devel rrdtool |
| libffi-devel |
+-----------------------------+
.. note::
Alternatively, you could rely on your distribution packages for the Modoboa
dependencies which require compilation - e.g. ``rrdtool`` - if the version
is compatible. In this case, you have to create your virtual environment
with the ``--system-site-packages`` option, and the required system
packages will be:
+---------------------------------------+
| python3-wheel python3-rrdtool rrdtool |
+---------------------------------------+
Then, install Modoboa by running:
.. code-block:: console
(env)$ pip install modoboa
.. _database:
Database
--------
.. warning::
This documentation does not cover the installation of a database
server but only the setup of a functional database that Modoboa
will use.
Thanks to Django, Modoboa is compatible with the following databases:
* PostgreSQL
* MySQL / MariaDB
* SQLite
Since the last one does not require particular actions, only the first
two ones are described. You should also read the notes for those database
backends on the `official Django documentation
<https://docs.djangoproject.com/en/stable/ref/databases/>`_.
PostgreSQL
**********
Install the corresponding Python binding:
.. code-block:: console
(env)$ pip install psycopg[binary]>=3.1
.. note::
Ubuntu and Debian repositories contain python-psycopgX package
but starting modoboa 2.2.0 minimum version required is 3.1 and
it has not yet it these distro yet
Prior modoboa version can run with ``python3-psycopg2``.
Then, create a user and a database. For example, to create the ``modoboa``
database owned by a ``modoboa`` user, run the following commands on your
PostgreSQL server:
.. code-block:: console
# sudo -l -u postgres createuser --no-createdb modoboa
# sudo -l -u postgres createdb --owner=modoboa modoboa
MySQL / MariaDB
***************
Install the corresponding Python binding:
.. code-block:: console
(env)$ pip install mysqlclient
.. note::
Alternatively, you can install the ``python3-mysqldb`` package instead on
Debian-based distributions if your virtual environment was created with
``--system-site-packages`` option.
.. note::
MariaDB 10.2 (and newer) require mysqlclient 1.3.11 (or newer).
Then, create a user and a database. For example, to create the ``modoboa``
database owned by a ``modoboa`` user, run the following SQL commands:
.. code-block:: mysql
CREATE DATABASE modoboa;
CREATE USER 'modoboa'@'localhost' IDENTIFIED BY 'my-strong-password-here';
GRANT ALL PRIVILEGES ON modoboa.* TO 'modoboa'@'localhost';
.. _deployment:
Deploy an instance
------------------
``modoboa-admin.py`` is a command line tool that lets you deploy a
*ready-to-use* Modoboa site. To create a new instance into ``./instance``,
you just have to run the following command:
.. code-block:: console
(env)$ modoboa-admin.py deploy instance --collectstatic \
--domain <hostname of your server> --dburl default:<database url>
.. note::
You can install additional extensions during the deploy process. To
do so, use the ``--extensions`` option which accepts a list of
names as argument (``--extensions ext1 ext2 ...``). If you want to
install all extensions, just use the ``all`` keyword like this
``--extensions all``.
If you choose to install extensions one at a time, you will have to
add their names in settings.py to ``MODOBOA_APPS``. Also ensure that
you have the line ``from modoboa_amavis.settings import *`` at the
end of this file and possibly perform more steps. Check the
documentation/readme of each extensions for specific Instructions.
The list of available extensions can be found on the :doc:`index
page <../index>`. Instructions to install them are available on
each extensions page.
.. note::
You can specify more than one database connection using the
``--dburl`` option. Multiple connections are differentiated by a
prefix.
The primary connection must use the ``default:`` prefix (as shown
in the example above). For the `amavis
<http://modoboa-amavis.readthedocs.org>`_ extension, use the
``amavis:`` prefix. For example: ``--dburl
default:<database url> amavis:<database url>``.
A database url should meet the following syntax
``<mysql|postgres>://[user:pass@][host:port]/dbname`` **OR**
``sqlite:////full/path/to/your/database/file.sqlite``.
Fox example, if you were using postgres, you could setup your command like this:
``modoboa-admin.py deploy instance_name --collectstatic --domain example.com --dburl default:postgres://user:pass@[localhost]/modoboa``
The command will ask you a few questions, answer them and you're
done.
If you need a **silent installation** (e.g. if you're using
Salt-Stack, Ansible or whatever), it's possible to supply the database
credentials as command line arguments.
You can consult the complete option list by running the following
command:
.. code-block:: console
(env)$ modoboa-admin.py help deploy
Cron jobs
---------
A few recurring jobs must be configured to make Modoboa works as
expected.
Create a new file, for example :file:`/etc/cron.d/modoboa` and put the
following content inside:
.. sourcecode:: bash
#
# Modoboa specific cron jobs
#
PYTHON=<path to Python binary inside the virtual environment>
INSTANCE=<path to Modoboa instance>
# Operations on mailboxes
* * * * * <mailbox user> $PYTHON $INSTANCE/manage.py handle_mailbox_operations
# Generate DKIM keys (they will belong to the user running this job)
* * * * * root umask 077 && $PYTHON $INSTANCE/manage.py modo manage_dkim_keys
# Sessions table cleanup
0 0 * * * root $PYTHON $INSTANCE/manage.py clearsessions
# Logs table cleanup
0 0 * * * root $PYTHON $INSTANCE/manage.py cleanlogs
# Logs parsing
*/15 * * * * root $PYTHON $INSTANCE/manage.py logparser &> /dev/null
0 * * * * modoboa $PYTHON $INSTANCE/manage.py update_statistics
# DNSBL checks
*/30 * * * * modoboa $PYTHON $INSTANCE/manage.py modo check_mx
# Public API communication
0 * * * * modoboa $PYTHON $INSTANCE/manage.py communicate_with_public_api
.. hint:: **🥵 potential high load configuration**
Please note that above crontab might not be ideal on high load systems.
If you receive a fairly high amount of emails per day, you may want to
run modoboas logparser tasks *once per night*.
This has the down side that the statistic graph and message log within
the UI are updated once per day only.
.. _policy_daemon:
Policy daemon
-------------
Modoboa comes with a built-in `Policy Daemon for Postfix <http://www.postfix.org/SMTPD_POLICY_README.html>`_. Current features are:
* Define daily sending limits for domains and/or accounts
A `redis server <https://redis.io/>`_ is required to run this new daemon.
You can launch it manually using the following command:
.. sourcecode:: bash
(env)> python manage.py policy_daemon
But we recommend an automatic start using ``systemd`` or
``supervisor``. Here is a configuration example for ``supervisor``:
.. sourcecode:: ini
[program:policyd]
autostart=true
autorestart=true
command=<path to Python binary inside the virtual environment> <path to Modoboa instance>/manage.py policy_daemon
directory=<modoboa user home dir>
redirect_stderr=true
user=modoboa
numprocs=1
It will listen by default on ``127.0.0.1`` and port ``9999``. The
policy daemon won't do anything unless you tell :ref:`postfix <policyd_config>` to use it.
RQ daemon
---------
Modoboa uses `RQ <https://python-rq.org>`_ as a job handler for async task.
A `redis server <https://redis.io/>`_ is required to run this new daemon.
A worker needs to be launched in the venv.
You can launch it manually using the following command:
.. sourcecode:: bash
(env)> rq worker high default low
But we recommend an automatic start using ``systemd`` or
``supervisor``. Here is a configuration example for ``supervisor``:
.. sourcecode:: ini
[program:modoboa-dkim-worker]
autostart=true
autorestart=true
command=<path to Python binary inside the virtual environment> <path to Modoboa instance>/manage.py rqworker dkim
directory=<modoboa user home dir>
user=<opendkim user>
redirect_stderr=true
numprocs=1
stopsignal=TERM
Now you can continue to the :ref:`webserver` section.
doc/manual_installation/opendkim.rst
-81
View File
@@ -1,81 +0,0 @@
########
OpenDKIM
########
Modoboa can generate `DKIM
<https://en.wikipedia.org/wiki/DomainKeys_Identified_Mail>`_ keys for
the hosted domains but it won't sign or check messages. To do that,
you need a dedicated software like `OpenDKIM <http://opendkim.org/>`_.
.. note::
The cron job in charge of creating DKIM keys must be run using the
same user than OpenDKIM (ie. opendkim in most cases).
Database
========
Since keys related information is stored in Modoboa's database, you
need to tell OpenDKIM how it can access it.
First, make sure to install the required additional packages on your
system (``libopendbx1-*`` on debian based distributions or ``opendbx-*``
on CentOS, the complete name depends on your database engine).
Then, insert the following SQL view into Modoboa's database:
PostgreSQL
----------
::
CREATE OR REPLACE VIEW dkim AS (
SELECT id, name as domain_name, dkim_private_key_path AS private_key_path,
dkim_key_selector AS selector
FROM admin_domain WHERE enable_dkim
);
MySQL/MariaDB
-------------
::
CREATE OR REPLACE VIEW dkim AS (
SELECT id, name as domain_name, dkim_private_key_path AS private_key_path,
dkim_key_selector AS selector
FROM admin_domain WHERE enable_dkim=1
);
Configuration
=============
You should find OpenDKIM's configuration file at :file:`/etc/opendkim.conf`.
Add the following content to it::
KeyTable dsn:<driver>://<user>:<password>@<db host>/<db name>/table=dkim?keycol=id?datacol=domain_name,selector,private_key_path
SigningTable dsn:<driver>://<user>:<password>@<db host>/<db name>/table=dkim?keycol=domain_name?datacol=id
Socket inet:12345@localhost
Replace values between ``<>`` by yours. Accepted values for ``driver``
are ``pgsql`` or ``mysql``. Make sure the user you specify has read
permission on the view created previously.
If you run a debian based system, make sure to adjust the following
setting in the :file:`/etc/default/opendkim` file::
SOCKET=inet:12345@localhost
Eventually, reload OpenDKIM.
Postfix integration
===================
Add the following lines to the :file:`/etc/postfix/main.cf` file::
smtpd_milters = inet:127.0.0.1:12345
non_smtpd_milters = inet:127.0.0.1:12345
milter_default_action = accept
milter_content_timeout = 30s
and reload postfix.
doc/manual_installation/postfix.rst
-109
View File
@@ -1,109 +0,0 @@
.. _postfix:
#######
Postfix
#######
This section gives an example about building a simple virtual hosting
configuration with *Postfix*. Refer to the `official documentation
<http://www.postfix.org/VIRTUAL_README.html>`_ for more explanation.
Map files
=========
You first need to create configuration files (or map files) that will
be used by Postfix to lookup into Modoboa tables.
To automaticaly generate the requested map files and store them in a
directory, run the following command:
.. sourcecode:: bash
> cd <modoboa_instance_path>
> python manage.py generate_postfix_maps --destdir <directory>
``<directory>`` is the directory where the files will be
stored. Answer the few questions and you're done.
.. _postfix_config:
Configuration
=============
Use the following configuration in the :file:`/etc/postfix/main.cf` file. For TLS configuration, you can look at the
`used configuration <https://github.com/modoboa/modoboa-installer/blob/master/modoboa_installer/scripts/files/postfix/main.cf.tpl>`_
for `modoboa installer <https://github.com/modoboa/modoboa-installer>`_.
(this is just one possible configuration)::
# Stuff before
unknown_local_recipient_reject_code = 550
unverified_recipient_reject_code = 550
# appending .domain is the MUA's job.
append_dot_mydomain = no
## Proxy maps
proxy_read_maps =
proxy:unix:passwd.byname
proxy:<driver>:/etc/postfix/sql-domains.cf
proxy:<driver>:/etc/postfix/sql-domain-aliases.cf
proxy:<driver>:/etc/postfix/sql-aliases.cf
proxy:<driver>:/etc/postfix/sql-relaydomains.cf
proxy:<driver>:/etc/postfix/sql-maintain.cf
proxy:<driver>:/etc/postfix/sql-relay-recipient-verification.cf
proxy:<driver>:/etc/postfix/sql-sender-login-map.cf
proxy:<driver>:/etc/postfix/sql-spliteddomains-transport.cf
proxy:<driver>:/etc/postfix/sql-transport.cf
## Virtual transport settings
virtual_transport = lmtp:unix:private/dovecot-lmtp
virtual_mailbox_domains = proxy:<driver>:/etc/postfix/sql-domains.cf
virtual_alias_domains = proxy:<driver>:/etc/postfix/sql-domain-aliases.cf
virtual_alias_maps = proxy:<driver>:/etc/postfix/sql-aliases.cf
## Relay domains
relay_domains = proxy:<driver>:/etc/postfix/sql-relaydomains.cf
transport_maps =
proxy:<driver>:/etc/postfix/sql-transport.cf
proxy:<driver>:/etc/postfix/sql-spliteddomains-transport.cf
smtpd_recipient_restrictions =
permit_mynetworks
permit_sasl_authenticated
check_recipient_access
proxy:<driver>:/etc/postfix/sql-maintain.cf
proxy:<driver>:/etc/postfix/sql-relay-recipient-verification.cf
reject_unverified_recipient
reject_unauth_destination
reject_non_fqdn_sender
reject_non_fqdn_recipient
reject_non_fqdn_helo_hostname
smtpd_sender_login_maps = proxy:<driver>:/etc/postfix/sql-sender-login-map.cf
# Stuff after
Replace ``<driver>`` by the name of the database you use.
Restart Postfix.
.. _policyd_config:
Policy daemon
-------------
If you want to enable the built-in policy daemon, add the following
content to the :file:`/etc/postfix/main.cf` file::
smtpd_recipient_restrictions =
# ...
check_policy_service inet:localhost:9999
# ...
And reload postfix.
.. note::
The ``check_policy_service`` line must be placed before the
``permit_mynetworks`` one, otherwise the daemon won't be called.
doc/manual_installation/radicale.rst
-127
View File
@@ -1,127 +0,0 @@
.. _radicale:
#######
Radicale
#######
This page is displaying how to install and use radicale when either having installed modoboa manually or with the dedicated installer.
.. _radicale_oauth2:
OAuth 2 authentication
======================
.. note::
These steps are automatic if you use an up-to-date modoboa-installer to install/upgrade.
Preparing the usage of radicale (manual install only)
-----------------------------------------------------
It is assumed you have not installed in the past radicale from your package manager and your modoboa installation is working correctly. If so, you may skip this section and proceed to the next one.
You will need to create directories for the radicale user, needed files and set-up the account (location may change depending on your OS and initial set-up).
.. sourcecode:: bash
> sudo mkdir /var/lib/radicale /etc/radicale
> sudo touch /etc/radicale/{rights,config}
> sudo adduser --system --home /var/lib/radicale/ --no-create-home --gecos "Radicale CalDAV server" --group --disabled-password --quiet radicale
> sudo chown -R radicale /etc/radicale
> sudo chown /var/lib/radicale
Creation of the virtual environment (manual install only)
---------------------------------------------------------
.. sourcecode:: bash
> sudo -u radicale virtualenv /var/lib/radicale/env
Installing radicale oauth plugin
--------------------------------
You need to install ``radicale-modoboa-auth-oauth2`` python package inside radicale venv.
If you used the installer you can use the following commands:
.. sourcecode:: bash
> sudo -u radicale -i bash
> cd ~
> env/bin/pip install radicale-modoboa-auth-oauth2
For manual installations, this will do the job:
.. sourcecode:: bash
> sudo -u radicale /var/lib/radicale/env/bin/pip install radicale-modoboa-auth-oauth2
Please note because the plugin offered by modoboa's team is listing radicale as a dependency you do not need to explicitely install radicale.
Oauth application creation
--------------------------
You first need to register Radicale as an authorized consumer of the
OAuth2 authentication service provided by Modoboa. To do so, create an
application with the following commands:
.. sourcecode:: bash
> cd <modoboa_instance_path>
> python manage.py createapplication --name=Radicale --skip-authorization --client-id=radicale confidential client-credentials
On success, you should see an output similar to::
New application Radicale created successfully.
client_secret: XXXX
To enable OAuth2 authentication in Radicale, edit the :file:`/etc/radicale/config`
file and update the `type` in `[auth]` to::
type = radicale_modoboa_auth_oauth2
Then, add the following line in `[auth]`::
oauth2_introspection_endpoint = https://radicale:<client_secret>@<hostname of your server>/api/o/introspect/
Replace ``<client_secret>`` with the value you obtained earlier.
Your :file:`/etc/radicale/config` should look like this (listening address and port may vary)::
[server]
hosts = 0.0.0.0:5232,[::]:5232
[auth]
type = radicale_modoboa_auth_oauth2
oauth2_introspection_endpoint = https://radicale:<client_secret>@<hostname of your server>/api/o/introspect/
[rights]
type = from_file
file = /etc/radicale/rights
[storage]
filesystem_folder = /var/lib/radicale/collections
With that set-up, radicale should be working when managing calendars through modoboa's web interface but _not_ when using other clients like Thunderbird.
Modifications for using external clients (optional)
---------------------------------------------------
To ensure other clients can identify, you need to modify radicale by adding in the config file under the [auth] section::
dovecot_socket = /run/dovecot/auth-radicale
and in 10-master.conf for dovecot::
unix_listener auth-radicale {
mode = 0660
user = radicale
group = dovecot
}
Then, restart both modoboa and radicale to enjoy managing calendars (ICS type) with your favorite client.
Reverse proxy for radicale (optional)
-------------------------------------
At this stage, no encryption is provided, and you may use a reverse proxy as described in `Radicale's documentation
<https://radicale.org/v3.html#reverse-proxy>`_.
doc/manual_installation/webserver.rst
-354
View File
@@ -1,354 +0,0 @@
.. _webserver:
##########
Web server
##########
.. note::
The following instructions are meant to help you get your site up
and running quickly. However it is not possible for the people
contributing documentation to Modoboa to test every single
combination of web server, wsgi server, distribution, etc. So it is
possible that **your** installation of uwsgi or nginx or Apache or
what-have-you works differently. Keep this in mind.
.. _apache2:
Apache2
*******
First, make sure that ``mod_wsgi`` is installed on your server.
Create a new virtualhost in your Apache configuration and put the
following content inside::
WSGIPythonHome /var/www/modoboa/env
WSGIPythonPath /var/www/modoboa/instance
<VirtualHost *:80>
ServerName <your value>
DocumentRoot <modoboa_instance_path>
Alias /media/ <modoboa_instance_path>/media/
<Directory <modoboa_instance_path>/media/>
Options FollowSymLinks
Require all granted
</Directory>
Alias /sitestatic/ <modoboa_instance_path>/sitestatic/
<Directory <modoboa_instance_path>/sitestatic/>
Options FollowSymLinks
Require all granted
</Directory>
WSGIScriptAliasMatch ^/(api|accounts) <modoboa_instance_path>/instance/wsgi.py
WSGIApplicationGroup %{GLOBAL}
# Pass Authorization header to enable API usage:
WSGIPassAuthorization On
Alias / <modoboa_instance_path>/frontend
<Directory <modoboa_instance_path>/frontend>
Options FollowSymLinks
Require all granted
</Directory>
LogLevel info
</VirtualHost>
This is just one possible configuration.
Replace values between ``<>`` with yours. If you don't use a
`virtualenv <http://virtualenv.readthedocs.org/en/latest/>`_, just
remove the last part of the ``WSGIDaemonProcess`` directive.
.. note::
You may need to add::
import sys
sys.path.append('<modoboa_instance_path>')
sys.path.append('<modoboa_venv_path>/bin')
sys.path.append('<modoboa_venv_path>/lib/python3.X/site-packages')
in :file:`<modoboa_instance_path>/instance/wsgi.py`.
.. note::
You will certainly need more configuration in order to launch
Apache.
Now, you can go the :ref:`dovecot` section to continue the installation.
.. _nginx-label:
Nginx
*****
This section covers two different ways of running Modoboa behind
`Nginx <http://nginx.org/>`_ using a WSGI application server. Choose
the one you prefer between `Green Unicorn <http://gunicorn.org/>`_ or
`uWSGI <https://github.com/unbit/uwsgi>`_.
In both cases, you'll need to download and `install nginx
<http://wiki.nginx.org/Install>`_.
uWSGI
+++++
The following setup is meant to get you started quickly. You should
read the documentation of both nginx and uwsgi to understand how to
optimize their configuration for your site.
The Django documentation includes the following warning regarding
uwsgi:
.. warning::
Use uwsgi 1.2.6 or newer. If you do not, you *will* run into
problems. Modoboa will fail in obscure ways.
To use this setup, first `download and install uwsgi
<http://uwsgi-docs.readthedocs.org/en/latest/WSGIquickstart.html>`_.
Recommend packages for debian and derivatives::
apt install uwsgi uwsgi-plugin-python3
Here is a sample nginx configuration::
upstream modoboa {
server unix:<uwsgi_socket_path> fail_timeout=0;
}
server {
listen 80;
listen [::]:80;
server_name <hostname>;
rewrite ^ https://$server_name$request_uri? permanent;
}
server {
listen 443 ssl http2;
listen [::]:443 ssl http2;
server_name <hostname>;
root <modoboa_instance_path>;
ssl_certificate <ssl certificate for your site>;
ssl_certificate_key <ssl certificate key for your site>;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers "ECDHE-RSA-AES256-GCM-SHA512:DHE-RSA-AES256-GCM-SHA512:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-SHA384";
ssl_prefer_server_ciphers on;
ssl_session_cache shared:SSL:10m;
ssl_verify_depth 3;
ssl_dhparam /etc/nginx/dhparam.pem;
client_max_body_size 10M;
access_log /var/log/nginx/modoboa-access.log;
error_log /var/log/nginx/modoboa-error.log;
location /sitestatic/ {
try_files $uri $uri/ =404;
}
location /media/ {
try_files $uri $uri/ =404;
}
location ~ ^/(api|accounts|autodiscover) {
include uwsgi_params;
uwsgi_param UWSGI_SCRIPT instance.wsgi:application;
uwsgi_pass modoboa;
}
location / {
alias <modoboa_instance_path>/frontend/;
index index.html;
expires -1;
add_header Pragma "no-cache";
add_header Cache-Control "no-store, no-cache, must-revalidate, post-check=0, pre-check=0";
try_files $uri $uri/ /index.html = 404;
}
}
``<uwsgi_socket_path>``, ``<modoboa instance name>``, ``<hostname>``,
``<modoboa_instance_path>`` and ``<ssl...>`` must be replaced by the
value you used when :ref:`you deployed your instance <deployment>`.
In case you want to use enable auto-configuration functionality,
create a second virtualhost configuration (the hostname should look
like ``autoconfig.<your domain here>``)::
server {
listen 80;
listen [::]:80;
server_name autoconfig.<your_domain>;
root <modoboa_instance_path>;
access_log /var/log/nginx/autoconfig-access.log;
error_log /var/log/nginx/autoconfig-error.log;
location ~ ^/(mail/config-v1.1.xml|mobileconfig) {
include uwsgi_params;
uwsgi_param UWSGI_SCRIPT instance.wsgi:application;
uwsgi_pass modoboa;
}
}
``<modoboa_instance_path>`` and ``<your_domain>`` must be replaced by
the value you used when :ref:`you deployed your instance
<deployment>`.
If you do not plan to use SSL then change the listen directive to
``listen 80;`` and delete each of the following directives::
ssl on;
keepalive_timeout 70;
ssl_certificate <ssl certificate for your site>;
ssl_certificate_key <ssl certificate key for your site>;
uwsgi_param UWSGI_SCHEME https;
If you do plan to use SSL, you'll have to generate a certificate and a
key. `This article
<http://wiki.nginx.org/HttpSslModule#Generate_Certificates>`_
contains information about how to do it.
Make sure to replace the ``<...>`` in the sample configuration with
appropriate values. Here are some explanations for the cases that may
not be completely self-explanatory:
``<hostname>``
This is the URL which will be the root of your Modoboa site at your
domain. For instance, if your Modoboa installation is reachable at
at ``https://foo/modoboa`` then ``<hostname>`` is
``/modoboa``. In this case you probably also have to set the
``alias`` directives to point to where Modoboa's sitestatic and
media directories are because otherwise nginx won't be able to find
them.
If Modoboa is at the root of your domain, then ``<hostname>``
is an empty string and can be deleted from the configuration
above. In this case, you probably do not need the ``alias``
directives.
``<uwsgi_socket_path>``
The location where uwsig is listening. It could be a unix domain
socket or an address:port combination. Ubuntu configures uwsgi so
that the port is::
unix:/run/uwsgi/app/<app name>/socket
where ``<app name>`` is the name of the application.
Your uwsgi configuration should be::
[uwsgi]
# Not needed when using uwsgi from pip
# plugins = python
chdir = <modoboa_instance_path>
module = <name>.wsgi:application
master = true
harakiri = 60
processes = 4
vhost = true
no-default-app = true
buffer-size = 8192
max-requests = 5000
single-interpreter = true
The plugins directive should be turned on if you use a uwsgi
installation that requires it. If uwsgi was installed from pip, it
does not require it. In the configuration above:
``<modoboa_instance_path>``
The directory where :file:`manage.py` resides. This directory is the
parent of ``<modoboa's settings dir>``
``<name>``
The name that you passed to ``modoboa-admin.py deploy`` when you
created your Modoboa instance, usually ``instance``.
Now, you can go the :ref:`dovecot` section to continue the installation.
Green Unicorn
+++++++++++++
Firstly, `Download and install gunicorn
<http://gunicorn.org/install.html>`_. Then, use the following sample
gunicorn configuration (create a new file named
:file:`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 <modoboa dir>
$ gunicorn -c gunicorn.conf.py <APP/INSTANCE Name>.wsgi:application
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 ssl;
ssl on;
keepalive_timeout 70;
server_name <host fqdn>;
root <modoboa_instance_path>;
access_log /var/log/nginx/<host fqdn>.access.log;
error_log /var/log/nginx/<host fqdn>.error.log;
ssl_certificate <ssl certificate for your site>;
ssl_certificate_key <ssl certificate key for your site>;
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;
proxy_pass http://modoboa;
}
}
If you do not plan to use SSL then change the listen directive to
``listen 80;`` and delete each of the following directives::
ssl on;
keepalive_timeout 70;
ssl_certificate <ssl certificate for your site>;
ssl_certificate_key <ssl certificate key for your site>;
proxy_set_header X-Forwarded-Protocol ssl;
If you do plan to use SSL, you'll have to generate a certificate and a
key. `This article
<http://wiki.nginx.org/HttpSslModule#Generate_Certificates>`__
contains information about how to do it.
Paste this content to your configuration (replace values between
``<>`` with yours) and restart nginx.
Now, you can go the :ref:`dovecot` section to continue the installation.
doc/moving.rst
-159
View File
@@ -1,159 +0,0 @@
#################
Moving to Modoboa
#################
You have an existing platform and you'd like to move to Modoboa, the
following tools could help you.
Using IMAP protocol
===================
.. _imap:
`Modoboa <https://modoboa.org/>`_ provides a way to transfer accounts
hosted on a different platform/provider to your personal server using
the IMAP protocol and a tool called `OfflineIMAP
<https://www.offlineimap.org/doc/installation.html>`_.
It works as follows:
* You first declare what needs to be migrated, basically the domain(s) you own and where they can be found. By doing that, you'll allow accounts hosted on the platform/provider you're migrating from to log into your Modoboa server
* The first time an old account (one coming from your previous provider) successfuly log into Modoboa, a dedicated migration task is created
* On a regular basis (every hour generally), a cron job is responsible for generating an OfflineIMAP configuration file including instructions to migrate all declared migrations and lauching OfflineIMAP to start/continue migrations
.. warning::
As you probably already understood, you can't migrate all your
accounts at the same time since you don't know their corresponding
password (most of the time). Every account migration must be
started by the account's owner.
Configuration
-------------
Modoboa won'thandle the installation of OfflineIMAP so you
need to do it on your own. The following `instructions
<https://www.offlineimap.org/doc/quick_start.html>`_ will help you.
Once done, *the new admin interface (v2)* will let you:
* define the neccessary information to `connect to your old platform/provider <providers>`_
* define `what is to be migrated <migrations>`_ (ie. the accounts)
* customize the behaviour of OfflineIMAP : go to 'Parameters > Imap Migration' from the left menu
.. warning::
**Auto create domain** option must be enabled to make this feature
work. Go to 'Parameters > Administration > Mailboxes' and check if
it's the case.
To generate an OfflineIMAP configuration file, run the following command:
.. sourcecode:: bash
> python manage.py generate_offlineimap_config
The synchronization script must be configured to run periodically on
your new server. Since it will copy mailboxes content to its final
destination, filesystem permissions must be respected. To do that, it
must be executed by the user which owns mailboxes (generally
``vmail``).
Here is a configuration example where the script is executed every
hours. You can copy it inside the ``/etc/cron.d/modoboa`` file:
.. sourcecode:: shell
PYTHON=/srv/modoboa/env/bin/python
INSTANCE=/srv/modoboa/instance
0 */1 * * * vmail cd /srv/vmail && $PYTHON $INSTANCE/manage.py generate_offlineimap_config --output .offlineimaprc && /usr/local/bin/offlineimap > /dev/null 2>&1
Feel free to adapt it.
This will sync back-and-forth user mailbox.
.. _providers:
Providers
---------
A provider represents an IMAP server that hosts one or several domains
you own. It includes connection information (network address, port,
etc.) and a list of hosted domain.
For each domain you declare, you must provide its name. Modoboa will
then create a local domain with the exact same name if needed (ie. if
it does not exist yet) the first time it migrates an account.
Optionaly, you have the possibility to rename a domain (for example:
domain.com -> domain.net) by providing a value to the 'Local domain'
field.
.. _migrations:
Migrations
----------
Migrations are automatically created, you don't need to do it.
The first time an account of your old platform successfuly log into
Modoboa (using old credentials), a local account and a migration task
will be created.
.. warning::
In case of domain renaming as described in `Providers <providers>`_,
users must use the new email address as username for next connection
attempts.
SuperAdmins can monitor running migrations and stop/delete them from
the `IMAP Migration` section (left menu).
From postfixadmin
=================
A dedicated command allows you to convert an existing `postfixadmin
<http://postfixadmin.sourceforge.net/>`_ database to a Modoboa
one. Consult the `documentation
<https://github.com/modoboa/modoboa-pfxadmin-migrate>`_ to know more
about the process.
Using CSV files
===============
Modoboa allows you to import any object (domain, domain alias, mailbox
and alias) using a simple CSV file encoded using **UTF8**. Each line
corresponds to a single object and must respect one of the following
format::
domain; <name: string>; <quota: integer>; <default mailbox quota: integer>; <enabled: boolean>
domainalias; <name: string>; <targeted domain: string>; <enabled: boolean>
relaydomain; <name: string>; <target host: string>; <target port: integer>; <service: string>; <enabled: boolean>; <verify recipients: boolean>
account; <loginname: string>; <password: string>; <first name: string>; <last name: string>; <enabled: boolean>; <group: string>; <address: string>; <quota: integer>; [<domain: string>, ...]
alias; <address: string>; <enabled: boolean>; <recipient: string>; ...
Boolean fields accept the following values: ``true``, ``1``, ``yes``,
``y`` (case insensitive). Any other value will be evaluated as false.
.. warning::
The order does matter. Objects are created sequencially so a
domain must be created before its mailboxes and aliases and a
mailbox must created before its alias(es).
To actually import such a file:
.. sourcecode:: bash
> sudo -u <modoboa_user> -i bash
> source <virtualenv_path>/bin/activate
> cd <modoboa_instance_dir>
> python manage.py modo import <your file>
Available options can be listed using the following command:
.. sourcecode:: bash
> python manage.py modo import -h
doc/rebuild_virtual_env.rst
-76
View File
@@ -1,76 +0,0 @@
Sometimes when upgrading your Operating System (eg from Ubuntu 17.04
to Ubuntu 17.10) your virtual environment running modoboa can get
corrupted. Your first response will be to panic but fear not! The
solution is in this document.
First things first:
Recover your database password
==============================
You will need to recover your database password (if using mysql or
postgresql). You will find this in ``/etc/postfix/sql-aliases.cf`` or
any file with ``sql-*.cf`` in the ``/etc/postfix`` directory.
Make note of this as you will need it when reconfiguring modoboa.
Reinstall Modoboa
=================
Start out by backup up your modoboa settings file located in the
``modoboa instance`` directory
(``/srv/modoboa/instance/instance/settings.py`` if you used the
default installer configuration). This contains your current
configuration.
Next, you want to remove all current modoboa files.
After doing this, follow the manual installation instructions for :ref:`modoboa_manual_install` **only** as everything should be working properly.
After this completes, simply restore your backed up settings file to
``/srv/instance/instance/settings.py`` (if you used installer default
configuration). You will then need to reinstall your `extensions
<http://modoboa.readthedocs.io/en/latest/index.html>`_.
You can find which plugins you had in your ``settings.py`` file under
the ``MODOBOA_APPS`` variable.
Instructions to install extensions can also be `found here
<http://modoboa.readthedocs.io/en/latest/installation.html#extensions>`_.
Once you have completed this step, you will need to run the following
commands:
.. sourcecode:: bash
> (env) $ cd <instance_dir>
> (env) $ python manage.py migrate
> (env) $ python manage.py collectstatic
You will then see a message similar to:
.. sourcecode:: text
You have requested to collect static files at the destination
location as specified in your settings:
/srv/modoboa/instance/sitestatic
This will overwrite existing files!
Are you sure you want to do this?
Type 'yes' to continue, or 'no' to cancel:
You will want to answer ``yes`` here then simply restart the ``uwsgi``
process with ``service uwsgi restart`` and you should be up and
running again.
Simply log into your modoboa web panel and verify that your extensions
and webmail box is working.
Information
===========
Rebuild instructions from:
`https://help.pythonanywhere.com/pages/RebuildingVirtualenvs/
<https://help.pythonanywhere.com/pages/RebuildingVirtualenvs/>`_
doc/requirements.txt
-2
View File
@@ -1,2 +0,0 @@
docutils<0.23
sphinx_rtd_theme
doc/rest_api.rst
-39
View File
@@ -1,39 +0,0 @@
########
REST API
########
To ease the integration with external sources (software or other),
Modoboa provides a REST API.
Every installed instance comes with a ready-to-use API and a
documentation.
**You will find them using the following url patterns:**
* New API+Docs: *https://<hostname>/api/schema-v2/swagger/*
* Old API: *http://<hostname>/api/v1/*
.. note::
You need to be logged in for the API docs to show.
**Examples:**
* `new example <https://demo.modoboa.org/api/schema-v2/swagger/>`_
documentation is available on the official demo.
Using this API requires an authentication and for now, only a token
based authentication is supported. To get a valid token, log-in to
your instance with a super administrator, go to *Settings > API* and
activate the API access. Press the Update button and wait until the
page is reloaded, the token will be displayed.
.. image:: _static/api_access_form.png
:align: center
To make valid API calls, every requests you send must embed this token
within an Authorization HTTP header like this::
Authorization: Token <YOUR_TOKEN>
and the content type of those requests must be ``application/json``.
doc/upgrade.rst
-2157
View File
File diff suppressed because it is too large Load Diff