Add documentation for wallet-rekey

1 files changed, 165 insertions, 0 deletions

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