opendmarc/opendmarc.conf.{5.in,sample}: update documentation

[dilyanpalauzov]

diff --git a/RELEASE_NOTES b/RELEASE_NOTES
--- a/RELEASE_NOTES
+++ b/RELEASE_NOTES
@@ -31,7 +31,7 @@ release, and a summary of the changes in that release.
        Feature request #127: Log SPF results when rejecting.  Requested
                by Patrick Wagner; patch from Andreas Schulze, follow-up
                patch from Juri Haberland.
-       Feature request #138: Inculde policy and disposition information
+       Feature request #138: Include policy and disposition information
                in an Authentication-Results comment.  Based on a patch
                from Juri Haberland.
        Feature request #139: Include the client host name if known
diff --git a/announcement b/announcement
--- a/announcement
+++ b/announcement
@@ -21,7 +21,7 @@ release:
        Feature request #127: Log SPF results when rejecting.  Requested
                by Patrick Wagner; patch from Andreas Schulze, follow-up
                patch from Juri Haberland.
-       Feature request #138: Inculde policy and disposition information
+       Feature request #138: Include policy and disposition information
                in an Authentication-Results comment.  Based on a patch
                from Juri Haberland.
        Feature request #139: Include the client host name if known
        Feature request #139: Include the client host name if known
diff --git a/db/README.schema b/db/README.schema
--- a/db/README.schema
+++ b/db/README.schema
@@ -15,6 +15,10 @@ selectors    A table that maps selector names to unique integer IDs.
                foreign key (into the domains table) for the domain that owns the
                selector.

+arcautchresults        A table for logging ARC-Authentication-Results information
+
+arcseals       A table for logging ARC-Seal information
+
 reporters      A table mapping reporting hosts to unique integer IDs.
                Intended for use by multi-MX systems so it's possible to tell
                where an inbound message landed.
diff --git a/docs/README.specs.html b/docs/README.specs.html
--- a/docs/README.specs.html
+++ b/docs/README.specs.html
@@ -18,7 +18,7 @@
   <a href="https://tools.ietf.org/html/rfc7208">
        RFC7208: Sender Policy Framework (SPF) for Authorizing Use of Domains in Email, Version 1 [PROPOSED STANDARD]
   </a> <br>
-  
+
   <h2> Email Format </h2>
   <a href="http://tools.ietf.org/html/rfc5322">
        RFC5322: Internet Message Format [DRAFT STANDARD]
diff --git a/opendmarc/opendmarc.8.in b/opendmarc/opendmarc.8.in
--- a/opendmarc/opendmarc.8.in
+++ b/opendmarc/opendmarc.8.in
@@ -125,7 +125,7 @@ above).  May be specified more than once to request increasing amounts of
 output.
 .TP
 .I \-V
-Print the version number and supported canonicalization and signature
+Print the version number, whether SPF support is compiled in and libmilter version
 algorithms, and then exit without doing anything else.
 .SH SIGNALS
 Upon receiving SIGUSR1, if the filter was started with a configuration
@@ -159,8 +159,10 @@ RFC5321 \- Simple Mail Transfer Protocol
 .P
 RFC5322 \- Internet Messages
 .P
-RFC5451 \- Message Header Field for Indicating Message Authentication Status
-.P
 RFC6376 \- DomainKeys Identified Mail
 .P
 RFC6591 \- Authentication Failure Reporting Using the Abuse Reporting Format
+.P
+RFC7489 \- Domain-based Message Authentication, Reporting, and Conformance (DMARC)
+.P
+RFC7601 \- Message Header Field for Indicating Message Authentication Status
diff --git a/opendmarc/opendmarc.conf.5.in b/opendmarc/opendmarc.conf.5.in
--- a/opendmarc/opendmarc.conf.5.in
+++ b/opendmarc/opendmarc.conf.5.in
@@ -15,7 +15,8 @@ specification for message authentication, policy enforcement, and reporting.
 This file is its configuration file.

 Blank lines are ignored.  Lines containing a hash ("#") character are
-truncated at the hash character to allow for comments in the file.
+truncated at the hash character to allow for comments in the file.  Lines
+longer than 1024 characters are also truncated.

 Other content should be the name of a parameter, followed by white space,
 followed by the value of that parameter, each on a separate line.
@@ -190,11 +191,14 @@ report.  It is expected that this will not be used in its raw form, but
 rather periodically imported into a relational database from which the
 aggregate reports can be extracted using
 .B opendmarc-importstats(8).
+For each record, the file is opened, locked, the data is appended, and the file
+in unlocked: when the file is renamed by the user on the filesystem, opendmarc
+will create a new file.

 .TP
 .I IgnoreAuthenticatedClients (Boolean)
 If set, causes mail from authenticated clients (i.e., those that used
-SMTP AUTH) to be ignored by the filter.  The default is "false".
+SMTP AUTH) to be ignored by the filter.

 .TP
 .I IgnoreHosts (string)
@@ -211,8 +215,8 @@ no mail is ignored.

 .TP
 .I MilterDebug (integer)
-Sets the debug level to be requested from the milter library.  The
-default is 0.
+Sets the debug level to be requested from the milter library.  Six is the
+highest useful value.

 .TP
 .I PidFile (string)
@@ -241,7 +245,6 @@ If set, messages will be rejected if they fail the DMARC evaluation, or
 temp-failed if evaluation could not be completed.  By default, no message will
 be rejected or temp-failed regardless of the outcome of the DMARC evaluation of
 the message.  Instead, an Authentication-Results header field will be added.
-The default is "false".

 .TP
 .I ReportCommand (string)
@@ -249,7 +252,7 @@ Indicates the shell command to which failure reports should 
be passed for
 delivery when
 .I FailureReports
 is enabled.  Defaults to
