Modoboa documentation¶

Install the corresponding Python binding:

(env)> pip install psycopg2

Then, create a user and a database:

> sudo -i postgres
>

Install the corresponding Python binding:

(env)> pip install MySQL-Python

Then, create a user and a database:

> mysqladmin -u root -p create modoboa

Firstly, Download and install gunicorn. Then, use the following sample gunicorn configuration (create a new file named gunicorn.conf.py inside Modoboa’s root dir):

backlog = 2048
bind = "unix:/var/run/gunicorn/modoboa.sock"
pidfile = "/var/run/gunicorn/modoboa.pid"
daemon = True
debug = False
workers = 2
logfile = "/var/log/gunicorn/modoboa.log"
loglevel = "info"

To start gunicorn, execute the following commands:

$ cd <modoboa dir>
$ gunicorn -c gunicorn.conf.py <modoboa dir>.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 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 Dovecot section to continue the installation.

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:

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.

Here is a sample nginx configuration:

server {
    listen 443 ssl;
    ssl on;
    keepalive_timeout 70;

    server_name <host fqdn>;
    root <modoboa's settings dir>;

    ssl_certificate     <ssl certificate for your site>;
    ssl_certificate_key <ssl certificate key for your site>;

    access_log  /var/log/nginx/<host fqdn>.access.log;
    error_log /var/log/nginx/<host fqdn>.error.log;

    location <modoboa's root url>/sitestatic/ {
            autoindex on;
            alias <location of sitestatic on your file system>;
    }

    # Whether or not Modoboa uses a media directory depends on how
    # you configured Modoboa. It does not hurt to have this.
    location <modoboa's root url>/media/ {
            autoindex on;
            alias <location of media on your file system>;
    }

    # This denies access to any file that begins with
    # ".ht". Apache's .htaccess and .htpasswd are such files. A
    # Modoboa installed from scratch would not contain any such
    # files, but you never know what the future holds.
    location ~ /\.ht {
        deny all;
    }

    location <modoba's root url>/ {
        include uwsgi_params;
        uwsgi_pass <uwsgi port>;
        uwsgi_param UWSGI_SCRIPT <modoboa instance name>.wsgi:application;
        uwsgi_param UWSGI_SCHEME https;
    }
}

<modoboa instance name> must be replaced by the value you used when you deployed your instance.

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 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:

<modoboa's settings dir>

Where Modoboa’s settings.py resides. This is also where the sitestatic and media directories reside.

<modoboa's root url>

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 <modoboa's root url> 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 <modoboa root url> is an empty string and can be deleted from the configuration above. In this case, you probably do not need the alias directives.

<uwsgi port>

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's top dir>
module = <name>.wsgi:application
master = true
harakiri = 60
processes = 4
vhost = true
no-default-app = 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's top dir>

The directory where 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.

Now, you can go the Dovecot section to continue the installation.

Three operation types are considered:

1. Mailbox creation
2. Mailbox renaming
3. 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 General parameters 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 not executed (see Postfix configuration).

Edit the crontab of the user who owns the mailboxes on the file system:

$ crontab -u <user> -e

And add the following line inside:

* * * * * python <modoboa_site>/manage.py handle_mailbox_operations

The result of each order is recorded into Modoboa’s log. Go to Modoboa > Logs to consult them.

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.

bower command is missing in manage.py if you don’t use the --devel option of the modoboa-admin.py deploy command.

To fix it, regenerate your instance or update your settings.py file manually. Look at devmode in https://github.com/tonioo/modoboa/blob/master/modoboa/core/commands/templates/settings.py.tpl

To declare a new administration parameter, use the following function:

from modoboa.lib import parameters

parameters.register_admin(name, **kwargs)

To declare a new user parameter, use the following function:

parameter.register_user(name, **kwargs)

Both functions accept extra arguments listed here:

• type : parameter’s type, possible values are : int, string, list, list_yesno,
• deflt : default value,
• help : help text,
• values : list of possible values if type is list.

To add a new tab to the account edition form, define new listeners (handlers) for the following events:

• ExtraAccountForm
• FillAccountInstances
• CheckExtraAccountForm (optional)

Example:

from modoboa.lib import events

@events.observe("ExtraAccountForm")
def extra_account_form(user, account=None):
    return [
        {"id": "tabid", "title": "Title", "cls": MyFormClass}
    ]

@events.observe("FillAccountInstances")
def fill_my_tab(user, account, instances):
    instances["id"] = my_instance

To add a new tab to the domain edition form, define new listeners (handlers) for the following events:

• ExtraDomainForm
• FillDomainInstances

Example:

