.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "TRUSTMAN 1"
.TH TRUSTMAN 1 2023-07-29 "perl v5.38.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
trustman \- Manage keys used as trust anchors
.SH SYNOPSIS
.IX Header "SYNOPSIS"
trustman [options]
.SH DESCRIPTION
.IX Header "DESCRIPTION"
\&\fBtrustman\fR manages keys used by DNSSEC as trust anchors in compliance with
RFC5011.  It may be used as a daemon for ongoing key verification or manually
for initialization and one-time key verification.
.PP
By default, \fBtrustman\fR runs as a daemon to ensure that keys stored locally in
configuration files still match the same keys fetched from the zone where they
are defined.  In addition, these checks can be run once manually (\fB\-S\fR) and
in the foreground (\fB\-f\fR).
.PP
For each key mismatch check, if key mismatches are detected then \fBtrustman\fR
performs the following operations:
.PP
.Vb 3
\&    \- sets an add hold\-down timer for new keys;
\&    \- sets a remove hold\-down timer for missing keys;
\&    \- removes revoked keys from the configuration file.
.Ve
.PP
On subsequent runs, the timers are checked.  If the timers have expired, keys
are added to or removed from the configuration file, as appropriate.
.PP
\&\fBnamed.conf\fR and \fBdnsval.conf\fR are the usual configuration files.  These
files must be specified in the DNSSEC-Tools configuration file or in command
line options.
.SH OPTIONS
.IX Header "OPTIONS"
\&\fBtrustman\fR takes a number of options, each of which is described in this
section.  Each option name may be shortened to the minimum number of unique
characters, but some options also have an alias (as noted.)  The single-letter
form of each option is denoted in parentheses, e.g.: \fB\-anchor_data_file\fR
(\fB\-a\fR).
.IP "\fB\-anchor_data_file file (\-a)\fR" 4
.IX Item "-anchor_data_file file (-a)"
A persistent data file for storing new keys waiting to be added.
.IP "\fB\-config file (\-c) \fR" 4
.IX Item "-config file (-c) "
Create a configuration file for \fBtrustman\fR from the command line options
given.  The existing DNSSEC-Tools configuration file is copied to the
specified configuration file, and new configuration entries are appended
corresponding to the command line options.  \fBtrustman\fR\-specific entries
already in the existing configuration file will be replaced with new entries
from the command line.  This will allow fewer command line options to be
specified in the future.
.IP "\fB\-dnsval_conf_file /path/to/dnsval.conf (\-k)\fR" 4
.IX Item "-dnsval_conf_file /path/to/dnsval.conf (-k)"
A \fBdnsval.conf\fR file to read, and possibly be updated.
.IP "\fB\-dtconfig config_file (\-d)\fR" 4
.IX Item "-dtconfig config_file (-d)"
Name of an alternate DNSSEC-Tools configuration file to be processed.
If specified, this configuration file is used \fIin place\fR of the normal
DNSSEC-Tools configuration file, \fBnot\fR in addition to it.  Also, it will be
handled prior to \fIkeyrec\fR files, \fIrollrec\fR files, and command-line options.
.IP "\fB\-foreground (\-f)\fR" 4
.IX Item "-foreground (-f)"
Run in the foreground.  \fBtrustman\fR will still run in a loop.
To run once, use the \fB\-single_run\fR option instead.
.IP "\fB\-hold_time seconds (\-w)\fR" 4
.IX Item "-hold_time seconds (-w)"
The value of the hold-down timer.  This is the number of seconds from the time
that a new key is found.  Generally, the default and recommended value of 30
days should be used.
.IP "\fB\-mail_contact_addr email_address (\-m)\fR" 4
.IX Item "-mail_contact_addr email_address (-m)"
Mail address for the contact person to whom reports should be sent.
.IP "\fB\-monitor (\-M)\fR" 4
.IX Item "-monitor (-M)"
Indicates that \fBtrustman\fR was run from a monitoring system, and a summary
of events will be printed.  Specifying this option automatically turns on
the \fB\-single_run\fR option and turns off the \fB\-verbose\fR option.
.Sp
This was developed for use with the Nagios monitoring system, but it can
be adapted for other monitors.
.IP "\fB\-named_conf_file /path/to/named.conf (\-n)\fR" 4
.IX Item "-named_conf_file /path/to/named.conf (-n)"
A \fBnamed.conf\fR file to read, and possibly update.
.IP \fB\-nomail\fR 4
.IX Item "-nomail"
Prevents mail from being sent, even if an SMTP server was specified in the
configuration file.  This is useful for only sending notifications via
\&\fBstdout\fR (\fB\-p\fR) or \fBsyslog\fR (\fB\-L\fR).
.IP \fB\-norevoke\fR 4
.IX Item "-norevoke"
This option turns off checks for the REVOKE bit.
.IP "\fB\-no_error (\-N)\fR" 4
.IX Item "-no_error (-N)"
Send report even when there are no errors.
.IP "\fB\-print (\-p)\fR" 4
.IX Item "-print (-p)"
Log messages to \fBstdout\fR.
.IP "\fB\-resolv_conf_file conffile (\-r)\fR" 4
.IX Item "-resolv_conf_file conffile (-r)"
A \fBresolv.conf\fR file to read.  \fB/dev/null\fR can be specified to force
\&\fIlibval\fR to recursively answer the query rather than asking other name
servers.)
.IP "\fB\-root_hints_file /path/to/root.hints (\-o)\fR" 4
.IX Item "-root_hints_file /path/to/root.hints (-o)"
A \fBroot.hints\fR file to read.
.IP "\fB\-single_run (\-S)\fR" 4
.IX Item "-single_run (-S)"
Do not loop, but run only once.
.IP "\fB\-sleeptime seconds (\-t)\fR" 4
.IX Item "-sleeptime seconds (-t)"
The number of seconds to sleep between checks.  Default is 3600 (one hour.)
.IP "\fB\-smtp_server smtpservername (\-s)\fR" 4
.IX Item "-smtp_server smtpservername (-s)"
The SMTP server that \fBtrustman\fR should use to send reports by mail.
.IP "\fB\-syslog (\-L)\fR" 4
.IX Item "-syslog (-L)"
Log messages to \fBsyslog\fR.
.IP "\fB\-tmp_dir directory (\-T)\fR" 4
.IX Item "-tmp_dir directory (-T)"
Specifies where temporary files should be created.  This is used when
creating new versions of the \fBdnsval.conf\fR and \fBnamed.conf\fR files before
they are moved into place.
.Sp
Files created in this directory will be \fBrenamed\fR to their final location.
You should ensure that this directory, the final \fBdnsval.conf\fR location,
and the final \fBnamed.conf\fR location are on the same disk partition.
Most operating systems will only rename files within a partition and will 
give an error if told to rename a file from one partition to another.
.IP "\fB\-zone zone (\-z)\fR" 4
.IX Item "-zone zone (-z)"
The zone to check.  Specifying this option supersedes the default
configuration file.
.IP "\fB\-help (\-h)\fR" 4
.IX Item "-help (-h)"
Display a help message.
.IP "\fB\-verbose (\-v)\fR" 4
.IX Item "-verbose (-v)"
Gives verbose output.
.IP "\fB\-Version (\-V)\fR" 4
.IX Item "-Version (-V)"
Displays the version information for \fBtrustman\fR and the DNSSEC-Tools package.
.SH CONFIGURATION
.IX Header "CONFIGURATION"
In addition to the command line arguments, the \fBdnssec\-tools.conf\fR file can
be configured with the following values to remove the need to use some of
the command-line options.  The command-line options always override the
settings in the \fBdnssec\-tools.conf\fR file.
.IP "\fBtaanchorfile file\fR" 4
.IX Item "taanchorfile file"
This specifies the file where \fBtrustman\fR state information will be kept.
This is equivalent to the \fB\-anchor_data_file\fR flag.
.IP "\fBtacontact contact_email\fR" 4
.IX Item "tacontact contact_email"
This is equivalent to the \fB\-mail_contact_addr\fR flag for specifying to whom
email notices will be sent.
.IP "\fBtadnsvalconffile file\fR" 4
.IX Item "tadnsvalconffile file"
This specifies the \fBdnsval.conf\fR file to read and write.
This is equivalent to the \fB\-dnsval_conf_file\fR flag.
.IP "\fBtanamedconffile file\fR" 4
.IX Item "tanamedconffile file"
This specifies the \fBnamed.conf\fR file to read and write.
This is equivalent to the \fB\-named_conf_file\fR flag.
.IP "\fBtaresolvconffile file\fR" 4
.IX Item "taresolvconffile file"
This specifies the \fBresolv.conf\fR file to use.
This is equivalent to the \fB\-resolv_conf_file\fR flag.
.IP "\fBtaroothintsfile file\fR" 4
.IX Item "taroothintsfile file"
This specifies the \fBroot.hints\fR file to read.
This is equivalent to the \fB\-root_hints_file\fR flag.
.IP "\fBtasmtpserver servername\fR" 4
.IX Item "tasmtpserver servername"
This is equivalent to the \fB\-smtp_server\fR flag for specifying the SMTP server
to which email notices will be sent.
.IP "\fBtatmpdir directory\fR" 4
.IX Item "tatmpdir directory"
This specifies where temporary files should be created.  This is used when
creating new versions of the \fBdnsval.conf\fR and \fBnamed.conf\fR files before
they're moved into place.
.Sp
See the note about renaming in the description of the \fB\-tmp_dir\fR option.
.SH "EXIT CODES"
.IX Header "EXIT CODES"
\&\fBtrustman\fR may exit for the following reasons:
.PP
.Vb 3
\&    0 \- Successful execution.  In daemon mode, this may just mean
\&        that the daemon was successfully started.  The daemon itself
\&        may exit with some other error.
\&
\&    1 \- Invalid options were specified.
\&
\&    2 \- No new\-key file was specified.
\&
\&    3 \- Unable to open the new\-key file.
\&
\&    4 \- Unable to determine a set of zones to check.
\&
\&    5 \- Some form of file\-management error was encountered.
.Ve
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright 2006\-2014 SPARTA, Inc.  All rights reserved.
See the COPYING file included with the DNSSEC-Tools package for details.
.SH Author
.IX Header "Author"
Lindy Foster
.PP
(Current contact for \fBtrustman\fR is Wayne Morrison, tewok@tislabs.com.)
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBNet::DNS::SEC::Tools::conf.pm\|(3)\fR,
\&\fBNet::DNS::SEC::Tools::defaults.pm\|(3)\fR,
.PP
\&\fBdnssec\-tools.conf\|(5)\fR