amorfo77/parsedmarc
1
0
Fork 0
mirror of https://github.com/domainaware/parsedmarc.git synced 2026-05-05 19:45:25 +00:00
Code Issues Projects Releases Wiki Activity
Files
d533ffca9d1245312dd81cccbd1b964f74974943
parsedmarc/installation.html
T
Sean Whalen d533ffca9d Update docs
2026-05-04 18:55:19 -04:00

268 lines
18 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!DOCTYPE html>
<html class="writer-html5" lang="en" data-content_root="./">
<head>
<meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Installation &mdash; parsedmarc 9.11.1 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=b86133f3" />
<link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=e59714d7" />
<script src="_static/jquery.js?v=5d32c60e"></script>
<script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
<script src="_static/documentation_options.js?v=e9bbcecf"></script>
<script src="_static/doctools.js?v=9bcbadda"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="_static/js/theme.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Using parsedmarc" href="usage.html" />
<link rel="prev" title="parsedmarc documentation - Open source DMARC report analyzer and visualizer" href="index.html" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="index.html" class="icon icon-home">
parsedmarc
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<p class="caption" role="heading"><span class="caption-text">Contents</span></p>
<ul class="current">
<li class="toctree-l1 current"><a class="current reference internal" href="#">Installation</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#prerequisites">Prerequisites</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#testing-multiple-report-analyzers">Testing multiple report analyzers</a></li>
<li class="toctree-l3"><a class="reference internal" href="#using-a-web-proxy">Using a web proxy</a></li>
<li class="toctree-l3"><a class="reference internal" href="#using-microsoft-exchange">Using Microsoft Exchange</a></li>
<li class="toctree-l3"><a class="reference internal" href="#ip-to-country-database">IP-to-country database</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#installing-parsedmarc">Installing parsedmarc</a></li>
<li class="toctree-l2"><a class="reference internal" href="#optional-dependencies">Optional dependencies</a></li>
<li class="toctree-l2"><a class="reference internal" href="#using-maxmind-geolite2-optional">Using MaxMind GeoLite2 (optional)</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="usage.html">Using parsedmarc</a></li>
<li class="toctree-l1"><a class="reference internal" href="output.html">Sample outputs</a></li>
<li class="toctree-l1"><a class="reference internal" href="elasticsearch.html">Elasticsearch and Kibana</a></li>
<li class="toctree-l1"><a class="reference internal" href="opensearch.html">OpenSearch and Grafana</a></li>
<li class="toctree-l1"><a class="reference internal" href="kibana.html">Using the Kibana dashboards</a></li>
<li class="toctree-l1"><a class="reference internal" href="splunk.html">Splunk</a></li>
<li class="toctree-l1"><a class="reference internal" href="davmail.html">Accessing an inbox using OWA/EWS</a></li>
<li class="toctree-l1"><a class="reference internal" href="dmarc.html">Understanding DMARC</a></li>
<li class="toctree-l1"><a class="reference internal" href="contributing.html">Contributing to parsedmarc</a></li>
<li class="toctree-l1"><a class="reference internal" href="api.html">API reference</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="index.html">parsedmarc</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="index.html" class="icon icon-home" aria-label="Home"></a></li>
<li class="breadcrumb-item active">Installation</li>
<li class="wy-breadcrumbs-aside">
<a href="_sources/installation.md.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<section class="tex2jax_ignore mathjax_ignore" id="installation">
<h1>Installation<a class="headerlink" href="#installation" title="Link to this heading"></a></h1>
<section id="prerequisites">
<h2>Prerequisites<a class="headerlink" href="#prerequisites" title="Link to this heading"></a></h2>
<p><code class="docutils literal notranslate"><span class="pre">parsedmarc</span></code> works with Python 3 only.</p>
<section id="testing-multiple-report-analyzers">
<h3>Testing multiple report analyzers<a class="headerlink" href="#testing-multiple-report-analyzers" title="Link to this heading"></a></h3>
<p>If you would like to test parsedmarc and another report processing
solution at the same time, you can have up to two <code class="docutils literal notranslate"><span class="pre">mailto</span></code> URIs in each of the rua and ruf
tags in your DMARC record, separated by commas.</p>
</section>
<section id="using-a-web-proxy">
<h3>Using a web proxy<a class="headerlink" href="#using-a-web-proxy" title="Link to this heading"></a></h3>
<p>If your system is behind a web proxy, you need to configure your system
to use that proxy. To do this, edit <code class="docutils literal notranslate"><span class="pre">/etc/environment</span></code> and add your
proxy details there, for example:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="nv">http_proxy</span><span class="o">=</span>http://user:password@prox-server:3128
<span class="nv">https_proxy</span><span class="o">=</span>https://user:password@prox-server:3128
<span class="nv">ftp_proxy</span><span class="o">=</span>http://user:password@prox-server:3128
</pre></div>
</div>
<p>Or if no credentials are needed:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="nv">http_proxy</span><span class="o">=</span>http://prox-server:3128
<span class="nv">https_proxy</span><span class="o">=</span>https://prox-server:3128
<span class="nv">ftp_proxy</span><span class="o">=</span>http://prox-server:3128
</pre></div>
</div>
<p>This will set the proxy up for use system-wide, including for <code class="docutils literal notranslate"><span class="pre">parsedmarc</span></code>.</p>
</section>
<section id="using-microsoft-exchange">
<h3>Using Microsoft Exchange<a class="headerlink" href="#using-microsoft-exchange" title="Link to this heading"></a></h3>
<p>If your mail server is Microsoft Exchange, ensure that it is patched to at
least:</p>
<ul class="simple">
<li><p>Exchange Server 2010 Update Rollup 22 (<a class="reference external" href="https://support.microsoft.com/KB/4295699">KB4295699</a>)</p></li>
<li><p>Exchange Server 2013 Cumulative Update 21 (<a class="reference external" href="https://support.microsoft.com/KB/4099855">KB4099855</a>)</p></li>
<li><p>Exchange Server 2016 Cumulative Update 11 (<a class="reference external" href="https://support.microsoft.com/kb/4134118">KB4134118</a>)</p></li>
</ul>
</section>
<section id="ip-to-country-database">
<h3>IP-to-country database<a class="headerlink" href="#ip-to-country-database" title="Link to this heading"></a></h3>
<p><code class="docutils literal notranslate"><span class="pre">parsedmarc</span></code> ships with a copy of the <a class="reference external" href="https://ipinfo.io/lite">IPinfo Lite</a> database (under
the terms of the <a class="reference external" href="https://creativecommons.org/licenses/by-sa/4.0/deed.en">Creative Commons Attribution-ShareAlike 4.0
License</a>), which is automatically refreshed from GitHub at startup
(and on <code class="docutils literal notranslate"><span class="pre">SIGHUP</span></code> in watch mode) unless the <code class="docutils literal notranslate"><span class="pre">offline</span></code> flag is set. No
IP database setup is required for the default configuration.</p>
<p>If you would prefer to use MaxMind’s GeoLite2 Country database
instead, see <a class="reference internal" href="#using-maxmind-geolite2-optional">Using MaxMind GeoLite2</a>
below.</p>
</section>
</section>
<section id="installing-parsedmarc">
<h2>Installing parsedmarc<a class="headerlink" href="#installing-parsedmarc" title="Link to this heading"></a></h2>
<p>On Debian or Ubuntu systems, run:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>sudo<span class="w"> </span>apt-get<span class="w"> </span>install<span class="w"> </span>-y<span class="w"> </span>python3-pip<span class="w"> </span>python3-venv<span class="w"> </span>python3-dev<span class="w"> </span>libxml2-dev<span class="w"> </span>libxslt-dev
</pre></div>
</div>
<p>On CentOS, RHEL, oR Rocky Linux systems, run:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>sudo<span class="w"> </span>dnf<span class="w"> </span>install<span class="w"> </span>-y<span class="w"> </span>python3<span class="w"> </span>python3-pip<span class="w"> </span>python3-devel<span class="w"> </span>libxml2-devel<span class="w"> </span>libxslt-devel
</pre></div>
</div>
<p>Python 3 installers for Windows and macOS can be found at
<a class="reference external" href="https://www.python.org/downloads/">https://www.python.org/downloads/</a>.</p>
<p><code class="docutils literal notranslate"><span class="pre">parsedmarc</span></code> requires Python 3.10 or newer. If your distribution’s
default <code class="docutils literal notranslate"><span class="pre">python3</span></code> is older, install a newer interpreter (e.g.
<code class="docutils literal notranslate"><span class="pre">python3.12</span></code>) and substitute it for <code class="docutils literal notranslate"><span class="pre">python3</span></code> in the commands below.</p>
<p>Create a dedicated system user, with <code class="docutils literal notranslate"><span class="pre">/opt/parsedmarc</span></code> as its home
directory so the directory is created with the correct ownership in
the same step</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>sudo<span class="w"> </span>useradd<span class="w"> </span>--system<span class="w"> </span>--create-home<span class="w"> </span>--home-dir<span class="w"> </span>/opt/parsedmarc<span class="w"> </span><span class="se">\</span>
<span class="w"> </span>--shell<span class="w"> </span>/usr/sbin/nologin<span class="w"> </span>--skel<span class="w"> </span>/dev/null<span class="w"> </span>parsedmarc
</pre></div>
</div>
<p>Create a virtualenv and install <code class="docutils literal notranslate"><span class="pre">parsedmarc</span></code> into it as that user, so
any files created later are also owned by <code class="docutils literal notranslate"><span class="pre">parsedmarc</span></code></p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>sudo<span class="w"> </span>-u<span class="w"> </span>parsedmarc<span class="w"> </span>python3<span class="w"> </span>-m<span class="w"> </span>venv<span class="w"> </span>/opt/parsedmarc/venv
sudo<span class="w"> </span>-u<span class="w"> </span>parsedmarc<span class="w"> </span>/opt/parsedmarc/venv/bin/pip<span class="w"> </span>install<span class="w"> </span>--upgrade<span class="w"> </span>pip
sudo<span class="w"> </span>-u<span class="w"> </span>parsedmarc<span class="w"> </span>/opt/parsedmarc/venv/bin/pip<span class="w"> </span>install<span class="w"> </span>--upgrade<span class="w"> </span>parsedmarc
</pre></div>
</div>
<p>To upgrade <code class="docutils literal notranslate"><span class="pre">parsedmarc</span></code> later, re-run the last command above and then
restart the service.</p>
</section>
<section id="optional-dependencies">
<h2>Optional dependencies<a class="headerlink" href="#optional-dependencies" title="Link to this heading"></a></h2>
<p>If you would like to be able to parse emails saved from Microsoft
Outlook (i.e. OLE .msg files), install <code class="docutils literal notranslate"><span class="pre">msgconvert</span></code>:</p>
<p>On Debian or Ubuntu systems, run:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>sudo<span class="w"> </span>apt-get<span class="w"> </span>install<span class="w"> </span>libemail-outlook-message-perl
</pre></div>
</div>
<p>On CentOS, RHEL, or Rocky Linux, the <code class="docutils literal notranslate"><span class="pre">Email::Outlook::Message</span></code> Perl
module is not packaged in the base repositories or EPEL, so install
it from CPAN:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>sudo<span class="w"> </span>dnf<span class="w"> </span>install<span class="w"> </span>-y<span class="w"> </span>perl<span class="w"> </span>perl-CPAN<span class="w"> </span>make<span class="w"> </span>gcc
sudo<span class="w"> </span>cpan<span class="w"> </span>-i<span class="w"> </span>Email::Outlook::Message
</pre></div>
</div>
<p>This installs the <code class="docutils literal notranslate"><span class="pre">msgconvert</span></code> script to <code class="docutils literal notranslate"><span class="pre">/usr/local/bin/msgconvert</span></code>.</p>
</section>
<section id="using-maxmind-geolite2-optional">
<h2>Using MaxMind GeoLite2 (optional)<a class="headerlink" href="#using-maxmind-geolite2-optional" title="Link to this heading"></a></h2>
<p><code class="docutils literal notranslate"><span class="pre">parsedmarc</span></code> will pick up the <a class="reference external" href="https://dev.maxmind.com/geoip/geolite2-free-geolocation-data">MaxMind GeoLite2 Country database</a> if
it is installed at one of the standard system paths (e.g.
<code class="docutils literal notranslate"><span class="pre">/usr/share/GeoIP/GeoLite2-Country.mmdb</span></code>,
<code class="docutils literal notranslate"><span class="pre">/var/lib/GeoIP/GeoLite2-Country.mmdb</span></code>, or the equivalent location on
Windows). <strong>Use this only if you specifically prefer MaxMind data over
the bundled IPinfo Lite database — most users do not need it.</strong></p>
<p>Install <a class="reference external" href="https://github.com/maxmind/geoipupdate">geoipupdate</a> for your platform:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="c1"># Debian 10+ (requires the contrib component in apt sources)</span>
sudo<span class="w"> </span>apt-get<span class="w"> </span>install<span class="w"> </span>-y<span class="w"> </span>geoipupdate
<span class="c1"># Ubuntu</span>
sudo<span class="w"> </span>add-apt-repository<span class="w"> </span>ppa:maxmind/ppa
sudo<span class="w"> </span>apt<span class="w"> </span>update
sudo<span class="w"> </span>apt<span class="w"> </span>install<span class="w"> </span>-y<span class="w"> </span>geoipupdate
<span class="c1"># CentOS, RHEL, or Rocky Linux</span>
sudo<span class="w"> </span>dnf<span class="w"> </span>install<span class="w"> </span>-y<span class="w"> </span>geoipupdate
</pre></div>
</div>
<p>Builds for Linux, macOS, and Windows are also available on the
<a class="reference external" href="https://github.com/maxmind/geoipupdate/releases">geoipupdate releases page on GitHub</a>.</p>
<p>Since December 2019, MaxMind has required a free account to download
the GeoLite2 databases (<a class="reference external" href="https://blog.maxmind.com/2019/12/18/significant-changes-to-accessing-and-using-geolite2-databases/">to comply with various privacy regulations</a>).
<a class="reference external" href="https://www.maxmind.com/en/geolite2/signup">Register for a free GeoLite2 account</a>, sign in, then create a new key on the <a class="reference external" href="https://www.maxmind.com/en/accounts/current/license-key">License
Keys</a> page (you can use <code class="docutils literal notranslate"><span class="pre">parsedmarc</span></code> as the description). Download the
pre-filled config file and save it to <code class="docutils literal notranslate"><span class="pre">/etc/GeoIP.conf</span></code> on Linux/macOS
or <code class="docutils literal notranslate"><span class="pre">%SystemDrive%\ProgramData\MaxMind\GeoIPUpdate\GeoIP.conf</span></code> on
Windows.</p>
<p>Then run</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>sudo<span class="w"> </span>geoipupdate
</pre></div>
</div>
<p>to download the databases for the first time. The GeoLite2 databases
are updated weekly (every Tuesday); add a cron job or scheduled task
to re-run <code class="docutils literal notranslate"><span class="pre">geoipupdate</span></code> weekly. More detail at the <a class="reference external" href="https://dev.maxmind.com/geoip/updating-databases/">MaxMind
geoipupdate page</a>.</p>
</section>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="index.html" class="btn btn-neutral float-left" title="parsedmarc documentation - Open source DMARC report analyzer and visualizer" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="usage.html" class="btn btn-neutral float-right" title="Using parsedmarc" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>&#169; Copyright 2018 - 2025, Sean Whalen and contributors.</p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink