mirror of
https://github.com/domainaware/parsedmarc.git
synced 2026-02-17 07:03:58 +00:00
283 lines
18 KiB
HTML
283 lines
18 KiB
HTML
|
||
|
||
<!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 — parsedmarc 9.0.10 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=9edc463e" />
|
||
|
||
|
||
<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=164cc7e6"></script>
|
||
<script src="_static/doctools.js?v=fd6eb6e6"></script>
|
||
<script src="_static/sphinx_highlight.js?v=6ffebe34"></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="#geoipupdate-setup">geoipupdate setup</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>
|
||
</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="geoipupdate-setup">
|
||
<h3>geoipupdate setup<a class="headerlink" href="#geoipupdate-setup" title="Link to this heading"></a></h3>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>Starting in <code class="docutils literal notranslate"><span class="pre">parsedmarc</span></code> 7.1.0, a static copy of the
|
||
<a class="reference external" href="https://db-ip.com/db/download/ip-to-country-lite">IP to Country Lite database</a> from IPDB is distributed with
|
||
<code class="docutils literal notranslate"><span class="pre">parsedmarc</span></code>, under the terms of the
|
||
[Creative Commons Attribution 4.0 International License].
|
||
as a fallback if the <a class="reference external" href="https://dev.maxmind.com/geoip/geolite2-free-geolocation-data">MaxMind GeoLite2 Country database</a> is not
|
||
installed. However, <code class="docutils literal notranslate"><span class="pre">parsedmarc</span></code> cannot install updated versions of
|
||
these databases as they are released, so MaxMind’s databases and the
|
||
<a class="reference external" href="https://github.com/maxmind/geoipupdate">geoipupdate</a> tool is still the preferable solution.</p>
|
||
<p>The location of the database file can be overridden by using the
|
||
<code class="docutils literal notranslate"><span class="pre">ip_db_path</span></code> setting.</p>
|
||
</div>
|
||
<p>On Debian 10 (Buster) or later, 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>geoipupdate
|
||
</pre></div>
|
||
</div>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p><a class="reference external" href="https://wiki.debian.org/SourcesList#Component">Component “contrib”</a> is required in your apt sources.</p>
|
||
</div>
|
||
<p>On Ubuntu systems run:</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></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
|
||
</pre></div>
|
||
</div>
|
||
<p>On CentOS or RHEL 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>geoipupdate
|
||
</pre></div>
|
||
</div>
|
||
<p>The latest builds for Linux, macOS, and Windows can be downloaded
|
||
from the <a class="reference external" href="https://github.com/maxmind/geoipupdate/releases">geoipupdate releases page on GitHub</a>.</p>
|
||
<p>On December 30th, 2019, MaxMind started requiring free accounts to
|
||
access the free Geolite2 databases, in order
|
||
<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>.</p>
|
||
<p>Start by <a class="reference external" href="https://www.maxmind.com/en/geolite2/signup">registering for a free GeoLite2 account</a>, and signing in.</p>
|
||
<p>Then, navigate to the <a class="reference external" href="https://www.maxmind.com/en/accounts/current/license-key">License Keys</a> page under your account,
|
||
and create a new license key for the version of
|
||
<code class="docutils literal notranslate"><span class="pre">geoipupdate</span></code> that was installed.</p>
|
||
<div class="admonition warning">
|
||
<p class="admonition-title">Warning</p>
|
||
<p>The configuration file format is different for older (i.e. <=3.1.1) and newer (i.e. >=3.1.1) versions
|
||
of <code class="docutils literal notranslate"><span class="pre">geoipupdate</span></code>. Be sure to select the correct version for your system.</p>
|
||
</div>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>To check the version of <code class="docutils literal notranslate"><span class="pre">geoipupdate</span></code> that is installed, run:</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>geoipupdate<span class="w"> </span>-V
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
<p>You can use <code class="docutils literal notranslate"><span class="pre">parsedmarc</span></code> as the description for the key.</p>
|
||
<p>Once you have generated a key, download the config pre-filled
|
||
configuration file. This file should be saved at <code class="docutils literal notranslate"><span class="pre">/etc/GeoIP.conf</span></code>
|
||
on Linux or macOS systems, or at
|
||
<code class="docutils literal notranslate"><span class="pre">%SystemDrive%\ProgramData\MaxMind\GeoIPUpdate\GeoIP.conf</span></code> on
|
||
Windows systems.</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.</p>
|
||
<p>The GeoLite2 Country, City, and ASN databases are updated weekly,
|
||
every Tuesday. <code class="docutils literal notranslate"><span class="pre">geoipupdate</span></code> can be run weekly by adding a cron
|
||
job or scheduled task.</p>
|
||
<p>More information about <code class="docutils literal notranslate"><span class="pre">geoipupdate</span></code> can be found at the
|
||
<a class="reference external" href="https://dev.maxmind.com/geoip/updating-databases/">MaxMind geoipupdate page</a>.</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-virtualenv<span class="w"> </span>python3-dev<span class="w"> </span>libxml2-dev<span class="w"> </span>libxslt-dev
|
||
</pre></div>
|
||
</div>
|
||
<p>On CentOS or RHEL 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>python39<span class="w"> </span>python3-virtualenv<span class="w"> </span>python3-setuptools<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>Create a system user</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>sudo<span class="w"> </span>mkdir<span class="w"> </span>/opt
|
||
sudo<span class="w"> </span>useradd<span class="w"> </span>parsedmarc<span class="w"> </span>-r<span class="w"> </span>-s<span class="w"> </span>/bin/false<span class="w"> </span>-m<span class="w"> </span>-b<span class="w"> </span>/opt
|
||
</pre></div>
|
||
</div>
|
||
<p>Install parsedmarc in a virtualenv</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>virtualenv<span class="w"> </span>/opt/parsedmarc/venv
|
||
</pre></div>
|
||
</div>
|
||
<p>CentOS/RHEL 8 systems use Python 3.6 by default, so on those systems
|
||
explicitly tell <code class="docutils literal notranslate"><span class="pre">virtualenv</span></code> to use <code class="docutils literal notranslate"><span class="pre">python3.9</span></code> instead</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>virtualenv<span class="w"> </span>-p<span class="w"> </span>python3.9<span class="w"> </span>/opt/parsedmarc/venv
|
||
</pre></div>
|
||
</div>
|
||
<p>Activate the virtualenv</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="nb">source</span><span class="w"> </span>/opt/parsedmarc/venv/bin/activate
|
||
</pre></div>
|
||
</div>
|
||
<p>To install or upgrade <code class="docutils literal notranslate"><span class="pre">parsedmarc</span></code> inside the virtualenv, run:</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>/opt/parsedmarc/venv/bin/pip<span class="w"> </span>install<span class="w"> </span>-U<span class="w"> </span>parsedmarc
|
||
</pre></div>
|
||
</div>
|
||
</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>
|
||
</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>© 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> |