From: Russ Allbery Date: Mon, 31 Jul 2006 18:49:31 +0000 (+0000) Subject: STABLE14-aklog-man-page-20060731 X-Git-Tag: openafs-stable-1_4_2b3~17 X-Git-Url: https://git.michaelhowe.org/gitweb/?a=commitdiff_plain;h=c99a7f176ca0dd0af13eee353a5e951db2385f95;p=packages%2Fo%2Fopenafs.git 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) --- diff --git a/doc/man-pages/pod1/aklog.pod b/doc/man-pages/pod1/aklog.pod new file mode 100644 index 000000000..aec8b0db0 --- /dev/null +++ b/doc/man-pages/pod1/aklog.pod @@ -0,0 +1,252 @@ +=head1 NAME + +aklog - Obtain tokens for authentication to AFS + +=head1 SYNOPSIS + +=for html +
+ +B [B<-d>] [B<-hosts>] [B<-zsubs>] [B<-noprdb>] [B<-noauth>] [B<-linked>] + [B<-force>] [B<-524>] [B<-setpag>] + S<<< [[B<-cell> | B<-c>] > [B<-k> >]]+ >>> + +B [B<-d>] [B<-hosts>] [B<-zsubs>] [B<-noprdb>] [B<-noauth>] [B<-linked>] + [B<-force>] [B<-524>] [B<-setpag>] [B<-path> | B<-p>] >+ + +=for html +
+ +=head1 DESCRIPTION + +The B program authenticates to a cell in AFS by obtaining AFS +tokens. If B 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 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 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 generates native K5 tokens. This flag tells B +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> >, B<-c> > + +This flag tells B that the next argument is the name of a cell to +authenticate to. It normally isn't necessary; B 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: + +This option is only useful in combination with paths as arguments rather +than cells. + +=item B<-k> > + +This flag is valid only immediately after the name of the cell. It tells +B to use that Kerberos realm when authenticating to the preceding +cell. By default, B 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 does up to +setting tokens. + +=item B<-noprdb> + +Ordinarily, B 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> >, B<-p> > + +This flag tells B that the next argument is a path in AFS. +B will walk that path and obtain tokens for every cell needed to +access all of the directories. Normally, this flag isn't necessary; +B 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: + +where is the instance of a class C 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 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 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 +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 cell: + + % aklog athena.mit.edu + +or + + % aklog athena + +The latter will work if you local cache manager already knows about the +C cell. + +To get tokens adequate to read F: + + % aklog /afs/athena.mit.edu/user/p/potato + +To get tokens for C 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 . + +=head1 COPYRIGHT + +Original manpage is copyright 1990, 1991 Massachusetts Institute of +Technology. All rights reserved. + +Copyright 2006 Russ Allbery . + +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 diff --git a/src/aklog/aklog.1 b/src/aklog/aklog.1 deleted file mode 100644 index bf1204381..000000000 --- a/src/aklog/aklog.1 +++ /dev/null @@ -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)