dwww Home | Manual pages | Find package

opendkim.conf(5)              File Formats Manual              opendkim.conf(5)

NAME
       opendkim.conf - Configuration file for opendkim

LOCATION
       /etc/opendkim.conf

DESCRIPTION
       opendkim(8)  implements the DKIM specification for signing and verifying
       e-mail messages on a per-domain basis.  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.

       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.

       For  parameters  that  are Boolean in nature, only the first byte of the
       value is processed.  For positive values, the  following  are  accepted:
       "T",  "t",  "Y",  "y",  "1".  For negative values, the following are ac-
       cepted: "F", "f", "N", "n", "0".

       Many, but not all, of these parameters are  also  available  as  command
       line  options to opendkim(8).  However, new parameters are generally not
       added as command line options so the complete set of options  is  avail-
       able  here,  and  thus  use of the configuration file is encouraged.  In
       some future release, the set of available command line options is likely
       to get trimmed.

       See the opendkim(8) man page for details about how and when the configu-
       ration file contents are reloaded.

       Some of these parameters are listed as having a type of "dataset".   See
       the opendkim(8) man page for a description of such parameters.

       Unless otherwise stated, Boolean values default to "false", integer val-
       ues  default  to 0, and string and dataset values default to being unde-
       fined.

PARAMETERS
       AllowSHA1Only (Boolean)
              Permit verify mode when only SHA1 support is available.   RFC6376
              requires  that  verifiers implement both SHA1 and SHA256 support.
              Setting this feature changes the absence of SHA256  support  from
              an error to a warning.

       AlwaysAddARHeader (Boolean)
              Add  an  "Authentication-Results:"  header field even to unsigned
              messages from domains with no "signs all" policy.   The  reported
              DKIM result will be "none" in such cases.  Normally unsigned mail
              from  non-strict  domains does not cause the results header field
              to be added.

       AuthservID (string)
              Sets the "authserv-id" to use when generating the Authentication-
              Results: header field after verifying a message.  The default  is
              to use the name of the MTA processing the message.  If the string
              "HOSTNAME"  is  provided, the name of the host running the filter
              (as returned by the gethostname(3) function) will be used.

       AuthservIDWithJobID (Boolean)
              If "true", requests that the authserv-id portion of the added Au-
              thentication-Results: header fields contain the  job  ID  of  the
              message being evaluated.

       AutoRestart (Boolean)
              Automatically  re-start  on  failures.   Use with caution; if the
              filter fails instantly after it starts, this can  cause  a  tight
              fork(2) loop.

       AutoRestartCount (integer)
              Sets  the  maximum automatic restart count.  After this number of
              automatic restarts, the filter will give  up  and  terminate.   A
              value of 0 implies no limit; this is the default.

       AutoRestartRate (string)
              Sets  the  maximum  automatic restart rate.  If the filter begins
              restarting faster than the rate defined here, it will give up and
              terminate.  This is a string of the form n/t[u] where n is an in-
              teger limiting the count of restarts in the  given  interval  and
              t[u]  defines  the time interval through which the rate is calcu-
              lated; t is an integer and u defines the units  thus  represented
              ("s" or "S" for seconds, the default; "m" or "M" for minutes; "h"
              or  "H" for hours; "d" or "D" for days).  For example, a value of
              "10/1h" limits the restarts to 10 in one hour.  There is  no  de-
              fault, meaning restart rate is not limited.

       Background (Boolean)
              Causes  opendkim  to fork and exits immediately, leaving the ser-
              vice running in the background.  The default is "true".

       BaseDirectory (string)
              If set, instructs the filter to change to the specified directory
              using chdir(2) before doing anything else.  This means any  files
              referenced  elsewhere  in the configuration file can be specified
              relative to this directory.  It's also useful for arranging  that
              any crash dumps will be saved to a specific location.

       BodyLengthDB (dataset)
              Requests  that  opendkim  include a "l=" body length tag when the
              set contains any of the envelope recipient  addresses.   The  ad-
              dresses  presented  are  tested  against  the database in various
              forms as described under the SigningTable setting (below).   This
              feature  of  the protocol exists to improve the likelihood that a
              signature will survive transit through a mailing list server,  as
              they  commonly  append  footers to messages.  Note, however, that
              this creates a potential security issue since someone  could  add
              arbitrary  text  to  the  signed  message and the signature would
              still validate.  See the DKIM specification for details.

       BogusKey (string)
              Instructs the filter to treat a passing signature associated with
              a bogus (forged) key in a special way.  Possible values are  neu-
              tral  (return  a "neutral" result), none (take no special action)
              and fail (return a "fail" result; this is the default).

       CaptureUnknownErrors (Boolean)
              When set, and on systems where MTA quarantine is  available,  the
              filter  will  request  quarantine of a message that results in an
              internal error or resource exhaustion.

       Canonicalization (string)
              Selects the canonicalization method(s) to be  used  when  signing
              messages.   When  verifying, the message's DKIM-Signature: header
              field specifies the canonicalization method.  The recognized val-
              ues are relaxed and simple as defined by the DKIM  specification.
              The  default  is  simple.   The  value  may include two different
              canonicalizations separated by a slash ("/") character, in  which
              case  the  first  will be applied to the header and the second to
              the body.

       ChangeRootDirectory (string)
              Requests that the operating system change the effective root  di-
              rectory  of the process to the one specified here prior to begin-
              ning execution.  chroot(2) requires superuser access.  A  warning
              will be generated if UserID is not also set.

       ClockDrift (integer)
              Sets  the  tolerance  in  seconds  to be applied when determining
              whether a signature was either expired or generated  in  the  fu-
              ture.  The default is 300.

       Diagnostics (Boolean)
              Requests  the  inclusion of "z=" tags in signatures, which encode
              the original header field set for use by verifiers when  diagnos-
              ing verification failures.  Not recommended for normal operation.

       DiagnosticDirectory (string)
              Directory  into  which  to  write diagnostic reports when message
              verification fails on a message bearing a "z=" tag.  If  not  set
              (the default), these files are not generated.

       DisableCryptoInit (Boolean)
              If  set,  skips  initialization of the SSL library initialization
              steps, which are normally  required  in  multi-threaded  environ-
              ments.  This assumes some other library opendkim is using will do
              the required initialization and shutdown.

       DNSConnect (Boolean)
              Requests  that  the asynchronous resolver start using TCP immedi-
              ately rather than using UDP until TCP is actually  needed.   Does
              not work with all resolvers.

       DNSTimeout (integer)
              Sets the DNS timeout in seconds.  A value of 0 causes an infinite
              wait.   The  default  is 5.  Ignored if not using an asynchronous
              resolver package.  See also the NOTES section below.

       Domain (dataset)
              A set of domains whose mail should  be  signed  by  this  filter.
              Mail  from  other  domains  will  be  verified  rather than being
              signed.

              This parameter is not required if a SigningTable is  in  use;  in
              that  case, the list of signed domains is implied by the lines in
              that file.

              This parameter is ignored if a KeyTable is defined.

       DomainKeysCompat (boolean)
              If set, backward  compatibility  with  DomainKeys  (RFC4870)  key
              records is enabled.  When not set, such keys are considered to be
              syntactically invalid.

       DontSignMailTo (dataset)
              A  set of e-mail address, mail to which should never be signed by
              the filter.  Note that this is an "any" feature; if  any  one  of
              the  recipients of the message matches a member of this list, the
              message will not be signed.

       EnableCoredumps (boolean)
              On systems that have such support, make an  explicit  request  to
              the kernel to dump cores when the filter crashes for some reason.
              Some  modern  UNIX systems suppress core dumps during crashes for
              security reasons if the user ID has changed during  the  lifetime
              of the process.  Currently only supported on Linux.

       ExemptDomains (dataset)
              Specifies a set of domains, mail from which should be ignored en-
              tirely  by  the  filter.  This is similar to the PeerList setting
              except that it bases its decision on the sender of the message as
              identified from the header fields or other message data, not  the
              identity of the SMTP client sending the message.

       ExternalIgnoreList (dataset)
              Identifies  a  set of "external" hosts that may send mail through
              the server as one of the signing domains without  credentials  as
              such.   This  has  the  effect  of suppressing the "external host
              (hostname) tried to send mail as (domain)" log messages.  Entries
              in the data set should be of  the  same  form  as  those  of  the
              PeerList option below.  The set is empty by default.

       FinalPolicyScript (string)
              Gives  the  name of a Lua script that should be run after the en-
              tire message has been received.  This can be used to enact  local
              policy  decisions  such as message rejection, quarantine, rerout-
              ing, etc. based on signatures found on the message,  the  results
              of  attempts  to verify them, and other properties of the message
              or signatures.  See opendkim-lua(3) for details.

       FixCRLF (Boolean)
              Requests that the DKIM library convert bare CRs and LFs to  CRLFs
              during  body canonicalization, anticipating that an MTA somewhere
              before delivery will do that conversion anyway.  The  default  is
              to leave them as-is.

       IdentityHeader (string)
              This  specifies  the  header  field  where an identity is stored.
              (Experimental feature not enabled for this installation.)

       IdentityHeaderRemove (Boolean)
              Remove the IdentityHeader after signing.   (Experimental  feature
              not enabled for this installation.)

       IgnoreMalformedMail (boolean)
              Silently  passes malformed messages without alteration.  This in-
              cludes messages that fail the RequiredHeaders check, if  enabled.
              The  default is to pass those messages but add an Authentication-
              Results field indicating that they were malformed.

       Include (string)
              Names a file to be opened and read as an additional configuration
              file.  Nesting is allowed to a maximum of five levels.

       InternalHosts (dataset)
              Identifies a set internal  hosts  whose  mail  should  be  signed
              rather  than  verified.  Entries in this data set follow the same
              form as those of the PeerList option below.   If  not  specified,
              the  default  of  "127.0.0.1" is applied.  Naturally, providing a
              value here overrides the  default,  so  if  mail  from  127.0.0.1
              should  be signed, the list provided here should include that ad-
              dress explicitly.

       KeepAuthResults (boolean)
              Suppresses removal of Authentication-Results header  fields  con-
              taining DKIM results apparently added by this filter (usually the
              result of a misconfiguration or a forgery).

       KeepTemporaryFiles (boolean)
              Instructs  the  filter  to  create temporary files containing the
              header and body canonicalizations of messages that are signed  or
              verified.   The location of these files can be set using the Tem-
              poraryDirectory parameter.  Intended only for debugging verifica-
              tion problems.

       KeyFile (string)
              Gives the location of a PEM-formatted private key to be used  for
              signing all messages.  Ignored if a KeyTable is defined.

       KeyTable (dataset)
              Gives  the  location of a file mapping key names to signing keys.
              If present, overrides any KeyFile setting  in  the  configuration
              file.   The  data set named here maps each key name to three val-
              ues: (a) the name of the domain to use in  the  signature's  "d="
              value;  (b)  the  name  of the selector to use in the signature's
              "s=" value; and (c) either a private key or a path to a file con-
              taining a private key.  If the first value consists solely  of  a
              percent sign ("%") character, it will be replaced by the apparent
              domain  of  the sender when generating a signature.  If the third
              value starts with a slash ("/") character, or "./" or "../", then
              it is presumed to refer to a file  from  which  the  private  key
              should  be read, otherwise it is itself a PEM-encoded private key
              or a base64-encoded DER private key; a "%" in the third value  in
              this  case  will  be  replaced by the apparent domain name of the
              sender.  The SigningTable (see below) is used to  select  records
              from this table to be used to add signatures based on the message
              sender.

       LDAPAuthMechanism (string)
              Names  the  authentication mechanism to use when connecting to an
              LDAP server.  The default is the empty string,  meaning  "simple"
              authentication should be done.

       LDAPAuthName (string)
              Specifies  the  authenticating name to use when using SASL to au-
              thenticate to an LDAP server.  Requires SASL support be installed
              on the local system.  There is no default.

       LDAPAuthRealm (string)
              Specifies the authentication realm to use when using SASL to  au-
              thenticate to an LDAP server.  Requires SASL support be installed
              on the local system.  There is no default.

       LDAPAuthUser (string)
              Specifies  the  authenticating user to use when using SASL to au-
              thenticate to an LDAP server.  Requires SASL support be installed
              on the local system.  There is no default.

       LDAPBindPassword (string)
              Specifies the password to use when conducting an LDAP "bind"  op-
              eration.  There is no default.

       LDAPBindUser (string)
              Specifies the user ID to use when conducting an LDAP "bind" oper-
              ation.  There is no default.

       LDAPDisableCache (Boolean)
              Suppresses creation of a local cache in front of LDAP queries.

       LDAPKeepaliveIdle (integer)
              Sets  the  number of seconds a connection to an LDAP server needs
              to remain idle before TCP starts sending  keepalive  probes.   If
              not specified, the LDAP library default is used.

       LDAPKeepaliveInterval (integer)
              Sets  the  interval  in seconds between TCP keepalive probes.  If
              not specified, the LDAP library default is used.

       LDAPKeepaliveProbes (integer)
              Sets the maximum number of keepalive probes TCP should  send  be-
              fore  abandoning  the connection.  If not specified, the LDAP li-
              brary default is used.

       LDAPTimeout (integer)
              Sets the time in seconds after which an LDAP operation should  be
              abandoned.  The default is 5.

       LDAPUseTLS (Boolean)
              Indicates  whether  or not a TLS connection should be established
              when contacting an LDAP server.  The default is "False".

       LogResults (boolean)
              If logging is enabled (see Syslog below), requests that  the  re-
              sults  of  evaluation of all signatures that were at least partly
              intact (i.e., the "d=", "s=", and "b=" tags could be extracted).

       LogWhy (boolean)
              If logging is enabled (see Syslog below),  issues  very  detailed
              logging  about  the  logic behind the filter's decision to either
              sign a message or verify it.  The logic behind  the  decision  is
              non-trivial  and  can be confusing to administrators not familiar
              with its operation.  A description of how the  decision  is  made
              can  be  found  in  the OPERATIONS section of the opendkim(8) man
              page.  This causes a large increase in the  amount  of  log  data
              generated  for each message, so it should be limited to debugging
              use and not enabled for general operation.

       MacroList (dataset)
              Defines a set of MTA-provided macros that should  be  checked  to
              see  if  the  sender  has  been determined to be a local user and
              therefore whether or not the message  should  be  signed.   If  a
              value  is  specified  matching  a macro name in the data set, the
              value of the macro must match  a  value  specified  (matching  is
              case-sensitive), otherwise the macro must be defined but may con-
              tain  any value.  The set is empty by default, meaning macros are
              not considered when making the sign-verify decision.  The general
              format of the value is  value1[|value2[|...]];  if  one  or  more
              value  is defined then the macro must be set to one of the listed
              values, otherwise the macro must  be  set  but  can  contain  any
              value.

              In  order for the macro and its value to be available to the fil-
              ter for checking, the MTA must send it during  the  protocol  ex-
              change.   This is either accomplished via manual configuration of
              the MTA to send the desired macros or,  for  MTA/filter  combina-
              tions  that  support  the  feature,  the filter can request those
              macros that are of interest.  The latter is a feature  negotiated
              at the time the filter receives a connection from the MTA and its
              availability  depends  upon the version of milter used to compile
              the filter and the version of the MTA making the connection.

              This data set must be of type "file" or "csl".

       MaximumHeaders (integer)
              Defines the maximum number of bytes the header block of a message
              may consume before the filter will reject the message.  This mit-
              igates a denial-of-service attack in which a client  connects  to
              the  MTA  and begins feeding an unbounded number of header fields
              of arbitrary size; since the filter keeps a cache of  these,  the
              attacker could cause the filter to allocate an unspecified amount
              of memory.  The default is 65536; a value of 0 removes the limit.

       MaximumSignaturesToVerify (integer)
              Defines  the  maximum number of signatures on a message for which
              verification should be conducted.  The default is three.   Signa-
              tures  are  selected  from  the  top of the message downward.  If
              TrustSignaturesFrom is set, signatures from domains in that  data
              set  are  always  verified,  which may consume part or all of, or
              even exceed, this limit.

       MaximumSignedBytes (integer)
              Specifies the maximum number of  bytes  of  message  body  to  be
              signed.  Messages shorter than this limit will be signed in their
              entirety.  Setting this value implies use of BodyLengthDB for all
              addresses.

       MilterDebug (integer)
              Sets  the  debug  level  to be requested from the milter library.
              Currently, the highest meaningful value is 6.

       Minimum (string)
              Instructs the verification code to fail messages for which a par-
              tial signature was received.  There are three  possible  formats:
              min  indicating  at least min bytes of the message must be signed
              (or if the message is smaller than min then all  of  it  must  be
              signed); min% requiring that at least min percent of the received
              message  must  be  signed;  and min+ meaning there may be no more
              than min bytes of unsigned data appended to the message for it to
              be considered valid.

       MinimumKeyBits (integer)
              Establishes a minimum key size for acceptable signatures.  Signa-
              tures with smaller key sizes, even if they  otherwise  pass  DKIM
              validation,  will  me marked as invalid.  The default is 1024.  A
              value of 0 accepts all keys.

       Mode (string)
              Selects operating modes.  The string is a concatenation of  char-
              acters  that  indicate  which  mode(s)  of operation are desired.
              Valid modes are s (signer) and v (verifier).  The default  is  sv
              except  in test mode (see the opendkim(8) man page) in which case
              the default is v.  When signing mode is enabled, one of the  fol-
              lowing combinations must also be set: (a) Domain, KeyFile, Selec-
              tor, no KeyTable, no SigningTable; (b) KeyTable, SigningTable, no
              Domain, no KeyFile, no Selector; (c) KeyTable, SetupPolicyScript,
              no Domain, no KeyFile, no Selector.

       MTA (dataset)
              A  set  of MTA names (a la the sendmail(8) DaemonPortOptions Name
              parameter) whose mail should be signed by this filter.  There  is
              no  default,  meaning  MTA name is not considered when making the
              sign-verify decision.

       MTACommand (string)
              Specifies the path to an executable to be used for  sending  mail
              such   as   that   generated  by  SendReports.   The  default  is
              /usr/sbin/sendmail.  The executable should accept  typical  send-
              mail(8)  command  line  options "-t" (take addresses from message
              body) and "-f" (set envelope sender), accept the new  message  on
              its  standard input, and return a non-zero exit status on any er-
              ror.

       MultipleSignatures (Boolean)
              Allow addition of multiple signatures when a signing table is  in
              use.  See SigningTable for more information.

       MustBeSigned (dataset)
              Specifies  a  set of header fields that, if present, must be cov-
              ered by the DKIM signature when verifying a message.  If a header
              field in this set is present in the message and  is  not  signed,
              the  filter  will  treat even an otherwise valid signature as in-
              valid.  The default is an empty list.

       Nameservers (string)
              Provides a comma-separated list of IP addresses that  are  to  be
              used  when  doing DNS queries to retrieve DKIM keys, VBR records,
              etc.  These override any local defaults built in to the  resolver
              in  use,  which  may be defined in /etc/resolv.conf or hard-coded
              into the software.

       NoHeaderB (Boolean)
              If set, this feature suppresses the use  of  "header.b"  tags  in
              added  Authentication-Results  header  fields.   The  default  is
              "false", which means those tags will be applied.

       OmitHeaders (dataset)
              Specifies a set of header fields that should be omitted when gen-
              erating signatures.  If an entry in the  list  names  any  header
              field  that  is  mandated by the DKIM specification, the entry is
              ignored.  A set of header fields is listed in the DKIM specifica-
              tion (RFC6376, Section 5.4) as "SHOULD NOT" be  signed;  the  de-
              fault list for this parameter contains those fields (Return-Path,
              Received,  Comments,  Keywords,  Bcc,  Resent-Bcc and DKIM-Signa-
              ture).  To omit no headers, simply use the  string  "."  (or  any
              string that will match no header field names).  Specifying a list
              with this parameter replaces the default entirely, unless one en-
              try  is  "*"  in which case the list is interpreted as a delta to
              the default; for example, "*,+foobar" will use the entire default
              list plus the name "foobar", while "*,-Bcc" would use the  entire
              default list except for the "Bcc" entry.

       On-BadSignature (string)
              Selects  the  action  to be taken when a signature fails to vali-
              date.  Possible values (with abbreviated forms  in  parentheses):
              accept  (a)  accept the message; discard (d) discard the message;
              quarantine (q) quarantine the message; reject (r) reject the mes-
              sage; tempfail (t) temp-fail the message.  The default is accept.
              Note that the "t" (testing) flag in a DKIM key bypasses this  be-
              haviour;  a  bad  signature  that  references a testing flag will
              still be delivered, though the added Authentication-Results field
              will indicate both the failed result and the test  mode  so  that
              consumers of the message can take appropriate action.

       On-Default (string)
              Selects  the action to be taken when any verification or internal
              error of any kind is encountered.  This is processed  before  the
              other  "On-"  values  so it can be used as a blanket setting fol-
              lowed by specific overrides.

       On-DNSError (string)
              Selects the action to be taken when a transient DNS error is  en-
              countered.   Possible values are the same as those for On-BadSig-
              nature.  The default is tempfail.

       On-InternalError (string)
              Selects the action to be taken when an  internal  error  of  some
              kind  is  encountered.  Possible values are the same as those for
              On-BadSignature.  The default is tempfail.

       On-KeyNotFound (string)
              Selects the action to be taken when the key referenced by a  sig-
              nature  is  not present in the DNS.  Possible values are the same
              as those for On-BadSignature.  The default is accept.

       On-NoSignature (string)
              Selects the action to be taken when a message  arrives  unsigned.
              Possible  values  are the same as those for On-BadSignature.  The
              default is accept.

       On-Security (string)
              Selects the action to be taken when a message arrives  containing
              properties  that  may be a security concern.  Possible values are
              the same as those for On-BadSignature.  The default is tempfail.

       On-SignatureError (string)
              Selects the action to be taken when a message  cannot  be  signed
              because  of issues with the message or the key provided for sign-
              ing.  Possible values are the same as those for  On-BadSignature.
              The default is reject.

       OversignHeaders (dataset)
              Specifies  a  set of header fields that should be included in all
              signature header lists (the "h=" tag) once more than  the  number
              of  times  they were actually present in the signed message.  The
              set is empty by default.  The purpose of this, and especially  of
              listing an absent header field, is to prevent the addition of im-
              portant  fields  between  the signer and the verifier.  Since the
              verifier would include that header field when performing  verifi-
              cation  if  it had been added by an intermediary, the signed mes-
              sage and the verified message were different and the verification
              would fail.  Note that listing a field name here and not  listing
              it  in  the SignHeaders list is likely to generate invalid signa-
              tures.

       PeerList (dataset)
              Identifies a set of "peers" that identifies clients whose connec-
              tions should be accepted without processing by this filter.   The
              set  should  contain  on  each line a hostname, domain name (e.g.
              ".example.com"), IP address, an IPv6 address (including  an  IPv4
              mapped   address),   or   a  CIDR-style  IP  specification  (e.g.
              "192.168.1.0/24").  An entry beginning with a bang ("!")  charac-
              ter  means  "not", allowing exclusions of specific hosts that are
              otherwise members of larger sets.   Host  and  domain  names  are
              matched  first, then the IP or IPv6 address depending on the con-
              nection type.  More precise entries are preferred over less  pre-
              cise    ones,    i.e.     "192.168.1.1"    will    match   before
              "!192.168.1.0/24".  The text  form  of  IPv6  addresses  will  be
              forced  to  lowercase  when queried (RFC5952), so the contents of
              this data set should also use lowercase.  The IP address  portion
              of  an  entry  may optionally contain square brackets; both forms
              (with and without) will be checked.

       PidFile (string)
              Specifies the path to a file that should be  created  at  process
              start containing the process ID.

       POPDBFile (dataset)
              Requests  that  the  filter  consult  a set for IP addresses that
              should be allowed for signing. This feature was designed for POP-
              before-SMTP datastores.  (Not enabled for this installation.)

       Quarantine (Boolean)
              Requests that messages which fail verification be quarantined  by
              the  MTA.   (Requires a sufficiently recent version of the milter
              library.)

       QueryCache (Boolean)
              Instructs the DKIM library to maintain its  own  local  cache  of
              keys  and policies retrieved from DNS, rather than relying on the
              nameserver for caching service.  Useful if the  nameserver  being
              used by the filter is not local.

       RedirectFailuresTo (address)
              Messages  bearing signatures that failed to verify are redirected
              to the specified address.  The original envelope recipient set is
              recorded in the header before redirection occurs.  By default, no
              redirection is done.

       RemoveARAll (Boolean)
              Removes all Authentication-Results: header fields that also  sat-
              isfy  the  requirements  of RemoveARFrom below.  By default, only
              those containing a DKIM result are removed.

       RemoveARFrom (dataset)
              Defines a set of hostnames whose  Authentication-Results:  header
              fields  should be removed before the message is passed for deliv-
              ery.  By default only those  header  fields  matching  the  local
              host's  canonical name will be removed.  Matching is only done on
              full hostnames (e.g. "host.example.com") or on domain names (e.g.
              ".example.com").

       RemoveOldSignatures (Boolean)
              Removes all existing signatures when operating in signing mode.

       ReplaceHeaders (data set)
              Defines a set of header fields that should  be  affected  by  the
              text  replacement  rules defined by the ReplaceRules setting.  By
              default, all header fields are included.  (Note: Feature  is  ex-
              perimental.)

       ReplaceRules (string)
              Specifies a file containing a list of text replacement rules that
              are  applied to the message header fields to replace certain con-
              tent expected to be changed as the message passes  through  local
              MTAs.   This  can be used to accommodate expected changes such as
              those made to From: fields by MTA  "masquerade"  features.   Each
              entry  in  the  file consists of a POSIX regular expression, fol-
              lowed by a tab (ASCII 9), followed by the  text  that  should  be
              used  to replace the text matching the expression.  The '#' char-
              acter denotes the beginning of a comment and text from that point
              on in a single line is ignored.  Blank lines  are  also  skipped.
              (Note: Feature is experimental.)

       ReportAddress (string)
              Specifies  the string to use in the From: header field for outgo-
              ing reports (see SendReports below).  If not specified, the  exe-
              cuting  user and local hostname will be used to construct the ad-
              dress.

       ReportBccAddress (string)
              Specifies address(es) to include in a Bcc: header field on outgo-
              ing reports (see SendReports below). If  multiple  addresses  are
              required, they should be comma separated.

       RequestReports (boolean)
              When  signing,  includes a request for signature evaluation fail-
              ures in the signature.  (See RFC6651 for details.)

       RequiredHeaders (boolean)
              Checks all messages for  compliance  with  RFC5322  header  field
              count requirements.  Non-compliant messages are rejected.

       RequireSafeKeys (boolean)
              When reading a key file, a message will be logged if the key file
              has  the  read or write bit set other than for the owner or for a
              group that the executing process is in.  With this feature set to
              "true", the filter will further consider this an error and refuse
              to make use of the file's contents.  The default is "true".

       ResignAll (boolean)
              Where ResignMailTo triggers a re-signing action, this flag  indi-
              cates  whether  or  not all mail should be signed (if set) versus
              only verified mail being signed (if not set).  (Experimental fea-
              ture not enabled for this installation.)

       ResignMailTo (dataset)
              Checks each message recipient against the specified dataset for a
              matching record.  The full address is checked in each case,  then
              the  hostname,  then  each domain preceded by ".".  If there is a
              match, the value returned is presumed to be the name of a key  in
              the  KeyTable  (if  defined) to be used to re-sign the message in
              addition to  verifying  it.   If  there  is  a  match  without  a
              KeyTable,  the default key is applied.  (Experimental feature not
              enabled for this installation.)

       ResolverConfiguration (string)
              Provides the given string as configuration information to the un-
              derlying resolver.  For the standard UNIX resolver, this  is  un-
              used; for Unbound, the string contains a filename that is consid-
              ered to be a configuration file.  There is no default.

       ResolverTracing (Boolean)
              Requests resolver tracing features be enabled, if available.  The
              effect  of this depends on how debugging features of the resolver
              might be implemented.  Currently only effective with the OpenDKIM
              asynchronous resolver library.

       ScreenPolicyScript (string)
              Gives the name of a Lua script that should be run  after  all  of
              the  header fields have been processed for a message; in particu-
              lar, this is useful after all DKIM signatures have been  detected
              and  initial  evaluation has been done.  The script has access to
              all of the header fields and connection information and  can  di-
              rect  that  certain  signatures be ignored based on that informa-
              tion.  See opendkim-lua(3) for details.

       SelectCanonicalizationHeader (string)
              Defines a header field name  which,  if  present,  adjusts  which
              canonicalization  will be used to generate an outgoing signature.
              Overrides the Canonicalization setting if  the  header  field  is
              present.  The default is "X-Canonicalization".

       Selector (string)
              Defines  the  name  of  the selector to be used when signing mes-
              sages.  See the DKIM specification for details.  Used  only  when
              signing  with  a single key; see the SigningTable parameter below
              for more information.

              This parameter is ignored if a KeyTable is defined.

       SenderHeaders (dataset)
              Specifies an  ordered  list  of  header  fields  that  should  be
              searched  to determine the sender of a message.  The first header
              field found is the one whose value is used.  This is mainly  used
              when  signing  for deciding which signing request(s) to make.  By
              default, the "From" header field is the only  one  checked.   See
              the OmitHeaders setting for a description of possible values.

       SenderMacro (string)
              Use  the  milter macro string to determine the sender of the mes-
              sage.  (Note: Feature is experimental.)

       SendReports (Boolean)
              If true, when a signature verification fails  and  the  signature
              included  a  reporting request ("r=y") and the signing domain ad-
              vertises a reporting  address  (i.e.   ra=user)  in  a  reporting
              record  in  the  DNS, the filter will send a structured report to
              that address containing details needed to reproduce the  problem.
              See RFC6651 for a complete description of this mechanism.

       SetupPolicyScript (string)
              Gives the name of a Lua script that should be run once all header
              fields  for a message have arrived.  The script has access to all
              of the header fields and connection information and  can  request
              DKIM  verification  or  signing  based  on that information.  See
              opendkim-lua(3) for details.

       SignatureAlgorithm (string)
              Selects the signing algorithm to use when generating  signatures.
              Use  'opendkim  -V' to see the list of supported algorithms.  The
              default is rsa-sha256 if it is available, otherwise  it  will  be
              rsa-sha1.

       SignatureTTL (integer)
              Sets the time-to-live, in seconds, of signatures generated by the
              filter.  If not set, no expiration time is added to signatures.

       SignHeaders (dataset)
              Specifies  the  set of header fields that should be included when
              generating signatures.  If the list omits any header  field  that
              is  mandated  by the DKIM specification, those fields are implic-
              itly added.  By default, those fields listed in the DKIM specifi-
              cation as "SHOULD" be  signed  (RFC6376,  Section  5.4)  will  be
              signed  by  the filter.  See the OmitHeaders configuration option
              for more information about the format and interpretation of  this
              field.

       SigningTable (dataset)
              Defines a table used to select one or more signatures to apply to
              a  message  based on the address found in the From: header field.
              Keys in this table vary depending on the type of table used; val-
              ues in this data set should include one  field  that  contains  a
              name  found in the KeyTable (see above) that identifies which key
              should be used in generating the signature, and an optional  sec-
              ond  field naming the signer of the message that will be included
              in the "i=" tag in the generated signature.  Note that  the  "i="
              value  will not be included in the signature if it conflicts with
              the signing domain (the "d=" value).

              If the first field contains only a "%" character, it will be  re-
              placed by the domain found in the From: header field.  Similarly,
              within  the  optional second field, any "%" character will be re-
              placed by the domain found in the From: header field.

              If this table specifies a  regular  expression  file  ("refile"),
              then  the keys are wildcard patterns that are matched against the
              address found in the From: header field.  Entries are checked  in
              the order in which they appear in the file.

              For  all  other  database  types,  the  full user@host is checked
              first, then simply host, then user@.domain (with all superdomains
              checked in  sequence,  so  "foo.example.com"  would  first  check
              "user@foo.example.com",     then     "user@.example.com",    then
              "user@.com"), then .domain, then user@*, and finally *.

              In any case, only the first match is applied, unless MultipleSig-
              natures is enabled in which case all matches are applied.

       SMTPURI (string)
              Specifies a URI (e.g., "smtp://localhost") to which  mail  should
              be  sent via SMTP when notifications are generated.  (Not enabled
              for this installation.)

       Socket (string)
              Specifies the socket that should be established by the filter  to
              receive connections from sendmail(8) in order to provide service.
              socketspec  is  in  one of two forms: local:path, which creates a
              UNIX domain socket at the specified path, or inet:port[@host]  or
              inet6:port[@host]  which  creates  a  TCP socket on the specified
              port and in the specified protocol family.  If the  host  is  not
              given  as  either a hostname or an IP address, the socket will be
              listening on all interfaces.  A literal IP address  must  be  en-
              closed  in  square  brackets.  This option is mandatory either in
              the configuration file or on the command line.

       SoftStart (Boolean)
              If set, the inability to connect and authenticate to an  LDAP  or
              SQL  server will not prevent the filter from starting, and recon-
              nections will be  attempted  for  each  query.   The  default  is
              "False".

       SoftwareHeader (Boolean)
              Causes  opendkim  to add an "DKIM-Filter" header field indicating
              the presence of this filter in the path of the message  from  in-
              jection to delivery.  The product's name, version, and the job ID
              are  included  in  the  header  field's  contents.  Note that the
              header field is not added if the Mode setting causes the  message
              to be ignored (e.g., if only signing mode is enabled and the con-
              figuration  causes  the  message not to be signed, or only verify
              mode is enabled and configuration would otherwise have caused the
              message to be signed, then it will not  have  this  header  field
              added).

       Statistics (filename)
              This  specifies a file in which to store DKIM transaction statis-
              tics.  See opendkim-stats(8) for a mechanism to parse the  file's
              contents, and opendkim-importstats() for a mechanism to translate
              the file's contents into SQL database insertions.  (Note: Feature
              is experimental.)

       StatisticsName (string)
              Defines  the  name to be used as the reporting host in statistics
              logs.  By default, the local host's  name  returned  by  gethost-
              name(3) is used.  (Note: Feature is experimental.)

       StatisticsPolicyScript (string)
              The  statistics  script is run after all of the DKIM verification
              and signing work has been completed but before any final  message
              handling is done.  The main purpose of this script is to give the
              user  an opportunity to examine the message or its signatures and
              make arbitrary additional statistical observations that should be
              recorded by the statistics module.

       StatisticsPrefix (string)
              When AnonymousStatistics is enabled, this string may be specified
              and will be prepended to all data before hashing  for  more  com-
              plete  anonymization.   This  means  two  records  from different
              sources referencing the same source will still produce  different
              hashes,  meaning such correlation is now only possible within the
              data from a single repoter.

       StrictHeaders (Boolean)
              If set, instructs the DKIM library to refuse processing of a mes-
              sage if the header field count does not conform to  RFC5322  Sec-
              tion 3.6.

       StrictTestMode (Boolean)
              Selects  strict CRLF mode during testing (see the -t command line
              flag in the opendkim(8) man page); messages for which all  header
              fields and body lines are not CRLF-terminated are considered mal-
              formed and will produce an error.

       SubDomains (Boolean)
              Sign  subdomains  of those listed by the Domain parameter as well
              as the actual domains.

       Syslog (Boolean)
              Log via calls to syslog(3) any interesting activity.

       SyslogFacility (string)
              Log via calls to syslog(3) using the named facility.  The  facil-
              ity  names  are  the  same as the ones allowed in syslog.conf(5).
              The default is "mail".

       SyslogName (string)
              Log via calls to syslog(3) using that name. That  way  one  could
              distinguish  multiple  instances.  The default is the name of the
              executable, normally "opendkim".

       SyslogSuccess (Boolean)
              Log via calls to syslog(3) additional entries indicating success-
              ful signing or verification of messages.

       TemporaryDirectory (string)
              Specifies the directory in which temporary canonicalization files
              should be written.  The default is to use the libopendkim default
              location, currently /tmp.

       TestDNSData (data set)
              Provides a data set whose keys will  be  treated  as  DNS  record
              names and values as TXT record contents.  Intended for use during
              automated testing.

       TestPublicKeys (string)
              Names a file from which public keys should be read.  Intended for
              use only during automated testing.

       TrustAnchorFile (string)
              Specifies a file from which trust anchor data should be read when
              doing DNS queries and applying the DNSSEC protocol.  This is cur-
              rently  ignored  unless the underlying library is compiled to use
              Unbound; see the documentation at at http://unbound.net  for  the
              expected format of this file.

       TrustSignaturesFrom (dataset)
              This  value  consists  of  a  set  of domains that are considered
              trustworthy in terms of third-party signatures.  That  is,  if  a
              message arrives with a signature from a domain that doesn't match
              the  domain  in the From: header, this setting determines whether
              or not that signature will be trusted.  If this  value  is  unde-
              fined, all signatures are trusted.

       UMask (integer)
              Requests  a  specific  permissions  mask to be used for file cre-
              ation.  This only really applies to creation of the  socket  when
              Socket  specifies  a  UNIX  domain socket, and to the PidFile (if
              any); temporary files are created by the mkstemp(3) function that
              enforces a specific file  mode  on  creation  regardless  of  the
              process umask.  See umask(2) for more information.

       UnprotectedKey (string)
              Instructs the filter to treat a passing signature associated with
              a  key  found  in  an insecure (i.e. not protected by DNSSEC) DNS
              record in a special way.  Possible values are neutral  (return  a
              "neutral"  result), none (take no special action; this is the de-
              fault) and fail (return a "fail" result).

       UserID (string)
              Attempts to become the specified userid  before  starting  opera-
              tions.   The  value  is  of the form userid[:group].  The process
              will be assigned all of the groups and primary group  ID  of  the
              named userid unless an alternate group is specified.

       VBR-Certifiers (string)
              The  default  certifiers  if  not  specified  in X-VBR-Certifiers
              header field.  (Note: Feature is experimental.)

       VBR-PurgeFields (string)
              If set, arranges to remove X-VBR-Certifiers and X-VBR-Type fields
              on messages prior to sending them.  (Note: Feature is  experimen-
              tal.)

       VBR-TrustedCertifiers (string)
              A  colon  or  comma sparated list of trusted certifiers to accept
              when verifying VBR-Info header field.  (Note: Feature is  experi-
              mental.)

       VBR-TrustedCertifiersOnly (Boolean)
              By  default,  the  certifiers that are in both the trusted certi-
              fiers list (above) and those in  the  message's  VBR-Info  header
              field  will  be  checked for vouching.  With this option set, the
              trusted certifiers will be checked and the ones  claimed  by  the
              message will be ignored.  (Note: Feature is experimental.)

       VBR-Type (string)
              This  default  VBR type if not specified in the X-VBR-Type header
              field.  (Note: Feature is experimental.)

       WeakSyntaxChecks (Boolean)
              Requests that the library continue processing  messages  even  if
              syntax  errors  are  discovered  early in message analysis.  This
              means, for example, that a signed message with  a  mangled  From:
              field will still proceed to verification even if the author's do-
              main could not be determined.

