elmau
/
iredmail-doc
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
iredmail-doc/html_bk/manage.iredapd.html

416 lines
20 KiB
HTML
Raw Permalink Blame History

<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Manage iRedAPD (white/blacklists, greylisting, throttling and more)</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;"
/>&nbsp;
<span>iRedMail</span>
</a>
&nbsp;&nbsp;//&nbsp;&nbsp;<a href="./index.html">Document Index</a></div><h1 id="manage-iredapd-whiteblacklists-greylisting-throttling-and-more">Manage iRedAPD (white/blacklists, greylisting, throttling and more)</h1>
<div class="toc">
<ul>
<li><a href="#manage-iredapd-whiteblacklists-greylisting-throttling-and-more">Manage iRedAPD (white/blacklists, greylisting, throttling and more)</a><ul>
<li><a href="#introduce-iredapd">Introduce iRedAPD</a></li>
<li><a href="#how-to-disable-iredapd-service">How to disable iRedAPD service</a></li>
<li><a href="#how-to-enable-or-disable-iredapd-plugins">How to enable or disable iRedAPD plugins</a></li>
<li><a href="#how-to-add-custom-settings">How to add custom settings</a></li>
<li><a href="#features">Features</a><ul>
<li><a href="#sender-address-restrictions">Sender Address Restrictions</a></li>
<li><a href="#whiteblacklisting">White/Blacklisting</a><ul>
<li><a href="#how-to-disable-whiteblacklists-completely">How to disable white/blacklists completely</a></li>
<li><a href="#manage-whiteblacklists">Manage white/blacklists</a><ul>
<li><a href="#available-arguments">Available arguments</a></li>
<li><a href="#valid-formats-of-whitelisted-and-blacklisted-addresses">Valid formats of whitelisted and blacklisted addresses</a></li>
<li><a href="#sample-usages">Sample usages</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#greylisting">Greylisting</a><ul>
<li><a href="#how-to-disable-greylisting-service-globally">How to disable greylisting service globally</a></li>
<li><a href="#general-settings">General settings</a></li>
<li><a href="#manage-greylisting-settings">Manage greylisting settings</a><ul>
<li><a href="#available-arguments_1">Available arguments</a></li>
<li><a href="#sample-usages_1">Sample usages</a></li>
<li><a href="#recommended-additional-greylisting-whitelist-support">RECOMMENDED: Additional greylisting whitelist support</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>All iRedAPD features listed in current page can be managed with our
web-based admin panel - <a href="https://www.iredmail.org/admin_panel.html">iRedAdmin-Pro</a>.</p>
</div>
<div class="admonition attention">
<p class="admonition-title">Attention</p>
<p>iRedAPD-4.0 and later releases requires Python 3, if you're running
iRedAPD-3.6 or earlier release, please run commands with Python 2 instead.</p>
</div>
<h2 id="introduce-iredapd">Introduce iRedAPD</h2>
<p>iRedAPD is a simple Postfix policy server, written in Python, with plugin
support. It listens on <code>127.0.0.1:7777</code> by default, and runs as a low-privileged
user <code>iredapd</code>.</p>
<p>Source code is hosted on <a href="https://github.com/iredmail/iRedAPD">GitHub</a>.</p>
<h2 id="how-to-disable-iredapd-service">How to disable iRedAPD service</h2>
<p>To disable iRedAPD service:</p>
<ol>
<li>please remove all <code>check_policy_service inet:127.0.0.1:7777</code> in Postfix config file
<code>/etc/postfix/main.cf</code> (Linux/OpenBSD) or <code>/usr/local/etc/postfix/main.cf</code>
(FreeBSD).</li>
<li>Restart or reload Postfix service.</li>
<li>Disable iredapd service.</li>
</ol>
<h2 id="how-to-enable-or-disable-iredapd-plugins">How to enable or disable iRedAPD plugins</h2>
<p>iRedAPD plugins are Python files under <code>/opt/iredapd/plugins/</code> directory. To
enable a plugin, please find line <code>plugins =</code> in iRedAPD config file
<code>/opt/iredapd/settings.py</code>, for example:</p>
<pre><code>plugins = ['greylisting', 'throttle']
</code></pre>
<p>If you want to enable plugin <code>reject_sender_login_mismatch</code> (file
<code>/opt/iredapd/plugins/reject_sender_login_mismatch.py</code>), please add the plugin
name without extension <code>.py</code> in <code>plugins =</code> like below, then restart iRedAPD
service:</p>
<pre><code>plugins = ['greylisting', 'throttle', 'reject_sender_login_mismatch']
</code></pre>
<p>The priorities of plugins shipped in iRedAPD are hard-coded, so the order of
plugin names doesn't matter.</p>
<p>To disable a plugin, just remove the plugin name and restart iRedAPD service.</p>
<h2 id="how-to-add-custom-settings">How to add custom settings</h2>
<p>iRedAPD has some default settings in file
<code>/opt/iredapd/libs/default_settings.py</code>, but you should never modify it.
Instead, you should copy the settings you want to modify from
<code>/opt/iredapd/libs/default_settings.py</code> to <code>/opt/iredapd/settings.py</code>, then
update it with new values. This way you will keep custom settings after
upgrading iRedAPD -- because iRedAPD upgrade tool will copy
<code>/opt/iredapd/settings.py</code> to new iRedAPD release during upgrading.</p>
<h2 id="features">Features</h2>
<h3 id="sender-address-restrictions">Sender Address Restrictions</h3>
<p>Plugin <code>reject_sender_login_mismatch</code> will reject emails if:</p>
<ul>
<li>smtp authentication username (<code>sasl_username</code>) is different from sender
address (<code>From:</code> in mail header). This is called <code>sender login mismatch</code>.
Note: This can be performed by Postfix with restriction rule
<code>reject_sender_login_mismatch</code> in <code>smtpd_sender_restrictions =</code>, but iRedAPD
plugin does more work.</li>
<li>sender domain is hosted on localhost, but sender doesn't perform smtp auth
to send email. This is called "forged" email.</li>
</ul>
<p>It offers some parameters to control whether or not to reject email:</p>
<ul>
<li>for forged sender address checking:</li>
</ul>
<pre><code># Check whether sender is forged in message sent without smtp auth.
CHECK_FORGED_SENDER = True
# If you allow someone or some service providers to send email as forged
# (your local) address, you can list all allowed addresses in this parameter.
# For example, if some ISPs may send email as 'user@mydomain.com' (mydomain.com
# is hosted on your server) to you, you should add `user@mydomain.com` as one
# of forged senders.
# Sample: ALLOWED_FORGED_SENDERS = ['user@mydomain.com', 'mydomain.com']
ALLOWED_FORGED_SENDERS = []
</code></pre>
<ul>
<li>for sender login mismatch:</li>
</ul>
<pre><code># Allow sender login mismatch for specified senders or sender domains.
#
# Sample setting: allow local user `user@local_domain_1.com` and all users
# under `local_domain_2.com` to send email as other users.
#
# ALLOWED_LOGIN_MISMATCH_SENDERS = ['user@local_domain_1.com', 'local_domain_2.com']
ALLOWED_LOGIN_MISMATCH_SENDERS = []
# Strictly allow sender to send as one of user alias addresses. Default is True.
ALLOWED_LOGIN_MISMATCH_STRICTLY = True
# Allow member of mail lists/alias account to send email as mail list/alias
# ('From: &lt;email_of_mail_list&gt;' in mail header). Default is False.
ALLOWED_LOGIN_MISMATCH_LIST_MEMBER = False
</code></pre>
<h3 id="whiteblacklisting">White/Blacklisting</h3>
<h4 id="how-to-disable-whiteblacklists-completely">How to disable white/blacklists completely</h4>
<p>To disable white/blacklists completely, please remove plugin name
<code>amavisd_wblist</code> in iRedAPD config file <code>/opt/iredapd/settings.py</code>,
parameter <code>plugins =</code>:</p>
<pre><code>plugins = [..., 'amavisd_wblist', ...]
</code></pre>
<p>Restarting iRedAPD service is required.</p>
<h4 id="manage-whiteblacklists">Manage white/blacklists</h4>
<blockquote>
<ul>
<li>White/blacklisting is available in iRedAPD-1.4.4 and later releases.</li>
<li>Script <code>tools/wblist_admin.py</code> is available in iRedAPD-1.7.0 and later releases.</li>
</ul>
</blockquote>
<p>White/blacklisting is controlled by plugin <code>amavisd_wblist</code> (file
<code>/opt/iredapd/plugins/amavisd_wblist.py</code>), you can manage it with script
<code>/opt/iredapd/tools/wblist_admin.py</code>.</p>
<h5 id="available-arguments">Available arguments</h5>
<pre><code> --outbound
Manage white/blacklist for outbound messages.
If no '--outbound' argument, defaults to manage inbound messages.
--account account
Add white/blacklists for specified (local) account. Valid formats:
- a single user: username@domain.com
- a single domain: @domain.com
- entire domain and all its sub-domains: @.domain.com
- anyone: @. (the ending dot is required)
if no '--account' argument, defaults to '@.' (anyone).
--add
Add white/blacklists for specified (local) account.
--delete
Delete specified white/blacklists for specified (local) account.
--delete-all
Delete ALL white/blacklists for specified (local) account.
--list
Show existing white/blacklists for specified (local) account. If no
account specified, defaults to manage server-wide white/blacklists.
--whitelist sender1 [sender2 sender3 ...]
Whitelist specified sender(s). Multiple senders must be separated by a space.
--blacklist sender1 [sender2 sender3 ...]
Blacklist specified sender(s). Multiple senders must be separated by a space.
WARNING: Do not use --list, --add-whitelist, --add-blacklist at the same time.
</code></pre>
<h5 id="valid-formats-of-whitelisted-and-blacklisted-addresses">Valid formats of whitelisted and blacklisted addresses</h5>
<ul>
<li>a single user: <code>user@domain.com</code></li>
<li>a single domain: <code>@domain.com</code>, <code>@sub.domain.com</code></li>
<li>entire domain and all its sub-domains: <code>@.domain.com</code> (there's a dot after <code>@</code>)</li>
<li>anyone: <code>@.</code> (the ending dot is required). it catches all addresses.</li>
<li>top-level domain: <code>@.com</code></li>
<li>single ip address: <code>192.168.1.2</code></li>
<li>CIDR network: <code>192.168.1.0/24</code></li>
</ul>
<h5 id="sample-usages">Sample usages</h5>
<ul>
<li>Show and add server-wide whitelists or blacklists:</li>
</ul>
<pre><code>python3 wblist_admin.py --list --whitelist
python3 wblist_admin.py --list --blacklist
# Whitelist IP address, email address, entire domain, subdomain (including main domain)
python3 wblist_admin.py --add --whitelist 192.168.1.10 user@domain.com @iredmail.org @.example.com
# Blacklist IP address, email address, entire domain, subdomain (including main domain)
python3 wblist_admin.py --add --blacklist 202.96.134.133 bad-user@domain.com @bad-domain.com @.sub-domain.com
</code></pre>
<ul>
<li>For per-user or per-domain whitelists and blacklists, please use option
<code>--account</code>. for example:</li>
</ul>
<pre><code>python3 wblist_admin.py --account @mydomain.com --add --whitelist 192.168.1.10 user@example.com
python3 wblist_admin.py --account user@mydomain.com --add --blacklist 172.16.1.10 baduser@example.com
python3 wblist_admin.py --account @mydomain.com --list --whitelist
python3 wblist_admin.py --account user@mydomain.com --list --blacklist
</code></pre>
<h3 id="greylisting">Greylisting</h3>
<div class="admonition attention">
<p class="admonition-title">Attention</p>
<p>Greylisting is available in iRedAPD-1.7.0 and later releases.</p>
</div>
<p>For technical details about greylisting, please visit <a href="http://greylisting.org/">http://greylisting.org/</a></p>
<h4 id="how-to-disable-greylisting-service-globally">How to disable greylisting service globally</h4>
<p>To disable greylisting global, please run command below:</p>
<pre><code>python3 /opt/iredapd/tools/greylisting_admin.py --disable --from '@.'
</code></pre>
<h4 id="general-settings">General settings</h4>
<p>There're several settings for greylisting behaviour, default values are defined
in <code>/opt/iredapd/libs/default_settings.py</code>. If you want to modify them, please
add the settings with custom values in <code>/opt/iredapd/settings.py</code>.</p>
<ul>
<li><code>GREYLISTING_TRAINING_MODE</code>: enable greylisting service, but don't reject
any emails. This training mode is useful if this is a new mail server, it
collects information of sender servers for further use.</li>
<li><code>GREYLISTING_MESSAGE</code>: the rejection message which will be sent to sender
server. Default is <code>Intentional policy rejection, please try again later</code>.</li>
<li><code>GREYLISTING_BLOCK_EXPIRE</code>: Time (in MINUTES) to wait before client retrying,
client will be rejected if retires too soon (in less than specified minutes).
Defaults to <code>15</code> minutes.</li>
<li><code>GREYLISTING_AUTH_TRIPLET_EXPIRE</code>: Disable greylisting for how long (in DAYS)
for clients which passed greylisting (retried and delivered). It's also used
to clean up old greylisting tracking records. Defaults to <code>30</code> days.</li>
<li><code>GREYLISTING_UNAUTH_TRIPLET_EXPIRE</code>: Time (in DAYS) to keep tracking records
if client didn't pass the greylisting, and no further deliver attempts.
Defaults to <code>2</code> days.</li>
</ul>
<h4 id="manage-greylisting-settings">Manage greylisting settings</h4>
<blockquote>
<ul>
<li>Script <code>tools/greylisting_admin.py</code> is available in iRedAPD-1.8.0 and
later releases.</li>
</ul>
</blockquote>
<p>Greylisting is controlled by plugin <code>greylisting</code> (file
<code>/opt/iredapd/plugins/greylisting.py</code>), you can manage it with script
<code>/opt/iredapd/tools/greylisting_admin.py</code>.</p>
<h5 id="available-arguments_1">Available arguments</h5>
<pre><code> --list-whitelist-domains
Show ALL whitelisted sender domain names (in `greylisting_whitelist_domains`)
--list-whitelists
Show ALL whitelisted sender addresses (in `greylisting_whitelists`)
--whitelist-domain
Whitelist the IP addresses/networks in SPF record of specified sender
domain for greylisting service. Whitelisted domain is stored in sql
table `greylisting_whitelist_domains`.
--remove-whitelist-domain
Remove whitelisted sender domain
--list
Show ALL existing greylisting settings.
--from &lt;from_address&gt;
--to &lt;to_address&gt;
Manage greylisting setting from email which is sent from &lt;from_address&gt;
to &lt;to_address&gt;.
Valid formats for both &lt;from_address&gt; and &lt;to_address&gt;:
- a single user: username@domain.com
- a single domain: @domain.com
- entire domain and all its sub-domains: @.domain.com
- anyone: @. (the ending dot is required)
if no '--from' or '--to' argument, defaults to '@.' (anyone).
--enable
Explicitly enable greylisting for specified account.
--disable
Explicitly disable greylisting for specified account.
--delete
Delete specified greylisting setting.
</code></pre>
<h5 id="sample-usages_1">Sample usages</h5>
<ul>
<li>List all existing greylisting settings:</li>
</ul>
<pre><code>python3 greylisting_admin.py --list
</code></pre>
<ul>
<li>List all whitelisted sender domain names (in SQL table <code>greylisting_whitelist_domains</code>):</li>
</ul>
<pre><code>python3 greylisting_admin.py --list-whitelist-domains
</code></pre>
<ul>
<li>List all whitelisted sender addresses (in SQL table <code>greylisting_whitelists</code>):</li>
</ul>
<pre><code>python3 greylisting_admin.py --list-whitelists
</code></pre>
<ul>
<li>Whitelist IP networks/addresses specified in sender domain:</li>
</ul>
<pre><code>python3 greylisting_admin.py --whitelist-domain --from '@example.com'
</code></pre>
<p>This is same as:</p>
<pre><code>python3 spf_to_whitelist_domains.py --submit example.com
</code></pre>
<ul>
<li>Remove a whitelisted sender domain:</li>
</ul>
<pre><code>python3 greylisting_admin.py --remove-whitelist-domain --from '@example.com'
</code></pre>
<ul>
<li>Enable greylisting for emails which are sent from anyone to local mail domain <code>example.com</code>:</li>
</ul>
<pre><code>python3 greylisting_admin.py --enable --to '@example.com'
</code></pre>
<ul>
<li>Disable greylisting for emails which are sent from anyone to local mail user <code>user@example.com</code>:</li>
</ul>
<pre><code>python3 greylisting_admin.py --disable --to 'user@example.com'
</code></pre>
<ul>
<li>Disable greylisting for emails which are sent from <code>gmail.com</code> to local mail user <code>user@example.com</code>:</li>
</ul>
<pre><code>python3 greylisting_admin.py --disable --from '@gmail.com' --to 'user@example.com'
</code></pre>
<ul>
<li>Disable greylisting for sender IP:</li>
</ul>
<pre><code>python3 greylisting_admin.py --disable --from '45.56.127.226'
</code></pre>
<ul>
<li>Delete greylisting setting for emails which are sent from anyone to local domain <code>test.com</code>:</li>
</ul>
<pre><code>python3 greylisting_admin.py --delete --to '@test.com'
</code></pre>
<h5 id="recommended-additional-greylisting-whitelist-support">RECOMMENDED: Additional greylisting whitelist support</h5>
<p>Since many companies setup their mail servers to re-deliver returned email
immediately from another server, this causes trouble with greylisting.</p>
<p>Possible solutions:</p>
<ol>
<li>Disable greylisting on your server completely.</li>
<li>[Recommended] Whitelist IP addresses/networks of their mail servers.</li>
</ol>
<p>For solution #2, you can whitelist those mail servers with script
<code>/opt/iredapd/tools/spf_to_greylist_whitelists.py</code>.</p>
<div class="admonition attention">
<p class="admonition-title">Attention</p>
<p>Script <code>tools/spf_to_greylist_whitelists.py</code> is available in iRedAPD-1.8.0 and later releases.</p>
</div>
<p>It queries SPF and MX records of specified mail domain names, then store all
converted IP addresses/networks defined in SPF/MX records in SQL table
<code>iredapd.greylisting_whitelists</code>.</p>
<p>To whitelist IP addresses/networks of some mail domain, for example,
<code>outlook.com</code>, <code>microsoft.com</code>, please run command like below:</p>
<pre><code>cd /opt/iredapd/tools/
python3 spf_to_greylist_whitelists.py outlook.com microsoft.com
</code></pre>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Above command stores server addresses/networks in SPF/MX records in SQL
table, but doesn't store whitelisted domain name in SQL, that means
iRedAPD won't re-query their DNS records regularly (via cron job) to get
the latest servers listed in SPF record. To store domain names and update
their server addresses/networks, please run above command with <code>--submit</code>
option.</p>
</div>
<p>If you want to whitelist more mail domains, just run the command with the
domain names like above sample.</p>
<p>Since iRedAPD-1.8.0, we have SQL table <code>iredapd.greylisting_whitelist_domains</code>
to store these mail domain names. if you run <code>spf_to_greylist_whitelists.py</code>
without any argument, it will fetch all mail domains stored in sql table
<code>greylisting_whitelist_domains</code> instead of fetching from command line arguments.</p>
<pre><code>python3 spf_to_greylist_whitelists.py
</code></pre>
<p>You should setup a cron job to run this script, so that it can keep the IP
addresses/networks up to date. iRedMail sets up the cron job to run every 10 or
30 minutes, like below:</p>
<pre><code>*/30 * * * * /usr/bin/python3 /opt/iredapd/tools/spf_to_greylist_whitelists.py &amp;&gt;/dev/null
</code></pre><div class="footer">
<p style="text-align: center; color: grey;">All documents are available in <a href="https://github.com/iredmail/docs/">GitHub 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://github.com/iredmail/docs/archive/master.zip">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></body></html>
Reference in New Issue View Git Blame Copy Permalink