| SUDO(8) | Maintenance Commands and Procedures | SUDO(8) |
sudo, sudoedit
— execute a command as another user
sudo |
-h | -K |
-k | -V |
sudo |
-v [-ABkNnS]
[-g group]
[-h host]
[-p prompt]
[-u user] |
sudo |
-l [-ABkNnS]
[-g group]
[-h host]
[-p prompt]
[-U user]
[-u user]
[command [arg ...]] |
sudo |
[-ABbEHnPS] [-C
num] [-D
directory] [-g
group] [-h
host] [-p
prompt] [-R
directory] [-T
timeout] [-u
user]
[VAR=value]
[-i | -s]
[command [arg ...]] |
sudoedit |
[-ABkNnS] [-C
num] [-D
directory] [-g
group] [-h
host] [-p
prompt] [-R
directory] [-T
timeout] [-u
user] file ... |
sudo allows a permitted user to execute a
command as the superuser or another user, as specified
by the security policy. The invoking user's real
(not
effective) user-ID is used to determine the user
name with which to query the security policy.
sudo supports a plugin architecture for
security policies, auditing, and input/output logging. Third parties can
develop and distribute their own plugins to work seamlessly with the
sudo front-end. The default security policy is
sudoers, which is configured via the file
/etc/sudoers, or via LDAP. See the
Plugins section for more information.
The security policy determines what privileges, if any, a user has
to run sudo. The policy may require that users
authenticate themselves with a password or another authentication mechanism.
If authentication is required, sudo will exit if the
user's password is not entered within a configurable time limit. This limit
is policy-specific; the default password prompt timeout for the
sudoers security policy is 5 minutes.
Security policies may support credential
caching to allow the user to run sudo again for a
period of time without requiring authentication. By default, the
sudoers policy caches credentials on a per-terminal basis
for 5 minutes. See the timestamp_type and
timestamp_timeout
options in sudoers(5) for more
information. By running sudo with the
-v option, a user can update the cached credentials
without running a command.
On systems where sudo is the primary
method of gaining superuser privileges, it is imperative to avoid syntax
errors in the security policy configuration files. For the default security
policy, sudoers(5), changes to the
configuration files should be made using the
visudo(8) utility which will ensure
that no syntax errors are introduced.
When invoked as sudoedit, the
-e option (described below), is implied.
Security policies and audit plugins may log successful and failed
attempts to run sudo. If an I/O plugin is
configured, the running command's input and output may
be logged as well.
The options are as follows:
-A,
--askpasssudo requires a password, it will
read it from the user's terminal. If the -A
(askpass)
option is specified, a (possibly graphical) helper program is executed to
read the user's password and output the password to the standard output.
If the SUDO_ASKPASS environment variable is set,
it specifies the path to the helper program. Otherwise, if
sudo.conf(5) contains a line
specifying the askpass program, that value will be used. For example:
# Path to askpass helper program Path askpass /usr/X11R6/bin/ssh-askpass
If no askpass program is available,
sudo will exit with an error.
-B,
--bell-b,
--backgroundsudo. Most interactive
commands will fail to work properly in background
mode.-C
num,
--close-from=numsudo will close all open file
descriptors other than standard input, standard output, and standard error
when executing a command. The security policy may
restrict the user's ability to use this option. The
sudoers policy only permits use of the
-C option when the administrator has enabled the
closefrom_override
option.-D
directory,
--chdir=directory-E,
--preserve-env--preserve-env=list-e,
--editSUDO_EDITOR, VISUAL
and EDITOR environment variables (in that
order). If none of SUDO_EDITOR,
VISUAL or EDITOR are
set, the first program listed in the
editor
sudoers(5) option is used.To help prevent the editing of unauthorized files, the following restrictions are enforced unless explicitly allowed by the security policy:
Users are never allowed to edit device special files.
If the specified file does not exist, it will be
created. Unlike most commands run by
sudo, the editor
is run with the invoking user's environment unmodified. If the temporary
file becomes empty after editing, the user will be prompted before it is
installed. If, for some reason, sudo is unable
to update a file with its edited version, the user will receive a
warning and the edited copy will remain in a temporary file.
-g
group,
--group=group#’ character (e.g.,
‘#0’ for GID 0). When running a
command as a GID, many shells require that the
‘#’ be escaped with a backslash
(‘\’). If no
-u option is specified, the
command will be run as the invoking user. In either
case, the primary group will be set to group. The
sudoers policy permits any of the target user's groups
to be specified via the -g option as long as the
-P option is not in use.-H,
--set-homeHOME
environment variable to the home directory specified by the target user's
password database entry. Depending on the policy, this may be the default
behavior.-h,
--help-h
host,
--host=host-l option
to list a user's privileges for the remote host.-i,
--login-c
option. The command and any
args are concatenated, separated by spaces, after
escaping each character (including white space) with a backslash
(‘\’) except for alphanumerics,
underscores, hyphens, and dollar signs. If no
command is specified, an interactive shell is
executed. sudo attempts to change to that user's
home directory before running the shell. The command
is run with an environment similar to the one a user would receive at log
in. Most shells behave differently when a command is
specified as compared to an interactive session; consult the shell's
manual for details. The
Command
environment section in the
sudoers(5) manual documents how the
-i option affects the environment in which a
command is run when the sudoers
policy is in use.-K,
--remove-timestamp-k option, except that it removes
every cached credential for the user, regardless of the terminal or parent
process ID. The next time sudo is run, a password
must be entered if the security policy requires authentication. It is not
possible to use the -K option in conjunction with
a command or other option. This option does not
require a password. Not all security policies support credential
caching.-k,
--reset-timestampsudo is run in the session, a password must be
entered if the security policy requires authentication. By default, the
sudoers policy uses a separate record in the
credential cache for each terminal (or parent process ID if no terminal is
present). This prevents the -k option from
interfering with sudo commands run in a different
terminal session. See the timestamp_type option in
sudoers(5) for more information.
This option does not require a password, and was added to allow a user to
revoke sudo permissions from a
.logout file.
When used in conjunction with a command
or an option that may require a password, this option will cause
sudo to ignore the user's cached credentials. As
a result, sudo will prompt for a password (if
one is required by the security policy) and will not update the user's
cached credentials.
Not all security policies support credential caching.
-l,
--list-U option) on the current host. A longer list
format is used if this option is specified multiple times and the security
policy supports a verbose output format.
If a command is specified and is
permitted by the security policy for the invoking user (or the,
user specified by the -U
option) on the current host, the fully-qualified path to the
command is displayed along with any
args. If -l is specified
more than once (and the security policy supports it), the matching rule
is displayed in a verbose format along with the
command. If a command is
specified but not allowed by the policy, sudo
will exit with a status value of 1.
-N,
--no-update-k flag, existing cached
credentials are used if they are valid. To detect when the user's cached
credentials are valid (or when no authentication is required), the
following can be used:
sudo -Nnv
Not all security policies support credential caching.
-n,
--non-interactivesudo
will display an error message and exit.-P,
--preserve-groups-p
prompt,
--prompt=prompt%’) escape sequences are
supported by the sudoers policy:
-u option is also specified)%’ characters
are collapsed into a single ‘%’
characterThe custom prompt will override the
default prompt specified by either the security policy or the
SUDO_PROMPT environment variable. On systems
that use PAM, the custom prompt will also override the prompt specified
by a PAM module unless the
passprompt_override
flag is disabled in sudoers.
-R
directory,
--chroot=directoryThis option is deprecated and will be removed in a future
version of sudo.
-S,
--stdin-s,
--shellSHELL environment
variable if it is set or the shell specified by the invoking user's
password database entry. If a command is specified,
it is passed to the shell as a simple command using the
-c option. The command and
any args are concatenated, separated by spaces,
after escaping each character (including white space) with a backslash
(‘\’) except for alphanumerics,
underscores, hyphens, and dollar signs. If no
command is specified, an interactive shell is
executed. Most shells behave differently when a
command is specified as compared to an interactive
session; consult the shell's manual for details.-U
user,
--other-user=user-l option to list the
privileges for user instead of for the invoking
user. The security policy may restrict listing other users' privileges.
When using the sudoers policy, the
-U option is restricted to the root user and users
with either the “list” priviege for the specified
user or the ability to run any
command as root or user on the
current host.-T
timeout,
--command-timeout=timeout-u
user,
--user=user#’
character (e.g., ‘#0’ for UID 0).
When running commands as a UID, many shells require
that the ‘#’ be escaped with a
backslash (‘\’). Some security
policies may restrict UIDs to those listed in the password database. The
sudoers policy allows UIDs that are not in the password
database as long as the targetpw option is not set.
Other security policies may not support this.-V,
--versionsudo version string as well as the
version string of any configured plugins. If the invoking user is already
root, the -V option will display the options
passed to configure when sudo was built; plugins
may display additional information such as default options.-v,
--validatesudo timeout for another 5 minutes by default, but
does not run a command. Not all security policies
support cached credentials.---- is used to delimit the end of the
sudo options. Subsequent options are passed to the
command.Options that take a value may only be specified once unless
otherwise indicated in the description. This is to help guard against
problems caused by poorly written scripts that invoke
sudo with user-controlled input.
Environment variables to be set for the
command may also be passed as options to
sudo in the form
VAR=value, for example
LD_LIBRARY_PATH=/usr/local/pkg/lib.
Environment variables may be subject to restrictions imposed by the security
policy plugin. The sudoers policy subjects environment
variables passed as options to the same restrictions as existing environment
variables with one important difference. If the
setenv option is
set in sudoers, the command to be
run has the SETENV tag set or the
command matched is
ALL, the
user may set variables that would otherwise be forbidden. See
sudoers(5) for more information.
When sudo executes a
command, the security policy specifies the execution
environment for the command. Typically, the real and
effective user and group and IDs are set to match those of the target user,
as specified in the password database, and the group vector is initialized
based on the group database (unless the -P option
was specified).
The following parameters may be specified by security policy:
There are two distinct ways sudo can run a
command.
If an I/O logging plugin is configured to log terminal I/O, or if
the security policy explicitly requests it, a new pseudo-terminal
(“pty”) is allocated and
fork(2) is used to create a second
sudo process, referred to as the
monitor. The monitor creates a new
terminal session with itself as the leader and the pty as its controlling
terminal, calls fork(2) again, sets up
the execution environment as described above, and then uses the
execve(2) system call to run the
command in the child process. The
monitor exists to relay job control signals between the
user's terminal and the pty the command is being run
in. This makes it possible to suspend and resume the
command normally. Without the
monitor, the command would be in
what POSIX terms an “orphaned process group” and it would not
receive any job control signals from the kernel. When the
command exits or is terminated by a signal, the
monitor passes the command's exit
status to the main sudo process and exits. After
receiving the command's exit status, the main
sudo process passes the
command's exit status to the security policy's close
function, as well as the close function of any configured audit plugin, and
exits. This mode is the default for sudo versions 1.9.14 and above when
using the sudoers policy.
If no pty is used, sudo calls
fork(2), sets up the execution
environment as described above, and uses the
execve(2) system call to run the
command in the child process. The main
sudo process waits until the
command has completed, then passes the
command's exit status to the security policy's close
function, as well as the close function of any configured audit plugins, and
exits. As a special case, if the policy plugin does not define a close
function, sudo will execute the
command directly instead of calling
fork(2) first. The
sudoers policy plugin will only define a close function
when I/O logging is enabled, a pty is required, an SELinux role is
specified, the command has an associated timeout, or
the pam_session or pam_setcred options
are enabled. Both pam_session and
pam_setcred are enabled by default on systems using PAM.
This mode is the default for sudo versions prior to 1.9.14 when using the
sudoers policy.
On systems that use PAM, the security policy's close function is responsible for closing the PAM session. It may also log the command's exit status.
When the command is run as a child of the
sudo process, sudo will
relay signals it receives to the command. The
SIGINT and SIGQUIT signals
are only relayed when the command is being run in a
new pty or when the signal was sent by a user process, not the kernel. This
prevents the command from receiving
SIGINT twice each time the user enters control-C.
Some signals, such as SIGSTOP and
SIGKILL, cannot be caught and thus will not be
relayed to the command. As a general rule,
SIGTSTP should be used instead of
SIGSTOP when you wish to suspend a
command being run by sudo.
As a special case, sudo will not
relay signals that were sent by the command it is
running. This prevents the command from accidentally
killing itself. On some systems, the
reboot(8) utility sends
SIGTERM to all non-system processes other than
itself before rebooting the system. This prevents
sudo from relaying the
SIGTERM signal it received back to
reboot(8), which might then exit
before the system was actually rebooted, leaving it in a half-dead state
similar to single user mode. Note, however, that this check only applies to
the command run by sudo and
not any other processes that the command may create.
As a result, running a script that calls
reboot(8) or
shutdown(8) via
sudo may cause the system to end up in this
undefined state unless the reboot(8)
or shutdown(8) are run using the
exec() family
of functions instead of
system()
(which interposes a shell between the command and the
calling process).
Plugins may be specified via Plugin directives
in the sudo.conf(5) file. They may
be loaded as dynamic shared objects (on systems that support them), or
compiled directly into the sudo binary. If no
sudo.conf(5) file is present, or if
it doesn't contain any Plugin lines,
sudo will use
sudoers(5) for the policy, auditing,
and I/O logging plugins. See the
sudo.conf(5) manual for details of
the /etc/sudo.conf file and the
sudo_plugin(5) manual for more
information about the sudo plugin architecture.
Upon successful execution of a command, the
exit status from sudo will be the exit status of the
program that was executed. If the command terminated
due to receipt of a signal, sudo will send itself
the same signal that terminated the command.
If the -l option was specified without a
command, sudo will exit with a
value of 0 if the user is allowed to run sudo and
they authenticated successfully (as required by the security policy). If a
command is specified with the
-l option, the exit value will only be 0 if the
command is permitted by the security policy, otherwise
it will be 1.
If there is an authentication failure, a configuration/permission
problem, or if the given command cannot be executed,
sudo exits with a value of 1. In the latter case,
the error string is printed to the standard error. If
sudo cannot
stat(2) one or more entries in the
user's PATH, an error is printed to the standard
error. (If the directory does not exist or if it is not really a directory,
the entry is ignored and no error is printed.) This should not happen under
normal circumstances. The most common reason for
stat(2) to return “permission
denied” is if you are running an automounter and one of the
directories in your PATH is on a machine that is
currently unreachable.
sudo tries to be safe when executing
external commands.
To prevent command spoofing, sudo checks
"." and "" (both denoting current directory) last when
searching for a command in the user's
PATH (if one or both are in the
PATH). Depending on the security policy, the user's
PATH environment variable may be modified, replaced,
or passed unchanged to the program that sudo
executes.
Users should
never be granted
sudo privileges to execute files that are writable
by the user or that reside in a directory that is writable by the user. If
the user can modify or replace the command there is no
way to limit what additional commands they can
run.
By default, sudo will only
log the command it explicitly runs. If a user runs a
command such as ‘sudo
su’ or ‘sudo sh’,
subsequent commands run from that shell are not
subject to sudo's security policy. The same is true
for commands that offer shell escapes (including most
editors). If I/O logging is enabled, subsequent
commands will have their input and/or output logged,
but there will not be traditional logs for those
commands. Because of this, care must be taken when
giving users access to commands via
sudo to verify that the
command does not inadvertently give the user an
effective root shell. For information on ways to address this, see the
Preventing shell
escapes section in
sudoers(5).
To prevent the disclosure of potentially sensitive information,
sudo disables core dumps by default while it is
executing (they are re-enabled for the command that is
run). This historical practice dates from a time when most operating systems
allowed set-user-ID processes to dump core by default. To aid in debugging
sudo crashes, you may wish to re-enable core dumps
by setting “disable_coredump” to false in the
sudo.conf(5) file as follows:
Set disable_coredump false
See the sudo.conf(5) manual for more information.
sudo utilizes the following environment
variables. The security policy has control over the actual content of the
command's environment.
EDITOR-e (sudoedit) mode if
neither SUDO_EDITOR nor
VISUAL is set.MAIL-i option is specified, or when
env_reset is enabled in sudoers
(unless MAIL is present in the
env_keep list).HOME-i or -H options are
specified, when the -s option is specified and
set_home
is set in sudoers, when
always_set_home
is enabled in sudoers, or when
env_reset is enabled in sudoers and
HOME is not present in the
env_keep list.LOGNAME-i option is specified, when the
set_logname
option is enabled in sudoers, or when the
env_reset option is enabled in sudoers
(unless LOGNAME is present in the
env_keep list).PATHSHELL-s
option.SUDO_ASKPASS-A option is
specified.SUDO_COMMANDSUDO_EDITOR-e (sudoedit) mode.SUDO_GIDSUDO_HOMESUDO_PROMPT-p
option was specified.SUDO_PS1PS1 will be set to its value for the
program being run.SUDO_TTYSUDO_UIDSUDO_USERUSERLOGNAME, described
above.VISUAL-e (sudoedit) mode if
SUDO_EDITOR is not set.sudo front-end configurationThe following examples assume a properly configured security policy.
To get a file listing of an unreadable directory:
$ sudo ls /usr/local/protected
To list the home directory of user yaz on a machine where the file system holding ~yaz is not exported as root:
$ sudo -u yaz ls ~yaz
To edit the index.html file as user www:
$ sudoedit -u www ~www/htdocs/index.html
To view system logs only accessible to root and users in the adm group:
$ sudo -g adm more /var/log/syslog
To run an editor as jim with a different primary group:
$ sudoedit -u jim -g audio ~jim/sound.txt
To shut down a machine:
$ sudo shutdown -r +15 "quick reboot"
To make a usage listing of the directories in the /home partition.
The commands are run in a sub-shell to allow the
‘cd’ command and file redirection to
work.
$ sudo sh -c "cd /home ; du -s * | sort -rn > USAGE"
Error messages produced by sudo
include:
editing files in a writable directory is not permitted
sudoedit does not
permit editing a file when any of the parent directories are writable by the
invoking user. This avoids a race condition that could allow the user to
overwrite an arbitrary file. See the
sudoedit_checkdir
option in sudoers(5) for more
information.editing symbolic links is not permitted
sudoedit does not
follow symbolic links when opening files. See the
sudoedit_follow
option in sudoers(5) for more
information.effective uid is not 0, is sudo installed setuid root?
sudo was not run with root
privileges. The sudo binary must be owned by the root
user and have the set-user-ID bit set. Also, it must not be located on a file
system mounted with the ‘nosuid’ option or on an NFS file system
that maps uid 0 to an unprivileged uid.effective uid is not 0, is sudo on a file system with the 'nosuid' option set or an NFS file system without root privileges?
sudo was not run with root
privileges. The sudo binary has the proper owner and
permissions but it still did not run with root privileges. The most common
reason for this is that the file system the sudo
binary is located on is mounted with the ‘nosuid’ option or it
is an NFS file system that maps uid 0 to an unprivileged uid.fatal error, unable to load plugins
invalid environment variable name
-E option contained an equal sign
(‘=’). The arguments to the
-E option should be environment variable names without
an associated value.no password was provided
sudo tried to read the
password, it did not receive any characters. This may happen if no terminal is
available (or the -S option is specified) and the
standard input has been redirected from
/dev/null.a terminal is required to read the password
sudo needs to read the
password but there is no mechanism available for it to do so. Remote commands
run via ssh(1) do not have a terminal
available by default; passing the -t option to
ssh(1) will cause it to allocate a terminal
which should allow sudo to read the password. To allow
sudo to run local commands without a terminal, the
-S option can be used to read a password from the
standard input, or an askpass helper can be configured via either the
sudo.conf(5) file or by setting the
SUDO_ASKPASS environment variable.no writable temporary directory found
sudoedit was unable to find a
usable temporary directory in which to store its intermediate files.The “no new privileges” flag is set, which prevents sudo from running as root.
sudo was run by a process that
has the Linux “no new privileges” flag is set. This causes the
set-user-ID bit to be ignored when running an executable, which will prevent
sudo from functioning. The most likely cause for this
is running sudo within a container that sets this
flag. Check the documentation to see if it is possible to configure the
container such that the flag is not set.sudo must be owned by uid 0 and have the setuid bit set
sudo was not run with root
privileges. The sudo binary does not have the correct
owner or permissions. It must be owned by the root user and have the
set-user-ID bit set.sudoedit is not supported on this platform
sudoedit on systems that support setting the effective
user-ID.timed out reading password
you do not exist in the passwd database
you may not specify environment variables in edit mode
su(1), stat(2), login_cap(3), passwd(5), sudo.conf(5), sudo_plugin(5), sudoers(5), sudoers_timestamp(5), sudoreplay(8), visudo(8)
See the HISTORY.md file in the sudo
distribution (https://www.sudo.ws/about/history/) for a brief history of
sudo.
Many people have worked on sudo over the
years; this version consists of code written primarily by:
See the CONTRIBUTORS.md file in the sudo
distribution (https://www.sudo.ws/about/contributors/) for an exhaustive
list of people who have contributed to sudo.
There is no easy way to prevent a user from gaining a root shell
if that user is allowed to run arbitrary commands via
sudo. Also, many programs (such as editors) allow
the user to run commands via shell escapes, thus
avoiding sudo's checks. However, on most systems it
is possible to prevent shell escapes with the
sudoers(5) plugin's
noexec
functionality.
It is not meaningful to run the
‘cd’ command
directly via sudo, e.g.,
$ sudo cd /usr/local/protected
since when the command exits the parent
process (your shell) will still be the same. The -D
option can be used to run a command in a specific
directory.
Running shell scripts via sudo can expose
the same kernel bugs that make set-user-ID shell scripts unsafe on some
operating systems (if your OS has a /dev/fd/ directory, set-user-ID shell
scripts are generally safe).
If you believe you have found a bug in
sudo, you can either file a bug report in the sudo
bug database, https://bugzilla.sudo.ws/, or open an issue at
https://github.com/sudo-project/sudo/issues. If you would prefer to use
email, messages may be sent to the sudo-workers mailing list,
https://www.sudo.ws/mailman/listinfo/sudo-workers (public) or
<sudo@sudo.ws> (private).
Please do not report security vulnerabilities through public GitHub issues, Bugzilla or mailing lists. Instead, report them via email to <Todd.Miller@sudo.ws>. You may encrypt your message with PGP if you would like, using the key found at https://www.sudo.ws/dist/PGPKEYS.
Limited free support is available via the sudo-users mailing list, see https://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or search the archives.
sudo is provided “AS IS” and
any express or implied warranties, including, but not limited to, the
implied warranties of merchantability and fitness for a particular purpose
are disclaimed. See the LICENSE.md file distributed with
sudo or https://www.sudo.ws/about/license/ for
complete details.
| June 7, 2025 | Sudo 1.9.17p1 |