NOTES
       When  using  DNS timeouts (see the DNSTimeout option above), be sure not
       to use a timeout that is larger than the timeout being used for interac-
       tion between sendmail and the filter.  Otherwise, the MTA could abort  a
       message  while  waiting  for  a  reply from the filter, which in turn is
       still waiting for a DNS reply.

       Features that involve specification of IPv4  addresses  or  CIDR  blocks
       will  use  the  inet_addr(3)  function to parse that information.  Users
       should be familiar with the way that function  handles  the  non-trivial
       cases  (for  example,  "192.0.2/24"  and "192.0.2.0/24" are not the same
       thing).

FILES
       /etc/opendkim.conf
              Default location of this file.

VERSION
       This man page covers version 2.11.0 of opendkim.

COPYRIGHT
       Copyright (c) 2007, 2008, Sendmail, Inc. and its suppliers.  All  rights
       reserved.

       Copyright  (c)  2009-2015,  The  Trusted Domain Project.  All rights re-
       served.

SEE ALSO
       opendkim(8), opendkim-lua(3), sendmail(8)

       RFC5451 - Message Header Field  for  Indicating  Message  Authentication
       Status

       RFC5617 - DKIM Author Domain Signing Practises

       RFC5965 - An Extensible Format for Email Feedback Reports

       RFC6008  - Authentication-Results Registration for Differentiating among
       Cryptographic Results

       RFC6376 - DomainKeys Identified Mail

       RFC6651 - Extensions to DomainKeys Identified Mail  (DKIM)  for  Failure
       Reporting

                           The Trusted Domain Project          opendkim.conf(5)

Generated by dwww version 1.16 on Fri Nov 6 16:18:36 CET 2026.