mirror of
https://git.openafs.org/openafs.git
synced 2025-01-31 13:38:01 +00:00
STABLE14-aklog-man-page-20060731
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: 3; 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)
This commit is contained in:
Russ Allbery
Derrick Brashear
parent
6629b2af2c
commit
c99a7f176c
252
doc/man-pages/pod1/aklog.pod
Normal file
252
doc/man-pages/pod1/aklog.pod
Normal file
@ -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
|
||||
@ -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)
|
||||
Loading…
x
Reference in New Issue
Block a user