iredmail-doc/en_US/iredmail-easy/2-iredmail-easy.best.practice.md

iRedMail Easy: Best Practice

[TOC]

How the fearless upgrade works

iRedMail Easy splits config files of softwares to 2 parts: Core and Custom, this is the magic of fearless one-click upgrade.

iRedMail Easy maintains core config files to make sure everything works as expected, but we understand that one rule doesn't work for everyone and you may want to change/override some settings configured by iRedMail Easy.

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

Including config files

Many softwares support loading settings from extra config files with directive 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 Easy, 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 Easy:

dovecot_protocols = pop3 imap sieve lmtp

What can you do to disable it 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 (pop3 is removed), then restart Dovecot service:

dovecot_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 Easy, the config file will be rewritten by iRedMail Easy, then you lose all custom settings.

Fortunately, iRedMail Easy 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 Easy 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 Easy and create a new one. Let's use parameter client_max_body_size for example.

iRedMail Easy 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 Easy deploys or upgrades Nginx, it will run this script the same way.

The rest

• SOGo doesn't support any of the ways mentioned above, if you need to modify any settings, please either use /opt/iredmail/custom/sogo/custom.sh to modify please read details below.

SSL cert

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

• key.pem: private key
• cert.pem: certificate
• combined.pem: full chain

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

• Request a free cert from Let's Encrypt, or
• Use a bought SSL certificate.

Passwords

• iRedMail Easy doesn't store any SQL/LDAP passwords on its deployment servers, instead it generates and reads from files under /root/.iredmail/kv/ on YOUR server to get the passwords.
• Files under /root/.iredmail/kv/ contain only one line.
• If you changed any of them, please update files under /root/.iredmail/kv/ also, so that iRedMail Easy can get correct password when you perform upgrade.

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 in mail server profile page on iRedMail Easy platform, you can find it in mail server profile page, under tab Settings.

Custom settings used by softwares

MariaDB

• /opt/iredmail/custom/mysql/:

  • All files end with .cnf will be loaded by Mariadb.

  • It will override existing settings defined in files under /etc/mysql/ (Linux) or /usr/local/etc/mysql/ (FreeBSD).

    Sample config file, /opt/iredmail/custom/mysql/custom.conf:

[mysqld]
max_connections     = 1024

Nginx

• /opt/iredmail/custom/nginx/custom.sh: a bash shell script for advanced customization. This file will be executed every time iRedMail Easy deploys / upgrades the Nginx.

  For example, Nginx doesn't support override existing settings by loading
  same parameter from another config file, in this case you should run `rm`
  command in this file (`custom.sh`) to remove existing config file
  generated by iRedMail Easy and store custom settings in another file.
  

• /opt/iredmail/custom/nginx/conf-enabled/: additional Nginx global settings used inside http {} block.

  • If you want to override a parameter which is already defined in /etc/nginx/conf-enabled/, please update /opt/iredmail/custom/nginx/custom.sh to remove file under /etc/nginx/conf-enabled/ first, then write your own config file under /opt/iredmail/custom/nginx/conf-enabled/ to set a proper value.

• /opt/iredmail/custom/nginx/sites-conf.d/default-ssl/: additional settings for default https website (inside the server {} block).

• /opt/iredmail/custom/nginx/sites-enabled/: additional virtual web hosts.

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/
                        |- custom.sh        # shell script used for advanced customization

Postfix

Postfix doesn't support loading main settings (main.cf and master.cf) from multiple files.

• /opt/iredmail/custom/postfix/main.cf: If this file exists, /etc/postfix/main.cf will be a symbol link to this file.
• /opt/iredmail/custom/postfix/master.cf: If this file exists, /etc/postfix/master.cf will be a symbol link to this file.

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

For example, Postfix loads 2 files for HELO access check:

• /opt/iredmail/custom/postfix/helo_access.pcre: You can add custom HELO access rules in this file, or add rule to override the one defined in /etc/postfix/helo_access.pcre. If access rule in this file matches, Postfix will ignore the second (and all the rest) files.
• /etc/postfix/helo_access.pcre: This file is maintained by iRedMail Easy, you should NOT modify it.

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

