2018-09-02 22:43:13 -05:00
# Best Practice
[TOC]
2018-12-17 06:20:35 -06:00
## How the fearless upgrade works
2018-12-17 03:57:59 -06:00
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
2019-03-24 19:25:20 -06:00
iRedMail Easy:
2018-12-17 03:57:59 -06:00
```
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
2018-12-17 06:20:35 -06:00
* 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 ](#sogo ).
2018-12-17 03:57:59 -06:00
2019-01-13 09:07:22 -06:00
## 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 ](./letsencrypt.html ), or
* [Use a bought SSL certificate ](./use.a.bought.ssl.certificate.html ).
2018-12-17 03:57:59 -06:00
## Softwares
2018-09-02 22:43:13 -05:00
### 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/` .
Sample config file, `/opt/iredmail/custom/mysql/custom.conf` :
```
[mysqld]
max_connections = 1024
```
### Nginx
2018-12-17 03:57:59 -06:00
- `/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.
2018-09-02 22:43:13 -05:00
2018-12-17 03:57:59 -06:00
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.
2018-09-02 22:43:13 -05:00
2018-09-03 07:58:22 -05:00
- `/opt/iredmail/custom/nginx/conf-enabled/` : additional Nginx global settings used inside `http {}` block.
2018-09-02 22:43:13 -05:00
- 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 settings 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.
- `/opt/iredmail/custom/postfix/helo_access.pcre`
- `/opt/iredmail/custom/postfix/postscreen_access.cidr`
2019-06-21 00:49:56 -05:00
- `/opt/iredmail/custom/postfix/custom.sh` : a bash shell script for advanced customization. It will be ran while iRedMail Easy deployment or upgrade.
2019-01-28 22:13:37 -06:00
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:
2019-06-21 00:49:56 -05:00
```
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
```
2019-07-13 06:21:55 -05:00
For more details about `postconf` command, please check its manual page:
2019-06-21 00:49:56 -05:00
[postconf(1) ](http://www.postfix.org/postconf.1.html ).
2018-09-02 22:43:13 -05:00
### 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
- `/opt/iredmail/custom/roundcube/custom.inc.php` .
All your custom settings should be placed in this file, and do __NOT__
touch main config file `/opt/www/roundcubemail/config/config.inc.php` .
- `/opt/iredmail/custom/roundcube/plugins/` : all third-party / custom
plugins should be placed under this directory. Plugins will be linked
to `/opt/www/roundcubemail/plugins/` automatically.
- `/opt/iredmail/custom/roundcube/skins/` : all third-party / custom
skins should be placed under this directory. Skins will be linked
to `/opt/www/roundcubemail/skins/` automatically.
### SOGo
- `/opt/iredmail/custom/sogo/sogo.conf` : If this file exists, `/etc/sogo/sogo.conf` will be a symbol link to this file.
- `/opt/iredmail/custom/sogo/custom.sh` : a bash shell script for advanced customization
Currently SOGo doesn’ `include` directive to load config
from multiple files, so you can either maintain your own SOGo config
file (`/opt/iredmail/custom/sogo/sogo.conf`) or use the `custom.sh`
shell script to do even more complex customization.
### iRedAPD
- `/opt/iredmail/custom/iredapd/settings.py` . It will be linked to `/opt/www/iredapd/custom_settings.py` also.
### iRedAdmin
- `/opt/iredmail/custom/iredadmin/settings.py` . it will be linked to `/opt/www/iredadmin/custom_settings.py` also.
### 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/` .
2018-12-17 03:57:59 -06:00
2019-06-16 22:57:26 -05:00
## 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.
2018-12-17 03:57:59 -06:00
## References
* [Dovecot: Including config files ](https://wiki.dovecot.org/ConfigFile#Including_config_files )
