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