doc/man-pages/pod1/aklog.pod

   1 =head1 NAME
   2
   3 aklog - Obtain tokens for authentication to AFS
   4
   5 =head1 SYNOPSIS
   6
   7 =for html
   8 <div class="synopsis">
   9
  10 B<aklog> [B<-d>] [B<-hosts>] [B<-zsubs>] [B<-noprdb>] [B<-noauth>] [B<-linked>]
  11     [B<-force>] [B<-524>] [B<-setpag>]
  12     S<<< [[B<-cell> | B<-c>] <I<cell>> [B<-k> <I<Kerberos realm>>]]+ >>>
  13
  14 B<aklog> [B<-d>] [B<-hosts>] [B<-zsubs>] [B<-noprdb>] [B<-noauth>] [B<-linked>]
  15     [B<-force>] [B<-524>] [B<-setpag>] [B<-path> | B<-p>] <I<path>>+
  16
  17 =for html
  18 </div>
  19
  20 =head1 DESCRIPTION
  21
  22 The B<aklog> program authenticates to a cell in AFS by obtaining AFS
  23 tokens.  If B<aklog> is invoked with no command-line arguments, it will
  24 obtain tokens for the workstation's local cell.  It may be invoked with an
  25 arbitrary number of cells and pathnames to obtain tokens for multiple
  26 cells.  B<aklog> knows how to expand cell name abbreviations, so cells can
  27 be referred to by enough letters to make the cell name unique among the
  28 cells the workstation knows about.
  29
  30 B<aklog> obtains tokens by obtaining a Kerberos service ticket for the AFS
  31 service and then storing it as a token.  By default, it obtains that
  32 ticket from the realm corresponding to that cell (the upcase version of
  33 the cell name), but a different realm for a particular cell can be
  34 specified with B<-k>.  B<-k> cannot be used in B<-path> mode (see below).
  35
  36 =head1 OPTIONS
  37
  38 =over 4
  39
  40 =item B<-524>
  41
  42 Normally, B<aklog> generates native K5 tokens.  This flag tells B<aklog>
  43 to instead use the krb524 translation service to generate K4 or rxkad2b
  44 tokens, which may be necessary for AFS cells that don't support native K5
  45 tokens.  Support for native K5 tokens were added in OpenAFS 1.2.8.
  46
  47 =item B<-cell> <I<cell>>, B<-c> <I<cell>>
  48
  49 This flag tells B<aklog> that the next argument is the name of a cell to
  50 authenticate to.  It normally isn't necessary; B<aklog> normally
  51 determines whether an argument is a cell or a path name based on whether
  52 it contains C</> or is C<.> or C<..>.  The cell may be followed by B<-k>
  53 to specify the corresponding Kerberos realm.
  54
  55 =item B<-d>
  56
  57 Turns on printing of debugging information.  This option is not intended
  58 for general users.
  59
  60 =item B<-force>
  61
  62 Normally, aklog will not replace tokens with new tokens that appear to be
  63 identical.  If this flag is given, it will skip that check.
  64
  65 =item B<-hosts>
  66
  67 Prints all the server addresses which may act as a single point of
  68 failure in accessing the specified directory path.  Each element of the
  69 path is examined, and as new volumes are traversed, if they are not
  70 replicated, the server's IP address containing the volume will be
  71 displayed.  The output is of the form:
  72
  73     host: <ip-address>
  74
  75 This option is only useful in combination with paths as arguments rather
  76 than cells.
  77
  78 =item B<-k> <I<Kerberos realm>>
  79
  80 This flag is valid only immediately after the name of the cell.  It tells
  81 B<aklog> to use that Kerberos realm when authenticating to the preceding
  82 cell.  By default, B<aklog> will use the realm (per the local Kerberos
  83 configuration) of the first database server in the cell, so this flag
  84 normally won't be necessary.
  85
  86 =item B<-linked>
  87
  88 If the AFS cell is linked to a DCE cell, get tokens for both.
  89
  90 =item B<-noauth>
  91
  92 Don't actually authenticate, just do everything else B<aklog> does up to
  93 setting tokens.
  94
  95 =item B<-noprdb>
  96
  97 Ordinarily, B<aklog> looks up the AFS ID corresponding to the name of the
  98 person invoking the command, and if the user doesn't exist and the cell is
  99 a foreign one, attempts automatic registration of the user with the remote
 100 cell.  Specifying this flag turns off this functionality.  This may be
 101 desirable if the protection database is unavailable for some reason and
 102 tokens are desired anyway, or if one wants to disable user registration.
 103
 104 =item B<-path> <I<pathname>>, B<-p> <I<pathname>>
 105
 106 This flag tells B<aklog> that the next argument is a path in AFS.
 107 B<aklog> will walk that path and obtain tokens for every cell needed to
 108 access all of the directories.  Normally, this flag isn't necessary;
 109 B<aklog> assumes an argument is a path if it contains C</> or is C<.> or
 110 C<..>.
 111
 112 =item B<-setpag>
 113
 114 When setting tokens, attempt to put the parent process in a new PAG.  This
 115 is usually used as part of the login process but can be used any time to
 116 create a new AFS authentication context.
 117
 118 =item B<-zsubs>
 119
 120 Prints out the Zephyr subscription information to get alerts regarding all
 121 of the file servers required to access a particular path.  The output is
 122 of the form:
 123
 124     zsub: <instance>
 125
 126 where <instance> is the instance of a class C<filsrv> Zephyr subscription.
 127
 128 =back
 129
 130 =head1 FILES
 131
 132 =over 4
 133
 134 =item F<~/.xlog>
 135
 136 If this file exists in the user's home directory, it should contain a list
 137 of AFS cells to which to authenticate, one per line.  If B<aklog> is
 138 invoked without any options, it will attempt to obtain tokens in every
 139 cell listed in this file if it exists, rather than only obtaining tokens
 140 for the local cell.
 141
 142 =back
 143
 144 =head1 EXIT CODES
 145
 146 The exit status of B<aklog> will be one of the following:
 147
 148 =over 3
 149
 150 =item 0
 151
 152 Success -- No error occurred.
 153
 154 =item 1
 155
 156 Usage -- Bad command syntax; accompanied by a usage message.
 157
 158 =item 2
 159
 160 Something failed -- More than one cell or pathname was given on the
 161 command line and at least one failure occurred.  A more specific error
 162 status is returned when only one directive is given.
 163
 164 =item 3
 165
 166 AFS -- Unable to get AFS configuration or unable to get information about
 167 a specific cell.
 168
 169 =item 4
 170
 171 Kerberos -- Unable to get tickets for authentication.
 172
 173 =item 5
 174
 175 Token -- Unable to get tokens.
 176
 177 =item 6
 178
 179 Bad pathname -- The path given was not a directory or lstat(2) failed on
 180 some component of the pathname.
 181
 182 =item 7
 183
 184 Miscellaneous -- An internal failure occurred.  For example, B<aklog>
 185 returns this if it runs out of memory.
 186
 187 =back
 188
 189 =head1 EXAMPLES
 190
 191 To get tokens for the local cell:
 192
 193     % aklog
 194
 195 To get tokens for the C<athena.mit.edu> cell:
 196
 197     % aklog athena.mit.edu
 198
 199 or
 200
 201     % aklog athena
 202
 203 The latter will work if you local cache manager already knows about the
 204 C<athena> cell.
 205
 206 To get tokens adequate to read F</afs/athena.mit.edu/user/p/potato>:
 207
 208     % aklog /afs/athena.mit.edu/user/p/potato
 209
 210 To get tokens for C<testcell.mit.edu> that is in a test Kerberos realm:
 211
 212     % aklog testcell.mit.edu -k TESTREALM.MIT.EDU
 213
 214 =head1 SEE ALSO
 215
 216 kinit(1), tokens(1), unlog(1)
 217
 218 =head1 AUTHOR
 219
 220 Manpage originally written by Emanuel Jay Berkenbilt (MIT-Project
 221 Athena).  Extensively modified by Russ Allbery <rra@stanford.edu>.
 222
 223 =head1 COPYRIGHT
 224
 225 Original manpage is copyright 1990, 1991 Massachusetts Institute of
 226 Technology.  All rights reserved.
 227
 228 Copyright 2006 Russ Allbery <rra@stanford.edu>.
 229
 230 Export of this software from the United States of America may require
 231 a specific license from the United States Government.  It is the
 232 responsibility of any person or organization contemplating export to
 233 obtain such a license before exporting.
 234
 235 WITHIN THAT CONSTRAINT, permission to use, copy, modify, and distribute
 236 this software and its documentation for any purpose and without fee is
 237 hereby granted, provided that the above copyright notice appear in all
 238 copies and that both that copyright notice and this permission notice
 239 appear in supporting documentation, and that the name of M.I.T. not be
 240 used in advertising or publicity pertaining to distribution of the
 241 software without specific, written prior permission.  Furthermore if you
 242 modify this software you must label your software as modified software and
 243 not distribute it in such a fashion that it might be confused with the
 244 original MIT software.  M.I.T. makes no representations about the
 245 suitability of this software for any purpose.  It is provided "as is"
 246 without express or implied warranty.
 247
 248 THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
 249 WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
 250 MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
 251
 252 =cut