--- /dev/null
+=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
+++ /dev/null
-.\"
-.\" $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)
git://git.openafs.org / openafs.git / commitdiff