From 21c5d2fc8fa0a1f7a205e988ed378367e4fab45f Mon Sep 17 00:00:00 2001 From: Russ Allbery Date: Wed, 29 Mar 2006 20:37:45 +0000 Subject: [PATCH] - Add man pages for asetkey and ka-forwarder. --- debian/changelog | 3 +- debian/openafs-krb5.install | 3 + debian/rules | 4 ++ doc/man-pages/pod8/asetkey.pod | 108 ++++++++++++++++++++++++++++ doc/man-pages/pod8/ka-forwarder.pod | 85 ++++++++++++++++++++++ 5 files changed, 202 insertions(+), 1 deletion(-) create mode 100644 doc/man-pages/pod8/asetkey.pod create mode 100644 doc/man-pages/pod8/ka-forwarder.pod diff --git a/debian/changelog b/debian/changelog index 23656815d..9ee4d6946 100644 --- a/debian/changelog +++ b/debian/changelog @@ -9,11 +9,12 @@ openafs (1.4.0+rc10-1) UNRELEASED; urgency=low - Update to the OpenAFS aklog and asetkey. (Closes: #196094) - Backport asetkey from upstream CVS. - Include ka-forwarder from the old migration toolkit. + - Add man pages for asetkey and ka-forwarder. * Subsume openafs-doc into this source package. * Always pass the system type into Autoconf, following autotools-dev best practices. - -- Russ Allbery Tue, 28 Mar 2006 17:03:45 -0800 + -- Russ Allbery Wed, 29 Mar 2006 12:36:19 -0800 openafs (1.4.0-4) unstable; urgency=low diff --git a/debian/openafs-krb5.install b/debian/openafs-krb5.install index 3b40c8282..b6a9a9fe0 100644 --- a/debian/openafs-krb5.install +++ b/debian/openafs-krb5.install @@ -4,3 +4,6 @@ debian/tmp/usr/bin/asetkey usr/sbin debian/tmp/usr/bin/ka-forwarder usr/sbin src/aklog/aklog.1 usr/share/man/man1 + +debian/tmp/usr/share/man/man8/asetkey.8 usr/share/man/man8 +debian/tmp/usr/share/man/man8/ka-forwarder.8 usr/share/man/man8 diff --git a/debian/rules b/debian/rules index e1dc7928a..d01974945 100755 --- a/debian/rules +++ b/debian/rules @@ -103,6 +103,10 @@ build-stamp: mkdir -p $(CURDIR)/debian/tmp $(MAKE) install_nolibafs DESTDIR=$(CURDIR)/debian/tmp chmod +x debian/afs-rootvol debian/afs-newcell + cd doc/man-pages/pod8 && pod2man -c 'AFS Command Reference' \ + -r 'OpenAFS' -s 8 asetkey.pod > ../man8/asetkey.8 + cd doc/man-pages/pod8 && pod2man -c 'AFS Command Reference' \ + -r 'OpenAFS' -s 8 ka-forwarder.pod > ../man8/ka-forwarder.8 touch build-stamp clean: diff --git a/doc/man-pages/pod8/asetkey.pod b/doc/man-pages/pod8/asetkey.pod new file mode 100644 index 000000000..b7f0765b5 --- /dev/null +++ b/doc/man-pages/pod8/asetkey.pod @@ -0,0 +1,108 @@ +=head1 NAME + +asetkey - Add a key from a keytab to an AFS KeyFile + +=head1 SYNOPSIS + +=for html +
+ +B add > > > + +B delete > + +B list + +=for html +
+ +=head1 DESCRIPTION + +The B command is used to add a key to an AFS KeyFile from a +Kerberos keytab. It is similar to B except that it must be +run locally on the system where the KeyFile is located and it takes the +new key from a Kerberos 5 keytab rather than prompting for the password. + +B can be used to delete a key (similar to B), and B will list the keys in a KeyFile (similar +to B). + +B is used when authentication for an AFS cell is provided by a +Kerberos 5 KDC rather than B. The key for the C or +C> principal in the Kerberos 5 KDC must match the key +stored in the AFS KeyFile on all AFS database servers and file servers. +This is done by creating a keytab containing that key using the standard +Kerberos commands (generally the C function of the B +command) and then, on each AFS database server and file server, adding +that key to the KeyFile with B. The I chosen should +match the kvno in the Kerberos KDC (checked with B or the +C function of B). I should be the name of +the AFS principal in the keytab, which must be either C or +C>. + +In cells that use the Update Server to distribute the contents of the +F directory, it is conventional to run B only +on the control machine and then let the Update Server propagate the new +KeyFile to all other systems. + +=head1 CAUTIONS + +AFS currently only supports des-cbc-crc:v4 Kerberos keys. Make sure, when +creating the keytab with C, you pass C<-e des-cbc-crc:v4> to force +the encryption type. Otherwise, AFS authentication may not work. + +As soon as a new keytab is created with C, new AFS service tickets +will use the new key. However, tokens formed from those service tickets +will only work if the new key is present in the KeyFile on the AFS file +server. There is therefore an outage window between when the new keytab +is created and when the key had been added to the KeyFile of all AFS +servers with B, during which newly obtained AFS tokens will not +work properly. + +All of the KeyFile entries must match the key in the Kerberos KDC, but +each time C is run, it creates a new key. Either the Update Server +must be used to distribute the KeyFile to all servers or the same keytab +must be used with B on each server. + +=head1 EXAMPLES + +The following commands create a new keytab for the principal C and +then import the key into the KeyFile. Note the kvno in the output from +C. + + % kadmin + Authenticating as principal rra/admin@stanford.edu with password. + Password for rra/admin@stanford.edu: + kadmin: ktadd -k /tmp/afs.keytab -e des-cbc-crc:v4 afs + Entry for principal afs with kvno 3, encryption type DES cbc mode + with CRC-32 added to keytab WRFILE:/tmp/afs.keytab. + kadmin: exit + % asetkey 3 /tmp/afs.keytab afs + +You may want to use C> instead of C, particularly if +you may have multiple AFS cells for a single Kerberos realm. + +=head1 PRIVILEGE REQUIRED + +The issuer must be able to read (for B) and write (for +B and B) the KeyFile, normally +F. In practice, this means that the issuer must be +the local superuser C on the AFS file server or database server. +For B, the issuer must also be able to read the specified +keytab file. + +=head1 SEE ALSO + +L, +L, +L, +L, +kadmin(8), +kvno(1) + +=head1 COPYRIGHT + +Copyright 2006 Russ Allbery + +This documentation is covered by the IBM Public License Version 1.0. This +man page was written by Russ Allbery for OpenAFS. diff --git a/doc/man-pages/pod8/ka-forwarder.pod b/doc/man-pages/pod8/ka-forwarder.pod new file mode 100644 index 000000000..321f900b9 --- /dev/null +++ b/doc/man-pages/pod8/ka-forwarder.pod @@ -0,0 +1,85 @@ +=head1 NAME + +ka-forwarder - Forward AFS Authentication Server requests to another server + +=head1 SYNOPSIS + +=for html +
+ +B S<<< [B<-p> >] >>> >[/>] [...] + +=for html +
+ +=head1 DESCRIPTION + +B listens for requests for an AFS Authentication Server and +forwards them to a remove B server. B is a server that +answers AFS Authentication Server protocol requests using a regular +Kerberos KDC and is provided with some Kerberos 5 implementations. +B has to run on the same host as the Kerberos KDC, however, and +AFS clients send all native AFS authentication requests to the AFS +database servers. If you don't want to run your Kerberos KDCs and your +AFS database servers on the same host, run B on the AFS +database servers and point it to B running on the Kerberos KDCs. + +B takes one or more servers to which to forward the +requests. The default port on the remote server to which to forward the +command is 7004, but a different port can be specified by following the +server name with a slash (C) and the port number. If multiple servers +are given, B will send queries to each server in turn in a +round-robin fashion. + +=head1 CAUTIONS + +Due to the way that B distinguishes from client requests and +server responses, any messages from one of the servers to which +B is forwarding will be considered a reply rather than a +command and will not be forwarded. This means that the servers running +B will not be able to use native AFS authentication requests and +rely on B to send the requests to the right server. + +B does not background itself. It should either be run in +the background via the shell, or run via the Basic OverSeer Server (see +L). + +=head1 OPTIONS + +=over 4 + +=item B<-p> > + +By default, B listens to the standard AFS Authentication +Server port (7004). To listen to a different port, specify it with the +B<-p> option. + +=back + +=head1 EXAMPLES + +Forward AFS Authentication Server reqests to the B servers on +kdc1.example.com and kdc2.example.com: + + % ka-forwarder kdc1.example.com kdc2.example.com & + +Note the C<&> to tell the shell to run this command in the background. + +=head1 PRIVILEGE REQUIRED + +B only has to listen to port 7004 and therefore does not +require any special privileges unless a privileged port is specified with +the B<-p> option. + +=head1 SEE ALSO + +L, +fakeka(8), +L + +=head1 COPYRIGHT + +Copyright 2006 Russ Allbery + +This documentation is covered by the IBM Public License Version 1.0. This +man page was written by Russ Allbery for OpenAFS. -- 2.39.5