klog.krb5 -lifetime is not implemented
[openafs.git] / doc / man-pages / pod1 / klog.krb5.pod
1 =head1 NAME
2
3 klog.krb5 - Authenticates to Kerberos and obtains a token
4
5 =head1 SYNOPSIS
6
7 =for html
8 <div class="synopsis">
9
10 B<klog.krb5> [B<-x>] S<<< [B<-principal> <I<user name>>] >>>
11     [-password <I<user's password>>] S<<< [B<-cell> <I<cell name>>] >>>
12     S<<< [B<-k> <I<realm>>] >>> [B<-pipe>] [B<-silent>]
13     S<<< [B<-lifetime> <I<ticket lifetime in hh[:mm[:ss]]>>] >>>
14     [B<-setpag>] [B<-tmp>] [B<-noprdb>] [B<-unwrap>] [B<-help>]
15
16 B<klog.krb5> [B<-x>] S<<< [B<-pr> <I<user name>>] >>>
17     S<<< [B<-pa> <I<user's password>>] >>>
18     S<<< [B<-c> <I<cell name>>] >>>
19     B<<< [B<-k> <I<realm>>] >>> [B<-pi>] [B<-si>]
20     S<<< [B<-l> <I<ticket lifetime in hh[:mm[:ss]]>>] >>>
21     [B<-se>] [B<-t>] [B<-n>] [B<-u>] [B<-h>]
22
23 =for html
24 </div>
25
26 =head1 DESCRIPTION
27
28 The B<klog.krb5> command obtains a Kerberos v5 ticket from a Kerberos
29 KDC and, from the ticket, an AFS token and then stores it in the Cache
30 Manager.  The Cache Manager keeps the token in kernel memory and uses it
31 when obtaining authenticated access to the AFS filespace.  This command
32 does not affect the issuer's identity (UNIX UID) on the local file system.
33
34 By default, the command interpreter obtains a token for the AFS user name
35 that matches the issuer's local user name.  To specify an alternate user,
36 include the B<-principal> argument.  The user named by the B<-principal>
37 argument does not have to appear in the local password file (the
38 F</etc/passwd> file or equivalent).
39
40 By default, the command interpreter obtains a token for the local cell, as
41 defined by the AFSCELL environment variable set in the command shell or by
42 the F</usr/vice/etc/ThisCell> file on the local machine.  To specify an
43 alternate cell, include the B<-cell> argument.  A user can have tokens in
44 multiple cells simultaneously, but only one token per cell per connection
45 to the client machine.  If the user's credential structure already
46 contains a token for the requested cell, the token resulting from this
47 command replaces it.
48
49 By default, the command interpreter obtains a Kerberos ticket for the
50 local realm.  To specify a different Kerberos realm, include the B<-k>
51 argument.  The Kerberos realm name need not match the AFS cell name.
52 B<klog.krb5> will request a ticket for the principal C<afs/I<cell>> where
53 I<cell> is the cell name for which the user is requesting tokens, falling
54 back on the principal C<afs> if that principal does not work.
55
56 The lifetime of the token resulting from this command is the smallest of
57 the following:
58
59 =over 4
60
61 =item *
62
63 The maximum ticket lifetime recorded for the C<afs/I<cell>> principal in
64 thet Kerberos database.
65
66 =item *
67
68 The maximum ticket lifetime recorded in the specified user's Kerberos
69 database entry.
70
71 =back
72
73 =head1 CAUTIONS
74
75 By default, this command does not create a new process authentication
76 group (PAG); see the description of the B<pagsh> command to learn about
77 PAGs.  If a cell does not use an AFS-modified login utility, users must
78 include B<-setpag> option to this command, or issue the B<pagsh> command
79 before this one, to have their tokens stored in a credential structure
80 that is identified by PAG rather than by local UID.  Users should be aware
81 that B<-setpag> will not work on some systems, most notably recent Linux
82 systems, and using B<pagsh> is preferrable and more reliable.
83
84 When a credential structure is identified by local UID, the potential
85 security exposure is that the local superuser C<root> can use the UNIX
86 B<su> command to assume any other identity and automatically inherit the
87 tokens associated with that UID.  Identifying the credential structure by
88 PAG makes it more difficult (but not impossible) for the local superuser
89 to obtain tokens of other users.
90
91 If the B<-password> argument is used, the specified password cannot begin
92 with a hyphen, because it is interpreted as another option name.  Use of
93 the B<-password> argument is not recommended in any case.
94
95 By default, it is possible to issue this command on a properly configured
96 NFS client machine that is accessing AFS via the NFS/AFS Translator,
97 assuming that the NFS client machine is a supported system type. However,
98 if the translator machine's administrator has enabled UID checking by
99 including the B<-uidcheck on> argument to the B<fs exportafs> command, the
100 command fails with an error message similar to the following:
101
102    Warning: Remote pioctl to <translator_machine> has failed (err=8). . .
103    Unable to authenticate to AFS because a pioctl failed.
104
105 Enabling UID checking means that the credential structure in which tokens
106 are stored on the translator machine must be identified by a UID that
107 matches the local UID of the process that is placing the tokens in the
108 credential structure.  After the B<klog.krb5> command interpreter obtains
109 the token on the NFS client, it passes it to the remote executor daemon on
110 the translator machine, which makes the system call that stores the token
111 in a credential structure on the translator machine.  The remote executor
112 generally runs as the local superuser C<root>, so in most cases its local
113 UID (normally zero) does not match the local UID of the user who issued
114 the B<klog.krb5> command on the NFS client machine.
115
116 Issuing the B<klog.krb5> command on an NFS client machine creates a
117 security exposure: the command interpreter passes the token across the
118 network to the remote executor daemon in clear text mode.
119
120 =head1 OPTIONS
121
122 =over 4
123
124 =item B<-x>
125
126 Appears only for backwards compatibility.  Its former function is now the
127 default behavior of this command.
128
129 =item B<-principal> <I<user name>>
130
131 Specifies the user name to authenticate.  If this argument is omitted, the
132 default value is the local user name.
133
134 =item B<-password> <I<user's password>>
135
136 Specifies the issuer's password (or that of the alternate user identified
137 by the B<-principal> argument).  Omit this argument to have the command
138 interpreter prompt for the password, in which case it does not echo
139 visibly in the command shell.
140
141 =item B<-cell> <I<cell name>>
142
143 Specifies the cell for which to obtain a token.  During a single login
144 session on a given machine, a user can be authenticated in multiple cells
145 simultaneously, but can have only one token at a time for each of them
146 (that is, can only authenticate under one identity per cell per session on
147 a machine).  It is acceptable to abbreviate the cell name to the shortest
148 form that distinguishes it from the other cells listed in the
149 F</usr/vice/etc/CellServDB> file on the client machine on which the
150 command is issued.
151
152 If this argument is omitted, the command is executed in the local cell, as
153 defined
154
155 =over 4
156
157 =item *
158
159 First, by the value of the environment variable AFSCELL.
160
161 =item *
162
163 Second, in the F</usr/vice/etc/ThisCell> file on the client machine on
164 which the command is issued.
165
166 =back
167
168 =item B<-k> <I<realm>>
169
170 Obtain tickets and tokens from the <I<realm>> Kerberos realm.  If this
171 option is not given, B<klog.krb5> defaults to using the default local
172 realm.  The Kerberos realm name need not match the AFS cell name.
173
174 =item B<-pipe>
175
176 Suppresses all output to the standard output stream, including prompts and
177 error messages. The B<klog.krb5> command interpreter expects to receive
178 the password from the standard input stream. Do not use this argument; it
179 is designed for use by application programs rather than human users.
180
181 =item B<-silent>
182
183 Suppresses some of the trace messages that the B<klog.krb5> command
184 produces on the standard output stream by default.  It still reports on
185 major problems encountered.
186
187 =item B<-lifetime> <I<ticket lifetime>
188
189 This option is not implemented by B<klog.krb5> and has no effect.
190
191 =item B<-setpag>
192
193 Creates a process authentication group (PAG) prior to requesting
194 authentication. The token is associated with the newly created PAG.
195
196 =item B<-tmp>
197
198 Creates a Kerberos-style ticket file rather than only obtaining tokens.
199 The ticket file will be stored in the default Kerberos ticket cache
200 location, which is usually in the F</tmp> directory of the local machine
201 (but depends on the Kerberos implementation used).
202
203 =item B<-noprdb>
204
205 By default, B<klog.krb5> looks up the user's AFS ID in the Protection
206 Server and associates the token with that AFS ID.  This is helpful when
207 looking at the output of commands like B<tokens> but is not required.  If
208 this option is given, this behavior is suppressed and B<klog.krb5> will
209 store the token under a generic name.  You may wish this if, for example,
210 you have problems contacting the Protection Server for an AFS cell for
211 some reason.
212
213 =item B<-unwrap>
214
215 Normally, B<klog.krb5> uses the Kerberos service ticket for the AFS
216 principal as the AFS token.  If this option is given, B<klog.krb5> creates
217 a different, simplified AFS token form based on the service ticket (the
218 so-called "rxkad 2b" token).  Normally, this is not necessary.  However,
219 if you are using older OpenAFS software that cannot handle large ticket
220 sizes in conjunction with Active Directory as the Kerberos server, using
221 B<-unwrap> can shrink the AFS token size so that older software can handle
222 it more easily.
223
224 =item B<-help>
225
226 Prints the online help for this command. All other valid options are
227 ignored.
228
229 =back
230
231 =head1 OUTPUT
232
233 If the B<-tmp> flag is included, the following message confirms that a
234 Kerberos ticket cache was created:
235
236    Wrote ticket file to /tmp/krb5cc_1000_rENJoZ
237
238 The path to the cache will vary, of course.
239
240 =head1 EXAMPLES
241
242 Most often, this command is issued without arguments. The appropriate
243 password is for the person currently logged into the local system.  The
244 ticket's lifetime is calculated as described in L</DESCRIPTION>.
245
246    % klog.krb5
247    Password for user@EXAMPLE.ORG:
248
249 The following example authenticates the user as admin in the Example
250 Corporation's test cell:
251
252    % klog.krb5 -principal admin -cell test.example.com
253    Password for admin@EXAMPLE.COM:
254
255 =head1 PRIVILEGE REQUIRED
256
257 None
258
259 =head1 SEE ALSO
260
261 L<aklog(1)>,
262 L<fs_exportafs(1)>,
263 L<pagsh(1)>,
264 L<tokens(1)>
265
266 =head1 COPYRIGHT
267
268 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
269
270 This documentation is covered by the IBM Public License Version 1.0.  It
271 was converted from HTML to POD by software written by Chas Williams and
272 Russ Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.