315 lines
16 KiB
HTML
315 lines
16 KiB
HTML
<!DOCTYPE html>
|
||
<html>
|
||
<head>
|
||
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
||
<title>Best Practice</title>
|
||
<link rel="stylesheet" type="text/css" href="./css/markdown.css" />
|
||
</head>
|
||
<body>
|
||
|
||
<div id="navigation">
|
||
<a href="https://www.iredmail.org" target="_blank">
|
||
<img alt="iRedMail web site"
|
||
src="./images/logo-iredmail.png"
|
||
style="vertical-align: middle; height: 30px;"
|
||
/>
|
||
<span>iRedMail</span>
|
||
</a>
|
||
// <a href="./index.html">Document Index</a></div><h1 id="best-practice">Best Practice</h1>
|
||
<div class="toc">
|
||
<ul>
|
||
<li><a href="#best-practice">Best Practice</a><ul>
|
||
<li><a href="#how-the-fearless-upgrade-works">How the fearless upgrade works</a><ul>
|
||
<li><a href="#including-config-files">Including config files</a></li>
|
||
<li><a href="#modify-config-files-in-place">Modify config files in-place</a></li>
|
||
<li><a href="#remove-existing-file-and-create-a-new-one">Remove existing file and create a new one</a></li>
|
||
<li><a href="#the-rest">The rest</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#ssl-cert">SSL cert</a></li>
|
||
<li><a href="#softwares">Softwares</a><ul>
|
||
<li><a href="#mariadb">MariaDB</a></li>
|
||
<li><a href="#nginx">Nginx</a></li>
|
||
<li><a href="#postfix">Postfix</a></li>
|
||
<li><a href="#dovecot">Dovecot</a></li>
|
||
<li><a href="#roundcube">Roundcube</a></li>
|
||
<li><a href="#sogo">SOGo</a></li>
|
||
<li><a href="#iredapd">iRedAPD</a></li>
|
||
<li><a href="#iredadmin">iRedAdmin</a></li>
|
||
<li><a href="#amavisd">Amavisd</a></li>
|
||
<li><a href="#fail2ban">Fail2ban</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#references">References</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
<h2 id="how-the-fearless-upgrade-works">How the fearless upgrade works</h2>
|
||
<p>iRedMail Easy splits config files of softwares to 2 parts: Core and Custom,
|
||
this is the magic of fearless one-click upgrade.</p>
|
||
<p>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.</p>
|
||
<p>Please follow some simple rules to store your custom settings, and do not
|
||
modify the core config files (manually) managed by iRedMail Easy.</p>
|
||
<h3 id="including-config-files">Including config files</h3>
|
||
<p>Many softwares support loading settings from extra config files with directive
|
||
like <code>include</code> (Nginx, Dovecot), <code>include_try</code> (Dovecot), <code>require_once</code> (PHP
|
||
applications). In this case, it will be configured to load extra config files
|
||
under <code>/opt/iredmail/custom/<software-name>/</code>. We use Dovecot for example to
|
||
explain the details.</p>
|
||
<p>Dovecot's main config file is <code>/etc/dovecot/dovecot.conf</code>, we have directives
|
||
at the bottom of <code>dovecot.conf</code> like this:</p>
|
||
<pre><code>!include_try /etc/dovecot/conf-enabled/*.conf
|
||
!include_try /opt/iredmail/custom/dovecot/conf-enabled/*.conf
|
||
</code></pre>
|
||
|
||
<p>It will try to load all files ends with <code>.conf</code> under
|
||
<code>/etc/dovecot/conf-enabled/</code> first, then
|
||
<code>/opt/iredmail/custom/dovecot/conf-enabled/</code>.</p>
|
||
<p>Files under <code>/etc/dovecot/conf-enabled/</code> are maintained by iRedMail Easy, if
|
||
you want to override some settings, please create a file which ends with
|
||
<code>.conf</code> under <code>/opt/iredmail/custom/dovecot/conf-enabled/</code> with your custom
|
||
settings. for example, Dovecot is configured to enable services like below by
|
||
iRedMail Easy:</p>
|
||
<pre><code>dovecot_protocols = pop3 imap sieve lmtp
|
||
</code></pre>
|
||
|
||
<p>What can you do to disable it without modify files under <code>/etc/dovecot/</code>? Easy,
|
||
just create a file, e.g. <code>custom.conf</code> under
|
||
<code>/opt/iredmail/custom/dovecot/conf-enabled/</code> with content below (<code>pop3</code> is
|
||
removed), then restart Dovecot service:</p>
|
||
<pre><code>dovecot_protocols = imap sieve lmtp
|
||
</code></pre>
|
||
|
||
<h3 id="modify-config-files-in-place">Modify config files in-place</h3>
|
||
<p>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 <code>/etc/</code>. For example, Postfix.</p>
|
||
<p>Postfix doesn't support directive like <code>include</code> to load extra config files,
|
||
you can change some settings by modifying its config files (e.g.
|
||
<code>/etc/postfix/main.cf</code>) 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.</p>
|
||
<p>Fortunately, iRedMail Easy supports executing a shell script each time it
|
||
deploying or upgrading a software. For Postfix, it's
|
||
<code>/opt/iredmail/custom/postfix/custom.sh</code>.</p>
|
||
<p>Let's say you want to add IP address <code>192.168.1.1</code> to Postfix parameter
|
||
<code>mynetworks</code>, instead of modifying <code>/etc/postfix/main.cf</code> directly, you can
|
||
write shell commands in <code>/opt/iredmail/custom/postfix/custom.sh</code> like below:</p>
|
||
<pre><code>postconf -e mynetworks='127.0.0.1 192.168.1.1'
|
||
</code></pre>
|
||
|
||
<p>Then run it manually:</p>
|
||
<pre><code>cd /opt/iredmail/custom/postfix/
|
||
bash custom.sh
|
||
</code></pre>
|
||
|
||
<p>When iRedMail Easy deploys or upgrades Postfix, it will run this script the
|
||
same way.</p>
|
||
<h3 id="remove-existing-file-and-create-a-new-one">Remove existing file and create a new one</h3>
|
||
<p>Nginx supports loading extra config file with <code>include</code> directive, but it
|
||
doesn't support overriding existing parameters. for example, if parameter
|
||
<code>client_max_body_size</code> is defined in one file, but you have <code>include</code> 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 <code>client_max_body_size</code> for example.</p>
|
||
<p>iRedMail Easy generates files under <code>/etc/nginx/conf-enabled/</code> for different
|
||
parameters, and parameter <code>client_max_body_size</code> is defined in
|
||
<code>/etc/nginx/conf-enabled/client_max_body_size.conf</code> like this:</p>
|
||
<pre><code>client_max_body_size 15m;
|
||
</code></pre>
|
||
|
||
<p>You need to add a new file under <code>/opt/iredmail/custom/nginx/conf-enabled/</code>
|
||
first, then add shell command in <code>/opt/iredmail/custom/nginx/custom.sh</code> to
|
||
remove <code>/etc/nginx/conf-enabled/client_max_body_size.conf</code> like below:</p>
|
||
<pre><code>rm -f /etc/nginx/conf-enabled/client_max_body_size.conf
|
||
</code></pre>
|
||
|
||
<p>Now run this script:</p>
|
||
<pre><code>cd /opt/iredmail/custom/nginx/
|
||
bash custom.sh
|
||
</code></pre>
|
||
|
||
<p>When iRedMail Easy deploys or upgrades Nginx, it will run this script the
|
||
same way.</p>
|
||
<h3 id="the-rest">The rest</h3>
|
||
<ul>
|
||
<li>SOGo doesn't support any of the ways mentioned above, if you need to modify any settings, please either use <code>/opt/iredmail/custom/sogo/custom.sh</code> to modify please read <a href="#sogo">details below</a>.</li>
|
||
</ul>
|
||
<h2 id="ssl-cert">SSL cert</h2>
|
||
<p>iRedMail Easy generates self-signed ssl cert by default, cert files are stored
|
||
under <code>/opt/iredmail/ssl/</code>:</p>
|
||
<ul>
|
||
<li><code>key.pem</code>: private key</li>
|
||
<li><code>cert.pem</code>: certificate</li>
|
||
<li><code>combined.pem</code>: full chain</li>
|
||
</ul>
|
||
<p>To get rid of self-signed cert, you can either:</p>
|
||
<ul>
|
||
<li><a href="./letsencrypt.html">Request a free cert from Let's Encrypt</a>, or</li>
|
||
<li><a href="./use.a.bought.ssl.certificate.html">Use a bought SSL certificate</a>.</li>
|
||
</ul>
|
||
<h2 id="softwares">Softwares</h2>
|
||
<h3 id="mariadb">MariaDB</h3>
|
||
<ul>
|
||
<li><code>/opt/iredmail/custom/mysql/</code>:<ul>
|
||
<li>All files end with <code>.cnf</code> will be loaded by Mariadb.</li>
|
||
<li>It will override existing settings defined in files under <code>/etc/mysql/</code>.</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>Sample config file, <code>/opt/iredmail/custom/mysql/custom.conf</code>:</p>
|
||
<pre><code>[mysqld]
|
||
max_connections = 1024
|
||
</code></pre>
|
||
|
||
<h3 id="nginx">Nginx</h3>
|
||
<ul>
|
||
<li>
|
||
<p><code>/opt/iredmail/custom/nginx/custom.sh</code>: a bash shell script for advanced
|
||
customization. This file will be executed every time iRedMail Easy deploys /
|
||
upgrades the Nginx.</p>
|
||
<p>For example, Nginx doesn't support override existing settings by loading
|
||
same parameter from another config file, in this case you should run <code>rm</code>
|
||
command in this file (<code>custom.sh</code>) to remove existing config file
|
||
generated by iRedMail Easy and store custom settings in another file.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>/opt/iredmail/custom/nginx/conf-enabled/</code>: additional Nginx global settings used inside <code>http {}</code> block.</p>
|
||
<ul>
|
||
<li>If you want to override a parameter which is already defined in
|
||
<code>/etc/nginx/conf-enabled/</code>, please update <code>/opt/iredmail/custom/nginx/custom.sh</code>
|
||
to remove file under <code>/etc/nginx/conf-enabled/</code> first, then write your
|
||
own config file under <code>/opt/iredmail/custom/nginx/conf-enabled/</code> to set
|
||
a proper value.</li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<p><code>/opt/iredmail/custom/nginx/sites-conf.d/default-ssl/</code>: additional settings for default https website (inside the <code>server {}</code> block).</p>
|
||
</li>
|
||
<li><code>/opt/iredmail/custom/nginx/sites-enabled/</code>: additional virtual web hosts.</li>
|
||
</ul>
|
||
<p>iRedMail uses the directory structure recommended by Debian/Ubuntu:</p>
|
||
<pre><code>/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
|
||
</code></pre>
|
||
|
||
<h3 id="postfix">Postfix</h3>
|
||
<p>Postfix doesn't support loading settings from multiple files.</p>
|
||
<ul>
|
||
<li><code>/opt/iredmail/custom/postfix/main.cf</code>: If this file exists, <code>/etc/postfix/main.cf</code> will be a symbol link to this file.</li>
|
||
<li><code>/opt/iredmail/custom/postfix/master.cf</code>: If this file exists, <code>/etc/postfix/master.cf</code> will be a symbol link to this file.</li>
|
||
<li><code>/opt/iredmail/custom/postfix/helo_access.pcre</code></li>
|
||
<li><code>/opt/iredmail/custom/postfix/postscreen_access.cidr</code></li>
|
||
<li>
|
||
<p><code>/opt/iredmail/custom/postfix/custom.sh</code>: a bash shell script for advanced customization.</p>
|
||
<p>For example, to change setting <code>enable_original_recipient</code> to <code>yes</code>
|
||
(defaults to <code>no</code> set in <code>/etc/postfix/main.cf</code>), you can write one shell
|
||
command in <code>/opt/iredmail/custom/postfix/custom.sh</code> like below:</p>
|
||
<p><code>postconf -e enable_original_recipient=yes</code></p>
|
||
</li>
|
||
</ul>
|
||
<h3 id="dovecot">Dovecot</h3>
|
||
<p>Dovecot supports loading from mulitple config files, and settings will be
|
||
overrode by the last one.</p>
|
||
<ul>
|
||
<li><code>/opt/iredmail/custom/dovecot/conf-enabled/</code>: store custom Dovecot settings.</li>
|
||
<li><code>/opt/iredmail/custom/dovecot/custom.sh</code>: a bash shell script used for advanced customization</li>
|
||
</ul>
|
||
<h3 id="roundcube">Roundcube</h3>
|
||
<ul>
|
||
<li><code>/opt/iredmail/custom/roundcube/custom.inc.php</code>.</li>
|
||
</ul>
|
||
<p>All your custom settings should be placed in this file, and do <strong>NOT</strong>
|
||
touch main config file <code>/opt/www/roundcubemail/config/config.inc.php</code>.</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>/opt/iredmail/custom/roundcube/plugins/</code>: all third-party / custom
|
||
plugins should be placed under this directory. Plugins will be linked
|
||
to <code>/opt/www/roundcubemail/plugins/</code> automatically.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>/opt/iredmail/custom/roundcube/skins/</code>: all third-party / custom
|
||
skins should be placed under this directory. Skins will be linked
|
||
to <code>/opt/www/roundcubemail/skins/</code> automatically.</p>
|
||
</li>
|
||
</ul>
|
||
<h3 id="sogo">SOGo</h3>
|
||
<ul>
|
||
<li><code>/opt/iredmail/custom/sogo/sogo.conf</code>: If this file exists, <code>/etc/sogo/sogo.conf</code> will be a symbol link to this file.</li>
|
||
<li>
|
||
<p><code>/opt/iredmail/custom/sogo/custom.sh</code>: a bash shell script for advanced customization</p>
|
||
<p>Currently SOGo doesn’t support <code>include</code> directive to load config
|
||
from multiple files, so you can either maintain your own SOGo config
|
||
file (<code>/opt/iredmail/custom/sogo/sogo.conf</code>) or use the <code>custom.sh</code>
|
||
shell script to do even more complex customization.</p>
|
||
</li>
|
||
</ul>
|
||
<h3 id="iredapd">iRedAPD</h3>
|
||
<ul>
|
||
<li><code>/opt/iredmail/custom/iredapd/settings.py</code>. It will be linked to <code>/opt/www/iredapd/custom_settings.py</code> also.</li>
|
||
</ul>
|
||
<h3 id="iredadmin">iRedAdmin</h3>
|
||
<ul>
|
||
<li><code>/opt/iredmail/custom/iredadmin/settings.py</code>. it will be linked to <code>/opt/www/iredadmin/custom_settings.py</code> also.</li>
|
||
</ul>
|
||
<h3 id="amavisd">Amavisd</h3>
|
||
<ul>
|
||
<li><code>/opt/iredmail/custom/amavisd/amavisd.conf</code></li>
|
||
</ul>
|
||
<h3 id="fail2ban">Fail2ban</h3>
|
||
<ul>
|
||
<li><code>/opt/iredmail/custom/fail2ban/jail.local</code>: used to override settings in
|
||
<code>[DEFAULT]</code> section of main fail2ban config file. For example, <code>maxretry</code>, <code>findtime</code>, <code>bantime</code>,
|
||
<code>ignoreip</code>.</li>
|
||
<li><code>/opt/iredmail/custom/dovecot/custom.sh</code>: used for advanced customization.
|
||
for example, if you have some new jails, you can write jail config files under
|
||
<code>/opt/iredmail/custom/fail2ban/</code> too (you're free to create sub-folder to
|
||
store the jail config files), then use <code>custom.sh</code> to create symbol link
|
||
of jails you want to enable under <code>/etc/fail2ban/jail.d/</code>.</li>
|
||
</ul>
|
||
<h2 id="references">References</h2>
|
||
<ul>
|
||
<li><a href="https://wiki.dovecot.org/ConfigFile#Including_config_files">Dovecot: Including config files</a></li>
|
||
</ul><div class="footer">
|
||
<p style="text-align: center; color: grey;">All documents are available in <a href="https://bitbucket.org/zhb/iredmail-docs/src">BitBucket repository</a>, and published under <a href="http://creativecommons.org/licenses/by-nd/3.0/us/" target="_blank">Creative Commons</a> license. You can <a href="https://bitbucket.org/zhb/iredmail-docs/get/tip.tar.bz2">download the latest version</a> for offline reading. If you found something wrong, please do <a href="https://www.iredmail.org/contact.html">contact us</a> to fix it.</p>
|
||
</div>
|
||
<!-- Global site tag (gtag.js) - Google Analytics -->
|
||
<script async src="https://www.googletagmanager.com/gtag/js?id=UA-3293801-21"></script>
|
||
<script>
|
||
window.dataLayer = window.dataLayer || [];
|
||
function gtag(){dataLayer.push(arguments);}
|
||
gtag('js', new Date());
|
||
|
||
gtag('config', 'UA-3293801-21');
|
||
</script>
|
||
</body></html> |