NAME

openarc.conf - Configuration file for openarc

LOCATION

/usr/local/etc/openarc.conf

DESCRIPTION

openarc(8) implements the ARC (Authenticated Received Chain) specification for verifying authentication and handling of messages as they are routed to their destinations. 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 accepted: "F", "f", "N", "n", "0".

See the openarc(8) man page for details about how and when the configuration file contents are reloaded.

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

PARAMETERS

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 integer limiting the count of restarts in the given interval and t[u] defines the time interval through which the rate is calculated; 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 default, meaning restart rate is not limited.
Background (Boolean): Causes openarc to fork and exits immediately, leaving the service running in the background. The default is "true".
Canonicalization (string): Selects the canonicalization method(s) to be used when signing messages. When verifying, the message's ARC-Message-Signature: header field specifies the canonicalization method. The recognized values are relaxed and simple as defined by the DKIM specification. The default is relaxed/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 directory of the process to the one specified here prior to beginning execution. chroot(2) requires superuser access. A warning will be generated if UserID is not also set.
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.
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 of hosts that identifies clients whose connections should be treated as "internal" by this filter. Messages received from such sources will not be verified and are instead trusted as-is; in particular, their Authentication-Results fields are trusted to be correct and authentic, meaning they will be assumed to contain the correct chain status when generating an outgoing seal. See the description of "PeerList" for a description of the supported format. If no set is provided, "127.0.0.1" is added to the list by default.
MilterDebug (integer): Sets the debug level to be requested from the milter library. The default is 0.
Mode (string): Selects the operating mode(s) for this filter. If the string contains the character "s", the filter will sign and seal messages passing through the filter. If the string contains the character "v", the filter will do signature and seal validation of arriving messages. The two can be combined. If neither is specified, the operating mode will be inferred on a per-connection basis based on the entries in the InternalHosts list; connections from internal hosts will be assigned to signing mode, and all others will be assigned to verify mode.
OversignHeaders (string): Specifies a comma-separated list of header field names 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 important fields between the signer and the verifier. Since the verifier would include that header field when performing verification if it had been added by an intermediary, the signed message 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 signatures.
PeerList (dataset): Identifies a set of "peers" that identifies clients whose connections 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 ("!") character 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 connection type. More precise entries are preferred over less precise 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.
SealHeaderChecks (string): Identifies a file containing header checks that should be done to determine whether to seal a message. Each entry in this file must be of the form "name:regexp". When this feature is set, messages will only be processed by the filter if any instance of the named header field exists and has a value matching the provided regular expression. If the value of an instance appears to be a JSON list, then the regular expression is applied to all strings in the list.
SignatureAlgorithm (string): Selects the signing algorithm to use when generating signatures. Use 'openarc -V' to see the list of supported algorithms. The default is rsa-sha256.
SignHeaders (string): Specifies the set of header fields that should be included when generating signatures. This is expected to be a comma-separated list of header field names, and matching is case-insensitive. If the list omits any header field that is mandated by the ARC specification, those fields are implicitly added. By default, those fields listed in the DKIM specification as "SHOULD" be signed (RFC6376, Section 5.4) will be signed by the filter.
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 enclosed in square brackets. This option is mandatory either in the configuration file or on the command line.
Syslog (Boolean): Log via calls to syslog(3) any interesting activity.
SyslogFacility (string): Log via calls to syslog(3) using the named facility. The facility names are the same as the ones allowed in syslog.conf(5). The default is "mail".
UserID (string): Attempts to become the specified userid before starting operations. 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.

NOTES

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).

NAME

LOCATION

DESCRIPTION

PARAMETERS

NOTES

FILES

VERSION

COPYRIGHT

SEE ALSO