SUPER(1)

SUPER(1) — General Commands Manual 👑

okay bestie, gather round. This is super, and she's out here letting specified users run commands as root — no cap. 💅

---

✨ 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 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. 🫶

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 fr fr, 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 executed 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 durations 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 discarded. If LINES or COLUMNS contains any characters other than [0-9], it is discarded. 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).
• (c) all signal handling is reset to the default.

If Super is executed without arguments, it will print the commands that the user may execute, 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 precede any user-supplied arguments; 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 example, 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-continued, 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 — prints the super version number. that's the whole thing, no notes 💅
• -S — when super is gonna prompt you for a password, this forces it to prompt on stdin, even if the default (/dev/tty) is readable and writable. heads up bestie: this only applies to password-type authentication — y'know, the older kind where super itself does the prompting. PAM authentication is handled by your system's PAM modules, not by super, so this flag doesn't touch it.
• -f — asks for a list of available commands in a terse format, the kind that's actually useful when a script needs to parse it. (-f stands for facts, as in "just the facts, m'am" — she's efficient like that 💁)
• -rreqpath — tells super to throw an error if the program associated with this command isn't reqpath. this is lowkey the move for writing scripts that need to be sure super only executes exactly what they expect, no surprises. see step 4 of the section "Creating Super Scripts" for an example of it in action 🫶
• -H — makes super print a verbose listing of the commands available to the user. it prints both the command and its translation to a program pgm. now here's the tea: if that displayed pgm contains an asterisk, then the actual program that gets executed is formed by swapping the asterisk out for the command the user typed in. here are the kinds of lines -H might show you:

Example 1.

super skill → /usr/local/bin/skill

so typing super skill will execute /usr/local/bin/skill. simple, clean, slay.

Example 2.

super {lp*} → /usr/bin/*

ok this one has asterisks on both sides. the left side shows the valid pattern you have to match in order to execute the command on the right-hand side. usually the right-hand side has no asterisk at all — just a full path to a command to execute. but if there is an asterisk there, it gets replaced by the command you entered, and that's what forms the actual executed command. so 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 means you can type super coxxx (where xxx is any string), but since the right-hand side has no asterisk, coxxx will always execute /usr/bin/compress. no matter what. periodt.

• -t — this turns on "test" mode 🧪. it does all the normal checks except the ones that need user input (passwords, and variables the user has to enter), and it doesn't execute any command at all. instead it exits with status code 0 if the command is ok to execute, otherwise 1. all the normal error message output gets generated the usual way, but no special debug messages are produced. so basically: it's a great way for a script to check whether a command is likely to work, and therefore whether it's reasonable to exec super.

let's say a script /usr/local/bin/foo wants to invoke itself using super foo (and yes — go read the section "Creating Super Scripts" for how to avoid infinite loops when you do this!! 😭). the script can use the -r option to make sure super foo refers to the correct file, and it can use test mode to make sure 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 are the options for when you're building and debugging super.tab files. they have little to no value for the everyday user, ngl. and with the exception of the -b option, you can combine them with the regular options above ✨

• -b — prints the names and values of built-in variables, then exits. super handy for administrators who need to learn the values that builtin variables can be tested against 👑
• -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 gets checked. exit code is 0 if the file's syntax is ok; otherwise it's 1 (and an error message gets printed). after you modify a super file, you should always use this option to check its integrity, fr fr.

⚠️ note that super -c is not a complete check that you've correctly set up an entry — you can absolutely create syntactically valid entries that don't do what you actually wanted. so you should also use super -d cmd to make sure the command you've entered will be executed with the correct arguments, uid, gid, umask, and so on. double check the vibe 💅

• -d — turns on 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 for checking whether a new entry in the super.tab file (see below) has been handled properly.
• -D — same as -d, plus it prints more information about variables defined in the super.tab file.
• -Fsuperfile — this one is only for debugging, and it lets you test a superfile before installing it. no command will actually be executed. it also turns on a non-verbose debugging mode, showing the matched command names and the reasons for accepting or rejecting the command.
• -Ggid — also a debugging option. 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 — also a debugging option. 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 — also a debugging option. 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 — also a debugging option. tells super to act as if the execution time is hh:mm/dayname. this lets you check whether 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 whole network 🌈
• /run/superstamps/username — used as a timestamp for the last time that the user entered his or her password 🕰️

---

🧚 CREATING SUPER SCRIPTS 🧚

ok bestie, sit down, because this part is serious. you must be exceedingly careful when writing scripts for super. a surprising variety of totally 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. minimalism is the aesthetic here.

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 a similar file. or — say you write a script to let users mount cd-rom's by executing mount(8). but if you don't write it carefully, a user could mount a floppy disk containing, like, a setuid-root shell 💀 not the vibe.

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 (which forces 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 too, so you don't have to remember to type it on the command line every single time. use a line like this 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 actually let somebody 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 they can just type

% cdmount args

instead of

% super cdmount args

you can make a script super itself by beginning the script like this:

#!/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. and the option -r$0 is a sanity-check option: it tells super that it's an error if super $prog doesn't execute $0, i.e. 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.

---

👀 SEE ALSO 👀

super.tab(5).

---

👑 AUTHOR 👑

Will Deich will@ucolick.org

---

💀 NOTES 💀

if the super.tab file isn't owned by root, or if it is group- or world-writable, super won't run setuid-root. (and if the user's real uid is root, super won't run at all; otherwise, the effective uid reverts to the real uid.) 🚨

there is a race condition when using password-requiring commands, but — good news — it doesn't affect security: if a user is running two copies of super 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 super commands to fail 😭. workaround: a single user shouldn't execute two password-requiring super programs simultaneously. just don't do it, bestie.

---

okay that's the whole page!! this one's the local build of SUPER(1), section 1 of the manual — go forth and be safe with your setuid scripts, mwah 💖✨🎀