--- name: "super" section: "1" platform: "linux" package: "super" version: "3.30.3-2+b2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/super" --- # super(1) execute commands setuid root. ## 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 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 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 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** 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''). - **-r***reqpath* 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 lp***xxx* (where *xxx* is any string), **super** will execute **/usr/bin/lp***xxx.* *Example 3.* **super {co\*}** → */usr/bin/compress* The asterisk on the left-hand side means you can enter **super co***xxx* (where *xxx* is any string), but since the right-hand side doesn't contain an asterisk, **co***xxx* 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 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 *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 administrators 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 properly. - **-D** Same as **-d**, plus prints more information about variables defined in the *super.tab* file. - **-F***superfile* 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. - **-G***gid* 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. - **-U***uid* 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. - **-M***mach* 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. - **-T***hh*:*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. - */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)](/mount/8.md)**. 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 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 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. ## SEE ALSO [**super.tab**(5)](/super.tab/5.md). ## 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. (If the user's real uid is root, **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 **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.