NAME

aklog - Obtain tokens for authentication to AuristorFS

SYNOPSIS

aklog [-d] [[-cell <cell>] [-k <Kerberos realm>]]+ [-path <path>]+ [-hosts] [-levels <security levels list>] [-noauth] [-noprdb] [-force] [-linked] [-principal <principal>] [-keytab <keytab_file>] [-cache <ccache_name>] [-524]

DESCRIPTION

The aklog program obtains Auristor authentication tokens using a cached Kerberos 5 ticket granting 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. When cells are locally configured in /etc/yfs/yfs-client.conf, cell names can be specified to aklog using a unique prefix.

aklog acquires the necessary Kerberos 5 service tickets and converts them into Auristor tokens. By default, the service tickets are obtained from the realm corresponding to that cell as determined by applying the Kerberos 5 library's host_to_realm function to the DNS name of the first entry in the location server list. The list of location servers is obtained from the local [cells] configuration or via DNS SRV (or AFSDB) queries. If no realm can be determined, Kerberos 5 KDC referrals are used. An alternative realm for a cell can be specified with -k. -k cannot be used in -path mode (see below).

If the Kerberos 5 principal's realm is not accepted as a local authentication realm by the cell, then a Kerberos 5 cross-realm trust is used and aklog looks up the Auristor ID corresponding to the Kerberos 5 ticket granting ticket's client principal. If an ID does not exist aklog attempts to register the Kerberos principal with the cell.

If the administrator of the cell has created the system:authuser@FOREIGN.REALM group in the protection database, then the user is then added to the group if registration is successful. Automatic registration will fail if the system:authuser@FOREIGN.REALM group does not exist or if adding a new member to the group would exceed the group's quota.

OPTIONS

-524

(deprecated) This flag forces aklog to use a krb524 translation service to generate tokens that are compatible with IBM AFS and OpenAFS servers that do not support native Kerberos 5 tokens.

-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

Enables debugging mode which generates output which can be used to identify the source of authentication failures.

-force

Normally, aklog will not replace tokens with new tokens that appear to be identical. This option is useful to force the cache manager to invalidate all network connections authenticated by the token. Forcing new connections will result in file servers re-evaluating the protection group memberships of the authenticated user and the client machine.

-hosts

(UNIX only) 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 -cell. It specifies the Kerberos realm used for authenticating local identities in the preceding cell. By default, aklog will automatically determine the realm of the cell (see DESCRIPTION).

-levels <security levels list>

This option specifies a comma-separated ordered list of one or more security levels: crypt, auth and clear. When supported by an RX security class, the list indicates the acceptable security levels and order of preference. The crypt level provides wire privacy and integrity protection. The auth level provides integrity protection but not wire privacy. The clear level provides neither wire privacy nor integrity protection. The default list is crypt,auth,clear.

The yfs-rxgk security class supports negotiated levels. The levels requested by the user are passed to the cell's RXGK service which compares them to service security policies prior to generating authentication tokens. By default, yfs-rxgk tokens are issued requiring the crypt mode. Use of an alternate security level requires both obtaining a token with the desired level and configuring the cache manager via fs setcrypt.

The rxkad and rxnull security classes ignore this option.

-linked

If the authenticated cell is linked to another 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 ID corresponding to the Kerberos 5 ticket granting ticket and stores it in the token description string, and if:

 * there is no matching ID
 * the cell is foreign (authenticated by a Kerberos 5 realm different from
   the ticket granting ticket)

then aklog attempts to register the authenticated entity in the cell's protection database.

The -noprdb flag turns off this functionality. This can be desirable when the protection database is unreachable in order to avoid waiting for a the network connection to timeout, or to disable the automatic registration.

-path <pathname>, -p <pathname>

This flag tells aklog that the next argument is a path in Auristor. 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 ...

-principal <principal>

Specifies the principal to be used for authentication. This can help in selecting the correct credentials cache when several are available in a cache collection.

-keytab <keytab_file>

Specifies a Kerberos v5 keytab file containing a key for the client principal specified by -principal.

-cache <ccache_name>

Specifies the Kerberos v5 credential cache or cache collection to be used for authentication. This option can be used when the KRB5CCNAME environment variable cannot be read by the Kerberos v5 library via secure_getenv().

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. This variable is a valid credential cache name of the form <type>:<name>. When using a file based credential cache set the value to path or FILE:path. Windows users can also specify MSLSA: or API:principal. See the documentation of your Kerberos implementation for additional credential cache options.

FILES

~/.xlog

(UNIX only) If this file exists in the user's home directory, it should contain a list of Auristor 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

Auristor -- Unable to get Auristor 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 your-cell-name.com cell:

    % aklog your-cell-name.com

or

    % aklog your

The latter will work if the local cache manager knows about the your cell.

To get tokens to read /afs/your-cell-name.com/user/p/potato:

    % aklog /afs/your-cell-name.com/user/p/potato

To get tokens for foreign-cell-name.com that uses the FOREIGN-REALM.COM Kerberos realm for authentication:

    % aklog foreign-cell-name.com -k FOREIGN-REALM.COM

SEE ALSO

fs_setcrypt(1), 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.

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

ACKNOWLEDGEMENTS

"AFS" is a registered mark of International Business Machines Corporation, used under license. (USPTO Registration 1598389)

"OpenAFS" is a registered mark of International Business Machines Corporation. (USPTO Registration 4577045)

The "AuriStor" name, log 'S' brand mark, and icon are registered marks of AuriStor, Inc. (USPTO Registrations 4849419, 4849421, and 4928460) (EUIPO Registration 015539653).

"Your File System" is a registered mark of AuriStor, Inc. (USPTO Registrations 4801402 and 4849418).

"YFS" and "AuriStor File System" are trademarks of AuriStor, Inc.