Add warnings for Authentication Server commands
authorRuss Allbery <rra@stanford.edu>
Thu, 27 May 2010 21:40:21 +0000 (16:40 -0500)
committerDerrick Brashear <shadow@dementia.org>
Tue, 1 Jun 2010 03:40:58 +0000 (20:40 -0700)
For each command only useful with the Authentication Server, add
warnings that the Authentication Server is obsolete and will be
removed in a future version of OpenAFS.  Encourage people who care
to update uss to work with a modern Kerberos KDC, recommend kinit
and aklog or klog.krb5 over klog, and warn that klog will be of
limited use without an Authentication Server.

Change-Id: Idc78ba548134b83ac1eea0fb81a5bc38a431bb38
Reviewed-on: http://gerrit.openafs.org/2052
Reviewed-by: Derrick Brashear <shadow@dementia.org>
Tested-by: Derrick Brashear <shadow@dementia.org>

12 files changed:
doc/man-pages/pod1/klog.pod
doc/man-pages/pod1/kpasswd.pod
doc/man-pages/pod5/AuthLog.dir.pod
doc/man-pages/pod5/AuthLog.pod
doc/man-pages/pod5/kaserver.DB0.pod
doc/man-pages/pod5/kaserverauxdb.pod
doc/man-pages/pod8/kadb_check.pod
doc/man-pages/pod8/kas.pod
doc/man-pages/pod8/kaserver.pod
doc/man-pages/pod8/kdb.pod
doc/man-pages/pod8/kpwvalid.pod
doc/man-pages/pod8/uss.pod

index 6736ee4..3dbdc72 100644 (file)
@@ -31,11 +31,16 @@ B<klog.krb> [B<-x>] S<<< [B<-principal> <I<user name>>] >>>
 
 =head1 DESCRIPTION
 
-The B<klog> command obtains an AFS token from the Authentication
-Server. The Cache Manager on the local machine stores the token in a
-credential structure in kernel memory and uses it when obtaining
-authenticated access to the AFS filespace. This command does not affect
-the issuer's identity (UNIX UID) in the local file system.
+The B<klog> command obtains an AFS token from the obsolete Authentication
+Server or a Kerberos KDC that speaks the same protocol, such as B<fakeka>
+or a Heimdal Kerberos KDC. The Cache Manager on the local machine stores
+the token in a credential structure in kernel memory and uses it when
+obtaining authenticated access to the AFS filespace. This command does not
+affect the issuer's identity (UNIX UID) in the local file system.
+
+The B<klog> command is obsolete and should not be used. Instead, use
+B<kinit> followed by B<aklog> or B<klog.krb5>. See L<aklog(1)> and
+L<klog.krb5(1)> for more information.
 
 By default, the command interpreter obtains a token for the AFS user name
 that matches the issuer's identity in the local file system. To specify an
@@ -56,16 +61,16 @@ token per cell per connection to the client machine. If the user's
 credential structure already contains a token for the requested cell, the
 token resulting from this command replaces it.
 
-Sites that employ Kerberos authentication instead of the AFS
-Authentication Server should normally use the combination of B<kinit> and
-B<aklog> instead of B<klog>.
+Sites that employ Kerberos version 5 authentication instead of the
+Authentication Server (strongly recommended) should normally use the
+combination of B<kinit> and B<aklog> instead of B<klog>.
 
-Sites using Kerberos v4 authentication (perhaps with the AFS
-Authentication Server) should use the Kerberos version of this command,
-B<klog.krb>, on all client machines. It automatically places the issuer's
-Kerberos tickets in the file named by the KRBTKFILE environment variable,
-which the B<pagsh.krb> command defines automatically as F</tmp/tktpI<X>>
-where I<X> is the number of the user's PAG.
+Sites using Kerberos v4 authentication (perhaps with the Authentication
+Server) may wish to use the Kerberos version of this command, B<klog.krb>,
+on all client machines. It automatically places the issuer's Kerberos
+tickets in the file named by the KRBTKFILE environment variable, which the
+B<pagsh.krb> command defines automatically as F</tmp/tktpI<X>> where I<X>
+is the number of the user's PAG.
 
 The lifetime of the token resulting from this command is the smallest of
 the following.
