aklog - Obtain tokens for authentication to AFS
] [ -linked
] [ -linked
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.
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
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
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,
, 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
mapping of Kerberos v5 principal to Kerberos v4 principal and
the determination that a Kerberos realm is foreign is performed in the absence
of the actual AFS server configuration. If the aklog
Kerberos v5 principal to Kerberos v4 principal or the foreign realm
determination is wrong, the PTS name-to-id lookup will produce the wrong AFS
ID for the user. The AFS ID is only used for display purposes and should not
be trusted. Use the -noprdb
switch to disable the PTS name-to-id
- 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
- -cell <cell>, -c
- 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.
- Turns on printing of debugging information. This option is
not intended for general users.
- Normally, aklog will not replace tokens with new tokens
that appear to be identical. If this flag is given, it will skip that
- 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:
This option is only useful in combination with paths as arguments rather
- -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.
- If the AFS cell is linked to a DCE cell, get tokens for
- Don't actually authenticate, just do everything else
aklog does up to setting tokens.
- 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
- 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 "..".
- 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.
- 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:
where <instance> is the instance of a class "filsrv" Zephyr
- 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
- 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.
The exit status of aklog
will be one of the following:
- Success -- No error occurred.
- Usage -- Bad command syntax; accompanied by a usage
- 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.
- AFS -- Unable to get AFS configuration or unable to get
information about a specific cell.
- Kerberos -- Unable to get tickets for authentication.
- Token -- Unable to get tokens.
- Bad pathname -- The path given was not a directory or
lstat(2) failed on some component of the pathname.
- Miscellaneous -- An internal failure occurred. For example,
aklog returns this if it runs out of memory.
To get tokens for the local cell:
To get tokens for the "athena.mit.edu" cell:
% aklog athena.mit.edu
% aklog athena
The latter will work if you local cache manager already knows about the
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
Manpage originally written by Emanuel Jay Berkenbilt (MIT-Project Athena).
Extensively modified by Russ Allbery <firstname.lastname@example.org>.
Original manpage is copyright 1990, 1991 Massachusetts Institute of Technology.
All rights reserved.
Copyright 2006 Russ Allbery <email@example.com>.
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
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.