From a4bf20e6c7bc7fecaf88d2f3d56bde4700c77dc3 Mon Sep 17 00:00:00 2001
From: Russ Allbery <rra@stanford.edu>
Date: Fri, 27 Aug 2010 13:58:48 -0700
Subject: 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.
---
 autogen                      | 24 ++++++---------
 contrib/wallet-unknown-hosts | 73 ++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 83 insertions(+), 14 deletions(-)

diff --git a/autogen b/autogen
index 4ed7e23..a34a0b4 100755
--- a/autogen
+++ b/autogen
@@ -9,17 +9,13 @@ rm -rf autom4te.cache
 
 # Generate manual pages.
 version=`grep '^wallet' NEWS | head -1 | cut -d' ' -f2`
-pod2man --release="$version" --center=wallet client/wallet.pod \
-    > client/wallet.1
-pod2man --release="$version" --center=wallet client/wallet-rekey.pod \
-    > client/wallet-rekey.1
-pod2man --release="$version" --center=wallet -s 8 contrib/wallet-summary \
-    > contrib/wallet-summary.8
-pod2man --release="$version" --center=wallet -s 8 server/keytab-backend \
-    > server/keytab-backend.8
-pod2man --release="$version" --center=wallet -s 8 server/wallet-admin \
-    > server/wallet-admin.8
-pod2man --release="$version" --center=wallet -s 8 server/wallet-backend \
-    > server/wallet-backend.8
-pod2man --release="$version" --center=wallet -s 8 server/wallet-report \
-    > server/wallet-report.8
+for doc in client/wallet client/wallet-rekey ; do
+    pod2man --release="$version" --center=wallet \
+        --name=`basename "$doc" | tr a-z A-Z` "$doc".pod > "$doc".1
+done
+for doc in contrib/wallet-summary contrib/wallet-unknown-hosts \
+           server/keytab-backend server/wallet-admin server/wallet-backend \
+           server/wallet-report ; do
+    pod2man --release="$version" --center=wallet --section=8 \
+        --name=`basename "$doc" | tr a-z A-Z` "$doc" > "$doc".8
+done
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
-- 
cgit v1.2.3