from modoboa.lib import events

@events.observe("ExtraDomainForm")
def extra_domain_form(user, domain):
    return [
        {"id": "tabid", "title": "Title", "cls": MyFormClass}
    ]

@events.observe("FillDomainInstances")
def fill_my_tab(user, domain, instances):
    instances["id"] = my_instance

Raised when a new account is automatically created (example: LDAP synchronization).

Callback prototype:

def callback(account): pass

• account is the newly created account (User instance)

Raised when a new account is created.

Callback prototype:

def callback(account): pass

• account is the newly created account (User instance)

Raised when an existing account is deleted.

Callback prototype:

def callback(account, byuser, **options): pass

• account is the account that is going to be deleted
• byuser is the adminstrator deleting account

Raised when an account is exported to CSV.

Callback prototype:

def callback(account): pass

• account is the account being exported

Must return a list of values to include in the export.

Raised when an account is imported from CSV.

Callback prototype:

def callback(user, account, row): pass

• user is the user importing the account
• account is the account being imported
• row is a list containing what remains from the CSV definition

Raised when an existing account is modified.

Callback prototype:

def callback(oldaccount, newaccount): pass

• oldaccount is the account before it is modified
• newaccount is the account after the modification

Raised when an admin menu is about to be displayed.

Callback prototype:

def callback(target, user): pass

The target argument indicates which menu is being displayed. Possible values are:

• admin_menu_box : corresponds to the menu bar available inside administration pages
• top_menu : corresponds to the top black bar

See UserMenuDisplay for a description of what callbacks that listen to this event must return.

Raised before the unicity of a domain name is checked. By default, modoboa prevents duplicate names between domains and domain aliases but extensions have the possibility to extend this rule using this event.

Callback prototype:

def callback(): pass

Must return a list of 2uple, each one containing a model class and an associated label.

When an account is being modified, this event lets extensions check if this account is concerned by a specific form.

Callback prototype:

def callback(account, form): pass

• account is the User instance beeing modified
• form is a dictionnary (same content as for ExtraAccountForm)

Callbacks listening to this event must return a list containing one Boolean.

Raised when a new domain alias is created.

Callback prototype:

def callback(user, domain_alias): pass

• user is the new domain alias owner (User instance)
• domain_alias is the new domain alias (DomainAlias instance)

Raised when an existing domain alias is about to be deleted.

Callback prototype:

def callback(domain_alias): pass

• domain_alias is a DomainAlias instance

Raised when a new domain is created.

Callback prototype:

def callback(user, domain): pass

• user corresponds to the User object creating the domain (its owner)
• domain is a Domain instance

Raised when an existing domain is about to be deleted.

Callback prototype:

def callback(domain): pass

• domain is a Domain instance

Raised when a domain has been modified.

Callback prototype:

def callback(domain): pass

• domain is the modified Domain instance, it contains an extra oldname field which contains the old name

Raised before the ownership of a domain is removed from its original creator.

Callback prototype:

def callback(owner, domain): pass

• owner is the original creator
• domain is the Domain instance being modified

Raised when the account list is displayed. Let developers define new actions to act on a specific user.

Callback prototype:

def callback(account): pass

• account is the account being listed

Let extensions add new forms to the account edition form (the one with tabs).

Callback prototype:

def callback(user, account): pass

• user is a User instance corresponding to the currently logged in user
• account is the account beeing modified (User instance)

Callbacks listening to the event must return a list of dictionnaries, each one must contain at least three keys:

{"id" : "<the form's id>",
 "title" : "<the title used to present the form>",
 "cls" : TheFormClassName}

Let extensions add extra content into the admin panel.

Callback prototype:

def callback(user, target, currentpage): pass

• user is a User instance corresponding to the currently logged in user
• target is a string indicating the place where the content will be displayed. Possible values are : leftcol
• currentpage is a string indicating which page (or section) is displayed. Possible values are : domains, identities

Callbacks listening to this event must return a list of string.

Raised to request extra entries to display inside the domains listing.

Callback prototype:

def callback(user, domfilter, searchquery, **extrafilters): pass

• user is the User instance corresponding to the currently logged in user
• domfilter is a string indicating which domain type the user needs
• searchquery is a string containing a search query
• extrafilters is a set of keyword arguments that may contain additional filters

Must return a valid QuerySet.

Raised to request extra filters for the domains listing page. For example, the postfix_relay_domains extension let users filter entries based on service types.

Callback prototype:

def callback(): pass

Must return a list of valid filter names (string).

Let extensions add new forms to the domain edition form (the one with tabs).

Callback prototype:

def callback(user, domain): pass

