Provided by: super_3.30.0-2_i386 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
            Users 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.

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