• /opt/iredmail/custom/postfix/postscreen_access.cidr

• /opt/iredmail/custom/postfix/custom.sh: a bash shell script for advanced customization. It will be ran each time your ran iRedMail Easy deployment or upgrade.

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

postconf -e enable_original_recipient=yes

To update settings in master.cf, you can run postconf -M and postconf -P. For example, create new transport submission:

postconf -M submission/inet="submission inet n - n - - smtpd"
postconf -P "submission/inet/syslog_name=postfix/submission"
postconf -P "submission/inet/smtpd_tls_security_level=encrypt"
postconf -P "submission/inet/smtpd_sasl_auth_enable=yes"
postconf -P "submission/inet/smtpd_client_restrictions=permit_sasl_authenticated,reject"
postconf -P "submission/inet/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.

• /opt/iredmail/custom/dovecot/conf-enabled/: store custom Dovecot settings.
• /opt/iredmail/custom/dovecot/custom.sh: a bash shell script used for advanced customization

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 Easy deployment, but you need to create the symbol link manually if you don't want to run another deployment.

Custom settings for official plugins

iRedMail Easy enables 2 official plugins by default:

• password: used by end users to change their own passwords.
• managesieve: used by end users to custom mail filter rules.

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

For example:

• For password plugin: /opt/iredmail/custom/roundcube/config_password.inc.php
• For managesieve plugin: /opt/iredmail/custom/roundcube/config_managesieve.inc.php

If you have custom settings for plugin which is not enabled by iRedMail Easy, please append a line to /opt/www/roundcubemail/plugins/<plugin-name>/config.inc.php like below:

require_once "/opt/iredmail/custom/roundcube/config_<plugin>.inc.php";

Then put all custom settings for this plugin to /opt/iredmail/custom/roundcube/config_<plugin>.inc.php.

For example, if you have custom settings for official plugin enigma, you should append this line to /opt/www/roundcubemail/plugins/enigma/config.inc.php:

require_once "/opt/iredmail/custom/roundcube/config_enigma.inc.php";

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

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

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 Easy deployment, but you need to create the symbol link manually if you don't want to run another deployment.

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 Easy platform.

• File /opt/iredmail/custom/sogo/sogo.conf

  If this file exists, /etc/sogo/sogo.conf will be created as a symbol link to this file during iRedMail Easy deployment.

• Shell script /opt/iredmail/custom/sogo/custom.sh

  A bash shell script for advanced customization, you can customize SOGo config file with shell commands organized in this file.

  This file will be ran by iRedMail Easy deployment each time it deploys or upgrade SOGo component.

iRedAPD

• File /opt/iredmail/custom/iredapd/settings.py

  All custom settings must be stored in this file. It will be linked to /opt/www/iredapd/custom_settings.py during iRedMail Easy deployment or upgrade.

iRedAdmin

• File /opt/iredmail/custom/iredadmin/settings.py

  All custom settings must be stored in this file. It will be linked to /opt/www/iredadmin/custom_settings.py during iRedMail Easy deployment or upgrade.

Amavisd

• /opt/iredmail/custom/amavisd/amavisd.conf

Fail2ban

• /opt/iredmail/custom/fail2ban/jail.local: used to override settings in [DEFAULT] section of main fail2ban config file. For example, maxretry, findtime, bantime, ignoreip.
• /opt/iredmail/custom/dovecot/custom.sh: used for advanced customization. for example, if you have some new jails, you can write jail config files under /opt/iredmail/custom/fail2ban/ too (you're free to create sub-folder to store the jail config files), then use custom.sh to create symbol link of jails you want to enable under /etc/fail2ban/jail.d/.

Backup

• iRedMail Easy generates daily cron jobs to backup mail accounts and SQL/LDAP databases (stored under /var/vmail/backup/ by default), but not mailboxes, you need to backup mailboxes yourself.
• Files under /opt/iredmail/custom/ contain all your custom settings. If you need to restore a iRedMail Easy server to another one, please copy /opt/iredmail/custom/ to new server first, then perform the iRedMail Easy deployment.

References

• Dovecot: Including config files