Provided by: super_3.30.0-6_i386 bug


       super - execute commands setuid root.


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

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


       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  ``'' 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  file  pairs  a  simple
       command  with  a  pgm  path.  But in fact, the command in the
       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
       then the translations made are
            User's Command      Executed Program

       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
                     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 file  can  specify  initial  arguments
       that that precede any user-supplied arguments; these arguments, if any,
       are printed after the FullPath column.

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


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

              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

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


       These  options  are useful when creating and debugging 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.

              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 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 file (see below) has been handled properly.

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

              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

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

              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  file is properly
              restricting execution.  It carries  the  same  restrictions  and
              debug info as the -F option.


              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  file
              can be used across a network.

              is  used  as a timestamp for the last time that the user entered
              his or her password.


       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 file starts a shell such as csh or
              tcsh, you may want to include the -b  option  in  the
              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
                   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:
                   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 file.



       Will Deich


       If the 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)