Annotation of embedaddon/sudo/doc/sudo.pod, revision 1.1
1.1 ! misho 1: Copyright (c) 1994-1996, 1998-2005, 2007-2011
! 2: 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: =pod
! 22:
! 23: =head1 NAME
! 24:
! 25: sudo, sudoedit - execute a command as another user
! 26:
! 27: =head1 SYNOPSIS
! 28:
! 29: B<sudo> S<[B<-D> I<level>]> B<-h> | B<-K> | B<-k> | B<-V>
! 30:
! 31: B<sudo> B<-v> [B<-AknS>]
! 32: S<[B<-a> I<auth_type>]>
! 33: S<[B<-D> I<level>]>
! 34: S<[B<-g> I<group name>|I<#gid>]> S<[B<-p> I<prompt>]>
! 35: S<[B<-u> I<user name>|I<#uid>]>
! 36:
! 37: B<sudo> B<-l[l]> [B<-AknS>]
! 38: S<[B<-a> I<auth_type>]>
! 39: S<[B<-D> I<level>]>
! 40: S<[B<-g> I<group name>|I<#gid>]> S<[B<-p> I<prompt>]>
! 41: S<[B<-U> I<user name>]> S<[B<-u> I<user name>|I<#uid>]> [I<command>]
! 42:
! 43: B<sudo> [B<-AbEHnPS>]
! 44: S<[B<-a> I<auth_type>]>
! 45: S<[B<-C> I<fd>]>
! 46: S<[B<-D> I<level>]>
! 47: S<[B<-c> I<class>|I<->]>
! 48: S<[B<-g> I<group name>|I<#gid>]> S<[B<-p> I<prompt>]>
! 49: S<[B<-r> I<role>]> S<[B<-t> I<type>]>
! 50: S<[B<-u> I<user name>|I<#uid>]>
! 51: S<[B<VAR>=I<value>]> S<[B<-i> | B<-s>]> [I<command>]
! 52:
! 53: B<sudoedit> [B<-AnS>]
! 54: S<[B<-a> I<auth_type>]>
! 55: S<[B<-C> I<fd>]>
! 56: S<[B<-c> I<class>|I<->]>
! 57: S<[B<-D> I<level>]>
! 58: S<[B<-g> I<group name>|I<#gid>]> S<[B<-p> I<prompt>]>
! 59: S<[B<-u> I<user name>|I<#uid>]> file ...
! 60:
! 61: =head1 DESCRIPTION
! 62:
! 63: B<sudo> allows a permitted user to execute a I<command> as the
! 64: superuser or another user, as specified by the security policy.
! 65: The real and effective uid and gid are set to match those of the
! 66: target user, as specified in the password database, and the group
! 67: vector is initialized based on the group database (unless the B<-P>
! 68: option was specified).
! 69:
! 70: B<sudo> supports a plugin architecture for security policies and
! 71: input/output logging. Third parties can develop and distribute
! 72: their own policy and I/O logging modules to work seemlessly with
! 73: the B<sudo> front end. The default security policy is I<sudoers>,
! 74: which is configured via the file F<@sysconfdir@/sudoers>, or via
! 75: LDAP. See the L<PLUGINS> section for more information.
! 76:
! 77: The security policy determines what privileges, if any, a user has
! 78: to run B<sudo>. The policy may require that users authenticate
! 79: themselves with a password or another authentication mechanism. If
! 80: authentication is required, B<sudo> will exit if the user's password
! 81: is not entered within a configurable time limit. This limit is
! 82: policy-specific; the default password prompt timeout for the
! 83: I<sudoers> security policy is C<@password_timeout@> minutes.
! 84:
! 85: Security policies may support credential caching to allow the user
! 86: to run B<sudo> again for a period of time without requiring
! 87: authentication. The I<sudoers> policy caches credentials for
! 88: C<@timeout@> minutes, unless overridden in L<sudoers(5)>. By
! 89: running B<sudo> with the B<-v> option, a user can update the cached
! 90: credentials without running a I<command>.
! 91:
! 92: When invoked as B<sudoedit>, the B<-e> option (described below),
! 93: is implied.
! 94:
! 95: Security policies may log successful and failed attempts to use
! 96: B<sudo>. If an I/O plugin is configured, the running command's
! 97: input and output may be logged as well.
! 98:
! 99: =head1 OPTIONS
! 100:
! 101: B<sudo> accepts the following command line options:
! 102:
! 103: =over 12
! 104:
! 105: =item -A
! 106:
! 107: Normally, if B<sudo> requires a password, it will read it from the
! 108: user's terminal. If the B<-A> (I<askpass>) option is specified,
! 109: a (possibly graphical) helper program is executed to read the user's
! 110: password and output the password to the standard output. If the
! 111: C<SUDO_ASKPASS> environment variable is set, it specifies the path
! 112: to the helper program. Otherwise, if F<@sysconfdir@/sudo.conf>
! 113: contains a line specifying the askpass program, that value will be
! 114: used. For example:
! 115:
! 116: # Path to askpass helper program
! 117: Path askpass /usr/X11R6/bin/ssh-askpass
! 118:
! 119: If no askpass program is available, sudo will exit with an error.
! 120:
! 121: =item -a I<type>
! 122:
! 123: The B<-a> (I<authentication type>) option causes B<sudo> to use the
! 124: specified authentication type when validating the user, as allowed
! 125: by F</etc/login.conf>. The system administrator may specify a list
! 126: of sudo-specific authentication methods by adding an "auth-sudo"
! 127: entry in F</etc/login.conf>. This option is only available on systems
! 128: that support BSD authentication.
! 129:
! 130: =item -b
! 131:
! 132: The B<-b> (I<background>) option tells B<sudo> to run the given
! 133: command in the background. Note that if you use the B<-b>
! 134: option you cannot use shell job control to manipulate the process.
! 135: Most interactive commands will fail to work properly in background
! 136: mode.
! 137:
! 138: =item -C I<fd>
! 139:
! 140: Normally, B<sudo> will close all open file descriptors other than
! 141: standard input, standard output and standard error. The B<-C>
! 142: (I<close from>) option allows the user to specify a starting point
! 143: above the standard error (file descriptor three). Values less than
! 144: three are not permitted. The security policy may restrict the
! 145: user's ability to use the B<-C> option. The I<sudoers> policy only
! 146: permits use of the B<-C> option when the administrator has enabled
! 147: the I<closefrom_override> option.
! 148:
! 149: =item -c I<class>
! 150:
! 151: The B<-c> (I<class>) option causes B<sudo> to run the specified command
! 152: with resources limited by the specified login class. The I<class>
! 153: argument can be either a class name as defined in F</etc/login.conf>,
! 154: or a single '-' character. Specifying a I<class> of C<-> indicates
! 155: that the command should be run restricted by the default login
! 156: capabilities for the user the command is run as. If the I<class>
! 157: argument specifies an existing user class, the command must be run
! 158: as root, or the B<sudo> command must be run from a shell that is already
! 159: root. This option is only available on systems with BSD login classes.
! 160:
! 161: =item -D I<level>
! 162:
! 163: Enable debugging of B<sudo> plugins and B<sudo> itself. The I<level>
! 164: may be a value from 1 through 9.
! 165:
! 166: =item -E
! 167:
! 168: The B<-E> (I<preserve> I<environment>) option indicates to the
! 169: security policy that the user wishes to preserve their existing
! 170: environment variables. The security policy may return an error if
! 171: the B<-E> option is specified and the user does not have permission
! 172: to preserve the environment.
! 173:
! 174: =item -e
! 175:
! 176: The B<-e> (I<edit>) option indicates that, instead of running a
! 177: command, the user wishes to edit one or more files. In lieu of a
! 178: command, the string "sudoedit" is used when consulting the security
! 179: policy. If the user is authorized by the policy, the following
! 180: steps are taken:
! 181:
! 182: =over 4
! 183:
! 184: =item 1.
! 185:
! 186: Temporary copies are made of the files to be edited with the owner
! 187: set to the invoking user.
! 188:
! 189: =item 2.
! 190:
! 191: The editor specified by the policy is run to edit the temporary files.
! 192: The I<sudoers> policy uses the C<SUDO_EDITOR>, C<VISUAL> and C<EDITOR>
! 193: environment variables (in that order). If none of C<SUDO_EDITOR>,
! 194: C<VISUAL> or C<EDITOR> are set, the first program listed in the
! 195: I<editor> L<sudoers(5)> option is used.
! 196:
! 197: =item 3.
! 198:
! 199: If they have been modified, the temporary files are copied back to
! 200: their original location and the temporary versions are removed.
! 201:
! 202: =back
! 203:
! 204: If the specified file does not exist, it will be created. Note
! 205: that unlike most commands run by B<sudo>, the editor is run with
! 206: the invoking user's environment unmodified. If, for some reason,
! 207: B<sudo> is unable to update a file with its edited version, the
! 208: user will receive a warning and the edited copy will remain in a
! 209: temporary file.
! 210:
! 211: =item -g I<group>
! 212:
! 213: Normally, B<sudo> runs a command with the primary group set to the
! 214: one specified by the password database for the user the command is
! 215: being run as (by default, root). The B<-g> (I<group>) option causes
! 216: B<sudo> to run the command with the primary group set to I<group>
! 217: instead. To specify a I<gid> instead of a I<group name>, use
! 218: I<#gid>. When running commands as a I<gid>, many shells require
! 219: that the '#' be escaped with a backslash ('\'). If no B<-u> option
! 220: is specified, the command will be run as the invoking user (not
! 221: root). In either case, the primary group will be set to I<group>.
! 222:
! 223: =item -H
! 224:
! 225: The B<-H> (I<HOME>) option requests that the security policy set
! 226: the C<HOME> environment variable to the home directory of the target
! 227: user (root by default) as specified by the password database.
! 228: Depending on the policy, this may be the default behavior.
! 229:
! 230: =item -h
! 231:
! 232: The B<-h> (I<help>) option causes B<sudo> to print a short help message
! 233: to the standard output and exit.
! 234:
! 235: =item -i [command]
! 236:
! 237: The B<-i> (I<simulate initial login>) option runs the shell specified
! 238: by the password database entry of the target user as a login shell.
! 239: This means that login-specific resource files such as C<.profile>
! 240: or C<.login> will be read by the shell. If a command is specified,
! 241: it is passed to the shell for execution via the shell's B<-c> option.
! 242: If no command is specified, an interactive shell is executed.
! 243: B<sudo> attempts to change to that user's home directory before
! 244: running the shell. The security policy shall initialize the
! 245: environment to a minimal set of variables, similar to what is present
! 246: when a user logs in. The I<Command Environment> section in the
! 247: L<sudoers(5)> manual documents how the B<-i> option affects the
! 248: environment in which a command is run when the I<sudoers> policy
! 249: is in use.
! 250:
! 251: =item -K
! 252:
! 253: The B<-K> (sure I<kill>) option is like B<-k> except that it removes
! 254: the user's cached credentials entirely and may not be used in
! 255: conjunction with a command or other option. This option does not
! 256: require a password. Not all security policies support credential
! 257: caching.
! 258:
! 259: =item -k [command]
! 260:
! 261: When used alone, the B<-k> (I<kill>) option to B<sudo> invalidates
! 262: the user's cached credentials. The next time B<sudo> is run a
! 263: password will be required. This option does not require a password
! 264: and was added to allow a user to revoke B<sudo> permissions from a
! 265: .logout file. Not all security policies support credential
! 266: caching.
! 267:
! 268: When used in conjunction with a command or an option that may require
! 269: a password, the B<-k> option will cause B<sudo> to ignore the user's
! 270: cached credentials. As a result, B<sudo> will prompt for a password
! 271: (if one is required by the security policy) and will not update the
! 272: user's cached credentials.
! 273:
! 274: =item -l[l] [I<command>]
! 275:
! 276: If no I<command> is specified, the B<-l> (I<list>) option will list
! 277: the allowed (and forbidden) commands for the invoking user (or the
! 278: user specified by the B<-U> option) on the current host. If a
! 279: I<command> is specified and is permitted by the security policy,
! 280: the fully-qualified path to the command is displayed along with any
! 281: command line arguments. If I<command> is specified but not allowed,
! 282: B<sudo> will exit with a status value of 1. If the B<-l> option
! 283: is specified with an B<l> argument (i.e. B<-ll>), or if B<-l> is
! 284: specified multiple times, a longer list format is used.
! 285:
! 286: =item -n
! 287:
! 288: The B<-n> (I<non-interactive>) option prevents B<sudo> from prompting
! 289: the user for a password. If a password is required for the command
! 290: to run, B<sudo> will display an error messages and exit.
! 291:
! 292: =item -P
! 293:
! 294: The B<-P> (I<preserve> I<group vector>) option causes B<sudo> to
! 295: preserve the invoking user's group vector unaltered. By default,
! 296: the I<sudoers> policy will initialize the group vector to the list
! 297: of groups the target user is in. The real and effective group IDs,
! 298: however, are still set to match the target user.
! 299:
! 300: =item -p I<prompt>
! 301:
! 302: The B<-p> (I<prompt>) option allows you to override the default
! 303: password prompt and use a custom one. The following percent (`C<%>')
! 304: escapes are supported by the I<sudoers> policy:
! 305:
! 306: =over 4
! 307:
! 308: =item C<%H>
! 309:
! 310: expanded to the host name including the domain name (on if
! 311: the machine's host name is fully qualified or the I<fqdn> option
! 312: is set in L<sudoers(5)>)
! 313:
! 314: =item C<%h>
! 315:
! 316: expanded to the local host name without the domain name
! 317:
! 318: =item C<%p>
! 319:
! 320: expanded to the name of the user whose password is being requested
! 321: (respects the I<rootpw>, I<targetpw> and I<runaspw> flags in
! 322: L<sudoers(5)>)
! 323:
! 324: =item C<%U>
! 325:
! 326: expanded to the login name of the user the command will be run as
! 327: (defaults to root unless the C<-u> option is also specified)
! 328:
! 329: =item C<%u>
! 330:
! 331: expanded to the invoking user's login name
! 332:
! 333: =item C<%%>
! 334:
! 335: two consecutive C<%> characters are collapsed into a single C<%> character
! 336:
! 337: =back
! 338:
! 339: The prompt specified by the B<-p> option will override the system
! 340: password prompt on systems that support PAM unless the
! 341: I<passprompt_override> flag is disabled in I<sudoers>.
! 342:
! 343: =item -r I<role>
! 344:
! 345: The B<-r> (I<role>) option causes the new (SELinux) security context to
! 346: have the role specified by I<role>.
! 347:
! 348: =item -S
! 349:
! 350: The B<-S> (I<stdin>) option causes B<sudo> to read the password from
! 351: the standard input instead of the terminal device. The password must
! 352: be followed by a newline character.
! 353:
! 354: =item -s [command]
! 355:
! 356: The B<-s> (I<shell>) option runs the shell specified by the I<SHELL>
! 357: environment variable if it is set or the shell as specified in the
! 358: password database. If a command is specified, it is passed to the
! 359: shell for execution via the shell's B<-c> option. If no command
! 360: is specified, an interactive shell is executed.
! 361:
! 362: =item -t I<type>
! 363:
! 364: The B<-t> (I<type>) option causes the new (SELinux) security context to
! 365: have the type specified by I<type>. If no type is specified, the default
! 366: type is derived from the specified role.
! 367:
! 368: =item -U I<user>
! 369:
! 370: The B<-U> (I<other user>) option is used in conjunction with the
! 371: B<-l> option to specify the user whose privileges should be listed.
! 372: The security policy may restrict listing other users' privileges.
! 373: The I<sudoers> policy only allows root or a user with the C<ALL>
! 374: privilege on the current host to use this option.
! 375:
! 376: =item -u I<user>
! 377:
! 378: The B<-u> (I<user>) option causes B<sudo> to run the specified
! 379: command as a user other than I<root>. To specify a I<uid> instead
! 380: of a I<user name>, use I<#uid>. When running commands as a I<uid>,
! 381: many shells require that the '#' be escaped with a backslash ('\').
! 382: Security policies may restrict I<uid>s to those listed in the
! 383: password database. The I<sudoers> policy allows I<uid>s that are
! 384: not in the password database as long as the I<targetpw> option is
! 385: not set. Other security policies may not support this.
! 386:
! 387: =item -V
! 388:
! 389: The B<-V> (I<version>) option causes B<sudo> to print its version
! 390: string and the version string of the security policy plugin and any
! 391: I/O plugins. If the invoking user is already root the B<-V> option
! 392: will display the arguments passed to configure when I<sudo> was
! 393: built and plugins may display more verbose information such as
! 394: default options.
! 395:
! 396: =item -v
! 397:
! 398: When given the B<-v> (I<validate>) option, B<sudo> will update the
! 399: user's cached credentials, authenticating the user's password if
! 400: necessary. For the I<sudoers> plugin, this extends the B<sudo>
! 401: timeout for another C<@timeout@> minutes (or whatever the timeout
! 402: is set to in I<sudoers>) but does not run a command. Not all
! 403: security policies support cached credentials.
! 404:
! 405: =item --
! 406:
! 407: The B<--> option indicates that B<sudo> should stop processing command
! 408: line arguments.
! 409:
! 410: =back
! 411:
! 412: Environment variables to be set for the command may also be passed
! 413: on the command line in the form of B<VAR>=I<value>, e.g.
! 414: B<LD_LIBRARY_PATH>=I</usr/local/pkg/lib>. Variables passed on the
! 415: command line are subject to the same restrictions as normal environment
! 416: variables with one important exception. If the I<setenv> option
! 417: is set in I<sudoers>, the command to be run has the C<SETENV> tag
! 418: set or the command matched is C<ALL>, the user may set variables
! 419: that would overwise be forbidden. See L<sudoers(5)> for more information.
! 420:
! 421: =head1 PLUGINS
! 422:
! 423: Plugins are dynamically loaded based on the contents of the
! 424: F<@sysconfdir@/sudo.conf> file. If no F<@sysconfdir@/sudo.conf>
! 425: file is present, or it contains no C<Plugin> lines, B<sudo>
! 426: will use the traditional I<sudoers> security policy and I/O logging,
! 427: which corresponds to the following F<@sysconfdir@/sudo.conf> file.
! 428:
! 429: #
! 430: # Default @sysconfdir@/sudo.conf file
! 431: #
! 432: # Format:
! 433: # Plugin plugin_name plugin_path
! 434: # Path askpass /path/to/askpass
! 435: # Path noexec /path/to/noexec.so
! 436: #
! 437: # The plugin_path is relative to @prefix@/libexec unless
! 438: # fully qualified.
! 439: # The plugin_name corresponds to a global symbol in the plugin
! 440: # that contains the plugin interface structure.
! 441: #
! 442: Plugin policy_plugin sudoers.so
! 443: Plugin io_plugin sudoers.so
! 444:
! 445: A C<Plugin> line consists of the C<Plugin> keyword, followed by the
! 446: I<symbol_name> and the I<path> to the shared object containing the
! 447: plugin. The I<symbol_name> is the name of the C<struct policy_plugin>
! 448: or C<struct io_plugin> in the plugin shared object. The I<path>
! 449: may be fully qualified or relative. If not fully qualified it is
! 450: relative to the F<@prefix@/libexec> directory. Any additional
! 451: parameters after the I<path> are ignored. Lines that don't begin
! 452: with C<Plugin> or C<Path> are silently ignored
! 453:
! 454: For more information, see the L<sudo_plugin(8)> manual.
! 455:
! 456: =head1 PATHS
! 457:
! 458: A C<Path> line consists of the C<Path> keyword, followed by the
! 459: name of the path to set and its value. E.g.
! 460:
! 461: Path noexec @noexec_file@
! 462: Path askpass /usr/X11R6/bin/ssh-askpass
! 463:
! 464: The following plugin-agnostic paths may be set in the
! 465: F<@sysconfdir@/sudo.conf> file.
! 466:
! 467: =over 16
! 468:
! 469: =item askpass
! 470:
! 471: The fully qualified path to a helper program used to read the user's
! 472: password when no terminal is available. This may be the case when
! 473: B<sudo> is executed from a graphical (as opposed to text-based)
! 474: application. The program specified by I<askpass> should display
! 475: the argument passed to it as the prompt and write the user's password
! 476: to the standard output. The value of I<askpass> may be overridden
! 477: by the C<SUDO_ASKPASS> environment variable.
! 478:
! 479: =item noexec
! 480:
! 481: The fully-qualified path to a shared library containing dummy
! 482: versions of the execv(), execve() and fexecve() library functions
! 483: that just return an error. This is used to implement the I<noexec>
! 484: functionality on systems that support C<LD_PRELOAD> or its equivalent.
! 485: Defaults to F<@noexec_file@>.
! 486:
! 487: =back
! 488:
! 489: =head1 RETURN VALUES
! 490:
! 491: Upon successful execution of a program, the exit status from B<sudo>
! 492: will simply be the exit status of the program that was executed.
! 493:
! 494: Otherwise, B<sudo> exits with a value of 1 if there is a
! 495: configuration/permission problem or if B<sudo> cannot execute the
! 496: given command. In the latter case the error string is printed to
! 497: the standard error. If B<sudo> cannot L<stat(2)> one or more entries
! 498: in the user's C<PATH>, an error is printed on stderr. (If the
! 499: directory does not exist or if it is not really a directory, the
! 500: entry is ignored and no error is printed.) This should not happen
! 501: under normal circumstances. The most common reason for L<stat(2)>
! 502: to return "permission denied" is if you are running an automounter
! 503: and one of the directories in your C<PATH> is on a machine that is
! 504: currently unreachable.
! 505:
! 506: =head1 SECURITY NOTES
! 507:
! 508: B<sudo> tries to be safe when executing external commands.
! 509:
! 510: To prevent command spoofing, B<sudo> checks "." and "" (both denoting
! 511: current directory) last when searching for a command in the user's
! 512: PATH (if one or both are in the PATH). Note, however, that the
! 513: actual C<PATH> environment variable is I<not> modified and is passed
! 514: unchanged to the program that B<sudo> executes.
! 515:
! 516: Please note that B<sudo> will normally only log the command it
! 517: explicitly runs. If a user runs a command such as C<sudo su> or
! 518: C<sudo sh>, subsequent commands run from that shell are not subject
! 519: to B<sudo>'s security policy. The same is true for commands that
! 520: offer shell escapes (including most editors). If I/O logging is
! 521: enabled, subsequent commands will have their input and/or output
! 522: logged, but there will not be traditional logs for those commands.
! 523: Because of this, care must be taken when giving users access to
! 524: commands via B<sudo> to verify that the command does not inadvertently
! 525: give the user an effective root shell. For more information, please
! 526: see the C<PREVENTING SHELL ESCAPES> section in L<sudoers(5)>.
! 527:
! 528: =head1 ENVIRONMENT
! 529:
! 530: B<sudo> utilizes the following environment variables. The security
! 531: policy has control over the content of the command's environment.
! 532:
! 533: =over 16
! 534:
! 535: =item C<EDITOR>
! 536:
! 537: Default editor to use in B<-e> (sudoedit) mode if neither C<SUDO_EDITOR>
! 538: nor C<VISUAL> is set
! 539:
! 540: =item C<MAIL>
! 541:
! 542: In B<-i> mode or when I<env_reset> is enabled in I<sudoers>, set
! 543: to the mail spool of the target user
! 544:
! 545: =item C<HOME>
! 546:
! 547: Set to the home directory of the target user if B<-i> or B<-H> are
! 548: specified, I<env_reset> or I<always_set_home> are set in I<sudoers>,
! 549: or when the B<-s> option is specified and I<set_home> is set in
! 550: I<sudoers>
! 551:
! 552: =item C<PATH>
! 553:
! 554: May be overridden by the security policy.
! 555:
! 556: =item C<SHELL>
! 557:
! 558: Used to determine shell to run with C<-s> option
! 559:
! 560: =item C<SUDO_ASKPASS>
! 561:
! 562: Specifies the path to a helper program used to read the password
! 563: if no terminal is available or if the C<-A> option is specified.
! 564:
! 565: =item C<SUDO_COMMAND>
! 566:
! 567: Set to the command run by sudo
! 568:
! 569: =item C<SUDO_EDITOR>
! 570:
! 571: Default editor to use in B<-e> (sudoedit) mode
! 572:
! 573: =item C<SUDO_GID>
! 574:
! 575: Set to the group ID of the user who invoked sudo
! 576:
! 577: =item C<SUDO_PROMPT>
! 578:
! 579: Used as the default password prompt
! 580:
! 581: =item C<SUDO_PS1>
! 582:
! 583: If set, C<PS1> will be set to its value for the program being run
! 584:
! 585: =item C<SUDO_UID>
! 586:
! 587: Set to the user ID of the user who invoked sudo
! 588:
! 589: =item C<SUDO_USER>
! 590:
! 591: Set to the login of the user who invoked sudo
! 592:
! 593: =item C<USER>
! 594:
! 595: Set to the target user (root unless the B<-u> option is specified)
! 596:
! 597: =item C<VISUAL>
! 598:
! 599: Default editor to use in B<-e> (sudoedit) mode if C<SUDO_EDITOR>
! 600: is not set
! 601:
! 602: =back
! 603:
! 604: =head1 FILES
! 605:
! 606: =over 24
! 607:
! 608: =item F<@sysconfdir@/sudo.conf>
! 609:
! 610: B<sudo> plugin and path configuration
! 611:
! 612: =back
! 613:
! 614: =head1 EXAMPLES
! 615:
! 616: Note: the following examples assume a properly configured security policy.
! 617:
! 618: To get a file listing of an unreadable directory:
! 619:
! 620: $ sudo ls /usr/local/protected
! 621:
! 622: To list the home directory of user yaz on a machine where the
! 623: file system holding ~yaz is not exported as root:
! 624:
! 625: $ sudo -u yaz ls ~yaz
! 626:
! 627: To edit the F<index.html> file as user www:
! 628:
! 629: $ sudo -u www vi ~www/htdocs/index.html
! 630:
! 631: To view system logs only accessible to root and users in the adm group:
! 632:
! 633: $ sudo -g adm view /var/log/syslog
! 634:
! 635: To run an editor as jim with a different primary group:
! 636:
! 637: $ sudo -u jim -g audio vi ~jim/sound.txt
! 638:
! 639: To shutdown a machine:
! 640:
! 641: $ sudo shutdown -r +15 "quick reboot"
! 642:
! 643: To make a usage listing of the directories in the /home
! 644: partition. Note that this runs the commands in a sub-shell
! 645: to make the C<cd> and file redirection work.
! 646:
! 647: $ sudo sh -c "cd /home ; du -s * | sort -rn > USAGE"
! 648:
! 649: =head1 SEE ALSO
! 650:
! 651: L<grep(1)>, L<su(1)>, L<stat(2)>,
! 652: L<login_cap(3)>,
! 653: L<passwd(5)>, L<sudoers(5)>, L<sudo_plugin(8)>, L<sudoreplay(8)>, L<visudo(8)>
! 654:
! 655: =head1 AUTHORS
! 656:
! 657: Many people have worked on B<sudo> over the years; this
! 658: version consists of code written primarily by:
! 659:
! 660: Todd C. Miller
! 661:
! 662: See the HISTORY file in the B<sudo> distribution or visit
! 663: http://www.sudo.ws/sudo/history.html for a short history
! 664: of B<sudo>.
! 665:
! 666: =head1 CAVEATS
! 667:
! 668: There is no easy way to prevent a user from gaining a root shell
! 669: if that user is allowed to run arbitrary commands via B<sudo>.
! 670: Also, many programs (such as editors) allow the user to run commands
! 671: via shell escapes, thus avoiding B<sudo>'s checks. However, on
! 672: most systems it is possible to prevent shell escapes with the
! 673: L<sudoers(5)> module's I<noexec> functionality.
! 674:
! 675: It is not meaningful to run the C<cd> command directly via sudo, e.g.,
! 676:
! 677: $ sudo cd /usr/local/protected
! 678:
! 679: since when the command exits the parent process (your shell) will
! 680: still be the same. Please see the EXAMPLES section for more information.
! 681:
! 682: Running shell scripts via B<sudo> can expose the same kernel bugs that
! 683: make setuid shell scripts unsafe on some operating systems (if your OS
! 684: has a /dev/fd/ directory, setuid shell scripts are generally safe).
! 685:
! 686: =head1 BUGS
! 687:
! 688: If you feel you have found a bug in B<sudo>, please submit a bug report
! 689: at http://www.sudo.ws/sudo/bugs/
! 690:
! 691: =head1 SUPPORT
! 692:
! 693: Limited free support is available via the sudo-users mailing list,
! 694: see http://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or
! 695: search the archives.
! 696:
! 697: =head1 DISCLAIMER
! 698:
! 699: B<sudo> is provided ``AS IS'' and any express or implied warranties,
! 700: including, but not limited to, the implied warranties of merchantability
! 701: and fitness for a particular purpose are disclaimed. See the LICENSE
! 702: file distributed with B<sudo> or http://www.sudo.ws/sudo/license.html
! 703: for complete details.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>