Update bos addkey/listkeys and KeyFile man pages for asetkey

[openafs.git] / doc / man-pages / pod8 / bos_addkey.pod

diff --git a/doc/man-pages/pod8/bos_addkey.pod b/doc/man-pages/pod8/bos_addkey.pod
index f3de026..2678d09 100644 (file)
--- a/doc/man-pages/pod8/bos_addkey.pod
+++ b/doc/man-pages/pod8/bos_addkey.pod
@@ -1,25 +1,40 @@
 =head1 NAME
 
-bos addkey - Adds a new server encryption key to the KeyFile file
+bos_addkey - Adds a new server encryption key to the KeyFile file
 
 =head1 SYNOPSIS
 
-B<bos addkey> B<-server> <I<machine name>> [B<-key> <I<key>>]
-    B<-kvno> <I<key version number>> [B<-cell> <I<cell name>>]
+=for html
+<div class="synopsis">
+
+B<bos addkey> S<<< B<-server> <I<machine name>> >>> S<<< [B<-key> <I<key>>] >>>
+    S<<< B<-kvno> <I<key version number>> >>> S<<< [B<-cell> <I<cell name>>] >>>
     [B<-noauth>] [B<-localauth>] [B<-help>]
 
-B<bos addk> B<-s> <I<machine name>> [B<-ke> <I<key>>]
-    B<-kv> <I<key version number>> [B<-ce> <I<cell name>>] [B<-n>]
+B<bos addk> S<<< B<-s> <I<machine name>> >>> S<<< [B<-ke> <I<key>>] >>>
+    S<<< B<-kv> <I<key version number>> >>> S<<< [B<-ce> <I<cell name>>] >>> [B<-n>]
     [B<-l>] [B<-h>]
 
+=for html
+</div>
+
 =head1 DESCRIPTION
 
 The B<bos addkey> command constructs a server encryption key from the text
 string provided, assigns it the key version number specified with the
 B<-kvno> argument, and adds it to the F</usr/afs/etc/KeyFile> file on the
-machine specified with the B<-server> argument. Be sure to use the B<kas
-setpassword> or B<kas setkey> command to add the same key to the C<afs>
-entry in the Authentication Database.
+machine specified with the B<-server> argument.
+
+Normally, B<asetkey add> should be used instead of this command; see
+L<asetkey(8)> for more details. The primary use of B<bos addkey> is for
+cells that are still using the Authentication Server instead of a Kerberos
+v5 KDC. It may, however, also be useful in unusual circumstances where a
+key needs to be added based on a known password rather than via a Kerberos
+v5 keytab.
+
+When using B<bos addkey> with an AFS cell that uses the Authentication
+Server, be sure to use the B<kas setpassword> or B<kas setkey> command to
+add the same key to the C<afs> entry in the Authentication Database.
 
 Do not use the B<-key> argument, which echoes the password string visibly
 on the screen. If the argument is omitted, the BOS Server prompts for the
@@ -35,6 +50,15 @@ with a server process because the current key is overwritten with a new
 key. Use the B<bos listkeys> command to display the key version numbers in
 the F</usr/afs/etc/KeyFile> file.
 
+=head1 CAUTIONS
+
+In the unusual case of using B<bos addkey> to add a key with a known
+password matching a password used to generate Kerberos v5 keys, the key in
+the Kerberos v5 KDC database must have only the DES encryption type and
+must use C<afs3> salt, not the default Kerberos v5 salt. Otherwise, the
+key generated by B<bos addkey> will not match the key generated by the
+Kerberos v5 KDC.
+
 =head1 OPTIONS
 
 =over 4
@@ -121,6 +145,7 @@ included.
 
 L<KeyFile(5)>,
 L<UserList(5)>,
+L<asetkey(8)>,
 L<bos(8)>,
 L<bos_listkeys(8)>,
 L<bos_removekey(8)>
@@ -129,6 +154,6 @@ L<bos_removekey(8)>
 
 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
 
-This documentation is covered by the IBM Public License Version 1.0.  It was
-converted from HTML to POD by software written by Chas Williams and Russ
-Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
+This documentation is covered by the IBM Public License Version 1.0.  It
+was converted from HTML to POD by software written by Chas Williams and
+Russ Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.