.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "dkim-rotate" "1" "" "" ""
.hy
.SH NAME
.PP
\f[C]dkim-rotate\f[R] - rotate and revoke and invalidate DKIM keys
.SH SYNOPSIS
.PP
\f[C]dkim-rotate\f[R] [\f[I]options\f[R]] \f[C]--new\f[R]
[\f[I]instance\f[R] \&...]
.PD 0
.P
.PD
\f[C]dkim-rotate\f[R] [\f[I]options\f[R]] \f[C]--major\f[R]
[\f[I]instance\f[R]..]
.PD 0
.P
.PD
\f[C]dkim-rotate\f[R] [\f[I]options\f[R]] \f[C]--minor\f[R]
[\f[I]instance\f[R] \&...]
.PD 0
.P
.PD
\f[C]dkim-rotate\f[R] [\f[I]options\f[R]] \f[C]--status\f[R]
[\f[I]instance\f[R] \&...]
.PD 0
.P
.PD
\f[C]dkim-rotate\f[R] [\f[I]options\f[R]] \f[C]--reinstall\f[R]
[\f[I]instance\f[R] \&...]
.SH DESCRIPTION
.PP
\f[C]dkim-rotate\f[R] is a tool for managing DKIM (email antispam) keys
in a manner that avoids unnecessarily making emails nonrepudiable.
.PP
For each instance, \f[C]dkim-rotate\f[R] maintains several keys
concurrently, using \[lq]selectors\[rq] in a circular rotation.
.PP
See \f[B]dkim-rotate(7)\f[R] for the Principles of Operation, and
details of how to configure your MTA, DNS, and WWW server.
.PP
If no \f[I]instance\f[R] is provided, \f[C]dkim-rotate\f[R] will operate
on all instances matching \f[C][a-z][-_0-9a-z]*\f[R] for which the
configuration file
\f[C]/etc/dkim-rotate/\f[R]\f[I]instance\f[R]\f[C].zone\f[R] exists.
.PP
See \f[B]dkim-rotate(5)\f[R] for details about the instance
configuration file.
.PP
If an \f[I]instance\f[R] is provided and contains a slash, it will be
treated as a pathname; otherwise it will be taken as a reference to the
configuration file in \f[C]/etc\f[R].
.PP
\f[C]dkim-rotate\f[R] should normally be run out of cron.
It will produce progress information on stdout.
It will produce stderr output if and only if something is wrong.
.SH MODE OPTIONS
.TP
\f[B]\f[CB]--major\f[B]\f[R]
Make progress.
Create new keys, advance to using different keys, and reveal old keys,
as necessary.
.TP
\f[B]\f[CB]--minor\f[B]\f[R]
Make progress, but do not advance to using a new key.
If you wish your keys to be rotated at particular times of the day or
week, you should run with \f[C]--major\f[R] at those times, and
\f[C]--minor\f[R] otherwise.
.RS
.PP
For example, the suggested/default configuration runs with
\f[C]--major\f[R] at 0400 local time.
The effect is that emails sent on a particular day all cease to be
repudiable at the same time.
.RE
.TP
\f[B]\f[CB]--new\f[B]\f[R]
Make progress, and, additionally, allow the creation of a new instance.
Without \f[C]--new\f[R], it is an error if there is a config file, but
no recorded state.
.TP
\f[B]\f[CB]--reinstall\f[B]\f[R]
Do not make any progress, but force recreation, reinstallation and
reload of MTA and DNS output files.
.TP
\f[B]\f[CB]--status\f[B]\f[R]
Produce a status report of all the relevant keys.
Do not make any changes.
.SH OTHER OPTIONS
.TP
\f[B]\f[CB]--etc-dir\f[B]\f[R]=\f[I]etc-dir\f[R]
Look for instance configuration files in \f[I]etc-dir\f[R] rather than
\f[C]/etc/dkim-rotate\f[R].
.TP
\f[B]\f[CB]--var-dir\f[B]\f[R]=\f[I]var-dir\f[R]
Look for instance state directories in \f[I]var-dir\f[R] rather than
\f[C]/var/lib/dkim-rotate\f[R].
.SH AUTHOR
.PP
Copyright 2022 Ian Jackson and contributors to dkim-rotate.
.PD 0
.P
.PD
There is NO WARRANTY.
.PD 0
.P
.PD
\f[C]SPDX-License-Identifier: GPL-3.0-or-later\f[R]
.SH SEE ALSO
.TP
dkim-rotate(5)
Configuration file
.TP
dkim-rotate(7)
Principles of Operation
.TP
RFC6376
DKIM Signatures