Annotation of embedaddon/sudo/doc/sudo.mdoc.in, revision 1.1
1.1 ! misho 1: .\"
! 2: .\" Copyright (c) 1994-1996, 1998-2005, 2007-2012
! 3: .\" Todd C. Miller <Todd.Miller@courtesan.com>
! 4: .\"
! 5: .\" Permission to use, copy, modify, and distribute this software for any
! 6: .\" purpose with or without fee is hereby granted, provided that the above
! 7: .\" copyright notice and this permission notice appear in all copies.
! 8: .\"
! 9: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
! 10: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
! 11: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
! 12: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
! 13: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
! 14: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
! 15: .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
! 16: .\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
! 17: .\"
! 18: .\" Sponsored in part by the Defense Advanced Research Projects
! 19: .\" Agency (DARPA) and Air Force Research Laboratory, Air Force
! 20: .\" Materiel Command, USAF, under agreement number F39502-99-1-0512.
! 21: .\"
! 22: .Dd July 10, 2012
! 23: .Dt SUDO @mansectsu@
! 24: .Os Sudo @PACKAGE_VERSION@
! 25: .Sh NAME
! 26: .Nm sudo ,
! 27: .Nm sudoedit
! 28: .Nd execute a command as another user
! 29: .Sh SYNOPSIS
! 30: .Nm sudo
! 31: .Fl h No | Fl K No | Fl k No | Fl V
! 32: .Nm sudo
! 33: .Fl v
! 34: .Op Fl AknS
! 35: .Bk -words
! 36: .Op Fl a Ar auth_type
! 37: .Ek
! 38: .Bk -words
! 39: .Op Fl g Ar group name No | Ar #gid
! 40: .Ek
! 41: .Bk -words
! 42: .Op Fl p Ar prompt
! 43: .Ek
! 44: .Bk -words
! 45: .Op Fl u Ar user name No | Ar #uid
! 46: .Ek
! 47: .Nm sudo
! 48: .Fl l Ns Op Ar l
! 49: .Op Fl AknS
! 50: .Bk -words
! 51: .Op Fl a Ar auth_type
! 52: .Ek
! 53: .Bk -words
! 54: .Op Fl g Ar group name No | Ar #gid
! 55: .Ek
! 56: .Bk -words
! 57: .Op Fl p Ar prompt
! 58: .Ek
! 59: .Bk -words
! 60: .Op Fl U Ar user name
! 61: .Ek
! 62: .Bk -words
! 63: .Op Fl u Ar user name No | Ar #uid
! 64: .Ek
! 65: .Op Ar command
! 66: .Nm sudo
! 67: .Op Fl AbEHnPS
! 68: .Bk -words
! 69: .Op Fl a Ar auth_type
! 70: .Ek
! 71: .Bk -words
! 72: .Op Fl C Ar fd
! 73: .Ek
! 74: .Bk -words
! 75: .Op Fl c Ar class No | Ar -
! 76: .Ek
! 77: .Bk -words
! 78: .Op Fl g Ar group name No | Ar #gid
! 79: .Ek
! 80: .Bk -words
! 81: .Op Fl p Ar prompt
! 82: .Ek
! 83: .Bk -words
! 84: .Op Fl r Ar role
! 85: .Ek
! 86: .Bk -words
! 87: .Op Fl t Ar type
! 88: .Ek
! 89: .Bk -words
! 90: .Op Fl u Ar user name No | Ar #uid
! 91: .Ek
! 92: .Bk -words
! 93: .Op Sy VAR Ns = Ns Ar value
! 94: .Ek
! 95: .Bk -words
! 96: .Fl i No | Fl s
! 97: .Ek
! 98: .Op Ar command
! 99: .Nm sudoedit
! 100: .Op Fl AnS
! 101: .Bk -words
! 102: .Op Fl a Ar auth_type
! 103: .Ek
! 104: .Bk -words
! 105: .Op Fl C Ar fd
! 106: .Ek
! 107: .Bk -words
! 108: .Op Fl c Ar class No | Ar -
! 109: .Ek
! 110: .Bk -words
! 111: .Op Fl g Ar group name No | Ar #gid
! 112: .Ek
! 113: .Bk -words
! 114: .Op Fl p Ar prompt
! 115: .Ek
! 116: .Bk -words
! 117: .Op Fl u Ar user name No | Ar #uid
! 118: .Ek
! 119: .Bk -words
! 120: file ...
! 121: .Ek
! 122: .Sh DESCRIPTION
! 123: .Nm sudo
! 124: allows a permitted user to execute a
! 125: .Ar command
! 126: as the superuser or another user, as specified by the security
! 127: policy.
! 128: .Pp
! 129: .Nm sudo
! 130: supports a plugin architecture for security policies and input/output
! 131: logging.
! 132: Third parties can develop and distribute their own policy and I/O
! 133: logging plugins to work seamlessly with the
! 134: .Nm sudo
! 135: front end.
! 136: The default security policy is
! 137: .Em sudoers ,
! 138: which is configured via the file
! 139: .Pa @sysconfdir@/sudoers ,
! 140: or via LDAP.
! 141: See the
! 142: .Sx PLUGINS
! 143: section for more information.
! 144: .Pp
! 145: The security policy determines what privileges, if any, a user has
! 146: to run
! 147: .Nm sudo .
! 148: The policy may require that users authenticate themselves with a
! 149: password or another authentication mechanism.
! 150: If authentication is required,
! 151: .Nm sudo
! 152: will exit if the user's password is not entered within a configurable
! 153: time limit.
! 154: This limit is policy-specific; the default password prompt timeout
! 155: for the
! 156: .Em sudoers
! 157: security policy is
! 158: .Li @password_timeout@
! 159: minutes.
! 160: .Pp
! 161: Security policies may support credential caching to allow the user
! 162: to run
! 163: .Nm sudo
! 164: again for a period of time without requiring authentication.
! 165: The
! 166: .Em sudoers
! 167: policy caches credentials for
! 168: .Li @timeout@
! 169: minutes, unless overridden in
! 170: .Xr sudoers @mansectform@ .
! 171: By running
! 172: .Nm sudo
! 173: with the
! 174: .Fl v
! 175: option, a user can update the cached credentials without running a
! 176: .Ar command .
! 177: .Pp
! 178: When invoked as
! 179: .Nm sudoedit ,
! 180: the
! 181: .Fl e
! 182: option (described below), is implied.
! 183: .Pp
! 184: Security policies may log successful and failed attempts to use
! 185: .Nm sudo .
! 186: If an I/O plugin is configured, the running command's input and
! 187: output may be logged as well.
! 188: .Pp
! 189: The options are as follows:
! 190: .Bl -tag -width Fl
! 191: .It Fl A
! 192: Normally, if
! 193: .Nm sudo
! 194: requires a password, it will read it from the user's terminal.
! 195: If the
! 196: .Fl A No ( Em askpass Ns No )
! 197: option is specified, a (possibly graphical) helper program is
! 198: executed to read the user's password and output the password to the
! 199: standard output.
! 200: If the
! 201: .Ev SUDO_ASKPASS
! 202: environment variable is set, it specifies the path to the helper
! 203: program.
! 204: Otherwise, if
! 205: .Pa @sysconfdir@/sudo.conf
! 206: contains a line specifying the askpass program, that value will be
! 207: used.
! 208: For example:
! 209: .Bd -literal -offset 4n
! 210: # Path to askpass helper program
! 211: Path askpass /usr/X11R6/bin/ssh-askpass
! 212: .Ed
! 213: .Pp
! 214: If no askpass program is available,
! 215: .Nm sudo
! 216: will exit with an error.
! 217: .It Fl a Ar type
! 218: The
! 219: .Fl a No ( Em "authentication type" Ns No )
! 220: option causes
! 221: .Nm sudo
! 222: to use the specified authentication type when validating the user,
! 223: as allowed by
! 224: .Pa /etc/login.conf .
! 225: The system administrator may specify a list of sudo-specific
! 226: authentication methods by adding an
! 227: .Dq auth-sudo
! 228: entry in
! 229: .Pa /etc/login.conf .
! 230: This option is only available on systems that support BSD authentication.
! 231: .It Fl b
! 232: The
! 233: .Fl b No ( Em background Ns No )
! 234: option tells
! 235: .Nm sudo
! 236: to run the given command in the background.
! 237: Note that if you use the
! 238: .Fl b
! 239: option you cannot use shell job control to manipulate the process.
! 240: Most interactive commands will fail to work properly in background
! 241: mode.
! 242: .It Fl C Ar fd
! 243: Normally,
! 244: .Nm sudo
! 245: will close all open file descriptors other than standard input,
! 246: standard output and standard error.
! 247: The
! 248: .Fl C No ( Em close from Ns No )
! 249: option allows the user to specify a starting point above the standard
! 250: error (file descriptor three).
! 251: Values less than three are not permitted.
! 252: The security policy may restrict the user's ability to use the
! 253: .Fl C
! 254: option.
! 255: The
! 256: .Em sudoers
! 257: policy only permits use of the
! 258: .Fl C
! 259: option when the administrator has enabled the
! 260: .Em closefrom_override
! 261: option.
! 262: .It Fl c Ar class
! 263: The
! 264: .Fl c No ( Em class Ns No )
! 265: option causes
! 266: .Nm sudo
! 267: to run the specified command with resources limited by the specified
! 268: login class.
! 269: The
! 270: .Em class
! 271: argument can be either a class name as defined in
! 272: .Pa /etc/login.conf ,
! 273: or a single
! 274: .Ql \-
! 275: character.
! 276: Specifying a
! 277: .Ar class
! 278: of
! 279: .Li -
! 280: indicates that the command should be run restricted by the default
! 281: login capabilities for the user the command is run as.
! 282: If the
! 283: .Ar class
! 284: argument specifies an existing user class, the command must be run
! 285: as root, or the
! 286: .Nm sudo
! 287: command must be run from a shell that is already root.
! 288: This option is only available on systems with BSD login classes.
! 289: .It Fl E
! 290: The
! 291: .Fl E No ( Em preserve environment Ns No )
! 292: option indicates to the security policy that the user wishes to
! 293: preserve their existing environment variables.
! 294: The security policy may return an error if the
! 295: .Fl E
! 296: option is specified and the user does not have permission to preserve
! 297: the environment.
! 298: .It Fl e
! 299: The
! 300: .Fl e No ( Em edit Ns No )
! 301: option indicates that, instead of running a command, the user wishes
! 302: to edit one or more files.
! 303: In lieu of a command, the string "sudoedit" is used when consulting
! 304: the security policy.
! 305: If the user is authorized by the policy, the following steps are
! 306: taken:
! 307: .Bl -enum -offset 4
! 308: .It
! 309: Temporary copies are made of the files to be edited with the owner
! 310: set to the invoking user.
! 311: .It
! 312: The editor specified by the policy is run to edit the temporary
! 313: files.
! 314: The
! 315: .Em sudoers
! 316: policy uses the
! 317: .Ev SUDO_EDITOR ,
! 318: .Ev VISUAL
! 319: and
! 320: .Ev EDITOR
! 321: environment variables (in that order).
! 322: If none of
! 323: .Ev SUDO_EDITOR ,
! 324: .Ev VISUAL
! 325: or
! 326: .Ev EDITOR
! 327: are set, the first program listed in the
! 328: .Em editor
! 329: .Xr sudoers @mansectform@
! 330: option is used.
! 331: .It
! 332: If they have been modified, the temporary files are copied back to
! 333: their original location and the temporary versions are removed.
! 334: .El
! 335: .Pp
! 336: If the specified file does not exist, it will be created.
! 337: Note that unlike most commands run by
! 338: .Em sudo ,
! 339: the editor is run with the invoking user's environment unmodified.
! 340: If, for some reason,
! 341: .Nm sudo
! 342: is unable to update a file with its edited version, the user will
! 343: receive a warning and the edited copy will remain in a temporary
! 344: file.
! 345: .It Fl g Ar group
! 346: Normally,
! 347: .Nm sudo
! 348: runs a command with the primary group set to the one specified by
! 349: the password database for the user the command is being run as (by
! 350: default, root).
! 351: The
! 352: .Fl g No ( Em group Ns No )
! 353: option causes
! 354: .Nm sudo
! 355: to run the command with the primary group set to
! 356: .Ar group
! 357: instead.
! 358: To specify a
! 359: .Em gid
! 360: instead of a
! 361: .Em "group name" ,
! 362: use
! 363: .Em #gid .
! 364: When running commands as a
! 365: .Em gid ,
! 366: many shells require that the
! 367: .Ql #
! 368: be escaped with a backslash
! 369: .Pq Ql \e .
! 370: If no
! 371: .Fl u
! 372: option is specified, the command will be run as the invoking user
! 373: (not root).
! 374: In either case, the primary group will be set to
! 375: .Em group .
! 376: .It Fl H
! 377: The
! 378: .Fl H No ( Em HOME Ns No )
! 379: option requests that the security policy set the
! 380: .Ev HOME
! 381: environment variable to the home directory of the target user (root
! 382: by default) as specified by the password database.
! 383: Depending on the policy, this may be the default behavior.
! 384: .It Fl h
! 385: The
! 386: .Fl h No ( Em help Ns No )
! 387: option causes
! 388: .Nm sudo
! 389: to print a short help message to the standard output and exit.
! 390: .It Fl i Op Ar command
! 391: The
! 392: .Fl i No ( Em simulate initial login Ns No )
! 393: option runs the shell specified by the password database entry of
! 394: the target user as a login shell.
! 395: This means that login-specific resource files such as
! 396: .Pa .profile
! 397: or
! 398: .Pa .login
! 399: will be read by the shell.
! 400: If a command is specified, it is passed to the shell for execution
! 401: via the shell's
! 402: .Fl c
! 403: option.
! 404: If no command is specified, an interactive shell is executed.
! 405: .Nm sudo
! 406: attempts to change to that user's home directory before running the
! 407: shell.
! 408: The security policy shall initialize the environment to a minimal
! 409: set of variables, similar to what is present when a user logs in.
! 410: The
! 411: .Em Command Environment
! 412: section in the
! 413: .Xr sudoers @mansectform@
! 414: manual documents how the
! 415: .Fl i
! 416: option affects the environment in which a command is run when the
! 417: .Em sudoers
! 418: policy is in use.
! 419: .It Fl K
! 420: The
! 421: .Fl K No ( sure Em kill Ns No )
! 422: option is like
! 423: .Fl k
! 424: except that it removes the user's cached credentials entirely and
! 425: may not be used in conjunction with a command or other option.
! 426: This option does not require a password.
! 427: Not all security policies support credential caching.
! 428: .It Fl k Op Ar command
! 429: When used alone, the
! 430: .Fl k No ( Em kill Ns No )
! 431: option to
! 432: .Nm sudo
! 433: invalidates the user's cached credentials.
! 434: The next time
! 435: .Nm sudo
! 436: is run a password will be required.
! 437: This option does not require a password and was added to allow a
! 438: user to revoke
! 439: .Nm sudo
! 440: permissions from a
! 441: .Pa .logout
! 442: file.
! 443: Not all security policies support credential caching.
! 444: .Pp
! 445: When used in conjunction with a command or an option that may require
! 446: a password, the
! 447: .Fl k
! 448: option will cause
! 449: .Nm sudo
! 450: to ignore the user's cached credentials.
! 451: As a result,
! 452: .Nm sudo
! 453: will prompt for a password (if one is required by the security
! 454: policy) and will not update the user's cached credentials.
! 455: .It Fl l Ns Oo Sy l Oc Op Ar command
! 456: If no
! 457: .Ar command
! 458: is specified, the
! 459: .Fl l No ( Em list Ns No )
! 460: option will list the allowed (and forbidden) commands for the
! 461: invoking user (or the user specified by the
! 462: .Fl U
! 463: option) on the current host.
! 464: If a
! 465: .Ar command
! 466: is specified and is permitted by the security policy, the fully-qualified
! 467: path to the command is displayed along with any command line
! 468: arguments.
! 469: If
! 470: .Ar command
! 471: is specified but not allowed,
! 472: .Nm sudo
! 473: will exit with a status value of 1.
! 474: If the
! 475: .Fl l
! 476: option is specified with an
! 477: .Ar l
! 478: argument
! 479: .Pq i.e.\& Fl ll ,
! 480: or if
! 481: .Fl l
! 482: is specified multiple times, a longer list format is used.
! 483: .It Fl n
! 484: The
! 485: .Fl n No ( Em non-interactive Ns No )
! 486: option prevents
! 487: .Nm sudo
! 488: from prompting the user for a password.
! 489: If a password is required for the command to run,
! 490: .Nm sudo
! 491: will display an error message and exit.
! 492: .It Fl P
! 493: The
! 494: .Fl P No ( Em preserve group vector Ns No )
! 495: option causes
! 496: .Nm sudo
! 497: to preserve the invoking user's group vector unaltered.
! 498: By default, the
! 499: .Em sudoers
! 500: policy will initialize the group vector to the list of groups the
! 501: target user is in.
! 502: The real and effective group IDs, however, are still set to match
! 503: the target user.
! 504: .It Fl p Ar prompt
! 505: The
! 506: .Fl p No ( Em prompt Ns No )
! 507: option allows you to override the default password prompt and use
! 508: a custom one.
! 509: The following percent
! 510: .Pq Ql %
! 511: escapes are supported by the
! 512: .Em sudoers
! 513: policy:
! 514: .Bl -tag -width 2n
! 515: .It Li %H
! 516: expanded to the host name including the domain name (on if the
! 517: machine's host name is fully qualified or the
! 518: .Em fqdn
! 519: option is set in
! 520: .Xr sudoers @mansectform@ )
! 521: .It Li %h
! 522: expanded to the local host name without the domain name
! 523: .It Li %p
! 524: expanded to the name of the user whose password is being requested
! 525: (respects the
! 526: .Em rootpw ,
! 527: .Em targetpw ,
! 528: and
! 529: .Em runaspw
! 530: flags in
! 531: .Xr sudoers @mansectform@ )
! 532: .It Li \&%U
! 533: expanded to the login name of the user the command will be run as
! 534: (defaults to root unless the
! 535: .Fl u
! 536: option is also specified)
! 537: .It Li %u
! 538: expanded to the invoking user's login name
! 539: .It Li %%
! 540: two consecutive
! 541: .Ql %
! 542: characters are collapsed into a single
! 543: .Ql %
! 544: character
! 545: .El
! 546: .Pp
! 547: The prompt specified by the
! 548: .Fl p
! 549: option will override the system password prompt on systems that
! 550: support PAM unless the
! 551: .Em passprompt_override
! 552: flag is disabled in
! 553: .Em sudoers .
! 554: .It Fl r Ar role
! 555: The
! 556: .Fl r No ( Em role Ns No )
! 557: option causes the new (SELinux) security context to have the role
! 558: specified by
! 559: .Ar role .
! 560: .It Fl S
! 561: The
! 562: .Fl S ( Em stdin Ns No )
! 563: option causes
! 564: .Nm sudo
! 565: to read the password from the standard input instead of the terminal
! 566: device.
! 567: The password must be followed by a newline character.
! 568: .It Fl s Op Ar command
! 569: The
! 570: .Fl s ( Em shell Ns No )
! 571: option runs the shell specified by the
! 572: .Ev SHELL
! 573: environment variable if it is set or the shell as specified in the
! 574: password database.
! 575: If a command is specified, it is passed to the shell for execution
! 576: via the shell's
! 577: .Fl c
! 578: option.
! 579: If no command is specified, an interactive shell is executed.
! 580: .It Fl t Ar type
! 581: The
! 582: .Fl t ( Em type Ns No )
! 583: option causes the new (SELinux) security context to have the type
! 584: specified by
! 585: .Ar type .
! 586: If no type is specified, the default type is derived from the
! 587: specified role.
! 588: .It Fl U Ar user
! 589: The
! 590: .Fl U ( Em other user Ns No )
! 591: option is used in conjunction with the
! 592: .Fl l
! 593: option to specify the user whose privileges should be listed.
! 594: The security policy may restrict listing other users' privileges.
! 595: The
! 596: .Em sudoers
! 597: policy only allows root or a user with the
! 598: .Li ALL
! 599: privilege on the current host to use this option.
! 600: .It Fl u Ar user
! 601: The
! 602: .Fl u ( Em user Ns No )
! 603: option causes
! 604: .Nm sudo
! 605: to run the specified command as a user other than
! 606: .Em root .
! 607: To specify a
! 608: .Em uid
! 609: instead of a
! 610: .Em user name ,
! 611: .Em #uid .
! 612: When running commands as a
! 613: .Em uid ,
! 614: many shells require that the
! 615: .Ql #
! 616: be escaped with a backslash
! 617: .Pq Ql \e .
! 618: Security policies may restrict
! 619: .Em uid Ns No s
! 620: to those listed in the password database.
! 621: The
! 622: .Em sudoers
! 623: policy allows
! 624: .Em uid Ns No s
! 625: that are not in the password database as long as the
! 626: .Em targetpw
! 627: option is not set.
! 628: Other security policies may not support this.
! 629: .It Fl V
! 630: The
! 631: .Fl V ( Em version Ns No )
! 632: option causes
! 633: .Nm sudo
! 634: to print its version string and the version string of the security
! 635: policy plugin and any I/O plugins.
! 636: If the invoking user is already root the
! 637: .Fl V
! 638: option will display the arguments passed to configure when
! 639: .Nm sudo
! 640: was built and plugins may display more verbose information such as
! 641: default options.
! 642: .It Fl v
! 643: When given the
! 644: .Fl v ( Em validate Ns No )
! 645: option,
! 646: .Nm sudo
! 647: will update the user's cached credentials, authenticating the user's
! 648: password if necessary.
! 649: For the
! 650: .Em sudoers
! 651: plugin, this extends the
! 652: .Nm sudo
! 653: timeout for another
! 654: .Li @timeout@
! 655: minutes (or whatever the timeout is set to by the security policy)
! 656: but does not run a command.
! 657: Not all security policies support cached credentials.
! 658: .It Fl -
! 659: The
! 660: .Fl -
! 661: option indicates that
! 662: .Nm sudo
! 663: should stop processing command line arguments.
! 664: .El
! 665: .Pp
! 666: Environment variables to be set for the command may also be passed
! 667: on the command line in the form of
! 668: .Sy VAR Ns No = Ns Em value ,
! 669: e.g.\&
! 670: .Sy LD_LIBRARY_PATH Ns No = Ns Em /usr/local/pkg/lib .
! 671: Variables passed on the command line are subject to the same
! 672: restrictions as normal environment variables with one important
! 673: exception.
! 674: If the
! 675: .Em setenv
! 676: option is set in
! 677: .Em sudoers ,
! 678: the command to be run has the
! 679: .Li SETENV
! 680: tag set or the command matched is
! 681: .Li ALL ,
! 682: the user may set variables that would otherwise be forbidden.
! 683: See
! 684: .Xr sudoers @mansectform@
! 685: for more information.
! 686: .Sh COMMAND EXECUTION
! 687: When
! 688: .Nm sudo
! 689: executes a command, the security policy specifies the execution
! 690: envionment for the command.
! 691: Typically, the real and effective uid and gid are set to
! 692: match those of the target user, as specified in the password database,
! 693: and the group vector is initialized based on the group database
! 694: (unless the
! 695: .Fl P
! 696: option was specified).
! 697: .Pp
! 698: The following parameters may be specified by security policy:
! 699: .Bl -bullet
! 700: .It
! 701: real and effective user ID
! 702: .It
! 703: real and effective group ID
! 704: .It
! 705: supplementary group IDs
! 706: .It
! 707: the environment list
! 708: .It
! 709: current working directory
! 710: .It
! 711: file creation mode mask (umask)
! 712: .It
! 713: SELinux role and type
! 714: .It
! 715: Solaris project
! 716: .It
! 717: Solaris privileges
! 718: .It
! 719: BSD login class
! 720: .It
! 721: scheduling priority (aka nice value)
! 722: .El
! 723: .Ss Process model
! 724: When
! 725: .Nm sudo
! 726: runs a command, it calls
! 727: .Xr fork 2 ,
! 728: sets up the execution environment as described above, and calls the
! 729: .Xr execve
! 730: system call in the child process.
! 731: The main
! 732: .Nm sudo
! 733: process waits until the command has completed, then passes the
! 734: command's exit status to the security policy's close method and exits.
! 735: If an I/O logging plugin is configured, a new pseudo-terminal
! 736: .Pq Dq pty
! 737: is created and a second
! 738: .Nm sudo
! 739: process is used to relay job control signals between the user's
! 740: existing pty and the new pty the command is being run in.
! 741: This extra process makes it possible to, for example, suspend
! 742: and resume the command.
! 743: Without it, the command would be in what POSIX terms an
! 744: .Dq orphaned process group
! 745: and it would not receive any job control signals.
! 746: .Ss Signal handling
! 747: Because the command is run as a child of the
! 748: .Nm sudo
! 749: process,
! 750: .Nm sudo
! 751: will relay signals it receives to the command.
! 752: Unless the command is being run in a new pty, the
! 753: .Dv SIGHUP ,
! 754: .Dv SIGINT
! 755: and
! 756: .Dv SIGQUIT
! 757: signals are not relayed unless they are sent by a user process,
! 758: not the kernel.
! 759: Otherwise, the command would receive
! 760: .Dv SIGINT
! 761: twice every time the user entered control-C.
! 762: Some signals, such as
! 763: .Dv SIGSTOP
! 764: and
! 765: .Dv SIGKILL ,
! 766: cannot be caught and thus will not be relayed to the command.
! 767: As a general rule,
! 768: .Dv SIGTSTP
! 769: should be used instead of
! 770: .Dv SIGSTOP
! 771: when you wish to suspend a command being run by
! 772: .Nm sudo .
! 773: .Pp
! 774: As a special case,
! 775: .Nm sudo
! 776: will not relay signals that were sent by the command it is running.
! 777: This prevents the command from accidentally killing itself.
! 778: On some systems, the
! 779: .Xr reboot @mansectsu@
! 780: command sends
! 781: .Dv SIGTERM
! 782: to all non-system processes other than itself before rebooting
! 783: the systyem.
! 784: This prevents
! 785: .Nm sudo
! 786: from relaying the
! 787: .Dv SIGTERM
! 788: signal it received back to
! 789: .Xr reboot @mansectsu@ ,
! 790: which might then exit before the system was actually rebooted,
! 791: leaving it in a half-dead state similar to single user mode.
! 792: Note, however, that this check only applies to the command run by
! 793: .Nm sudo
! 794: and not any other processes that the command may create.
! 795: As a result, running a script that calls
! 796: .Xr reboot @mansectsu@
! 797: or
! 798: .Xr shutdown @mansectsu@
! 799: via
! 800: .Nm sudo
! 801: may cause the system to end up in this undefined state unless the
! 802: .Xr reboot @mansectsu@
! 803: or
! 804: .Xr shutdown @mansectsu@
! 805: are run using the
! 806: .Fn exec
! 807: family of functions instead of
! 808: .Fn system
! 809: (which interposes a shell between the command and the calling process).
! 810: .Sh PLUGINS
! 811: Plugins are dynamically loaded based on the contents of the
! 812: .Pa @sysconfdir@/sudo.conf
! 813: file.
! 814: If no
! 815: .Pa @sysconfdir@/sudo.conf
! 816: file is present, or it contains no
! 817: .Li Plugin
! 818: lines,
! 819: .Nm sudo
! 820: will use the traditional
! 821: .Em sudoers
! 822: security policy and I/O logging, which corresponds to the following
! 823: .Pa @sysconfdir@/sudo.conf
! 824: file.
! 825: .Bd -literal
! 826: #
! 827: # Default @sysconfdir@/sudo.conf file
! 828: #
! 829: # Format:
! 830: # Plugin plugin_name plugin_path plugin_options ...
! 831: # Path askpass /path/to/askpass
! 832: # Path noexec /path/to/sudo_noexec.so
! 833: # Debug sudo /var/log/sudo_debug all@warn
! 834: # Set disable_coredump true
! 835: #
! 836: # The plugin_path is relative to @prefix@/libexec unless
! 837: # fully qualified.
! 838: # The plugin_name corresponds to a global symbol in the plugin
! 839: # that contains the plugin interface structure.
! 840: # The plugin_options are optional.
! 841: #
! 842: Plugin policy_plugin sudoers.so
! 843: Plugin io_plugin sudoers.so
! 844: .Ed
! 845: .Pp
! 846: A
! 847: .Li Plugin
! 848: line consists of the
! 849: .Li Plugin
! 850: keyword, followed by the
! 851: .Em symbol_name
! 852: and the
! 853: .Em path
! 854: to the shared object containing the plugin.
! 855: The
! 856: .Em symbol_name
! 857: is the name of the
! 858: .Li struct policy_plugin
! 859: or
! 860: .Li struct io_plugin
! 861: in the plugin shared object.
! 862: The
! 863: .Em path
! 864: may be fully qualified or relative.
! 865: If not fully qualified it is relative to the
! 866: .Pa @prefix@/libexec
! 867: directory.
! 868: Any additional parameters after the
! 869: .Em path
! 870: are passed as arguments to the plugin's
! 871: .Em open
! 872: function.
! 873: Lines that don't begin with
! 874: .Li Plugin ,
! 875: .Li Path ,
! 876: .Li Debug ,
! 877: or
! 878: .Li Set
! 879: are silently ignored.
! 880: .Pp
! 881: For more information, see the
! 882: .Xr sudo_plugin @mansectsu@
! 883: manual.
! 884: .Sh PATHS
! 885: A
! 886: .Li Path
! 887: line consists of the
! 888: .Li Path
! 889: keyword, followed by the name of the path to set and its value.
! 890: E.g.
! 891: .Bd -literal -offset indent
! 892: Path noexec @noexec_file@
! 893: Path askpass /usr/X11R6/bin/ssh-askpass
! 894: .Ed
! 895: .Pp
! 896: The following plugin-agnostic paths may be set in the
! 897: .Pa @sysconfdir@/sudo.conf
! 898: file:
! 899: .Bl -tag -width 8n
! 900: .It askpass
! 901: The fully qualified path to a helper program used to read the user's
! 902: password when no terminal is available.
! 903: This may be the case when
! 904: .Nm sudo
! 905: is executed from a graphical (as opposed to text-based) application.
! 906: The program specified by
! 907: .Em askpass
! 908: should display the argument passed to it as the prompt and write
! 909: the user's password to the standard output.
! 910: The value of
! 911: .Em askpass
! 912: may be overridden by the
! 913: .Ev SUDO_ASKPASS
! 914: environment variable.
! 915: .It noexec
! 916: The fully-qualified path to a shared library containing dummy
! 917: versions of the
! 918: .Fn execv ,
! 919: .Fn execve
! 920: and
! 921: .Fn fexecve
! 922: library functions that just return an error.
! 923: This is used to implement the
! 924: .Em noexec
! 925: functionality on systems that support
! 926: .Ev LD_PRELOAD
! 927: or its equivalent.
! 928: Defaults to
! 929: .Pa @noexec_file@ .
! 930: .El
! 931: .Sh DEBUG FLAGS
! 932: .Nm sudo
! 933: versions 1.8.4 and higher support a flexible debugging framework
! 934: that can help track down what
! 935: .Nm sudo
! 936: is doing internally if there is a problem.
! 937: .Pp
! 938: A
! 939: .Li Debug
! 940: line consists of the
! 941: .Li Debug
! 942: keyword, followed by the name of the program to debug
! 943: .Pq Nm sudo , Nm visudo , Nm sudoreplay ,
! 944: the debug file name and a comma-separated list of debug flags.
! 945: The debug flag syntax used by
! 946: .Nm sudo
! 947: and the
! 948: .Em sudoers
! 949: plugin is
! 950: .Em subsystem Ns No @ Ns Em priority
! 951: but the plugin is free to use a different format so long as it does
! 952: not include a comma
! 953: .Pq Ql \&, .
! 954: .Pp
! 955: For instance:
! 956: .Bd -literal -offset indent
! 957: Debug sudo /var/log/sudo_debug all@warn,plugin@info
! 958: .Ed
! 959: .Pp
! 960: would log all debugging statements at the
! 961: .Em warn
! 962: level and higher in addition to those at the
! 963: .Em info
! 964: level for the plugin subsystem.
! 965: .Pp
! 966: Currently, only one
! 967: .Li Debug
! 968: entry per program is supported.
! 969: The
! 970: .Nm sudo
! 971: .Li Debug
! 972: entry is shared by the
! 973: .Nm sudo
! 974: front end,
! 975: .Nm sudoedit
! 976: and the plugins.
! 977: A future release may add support for per-plugin
! 978: .Li Debug
! 979: lines and/or support for multiple debugging files for a single
! 980: program.
! 981: .Pp
! 982: The priorities used by the
! 983: .Nm sudo
! 984: front end, in order of decreasing severity, are:
! 985: .Em crit , err , warn , notice , diag , info , trace
! 986: and
! 987: .Em debug .
! 988: Each priority, when specified, also includes all priorities higher
! 989: than it.
! 990: For example, a priority of
! 991: .Em notice
! 992: would include debug messages logged at
! 993: .Em notice
! 994: and higher.
! 995: .Pp
! 996: The following subsystems are used by the
! 997: .Nm sudo
! 998: front-end:
! 999: .Bl -tag -width Fl
! 1000: .It Em all
! 1001: matches every subsystem
! 1002: .It Em args
! 1003: command line argument processing
! 1004: .It Em conv
! 1005: user conversation
! 1006: .It Em edit
! 1007: sudoedit
! 1008: .It Em exec
! 1009: command execution
! 1010: .It Em main
! 1011: .Nm sudo
! 1012: main function
! 1013: .It Em netif
! 1014: network interface handling
! 1015: .It Em pcomm
! 1016: communication with the plugin
! 1017: .It Em plugin
! 1018: plugin configuration
! 1019: .It Em pty
! 1020: pseudo-tty related code
! 1021: .It Em selinux
! 1022: SELinux-specific handling
! 1023: .It Em util
! 1024: utility functions
! 1025: .It Em utmp
! 1026: utmp handling
! 1027: .El
! 1028: .Sh EXIT VALUE
! 1029: Upon successful execution of a program, the exit status from
! 1030: .Em sudo
! 1031: will simply be the exit status of the program that was executed.
! 1032: .Pp
! 1033: Otherwise,
! 1034: .Nm sudo
! 1035: exits with a value of 1 if there is a configuration/permission
! 1036: problem or if
! 1037: .Nm sudo
! 1038: cannot execute the given command.
! 1039: In the latter case the error string is printed to the standard error.
! 1040: If
! 1041: .Nm sudo
! 1042: cannot
! 1043: .Xr stat 2
! 1044: one or more entries in the user's
! 1045: .Ev PATH ,
! 1046: an error is printed on stderr.
! 1047: (If the directory does not exist or if it is not really a directory,
! 1048: the entry is ignored and no error is printed.)
! 1049: This should not happen under normal circumstances.
! 1050: The most common reason for
! 1051: .Xr stat 2
! 1052: to return
! 1053: .Dq permission denied
! 1054: is if you are running an automounter and one of the directories in
! 1055: your
! 1056: .Ev PATH
! 1057: is on a machine that is currently unreachable.
! 1058: .Sh SECURITY NOTES
! 1059: .Nm sudo
! 1060: tries to be safe when executing external commands.
! 1061: .Pp
! 1062: To prevent command spoofing,
! 1063: .Nm sudo
! 1064: checks "." and "" (both denoting current directory) last when
! 1065: searching for a command in the user's
! 1066: .Ev PATH
! 1067: (if one or both are in the
! 1068: .Ev PATH ) .
! 1069: Note, however, that the actual
! 1070: .Ev PATH
! 1071: environment variable is
! 1072: .Em not
! 1073: modified and is passed unchanged to the program that
! 1074: .Nm sudo
! 1075: executes.
! 1076: .Pp
! 1077: Please note that
! 1078: .Nm sudo
! 1079: will normally only log the command it explicitly runs.
! 1080: If a user runs a command such as
! 1081: .Li sudo su
! 1082: or
! 1083: .Li sudo sh ,
! 1084: subsequent commands run from that shell are not subject to
! 1085: .Nm sudo Ns No 's
! 1086: security policy.
! 1087: The same is true for commands that offer shell escapes (including
! 1088: most editors).
! 1089: If I/O logging is enabled, subsequent commands will have their input and/or
! 1090: output logged, but there will not be traditional logs for those commands.
! 1091: Because of this, care must be taken when giving users access to commands via
! 1092: .Nm sudo
! 1093: to verify that the command does not inadvertently give the user an
! 1094: effective root shell.
! 1095: For more information, please see the
! 1096: .Em PREVENTING SHELL ESCAPES
! 1097: section in
! 1098: .Xr sudoers @mansectform@ .
! 1099: .Pp
! 1100: To prevent the disclosure of potentially sensitive information,
! 1101: .Nm sudo
! 1102: disables core dumps by default while it is executing (they are
! 1103: re-enabled for the command that is run).
! 1104: To aid in debugging
! 1105: .Nm sudo
! 1106: crashes, you may wish to re-enable core dumps by setting
! 1107: .Dq disable_coredump
! 1108: to false in the
! 1109: .Pa @sysconfdir@/sudo.conf
! 1110: file as follows:
! 1111: .Bd -literal -offset indent
! 1112: Set disable_coredump false
! 1113: .Ed
! 1114: .Pp
! 1115: Note that by default, most operating systems disable core dumps
! 1116: from setuid programs, which includes
! 1117: .Nm sudo .
! 1118: To actually get a
! 1119: .Nm sudo
! 1120: core file you may need to enable core dumps for setuid processes.
! 1121: On BSD and Linux systems this is accomplished via the sysctl command,
! 1122: on Solaris the coreadm command can be used.
! 1123: .Sh ENVIRONMENT
! 1124: .Nm sudo
! 1125: utilizes the following environment variables.
! 1126: The security policy has control over the actual content of the command's
! 1127: environment.
! 1128: .Bl -tag -width 15n
! 1129: .It Ev EDITOR
! 1130: Default editor to use in
! 1131: .Fl e
! 1132: (sudoedit) mode if neither
! 1133: .Ev SUDO_EDITOR
! 1134: nor
! 1135: .Ev VISUAL
! 1136: is set.
! 1137: .It Ev MAIL
! 1138: In
! 1139: .Fl i
! 1140: mode or when
! 1141: .Em env_reset
! 1142: is enabled in
! 1143: .Em sudoers ,
! 1144: set to the mail spool of the target user.
! 1145: .It Ev HOME
! 1146: Set to the home directory of the target user if
! 1147: .Fl i
! 1148: or
! 1149: .Fl H
! 1150: are specified,
! 1151: .Em env_reset
! 1152: or
! 1153: .Em always_set_home
! 1154: are set in
! 1155: .Em sudoers ,
! 1156: or when the
! 1157: .Fl s
! 1158: option is specified and
! 1159: .Em set_home
! 1160: is set in
! 1161: .Em sudoers .
! 1162: .It Ev PATH
! 1163: May be overridden by the security policy.
! 1164: .It Ev SHELL
! 1165: Used to determine shell to run with
! 1166: .Fl s
! 1167: option.
! 1168: .It Ev SUDO_ASKPASS
! 1169: Specifies the path to a helper program used to read the password
! 1170: if no terminal is available or if the
! 1171: .Fl A
! 1172: option is specified.
! 1173: .It Ev SUDO_COMMAND
! 1174: Set to the command run by sudo.
! 1175: .It Ev SUDO_EDITOR
! 1176: Default editor to use in
! 1177: .Fl e
! 1178: (sudoedit) mode.
! 1179: .It Ev SUDO_GID
! 1180: Set to the group ID of the user who invoked sudo.
! 1181: .It Ev SUDO_PROMPT
! 1182: Used as the default password prompt.
! 1183: .It Ev SUDO_PS1
! 1184: If set,
! 1185: .Ev PS1
! 1186: will be set to its value for the program being run.
! 1187: .It Ev SUDO_UID
! 1188: Set to the user ID of the user who invoked sudo.
! 1189: .It Ev SUDO_USER
! 1190: Set to the login name of the user who invoked sudo.
! 1191: .It Ev USER
! 1192: Set to the target user (root unless the
! 1193: .Fl u
! 1194: option is specified).
! 1195: .It Ev VISUAL
! 1196: Default editor to use in
! 1197: .Fl e
! 1198: (sudoedit) mode if
! 1199: .Ev SUDO_EDITOR
! 1200: is not set.
! 1201: .El
! 1202: .Sh FILES
! 1203: .Bl -tag -width 24n
! 1204: .It Pa @sysconfdir@/sudo.conf
! 1205: .Nm sudo
! 1206: front end configuration
! 1207: .El
! 1208: .Sh EXAMPLES
! 1209: Note: the following examples assume a properly configured security
! 1210: policy.
! 1211: .Pp
! 1212: To get a file listing of an unreadable directory:
! 1213: .Bd -literal -offset indent
! 1214: $ sudo ls /usr/local/protected
! 1215: .Ed
! 1216: .Pp
! 1217: To list the home directory of user yaz on a machine where the file
! 1218: system holding ~yaz is not exported as root:
! 1219: .Bd -literal -offset indent
! 1220: $ sudo -u yaz ls ~yaz
! 1221: .Ed
! 1222: .Pp
! 1223: To edit the
! 1224: .Pa index.html
! 1225: file as user www:
! 1226: .Bd -literal -offset indent
! 1227: $ sudo -u www vi ~www/htdocs/index.html
! 1228: .Ed
! 1229: .Pp
! 1230: To view system logs only accessible to root and users in the adm
! 1231: group:
! 1232: .Bd -literal -offset indent
! 1233: $ sudo -g adm view /var/log/syslog
! 1234: .Ed
! 1235: .Pp
! 1236: To run an editor as jim with a different primary group:
! 1237: .Bd -literal -offset indent
! 1238: $ sudo -u jim -g audio vi ~jim/sound.txt
! 1239: .Ed
! 1240: .Pp
! 1241: To shut down a machine:
! 1242: .Bd -literal -offset indent
! 1243: $ sudo shutdown -r +15 "quick reboot"
! 1244: .Ed
! 1245: .Pp
! 1246: To make a usage listing of the directories in the /home partition.
! 1247: Note that this runs the commands in a sub-shell to make the
! 1248: .Li cd
! 1249: and file redirection work.
! 1250: .Bd -literal -offset indent
! 1251: $ sudo sh -c "cd /home ; du -s * | sort -rn > USAGE"
! 1252: .Ed
! 1253: .Sh SEE ALSO
! 1254: .Xr grep 1 ,
! 1255: .Xr su 1 ,
! 1256: .Xr stat 2 ,
! 1257: .Xr login_cap 3 ,
! 1258: .Xr passwd @mansectform@ ,
! 1259: .Xr sudoers @mansectform@ ,
! 1260: .Xr sudo_plugin @mansectsu@ ,
! 1261: .Xr sudoreplay @mansectsu@ ,
! 1262: .Xr visudo @mansectsu@
! 1263: .Sh HISTORY
! 1264: See the HISTORY file in the
! 1265: .Nm sudo
! 1266: distribution (http://www.sudo.ws/sudo/history.html) for a brief
! 1267: history of sudo.
! 1268: .Sh AUTHORS
! 1269: Many people have worked on
! 1270: .Nm sudo
! 1271: over the years; this version consists of code written primarily by:
! 1272: .Bd -ragged -offset indent
! 1273: Todd C. Miller
! 1274: .Ed
! 1275: .Pp
! 1276: See the CONTRIBUTORS file in the
! 1277: .Nm sudo
! 1278: distribution (http://www.sudo.ws/sudo/contributors.html) for an
! 1279: exhaustive list of people who have contributed to
! 1280: .Nm sudo .
! 1281: .Sh CAVEATS
! 1282: There is no easy way to prevent a user from gaining a root shell
! 1283: if that user is allowed to run arbitrary commands via
! 1284: .Nm sudo .
! 1285: Also, many programs (such as editors) allow the user to run commands
! 1286: via shell escapes, thus avoiding
! 1287: .Nm sudo Ns No 's
! 1288: checks.
! 1289: However, on most systems it is possible to prevent shell escapes with the
! 1290: .Xr sudoers @mansectform@
! 1291: plugin's
! 1292: .Em noexec
! 1293: functionality.
! 1294: .Pp
! 1295: It is not meaningful to run the
! 1296: .Li cd
! 1297: command directly via sudo, e.g.,
! 1298: .Bd -literal -offset indent
! 1299: $ sudo cd /usr/local/protected
! 1300: .Ed
! 1301: .Pp
! 1302: since when the command exits the parent process (your shell) will
! 1303: still be the same.
! 1304: Please see the
! 1305: .Sx EXAMPLES
! 1306: section for more information.
! 1307: .Pp
! 1308: Running shell scripts via
! 1309: .Nm sudo
! 1310: can expose the same kernel bugs that make setuid shell scripts
! 1311: unsafe on some operating systems (if your OS has a /dev/fd/ directory,
! 1312: setuid shell scripts are generally safe).
! 1313: .Sh BUGS
! 1314: If you feel you have found a bug in
! 1315: .Nm sudo ,
! 1316: please submit a bug report at http://www.sudo.ws/sudo/bugs/
! 1317: .Sh SUPPORT
! 1318: Limited free support is available via the sudo-users mailing list,
! 1319: see http://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or
! 1320: search the archives.
! 1321: .Sh DISCLAIMER
! 1322: .Nm sudo
! 1323: is provided
! 1324: .Dq AS IS
! 1325: and any express or implied warranties, including, but not limited
! 1326: to, the implied warranties of merchantability and fitness for a
! 1327: particular purpose are disclaimed.
! 1328: See the LICENSE file distributed with
! 1329: .Nm sudo
! 1330: or http://www.sudo.ws/sudo/license.html for complete details.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to sudo.mdoc.in CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / sudo / doc