• user is a User instance corresponding to the currently logged in user
• domain is the domain beeing modified (Domain instance)

Callbacks listening to the event must return a list of dictionnaries, each one must contain at least three keys:

{"id" : "<the form's id>",
 "title" : "<the title used to present the form>",
 "cls" : TheFormClassName}

Raised to request extra help text to display inside the domain import form.

Callback prototype:

def callback(): pass

Must return a list a string.

Raised to request extra entries to include in the left menu of the domains listing page.

Callback prototype:

def callback(user): pass

• user is the User instance corresponding to the currently logged in user

Must return a list of dictionaries. Each dictionary must contain at least three keys:

{"name": "<menu name>",
 "label": "<menu label>",
 "url": "<menu url>"}

Raised to request extra fields to include in a django form.

Callback prototype:

def callback(form_name, instance=None): pass

• form_name is a string used to distinguish a specific form
• instance is a django model instance related to form_name

Must return a list of 2uple, each one containing the following information:

('field name', <Django form field instance>)

Let extensions add new forms to the relay domain edition form (the one with tabs).

Callback prototype:

def callback(user, rdomain): pass

• user is the User instance corresponding to the currently logged in user
• rdomain is the relay domain being modified (RelayDomain instance)

Callbacks listening to the event must return a list of dictionnaries, each one must contain at least three keys:

{"id" : "<the form's id>",
 "title" : "<the title used to present the form>",
 "cls" : TheFormClassName}

When an account is beeing modified, this event is raised to fill extra forms.

Callback prototype:

def callback(user, account, instances): pass

• user is a User instance corresponding to the currently logged in user
• account is the User instance beeing modified
• instances is a dictionnary where the callback will add information needed to fill a specific form

When a domain is beeing modified, this event is raised to fill extra forms.

Callback prototype:

def callback(user, domain, instances): pass

• user is a User instance corresponding to the currently logged in user
• domain is the Domain instance beeing modified
• instances is a dictionnary where the callback will add information needed to fill a specific form

When a relay domain is being modified, this event is raised to fill extra forms.

Callback prototype:

def callback(user, rdomain, instances): pass

• user is the User instance corresponding to the currently logged in user
• rdomain is the RelayDomain instance being modified
• instances is a dictionnary where the callback will add information needed to fill a specific form

Some places in the interface let plugins add their own announcement (ie. message).

Callback prototype:

def callback(target): pass

• target is a string indicating the place where the announcement will appear:
• loginpage : corresponds to the login page

Callbacks listening to this event must return a list of string.

Raised to request the list of actions available for the domains listing entry being displayed.

Callback prototype:

def callback(user, rdomain): pass

• user is the User instance corresponding to the currently logged in user
• rdomain is the RelayDomain instance being displayed

Must return a list of dictionaries, each dictionary containing at least the following entries:

{"name": "<action name>",
 "url": "<action url>",
 "title": "<action title>",
 "img": "<action icon>"}

Raised to request the modification url of the domains listing entry being displayed.

Callback prototype:

def callback(domain): pass

• domain is a model instance (RelayDomain for example)

Must return a dictionary containing at least the following entry:

{'url': '<modification url>'}

Raised to request extra limit templates. For example, the postfix_relay_domains extension define a template to limit the number of relay domains an administrator can create.

Callback prototype:

def callback(): pass

Must return a list of set. Each set must contain at least three entries:

[('<limit_name>', '<limit label>', '<limit help text>')]

Raised to request extra parameters for a given parameters form.

Callback prototype:

def callback(application, level): pass

• application is the name of the form’s application (ie. admin, amavis, etc.)
• level is the form’s level: A for admin or U for user

Must return a dictionary. Each entry must be a valid Django form field.

Let extensions define new permissions for a given role.

Callback prototype:

def callback(rolename): pass

• rolename is the role’s name (str)

Callbacks listening to this event must return a list of list. The second list level must contain exactly 3 strings: the application name, the model name and the permission name. Example:

[
    ["core", "user", "add_user"],
    ["core", "user", "change_user"],
    ["core", "user", "delete_user"],
]

Let extensions define new administrative roles (will be used to create or modify an account).

Callback prototype:

def callback(user, account): pass

• user is a User instance corresponding to the currently logged in user
• account is the account being modified (None on creation)

Callbacks listening to this event must return a list of 2uple (two strings) which respect the following format: (value, label).

Let extensions add static content (ie. CSS or javascript) to default pages. It is pretty useful for functionalities that don’t need a template but need javascript stuff.

Callback prototype:

def callback(caller, st_type, user): pass

