man-page-asetkey-20060329

Add a man page for asetkey.

diff --git a/doc/man-pages/pod8/asetkey.pod b/doc/man-pages/pod8/asetkey.pod
new file mode 100644 (file)
index 0000000..b7f0765
--- /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
+<div class="synopsis">
+
+B<asetkey> add <I<kvno>> <I<keyfile>> <I<principal>>
+
+B<asetkey> delete <I<kvno>>
+
+B<asetkey> list
+
+=for html
+</div>
+
+=head1 DESCRIPTION
+
+The B<asetkey> command is used to add a key to an AFS KeyFile from a
+Kerberos keytab.  It is similar to B<bos addkey> 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<asetkey delete> can be used to delete a key (similar to B<bos
+removekeys>), and B<asetkey list> will list the keys in a KeyFile (similar
+to B<bos listkeys>).
+
+B<asetkey> is used when authentication for an AFS cell is provided by a
+Kerberos 5 KDC rather than B<kaserver>.  The key for the C<afs> or
+C<afs/I<cell name>> 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<ktadd> function of the B<kadmin>
+command) and then, on each AFS database server and file server, adding
+that key to the KeyFile with B<asetkey add>.  The I<kvno> chosen should
+match the kvno in the Kerberos KDC (checked with B<kvno> or the
+C<getprinc> function of B<kadmin>).  I<principal> should be the name of
+the AFS principal in the keytab, which must be either C<afs> or
+C<afs/I<cell name>>.
+
+In cells that use the Update Server to distribute the contents of the
+F</usr/afs/etc> directory, it is conventional to run B<asetkey add> 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<ktadd>, 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<ktadd>, 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<asetkey>, 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<ktadd> 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<asetkey> on each server.
+
+=head1 EXAMPLES
+
+The following commands create a new keytab for the principal C<afs> and
+then import the key into the KeyFile.  Note the kvno in the output from
+C<ktadd>.
+
+    % 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<afs/I<cell name>> instead of C<afs>, 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<asetkey list>) and write (for
+B<asetkey add> and B<asetkey delete>) the KeyFile, normally
+F</usr/afs/etc/KeyFile>.  In practice, this means that the issuer must be
+the local superuser C<root> on the AFS file server or database server.
+For B<asetkey add>, the issuer must also be able to read the specified
+keytab file.
+
+=head1 SEE ALSO
+
+L<KeyFile(5)>,
+L<bos_addkey(8)>,
+L<bos_listkeys(8)>,
+L<bos_removekey(8)>,
+kadmin(8),
+kvno(1)
+
+=head1 COPYRIGHT
+
+Copyright 2006 Russ Allbery <rra@stanford.edu>
+
+This documentation is covered by the IBM Public License Version 1.0.  This
+man page was written by Russ Allbery for OpenAFS.