434 lines
18 KiB
Markdown
434 lines
18 KiB
Markdown
# 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](#sogo).
|
||
|
||
## 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).
|
||
|
||
## 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)<br/>`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)<br>`/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)](http://www.postfix.org/postconf.1.html).
|
||
|
||
### 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](https://wiki.dovecot.org/ConfigFile#Including_config_files)
|