nixos/modules/services/monitoring/parsedmarc.xml

   1 <chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="module-services-parsedmarc">
   2   <title>parsedmarc</title>
   3   <para>
   4     <link xlink:href="https://domainaware.github.io/parsedmarc/">parsedmarc</link>
   5     is a service which parses incoming
   6     <link xlink:href="https://dmarc.org/">DMARC</link> reports and
   7     stores or sends them to a downstream service for further analysis.
   8     In combination with Elasticsearch, Grafana and the included Grafana
   9     dashboard, it provides a handy overview of DMARC reports over time.
  10   </para>
  11   <section xml:id="module-services-parsedmarc-basic-usage">
  12     <title>Basic usage</title>
  13     <para>
  14       A very minimal setup which reads incoming reports from an external
  15       email address and saves them to a local Elasticsearch instance
  16       looks like this:
  17     </para>
  18     <programlisting language="bash">
  19 services.parsedmarc = {
  20   enable = true;
  21   settings.imap = {
  22     host = &quot;imap.example.com&quot;;
  23     user = &quot;alice@example.com&quot;;
  24     password = &quot;/path/to/imap_password_file&quot;;
  25     watch = true;
  26   };
  27   provision.geoIp = false; # Not recommended!
  28 };
  29 </programlisting>
  30     <para>
  31       Note that GeoIP provisioning is disabled in the example for
  32       simplicity, but should be turned on for fully functional reports.
  33     </para>
  34   </section>
  35   <section xml:id="local-mail">
  36     <title>Local mail</title>
  37     <para>
  38       Instead of watching an external inbox, a local inbox can be
  39       automatically provisioned. The recipient’s name is by default set
  40       to <literal>dmarc</literal>, but can be configured in
  41       <link xlink:href="options.html#opt-services.parsedmarc.provision.localMail.recipientName">services.parsedmarc.provision.localMail.recipientName</link>.
  42       You need to add an MX record pointing to the host. More
  43       concretely: for the example to work, an MX record needs to be set
  44       up for <literal>monitoring.example.com</literal> and the complete
  45       email address that should be configured in the domain’s dmarc
  46       policy is <literal>dmarc@monitoring.example.com</literal>.
  47     </para>
  48     <programlisting language="bash">
  49 services.parsedmarc = {
  50   enable = true;
  51   provision = {
  52     localMail = {
  53       enable = true;
  54       hostname = monitoring.example.com;
  55     };
  56     geoIp = false; # Not recommended!
  57   };
  58 };
  59 </programlisting>
  60   </section>
  61   <section xml:id="grafana-and-geoip">
  62     <title>Grafana and GeoIP</title>
  63     <para>
  64       The reports can be visualized and summarized with parsedmarc’s
  65       official Grafana dashboard. For all views to work, and for the
  66       data to be complete, GeoIP databases are also required. The
  67       following example shows a basic deployment where the provisioned
  68       Elasticsearch instance is automatically added as a Grafana
  69       datasource, and the dashboard is added to Grafana as well.
  70     </para>
  71     <programlisting language="bash">
  72 services.parsedmarc = {
  73   enable = true;
  74   provision = {
  75     localMail = {
  76       enable = true;
  77       hostname = url;
  78     };
  79     grafana = {
  80       datasource = true;
  81       dashboard = true;
  82     };
  83   };
  84 };
  85
  86 # Not required, but recommended for full functionality
  87 services.geoipupdate = {
  88   settings = {
  89     AccountID = 000000;
  90     LicenseKey = &quot;/path/to/license_key_file&quot;;
  91   };
  92 };
  93
  94 services.grafana = {
  95   enable = true;
  96   addr = &quot;0.0.0.0&quot;;
  97   domain = url;
  98   rootUrl = &quot;https://&quot; + url;
  99   protocol = &quot;socket&quot;;
 100   security = {
 101     adminUser = &quot;admin&quot;;
 102     adminPasswordFile = &quot;/path/to/admin_password_file&quot;;
 103     secretKeyFile = &quot;/path/to/secret_key_file&quot;;
 104   };
 105 };
 106
 107 services.nginx = {
 108   enable = true;
 109   recommendedTlsSettings = true;
 110   recommendedOptimisation = true;
 111   recommendedGzipSettings = true;
 112   recommendedProxySettings = true;
 113   upstreams.grafana.servers.&quot;unix:/${config.services.grafana.socket}&quot; = {};
 114   virtualHosts.${url} = {
 115     root = config.services.grafana.staticRootPath;
 116     enableACME = true;
 117     forceSSL = true;
 118     locations.&quot;/&quot;.tryFiles = &quot;$uri @grafana&quot;;
 119     locations.&quot;@grafana&quot;.proxyPass = &quot;http://grafana&quot;;
 120   };
 121 };
 122 users.users.nginx.extraGroups = [ &quot;grafana&quot; ];
 123 </programlisting>
 124   </section>
 125 </chapter>