@@ -147,6 +152,14 @@ lifetime to the next highest possible lifetime.
 
 =head1 CAUTIONS
 
+B<klog> speaks a protocol specific to the obsolete Authentication Server
+and is provided primarily to support cells that have not yet migrated to a
+Kerberos version 5 KDC. It is still useful at cells not running the
+Authentication Server if the associated Kerberos realm supports
+Authentication Server queries (such as a Heimdal KDC or B<fakeka>), but
+using B<klog.krb5> or B<kinit> plus B<aklog> instead of this command is
+recommended.
+
 By default, this command does not create a new process authentication
 group (PAG); see the description of the B<pagsh> command to learn about
 PAGs. If a cell does not use an AFS-modified login utility, users must
index f6317d7..a73338f 100644 (file)
@@ -22,11 +22,12 @@ B<kpasswd> [B<-x>] S<<< [B<-pr> <I<user name>>] >>> S<<< [B<-pa> <I<user's passw
 =head1 DESCRIPTION
 
 The B<kpasswd> command changes the password recorded in an Authentication
-Database entry. By default, the command interpreter changes the password
-for the AFS user name that matches the issuer's local identity (UNIX
-UID). To specify an alternate user, include the B<-principal>
-argument. The user named by the B<-principal> argument does not have to
-appear in the local password file (the F</etc/passwd> file or equivalent).
+Database entry on the obsolete Authentication Server. By default, the
+command interpreter changes the password for the AFS user name that
+matches the issuer's local identity (UNIX UID). To specify an alternate
+user, include the B<-principal> argument. The user named by the
+B<-principal> argument does not have to appear in the local password file
+(the F</etc/passwd> file or equivalent).
 
 By default, the command interpreter sends the password change request to
 the Authentication Server running on one of the database server machines
@@ -74,6 +75,13 @@ a password before the minimum time has passed:
 
 =back
 
+=head1 CAUTIONS
+
+The B<kpasswd> command is only used by the obsolete Authentication Server
+It is provided for sites that have not yet migrated to a Kerberos version
+5 KDC. The Authentication Server and supporting commands, including
+B<kpwvalid>, will be removed in a future version of OpenAFS.
+
 =head1 OPTIONS
 
 =over 4
index fe366d6..6a02052 100644 (file)
@@ -16,6 +16,10 @@ superuser C<root>.
 
 =head1 CAUTIONS
 
+The Authentication Server is obsolete and is provided only for sites that
+need to use it while preparing for a migration to Kerberos KDC. It will be
+removed in a future version of OpenAFS.
+
 The Authentication Server is possibly unable to create these files on some
 operating systems that AFS otherwise supports, making the B<kdb> command
 inoperative.
index fa3a1f6..4cb56a3 100644 (file)
@@ -26,6 +26,12 @@ and cannot recover from failures by reviewing the file. The log contents
 are useful for administrative evaluation of process failures and other
 problems.
 
+=head1 CAUTIONS
+
+The Authentication Server is obsolete and is provided only for sites that
+need to use it while preparing for a migration to Kerberos KDC. It will be
+removed in a future version of OpenAFS.
+
 =head1 SEE ALSO
 
 L<UserList(5)>,
index 0cede50..eefbbad 100644 (file)
@@ -27,6 +27,12 @@ Always use the commands in the kas suite to administer the Authentication
 Database. It is advisable to create an archive copy of the database on a
 regular basis, using a tool such as the UNIX B<tar> command.
 
+=head1 CAUTIONS
+
+The Authentication Server is obsolete and is provided only for sites that
+need to use it while preparing for a migration to Kerberos KDC. It will be
+removed in a future version of OpenAFS.
+
 =head1 SEE ALSO
 
 L<kadb_check(8)>,
index dd27600..8a96d3c 100644 (file)
@@ -23,6 +23,12 @@ directly accessible. However, the output from the B<kas examine> command
 reports an account's maximum number of failed attempts, the lockout time,
 and whether the account is currently locked.
 
+=head1 CAUTIONS
+
+The Authentication Server is obsolete and is provided only for sites that
+need to use it while preparing for a migration to Kerberos KDC. It will be
+removed in a future version of OpenAFS.
+
 =head1 SEE ALSO
 
 L<kaserver.DB0(5)>,
