Configuration — Modoboa 1.7.4 documentation

### Navigation

- index
- next |
- previous |
- Modoboa 1.7.4 documentation »

# 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.

### General parameters

The admin application exposes several parameters, they are presented below:

Name | Tab | Description | Default value
--- | --- | --- | ---
Authentication type | General | The backend used for authentication | Local
Default password scheme | General | Scheme used to crypt mailbox passwords | crypt
Rounds | General | Number of rounds (only used by sha256crypt and sha512crypt). Must be between 1000 and 999999999, inclusive. | 70000
Secret key | General | A key used to encrypt users’ password in sessions | random value
Sender address | General | Email address used to send notifications. |
Enable communication | General | Enable communication with Modoboa public API | yes
Check new versions | General | Automatically checks if a newer version is available | yes
Send statistics | General | Send statistics to Modoboa public API (counters and used extensions) | yes
Top notifications check interval | General | Interval between two top notification checks (in seconds) | 30
Maximum log record age | General | The maximum age in days of a log record | 365
Items per page | General | Number of displayed items per page | 30
Default top redirection | General | The default redirection used when no application is specified | userprefs
Enable MX checks | Admin | Check that every domain has a valid MX record | yes
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 major DNSBL providers | yes
Handle mailboxes on filesystem | Admin | Rename or remove mailboxes on the filesystem when they get renamed or removed within Modoboa | no
Mailboxes owner | Admin | The UNIX account who owns mailboxes on the filesystem | vmail
Default domain quota | Admin | Default quota (in MB) applied to freshly created domains with no value specified. A value of 0 means no quota. | 0
Automatic account removal | Admin | When a mailbox is removed, also remove the associated account | no
Automatic domain/mailbox creation | Admin | Create a domain and a mailbox when an account is automatically created | yes

Note

If you are not familiar with virtual domain hosting, you should take a look at postfix’s documentation. This How to 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 LDAP authentication.

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

### Custom logo

You have the possibility to use a custom logo instead of the default one on the login page.

To do so, open the `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`.

## Host configuration

Note

This section is only relevant when Modoboa handles mailboxes renaming and removal from the filesystem.

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 `/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.

## Time zone and language

Modoboa is available in many languages.

To specify the default language to use, edit the `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 to store per-user information.

Few parameters need to be set in the `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.

## External authentication

### LDAP

Modoboa supports external LDAP authentication using the following extra components:

- Python LDAP client
- Django LDAP authentication backend

If you want to use this feature, you must first install those components:

    $ pip install python-ldap django-auth-ldap

Then, all you have to do is to modify the `settings.py` file. Add a new authentication backend to the AUTHENTICATION_BACKENDS variable, like this:

    AUTHENTICATION_BACKENDS = (
      'modoboa.lib.authbackends.LDAPBackend',
      '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 the DNS name of the LDAP server | localhost
Server port | The TCP port number used by the LDAP server | 389
Use a secure connection | Use an SSL/TLS connection to access the LDAP server | no
Authentication method | Choose the authentication method to use | Direct bind
User DN template (direct bind mode) | The template used to 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 (e.g. ‘(objectClass=person)’). In order to be valid, it must be enclosed in parentheses. | (mail=%(user)s)
Password attribute | The attribute used to store user passwords | userPassword
Active Directory | Tell if the LDAP server is an Active Directory one | no
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 LDAP directory. | PosixGroup
Groups search base | The distinguished name of the search base used to find groups |
Domain/mailbox creation | Automatically create a domain and 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 | yes

If you need additional parameters, you will find a detailled documentation here.

Once the authentication is properly configured, the users defined in your LDAP directory will be able to connect to Modoboa, the associated domain and mailboxes will be automatically created if needed.

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

It is possible to use an existing SMTP server as an authentication source. To enable this feature, edit the `settings.py` file and change the following setting:

    AUTHENTICATION_BACKENDS = (
        'modoboa.lib.authbackends.SMTPBackend',
        'django.contrib.auth.backends.ModelBackend',
    )

SMTP server location can be customized using the following settings:

    AUTH_SMTP_SERVER_ADDRESS = 'localhost'
    AUTH_SMTP_SERVER_PORT = 25
    AUTH_SMTP_SECURED_MODE = None  # 'ssl' or 'starttls' are accepted

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

### Navigation

- index
- next |
- previous |
- Modoboa 1.7.4 documentation »