Best Practice

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

SSL cert

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

Softwares

MariaDB

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

[mysqld]
max_connections     = 1024

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

Postfix

Postfix doesn't support loading settings from multiple files.

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.

Roundcube

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

SOGo

iRedAPD

iRedAdmin

Amavisd

Fail2ban

Backup

References

All documents are available in BitBucket 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.