File: super.1.in

package info (click to toggle)
super 3.30.0-3+squeeze2
  • links: PTS
  • area: main
  • in suites: squeeze
  • size: 1,088 kB
  • ctags: 755
  • sloc: ansic: 10,089; sh: 288; makefile: 201
file content (712 lines) | stat: -rw-r--r-- 18,369 bytes parent folder | download | duplicates (5)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
.TH SUPER 1 local
.\"
.\"	Copyright (c) 1993 by California Institute of Technology.
.\"	Written by William Deich.  Not derived from licensed software.
.\"
.\"    You may distribute under the terms of either the GNU General Public
.\"    License or the Artistic License, as specified in the README file.
.\"
.\"
.SH NAME
super \- execute commands setuid root.
.SH SYNOPSIS
To execute a command:
.br
.ti +.5i
.B super
.RI [\ \-r\ reqpath ]
.I command
.RI [ " args " ]
.br
.ti +.5i
.B super
.RI [\ \-r\ reqpath ]
.B \-o
.I path
.RI [ " args " ]
.br
.ti +.5i
.B command
.RI [ " args " ]
.sp
To list available commands:
.br
.ti +.5i
.B super
.RI [ \-H | \-f ]
.RI [ \-S ]
.sp
For usage and/or version information:
.br
.ti +.5i
.B super
.RI [ \-h ]
.RI [ \-V ]
.sp
For debugging and development:
.br
.ti +.5i
.B super
.B \-b
.br
.ti +.5i
.B super
.B \-c
.RI [ " superfile " ]
.br
.ti +.5i
.B super
.RI [ \-d | \-D | \-t ]
.RI [ \-S ]
.RI [ MasqOptions ]
.RI [ \-H | \-f | command... ]
.sp
.ti +0.5i
MasqOptions:
.RS
.RS
.nf
.I \-F\ file
.I \-T\ hh:mm/dayname
.I \-G\ gid
.I \-U\ uid
.I \-M\ mach
.fi
.RE
.RE
.SH DESCRIPTION
.B Super
allows specified users to execute scripts (or other commands) as if they
were root; or it can set the uid, gid, and/or supplementary groups on
a per-command basis before executing the command.
It is intended to be a secure alternative to making scripts setuid root.
Super also allows ordinary users to supply commands for execution by others;
these execute with the uid, gid, and groups of the user offering the command.
.PP
.B Super
consults a
.RI `` super.tab ''
file to see if the user is allowed to execute the requested
.IR command .
If permission is granted,
.B super
will exec
.IR pgm\  [\  args\  ],
where
.I pgm
is the program that is associated with this
.I command.
(Root is allowed execution by default, but can still be denied if a rule
excludes root.  Ordinary users are disallowed execution by default.)
.PP
The most common sort of entry in a
.I super.tab
file pairs a simple
.I command
with a
.I pgm
path.
But in fact, the command in the
.I super.tab
file is actually treated as a pattern, and
.I any
user-entered
command that matches this pattern causes the associated
.I pgm
to be executed.  If the listed
.I pgm
contains an asterisk, then the asterisk is replaced with
the command entered by the user.  One use of this is to
let any program in a certain directory be executed by a user.
For example, if the entry contains the command/pgm pairs
.ta 1.75i 2i 
.ti +.5i
.I "CommandPattern		Program"
.br
.ti +.5i
.B "scripts/*	\(->	/usr/local/super/*"
.br
.ti +.5i
.B "\ \ \ *	\(->	/usr/local/somedir/*"
.br
then the translations made are
.ti +.5i
.I "User's Command		Executed Program"
.br
.ti +.5i
.B "scripts/xyz	\(->	/usr/local/super/scripts/xyz"
.br
.ti +.5i
.B "xyz	\(->	/usr/local/somedir/xyz"
.br
.PP
Some commands can only be run after the user enters his or her password.
These commands can then be run multiple times until some expiration time,
at which point the password needs to be re-entered.
The list of password-requiring commands and the password durations
are set in the same file that records the valid users for each command.
.PP
If
\fIcommand\fR
is a symbolic link (or hard link, too) to the
.B super
program,
then typing
.ti +.5i
% \fIcommand args\fP
.br
is equivalent to typing
.ti +.5i
% \fBsuper\fP \fIcommand args\fP
.br
(The
.I command
must not be
.BR super ,
or
.B super
will not recognize that it's being invoked via a link.)
.PP
.B Super
without any arguments will display the list of commands that may be executed
by the user.
.PP
For security, the following precautions are taken before exec'ing:
.TP
(a)
all descriptors save 0,1,2 are closed;
.TP
(b)
all of the user's environment variables are
discarded, save for TERM, LINES, and COLUMNS.
If TERM contains any characters other than
{-/:+._a\-zA\-Z0\-9}, it is discarded.
If LINES or COLUMNS contains any
characters other than [0\-9], it is discarded.
To these
are added reasonable values for:
.RS
.HP
USER and LOGNAME: both are set to the username associated with the
real uid of the program running under
.BR super ;
.HP
HOME: set to the login directory
of the user running
.BR super ;
.HP
ORIG_USER, ORIG_LOGNAME, ORIG_HOME: the values of
USER, LOGNAME, and HOME that refer to the user who invoked
.BR super .
(These values are computed by
.BR super ,
and are not the values set by the caller, so they are a reliable
description of the caller.  These are normally the same values
as USER, LOGNAME, and HOME,
but they will differ if the super command changes uid or gid
before executing the program.);
.HP
IFS: set to blank, tab, newline;
.HP
PATH: set to
.IR @SAFE_PATH@ .
.HP
SUPERCMD: set to \fIcommand\fP.
.HP
additional environment variables as specified in the
.I super.tab
file (see below).
.RE
.in -.5i
.TP
(c)
all signal handling is reset to the default.
.PP
If
.I Super
is executed without arguments, it will print
the commands that the user may execute, one command per line.
.B "Super \-H"
prints a long-winded description of each command that the user may execute.
.br
The
.I CmdPat
is the command pattern, and
.I FullPath
is the full path that will be executed.
The super.tab file can specify initial arguments that
that precede any user-supplied arguments;
these arguments, if any, are printed after the
.I FullPath
column.
.SH User-Defined Super.tab Files
.PP
Ordinary users can supply their own super files.
This lets users give well-controlled setuid/setgid access to their
programs: the user who offers the program gets the assurance of
safe IFS settings, safe environment variable settings, etc; and the
user who executes the program knows that it will execute under
the uid and gid of the offering user.
If a
.I command
is entered in the form
.RS
\fBsuper\fP \fIloginname\fB:\fIcmd\fR
.RE
.I super
looks for
.I cmd
in the file
.BR .supertab ,
in the home directory of account
.IR loginname .
The
.I cmd
will be executed using the uid, gid, and supplementary groups (if any) of user
.IR loginname .
.PP
The usual super options (such as \fB\-H\fP) can be applied to a
user's .supertab file.  For example, help information about one command
can be had by using:
.ti +0.5i
\fBsuper \-H\fP \fIloginname\fP\fB:\fP\fIcmd\fP
.br
Likewise, help information about all of
.IR loginname 's
commands can be obtained with:
.ti +0.5i
\fBsuper \-H\fP \fIloginname\fP\fB:\fP
.br
.ta 0.5i 1.0i 1.5i 2.0i 2.5i 3.0i 3.5i 4.0i 4.5i 5.0i 5.5i 6.0i 6.5i 7.0i
.PP
Links to per-user commands can be created and used in a manner similar to
making symlinks to
.I super
itself.  If
.I command
is a symbolic link to a
user's .supertab file, and that .supertab file is
.RS
.HP
(a)	executable, and
.br
.HP
(b)	begins with
.RS
.B #!\ /path/to/super \-o
.RE
.RE
.sp
then the following pair are completely equivalent:
.RS
.IB % \ super \ loginname : command
.br
.I % command
.RE
If the
.BR #! -line
would be longer than the typical Unix limit of 32 characters,
you can instead start the .supertab file with:
.RS
.nf
#! /bin/sh
# Keep this backslash -> \\
	exec /long/path/to/the/super/executable -o $0 ${1+"$@"}
...
.fi
.RE
(The above takes advantage of the fact that super allows comments to
be backslash-continued, but the shell doesn't.)
.PP
Per-user .supertab linking works as follows: if
.I /path/to/xyz
is a symlink to some user's .supertab file, and the .supertab file
begins with \fI#! /path/to/super -o\fP,
then the shell will invoke
.I super
with arguments something like
.RS
.B super -o /path/to/xyz [args]
.RE
Super checks that
.I /path/to/xyz
is a link to a real .supertab file,
and then always turns the last part of the path (here
.IR xyz )
into the command to execute.
.PP
.ce 1
.B ** Security Warning **
.br
Note that if you use symlinks to a per-user .supertab file,
then you must trust that the .supertab file will
actually execute a super command, instead of doing something nasty.
That is because
.I super
itself isn't invoked until the shell has opened the .supertab file
and done whatever the .supertab file tells it to do.
By contrast, the direct command
.BI super \ loginname : cmd
doesn't involve any shell processing of the .supertab file.
.ta 1.75i 2i 
.SH REGULAR OPTIONS
.TP
.BR \-V
Print the super version number.
.TP
.BR \-S
When
.B super 
prompts for a password, this forces it to prompt on stdin, even if
the default
.RB ( /dev/tty )
is readable and writable.
.I Note:
This only applies to password-type authentication \(em that is, the older
type of authentication wherein
.B super
itself prompts for the password; PAM authentication is handled
by your system's PAM modules.
.TP
.BR \-f
This requests a list of available commands in a terse
format useful for processing by scripts.
(\fB\-f\fP stands for facts, as in ``just the facts, m'am'').
.TP
.BI \-r reqpath
Tells super to generate an error if the program associated with this
.I command
is not
.I reqpath.
This helps you write scripts that ensure that super only executes
what they expect it to execute.  See step\ 4 of the section,
``Creating Super Scripts'', for an example of its use.
.TP
.B
\-H
Causes
.B super
to print a verbose listing of the commands available to the user.
It prints both the
.I command
and its translation to a program
.IR pgm .
If the displayed
.I pgm
contains an asterisk, then the actual program executed is formed
by replacing the asterisk with the
.IR command
entered by the user.
The following examples show the kinds of lines that may be
displayed with the
.B \-H
option:
.sp
.I "Example 1."
.ti +0.5i
.B super skill
\(->
.I /usr/local/bin/skill
.sp
Typing
.B super\ skill
will execute
.BR /usr/local/bin/skill .
.sp
.I "Example 2."
.ti +0.5i
.B super {lp*}
\(->
.I /usr/bin/*
.sp
This example contains asterisks on both the left and right sides.
The left side shows the valid pattern you must match to execute
the command shown on the right-hand side.
Usually, the right-hand side has no asterisk, just
a full path to a command to execute.
If there
.I is
an asterisk present, it is replaced by the command you entered,
thereby forming the actual executed command.
Thus, if you type
.BI super\ lp xxx
(where
.I xxx
is any string),
.B super
will execute
.BI /usr/bin/lp xxx.
.sp
.I "Example 3."
.ti +0.5i
.B super {co*}
\(->
.I /usr/bin/compress
.sp
The asterisk on the left-hand side means you can enter
.BI super\ co xxx
(where
.I xxx
is any string),
but since the right-hand side
doesn't contain an asterisk,
.BI co xxx
will always execute
.BR /usr/bin/compress .
.TP
.BR \-t
This enables ``test'' mode.  It does all normal checks except for
those requiring user input (passwords and variables that the
user must enter), but doesn't execute any command.  Instead, it
exits with status code 0 if the command is ok to execute, else 1.
All normal error message output is generated in the usual way,
but no special debug messages are generated.  Thus, it is a useful
means for a script to check if a command is likely to work,
and hence reasonable to exec super.  Let's say that a script
/usr/local/bin/foo wants to invoke itself using \fIsuper foo\fP
(See the section ``Creating Super Scripts'' for how to avoid
infinite loops when doing this!)
the script can use the \fB\-r\fP option to ensure that \fIsuper foo\fP
refers to the correct file, and it can use test mode to ensure
that \fIsuper foo\fP is a valid command:
.in +.5i
.nf
prog=\`basename $0\`
/usr/local/bin/super -t -r $0 $prog
case $? in
0 ) exec /usr/local/bin/super -t -r $0 $prog ;;
* ) echo "Super $prog doesn't work!"
    ... So take appropriate action ...
    ;;
esac
.fi
.in -.5i
.SH DEBUG AND DEVELOPMENT OPTIONS
.PP
These options are useful when creating and debugging
.I super.tab
files.  They have little or no value to the everyday user.
With the exception of the
.B \-b 
option, they can be combined with the regular options, above.
.TP
.BR \-b
Print the names and values of built-in variables, then exit.
Useful for administrators to learn the values against which
builtin variables can be tested.
.TP
.BR \-c [\fIsuperfile\fP]
Tells
.I super
to check the syntax of the entries in the
.IR superfile ,
but not to execute any command.  If no
.I superfile
is given, the regular
.I super.tab
is checked.
The exit code is 0 if the file's syntax is ok; otherwise the
exit code is 1 (and an error message is printed).
After modifying a
super file, you should use this option to check its integrity.
.sp
Note that
.I "super \-c"
isn't a complete check that you've correctly set up an
entry, because you can create syntactically valid
entries that don't do exactly what you want.  Therefore,
you should also use
.IR "super \-d cmd"
to make sure that the command you've entered will be executed with the
correct arguments, uid, gid, umask, and so on.
.TP
.BR \-d
This enables debug mode, in which case (a) debugging information
is printed while checking a user for validity, and (b) the command
isn't actually executed.  Useful to check if a new entry in the
.I super.tab
file (see below) has been handled properly.
.TP
.BR \-D
Same as
.BR \-d ,
plus prints more information about variables defined in
the
.I super.tab
file.
.TP
.BR \-F \fIsuperfile\fP
This option is only used for debugging, and
lets you test a superfile before installing it.
No command will actually be executed.
It also turns on a non-verbose debugging,
showing the matched command names
and reasons for accepting or rejecting the command.
.TP
.BR \-G \fIgid\fP
This option is also used for debugging, and tells
.I super
to act as if the caller's groupid or groupname was
.IR gid .
It carries the same restrictions and debug info as the \-F option.
.TP
.BR \-U \fIuid\fP
This option is also used for debugging, and tells
.I super
to act as if the caller's uid or username was
.IR uid .
It carries the same restrictions and debug info as the \-F option.
.TP
.BR \-M \fImach\fP
This option is also used for debugging, and tells
.I super
to act as if the caller's host (machine) was
.IR mach .
It carries the same restrictions and debug info as the \-F option.
.TP
.BR \-T \fIhh\fP:\fImm\fP/\fIdayname\fP
This option is also used for debugging, and
tells
.I super
to act as if the execution time is
.IR hh : mm / dayname .
This lets you check if a time specification in the
.I super.tab
file is properly restricting execution.
It carries the same restrictions and debug info as the \-F option.
.SH FILES
.TP
.I @SUPERDIR@/super.tab
contains the list of commands that
.B super
may execute, along with the names of the user/group combinations
who may execute each command.  The valid-user line can restrict use to
particular users or groups on different hosts, so a single super.tab
file can be used across a network.
.TP
.IR @TIMESTAMP_DIR@/ username
is used as a timestamp for the last time that the user entered
his or her password.
.SH CREATING SUPER SCRIPTS
You must be exceedingly careful when writing scripts for
.BR super .
A surprising variety of ordinary commands can, when
run setuid-root, be exploited for nasty purposes.  Always make your
scripts do as little as possible, and give the user as few options
as possible.
.PP
Think twice about side-effects and alternative uses
of these scripts.  For instance, make sure your script doesn't quietly
invoke the user's
.I .cshrc
or similar file.
Or, you might write a script to allow
users to mount cd-rom's by executing
.BR mount(8) .
But if you don't write it carefully, a user could mount a floppy
disk containing, say, a setuid-root shell.
.PP
Security issues aside, here are some hints on creating super scripts:
.TP
1.
Scripts must begin with \fB#!\ \fIinterpreter-path\fR.
.TP
2.
Some variants of csh will not run setuid scripts
unless the \-b flag (force a "break" from option processing) is set:
.ti +.5i
#!/bin/csh \-fb
.br
Similarly, if your
.I super.tab
file starts a shell such as csh or tcsh, you
may want to include the \-b option in the
.I super.tab
file, so that you
don't have to remember to type it on the command line every time;
use a line like the following in the
.I super.tab
file:
.ti +.5i
SHELL  "/usr/bin/csh \-fb"  some_priv_user
.br
N.B.  This is by way of example only; it's not a very good idea to
really let somebody become root without any password check.
.TP
3.
Better still, avoid csh scripts entirely -- they are harder to
write safely than Bourne-shell scripts.
.TP
4.
It's nice to make the
.B super
call transparent to users, so that they can type
.ti +.5i
% \fBcdmount\fP \fIargs\fP
.br
instead of
.ti +.5i
% \fBsuper cdmount\fP \fIargs\fP
.br
You can make a script
.B super
itself by beginning the script in the following way:
.in +.5i
.nf
#!/bin/sh
prog=\`basename $0\`
test "X$SUPERCMD" = "X$prog" ||
		exec /usr/local/bin/super -r $0 $prog ${1+"$@"}
.fi
.in -.5i
Here, the path that is exec'd should be replaced with the
path at your site that leads to
.I super.
The option
.IR -r $0
is a sanity-check option: it tells super that it's an error if
``super $prog'' doesn't execute ``$0'', ie this self-same program.
(Also, see the \fB\-t\fP option for how a script can check that
\fIsuper $prog\fP will work before doing an \fIexec super\fP.)
.TP
5.
Some programs need certain directories in the path.  Your
super scripts may have to add directories like
.I /etc
or
.I /usr/etc
to make commands work.
For instance, SunOS\ 4.1 needs
.I /usr/etc
in the path before it can mount filesystems of type ``hsfs''.
.TP
6.
By default, \fBsuper\fP only changes the effective uid.
Some programs (e.g. \fBexportfs\fP under SunOS\ 4.1.x)
require the real uid to be root.  In that case, you should put
an option like ``\fIuid=root\fP'' or ``\fIu+g=root\fP''
into the
.I super.tab
file.
.SH "SEE ALSO"
.BR super (5).
.SH AUTHOR
Will Deich
.br
will@ucolick.org
.SH NOTES
If the
.I super.tab
file isn't owned by root, or if it is group- or world-writable,
.B super
won't run setuid-root.  (If the user's real uid is root,
.B super
won't run at all; otherwise, the effective uid reverts to real uid.)

There is a race condition when using password-requiring commands,
but it doesn't affect security: if a user is running two copies
of \fBsuper\fR simultaneously, and both processes try to update the
user's password timestamp file at the same time, then it is possible
for one of the \fBsuper\fR commands to fail.
Workaround: a single user shouldn't execute two password-requiring
\fBsuper\fR programs simultaneously.