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