Add documentation for wallet-unknown-hosts

Change how autogen generates man pages to use a loop, which will make
it easier to add more documentation in the future.

1 files changed, 73 insertions, 0 deletions

diff --git a/contrib/wallet-unknown-hosts b/contrib/wallet-unknown-hosts
index fec0956..29efb96 100755
--- a/contrib/wallet-unknown-hosts
+++ b/contrib/wallet-unknown-hosts
@@ -182,3 +182,76 @@ if ($command eq 'check') {
 } else {
     die "$0: unknown command $command\n";
 }
+
+##############################################################################
+# Documentation
+##############################################################################
+
+=head1 NAME
+
+wallet-unknown-hosts - Report host keytabs in wallet for unknown hosts
+
+=head1 SYNOPSIS
+
+B<wallet-unknown-hosts> check
+
+B<wallet-unknown-hosts> report I<min> I<date>
+
+env REMOTE_USER=I<principal> B<wallet-unknown-hosts> purge I<min> I<date>
+
+=head1 DESCRIPTION
+
+B<wallet-unknown-hosts> constructs a database recording host-based keytabs
+in wallet whose corresponding hosts are not found in DNS.  It records in
+that database the number of times the host wasn't found and the timestamp
+of the first time it was not found.  It can then generate a report of
+host-based keytab objects that have not been found for a minimum number of
+consecutive times and which were last found longer ago than a particular
+date.  Finally, it can purge from wallet all objects that meet those
+requirements.
+
+When run with the C<check> argument, B<wallet-unknown-hosts> traverses the
+wallet database looking for host-based keytabs, which it recognizes by
+looking for keytab objects for principals with at least one period (C<.>)
+after a slash (C</>).  It then applies a local check followed by a DNS
+check.  The DNS check is only successful (only considers the host to be
+found) if it resolves to an IP address (possibly through a CNAME).
+
+For any host that's not found, it records that host in its associated
+database.  If this is the first time it wasn't found, it records the first
+missing time as the current time and the missing count as 1.  If it
+previously wasn't found, it just increments the missing count.
+
+For any host that is found, it deletes any record for that keytab from the
+database.
+
+When run with the C<report> argument, B<wallet-unknown-hosts> takes two
+additional arguments: I<min> and I<date>.  I<min> is the minimum number of
+times that a host must be found missing for the corresponding keytabs to
+show up on the report.  I<date> is a cutoff date in seconds since epoch;
+keytabs will not be included in the report unless their first missing date
+is older than I<date>.  The output will be the name component of the
+keytab objects in the wallet that correspond to unknown hosts and meet
+those thresholds.
+
+When run with the C<purge> argument, B<wallet-unknown-hosts> will build a
+list of keytab objects the same as with the C<report> argument, using the
+same additioanl arguments, but rather than printing them out will instead
+delete them from the wallet database.  To run C<purge>, the environment
+variable REMOTE_USER must be set to a principal that's a member of the
+C<ADMIN> ACL.
+
+=head1 BUGS
+
+B<wallet-unknown-hosts> doesn't have any facility to purge from its
+database all objects that are no longer in the wallet.
+
+Having to specify an identity for purge mode is an artifact of the
+Wallet::Server API and needs to be fixed by providing some way to perform
+actions as a local administrator.
+
+=head1 AUTHOR
+
+Russ Allbery <rra@stanford.edu>
+
+=cut