iRedMail Enterprise Edition (EE): Best Practice

Attention

Check out the lightweight on-premises email archiving software developed by iRedMail team: Spider Email Archiver.

How the fearless upgrade works

iRedMail Enterprise Edition ("EE" for short) splits software config files to 2 parts: core configuration and custom settings.

EE generates and maintains core config files to make sure everything works by default with our best practice, but we understand that you may need to tune some settings to match your own requirements, so EE offers several ways to allow you to archive this goal.

Please follow some simple rules to store your custom settings, and do not modify the core config files manually maintained by EE.

Including config files

Many software supports loading settings from extra config files with directives like include (Nginx, Dovecot), include_try (Dovecot), require_once (PHP applications). In this case, it will be configured to load extra config files under /opt/iredmail/custom/<software-name>/. We use Dovecot for example to explain the details.

Dovecot's main config file is /etc/dovecot/dovecot.conf, we have directives at the bottom of dovecot.conf like this:

!include_try /etc/dovecot/conf-enabled/*.conf
!include_try /opt/iredmail/custom/dovecot/conf-enabled/*.conf

It will try to load all files ends with .conf under /etc/dovecot/conf-enabled/ first, then /opt/iredmail/custom/dovecot/conf-enabled/. Earlier settings with same parameter name will be overridden by the latter one.

/etc/dovecot/dovecot.conf and all files under /etc/dovecot/conf-enabled/ are generated and maintained by EE based on the settings you done on EE web UI (especially the Server Settings page). If you want to override some settings, please create a file ends with .conf under /opt/iredmail/custom/dovecot/conf-enabled/ with your custom settings. for example, Dovecot is configured to enable services like below by iRedMail EE:

protocols = pop3 imap sieve lmtp

What can you do to disable pop3 service without modify files under /etc/dovecot/? Easy, just create a file, e.g. custom.conf, under /opt/iredmail/custom/dovecot/conf-enabled/ with content below (note: service name pop3 is removed in this setting), then restart Dovecot service:

protocols = imap sieve lmtp

Modify config files in-place

If software does not support loading settings from extra config files, you may need to apply your own settings by running commands to modify its config files under /etc/. For example, Postfix.

Postfix doesn't support directive like include to load extra config files, so if you modifying Postfix config files (e.g. /etc/postfix/main.cf) manually, your modifications will be lost after next time you perform deployment (update, upgrade, etc) on EE web UI, because EE always re-generates the files it maintains during deployment.

Fortunately, EE supports executing a (bash) shell script during each deployment, the script is /opt/iredmail/custom/<COMPONENT>/custom.sh. For Postfix, it's /opt/iredmail/custom/postfix/custom.sh.

Let's say you want to add IP address 192.168.1.1 to Postfix parameter mynetworks, instead of modifying /etc/postfix/main.cf directly, you can write shell commands in /opt/iredmail/custom/postfix/custom.sh like below:

postconf -e mynetworks='127.0.0.1 192.168.1.1'

Again, this custom.sh will be executed by EE during deployment, if you want to apply the changes immediately, please execute it manually:

cd /opt/iredmail/custom/postfix/
bash custom.sh

SSL cert

EE generates self-signed ssl cert during initial setup, but you can request free cert from Let's Encrypt after initial setup.

Cert files are stored under /opt/iredmail/ssl/:

Passwords

Backend File Name Comment Value could be found in file
LDAP, MySQL sql_user_root MySQL root password. /root/.my.cnf
PostgreSQL sql_user_postgres (Linux)
sql_user__postgresql (OpenBSD)		 PostgreSQL root password. /var/lib/pgsql/.pgpass (CentOS), or /var/lib/postgresql/.pgpass (Debian/Ubuntu), /var/postgresql/.pgpass (OpenBSD)
LDAP ldap_root_password Password of LDAP root dn (cn=Manager,dc=xx,dc=xx)
LDAP ldap_vmail_password Password of LDAP dn cn=vmail,dc=xx,dc=xx /etc/postfix/ldap/*.cf
LDAP ldap_vmailadmin_password Password of LDAP dn cn=vmailadmin,dc=xx,dc=xx /opt/www/iredadmin/settings.py
ALL sql_user_vmail Password of SQL user vmail /etc/postfix/mysql/*.cf or /etc/postfix/pgsql/*.cf
ALL sql_user_vmailadmin Password of SQL user vmailadmin /opt/www/iredadmin/settings.py
ALL sql_user_amavisd Password of SQL user amavisd /etc/amavisd/amavisd.conf (Linux/OpenBSD)
/etc/amavis/conf.d/50-user (Debian/Ubuntu)
ALL sql_user_sa_bayes Password of SQL user sa_bayes /etc/mail/spamassassin/local.cf
ALL sql_user_iredadmin Password of SQL user iredadmin /opt/www/iredadmin/settings.py
ALL sql_user_iredapd Password of SQL user iredapd /opt/iredapd/settings.py
ALL sql_user_roundcube Password of SQL user roundcube /root/.my.cnf-roundcube or /opt/www/roundcubemail/config/config.inc.php
ALL sql_user_sogo Password of SQL user sogo /etc/sogo/sogo.conf
ALL sql_user_netdata Password of SQL user netdata /root/.my.cnf-netdata or /opt/netdata/etc/netdata/my.cnf
ALL sql_user_fail2ban Password of SQL user fail2ban /root/.my.cnf-fail2ban
ALL iredapd_srs_secret The secret string used to sign SRS. /opt/iredapd/settings.py, parameter srs_secrets =.
ALL sogo_sieve_master_password The Dovecot master user used by SOGo. /etc/sogo/sieve.cred.
ALL roundcube_des_key The DES key used by Roundcube to encrypt the session. /opt/www/roundcubemail/config/config.inc.php, parameter $config['des_key'] =.
ALL mlmmjadmin_api_token API token for authentication. /opt/mlmmjadmin/settings.py, parameter api_auth_tokens =.
ALL first_domain_admin_password Password of the mail user postmaster@<your-domain.com>. your-domain.com is the first mail domain name you (are going to) set during iRedMail installation.

Custom settings used by software

MariaDB

[mysqld]
max_connections     = 1024

OpenLDAP

database    mdb
suffix      dc=my-ldap-suffix,dc=com
directory   /var/lib/ldap/my-ldap-suffix.com

rootdn      cn=Manager,dc=my-ldap-suffix,dc=com
rootpw      {SSHA}...

sizelimit   unlimited
maxsize     2147483648
checkpoint  128 3
mode        0700

index attr_1,attr_2,attr_3  eq,pres
index attr_4,attr_5,attr_6  eq,pres

Nginx

iRedMail uses the directory structure recommended by Debian/Ubuntu:

/etc/nginx/                         # all config files

        |- conf-available/          # store settings used inside Nginx `http {}` block.
                                    # Note: files under this directory are NOT
                                    #       loaded by Nginx directly.

        |- conf-enabled/            # symbol links to files under `conf-available/`.
                                    # Note: files under this directory are
                                    #       loaded by Nginx directly.

        |- sites-available/         # store virtual web host config files.
                                    # Note: files under this directory are NOT
                                    #       loaded by Nginx directly.

        |- sites-enabled/           # symbol links to files under `sites-available/`.
                                    # Note: files under this directory are
                                    #       loaded by Nginx directly.

        |- sites-conf.d/
                |- default-ssl/     # modular config files used by default
                                    # virtual web host.

/opt/iredmail/custom/nginx/         # all custom config files.
                        |- conf-available/
                        |- conf-enabled/
                        |- sites-available/
                        |- sites-enabled/
                        |- webapps/         # config snippets for certain web applications.
                        |- custom.sh        # (bash) shell script used for advanced customization

Postfix

Postfix doesn't support loading main settings (/etc/postfix/main.cf and /etc/postfix/master.cf) from multiple files, so iRedMail EE uses alternative solution to split core and custom settings.

For other settings, Postfix is configured to load files under /opt/iredmail/custom/postfix/ first (they store custom settings and maintained by you), then another one from /etc/postfix/ (maintained by iRedMail EE and you should NOT modify them). If rule defined in custom files matches, Postfix will skip the second file.

For example, Postfix is configured to load 2 files for HELO access check:

smtpd_helo_restrictions =
    ...
    check_helo_access pcre:/opt/iredmail/custom/postfix/helo_access.pcre
    check_helo_access pcre:/etc/postfix/helo_access.pcre
    ...

You can find some other files for customization under /opt/iredmail/custom/postfix/. For example:

There's also a (Bash) shell script for flexible customization: /opt/iredmail/custom/postfix/custom.sh. It will be ran each time you perform deployment or upgrade.

For example, to set value of parameter enable_original_recipient to yes (defaults to no set in /etc/postfix/main.cf), you can write command in /opt/iredmail/custom/postfix/custom.sh like below:

postconf -e enable_original_recipient=yes

To add new or update existing transport settings in /etc/postfix/master.cf, you can run postconf -M and postconf -P (requires Postfix-2.11 or later releases). For example, create new transport 465 for SMTPS (SMTP over SSL):

postconf -M 465/inet="465 inet n - n - - smtpd"
postconf -P "465/inet/syslog_name=postfix/smtps"
postconf -P "465/inet/smtpd_tls_wrappermode=yes"
postconf -P "465/inet/smtpd_sasl_auth_enable=yes"
postconf -P "465/inet/smtpd_client_restrictions=permit_sasl_authenticated,reject"
postconf -P "465/inet/content_filter=smtp-amavis:[127.0.0.1]:10026"

It will generate new lines in /etc/postfix/master.cf like below:

465 inet n - n - - smtpd
  -o syslog_name=postfix/smtps
  -o smtpd_tls_wrappermode=yes
  -o smtpd_sasl_auth_enable=yes
  -o smtpd_client_restrictions=permit_sasl_authenticated,reject
  -o content_filter=smtp-amavis:[127.0.0.1]:10026

For more details about postconf command, please check its manual page: postconf(1).

Updating configuration with postconf is not that user-friendly, use append_main.cf and append_master.cf if possible.

Dovecot

Dovecot supports loading from mulitple config files, and settings will be overrode by the last one.

Roundcube

Custom global settings

All your custom settings should be placed in /opt/iredmail/custom/roundcube/custom.inc.php, and do NOT touch main config file /opt/www/roundcubemail/config/config.inc.php.

Third-party or custom plugins

All third-party or custom plugins should be placed under /opt/iredmail/custom/roundcube/plugins/.

Plugins will be linked to /opt/www/roundcubemail/plugins/ automatically during iRedMail EE deployment, but you need to create the symbol link manually if you don't want to run another deployment.

Don't forget to enable the plugin(s) in /opt/iredmail/custom/roundcube/custom.inc.php. For example:

$config['plugins'] = array('managesieve', 'password', 'markasjunk', 'YOUR-PLUGIN-1', 'YOUR-PLUGIN-2');

Third-party or custom skins

All third-party or custom skins should be placed under /opt/iredmail/custom/roundcube/skins/.

Skins will be linked to /opt/www/roundcubemail/skins/ automatically during iRedMail EE deployment, but you need to create the symbol link manually if you don't want to run another deployment.

To use some third-party skin as the default one for all users, append a line in /opt/iredmail/custom/roundcube/custom.inc.php like below:

$config['skin'] = 'YOUR-SKIN-NAME';

Custom settings for official plugins

iRedMail EE enables 3 official plugins by default:

If you have custom settings for plugins enabled by iRedMail EE, please put the custom settings in file /opt/iredmail/custom/roundcube/config_<plugin_name>.inc.php.

For example:

Custom settings for official plugins but not enabled by iRedMail

If you need to enable some Roundcube official plugin which is not enabled by iRedMail EE:

cd /opt/www/roundcubemail/plugins/<plugin>/
cp config.inc.php.dist config.inc.php
echo 'require_once "/opt/iredmail/custom/roundcube/config_<plugin>.inc.php";' >> config.inc.php

This way if iRedMail EE enables this plugin in the future, it will successfully load your own custom settings and not mess it up.

For example, if you have custom settings for official plugin enigma, you should add shell commands like below in /opt/iredmail/custom/roundcube/custom.sh

cd /opt/www/roundcubemail/plugins/engima/
cp config.inc.php.dist config.inc.php
echo 'require_once "/opt/iredmail/custom/roundcube/config_enigma.inc.php";' >> config.inc.php

Then put all custom settings for plugin enigma to /opt/iredmail/custom/roundcube/config_enigma.inc.php.

SOGo

SOGo doesn’t support directive like include to load extra settings from multiple files, so you have to either maintain your own SOGo config file (/opt/iredmail/custom/sogo/sogo.conf) or use the custom.sh (bash) shell script to do some customization based on the config file generated by iRedMail EE.

iRedAPD

Amavisd

SpamAssassin

Store custom rules in /opt/iredmail/custom/spamassassin/custom.cf.

Fail2ban

Backup

FAQ

DKIM signature is now signed by the new milter program

Attention

If you migrated from iRedMail open source edition or iRedMail Easy, existing DKIM keys were migrated by EE automatically during migration.

All documents are available in GitHub repository, and published under Creative Commons license. You can download the latest version for offline reading. If you found something wrong, please do contact us to fix it.