Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
SUPER(1)		    General Commands Manual		      SUPER(1)

       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 in-
       tended 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

       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	execu-
       tion by default.)

       The most	common sort of entry in	a file pairs a  simple  com-
       mand  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
	    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 pass-
       word.  These commands can then be run multiple times until some expira-
       tion  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;

		     and HOME that  refer  to  the  user  who  invoked	super.
		     (These values are computed	by super, and are not the val-
		     ues 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  su-
		     per  command changes uid or gid before executing the pro-

	      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	 envi-
       ronment	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 ac-
       count loginname.	 The cmd will be executed using	the uid, gid, and sup-
       plementary groups (if any) of user loginname.

       The  usual  super  options (such	as -H) can be applied to a user's .su-
       pertab 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 ob-
       tained 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	 char-
       acters, 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  sym-
       link  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  com-
       mand,  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	avail-
	      able  to	the user.  It prints both the command and its transla-
	      tion to a	program	pgm.  If the displayed pgm contains an	aster-
	      isk, 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 su-
	      per 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 in-
	      finite 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 ...

       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  en-
	      tries  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 com-
	      mand 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  su-
	      perfile  before installing it.  No command will actually be exe-
	      cuted.  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  re-
	      stricting	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 sur-
       prising variety of ordinary commands can, when run setuid-root, be  ex-
       ploited	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 care-
       fully, a	user could mount a floppy disk containing, say,	a  setuid-root

       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  com-
	      mand  line  every	time; use a line like the following in the su- 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:
		   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 su-
       per commands to fail.  Workaround: a single user	shouldn't execute  two
       password-requiring super	programs simultaneously.

				     local			      SUPER(1)


Want to link to this manual page? Use this URL:

home | help