Provided by: super_3.30.0-7build1_amd64 bug

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'').

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

       -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-
              verbose  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.

       /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
              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).

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.

                                              local                                      SUPER(1)