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 config files of software to 2 parts: Core and Custom, this is the magic of fearless one-click upgrade.

iRedMail EE maintains core config files to make sure everything works as expected, but we understand that you may need to change some settings configured by iRedMail EE.

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

Including config files

A lot of 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/.

Files under /etc/dovecot/conf-enabled/ are maintained by iRedMail EE, if you want to override some settings, please create a file which 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, you can change some settings by modifying its config files (e.g. /etc/postfix/main.cf) directly, but next time you upgrade your iRedMail server with iRedMail EE, the config file will be rewritten by iRedMail EE, then you lose all custom settings.

Fortunately, iRedMail EE supports executing a shell script each time it deploying or upgrading a software. 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'

Then run it manually:

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

When iRedMail EE deploys or upgrades Postfix, it will run this script the same way.

Remove existing file and create a new one

Nginx supports loading extra config file with include directive, but it doesn't support overriding existing parameters. for example, if parameter client_max_body_size is defined in one file, but you have include directive to load same parameter in another file, Nginx will report duplicate parameter and refuse to start. In this case, you have to remove existing config files (which contains the parameter you want to customize) generated by iRedMail EE and create a new one. Let's use parameter client_max_body_size for example.

iRedMail EE generates files under /etc/nginx/conf-enabled/ for different parameters, and parameter client_max_body_size is defined in /etc/nginx/conf-enabled/client_max_body_size.conf like this:

client_max_body_size 15m;

You need to add a new file under /opt/iredmail/custom/nginx/conf-enabled/ first, then add shell command in /opt/iredmail/custom/nginx/custom.sh to remove /etc/nginx/conf-enabled/client_max_body_size.conf like below:

rm -f /etc/nginx/conf-enabled/client_max_body_size.conf

Now run this script:

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

When iRedMail EE deploys or upgrades Nginx, it will run this script the same way.

The rest

SSL cert

iRedMail EE generates self-signed ssl cert by default, cert files are stored under /opt/iredmail/ssl/:

To get rid of self-signed cert, you can either:

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 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        # 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 first one 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 scripting 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).

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

References

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.