From d6a512c1b8663c2ed4d3aeae93f580f66e65a362 Mon Sep 17 00:00:00 2001 From: Russ Allbery Date: Thu, 29 Jul 2010 15:23:02 -0700 Subject: Add documentation for wallet-rekey --- client/wallet-rekey.pod | 165 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 165 insertions(+) create mode 100644 client/wallet-rekey.pod (limited to 'client') 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 [B<-hv>] [B<-c> I] [B<-k> I] + [B<-p> I] [B<-s> I] [B<-u> I] [I ...] + +=head1 DESCRIPTION + +B 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 +aborts. If some new keys were successfully downloaded, B +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 +attempts to rekey F, 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 old' + +for MIT Kerberos, where is the path to the keytab and +is a principal in the keytab (repeating the command for each principal) +or: + + ktutil -k purge + +for Heimdal. This functionality will eventually be provided by +B directly. + +=head1 OPTIONS + +=over 4 + +=item B<-c> I + +The command prefix (remctl type) to use. Normally this is an internal +implementation detail and the default (C) 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; see L below. + +=item B<-k> I + +The service principal of the wallet server. The default is to use the +C principal for the wallet server. The principal chosen must match +one of the keys in the keytab used by B on the wallet server. +This option can also be set in F; see L below. + +=item B<-h> + +Display a brief summary of options and exit. All other valid options and +commands are ignored. + +=item B<-p> I + +The port to connect to on the wallet server. The default is the default +remctl port. This option can also be set in F; see +L below. + +=item B<-s> I + +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. See L below. + +=item B<-u> I + +Rather than using the user's existing ticket cache for authentication, +authenticate as I first and use those credentials for +authentication to the wallet server. B will prompt for the +password for I. Non-password authentication methods such as +PKINIT aren't supported; to use those, run B first and use an +existing ticket cache. + +=item B<-v> + +Display the version of the B client and exit. All other valid +options and commands are ignored. + +=back + +=head1 CONFIGURATION + +The wallet system, including B, can optionally be configured +in the system F. It will read the default F file +for the Kerberos libraries with which it was compiled. To set an option, +put the option in the [appdefaults] section. B will look +for options either at the top level of the [appdefaults] section or in a +subsection named C. For example, the following fragment of a +F file would set the default port to 4373 and the default +server to C. + + [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 principal for the wallet server. The principal chosen must match +one of the keys in the keytab used by B 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. + +=item wallet_type + +The command prefix (remctl type) to use. Normally this is an internal +implementation detail and the default (C) 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. + +B uses the remctl protocol. For more information about +remctl, see L. + +=head1 AUTHOR + +Russ Allbery + +=cut -- cgit v1.2.3