DEVEL15-aklog-man-page-20060731
authorRuss Allbery <rra@stanford.edu>
Mon, 31 Jul 2006 18:51:28 +0000 (18:51 +0000)
committerDerrick Brashear <shadow@dementia.org>
Mon, 31 Jul 2006 18:51:28 +0000 (18:51 +0000)
Rewrite the aklog man page in POD and add documentation of the new flags
and .xlog.

RCS file: /cvs/openafs/src/aklog/Attic/aklog.1,v
Working file: src/aklog/aklog.1
head: 1.2
branch:
locks: strict
access list:
keyword substitution: kv
total revisions: 4; selected revisions: 0
description:

====================
This delta was composed from multiple commits as part of the CVS->Git migration.
The checkin message with each commit was inconsistent.
The following are the additional commit messages.
====================

Fix unterminated B<>.

(cherry picked from commit 5f434b8087d3c73123860f853d15a0f51c03bf73)

doc/man-pages/pod1/aklog.pod [new file with mode: 0644]
src/aklog/aklog.1 [deleted file]

diff --git a/doc/man-pages/pod1/aklog.pod b/doc/man-pages/pod1/aklog.pod
new file mode 100644 (file)
index 0000000..aec8b0d
--- /dev/null
@@ -0,0 +1,252 @@
+=head1 NAME
+
+aklog - Obtain tokens for authentication to AFS
+
+=head1 SYNOPSIS
+
+=for html
+<div class="synopsis">
+
+B<aklog> [B<-d>] [B<-hosts>] [B<-zsubs>] [B<-noprdb>] [B<-noauth>] [B<-linked>]
+    [B<-force>] [B<-524>] [B<-setpag>]
+    S<<< [[B<-cell> | B<-c>] <I<cell>> [B<-k> <I<Kerberos realm>>]]+ >>>
+
+B<aklog> [B<-d>] [B<-hosts>] [B<-zsubs>] [B<-noprdb>] [B<-noauth>] [B<-linked>]
+    [B<-force>] [B<-524>] [B<-setpag>] [B<-path> | B<-p>] <I<path>>+
+
+=for html
+</div>
+
+=head1 DESCRIPTION
+
+The B<aklog> program authenticates to a cell in AFS by obtaining AFS
+tokens.  If B<aklog> is invoked with no command-line arguments, it will
+obtain tokens for the workstation's local cell.  It may be invoked with an
+arbitrary number of cells and pathnames to obtain tokens for multiple
+cells.  B<aklog> knows how to expand cell name abbreviations, so cells can
+be referred to by enough letters to make the cell name unique among the
+cells the workstation knows about.
+
+B<aklog> obtains tokens by obtaining a Kerberos service ticket for the AFS
+service and then storing it as a token.  By default, it obtains that
+ticket from the realm corresponding to that cell (the upcase version of
+the cell name), but a different realm for a particular cell can be
+specified with B<-k>.  B<-k> cannot be used in B<-path> mode (see below).
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-524>
+
+Normally, B<aklog> generates native K5 tokens.  This flag tells B<aklog>
+to instead use the krb524 translation service to generate K4 or rxkad2b
+tokens, which may be necessary for AFS cells that don't support native K5
+tokens.  Support for native K5 tokens were added in OpenAFS 1.2.8.
+
+=item B<-cell> <I<cell>>, B<-c> <I<cell>>
+
+This flag tells B<aklog> that the next argument is the name of a cell to
+authenticate to.  It normally isn't necessary; B<aklog> normally
+determines whether an argument is a cell or a path name based on whether
+it contains C</> or is C<.> or C<..>.  The cell may be followed by B<-k>
+to specify the corresponding Kerberos realm.
+
+=item B<-d>
+
+Turns on printing of debugging information.  This option is not intended
+for general users.
+
+=item B<-force>
+
+Normally, aklog will not replace tokens with new tokens that appear to be
+identical.  If this flag is given, it will skip that check.
+
+=item B<-hosts>
+
+Prints all the server addresses which may act as a single point of
+failure in accessing the specified directory path.  Each element of the
+path is examined, and as new volumes are traversed, if they are not
+replicated, the server's IP address containing the volume will be
+displayed.  The output is of the form:
+
+    host: <ip-address>
+
+This option is only useful in combination with paths as arguments rather
+than cells.
+
+=item B<-k> <I<Kerberos realm>>
+
+This flag is valid only immediately after the name of the cell.  It tells
+B<aklog> to use that Kerberos realm when authenticating to the preceding
+cell.  By default, B<aklog> will use the realm (per the local Kerberos
+configuration) of the first database server in the cell, so this flag
+normally won't be necessary.
+
+=item B<-linked>
+
+If the AFS cell is linked to a DCE cell, get tokens for both.
+
+=item B<-noauth>
+
+Don't actually authenticate, just do everything else B<aklog> does up to
+setting tokens.
+
+=item B<-noprdb>
+
+Ordinarily, B<aklog> looks up the AFS ID corresponding to the name of the
+person invoking the command, and if the user doesn't exist and the cell is
+a foreign one, attempts automatic registration of the user with the remote
+cell.  Specifying this flag turns off this functionality.  This may be
+desirable if the protection database is unavailable for some reason and
+tokens are desired anyway, or if one wants to disable user registration.
+
+=item B<-path> <I<pathname>>, B<-p> <I<pathname>>
+
+This flag tells B<aklog> that the next argument is a path in AFS.
+B<aklog> will walk that path and obtain tokens for every cell needed to
+access all of the directories.  Normally, this flag isn't necessary;
+B<aklog> assumes an argument is a path if it contains C</> or is C<.> or
+C<..>.
+
+=item B<-setpag>
+
+When setting tokens, attempt to put the parent process in a new PAG.  This
+is usually used as part of the login process but can be used any time to
+create a new AFS authentication context.
+
+=item B<-zsubs>
+
+Prints out the Zephyr subscription information to get alerts regarding all
+of the file servers required to access a particular path.  The output is
+of the form:
+
+    zsub: <instance>
+
+where <instance> is the instance of a class C<filsrv> Zephyr subscription.
+
+=back
+
+=head1 FILES
+
+=over 4
+
+=item F<~/.xlog>
+
+If this file exists in the user's home directory, it should contain a list
+of AFS cells to which to authenticate, one per line.  If B<aklog> is
+invoked without any options, it will attempt to obtain tokens in every
+cell listed in this file if it exists, rather than only obtaining tokens
+for the local cell.
+
+=back
+
+=head1 EXIT CODES
+
+The exit status of B<aklog> will be one of the following:
+
+=over 3
+
+=item 0
+
+Success -- No error occurred.
+
+=item 1
+
+Usage -- Bad command syntax; accompanied by a usage message.
+
+=item 2
+
+Something failed -- More than one cell or pathname was given on the
+command line and at least one failure occurred.  A more specific error
+status is returned when only one directive is given.
+
+=item 3
+
+AFS -- Unable to get AFS configuration or unable to get information about
+a specific cell.
+
+=item 4
+
+Kerberos -- Unable to get tickets for authentication.
+
+=item 5
+
+Token -- Unable to get tokens.
+
+=item 6
+
+Bad pathname -- The path given was not a directory or lstat(2) failed on
+some component of the pathname.
+
+=item 7
+
+Miscellaneous -- An internal failure occurred.  For example, B<aklog>
+returns this if it runs out of memory.
+
+=back
+
+=head1 EXAMPLES
+
+To get tokens for the local cell:
+
+    % aklog
+
+To get tokens for the C<athena.mit.edu> cell:
+
+    % aklog athena.mit.edu
+
+or
+
+    % aklog athena
+
+The latter will work if you local cache manager already knows about the
+C<athena> cell.
+
+To get tokens adequate to read F</afs/athena.mit.edu/user/p/potato>:
+
+    % aklog /afs/athena.mit.edu/user/p/potato
+
+To get tokens for C<testcell.mit.edu> that is in a test Kerberos realm:
+
+    % aklog testcell.mit.edu -k TESTREALM.MIT.EDU
+
+=head1 SEE ALSO
+
+kinit(1), tokens(1), unlog(1)
+
+=head1 AUTHOR
+
+Manpage originally written by Emanuel Jay Berkenbilt (MIT-Project
+Athena).  Extensively modified by Russ Allbery <rra@stanford.edu>.
+
+=head1 COPYRIGHT
+
+Original manpage is copyright 1990, 1991 Massachusetts Institute of
+Technology.  All rights reserved.
+
+Copyright 2006 Russ Allbery <rra@stanford.edu>.
+
+Export of this software from the United States of America may require
+a specific license from the United States Government.  It is the
+responsibility of any person or organization contemplating export to
+obtain such a license before exporting.
+
+WITHIN THAT CONSTRAINT, permission to use, copy, modify, and distribute
+this software and its documentation for any purpose and without fee is
+hereby granted, provided that the above copyright notice appear in all
+copies and that both that copyright notice and this permission notice
+appear in supporting documentation, and that the name of M.I.T. not be
+used in advertising or publicity pertaining to distribution of the
+software without specific, written prior permission.  Furthermore if you
+modify this software you must label your software as modified software and
+not distribute it in such a fashion that it might be confused with the
+original MIT software.  M.I.T. makes no representations about the
+suitability of this software for any purpose.  It is provided "as is"
+without express or implied warranty.
+
+THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
+WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
+MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+
+=cut
diff --git a/src/aklog/aklog.1 b/src/aklog/aklog.1
deleted file mode 100644 (file)
index bf12043..0000000
+++ /dev/null
@@ -1,189 +0,0 @@
-.\" 
-.\" $Id$
-.\"
-.\" Copyright 1990,1991 by the Massachusetts Institute of Technology
-.\" For distribution and copying rights, see the file "mit-copyright.h"
-.\"
-.TH AKLOG 1 "August 1, 1990"
-.UC 4
-.SH NAME
-aklog \- Obtain tokens for authentication to AFS
-
-.SH SYNOPSIS
-.B aklog 
-[ 
-.B \-d 
-] [ 
-.B \-hosts
-] [ 
-.B \-zsubs 
-] [ 
-.B \-noprdb 
-] [ [
-.B \-cell | \-c 
-] cell [
-.B \-k 
-kerberos-realm
-] ] [ [ 
-.B \-path | \-p 
-] pathname ]
-
-.SH DESCRIPTION
-The 
-.I aklog
-program is used to authenticate to a cell or directory in 
-.I AFS,
-the Andrew Filesystem, by obtaining AFS 
-.I tokens.  
-Ordinarily, aklog is not used directly but called by
-.IR attach (1).
-
-If 
-.I aklog
-is invoked with no command line arguments, it will obtain tokens 
-for the workstation's local cell.  It is possible to invoke
-.I aklog
-with arbitrarily many cells and pathnames
-specified on the command line.  
-.I aklog 
-knows how to expand cell name abbreviations, so short
-forms of cell names can be use used.  In addition, 
-.I aklog
-understands the following command line options:
-
-.TP 4 
-.B  \-cell | \-c \fRcell
-This flag is not ordinarily necessary since 
-.I aklog
-can usually figure out when an argument is a cell.  It can be
-used to introduce a cell name that would ordinarily be mistaken
-for a path name if this should be required.  If this flag is
-omitted, an argument will be treated as a cell name if it
-contains no slashes (/) and is neither "." nor ".." .
-
-.TP
-.B \-k \fRkerberos-realm
-This flag is valid only when immediately following the name of a
-cell.  It is used to tell 
-.I aklog
-what kerberos realm should be used while authenticating to the
-preceding cell.  This argument is unnecessary except when the
-workstation is not properly configured.  Ordinarily, 
-.I aklog
-can determine this information on its own.
-
-.TP
-.B \-path | \-p \fRpathname
-Like the \-cell flag, this flag is usually unnecessary.  When it
-appears, the next command line argument is always treated as a
-path name.  Ordinarily, an argument is treated as a path name
-if it is "." or ".." or if it contains a slash (/).  
-
-.TP
-.B \-hosts
-Prints all the server addresses which may act as a single point of
-failure in accessing the specified directory path.  Each element of the
-path is examined, and as new volumes are traversed, if they are not
-replicated, the server's IP address containing the volume will be
-displayed.
-.IR Attach (1)
-invokes 
-.I aklog
-with this option.  The output is of the form
-
-host: 
-.I IP address
-
-.TP
-.B \-zsubs
-Causes the printing of the zephyr subscription information that a
-person using a given path or cell would want.  
-.IR Attach (1)
-invokes 
-.I aklog
-with this option.  The output is of the form
-
-zsub: 
-.I instance
-
-where 
-.I instance
-is the instance of a class filsrv zephyr subscription.
-
-.TP
-.B \-noprdb
-Ordinarily, aklog looks up the AFS ID corresponding to the name
-of the person invoking the command.  Specifying this flag turns
-off this functionality.  This may be desirable if the protection
-database is unavailable for some reason and tokens are desired
-anyway.  
-
-.TP
-.B \-d
-Turns on printing of debugging information.  This option is not
-intended for general users.
-
-.SH EXIT CODES
-The exit status of
-.I aklog
-will be one of the following:
-.TP 5
-0
-Success -- No error occurred.
-.TP 5
-1
-Usage -- Bad command syntax; accompanied by a usage message.
-.TP 5
-2
-Something failed -- More than one cell or pathname was given on
-the command line and at least one failure occurred.
-A more specific error status is returned when only one directive
-is given.
-.TP 5
-3
-AFS -- Unable to get AFS configuration or unable to get
-information about a specific cell.
-.TP 5
-4
-Kerberos -- Unable to get tickets for authentication.
-.TP 5
-5
-Token -- Unable to get tokens.
-.TP 5
-6
-Bad pathname -- The path given was not a directory or 
-.I lstat(2)
-failed on some component of the pathname.
-.TP 5
-7
-Miscellaneous -- An internal failure occurred.  For example, 
-.I aklog
-returns this if it runs out of memory.
-
-.SH EXAMPLES
-.br
-To get tokens for the local cell:
-.br
-% aklog
-
-To get tokens for the athena.mit.edu cell:
-.br
-% aklog athena.mit.edu
-.br
-or
-.br
-% aklog athena
-
-To get tokens adequate to read /afs/athena.mit.edu/user/p/potato:
-.br
-% aklog /afs/athena.mit.edu/user/p/potato
-
-To get tokens for a test cell that is in a test Kerberos realm:
-.br
-% aklog testcell.mit.edu -k TESTREALM.MIT.EDU
-
-.SH SEE ALSO
-attach(1), tokens(1), unlog(1)
-
-.SH AUTHOR
-Emanuel Jay Berkenbilt (MIT-Project Athena)