1opendmarc.conf(5)             File Formats Manual            opendmarc.conf(5)
2
3
4

NAME

6       opendmarc.conf - Configuration file for opendmarc
7
8

LOCATION

10       /etc/opendmarc.conf
11
12

DESCRIPTION

14       opendmarc(8)  implements  the  proposed DMARC specification for message
15       authentication, policy enforcement, and reporting.  This  file  is  its
16       configuration file.
17
18       Blank  lines  are ignored.  Lines containing a hash ("#") character are
19       truncated at the hash character to allow for comments in the file.
20
21       Other content should be the name of  a  parameter,  followed  by  white
22       space,  followed  by  the  value  of that parameter, each on a separate
23       line.
24
25       For parameters that are Boolean in nature, only the first byte  of  the
26       value  is  processed.  For positive values, the following are accepted:
27       "T", "t", "Y", "y", "1".  For negative values, the  following  are  ac‐
28       cepted: "F", "f", "N", "n", "0".
29
30       Some,  but  not  all, of these parameters are also available as command
31       line options to opendmarc(8).  However, new  parameters  are  generally
32       not  added  as  command  line options so the complete set of options is
33       available here, and thus use of the configuration file  is  encouraged.
34       In  some  future  release, the set of available command line options is
35       likely to get trimmed.
36
37       See the opendmarc(8) man page for details about how and when  the  con‐
38       figuration file contents are reloaded.
39
40       Unless  otherwise  stated,  Boolean  values default to "false", integer
41       values default to 0, and string and dataset values default to being un‐
42       defined.
43
44

PARAMETERS

