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 --- Makefile.am | 2 +- autogen | 2 + client/wallet-rekey.pod | 165 ++++++++++++++++++++++++++++++++++++++++++++++ tests/docs/pod-spelling-t | 4 +- tests/docs/pod-t | 5 +- 5 files changed, 173 insertions(+), 5 deletions(-) create mode 100644 client/wallet-rekey.pod 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 [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 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) { -- cgit v1.2.3