doc: fix some broken link specifications

[openafs.git] / doc / man-pages / pod1 / klog.pod

diff --git a/doc/man-pages/pod1/klog.pod b/doc/man-pages/pod1/klog.pod
index 45dd68b..175c8da 100644 (file)
--- a/doc/man-pages/pod1/klog.pod
+++ b/doc/man-pages/pod1/klog.pod
@@ -1,6 +1,6 @@
 =head1 NAME
 
-klog - Authenticates with the Authentication Server
+klog, klog.krb - Authenticates with the Authentication Server
 
 =head1 SYNOPSIS
 
@@ -19,16 +19,28 @@ B<klog> [B<-x>] S<<< [B<-pr> <I<user name>>] >>> S<<< [B<-pa> <I<user's password
     [B<-pi>] [B<-si>] S<<< [B<-l> <I<ticket lifetime in hh[:mm[:ss]]>>] >>>
     [B<-se>] [B<-t>] [B<-h>]
 
+B<klog.krb> [B<-x>] S<<< [B<-principal> <I<user name>>] >>>
+    [-password <I<user's password>>] S<<< [B<-cell> <I<cell name>>] >>>
+    S<<< [B<-servers> <I<explicit list of servers>>+] >>>
+    [B<-pipe>] [B<-silent>]
+    S<<< [B<-lifetime> <I<ticket lifetime in hh[:mm[:ss]]>>] >>>
+    [B<-setpag>] [B<-tmp>] [B<-help>]
+
 =for html
 </div>
 
 =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
@@ -49,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) must 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.
@@ -140,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
@@ -265,7 +285,7 @@ encountered.
 Requests a specific lifetime for the token. Provide a number of hours and
 optionally minutes and seconds in the format I<hh>[B<:>I<mm>[B<:>I<ss>]].
 The value is used in calculating the token lifetime as described in
-L<DESCRIPTION>.
+L</DESCRIPTION>.
 
 =item B<-setpag>
 
@@ -305,7 +325,7 @@ Kerberos-style ticket file was created:
 
 Most often, this command is issued without arguments. The appropriate
 password is for the person currently logged into the local system. The
-ticket's lifetime is calculated as described in L<DESCRIPTION> (if no
+ticket's lifetime is calculated as described in L</DESCRIPTION> (if no
 defaults have been changed, it is 25 hours for a user whose Authentication
 Database entry was created in AFS 3.1 or later).
 
@@ -321,7 +341,7 @@ Corporation's test cell:
 In the following, the issuer requests a ticket lifetime of 104 hours 30
 minutes (4 days 8 hours 30 minutes). Presuming that this lifetime is
 allowed by the maximum ticket lifetimes and other factors described in
-L<DESCRIPTION>, the token's lifetime is 110:44:28, which is the next
+L</DESCRIPTION>, the token's lifetime is 110:44:28, which is the next
 largest possible value.
 
    % klog -lifetime 104:30