46       AuthservID (string)
47              Sets  the  "authserv-id"  to use when generating the Authentica‐
48              tion-Results: header field after verifying a message.   The  de‐
49              fault  is to use the name of the MTA processing the message.  If
50              the string "HOSTNAME" is provided, the name of the host  running
51              the  filter (as returned by the gethostname(3) function) will be
52              used.
53
54
55       AuthservIDWithJobID (Boolean)
56              If "true", requests that the authserv-id portion  of  the  added
57              Authentication-Results:  header fields contain the job ID of the
58              message being evaluated.
59
60
61       AutoRestart (Boolean)
62              Automatically re-start on failures.  Use with  caution;  if  the
63              filter  fails  instantly after it starts, this can cause a tight
64              fork(2) loop.
65
66
67       AutoRestartCount (integer)
68              Sets the maximum automatic restart count.  After this number  of
69              automatic  restarts,  the  filter will give up and terminate.  A
70              value of 0 implies no limit; this is the default.
71
72
73       AutoRestartRate (string)
74              Sets the maximum automatic restart rate.  If the  filter  begins
75              restarting  faster  than  the rate defined here, it will give up
76              and terminate.  This is a string of the form n/t[u] where  n  is
77              an  integer limiting the count of restarts in the given interval
78              and t[u] defines the time interval through  which  the  rate  is
79              calculated;  t is an integer and u defines the units thus repre‐
80              sented ("s" or "S" for seconds, the default; "m" or "M" for min‐
81              utes;  "h" or "H" for hours; "d" or "D" for days).  For example,
82              a value of "10/1h" limits the restarts to 10 in one hour.  There
83              is no default, meaning restart rate is not limited.
84
85
86       Background (Boolean)
87              Causes opendmarc to fork and exits immediately, leaving the ser‐
88              vice running in the background.  The default is "true".
89
90
91       BaseDirectory (string)
92              If set, instructs the filter to change to the  specified  direc‐
93              tory  using chdir(2) before doing anything else.  This means any
94              files referenced elsewhere in  the  configuration  file  can  be
95              specified  relative to this directory.  It's also useful for ar‐
96              ranging that any crash dumps will be saved to a  specific  loca‐
97              tion.
98
99
100       ChangeRootDirectory (string)
101              Requests that the operating system change the effective root di‐
102              rectory of the process to the one specified here prior to begin‐
103              ning execution.  chroot (2) requires superuser access. A warning
104              will be generated if UserID is not also set.
105
106
107       CopyFailuresTo (string)
108              Adds the specified recipient to the  message's  envelope  if  it
109              fails the DMARC evaluation.
110
111
112       DomainWhitelist (string)
113              A  brief  list  of  whitelisted  domains for which ARC signature
114              headers are trusted as determined by evaluating entries  in  the
115              "arc.chain"  field  found in a locally generated Authentication-
116              Results header.
117
118              This list will be concatenated with DomainWhitelistFile (if pro‐
119              vided).
120
121
122       DomainWhitelistFile (string)
123              A comprehensive list of whitelisted domains for which ARC signa‐
124              ture headers are trusted as determined by evaluating entries  in
125              the  "arc.chain"  field found in a locally generated Authentica‐
126              tion-Results header.
127
128              This list will be concatenated  with  DomainWhitelist  (if  pro‐
129              vided).
130
131
132       DomainWhitelistSize (integer)
133              Sets the capacity of the whitelisted domains data structure. The
134              value specifies the maximum number of entries including  domains
135              listed  in  the  DomainWhitelist configuration parameter and the
136              domains listed in the DomainWhiteListFile. The final  size  will
137              be  increased by approximately 20% to increase the efficiency of
138              the hashing algorithm.
139
140
141       DNSTimeout (integer)
142              Sets the DNS timeout in seconds.  A value of 0 causes  an  infi‐
143              nite wait.  The default is 5.  Ignored if not using an asynchro‐
144              nous resolver package.
145
146
147       EnableCoredumps (Boolean)
148              On systems that have such support, make an explicit  request  to
149              the  kernel  to dump cores when the filter crashes for some rea‐
150              son.  Some  modern  UNIX  systems  suppress  core  dumps  during
151              crashes  for  security reasons if the user ID has changed during
152              the lifetime of the process.  Currently only supported on Linux.
153
154
155       FailureReports (Boolean)
156              Enables generation of failure reports when the DMARC test  fails
157              and  the  purported sender of the message has requested such re‐
158              ports.  Reports are formatted per RFC6591.
159
160
161       FailureReportsBcc (string)
162              When failure reports are enabled and one is to be generated, al‐
163              ways  send  one to the address(es) specified here.  If a failure
164              report is requested by the domain  owner,  the  address(es)  are
165              added  in a Bcc: field.  If no request is made, they address(es)
166              are used in a To: field.  There is no default.
167
168
169       FailureReportsOnNone (Boolean)
170              Supplementary to the previous  setting,  enables  generation  of
171              failure  reports  for sending domains that publish a "none" pol‐
172              icy.
173
174
175       FailureReportsSentBy (string)
176              Sets the value of the From: field to be used when sending  fail‐
177              ure  reports  (see  above).  The default is to use the userid of
178              the user executing the filter and the local host  name  to  con‐
179              struct an email address.
180
181
182       HistoryFile (string)
183              If  set,  specifies the location of a text file to which records
184              are written that can be used to  generate  DMARC  aggregate  re‐
185              ports.  Records are batches of rows containing information about
186              a single received message, and include all relevant  information
187              needed  to  generate  a  DMARC aggregate report.  It is expected
188              that this will not be used in its raw form, but rather  periodi‐
189              cally  imported into a relational database from which the aggre‐
190              gate reports can be extracted using opendmarc-importstats(8).
191
192
193       HoldQuarantinedMessages (Boolean)
194              If set, the milter will signal to the  mta  that  messages  with
195              p=quarantine, which fail dmarc authentication, should be held in
196              the MTA's "Hold" or "Quarantine" queue.  The name varies by MTA.
197              If  false,  messsages will be accepted and passed along with the
198              regular mail flow, and the quarantine will be left up  to  down‐
199              stream  MTA/MDA/MUA  filters, if any, to handle by re-evaluating
200              the headers, including the Authentication-Results  header  added
201              by this filter.  The default is "false".
202
203
204       HoldQuarantinedMessages (Boolean)
205              If  set,  the  milter  will signal to the mta that messages with
206              p=quarantine, which fail dmarc authentication, should be held in
207              the MTA's "Hold" or "Quarantine" queue.  The name varies by MTA.
208              If false, messsages will be accepted and passed along  with  the
209              regular  mail  flow, and the quarantine will be left up to down‐
210              stream MTA/MDA/MUA filters, if any, to handle  by  re-evaluating
211              the  headers,  including the Authentication-Results header added
212              by this filter.  The default is "false".
213
214
215       IgnoreAuthenticatedClients (Boolean)
216              If set, causes mail from authenticated clients (i.e., those that
217              used  SMTP  AUTH)  to  be ignored by the filter.  The default is
218              "false".
219
220
221       IgnoreHosts (string)
222              Specifies the path to a file that contains a list of  hostnames,
223              IP  addresses,  and/or  CIDR expressions identifying hosts whose
224              SMTP connections are to be ignored by the filter.  If not speci‐
225              fied, defaults to "127.0.0.1" only.
226
227
228       IgnoreMailFrom (string)
229              Gives  a list of domain names whose mail (based on the From: do‐
230              main) is to be ignored by the filter.  The list should be comma-
231              separated.  Matching against this list is case-insensitive.  The
232              default is an empty list, meaning no mail is ignored.
233
234
235       MilterDebug (integer)
236              Sets the debug level to be requested from  the  milter  library.
237              The default is 0.
238
239
240       PidFile (string)
241              Specifies  the  path to a file that should be created at process
242              start containing the process ID.
243
244
245       PublicSuffixList (string)
246              Specifies the path to a file  that  contains  top-level  domains
247              (TLDs)  that  will  be used to compute the Organizational Domain
248              for a given domain name, as described in  the  DMARC  specifica‐
249              tion.  If not provided, the filter will not be able to determine
250              the Organizational Domain and only the presented domain will  be
251              evaluated.  This file should be periodically updated.  One loca‐
252              tion to retrieve the file from is https://publicsuffix.org/list/
253
254
255       RecordAllMessages (Boolean)
256              If set and HistoryFile is in  use,  all  received  messages  are
257              recorded  to  the  history file.  If not set (the default), only
258              messages for which the From: domain  published  a  DMARC  record
259              will be recorded in the history file.
260
261
262       RejectFailures (Boolean)
263              If set, messages will be rejected if they fail the DMARC evalua‐
264              tion, or temp-failed if evaluation could not be  completed.   By
265              default,  no  message will be rejected or temp-failed regardless
266              of the outcome of the DMARC evaluation of the message.  Instead,
267              an  Authentication-Results  header field will be added.  The de‐
268              fault is "false".
269
270
271       RejectMultiValueFrom (Boolean)
272              If set, messages with multiple addresses in the From:  field  of
273              the  message  will  be  rejected unless all domain names in that
274              field are the same.  They will otherwise be ignored by the  fil‐
275              ter (the default).
276
277
278       ReportCommand (string)
279              Indicates  the  shell command to which failure reports should be
280              passed for delivery when FailureReports is enabled.  Defaults to
281              /usr/sbin/sendmail.
282
283
284       RequiredHeaders (Boolean)
285              If  set,  the  filter will ensure the header of the message con‐
286              forms to the basic header field count restrictions laid  out  in
287              RFC5322,  Section  3.6.  Messages failing this test are rejected
288              without further processing.  A From: field from which no  domain
289              name could be extracted will also be rejected.
290
291
292       Socket (string)
293              Specifies the socket that should be established by the filter to
294              receive connections from sendmail(8) in order  to  provide  ser‐
295              vice.  socketspec is in one of two forms: local:path, which cre‐
296              ates  a  UNIX  domain  socket  at   the   specified   path,   or
297              inet:port[@host] or inet6:port[@host] which creates a TCP socket
298              on the specified port for the appropriate protocol  family.   If
299              the host is not given as either a hostname or an IP address, the
300              socket will be listening on  all  interfaces.   This  option  is
301              mandatory  either  in  the  configuration file or on the command
302              line.  If an IP address is used, it must be enclosed  in  square
303              brackets.
304
305
306       SoftwareHeader (Boolean)
307              Causes opendmarc to add a "DMARC-Filter" header field indicating
308              the presence of this filter in the path of the message from  in‐
309              jection  to  delivery.  The product's name, version, and the job
310              ID are included in the header field's contents.
311
312
313       SPFIgnoreResults (Boolean)
314              Causes the filter to ignore any SPF results in the header of the
315              message.   This  is useful if you want the filter to perform SPF
316              checks itself, or because you don't trust the  arriving  header.
317              The default is "false".
318
319
320       SPFSelfValidate (Boolean)
321              Causes the filter to perform a fallback SPF check itself when it
322              can find no SPF results in the message header.  If  SPFIgnoreRe‐
323              sults is also set, it never looks for SPF results in headers and
324              always performs the SPF check itself when this is set.  The  de‐
325              fault is "false".
326
327
328       Syslog (Boolean)
329              Log via calls to syslog(3) any interesting activity.
330
331
332       SyslogFacility (string)
333              Log via calls to syslog(3) using the named facility.  The facil‐
334              ity names are the same as the ones  allowed  in  syslog.conf(5).
335              The default is "mail".
336
337
338       TrustedAuthservIDs (string)
339              Provides  a list of authserv-ids that are to be used to identify
340              Authentication-Results header fields whose contents  are  to  be
341              assumed  as  valid input for the DMARC assessment.  To provide a
342              list, separate values by commas.  If the  string  "HOSTNAME"  is
343              provided,  the  name of the host running the filter (as returned
344              by the gethostname(3) function) will be used.  Matching  against
345              this  list is case-insensitive.  The default is to use the value
346              of AuthservID.
347
348
349       UMask (integer)
350              Requests a specific permissions mask to be used  for  file  cre‐
351              ation.   This only really applies to creation of the socket when
352              Socket specifies a UNIX domain socket, and to  the  PidFile  (if
353              any);  temporary  files  are  created by the mkstemp(3) function
354              that enforces a specific file mode on creation regardless of the
355              process umask.  See umask(2) for more information.
356
357
358       UserID (string)
359              Attempts  to  become the specified userid before starting opera‐
360              tions.  The value is of the form  userid[:group].   The  process
361              will  be  assigned all of the groups and primary group ID of the
362              named userid unless an alternate group is specified.
363

FILES

365       /etc/opendmarc.conf
366              Default location of this file.
367

VERSION

369       This man page covers version 1.4.2 of opendmarc.
370
371
373       Copyright (c) 2012-2015, 2018, 2021, The Trusted Domain  Project.   All
374       rights reserved.
375

SEE ALSO

377       opendmarc(8), opendmarc-importstats(8), sendmail(8)
378
379       RFC4408 - Sender Policy Framework
380
381       RFC5451  -  Message  Header Field for Indicating Message Authentication
382       Status
383
384       RFC5965 - An Extensible Format for Email Feedback Reports
385
386       RFC6376 - DomainKeys Identified Mail
387
388       RFC6591 - Authentication Failure Reporting Using  the  Abuse  Reporting
389       Format
390
391
392
393                          The Trusted Domain Project         opendmarc.conf(5)
Impressum