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.
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
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.
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.
/opt/iredmail/custom/sogo/custom.sh
to modify please read details below.iRedMail Easy generates self-signed ssl cert by default, cert files are stored
under /opt/iredmail/ssl/
:
key.pem
: private keycert.pem
: certificatecombined.pem
: full chainTo get rid of self-signed cert, you can either:
/root/.iredmail/kv/
on
YOUR server to get the passwords./root/.iredmail/kv/
contain only one line./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 . |
/opt/iredmail/custom/mysql/
:.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
/opt/iredmail/custom/openldap/schema/
Extra LDAP schema files must be stored in this directory, owned by OpenLDAP daemon user and group with permission 0640.
/opt/iredmail/custom/openldap/conf.d/global.conf
Extra global settings should be stored in this file. For example, you can load extra LDAP schema file by adding line below:
include /opt/iredmail/custom/openldap/schema/custom.schema
/opt/iredmail/custom/openldap/conf.d/databases.conf
OpenLDAP is configured to run one database for mail domains and accounts by iRedMail Easy, if you want to run extra databases, you can add database related settings in this file. for example:
database mdb
suffix dc=my-ldap-suffix,dc=com
directory /var/lib/ldap/my-ldap-suffix.com
rootdn cn=Manager,dc=my-ldap-suffix,dc=com
rootpw {SSHA}...
sizelimit unlimited
maxsize 2147483648
checkpoint 128 3
mode 0700
index attr_1,attr_2,attr_3 eq,pres
index attr_4,attr_5,attr_6 eq,pres
/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.
/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 doesn't support loading main settings (/etc/postfix/main.cf
and
/etc/postfix/master.cf
) from multiple files, so iRedMail Easy uses alternative
solution to split core and custom settings.
/opt/iredmail/custom/postfix/custom.sh
,
modifying settings in main.cf
and master.cf
with command postconf -e
.
Details will be explained later in this section.main.cf
and master.cf
under /opt/iredmail/custom/postfix/
directory./opt/iredmail/custom/postfix/main.cf
exists, iRedMail Easy will
create /etc/postfix/main.cf
as symbol link to this file./opt/iredmail/custom/postfix/master.cf
exists, iRedMail Easy
will create /etc/postfix/master.cf
as symbol link to this file.For other settings, Postfix is configured to load files under
/opt/iredmail/custom/postfix/
first (they store custom settings and
maintained by you), then another one from /etc/postfix/
(maintained by
iRedMail Easy and you should NOT modify them). If rule defined in first one
matches, Postfix will skip the second file.
For example, Postfix is configured to load 2 files for HELO access check:
smtpd_helo_restrictions =
...
check_helo_access pcre:/opt/iredmail/custom/postfix/helo_access.pcre
check_helo_access pcre:/etc/postfix/helo_access.pcre
...
/opt/iredmail/custom/postfix/helo_access.pcre
, is used to
store your cusotm HELO access rules. If rule in this file matched,
Postfix will ignore other rules defined later in same file, also the second
file /etc/postfix/helo_access.pcre
. So you can write rule in first file
for new HELO access, or write same rule with different action to override the
one defined in /etc/postfix/helo_access.pcre
./etc/postfix/helo_access.pcre
: This file is maintained by iRedMail Easy,
please do NOT modify it.You can find some other files for customization under
/opt/iredmail/custom/postfix/
. For example:
body_checks.pcre
header_checks.pcre
command_filter.pcre
postscreen_access.cidr
There's also a (Bash) shell scripting for flexible customization:
/opt/iredmail/custom/postfix/custom.sh
. It will be ran each time you perform
deployment or upgrade through iRedMail Easy platform.
For example, to set value of parameter enable_original_recipient
to yes
(defaults to no
set in /etc/postfix/main.cf
), you can write command in
/opt/iredmail/custom/postfix/custom.sh
like below:
postconf -e enable_original_recipient=yes
To add new or update existing transport settings in /etc/postfix/master.cf
,
you can run postconf -M
and postconf -P
. For example, create new transport
465
for SMTPS (SMTP over SSL):
postconf -M 465/inet="465 inet n - n - - smtpd"
postconf -P "465/inet/syslog_name=postfix/smtps"
postconf -P "465/inet/smtpd_tls_wrappermode=yes"
postconf -P "465/inet/smtpd_sasl_auth_enable=yes"
postconf -P "465/inet/smtpd_client_restrictions=permit_sasl_authenticated,reject"
postconf -P "465/inet/content_filter=smtp-amavis:[127.0.0.1]:10026"
It will generate new lines in /etc/postfix/master.cf
like below:
465 inet n - n - - smtpd
-o syslog_name=postfix/smtps
-o smtpd_tls_wrappermode=yes
-o smtpd_sasl_auth_enable=yes
-o smtpd_client_restrictions=permit_sasl_authenticated,reject
-o content_filter=smtp-amavis:[127.0.0.1]:10026
For more details about postconf
command, please check its manual page:
postconf(1).
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/opt/iredmail/custom/dovecot/dovecot.sieve
: custom global sieve rule file.
If this file exists, iRedMail Easy will link it to
/var/vmail/sieve/dovecot.sieve
as global sieve rule file.
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
.
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.
iRedMail Easy enables 3 official plugins by default:
password
: used by end users to change their own passwords.managesieve
: used by end users to custom mail filter rules.markasjunk
: used by end users to report spam or ham.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:
password
plugin: /opt/iredmail/custom/roundcube/config_password.inc.php
managesieve
plugin: /opt/iredmail/custom/roundcube/config_managesieve.inc.php
markasjunk
plugin: /opt/iredmail/custom/roundcube/config_markasjunk.inc.php
If you need to enable some Roundcube official plugin which is not enabled by iRedMail Easy:
/opt/iredmail/custom/roundcube/custom.sh
(Note: replace <plugin>
by the real plugin name):cd /opt/www/roundcubemail/plugins/<plugin>/
cp config.inc.php.dist config.inc.php
echo 'require_once "/opt/iredmail/custom/roundcube/config_<plugin>.inc.php";' >> config.inc.php
/opt/iredmail/custom/roundcube/config_<plugin>.inc.php
and
store all your custom settings in this file. WARNING: this file must be a
valid php file.This way if iRedMail Easy enables this plugin in the future, it will successfully load your own custom settings and not mess it up.
For example, if you have custom settings for official plugin enigma
, you
should add shell commands like below in /opt/iredmail/custom/roundcube/custom.sh
cd /opt/www/roundcubemail/plugins/engma/
cp config.inc.php.dist config.inc.php
echo 'require_once "/opt/iredmail/custom/roundcube/config_enigma.inc.php";' >> config.inc.php
Then put all custom settings for plugin enigma
to
/opt/iredmail/custom/roundcube/config_enigma.inc.php
.
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 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.
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.
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.
/opt/iredmail/custom/amavisd/amavisd.conf
/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/fail2ban/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/
./var/vmail/backup/
by default), but not mailboxes, you
need to backup mailboxes yourself./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.