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