index 2c1c195..f0af119 100644 (file)
@@ -18,12 +18,18 @@ B<kadb_check> S<<< B<-d> <I<kadb file>> >>> [B<-u>] [B<-k>] [B<-e>] [B<-v>]
 
 =head1 DESCRIPTION
 
-The B<kadb_check> command checks the integrity of the Protection Database,
-reporting any errors or corruption it finds. If there are problems, do not
-issue any B<kas> commands until the database is repaired.
+The B<kadb_check> command checks the integrity of the Authentication
+Database, reporting any errors or corruption it finds. If there are
+problems, do not issue any B<kas> commands until the database is repaired.
 
 =head1 CAUTIONS
 
+The B<kadb_check> command is only used with the database used by the
+obsolete Authentication Server, which should no longer be used. It is
+provided for sites that have not yet migrated to a Kerberos version 5
+KDC. The Authentication Server and supporting commands, including B<kdb>,
+will be removed in a future version of OpenAFS.
+
 The results can be unpredictable if the Authentication Server makes
 changes to the Authentication Database while this command is running. Use
 the B<bos shutdown> command to shutdown the local B<kaserver> process
index 6952525..f6cda79 100644 (file)
@@ -5,10 +5,12 @@ kas - Introduction to the kas command suite
 =head1 DESCRIPTION
 
 The commands in the B<kas> command suite are the administrative interface
-to the Authentication Server, which runs on each database server machine
-in a cell, maintains the Authentication Database, and provides the
-authentication tickets that client applications must present to AFS
-servers in order to obtain access to AFS data and other services.
+to the Authentication Server, an obsolete AFS server process that
+maintains the Authentication Database and provides the authentication
+tickets that client applications must present to AFS servers in order to
+obtain access to AFS data and other services. It is used only for cells
+still running the Authentication Server until they can migrate to a
+Kerberos version 5 KDC.
 
 There are several categories of commands in the B<kas> command suite:
 
@@ -84,6 +86,14 @@ argument.
 
 =back
 
+=head1 CAUTIONS
+
+The B<kas> command suite is provided only for administration of the
+obsolete Authentication Server for cells that have not yet migrated to a
+Kerberos version 5 KDC. New deployments should not use the Authentication
+Server, and it and the B<kas> command suite will be removed in a future
+version of OpenAFS.
+
 =head1 OPTIONS
 
 The following arguments and flags are available on many commands in the
index 700adfd..7c6d12c 100644 (file)
@@ -18,10 +18,16 @@ B<kaserver> [B<-noAuth>] [B<-database> <I<dbpath>>]
 
 =head1 DESCRIPTION
 
-The B<kaserver> command initializes the Authentication Server, which runs
-on every database server machine. In the conventional configuration, its
-binary file is located in the F</usr/afs/bin> directory on a file server
-machine.
+The B<kaserver> command initializes the Authentication Server, an obsolete
+way of providing authentication services to an AFS cell. It should no
+longer be used; instead, it should be replaced with a Kerberos version 5
+KDC. It is provided only for support of sites already running the
+Authentication Server and that have not yet migrated to Kerberos version
+5.
+
+For a cell using the Authentication Server, it runs on every database
+server machine. In the conventional configuration, its binary file is
+located in the F</usr/afs/bin> directory on a file server machine.
 
 The B<kaserver> command is not normally issued at the command shell prompt
 but rather placed into a file server machine's F</usr/afs/local/BosConfig>
@@ -61,6 +67,21 @@ F<AuthLog.pag>.
 This command does not use the syntax conventions of the AFS command
 suites. Provide the command name and all option names in full.
 
+=head1 CAUTIONS
+
+The Authentication Server provides only Kerberos version 4, which is no
+longer considered sufficiently secure. It can only use DES encryption for
+user keys, is vulnerable to known flaws in the Kerberos version 4
+protocol, and is based on protocols that are obsolete and no longer
+developed. The Authentication Server is also not widely tested and is
+known to have problems on some platforms OpenAFS otherwise supports.
+
+The Authentication Server should not be used for any new deployment. It is
+provided only for sites that need to use it while preparing for a
+migration to Kerberos KDC. No significant updates to the Authentication
+Server will be developed, and it will be removed from a future version of
+OpenAFS.
+
 =head1 OPTIONS
 
 =over 4
