super(1) - phpMan

SUPER(1) SUPER(1)

NAME
super - execute commands setuid root.

SYNOPSIS
To execute a command:
super [ -r reqpath] command [ args ]
super [ -r reqpath] -o path [ args ]
command [ args ]

To list available commands:
super [-H|-f] [-S]

For usage and/or version information:
super [-h] [-V]

For debugging and development:
super -b
super -c [ superfile ]
super [-d|-D|-t] [-S] [MasqOptions] [-H|-f|command...]

MasqOptions:
-F file
-T hh:mm/dayname
-G gid
-U uid
-M mach

DESCRIPTION
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 exe-
cuting 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.

Super consults a ``super.tab'' file to see if the user is allowed to execute the requested
command. If permission is granted, super will exec pgm [ args ], where pgm is the program
that is associated with this command. (Root is allowed execution by default, but can
still be denied if a rule excludes root. Ordinary users are disallowed execution by
default.)

The most common sort of entry in a super.tab file pairs a simple command with a pgm path.
But in fact, the command in the super.tab file is actually treated as a pattern, and any
user-entered command that matches this pattern causes the associated pgm to be executed.
If the listed 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 exe-
cuted by a user. For example, if the entry contains the command/pgm pairs
CommandPattern Program
scripts/* -> /usr/local/super/*
* -> /usr/local/somedir/*
then the translations made are
User's Command Executed Program
scripts/xyz -> /usr/local/super/scripts/xyz
xyz -> /usr/local/somedir/xyz

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 dura-
tions are set in the same file that records the valid users for each command.

If command is a symbolic link (or hard link, too) to the super program, then typing
% command args
is equivalent to typing
% super command args
(The command must not be super, or super will not recognize that it's being invoked via a
link.)

Super without any arguments will display the list of commands that may be executed by the
user.

For security, the following precautions are taken before exec'ing:

(a) all descriptors save 0,1,2 are closed;

(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 dis-
carded. If LINES or COLUMNS contains any characters other than [0-9], it is dis-
carded. To these are added reasonable values for:

USER and LOGNAME: both are set to the username associated with the real uid of the
program running under super;

HOME: set to the login directory of the user running super;

ORIG_USER, ORIG_LOGNAME, ORIG_HOME: the values of USER, LOGNAME, and HOME that
refer to the user who invoked super. (These values are computed by 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.);

IFS: set to blank, tab, newline;

PATH: set to /bin:/usr/bin.

SUPERCMD: set to command.

additional environment variables as specified in the super.tab file (see below).

If Super is executed without arguments, it will print the commands that the user may exe-
cute, one command per line. Super -H prints a long-winded description of each command
that the user may execute.
The CmdPat is the command pattern, and FullPath is the full path that will be executed.
The super.tab file can specify initial arguments that that precede any user-supplied argu-
ments; these arguments, if any, are printed after the FullPath column.

User-Defined Super.tab Files
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
command is entered in the form
super loginname:cmd
super looks for cmd in the file .supertab, in the home directory of account loginname.
The cmd will be executed using the uid, gid, and supplementary groups (if any) of user
loginname.

The usual super options (such as -H) can be applied to a user's .supertab file. For exam-
ple, help information about one command can be had by using:
super -H loginname:cmd
Likewise, help information about all of loginname's commands can be obtained with:
super -H loginname:

Links to per-user commands can be created and used in a manner similar to making symlinks
to super itself. If command is a symbolic link to a user's .supertab file, and that
.supertab file is

(a) executable, and

(b) begins with
#! /path/to/super -o

then the following pair are completely equivalent:
% super loginname:command
% command
If the #!-line would be longer than the typical Unix limit of 32 characters, you can
instead start the .supertab file with:
#! /bin/sh
# Keep this backslash -> \
exec /long/path/to/the/super/executable -o $0 ${1+"$@"}
(The above takes advantage of the fact that super allows comments to be backslash-contin-
ued, but the shell doesn't.)

Per-user .supertab linking works as follows: if /path/to/xyz is a symlink to some user's
.supertab file, and the .supertab file begins with #! /path/to/super -o, then the shell
will invoke super with arguments something like
super -o /path/to/xyz [args]
Super checks that /path/to/xyz is a link to a real .supertab file, and then always turns
the last part of the path (here xyz) into the command to execute.

** Security Warning **
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 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
super loginname:cmd doesn't involve any shell processing of the .supertab file.

REGULAR OPTIONS
-V Print the super version number.

-S When super prompts for a password, this forces it to prompt on stdin, even if the
default (/dev/tty) is readable and writable. Note: This only applies to password-
type authentication -- that is, the older type of authentication wherein super
itself prompts for the password; PAM authentication is handled by your system's PAM
modules.

-f This requests a list of available commands in a terse format useful for processing
by scripts. (-f stands for facts, as in ``just the facts, m'am'').

-rreqpath
Tells super to generate an error if the program associated with this command is not
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.

-H Causes super to print a verbose listing of the commands available to the user. It
prints both the command and its translation to a program pgm. If the displayed pgm
contains an asterisk, then the actual program executed is formed by replacing the
asterisk with the command entered by the user. The following examples show the
kinds of lines that may be displayed with the -H option:

Example 1.
super skill -> /usr/local/bin/skill

Typing super skill will execute /usr/local/bin/skill.

Example 2.
super {lp*} -> /usr/bin/*

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 is an asterisk present, it is replaced by the command
you entered, thereby forming the actual executed command. Thus, if you type
super lpxxx (where xxx is any string), super will execute /usr/bin/lpxxx.

Example 3.
super {co*} -> /usr/bin/compress

The asterisk on the left-hand side means you can enter super coxxx (where xxx is
any string), but since the right-hand side doesn't contain an asterisk, coxxx will
always execute /usr/bin/compress.

-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 spe-
cial 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 super foo (See
the section ``Creating Super Scripts'' for how to avoid infinite loops when doing
this!) the script can use the -r option to ensure that super foo refers to the
correct file, and it can use test mode to ensure that super foo is a valid command:
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

DEBUG AND DEVELOPMENT OPTIONS
These options are useful when creating and debugging super.tab files. They have little or
no value to the everyday user. With the exception of the -b option, they can be combined
with the regular options, above.

-b Print the names and values of built-in variables, then exit. Useful for adminis-
trators to learn the values against which builtin variables can be tested.

-c[superfile]
Tells super to check the syntax of the entries in the superfile, but not to execute
any command. If no superfile is given, the regular 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.

Note that 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 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.

-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 super.tab file (see below) has been handled prop-
erly.

-D Same as -d, plus prints more information about variables defined in the super.tab
file.

-Fsuperfile
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-ver-
bose debugging, showing the matched command names and reasons for accepting or
rejecting the command.

-Ggid This option is also used for debugging, and tells super to act as if the caller's
groupid or groupname was gid. It carries the same restrictions and debug info as
the -F option.

-Uuid This option is also used for debugging, and tells super to act as if the caller's
uid or username was uid. It carries the same restrictions and debug info as the -F
option.

-Mmach This option is also used for debugging, and tells super to act as if the caller's
host (machine) was mach. It carries the same restrictions and debug info as the -F
option.

-Thh:mm/dayname
This option is also used for debugging, and tells super to act as if the execution
time is hh:mm/dayname. This lets you check if a time specification in the
super.tab file is properly restricting execution. It carries the same restrictions
and debug info as the -F option.

FILES
/etc/super.tab
contains the list of commands that 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.

/var/run/superstamps/username
is used as a timestamp for the last time that the user entered his or her password.

CREATING SUPER SCRIPTS
You must be exceedingly careful when writing scripts for 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.

Think twice about side-effects and alternative uses of these scripts. For instance, make
sure your script doesn't quietly invoke the user's .cshrc or similar file. Or, you might
write a script to allow users to mount cd-rom's by executing mount(8). But if you don't
write it carefully, a user could mount a floppy disk containing, say, a setuid-root shell.

Security issues aside, here are some hints on creating super scripts:

1. Scripts must begin with #! interpreter-path.

2. Some variants of csh will not run setuid scripts unless the -b flag (force a
"break" from option processing) is set:
#!/bin/csh -fb
Similarly, if your super.tab file starts a shell such as csh or tcsh, you may want
to include the -b option in the 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
super.tab file:
SHELL "/usr/bin/csh -fb" some_priv_user
N.B. This is by way of example only; it's not a very good idea to really let some-
body become root without any password check.

3. Better still, avoid csh scripts entirely -- they are harder to write safely than
Bourne-shell scripts.

4. It's nice to make the super call transparent to users, so that they can type
% cdmount args
instead of
% super cdmount args
You can make a script super itself by beginning the script in the following way:
#!/bin/sh
prog=`basename $0`
test "X$SUPERCMD" = "X$prog" ||
exec /usr/local/bin/super -r $0 $prog ${1+"$@"}
Here, the path that is exec'd should be replaced with the path at your site that
leads to super. The option -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 -t option for how a script can check that super $prog will work
before doing an exec super.)

5. Some programs need certain directories in the path. Your super scripts may have to
add directories like /etc or /usr/etc to make commands work. For instance,
SunOS 4.1 needs /usr/etc in the path before it can mount filesystems of type
``hsfs''.

6. By default, super only changes the effective uid. Some programs (e.g. exportfs
under SunOS 4.1.x) require the real uid to be root. In that case, you should put
an option like ``uid=root'' or ``u+g=root'' into the super.tab file.