NAME

       aklog - Obtain tokens for authentication to AFS

SYNOPSIS

       aklog [-d] [-hosts] [-zsubs] [-noprdb] [-noauth] [-linked]
           [-force] [-524] [-setpag]
           [[-cell | -c] <cell> [-k <Kerberos realm>]]+

       aklog [-d] [-hosts] [-zsubs] [-noprdb] [-noauth] [-linked]
           [-force] [-524] [-setpag] [-path | -p] <path>+

DESCRIPTION

       The aklog program authenticates to a cell in AFS by obtaining AFS tokens using a Kerberos
       5 ticket. If 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.  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.

       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 uppercase version of the cell name), but a different realm for a particular
       cell can be specified with -k.  -k cannot be used in -path mode (see below).

       When a Kerberos 5 cross-realm trust is used, aklog looks up the AFS ID corresponding to
       the name (Kerberos principal) of the person invoking the command, and if the user doesn't
       exist and the system:authuser@FOREIGN.REALM PTS group exists, then it attempts automatic
       registration of the user with the foreign cell.  The user is then added to the
       system:authuser@FOREIGN.REALM PTS group if registration is successful.  Automatic
       registration in the foreign cell will fail if the group quota for the
       system:authuser@FOREIGN.REALM group is less than one.  Each automatic registration
       decrements the group quota by one.

       When using aklog, be aware that AFS uses the Kerberos v4 principal naming format, not the
       Kerberos v5 format, when referring to principals in PTS ACLs, UserList, and similar
       locations.  AFS will internally map Kerberos v5 principal names to the Kerberos v4 syntax
       by removing any portion of the instance after the first period (generally the domain name
       of a host principal), changing any "/" to ".", and changing an initial principal part of
       "host" to "rcmd".  In other words, to create a PTS entry for the Kerberos v5 principal
       "user/admin", refer to it as "user.admin", and for the principal "host/shell.example.com",
       refer to it as "rcmd.shell".

OPTIONS

       -524
           Normally, aklog generates native K5 tokens.  This flag tells 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.

       -cell <cell>, -c <cell>
           This flag tells aklog that the next argument is the name of a cell to authenticate to.
           It normally isn't necessary; aklog normally determines whether an argument is a cell
           or a path name based on whether it contains "/" or is "." or "..".  The cell may be
           followed by -k to specify the corresponding Kerberos realm.

       -d  Turns on printing of debugging information.  This option is not intended for general
           users.

       -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.

       -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.

       -k <Kerberos realm>
           This flag is valid only immediately after the name of the cell.  It tells aklog to use
           that Kerberos realm when authenticating to the preceding cell.  By default, 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.

       -linked
           If the AFS cell is linked to a DCE cell, get tokens for both.

       -noauth
           Don't actually authenticate, just do everything else aklog does up to setting tokens.

       -noprdb
           Ordinarily, aklog looks up the AFS ID corresponding to the name of the person invoking
           the command, and if the user doesn't exist, the cell is a foreign one, the
           system:authuser@FOREIGN.REALM PTS group exists, and has a positive group quota, then
           it attempts automatic registration of the user with the foreign 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.

       -path <pathname>, -p <pathname>
           This flag tells aklog that the next argument is a path in AFS.  aklog will walk that
           path and obtain tokens for every cell needed to access all of the directories.
           Normally, this flag isn't necessary; aklog assumes an argument is a path if it
           contains "/" or is "." or "..".

       -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.  Note that this in some cases relies on dangerous and tricky
           manipulations of kernel records and will not work on all platforms or with all Linux
           kernels.

       -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 "filsrv" Zephyr subscription.

ENVIRONMENT

       KRB5CCNAME
           As with most programs that use an existing Kerberos ticket cache, aklog can be told to
           use a cache other than the default by setting the environment variable KRB5CCNAME.  On
           UNIX and Linux systems, this variable is normally set to a file name, but may point to
           other types of caches.  See the documentation of your Kerberos implementation for more
           details.

FILES

       ~/.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 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.

EXIT CODES

       The exit status of aklog will be one of the following:

       0  Success -- No error occurred.

       1  Usage -- Bad command syntax; accompanied by a usage message.

       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.

       3  AFS -- Unable to get AFS configuration or unable to get information about a specific
          cell.

       4  Kerberos -- Unable to get tickets for authentication.

       5  Token -- Unable to get tokens.

       6  Bad pathname -- The path given was not a directory or lstat(2) failed on some component
          of the pathname.

       7  Miscellaneous -- An internal failure occurred.  For example, aklog returns this if it
          runs out of memory.

EXAMPLES

       To get tokens for the local cell:

           % aklog

       To get tokens for the "athena.mit.edu" cell:

           % aklog athena.mit.edu

       or

           % aklog athena

       The latter will work if you local cache manager already knows about the "athena" cell.

       To get tokens adequate to read /afs/athena.mit.edu/user/p/potato:

           % aklog /afs/athena.mit.edu/user/p/potato

       To get tokens for "testcell.mit.edu" that is in a test Kerberos realm:

           % aklog testcell.mit.edu -k TESTREALM.MIT.EDU

SEE ALSO

       kinit(1), tokens(1), unlog(1)

AUTHOR

       Manpage originally written by Emanuel Jay Berkenbilt (MIT-Project Athena).  Extensively
       modified by Russ Allbery <rra@stanford.edu>.

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.