index ca039cf..eb9e810 100644 (file)
@@ -20,10 +20,17 @@ F<AuthLog.pag> files associated with the F<AuthLog> file that resides on
 the local disk, by default in the F</usr/afs/logs> directory. The files
 must exist in that directory, which normally implies that the
 Authentication Server is running on the machine. The files contain
-information on privileged actions performed by the Authentication Server.
+information on privileged actions performed by the obsolete Authentication
+Server.
 
 =head1 CAUTIONS
 
+The B<kdb> command is only used to read the log files from the obsolete
+Authentication Server, which should no longer be used. It is provided for
+sites that have not yet migrated to a Kerberos version 5 KDC. The
+Authentication Server and supporting commands, including B<kdb>, will be
+removed in a future version of OpenAFS.
+
 It is possible that on some operating systems that AFS otherwise supports,
 the Authentication Server cannot create the F</usr/afs/logs/AuthLog.dir>
 and F</usr/afs/logs/AuthLog.pag> files, making this command inoperative.
index 6e35044..7ee468e 100644 (file)
@@ -15,13 +15,14 @@ B<kpwvalid>
 =head1 DESCRIPTION
 
 The B<kpwvalid> command checks the quality of a new password passed to it
-from the B<kpasswd> or B<kas setpassword> command. It is optional. If it
-exists, it must reside in the same AFS directory as the binaries for the
-B<kpasswd> and B<kas> command suites (create a symbolic link from the
-client machine's local disk to this directory). The directory's ACL must
-extend the C<a> (administer) and C<w> (write) permissions to the
-system:administrators group only. These requirements prevent unauthorized
-users from substituting a spurious B<kpwvalid> binary.
+from the B<kpasswd> or B<kas setpassword> command for the obsolete
+Authentication Server. It is optional. If it exists, it must reside in the
+same AFS directory as the binaries for the B<kpasswd> and B<kas> command
+suites (create a symbolic link from the client machine's local disk to
+this directory). The directory's ACL must extend the C<a> (administer) and
+C<w> (write) permissions to the system:administrators group only. These
+requirements prevent unauthorized users from substituting a spurious
+B<kpwvalid> binary.
 
 The AFS distribution includes an example B<kpwvalid> program that checks
 that the password is at least eight characters long; the code for it
@@ -50,6 +51,13 @@ password is not acceptable.
 Further, it must write any error messages only to the standard error
 stream, not to the standard output stream.
 
+=head1 CAUTIONS
+
+The B<kpwvalid> command is only used by the obsolete Authentication Server
+It is provided for sites that have not yet migrated to a Kerberos version
+5 KDC. The Authentication Server and supporting commands, including
+B<kpwvalid>, will be removed in a future version of OpenAFS.
+
 =head1 EXAMPLES
 
 The following example program, included in the AFS distribution, verifies
index 8c1c716..3b45590 100644 (file)
@@ -5,9 +5,10 @@ uss - Introduction to the uss command suite
 =head1 DESCRIPTION
 
 The commands in the B<uss> command suite help administrators to create AFS
-user accounts more easily and efficiently. If B<uss> commands are not
-used, creating an account requires issuing at least six separate commands
-to five different AFS servers.
+user accounts more easily and efficiently for cells using the obsolete
+Authentication Server. If B<uss> commands are not used, creating an
+account requires issuing at least six separate commands to five different
+AFS servers.
 
 There are three main commands in the suite:
 
@@ -32,6 +33,15 @@ The B<uss delete> command removes most parts of a user account.
 
 To obtain help, issue the B<uss apropos> and B<uss help> commands.
 
+=head1 CAUTIONS
+
+The B<uss> command suite is currently designed for cells using the
+obsolete Authentication Server, and therefore is primarily useful for
+sites that have not yet migrated to a Kerberos version 5 KDC. The
+Authentication Server and supporting commands will be removed in a future
+version of OpenAFS, which may include B<uss> unless someone who finds it
+useful converts it to work with a Kerberos version 5 KDC.
+
 =head1 OPTIONS
 
 The following arguments and flags are available on many commands in the