Mercurial > repos > rliterman > csp2

comparison CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/share/man/man1/ksu.1 @ 68:5028fdace37b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
planemo upload commit 2e9511a184a1ca667c7be0c6321a36dc4e3d116d
author jpayne
date Tue, 18 Mar 2025 16:23:26 -0400
parents
children
comparison
equal deleted inserted replaced
67:0e9998148a16 68:5028fdace37b
1 .\" Man page generated from reStructuredText.
2 .
3 .TH "KSU" "1" " " "1.20.1" "MIT Kerberos"
4 .SH NAME
5 ksu \- Kerberized super-user
6 .
7 .nr rst2man-indent-level 0
8 .
9 .de1 rstReportMargin
10 \\$1 \\n[an-margin]
11 level \\n[rst2man-indent-level]
12 level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
13 -
14 \\n[rst2man-indent0]
15 \\n[rst2man-indent1]
16 \\n[rst2man-indent2]
17 ..
18 .de1 INDENT
19 .\" .rstReportMargin pre:
20 . RS \\$1
21 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
22 . nr rst2man-indent-level +1
23 .\" .rstReportMargin post:
24 ..
25 .de UNINDENT
26 . RE
27 .\" indent \\n[an-margin]
28 .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
29 .nr rst2man-indent-level -1
30 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
31 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
32 ..
33 .SH SYNOPSIS
34 .sp
35 \fBksu\fP
36 [ \fItarget_user\fP ]
37 [ \fB\-n\fP \fItarget_principal_name\fP ]
38 [ \fB\-c\fP \fIsource_cache_name\fP ]
39 [ \fB\-k\fP ]
40 [ \fB\-r\fP time ]
41 [ \fB\-p\fP | \fB\-P\fP]
42 [ \fB\-f\fP | \fB\-F\fP]
43 [ \fB\-l\fP \fIlifetime\fP ]
44 [ \fB\-z | Z\fP ]
45 [ \fB\-q\fP ]
46 [ \fB\-e\fP \fIcommand\fP [ args ... ] ] [ \fB\-a\fP [ args ... ] ]
47 .SH REQUIREMENTS
48 .sp
49 Must have Kerberos version 5 installed to compile ksu. Must have a
50 Kerberos version 5 server running to use ksu.
51 .SH DESCRIPTION
52 .sp
53 ksu is a Kerberized version of the su program that has two missions:
54 one is to securely change the real and effective user ID to that of
55 the target user, and the other is to create a new security context.
56 .sp
57 \fBNOTE:\fP
58 .INDENT 0.0
59 .INDENT 3.5
60 For the sake of clarity, all references to and attributes of
61 the user invoking the program will start with "source"
62 (e.g., "source user", "source cache", etc.).
63 .sp
64 Likewise, all references to and attributes of the target
65 account will start with "target".
66 .UNINDENT
67 .UNINDENT
68 .SH AUTHENTICATION
69 .sp
70 To fulfill the first mission, ksu operates in two phases:
71 authentication and authorization. Resolving the target principal name
72 is the first step in authentication. The user can either specify his
73 principal name with the \fB\-n\fP option (e.g., \fB\-n jqpublic@USC.EDU\fP)
74 or a default principal name will be assigned using a heuristic
75 described in the OPTIONS section (see \fB\-n\fP option). The target user
76 name must be the first argument to ksu; if not specified root is the
77 default. If \fB\&.\fP is specified then the target user will be the
78 source user (e.g., \fBksu .\fP). If the source user is root or the
79 target user is the source user, no authentication or authorization
80 takes place. Otherwise, ksu looks for an appropriate Kerberos ticket
81 in the source cache.
82 .sp
83 The ticket can either be for the end\-server or a ticket granting
84 ticket (TGT) for the target principal\(aqs realm. If the ticket for the
85 end\-server is already in the cache, it\(aqs decrypted and verified. If
86 it\(aqs not in the cache but the TGT is, the TGT is used to obtain the
87 ticket for the end\-server. The end\-server ticket is then verified.
88 If neither ticket is in the cache, but ksu is compiled with the
89 \fBGET_TGT_VIA_PASSWD\fP define, the user will be prompted for a
90 Kerberos password which will then be used to get a TGT. If the user
91 is logged in remotely and does not have a secure channel, the password
92 may be exposed. If neither ticket is in the cache and
93 \fBGET_TGT_VIA_PASSWD\fP is not defined, authentication fails.
94 .SH AUTHORIZATION
95 .sp
96 This section describes authorization of the source user when ksu is
97 invoked without the \fB\-e\fP option. For a description of the \fB\-e\fP
98 option, see the OPTIONS section.
99 .sp
100 Upon successful authentication, ksu checks whether the target
101 principal is authorized to access the target account. In the target
102 user\(aqs home directory, ksu attempts to access two authorization files:
103 \&.k5login(5) and .k5users. In the .k5login file each line
104 contains the name of a principal that is authorized to access the
105 account.
106 .sp
107 For example:
108 .INDENT 0.0
109 .INDENT 3.5
110 .sp
111 .nf
112 .ft C
113 jqpublic@USC.EDU
114 jqpublic/secure@USC.EDU
115 jqpublic/admin@USC.EDU
116 .ft P
117 .fi
118 .UNINDENT
119 .UNINDENT
120 .sp
121 The format of .k5users is the same, except the principal name may be
122 followed by a list of commands that the principal is authorized to
123 execute (see the \fB\-e\fP option in the OPTIONS section for details).
124 .sp
125 Thus if the target principal name is found in the .k5login file the
126 source user is authorized to access the target account. Otherwise ksu
127 looks in the .k5users file. If the target principal name is found
128 without any trailing commands or followed only by \fB*\fP then the
129 source user is authorized. If either .k5login or .k5users exist but
130 an appropriate entry for the target principal does not exist then
131 access is denied. If neither file exists then the principal will be
132 granted access to the account according to the aname\->lname mapping
133 rules. Otherwise, authorization fails.
134 .SH EXECUTION OF THE TARGET SHELL
135 .sp
136 Upon successful authentication and authorization, ksu proceeds in a
137 similar fashion to su. The environment is unmodified with the
138 exception of USER, HOME and SHELL variables. If the target user is
139 not root, USER gets set to the target user name. Otherwise USER
140 remains unchanged. Both HOME and SHELL are set to the target login\(aqs
141 default values. In addition, the environment variable \fBKRB5CCNAME\fP
142 gets set to the name of the target cache. The real and effective user
143 ID are changed to that of the target user. The target user\(aqs shell is
144 then invoked (the shell name is specified in the password file). Upon
145 termination of the shell, ksu deletes the target cache (unless ksu is
146 invoked with the \fB\-k\fP option). This is implemented by first doing a
147 fork and then an exec, instead of just exec, as done by su.
148 .SH CREATING A NEW SECURITY CONTEXT
149 .sp
150 ksu can be used to create a new security context for the target
151 program (either the target shell, or command specified via the \fB\-e\fP
152 option). The target program inherits a set of credentials from the
153 source user. By default, this set includes all of the credentials in
154 the source cache plus any additional credentials obtained during
155 authentication. The source user is able to limit the credentials in
156 this set by using \fB\-z\fP or \fB\-Z\fP option. \fB\-z\fP restricts the copy
157 of tickets from the source cache to the target cache to only the
158 tickets where client == the target principal name. The \fB\-Z\fP option
159 provides the target user with a fresh target cache (no creds in the
160 cache). Note that for security reasons, when the source user is root
161 and target user is non\-root, \fB\-z\fP option is the default mode of
162 operation.
163 .sp
164 While no authentication takes place if the source user is root or is
165 the same as the target user, additional tickets can still be obtained
166 for the target cache. If \fB\-n\fP is specified and no credentials can
167 be copied to the target cache, the source user is prompted for a
168 Kerberos password (unless \fB\-Z\fP specified or \fBGET_TGT_VIA_PASSWD\fP
169 is undefined). If successful, a TGT is obtained from the Kerberos
170 server and stored in the target cache. Otherwise, if a password is
171 not provided (user hit return) ksu continues in a normal mode of
172 operation (the target cache will not contain the desired TGT). If the
173 wrong password is typed in, ksu fails.
174 .sp
175 \fBNOTE:\fP
176 .INDENT 0.0
177 .INDENT 3.5
178 During authentication, only the tickets that could be
179 obtained without providing a password are cached in the
180 source cache.
181 .UNINDENT
182 .UNINDENT
183 .SH OPTIONS
184 .INDENT 0.0
185 .TP
186 \fB\-n\fP \fItarget_principal_name\fP
187 Specify a Kerberos target principal name. Used in authentication
188 and authorization phases of ksu.
189 .sp
190 If ksu is invoked without \fB\-n\fP, a default principal name is
191 assigned via the following heuristic:
192 .INDENT 7.0
193 .IP \(bu 2
194 Case 1: source user is non\-root.
195 .sp
196 If the target user is the source user the default principal name
197 is set to the default principal of the source cache. If the
198 cache does not exist then the default principal name is set to
199 \fBtarget_user@local_realm\fP\&. If the source and target users are
200 different and neither \fB~target_user/.k5users\fP nor
201 \fB~target_user/.k5login\fP exist then the default principal name
202 is \fBtarget_user_login_name@local_realm\fP\&. Otherwise, starting
203 with the first principal listed below, ksu checks if the
204 principal is authorized to access the target account and whether
205 there is a legitimate ticket for that principal in the source
206 cache. If both conditions are met that principal becomes the
207 default target principal, otherwise go to the next principal.
208 .INDENT 2.0
209 .IP a. 3
210 default principal of the source cache
211 .IP b. 3
212 target_user@local_realm
213 .IP c. 3
214 source_user@local_realm
215 .UNINDENT
216 .sp
217 If a\-c fails try any principal for which there is a ticket in
218 the source cache and that is authorized to access the target
219 account. If that fails select the first principal that is
220 authorized to access the target account from the above list. If
221 none are authorized and ksu is configured with
222 \fBPRINC_LOOK_AHEAD\fP turned on, select the default principal as
223 follows:
224 .sp
225 For each candidate in the above list, select an authorized
226 principal that has the same realm name and first part of the
227 principal name equal to the prefix of the candidate. For
228 example if candidate a) is \fBjqpublic@ISI.EDU\fP and
229 \fBjqpublic/secure@ISI.EDU\fP is authorized to access the target
230 account then the default principal is set to
231 \fBjqpublic/secure@ISI.EDU\fP\&.
232 .IP \(bu 2
233 Case 2: source user is root.
234 .sp
235 If the target user is non\-root then the default principal name
236 is \fBtarget_user@local_realm\fP\&. Else, if the source cache
237 exists the default principal name is set to the default
238 principal of the source cache. If the source cache does not
239 exist, default principal name is set to \fBroot\e@local_realm\fP\&.
240 .UNINDENT
241 .UNINDENT
242 .sp
243 \fB\-c\fP \fIsource_cache_name\fP
244 .INDENT 0.0
245 .INDENT 3.5
246 Specify source cache name (e.g., \fB\-c FILE:/tmp/my_cache\fP). If
247 \fB\-c\fP option is not used then the name is obtained from
248 \fBKRB5CCNAME\fP environment variable. If \fBKRB5CCNAME\fP is not
249 defined the source cache name is set to \fBkrb5cc_<source uid>\fP\&.
250 The target cache name is automatically set to \fBkrb5cc_<target
251 uid>.(gen_sym())\fP, where gen_sym generates a new number such that
252 the resulting cache does not already exist. For example:
253 .INDENT 0.0
254 .INDENT 3.5
255 .sp
256 .nf
257 .ft C
258 krb5cc_1984.2
259 .ft P
260 .fi
261 .UNINDENT
262 .UNINDENT
263 .UNINDENT
264 .UNINDENT
265 .INDENT 0.0
266 .TP
267 \fB\-k\fP
268 Do not delete the target cache upon termination of the target
269 shell or a command (\fB\-e\fP command). Without \fB\-k\fP, ksu deletes
270 the target cache.
271 .TP
272 \fB\-z\fP
273 Restrict the copy of tickets from the source cache to the target
274 cache to only the tickets where client == the target principal
275 name. Use the \fB\-n\fP option if you want the tickets for other then
276 the default principal. Note that the \fB\-z\fP option is mutually
277 exclusive with the \fB\-Z\fP option.
278 .TP
279 \fB\-Z\fP
280 Don\(aqt copy any tickets from the source cache to the target cache.
281 Just create a fresh target cache, where the default principal name
282 of the cache is initialized to the target principal name. Note
283 that the \fB\-Z\fP option is mutually exclusive with the \fB\-z\fP
284 option.
285 .TP
286 \fB\-q\fP
287 Suppress the printing of status messages.
288 .UNINDENT
289 .sp
290 Ticket granting ticket options:
291 .INDENT 0.0
292 .TP
293 \fB\-l\fP \fIlifetime\fP \fB\-r\fP \fItime\fP \fB\-p\fP \fB\-P\fP \fB\-f\fP \fB\-F\fP
294 The ticket granting ticket options only apply to the case where
295 there are no appropriate tickets in the cache to authenticate the
296 source user. In this case if ksu is configured to prompt users
297 for a Kerberos password (\fBGET_TGT_VIA_PASSWD\fP is defined), the
298 ticket granting ticket options that are specified will be used
299 when getting a ticket granting ticket from the Kerberos server.
300 .TP
301 \fB\-l\fP \fIlifetime\fP
302 (duration string.) Specifies the lifetime to be requested
303 for the ticket; if this option is not specified, the default ticket
304 lifetime (12 hours) is used instead.
305 .TP
306 \fB\-r\fP \fItime\fP
307 (duration string.) Specifies that the \fBrenewable\fP option
308 should be requested for the ticket, and specifies the desired
309 total lifetime of the ticket.
310 .TP
311 \fB\-p\fP
312 specifies that the \fBproxiable\fP option should be requested for
313 the ticket.
314 .TP
315 \fB\-P\fP
316 specifies that the \fBproxiable\fP option should not be requested
317 for the ticket, even if the default configuration is to ask for
318 proxiable tickets.
319 .TP
320 \fB\-f\fP
321 option specifies that the \fBforwardable\fP option should be
322 requested for the ticket.
323 .TP
324 \fB\-F\fP
325 option specifies that the \fBforwardable\fP option should not be
326 requested for the ticket, even if the default configuration is to
327 ask for forwardable tickets.
328 .TP
329 \fB\-e\fP \fIcommand\fP [\fIargs\fP ...]
330 ksu proceeds exactly the same as if it was invoked without the
331 \fB\-e\fP option, except instead of executing the target shell, ksu
332 executes the specified command. Example of usage:
333 .INDENT 7.0
334 .INDENT 3.5
335 .sp
336 .nf
337 .ft C
338 ksu bob \-e ls \-lag
339 .ft P
340 .fi
341 .UNINDENT
342 .UNINDENT
343 .sp
344 The authorization algorithm for \fB\-e\fP is as follows:
345 .sp
346 If the source user is root or source user == target user, no
347 authorization takes place and the command is executed. If source
348 user id != 0, and \fB~target_user/.k5users\fP file does not exist,
349 authorization fails. Otherwise, \fB~target_user/.k5users\fP file
350 must have an appropriate entry for target principal to get
351 authorized.
352 .sp
353 The .k5users file format:
354 .sp
355 A single principal entry on each line that may be followed by a
356 list of commands that the principal is authorized to execute. A
357 principal name followed by a \fB*\fP means that the user is
358 authorized to execute any command. Thus, in the following
359 example:
360 .INDENT 7.0
361 .INDENT 3.5
362 .sp
363 .nf
364 .ft C
365 jqpublic@USC.EDU ls mail /local/kerberos/klist
366 jqpublic/secure@USC.EDU *
367 jqpublic/admin@USC.EDU
368 .ft P
369 .fi
370 .UNINDENT
371 .UNINDENT
372 .sp
373 \fBjqpublic@USC.EDU\fP is only authorized to execute \fBls\fP,
374 \fBmail\fP and \fBklist\fP commands. \fBjqpublic/secure@USC.EDU\fP is
375 authorized to execute any command. \fBjqpublic/admin@USC.EDU\fP is
376 not authorized to execute any command. Note, that
377 \fBjqpublic/admin@USC.EDU\fP is authorized to execute the target
378 shell (regular ksu, without the \fB\-e\fP option) but
379 \fBjqpublic@USC.EDU\fP is not.
380 .sp
381 The commands listed after the principal name must be either a full
382 path names or just the program name. In the second case,
383 \fBCMD_PATH\fP specifying the location of authorized programs must
384 be defined at the compilation time of ksu. Which command gets
385 executed?
386 .sp
387 If the source user is root or the target user is the source user
388 or the user is authorized to execute any command (\fB*\fP entry)
389 then command can be either a full or a relative path leading to
390 the target program. Otherwise, the user must specify either a
391 full path or just the program name.
392 .TP
393 \fB\-a\fP \fIargs\fP
394 Specify arguments to be passed to the target shell. Note that all
395 flags and parameters following \-a will be passed to the shell,
396 thus all options intended for ksu must precede \fB\-a\fP\&.
397 .sp
398 The \fB\-a\fP option can be used to simulate the \fB\-e\fP option if
399 used as follows:
400 .INDENT 7.0
401 .INDENT 3.5
402 .sp
403 .nf
404 .ft C
405 \-a \-c [command [arguments]].
406 .ft P
407 .fi
408 .UNINDENT
409 .UNINDENT
410 .sp
411 \fB\-c\fP is interpreted by the c\-shell to execute the command.
412 .UNINDENT
413 .SH INSTALLATION INSTRUCTIONS
414 .sp
415 ksu can be compiled with the following four flags:
416 .INDENT 0.0
417 .TP
418 \fBGET_TGT_VIA_PASSWD\fP
419 In case no appropriate tickets are found in the source cache, the
420 user will be prompted for a Kerberos password. The password is
421 then used to get a ticket granting ticket from the Kerberos
422 server. The danger of configuring ksu with this macro is if the
423 source user is logged in remotely and does not have a secure
424 channel, the password may get exposed.
425 .TP
426 \fBPRINC_LOOK_AHEAD\fP
427 During the resolution of the default principal name,
428 \fBPRINC_LOOK_AHEAD\fP enables ksu to find principal names in
429 the .k5users file as described in the OPTIONS section
430 (see \fB\-n\fP option).
431 .TP
432 \fBCMD_PATH\fP
433 Specifies a list of directories containing programs that users are
434 authorized to execute (via .k5users file).
435 .TP
436 \fBHAVE_GETUSERSHELL\fP
437 If the source user is non\-root, ksu insists that the target user\(aqs
438 shell to be invoked is a "legal shell". \fIgetusershell(3)\fP is
439 called to obtain the names of "legal shells". Note that the
440 target user\(aqs shell is obtained from the passwd file.
441 .UNINDENT
442 .sp
443 Sample configuration:
444 .INDENT 0.0
445 .INDENT 3.5
446 .sp
447 .nf
448 .ft C
449 KSU_OPTS = \-DGET_TGT_VIA_PASSWD \-DPRINC_LOOK_AHEAD \-DCMD_PATH=\(aq"/bin /usr/ucb /local/bin"
450 .ft P
451 .fi
452 .UNINDENT
453 .UNINDENT
454 .sp
455 ksu should be owned by root and have the set user id bit turned on.
456 .sp
457 ksu attempts to get a ticket for the end server just as Kerberized
458 telnet and rlogin. Thus, there must be an entry for the server in the
459 Kerberos database (e.g., \fBhost/nii.isi.edu@ISI.EDU\fP). The keytab
460 file must be in an appropriate location.
461 .SH SIDE EFFECTS
462 .sp
463 ksu deletes all expired tickets from the source cache.
464 .SH AUTHOR OF KSU
465 .sp
466 GENNADY (ARI) MEDVINSKY
467 .SH ENVIRONMENT
468 .sp
469 See kerberos(7) for a description of Kerberos environment
470 variables.
471 .SH SEE ALSO
472 .sp
473 kerberos(7), kinit(1)
474 .SH AUTHOR
475 MIT
476 .SH COPYRIGHT
477 1985-2022, MIT
478 .\" Generated by docutils manpage writer.
479 .