DEVEL15-man-page-krb-varients-20090518

FIXES 124799
LICENSE IPL10

Install symlinks for the *.krb versions of klog, pagsh, and tokens to the
non-krb versions and add information about the *.krb versions to the
non-krb man pages.


(cherry picked from commit 798ffe54af)

doc/man-pages/Makefile.in

@@ -11,6 +11,8 @@ maintclean:
 html:
 	perl generate-html
 
+LINKEDPAGES = klog pagsh tokens
+
 dest:
 	chmod +x install-man
 	mkdir -p $(DEST)/man/man1 $(DEST)/man/man5 $(DEST)/man/man8
@@ -23,6 +25,11 @@ dest:
 	set -e; cd man8 && for M in *.8 ; do \
 	    ../install-man $$M $(DEST)/man/man8/$$M ; \
 	done
+	set -e; for M in ${LINKEDPAGES}; do \
+	    NEWPAGE=$(DEST)/man/man1/$$M.krb.1 ; \
+	    test -h ${NEWPAGE} || ln -s $$M.1 ${NEWPAGE} ; \
+	done
+
 
 install: $(MAN1) $(MAN8)
 	chmod +x install-man
@@ -37,3 +44,7 @@ install: $(MAN1) $(MAN8)
 	set -e; cd man8 && for M in *.8 ; do \
 	    ../install-man $$M $(DESTDIR)$(mandir)/man8/$$M ; \
 	done
+	set -e; for M in ${LINKEDPAGES}; do \
+	    NEWPAGE=$(DESTDIR)$(mandir)/man1/$$M.krb.1 ; \
+	    test -h ${NEWPAGE} || ln -s $$M.1 ${NEWPAGE} ; \
+	done

doc/man-pages/README

@@ -229,19 +229,8 @@ Known Problems
   don't just report the deficiency again, but any contributions towards
   fixing it are greatly appreciated.
 
-   * The following installed commands have no man pages:
-
-       klog.krb
-       pagsh.krb
-       tokens.krb
-
    * Add -noresolve to the documentation of all the vos commands.
 
-   * klog.krb, pagsh.krb, and tokens.krb need to be listed as alternative
-     names in the NAME line of the non-.krb man pages, links should be
-     installed on man page installation, and the behavior of pagsh.krb
-     should be documented in the pagsh man page.
-
    * Some of the documentation in fs getserverprefs needs minor updates to
      reflect what happens in the dynroot case.
 

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,6 +19,13 @@ 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>
 
@@ -54,7 +61,7 @@ Authentication Server 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,
+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>>

doc/man-pages/pod1/pagsh.pod

@@ -1,6 +1,6 @@
 =head1 NAME
 
-pagsh - Creates a new PAG
+pagsh, pagsh.krb - Creates a new PAG
 
 =head1 SYNOPSIS
 
@@ -9,6 +9,8 @@ pagsh - Creates a new PAG
 
 B<pagsh>
 
+B<pagsh.krb>
+
 =for html
 </div>
 
@@ -24,9 +26,9 @@ track each user.
 
 Any tokens acquired subsequently (presumably for other cells) become
 associated with the PAG, rather than with the user's UNIX UID.  This
-method for distinguishing users has two advantages.
+method for distinguishing users has two advantages:
 
-=over 4
+=over 2
 
 =item *
 
@@ -49,6 +51,13 @@ UID. Use of a PAG as an identifier eliminates that possibility.
 
 =back
 
+The (mostly obsolete) B<pagsh.krb> command is the same as B<pagsh> except
+that it also sets the KRBTKFILE environment variable, which controls the
+default Kerberos v4 ticket cache, to F</tmp/tktpI<X>> where I<X> is the
+number of the user's PAG.  This is only useful for AFS cells still using
+Kerberos v4 outside of AFS and has no effect for cells using Kerberos v5
+and B<aklog> or B<klog.krb5>.
+
 =head1 CAUTIONS
 
 Each PAG created uses two of the memory slots that the kernel uses to
@@ -98,6 +107,7 @@ None
 
 =head1 SEE ALSO
 
+L<aklog(1)>,
 L<fs_exportafs(1)>,
 L<klog(1)>,
 L<tokens(1)>

doc/man-pages/pod1/tokens.pod

@@ -1,6 +1,6 @@
 =head1 NAME
 
-tokens - Displays the issuer's tokens
+tokens, tokens.krb - Displays the issuer's tokens
 
 =head1 SYNOPSIS
 
@@ -11,16 +11,23 @@ B<tokens> [B<-help>]
 
 B<tokens> [B<-h>]
 
+B<tokens.krb> [B<-help>]
+
+B<tokens.krb> [B<-h>]
+
 =for html
 </div>
 
 =head1 DESCRIPTION
 
-The tokens command displays all tokens (tickets) cached on the local
+The B<tokens> command displays all tokens (tickets) cached on the local
 machine for the issuer. AFS server processes require that their clients
 present a token as evidence that they have authenticated in the server's
 local cell.
 
+The (mostly obsolete) B<tokens.krb> command is the same as B<tokens>
+except that it also displays the user's Kerberos v4 ticket cache.
+
 =head1 OPTIONS
 
 =over 4
@@ -37,7 +44,7 @@ ignored.
 The output lists one token for each cell in which the user is
 authenticated. The output indicates the
 
-=over 4
+=over 2
 
 =item *