• caller is name of the application (or the location) responsible for the call
• st_type is the expected static content type (css or js)
• user is a User instance corresponding to the currently logged in user

Callbacks listening to this event must return a list of string.

Raised to request the function handling an object being imported from CSV.

Callback prototype:

def callback(objtype): pass

objtype is the type of object being imported

Must return a list of function. A valid import function must respect the following prototype:

def import_function(user, row, formopts): pass

• user is the User instance corresponding to the currently logged in user
• row is a string containing the object’s definition (CSV format)
• formopts is a dictionary that may contain options

Raised a initial data has been loaded for a given extension.

Callback prototype:

 def callback(extname); pass

``extname`` is the extension name (str)

Raised when a new mailbox alias is created.

Callback prototype:

def callback(user, mailbox_alias): pass

• user is the new domain alias owner (User instance)
• mailbox_alias is the new mailbox alias (Alias instance)

Raised when an existing mailbox alias is about to be deleted.

Callback prototype:

def callback(mailbox_alias): pass

• mailbox_alias is an Alias instance

Raised when a new mailbox is created.

Callback prototype:

def callback(user, mailbox): pass

• user is the new mailbox’s owner (User instance)
• mailbox is the new mailbox (Mailbox instance)

Raised when an existing mailbox is about to be deleted.

Callback prototype:

def callback(mailbox): pass

• mailbox is a Mailbox instance

Raised when an existing mailbox is modified.

Callback prototype:

def callback(mailbox): pass

• mailbox is the Mailbox modified instance. It contains a old_full_address extra field to check if the address was modified.

Raised just before a password change action.

Callback prototype:

def callback(user): pass

• user is a User instance

Callbacks listening to this event must return a list containing either True or False. If at least one True is returned, the password change will be cancelled (ie. changing the password for this user is disabled).

Lets extensions subscribe to the global notification service (located inside the top bar).

Callback prototype:

def callback(user, include_all): pass

• request is a Request instance
• include_all is a boolean indicating if empty notifications must be included into the result or not

Callbacks listening to this event must return a list of dictionary, each dictionary containing at least the following entries:

{"id": "<notification entry ID>",
 "url": "<associated URL>",
 "text": "<text to display>"}

If your notification needs a counter, you can specify it by adding the two following entries in the dictionary:

{“counter”: <associated counter>,

“level”: “<info|success|warning|error>”}

Raised when a user logs in.

Callback prototype:

def callback(request, username, password): pass

Raised when a user logs out.

Callback prototype:

def callback(request): pass

Raised when a user menu is about to be displayed.

Callback prototype:

def callback(target, user): pass

The target argument indicates which menu is being displayed. Possible values are:

• options_menu: corresponds to the top-right user menu
• uprefs_menu: corresponds to the menu bar available inside the User preferences page
• top_menu: corresponds to the top black bar

All the callbacks that listen to this event must return a list of dictionnaries (corresponding to menu entries). Each dictionnary must contain at least the following keys:

{"name" : "a_name_without_spaces",
 "label" : _("The menu label"),
 "url" : reverse("your_view")}

Raised when a new relay domain alias is created.

Callback prototype:

def callback(user, rdomain_alias): pass

• user is the new relay domain alias owner (User instance)
• rdomain_alias is the new relay domain alias (DomainAlias instance)

Raised when an existing relay domain alias is about to be deleted.

Callback prototype:

def callback(rdomain_alias): pass

• rdomain_alias is a RelayDomainAlias instance

Raised when a new relay domain is created.

Callback prototype:

def callback(user, rdomain): pass

• user corresponds to the User object creating the relay domain (its owner)
• rdomain is a RelayDomain instance

Raised when an existing relay domain is about to be deleted.

Callback prototype:

def callback(rdomain): pass

• rdomain is a RelayDomain instance

Raised when a relay domain has been modified.

Callback prototype:

def callback(rdomain): pass

• rdomain is the modified RelayDomain instance, it contains an

  extra oldname field which contains the old name

Raised when the role of an account is about to be changed.

Callback prototype:

def callback(account, role): pass

• account is the account being modified
• role is the new role (string)

Raised to save extra fields declared using ExtraFormFields.

Callback prototype:

def callback(form_name, instance, values): pass

• form_name is a string used to distinguish a specific form
• instance is a django model instance related to form_name
• values is a dictionary containing the form’s values

Raised to check if a user is allowed to set a given role to an account.

Callback prototype:

def callback(user, role, account): pass

• user is the User instance corresponding to the currently logged in user
• role is the role user tries to set
• account is the account being modified (None on creation)

Must return a list containing True or False to indicate if this user can is allowed to set role.