From e625800ebd00a1d975f2f347879760c48a329d5c Mon Sep 17 00:00:00 2001 From: Zhang Huangbin Date: Mon, 17 Dec 2018 17:57:59 +0800 Subject: [PATCH] Update best practice. --- .../1-iredmail-easy.getting.start.md | 3 + .../iredmail-easy.best.practice.md | 166 ++++++++++++++---- html/iredmail-easy.best.practice.html | 149 ++++++++++++---- html/iredmail-easy.getting.start.html | 2 + 4 files changed, 256 insertions(+), 64 deletions(-) diff --git a/en_US/iredmail-easy/1-iredmail-easy.getting.start.md b/en_US/iredmail-easy/1-iredmail-easy.getting.start.md index fbd7e318..05015d05 100644 --- a/en_US/iredmail-easy/1-iredmail-easy.getting.start.md +++ b/en_US/iredmail-easy/1-iredmail-easy.getting.start.md @@ -17,6 +17,9 @@ get the fast and professional technical support from iRedMail team. We encourage all users to deploy new iRedMail servers with this platform and keep the servers up to date. +Please also read [Best Practice](./iredmail-easy.best.practice.html) to +understand how to achieve fearless one-click with iRedMail Easy. + If you prefer classic downloadable iRedMail installer, you can find the installation guides here: [Install iRedMail](./index.html#install). diff --git a/en_US/iredmail-easy/iredmail-easy.best.practice.md b/en_US/iredmail-easy/iredmail-easy.best.practice.md index 11c4a9d4..b1956190 100644 --- a/en_US/iredmail-easy/iredmail-easy.best.practice.md +++ b/en_US/iredmail-easy/iredmail-easy.best.practice.md @@ -2,27 +2,132 @@ [TOC] -iRedMail Easy (the deployment and support platform) maintains core config files, -it's normal that you want to override some settings in default setup, please -follow some simple rules to store your custom settings, and do not modify the -core config files managed by iRedMail Easy. This is the key to -achieve fear-less upgrade. +## How fearless upgrade works -* If software supports loading settings from multiple config files, you can - write your own config file under `/opt/iredmail/custom//` - without touching its core config files under `/etc/`. For example, Dovecot, - MariaDB, Roundcube, etc. -* If software does not support loading settings from multiple config files, - you may need to apply your own settings by running commands to modify - config files under `/etc/` directly. For example, Postfix (use `postconf` - command). Commands can be written in file - `/opt/iredmail/custom/postfix/custom.sh`, it's ran by iRedMail Easy - each time it deploys or upgrades this software. -* If software doesn't support overriding existing settings, you may need to - remove existing config file first, then write your own config file with new - setting. for example, Nginx. In this case, you need to update - `/opt/iredmail/custom/nginx/custom.sh` to remove config file first, then - write your own config files under `/opt/iredmail/custom/nginx/`. +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//`. 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 Eazy: + +``` +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, please read [details below](#sogo). + +## Softwares ### MariaDB @@ -39,15 +144,14 @@ 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 component. +- `/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. + 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 @@ -59,8 +163,6 @@ max_connections = 1024 - `/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. -#### Directory Structure - iRedMail uses the directory structure recommended by Debian/Ubuntu: ``` @@ -159,3 +261,7 @@ overrode by the last one. `/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/`. + +## References + +* [Dovecot: Including config files](https://wiki.dovecot.org/ConfigFile#Including_config_files) diff --git a/html/iredmail-easy.best.practice.html b/html/iredmail-easy.best.practice.html index a1ed55a2..d85e3ff3 100644 --- a/html/iredmail-easy.best.practice.html +++ b/html/iredmail-easy.best.practice.html @@ -19,11 +19,16 @@
-

iRedMail Eazy (the deployment and support platform) maintains core config files, -it's normal that you want to override some settings in default setup, please -follow some simple rules to store your custom settings, and do not modify the -core config files managed by iRedMail Eazy. This is the key to -achieve fear-less upgrade.

+

How 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 Eazy:

+
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

    -
  • If software supports loading settings from multiple config files, you can - write your own config file under /opt/iredmail/custom/<software-name>/ - without touching its core config files under /etc/. For example, Dovecot, - MariaDB, Roundcube, etc.
    • -
  • If software does not support loading settings from multiple config files, - you may need to apply your own settings by running commands to modify - config files under /etc/ directly. For example, Postfix (use postconf - command). Commands can be written in file - /opt/iredmail/custom/postfix/custom.sh, it's ran by iRedMail Eazy - each time it deploys or upgrades this software.
    • -
  • If software doesn't support overriding existing settings, you may need to - remove existing config file first, then write your own config file with new - setting. for example, Nginx. In this case, you need to update - /opt/iredmail/custom/nginx/custom.sh to remove config file first, then - write your own config files under /opt/iredmail/custom/nginx/.
    • +
  • SOGo doesn't support any of the ways mentioned above, please read details below.
+

Softwares

MariaDB

  • /opt/iredmail/custom/mysql/:
      @@ -74,16 +155,13 @@ 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 Eazy deploys / upgrades the Nginx component.
          • -
        -

        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 Eazy and store custom settings in - another file.

        +

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

        @@ -100,7 +178,6 @@ max_connections = 1024
      • /opt/iredmail/custom/nginx/sites-enabled/: additional virtual web hosts.
      -

      Directory Structure

      iRedMail uses the directory structure recommended by Debian/Ubuntu:

      /etc/nginx/                         # all config files
 
@@ -199,6 +276,10 @@ shell script to do even more complex customization.
      
   /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/.
+
    +

    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.

    diff --git a/html/iredmail-easy.getting.start.html b/html/iredmail-easy.getting.start.html index 94ac960e..b325a11c 100644 --- a/html/iredmail-easy.getting.start.html +++ b/html/iredmail-easy.getting.start.html @@ -50,6 +50,8 @@ platform, it's easy to deploy and keep the iRedMail server up to date, easy to get the fast and professional technical support from iRedMail team.

    We encourage all users to deploy new iRedMail servers with this platform and keep the servers up to date.

    +

    Please also read Best Practice to +understand how to achieve fearless one-click with iRedMail Easy.

    If you prefer classic downloadable iRedMail installer, you can find the installation guides here: Install iRedMail.

    System Requirements