Add documentation for wallet-rekey

5 files changed, 173 insertions, 5 deletions

diff --git a/Makefile.am b/Makefile.am
index 10f47d9..0b5593f 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -74,7 +74,7 @@ client_wallet_rekey_LDFLAGS = $(REMCTL_LDFLAGS) $(KRB5_LDFLAGS)
 client_wallet_rekey_LDADD = client/libwallet.a util/libutil.a \
 	portable/libportable.a $(REMCTL_LIBS) $(KRB5_LIBS)
 
-dist_man_MANS = client/wallet.1 server/keytab-backend.8 \
+dist_man_MANS = client/wallet.1 client/wallet-rekey.1 server/keytab-backend.8 \
 	server/wallet-admin.8 server/wallet-backend.8 server/wallet-report.8
 
 # A set of flags for warnings.  Add -O because gcc won't find some warnings
diff --git a/autogen b/autogen
index f7c8055..4ed7e23 100755
--- a/autogen
+++ b/autogen
@@ -11,6 +11,8 @@ rm -rf autom4te.cache
 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 \
diff --git a/client/wallet-rekey.pod b/client/wallet-rekey.pod
new file mode 100644
index 0000000..efe9a0b
--- /dev/null
+++ b/client/wallet-rekey.pod
@@ -0,0 +1,165 @@
+=for stopwords
+wallet-rekey rekey rekeying keytab -hv Heimdal remctl remctld PKINIT kinit
+appdefaults Allbery
+
+=head1 NAME
+
+wallet-rekey - Client for rekeying a Kerberos keytab using wallet
+
+=head1 SYNOPSIS
+
+B<wallet-rekey> [B<-hv>] [B<-c> I<command>] [B<-k> I<principal>]
+    [B<-p> I<port>] [B<-s> I<server>] [B<-u> I<principal>] [I<keytab> ...]
+
+=head1 DESCRIPTION
+
+B<wallet-rekey> is a specialized client for the wallet system used to
+rekey a Kerberos keytab by downloading new keytab objects from wallet for
+each principal found in the keytab.  For each keytab file listed on the
+command line, it walks through the principals in that keytab, finds all
+from the local default realm, requests new wallet keytab objects for each
+principal (removing the realm when naming the keytab), and merges the new
+keys into the keytab.
+
+If an error occurs before any new keys were downloaded, B<wallet-rekey>
+aborts.  If some new keys were successfully downloaded, B<wallet-rekey>
+warns about errors but continues to rekey all principals that it can.  In
+this case, a copy of the existing keytab prior to the rekeying is saved in
+a file named by appending C<.old> to the file name.
+
+If no keytab file name is given on the command line, B<wallet-rekey>
+attempts to rekey F</etc/krb5.keytab>, the system default keytab file.
+
+The new keys are merged into the existing keytab file, but old keys are
+not removed.  This means that, over time, the keytab will grow and
+accumulate old keys, which eventually should no longer be honored.
+Administrators may want to run:
+
+    kadmin -q 'ktremove -k <keytab> <principal> old'
+
+for MIT Kerberos, where <keytab> is the path to the keytab and <principal>
+is a principal in the keytab (repeating the command for each principal)
+or:
+
+    ktutil -k <keytab> purge
+
+for Heimdal.  This functionality will eventually be provided by
+B<wallet-rekey> directly.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-c> I<command>
+
+The command prefix (remctl type) to use.  Normally this is an internal
+implementation detail and the default (C<wallet>) should be fine.  It may
+sometimes be useful to use a different prefix for testing a different
+version of the wallet code on the server.  This option can also be set in
+F<krb5.conf>; see L<CONFIGURATION> below.
+
+=item B<-k> I<principal>
+
+The service principal of the wallet server.  The default is to use the
+C<host> principal for the wallet server.  The principal chosen must match
+one of the keys in the keytab used by B<remctld> on the wallet server.
+This option can also be set in F<krb5.conf>; see L<CONFIGURATION> below.
+
+=item B<-h>
+
+Display a brief summary of options and exit.  All other valid options and
+commands are ignored.
+
+=item B<-p> I<port>
+
+The port to connect to on the wallet server.  The default is the default
+remctl port.  This option can also be set in F<krb5.conf>; see
+L<CONFIGURATION> below.
+
+=item B<-s> I<server>
+
+The wallet server to connect to.  The default may be set when compiling
+the wallet client.  If it isn't, either B<-s> must be given or the server
+must be set in F<krb5.conf>.  See L<CONFIGURATION> below.
+
+=item B<-u> I<principal>
+
+Rather than using the user's existing ticket cache for authentication,
+authenticate as I<principal> first and use those credentials for
+authentication to the wallet server.  B<wallet> will prompt for the
+password for I<principal>.  Non-password authentication methods such as
+PKINIT aren't supported; to use those, run B<kinit> first and use an
+existing ticket cache.
+
+=item B<-v>
+
+Display the version of the B<wallet> client and exit.  All other valid
+options and commands are ignored.
+
+=back
+
+=head1 CONFIGURATION
+
+The wallet system, including B<wallet-rekey>, can optionally be configured
+in the system F<krb5.conf>.  It will read the default F<krb5.conf> file
+for the Kerberos libraries with which it was compiled.  To set an option,
+put the option in the [appdefaults] section.  B<wallet-rekey> will look
+for options either at the top level of the [appdefaults] section or in a
+subsection named C<wallet>.  For example, the following fragment of a
+F<krb5.conf> file would set the default port to 4373 and the default
+server to C<wallet.example.org>.
+
+    [appdefaults]
+        wallet_port = 4373
+        wallet = {
+            wallet_server = wallet.example.org
+        }
+
+The supported options are:
+
+=over 4
+
+=item wallet_principal
+
+The service principal of the wallet server.  The default is to use the
+C<host> principal for the wallet server.  The principal chosen must match
+one of the keys in the keytab used by B<remctld> on the wallet server.
+The B<-k> command-line option overrides this setting.
+
+=item wallet_port
+
+The port to connect to on the wallet server.  The default is the default
+remctl port.  The B<-p> command-line option overrides this setting.
+
+=item wallet_server
+
+The wallet server to connect to.  The B<-s> command-line option overrides
+this setting.  The default may be set when compiling the wallet client.
+If it isn't, either B<-s> must be given or this parameter must be present
+in in F<krb5.conf>.
+
+=item wallet_type
+
+The command prefix (remctl type) to use.  Normally this is an internal
+implementation detail and the default (C<wallet>) should be fine.  It may
+sometimes be useful to use a different prefix for testing a different
+version of the wallet code on the server.  The B<-c> command-line option
+overrides this setting.
+
+=back
+
+=head1 SEE ALSO
+
+kadmin(8), kinit(1), krb5.conf(5), remctl(1), remctld(8), wallet(1)
+
+This program is part of the wallet system.  The current version is available
+from L<http://www.eyrie.org/~eagle/software/wallet/>.
+
+B<wallet-rekey> uses the remctl protocol.  For more information about
+remctl, see L<http://www.eyrie.org/~eagle/software/remctl/>.
+
+=head1 AUTHOR
+
+Russ Allbery <rra@stanford.edu>
+
+=cut
diff --git a/tests/docs/pod-spelling-t b/tests/docs/pod-spelling-t
index 6993e4c..eaa7dd6 100755
--- a/tests/docs/pod-spelling-t
+++ b/tests/docs/pod-spelling-t
@@ -47,8 +47,8 @@ my @pod = map {
     my $pod = "$ENV{SOURCE}/../" . $_;
     $pod =~ s,[^/.][^/]*/../,,g;
     $pod;
-} qw(client/wallet.pod server/keytab-backend server/wallet-admin
-     server/wallet-backend server/wallet-report);
+} qw(client/wallet.pod client/wallet-rekey.pod server/keytab-backend
+     server/wallet-admin server/wallet-backend server/wallet-report);
 plan tests => scalar @pod;
 
 # Finally, do the checks.
diff --git a/tests/docs/pod-t b/tests/docs/pod-t
index f92ba2c..e25ade2 100755
--- a/tests/docs/pod-t
+++ b/tests/docs/pod-t
@@ -12,8 +12,9 @@ use Test::More;
 eval 'use Test::Pod 1.00';
 plan skip_all => 'Test::Pod 1.00 required for testing POD' if $@;
 
-my @files = qw(client/wallet.pod server/keytab-backend server/wallet-admin
-               server/wallet-backend server/wallet-report);
+my @files = qw(client/wallet.pod client/wallet-rekey.pod server/keytab-backend
+               server/wallet-admin server/wallet-backend
+               server/wallet-report);
 my $total = scalar (@files);
 plan tests => $total;
 for my $file (@files) {