-.I /usr/sbin/sendmail.
+.I /usr/sbin/sendmail -t -odq.

 .TP
 .I RequiredHeaders (Boolean)
@@ -294,14 +297,14 @@ version, and the job ID are included in the header field's contents.
 .I SPFIgnoreResults (Boolean)
 Causes the filter to ignore any SPF results in the header of the
 message.  This is useful if you want the filter to perfrom SPF checks
-itself, or because you don't trust the arriving header.  The default is "false".
+itself, or because you don't trust the arriving header.

 .TP
 .I SPFSelfValidate (Boolean)
 Causes the filter to perform a fallback SPF check itself when
 it can find no SPF results in the message header.  If SPFIgnoreResults
 is also set, it never looks for SPF results in headers and
-always performs the SPF check itself when this is set.  The default is "false".
+always performs the SPF check itself when this is set.

 .TP
 .I Syslog (Boolean)
@@ -322,9 +325,13 @@ The default is "mail".
 .I TrustedAuthservIDs (string)
 Provides a list of authserv-ids that are to be used to identify
 Authentication-Results header fields whose contents are to be assumed as valid
-input for the DMARC assessment.  To provide a list, separate values by commas.
-If the string "HOSTNAME" is provided, the name of the host running the filter
-(as returned by the
+input for the DMARC assessment.  If
+.I AuthservIDWithJobID
+is set and the authserv-ids of the inspected AR header is not found in
+.I TrustedAuthservIDs
+then the JobId is appended when matching.  To provide a list, separate values
+by commas.  If the string "HOSTNAME" is provided, the name of the host running
+the filter (as returned by the
 .I gethostname(3)
 function) will be used.  Matching against this list is case-insensitive.  The
 default is to use the value of
@@ -370,10 +377,12 @@ Copyright (c) 2012-2015, 2018, The Trusted Domain Project.  All rights reserved.
 .P
 RFC4408 \- Sender Policy Framework
 .P
-RFC5451 \- Message Header Field for Indicating Message Authentication Status
-.P
 RFC5965 \- An Extensible Format for Email Feedback Reports
 .P
 RFC6376 \- DomainKeys Identified Mail
 .P
 RFC6591 \- Authentication Failure Reporting Using the Abuse Reporting Format
+.P
+RFC7489 \- Domain-based Message Authentication, Reporting, and Conformance (DMARC)
+.P
+RFC7601 \- Message Header Field for Indicating Message Authentication Status
diff --git a/opendmarc/opendmarc.conf.sample b/opendmarc/opendmarc.conf.sample
index 1e483f9..cfa7413 100644
--- a/opendmarc/opendmarc.conf.sample
+++ b/opendmarc/opendmarc.conf.sample
@@ -286,12 +286,12 @@
 # RejectFailures false

 ##  ReportCommand string
-##     default "/usr/sbin/sendmail -t"
+##     default "/usr/sbin/sendmail -t -odq"
 ##
 ##  Indicates the shell command to which failure reports should be passed for
 ##  delivery when "FailureReports" is enabled.
 #
-# ReportCommand /usr/sbin/sendmail -t
+# ReportCommand /usr/sbin/sendmail -t -odq

 ##  RequiredHeaders { true | false }
 ##     default "false"
@@ -370,8 +370,10 @@
 ##     default HOSTNAME
 ##
 ##  Specifies one or more "authserv-id" values to trust as relaying true
-##  upstream DKIM and SPF results.  The default is to use the name of
-##  the MTA processing the message.  To specify a list, separate each entry
+##  upstream DKIM and SPF results.  If AuthservIDWithJobID is set and the
+##  authserv-ids of the inspected AR header is not found in TrustedAuthservIDs
+##  then the JobID is appended when matching.  The default is to use the name of
+##  the MTA processing the message.   To specify a list, separate each entry
 ##  with a comma.  The key word "HOSTNAME" will be replaced by the name of
 ##  the host running the filter as reported by the gethostname(3) function.
 #

[thegushi]

Hey there. It's been a while.

Your contribution efforts are appreciated. These are mostly fine patches, but is it at all possible we can get them as a github pull request? We're triaging some older bugs and the difference in workload between copying a bunch of text out of a colored git page vs just accepting a pull is non-trivial.

If not, we'll get to this eventually. It may just take a little longer.

[dilyanpalauzov]

I do not believe on any promises here.

https://github.com/trusteddomainproject/OpenDMARC/pull/119 fixes a bug, but is not considered yet and it does not matter how I provide the changes.

The changes I use are uploaded at https://mail.aegee.org/cgit/OpenDMARC/ . You can clone it and use any commit you like.

[dilyanpalauzov]

I meant https://github.com/trusteddomainproject/OpenDMARC/pull/93 not https://github.com/trusteddomainproject/OpenDMARC/pull/119.

[thegushi]

See my comments on #93 -- as for the documentation update, some of the updates here are good, others confuse me. For example, we like it when our manpages say what the default for a setting is, and while that makes manpages a bit longer, they compress.

I would need to cherry-pick this change a bit more to apply it all. Which I'm still happy to offer credit for. I'll take anything that makes the code more polished.

-Dan

[dilyanpalauzov]

The man page says:

Unless otherwise stated, Boolean values default to "false", integer values default to 0, and string and dataset values default to being undefined.

So either this text shall be removed, or the per flag text stating that the default is 0.

[thegushi]

I'm not against having it in both places. Someone went to the trouble of writing it that way, and it's not misleading. Some people will skip through the manpage only looking for the field they're looking for and miss the subtle bit at the beginning.

That said, many of your other suggested fixes are great and I'm going to wind up cherry picking them in.