From af1dbcf0c9d29d2dfaf87c7f6fe64018927626ad Mon Sep 17 00:00:00 2001 From: Russ Allbery Date: Thu, 27 May 2010 16:40:21 -0500 Subject: [PATCH] Add warnings for Authentication Server commands 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 Tested-by: Derrick Brashear --- doc/man-pages/pod1/klog.pod | 41 ++++++++++++++++++---------- doc/man-pages/pod1/kpasswd.pod | 18 ++++++++---- doc/man-pages/pod5/AuthLog.dir.pod | 4 +++ doc/man-pages/pod5/AuthLog.pod | 6 ++++ doc/man-pages/pod5/kaserver.DB0.pod | 6 ++++ doc/man-pages/pod5/kaserverauxdb.pod | 6 ++++ doc/man-pages/pod8/kadb_check.pod | 12 ++++++-- doc/man-pages/pod8/kas.pod | 18 +++++++++--- doc/man-pages/pod8/kaserver.pod | 29 +++++++++++++++++--- doc/man-pages/pod8/kdb.pod | 9 +++++- doc/man-pages/pod8/kpwvalid.pod | 22 ++++++++++----- doc/man-pages/pod8/uss.pod | 16 +++++++++-- 12 files changed, 146 insertions(+), 41 deletions(-) diff --git a/doc/man-pages/pod1/klog.pod b/doc/man-pages/pod1/klog.pod index 6736ee4e3..3dbdc7229 100644 --- a/doc/man-pages/pod1/klog.pod +++ b/doc/man-pages/pod1/klog.pod @@ -31,11 +31,16 @@ B [B<-x>] S<<< [B<-principal> >] >>> =head1 DESCRIPTION -The B 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 command obtains an AFS token from the obsolete Authentication +Server or a Kerberos KDC that speaks the same protocol, such as B +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 command is obsolete and should not be used. Instead, use +B followed by B or B. See L and +L 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 and -B instead of B. +Sites that employ Kerberos version 5 authentication instead of the +Authentication Server (strongly recommended) should normally use the +combination of B and B instead of B. -Sites using Kerberos v4 authentication (perhaps with the AFS -Authentication Server) should use the Kerberos version of this command, -B, on all client machines. It automatically places the issuer's -Kerberos tickets in the file named by the KRBTKFILE environment variable, -which the B command defines automatically as F> -where I 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, +on all client machines. It automatically places the issuer's Kerberos +tickets in the file named by the KRBTKFILE environment variable, which the +B command defines automatically as F> where I +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 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), but +using B or B plus B 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 command to learn about PAGs. If a cell does not use an AFS-modified login utility, users must diff --git a/doc/man-pages/pod1/kpasswd.pod b/doc/man-pages/pod1/kpasswd.pod index f6317d7f1..a73338fa2 100644 --- a/doc/man-pages/pod1/kpasswd.pod +++ b/doc/man-pages/pod1/kpasswd.pod @@ -22,11 +22,12 @@ B [B<-x>] S<<< [B<-pr> >] >>> S<<< [B<-pa> 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 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 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 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, will be removed in a future version of OpenAFS. + =head1 OPTIONS =over 4 diff --git a/doc/man-pages/pod5/AuthLog.dir.pod b/doc/man-pages/pod5/AuthLog.dir.pod index fe366d61a..6a020521f 100644 --- a/doc/man-pages/pod5/AuthLog.dir.pod +++ b/doc/man-pages/pod5/AuthLog.dir.pod @@ -16,6 +16,10 @@ superuser C. =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 command inoperative. diff --git a/doc/man-pages/pod5/AuthLog.pod b/doc/man-pages/pod5/AuthLog.pod index fa3a1f69f..4cb56a344 100644 --- a/doc/man-pages/pod5/AuthLog.pod +++ b/doc/man-pages/pod5/AuthLog.pod @@ -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, diff --git a/doc/man-pages/pod5/kaserver.DB0.pod b/doc/man-pages/pod5/kaserver.DB0.pod index 0cede5033..eefbbadac 100644 --- a/doc/man-pages/pod5/kaserver.DB0.pod +++ b/doc/man-pages/pod5/kaserver.DB0.pod @@ -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 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, diff --git a/doc/man-pages/pod5/kaserverauxdb.pod b/doc/man-pages/pod5/kaserverauxdb.pod index dd2760047..8a96d3c7a 100644 --- a/doc/man-pages/pod5/kaserverauxdb.pod +++ b/doc/man-pages/pod5/kaserverauxdb.pod @@ -23,6 +23,12 @@ directly accessible. However, the output from the B 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, diff --git a/doc/man-pages/pod8/kadb_check.pod b/doc/man-pages/pod8/kadb_check.pod index 2c1c1950a..f0af11917 100644 --- a/doc/man-pages/pod8/kadb_check.pod +++ b/doc/man-pages/pod8/kadb_check.pod @@ -18,12 +18,18 @@ B S<<< B<-d> > >>> [B<-u>] [B<-k>] [B<-e>] [B<-v>] =head1 DESCRIPTION -The B command checks the integrity of the Protection Database, -reporting any errors or corruption it finds. If there are problems, do not -issue any B commands until the database is repaired. +The B command checks the integrity of the Authentication +Database, reporting any errors or corruption it finds. If there are +problems, do not issue any B commands until the database is repaired. =head1 CAUTIONS +The B 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, +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 command to shutdown the local B process diff --git a/doc/man-pages/pod8/kas.pod b/doc/man-pages/pod8/kas.pod index 69525253c..f6cda79e7 100644 --- a/doc/man-pages/pod8/kas.pod +++ b/doc/man-pages/pod8/kas.pod @@ -5,10 +5,12 @@ kas - Introduction to the kas command suite =head1 DESCRIPTION The commands in the B 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 command suite: @@ -84,6 +86,14 @@ argument. =back +=head1 CAUTIONS + +The B 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 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 diff --git a/doc/man-pages/pod8/kaserver.pod b/doc/man-pages/pod8/kaserver.pod index 700adfdbd..7c6d12ce0 100644 --- a/doc/man-pages/pod8/kaserver.pod +++ b/doc/man-pages/pod8/kaserver.pod @@ -18,10 +18,16 @@ B [B<-noAuth>] [B<-database> >] =head1 DESCRIPTION -The B command initializes the Authentication Server, which runs -on every database server machine. In the conventional configuration, its -binary file is located in the F directory on a file server -machine. +The B 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 directory on a file server machine. The B command is not normally issued at the command shell prompt but rather placed into a file server machine's F @@ -61,6 +67,21 @@ F. 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 diff --git a/doc/man-pages/pod8/kdb.pod b/doc/man-pages/pod8/kdb.pod index ca039cf26..eb9e81081 100644 --- a/doc/man-pages/pod8/kdb.pod +++ b/doc/man-pages/pod8/kdb.pod @@ -20,10 +20,17 @@ F files associated with the F file that resides on the local disk, by default in the F 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 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, 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 and F files, making this command inoperative. diff --git a/doc/man-pages/pod8/kpwvalid.pod b/doc/man-pages/pod8/kpwvalid.pod index 6e3504428..7ee468e60 100644 --- a/doc/man-pages/pod8/kpwvalid.pod +++ b/doc/man-pages/pod8/kpwvalid.pod @@ -15,13 +15,14 @@ B =head1 DESCRIPTION The B command checks the quality of a new password passed to it -from the B or B command. It is optional. If it -exists, it must reside in the same AFS directory as the binaries for the -B and B command suites (create a symbolic link from the -client machine's local disk to this directory). The directory's ACL must -extend the C (administer) and C (write) permissions to the -system:administrators group only. These requirements prevent unauthorized -users from substituting a spurious B binary. +from the B or B 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 and B command +suites (create a symbolic link from the client machine's local disk to +this directory). The directory's ACL must extend the C (administer) and +C (write) permissions to the system:administrators group only. These +requirements prevent unauthorized users from substituting a spurious +B binary. The AFS distribution includes an example B 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 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, will be removed in a future version of OpenAFS. + =head1 EXAMPLES The following example program, included in the AFS distribution, verifies diff --git a/doc/man-pages/pod8/uss.pod b/doc/man-pages/pod8/uss.pod index 8c1c716b1..3b4559091 100644 --- a/doc/man-pages/pod8/uss.pod +++ b/doc/man-pages/pod8/uss.pod @@ -5,9 +5,10 @@ uss - Introduction to the uss command suite =head1 DESCRIPTION The commands in the B command suite help administrators to create AFS -user accounts more easily and efficiently. If B 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 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 command removes most parts of a user account. To obtain help, issue the B and B commands. +=head1 CAUTIONS + +The B 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 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 -- 2.39.5