Annotation of src/usr.bin/sudo/sudo.pod, Revision 1.1
1.1 ! millert 1: =cut
! 2: Copyright (c) 1994-1996,1998-2007 Todd C. Miller <Todd.Miller@courtesan.com>
! 3:
! 4: Permission to use, copy, modify, and distribute this software for any
! 5: purpose with or without fee is hereby granted, provided that the above
! 6: copyright notice and this permission notice appear in all copies.
! 7:
! 8: THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
! 9: WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
! 10: MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
! 11: ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
! 12: WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
! 13: ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
! 14: OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
! 15: ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
! 16:
! 17: Sponsored in part by the Defense Advanced Research Projects
! 18: Agency (DARPA) and Air Force Research Laboratory, Air Force
! 19: Materiel Command, USAF, under agreement number F39502-99-1-0512.
! 20:
! 21: $Sudo: sudo.pod,v 1.70.2.12 2007/07/26 14:04:54 millert Exp $
! 22: =pod
! 23:
! 24: =head1 NAME
! 25:
! 26: sudo, sudoedit - execute a command as another user
! 27:
! 28: =head1 SYNOPSIS
! 29:
! 30: B<sudo> B<-h> | B<-K> | B<-k> | B<-L> | B<-l> | B<-V> | B<-v>
! 31:
! 32: B<sudo> [B<-bEHPS>] S<[B<-a> I<auth_type>]>
! 33: S<[B<-c> I<class>|I<->]> S<[B<-p> I<prompt>]> S<[B<-u> I<username>|I<#uid>]>
! 34: S<[B<VAR>=I<value>]> S<{B<-i> | B<-s> | I<command>}>
! 35:
! 36: B<sudoedit> [B<-S>] S<[B<-a> I<auth_type>]> S<[B<-c> I<class>|I<->]>
! 37: S<[B<-p> I<prompt>]> S<[B<-u> I<username>|I<#uid>]>
! 38: file ...
! 39:
! 40: =head1 DESCRIPTION
! 41:
! 42: B<sudo> allows a permitted user to execute a I<command> as the
! 43: superuser or another user, as specified in the I<sudoers> file.
! 44: The real and effective uid and gid are set to match those of the
! 45: target user as specified in the passwd file and the group vector
! 46: is initialized based on the group file (unless the B<-P> option was
! 47: specified). If the invoking user is root or if the target user is
! 48: the same as the invoking user, no password is required. Otherwise,
! 49: B<sudo> requires that users authenticate themselves with a password
! 50: by default (NOTE: in the default configuration this is the user's
! 51: password, not the root password). Once a user has been authenticated,
! 52: a timestamp is updated and the user may then use sudo without a
! 53: password for a short period of time (C<@timeout@> minutes unless
! 54: overridden in I<sudoers>).
! 55:
! 56: When invoked as B<sudoedit>, the B<-e> option (described below),
! 57: is implied.
! 58:
! 59: B<sudo> determines who is an authorized user by consulting the file
! 60: F<@sysconfdir@/sudoers>. By giving B<sudo> the B<-v> flag, a user
! 61: can update the time stamp without running a I<command.> The password
! 62: prompt itself will also time out if the user's password is not
! 63: entered within C<@password_timeout@> minutes (unless overridden via
! 64: I<sudoers>).
! 65:
! 66: If a user who is not listed in the I<sudoers> file tries to run a
! 67: command via B<sudo>, mail is sent to the proper authorities, as
! 68: defined at configure time or in the I<sudoers> file (defaults to
! 69: C<@mailto@>). Note that the mail will not be sent if an unauthorized
! 70: user tries to run sudo with the B<-l> or B<-v> flags. This allows
! 71: users to determine for themselves whether or not they are allowed
! 72: to use B<sudo>.
! 73:
! 74: If B<sudo> is run by root and the C<SUDO_USER> environment variable
! 75: is set, B<sudo> will use this value to determine who the actual
! 76: user is. This can be used by a user to log commands through sudo
! 77: even when a root shell has been invoked. It also allows the B<-e>
! 78: flag to remain useful even when being run via a sudo-run script or
! 79: program. Note however, that the sudoers lookup is still done for
! 80: root, not the user specified by C<SUDO_USER>.
! 81:
! 82: B<sudo> can log both successful and unsuccessful attempts (as well
! 83: as errors) to syslog(3), a log file, or both. By default B<sudo>
! 84: will log via syslog(3) but this is changeable at configure time
! 85: or via the I<sudoers> file.
! 86:
! 87: =head1 OPTIONS
! 88:
! 89: B<sudo> accepts the following command line options:
! 90:
! 91: =over 4
! 92:
! 93: =item -a
! 94:
! 95: The B<-a> (I<authentication type>) option causes B<sudo> to use the
! 96: specified authentication type when validating the user, as allowed
! 97: by C</etc/login.conf>. The system administrator may specify a list
! 98: of sudo-specific authentication methods by adding an "auth-sudo"
! 99: entry in C</etc/login.conf>. This option is only available on systems
! 100: that support BSD authentication.
! 101:
! 102: =item -b
! 103:
! 104: The B<-b> (I<background>) option tells B<sudo> to run the given
! 105: command in the background. Note that if you use the B<-b>
! 106: option you cannot use shell job control to manipulate the process.
! 107:
! 108: =item -c
! 109:
! 110: The B<-c> (I<class>) option causes B<sudo> to run the specified command
! 111: with resources limited by the specified login class. The I<class>
! 112: argument can be either a class name as defined in C</etc/login.conf>,
! 113: or a single '-' character. Specifying a I<class> of C<-> indicates
! 114: that the command should be run restricted by the default login
! 115: capabilities for the user the command is run as. If the I<class>
! 116: argument specifies an existing user class, the command must be run
! 117: as root, or the B<sudo> command must be run from a shell that is already
! 118: root. This option is only available on systems with BSD login classes.
! 119:
! 120: =item -E
! 121:
! 122: The B<-E> (I<preserve> environment) option will override the
! 123: I<env_reset> option in L<sudoers(5)>). It is only
! 124: available when either the matching command has the C<SETENV> tag
! 125: or the I<setenv> option is set in L<sudoers(5)>.
! 126:
! 127: =item -e
! 128:
! 129: The B<-e> (I<edit>) option indicates that, instead of running
! 130: a command, the user wishes to edit one or more files. In lieu
! 131: of a command, the string "sudoedit" is used when consulting
! 132: the I<sudoers> file. If the user is authorized by I<sudoers>
! 133: the following steps are taken:
! 134:
! 135: =over 8
! 136:
! 137: =item 1.
! 138:
! 139: Temporary copies are made of the files to be edited with the owner
! 140: set to the invoking user.
! 141:
! 142: =item 2.
! 143:
! 144: The editor specified by the C<VISUAL> or C<EDITOR> environment
! 145: variables is run to edit the temporary files. If neither C<VISUAL>
! 146: nor C<EDITOR> are set, the program listed in the I<editor> I<sudoers>
! 147: variable is used.
! 148:
! 149: =item 3.
! 150:
! 151: If they have been modified, the temporary files are copied back to
! 152: their original location and the temporary versions are removed.
! 153:
! 154: =back
! 155:
! 156: If the specified file does not exist, it will be created. Note
! 157: that unlike most commands run by B<sudo>, the editor is run with
! 158: the invoking user's environment unmodified. If, for some reason,
! 159: B<sudo> is unable to update a file with its edited version, the
! 160: user will receive a warning and the edited copy will remain in a
! 161: temporary file.
! 162:
! 163: =item -H
! 164:
! 165: The B<-H> (I<HOME>) option sets the C<HOME> environment variable
! 166: to the homedir of the target user (root by default) as specified
! 167: in passwd(5). By default, B<sudo> does not modify C<HOME>
! 168: (see I<set_home> and I<always_set_home> in L<sudoers(5)>).
! 169:
! 170: =item -h
! 171:
! 172: The B<-h> (I<help>) option causes B<sudo> to print a usage message and exit.
! 173:
! 174: =item -i
! 175:
! 176: The B<-i> (I<simulate initial login>) option runs the shell specified
! 177: in the L<passwd(5)> entry of the user that the command is
! 178: being run as. The command name argument given to the shell begins
! 179: with a `C<->' to tell the shell to run as a login shell. B<sudo>
! 180: attempts to change to that user's home directory before running the
! 181: shell. It also initializes the environment, leaving I<TERM>
! 182: unchanged, setting I<HOME>, I<SHELL>, I<USER>, I<LOGNAME>, and
! 183: I<PATH>, and unsetting all other environment variables. Note that
! 184: because the shell to use is determined before the I<sudoers> file
! 185: is parsed, a I<runas_default> setting in I<sudoers> will specify
! 186: the user to run the shell as but will not affect which shell is
! 187: actually run.
! 188:
! 189: =item -K
! 190:
! 191: The B<-K> (sure I<kill>) option is like B<-k> except that it removes
! 192: the user's timestamp entirely. Like B<-k>, this option does not
! 193: require a password.
! 194:
! 195: =item -k
! 196:
! 197: The B<-k> (I<kill>) option to B<sudo> invalidates the user's timestamp
! 198: by setting the time on it to the Epoch. The next time B<sudo> is
! 199: run a password will be required. This option does not require a password
! 200: and was added to allow a user to revoke B<sudo> permissions from a .logout
! 201: file.
! 202:
! 203: =item -L
! 204:
! 205: The B<-L> (I<list> defaults) option will list out the parameters
! 206: that may be set in a I<Defaults> line along with a short description
! 207: for each. This option is useful in conjunction with L<grep(1)>.
! 208:
! 209: =item -l
! 210:
! 211: The B<-l> (I<list>) option will list out the allowed (and
! 212: forbidden) commands for the invoking user on the current host.
! 213:
! 214: =item -P
! 215:
! 216: The B<-P> (I<preserve> group vector) option causes B<sudo> to
! 217: preserve the invoking user's group vector unaltered. By default,
! 218: B<sudo> will initialize the group vector to the list of groups the
! 219: target user is in. The real and effective group IDs, however, are
! 220: still set to match the target user.
! 221:
! 222: =item -p
! 223:
! 224: The B<-p> (I<prompt>) option allows you to override the default
! 225: password prompt and use a custom one. The following percent (`C<%>')
! 226: escapes are supported:
! 227:
! 228: =over 8
! 229:
! 230: =item C<%H>
! 231:
! 232: expanded to the local hostname including the domain name
! 233: (on if the machine's hostname is fully qualified or the I<fqdn>
! 234: I<sudoers> option is set)
! 235:
! 236: =item C<%h>
! 237:
! 238: expanded to the local hostname without the domain name
! 239:
! 240: =item C<%U>
! 241:
! 242: expanded to the login name of the user the command will
! 243: be run as (defaults to root)
! 244:
! 245: =item C<%u>
! 246:
! 247: expanded to the invoking user's login name
! 248:
! 249: =item C<%%>
! 250:
! 251: two consecutive C<%> characters are collapsed into a single C<%> character
! 252:
! 253: =back
! 254:
! 255: =item -S
! 256:
! 257: The B<-S> (I<stdin>) option causes B<sudo> to read the password from
! 258: the standard input instead of the terminal device.
! 259:
! 260: =item -s
! 261:
! 262: The B<-s> (I<shell>) option runs the shell specified by the I<SHELL>
! 263: environment variable if it is set or the shell as specified
! 264: in L<passwd(5)>.
! 265:
! 266: =item -u
! 267:
! 268: The B<-u> (I<user>) option causes B<sudo> to run the specified command
! 269: as a user other than I<root>. To specify a I<uid> instead of a
! 270: I<username>, use I<#uid>. Note that if the I<targetpw> Defaults
! 271: option is set (see L<sudoers(5)>) it is not possible
! 272: to run commands with a uid not listed in the password database.
! 273:
! 274: =item -V
! 275:
! 276: The B<-V> (I<version>) option causes B<sudo> to print the version
! 277: number and exit. If the invoking user is already root the B<-V>
! 278: option will print out a list of the defaults B<sudo> was compiled
! 279: with as well as the machine's local network addresses.
! 280:
! 281: =item -v
! 282:
! 283: If given the B<-v> (I<validate>) option, B<sudo> will update the
! 284: user's timestamp, prompting for the user's password if necessary.
! 285: This extends the B<sudo> timeout for another C<@timeout@> minutes
! 286: (or whatever the timeout is set to in I<sudoers>) but does not run
! 287: a command.
! 288:
! 289: =item --
! 290:
! 291: The B<--> flag indicates that B<sudo> should stop processing command
! 292: line arguments. It is most useful in conjunction with the B<-s> flag.
! 293:
! 294: =back
! 295:
! 296: Environment variables to be set for the command may also be passed
! 297: on the command line in the form of B<VAR>=I<value>, e.g.
! 298: B<LD_LIBRARY_PATH>=I</usr/local/pkg/lib>. Variables passed on the
! 299: command line are subject to the same restrictions as normal environment
! 300: variables with one important exception. If the I<setenv> option
! 301: is set in I<sudoers> or the command to be run has the C<SETENV> tag
! 302: set the user may set variables that would overwise be forbidden.
! 303: See L<sudoers(5)> for more information.
! 304:
! 305: =head1 RETURN VALUES
! 306:
! 307: Upon successful execution of a program, the return value from B<sudo>
! 308: will simply be the return value of the program that was executed.
! 309:
! 310: Otherwise, B<sudo> quits with an exit value of 1 if there is a
! 311: configuration/permission problem or if B<sudo> cannot execute the
! 312: given command. In the latter case the error string is printed to
! 313: stderr. If B<sudo> cannot L<stat(2)> one or more entries in the user's
! 314: C<PATH> an error is printed on stderr. (If the directory does not
! 315: exist or if it is not really a directory, the entry is ignored and
! 316: no error is printed.) This should not happen under normal
! 317: circumstances. The most common reason for L<stat(2)> to return
! 318: "permission denied" is if you are running an automounter and one
! 319: of the directories in your C<PATH> is on a machine that is currently
! 320: unreachable.
! 321:
! 322: =head1 SECURITY NOTES
! 323:
! 324: B<sudo> tries to be safe when executing external commands.
! 325:
! 326: There are two distinct ways to deal with environment variables.
! 327: By default, the I<env_reset> I<sudoers> option is enabled.
! 328: This causes commands to be executed with a minimal environment
! 329: containing C<TERM>, C<PATH>, C<HOME>, C<SHELL>, C<LOGNAME>, C<USER>
! 330: and C<USERNAME> in addition to variables from the invoking process
! 331: permitted by the I<env_check> and I<env_keep> I<sudoers> options.
! 332: There is effectively a whitelist for environment variables.
! 333:
! 334: If, however, the I<env_reset> option is disabled in I<sudoers>, any
! 335: variables not explicitly denied by the I<env_check> and I<env_delete>
! 336: options are inherited from the invoking process. In this case,
! 337: I<env_check> and I<env_delete> behave like a blacklist. Since it
! 338: is not possible to blacklist all potentially dangerous environment
! 339: variables, use of the default I<env_reset> behavior is encouraged.
! 340:
! 341: In all cases, environment variables with a value beginning with
! 342: C<()> are removed as they could be interpreted as B<bash> functions.
! 343: The list of environment variables that B<sudo> allows or denies is
! 344: contained in the output of C<sudo -V> when run as root.
! 345:
! 346: Note that the dynamic linker on most operating systems will remove
! 347: variables that can control dynamic linking from the environment of
! 348: setuid executables, including B<sudo>. Depending on the operating
! 349: system this may include C<_RLD*>, C<DYLD_*>, C<LD_*>, C<LDR_*>,
! 350: C<LIBPATH>, C<SHLIB_PATH>, and others. These type of variables are
! 351: removed from the environment before B<sudo> even begins execution
! 352: and, as such, it is not possible for B<sudo> to preserve them.
! 353:
! 354: To prevent command spoofing, B<sudo> checks "." and "" (both denoting
! 355: current directory) last when searching for a command in the user's
! 356: PATH (if one or both are in the PATH). Note, however, that the
! 357: actual C<PATH> environment variable is I<not> modified and is passed
! 358: unchanged to the program that B<sudo> executes.
! 359:
! 360: B<sudo> will check the ownership of its timestamp directory
! 361: (F<@timedir@> by default) and ignore the directory's contents if
! 362: it is not owned by root or if it is writable by a user other than
! 363: root. On systems that allow non-root users to give away files via
! 364: L<chown(2)>, if the timestamp directory is located in a directory
! 365: writable by anyone (e.g., F</tmp>), it is possible for a user to
! 366: create the timestamp directory before B<sudo> is run. However,
! 367: because B<sudo> checks the ownership and mode of the directory and
! 368: its contents, the only damage that can be done is to "hide" files
! 369: by putting them in the timestamp dir. This is unlikely to happen
! 370: since once the timestamp dir is owned by root and inaccessible by
! 371: any other user, the user placing files there would be unable to get
! 372: them back out. To get around this issue you can use a directory
! 373: that is not world-writable for the timestamps (F</var/adm/sudo> for
! 374: instance) or create F<@timedir@> with the appropriate owner (root)
! 375: and permissions (0700) in the system startup files.
! 376:
! 377: B<sudo> will not honor timestamps set far in the future.
! 378: Timestamps with a date greater than current_time + 2 * C<TIMEOUT>
! 379: will be ignored and sudo will log and complain. This is done to
! 380: keep a user from creating his/her own timestamp with a bogus
! 381: date on systems that allow users to give away files.
! 382:
! 383: Please note that B<sudo> will normally only log the command it
! 384: explicitly runs. If a user runs a command such as C<sudo su> or
! 385: C<sudo sh>, subsequent commands run from that shell will I<not> be
! 386: logged, nor will B<sudo>'s access control affect them. The same
! 387: is true for commands that offer shell escapes (including most
! 388: editors). Because of this, care must be taken when giving users
! 389: access to commands via B<sudo> to verify that the command does not
! 390: inadvertently give the user an effective root shell. For more
! 391: information, please see the C<PREVENTING SHELL ESCAPES> section in
! 392: L<sudoers(5)>.
! 393:
! 394: =head1 ENVIRONMENT
! 395:
! 396: B<sudo> utilizes the following environment variables:
! 397:
! 398: EDITOR Default editor to use in -e (sudoedit) mode if
! 399: VISUAL is not set
! 400:
! 401: HOME In -s or -H mode (or if sudo was configured with
! 402: the --enable-shell-sets-home option), set to
! 403: homedir of the target user
! 404:
! 405: PATH Set to a sane value if sudo was configured with
! 406: the --with-secure-path option
! 407:
! 408: SHELL Used to determine shell to run with -s option
! 409:
! 410: SUDO_PROMPT Used as the default password prompt
! 411:
! 412: SUDO_COMMAND Set to the command run by sudo
! 413:
! 414: SUDO_USER Set to the login of the user who invoked sudo
! 415:
! 416: SUDO_UID Set to the uid of the user who invoked sudo
! 417:
! 418: SUDO_GID Set to the gid of the user who invoked sudo
! 419:
! 420: SUDO_PS1 If set, PS1 will be set to its value
! 421:
! 422: USER Set to the target user (root unless the -u option
! 423: is specified)
! 424:
! 425: VISUAL Default editor to use in -e (sudoedit) mode
! 426:
! 427: =head1 FILES
! 428:
! 429: @sysconfdir@/sudoers List of who can run what
! 430: @timedir@ Directory containing timestamps
! 431:
! 432: =head1 EXAMPLES
! 433:
! 434: Note: the following examples assume suitable L<sudoers(5)> entries.
! 435:
! 436: To get a file listing of an unreadable directory:
! 437:
! 438: $ sudo ls /usr/local/protected
! 439:
! 440: To list the home directory of user yazza on a machine where the
! 441: file system holding ~yazza is not exported as root:
! 442:
! 443: $ sudo -u yazza ls ~yazza
! 444:
! 445: To edit the F<index.html> file as user www:
! 446:
! 447: $ sudo -u www vi ~www/htdocs/index.html
! 448:
! 449: To shutdown a machine:
! 450:
! 451: $ sudo shutdown -r +15 "quick reboot"
! 452:
! 453: To make a usage listing of the directories in the /home
! 454: partition. Note that this runs the commands in a sub-shell
! 455: to make the C<cd> and file redirection work.
! 456:
! 457: $ sudo sh -c "cd /home ; du -s * | sort -rn > USAGE"
! 458:
! 459: =head1 SEE ALSO
! 460:
! 461: L<grep(1)>, L<su(1)>, L<stat(2)>, L<login_cap(3)>, L<passwd(5)>,
! 462: L<sudoers(5)>, L<visudo(8)>
! 463:
! 464: =head1 AUTHORS
! 465:
! 466: Many people have worked on B<sudo> over the years; this
! 467: version consists of code written primarily by:
! 468:
! 469: Todd C. Miller
! 470: Chris Jepeway
! 471:
! 472: See the HISTORY file in the B<sudo> distribution or visit
! 473: http://www.sudo.ws/sudo/history.html for a short history
! 474: of B<sudo>.
! 475:
! 476: =head1 CAVEATS
! 477:
! 478: There is no easy way to prevent a user from gaining a root shell
! 479: if that user is allowed to run arbitrary commands via B<sudo>.
! 480: Also, many programs (such as editors) allow the user to run commands
! 481: via shell escapes, thus avoiding B<sudo>'s checks. However, on
! 482: most systems it is possible to prevent shell escapes with B<sudo>'s
! 483: I<noexec> functionality. See the L<sudoers(5)> manual
! 484: for details.
! 485:
! 486: It is not meaningful to run the C<cd> command directly via sudo, e.g.,
! 487:
! 488: $ sudo cd /usr/local/protected
! 489:
! 490: since when the command exits the parent process (your shell) will
! 491: still be the same. Please see the EXAMPLES section for more information.
! 492:
! 493: If users have sudo C<ALL> there is nothing to prevent them from
! 494: creating their own program that gives them a root shell regardless
! 495: of any '!' elements in the user specification.
! 496:
! 497: Running shell scripts via B<sudo> can expose the same kernel bugs that
! 498: make setuid shell scripts unsafe on some operating systems (if your OS
! 499: has a /dev/fd/ directory, setuid shell scripts are generally safe).
! 500:
! 501: =head1 BUGS
! 502:
! 503: If you feel you have found a bug in B<sudo>, please submit a bug report
! 504: at http://www.sudo.ws/sudo/bugs/
! 505:
! 506: =head1 SUPPORT
! 507:
! 508: Limited free support is available via the sudo-users mailing list,
! 509: see http://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or
! 510: search the archives.
! 511:
! 512: =head1 DISCLAIMER
! 513:
! 514: B<sudo> is provided ``AS IS'' and any express or implied warranties,
! 515: including, but not limited to, the implied warranties of merchantability
! 516: and fitness for a particular purpose are disclaimed. See the LICENSE
! 517: file distributed with B<sudo> or http://www.sudo.ws/sudo/license.html
! 518: for complete details.
![[BACK]](/icons/back.gif){kind=icon}
Return to sudo.pod CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / sudo