adm_sudo.xml

<?xml version="1.0"?>
<!DOCTYPE chapter [
  <!ENTITY % entities SYSTEM "generic-entities.ent">
  %entities;
]>

<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="cha-adm-sudo">
 <title>sudo
<!-- TODO: Better title --></title>
 <info>
  <meta name="description">Configure sudo settings to manage user permissions and secure access to elevated commands in your Linux system</meta>
  <dm:docmanager xmlns:dm="urn:x-suse:ns:docmanager">
   <dm:bugtracker/>
   <dm:translation>yes</dm:translation>
  </dm:docmanager>
 <revhistory xml:id="rh-cha-adm-sudo">
   <revision>
     <date>2026-04-09</date>
     <revdescription>
       <para/>
     </revdescription>
   </revision>
 </revhistory>
</info>
 <para>
  Many commands and system utilities need to be run as &rootuser; to modify
  files and/or perform tasks that only the super user is allowed to. For
  security reasons and to avoid accidentally running dangerous commands, it is
  generally advisable not to log in directly as &rootuser;. Instead, it is
  recommended to work as a normal, unprivileged user and use the &sudo;
  command to run commands with elevated privileges.
 </para>
 <para>
  On &productname;, &sudo; is configured by default to work similarly to su.
  However, &sudo; offers the possibility to allow users to run commands with
  privileges of any other user in a highly configurable manner. This can be
  used to assign roles with specific privileges to certain users and groups. It
  is for example possible to allow members of the group &examplegroup; to run a
  command with the privileges of &exampleuserII;. Access to the command can be
  further restricted by, for example, forbidding to specify any command
  options. While su always requires the &rootuser; password for authentication
  with PAM, &sudo; can be configured to authenticate with your own credentials.
  This increases security by not having to share the &rootuser; password. For
  example, you can allow members of the group &examplegroup; to run a command
  <command>frobnicate</command> as &exampleuserII;, with the restriction that
  no arguments are specified. This can be used to assign roles with specific
  abilities to certain users and groups.
 </para>
 <sect1 xml:id="sec-adm-sudo-usage">
  <title>Basic &sudo; Usage</title>

  <para>
   &sudo; is simple to use, yet very powerful.
  </para>

  <sect2 xml:id="sec-adm-sudo-usage-cmd">
   <title>Running a Single Command</title>
   <para>
    Logged in as normal user, you can run any command as &rootuser; by
    adding &sudo; before it. It will prompt for the root password and, if
    authenticated successfully, run the command as &rootuser;:
   </para>
<screen>
&prompt.user;<command>id -un</command><co xml:id="co-sudo-usage-id"/>
tux
&prompt.user;<command>sudo id -un</command>
root's password:<co xml:id="co-sudo-usage-pw"/>
root
&prompt.user;<command>id -un</command>
tux<co xml:id="co-sudo-usage-after"/>
&prompt.user;<command>sudo id -un</command>
<co xml:id="co-sudo-usage-nopw"/>
root
</screen>
   <calloutlist>
    <callout arearefs="co-sudo-usage-id">
     <para>
      The <command>id -un</command> command prints the login name of the
      current user.
     </para>
    </callout>
    <callout arearefs="co-sudo-usage-pw">
     <para>
      The password is not shown during input, neither as clear text nor as
      bullets.
     </para>
    </callout>
    <callout arearefs="co-sudo-usage-after">
     <para>
      Only commands started with &sudo; are run with elevated privileges. If
      you run the same command without the &sudo; prefix, it is run with the
      privileges of the current user again.
     </para>
    </callout>
    <callout arearefs="co-sudo-usage-nopw">
     <para>
      The elevated privileges persist for a certain period of time, so you
      do not need to provide the &rootuser; password again.
     </para>
    </callout>
   </calloutlist>
   <tip>
    <title>I/O Redirection</title>
    <para>
     I/O redirection does not work as you would probably expect:
    </para>
<screen>
&prompt.user;sudo echo s &gt; /proc/sysrq-trigger
bash: /proc/sysrq-trigger: Permission denied
&prompt.user;sudo cat &lt; /proc/1/maps
bash: /proc/1/maps: Permission denied
</screen>
    <para>
     Only the <command>echo</command>/<command>cat</command> binary is run with
     elevated privileges, while the redirection is performed by the user's
     shell with user privileges. You can either start a shell like in
     <xref linkend="sec-sudo-shell"/> or use the <command>dd</command> utility
     instead:
    </para>
<screen>
echo s | sudo dd of=/proc/sysrq-trigger
sudo dd if=/proc/1/maps | cat <!-- TODO: Better example! -->
</screen>
   </tip>
  </sect2>

  <sect2 xml:id="sec-sudo-shell">
   <title>Starting a Shell</title>
   <para>
    Having to add &sudo; before every command can be cumbersome. While you
    could specify a shell as a command <command>sudo bash</command>, it is
    recommended to rather use one of the built-in mechanisms to start a shell:
   </para>
   <variablelist>
    <varlistentry>
     <term><literal>sudo -s (&lt;command&gt;)</literal>
     </term>
     <listitem>
      <para>
       Starts a shell specified by the <envar>SHELL</envar> environment
       variable or the target user's default shell. If a command is given, it
       is passed to the shell (with the <option>-c</option> option), else the
       shell is run in interactive mode.
      </para>
<screen>
<prompt>&exampleuser_plain;:~ &gt; </prompt>sudo -i
root's password:
<prompt>root:/home/tux # </prompt>exit
<prompt>&exampleuser_plain;:~ &gt; </prompt>
</screen>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><literal>sudo -i (&lt;command&gt;)</literal>
     </term>
     <listitem>
      <para>
       Like <option>-s</option>, but starts the shell as login shell. This
       means that the shell's start-up files (<filename>.profile</filename>
       etc.) are processed and the current working directory is set to the
       target user's home directory.
      </para>
<screen>
<prompt>&exampleuser_plain;:~ &gt; </prompt>sudo -i
root's password:
<prompt>root:~ # </prompt>exit
<prompt>&exampleuser_plain;:~ &gt; </prompt>
            </screen>
     </listitem>
    </varlistentry>
   </variablelist>
  </sect2>

  <sect2 xml:id="sec-adm-sudo-usage-env">
   <title>Environment Variables</title>
   <para>
    By default, &sudo; does not propagate environment variables:
   </para>
<screen>
&prompt.user;ENVVAR=test env | grep ENVVAR
ENVVAR=test
&prompt.user;ENVVAR=test sudo env | grep ENVVAR
root's password:
<co xml:id="co-sudo-env-novar"/>
&prompt.user;
      </screen>
   <calloutlist>
    <callout arearefs="co-sudo-env-novar">
     <para>
      The empty output shows that the environment variable
      <envar>ENVVAR</envar> did not exist in the context of the command run
      with &sudo;.
     </para>
    </callout>
   </calloutlist>
   <para>
    This behavior can be changed by the <literal>env_reset</literal> option,
    see <xref linkend="tab-adm-sudo-options"/>.
   </para>
  </sect2>
 </sect1>
 <sect1 xml:id="sec-sudo-conf">
  <title>Configuring &sudo;</title>

  <para>
   &sudo; is a very flexible tool with extensive configuration.
  </para>

  <note>
   <title>Locked yourself out of sudo</title>
   <para>
    If you accidentally locked yourself out of &sudo;, use <command>su
    -</command> and the &rootuser; password to get a root shell.
    To fix the error, run <command>visudo</command>.
   </para>
  </note>

  <sect2 xml:id="sec-sudo-conf-edit">
   <title>Editing the Configuration Files</title>
   <!-- Idea for additional content: setting up LDAP/SASL authentication:
   /etc/ldap.conf -> use_sasl; man sudoers.ldap (via bsc#979531)
   - sknorr, 2016-08-22 -->
   <para>
    The main policy configuration file for &sudo; is
    <filename>/etc/sudoers</filename>. As it is possible to lock yourself out
    of the system due to errors in this file, it is strongly
    recommended to use <command>visudo</command> for editing. It will prevent
    simultaneous changes to the opened file and check for syntax errors before
    saving the modifications.
   </para>
   <para>
    Despite its name, you can also use editors other than vi by setting the
    <envar>EDITOR</envar> environment variable, for example:
   </para>
<screen>sudo EDITOR=<replaceable>/usr/bin/nano</replaceable> visudo</screen>
   <para>
    However, the <filename>/etc/sudoers</filename> file itself is supplied by
    the system packages and modifications may break on updates. Therefore, it
    is recommended to put custom configuration into files in the
    <filename>/etc/sudoers.d/</filename> directory. Any file in there is
    automatically included. To create or edit a file in that subdirectory, run:
   </para>
<screen>sudo visudo -f /etc/sudoers.d/<replaceable>NAME</replaceable></screen>
   <para>
    Alternatively with a different editor (for example
    <command>nano</command>):
   </para>
<screen>sudo EDITOR=<replaceable>/usr/bin/nano</replaceable> visudo -f /etc/sudoers.d/<replaceable>NAME</replaceable></screen>
   <note>
    <title>Ignored Files in <filename>/etc/sudoers.d</filename></title>
    <para>
     The <literal>#includedir</literal> command in
     <filename>/etc/sudoers</filename>, used for
     <filename>/etc/sudoers.d</filename>, ignores files that end in
     <literal>~</literal> (tilde) or contain a <literal>.</literal> (dot).
    </para>
   </note>
   <para>
    For more information on the <command>visudo</command> command, run
    <command>man 8 visudo</command>.
   </para>
  </sect2>

  <sect2 xml:id="sec-sudo-conf-syntax">
   <title>Basic sudoers Configuration Syntax</title>
   <para>
    In the sudoers configuration files, there are two types of options: strings
    and flags. While strings can contain any value, flags can be turned either
    ON or OFF. The most important syntax constructs for sudoers configuration
    files are:
   </para>
<screen>
# Everything on a line after a # gets ignored <co xml:id="co-sudo-syntax-comment"/>
Defaults !insults # Disable the insults flag <co xml:id="co-sudo-syntax-flag"/>
Defaults env_keep += "DISPLAY HOME" # Add DISPLAY and HOME to env_keep
&exampleuser_plain; ALL = NOPASSWD: /usr/bin/frobnicate, PASSWD: /usr/bin/journalctl <co xml:id="co-sudo-syntax-rule"/>
</screen>
   <calloutlist>
    <callout arearefs="co-sudo-syntax-comment">
     <para>
      There are two exceptions: <literal>#include</literal> and
      <literal>#includedir</literal> are normal commands. Followed by digits,
      it specifies a UID.
     </para>
    </callout>
    <callout arearefs="co-sudo-syntax-flag">
     <para>
      Remove the <literal>!</literal> to set the specified flag to ON.
     </para>
    </callout>
    <callout arearefs="co-sudo-syntax-rule">
     <para>
      See <xref linkend="sec-sudo-conf-rule"/>.
     </para>
    </callout>
   </calloutlist>
   <table xml:id="tab-adm-sudo-options">
    <title>Useful Flags and Options</title>
    <tgroup cols="3">
     <thead>
      <row>
       <entry>
        <para>
         Option name
        </para>
       </entry>
       <entry>
        <para>
         Description
        </para>
       </entry>
       <entry>
        <para>
         Example
        </para>
       </entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry><literal>targetpw</literal>
       </entry>
       <entry>
        <para>
         This flag controls whether the invoking user is required to enter the
         password of the target user (ON) (for example &rootuser;) or the
         invoking user (OFF).
        </para>
       </entry>
       <entry>
<screen>Defaults targetpw # Turn targetpw flag ON</screen>
       </entry>
      </row>
      <row>
       <entry><literal>rootpw</literal>
       </entry>
       <entry>
        <para>
         If set, &sudo; will prompt for the &rootuser; password instead of the
         target user's or the password of the user that invoked the command. The default is OFF.
        </para>
       </entry>
       <entry>
<screen>Defaults !rootpw # Turn rootpw flag OFF</screen>
       </entry>
      </row>
      <row>
       <entry><literal>env_reset</literal>
       </entry>
       <entry>
        <para>
         If set, &sudo; constructs a minimal environment with only
         <envar>TERM</envar>, <envar>PATH</envar>, <envar>HOME</envar>,
         <envar>MAIL</envar>, <envar>SHELL</envar>, <envar>LOGNAME</envar>,
         <envar>USER</envar>, <envar>USERNAME</envar>, and
         <envar>SUDO_*</envar> set. Additionally, variables listed in
         <literal>env_keep</literal> get imported from the calling
         environment. The default is ON.
        </para>
       </entry>
       <entry>
<screen>Defaults env_reset # Turn env_reset flag ON</screen>
       </entry>
      </row>
      <row>
       <entry><literal>env_keep</literal>
       </entry>
       <entry>
        <para>
         List of environment variables to keep when the
         <literal>env_reset</literal> flag is ON.
        </para>
       </entry>
       <entry>
<screen>
# Set env_keep to contain EDITOR and PROMPT
Defaults env_keep = "EDITOR PROMPT"
Defaults env_keep += "JRE_HOME" # Add JRE_HOME
Defaults env_keep -= "JRE_HOME" # Remove JRE_HOME
</screen>
       </entry>
      </row>
      <row>
       <entry><literal>env_delete</literal>
       </entry>
       <entry>
        <para>
         List of environment variables to remove when the
         <literal>env_reset</literal> flag is OFF.
        </para>
       </entry>
       <entry>
<screen>
# Set env_delete to contain EDITOR and PROMPT
Defaults env_delete = "EDITOR PROMPT"
Defaults env_delete += "JRE_HOME" # Add JRE_HOME
Defaults env_delete -= "JRE_HOME" # Remove JRE_HOME
</screen>
       </entry>
      </row>
     </tbody>
    </tgroup>
   </table>
   <para>
    The <literal>Defaults</literal> token can also be used to create aliases
    for a collection of users, hosts, and commands. Furthermore, it is possible
    to apply an option only to a specific set of users.
   </para>
   <para>
    For detailed information about the <filename>/etc/sudoers</filename>
    configuration file, consult <command>man 5 sudoers</command>.
   </para>
  </sect2>

  <sect2 xml:id="sec-sudo-conf-rule">
   <title>Rules in sudoers</title>
   <para>
    Rules in the sudoers configuration can be very complex, so this section
    will only cover the basics. Each rule follows the basic scheme
    (<literal>[]</literal> marks optional parts):
   </para>
<screen>
#Who      Where         As whom      Tag                What
User_List Host_List = [(User_List)] [NOPASSWD:|PASSWD:] Cmnd_List
</screen>
   <variablelist>
    <title>Syntax for sudoers Rules</title>
    <varlistentry>
     <term><literal>User_List</literal>
     </term>
     <listitem>
      <para>
       One or more (separated by <literal>,</literal>) identifiers: Either a
       user name, a group in the format <literal>%GROUPNAME</literal> or a user
       ID in the format <literal>#UID</literal>. Negation can be performed with
       a <literal>!</literal> prefix.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><literal>Host_List</literal>
     </term>
     <listitem>
      <para>
       One or more (separated by <literal>,</literal>) identifiers: Either a
       (fully qualified) host name or an IP address. Negation can be performed
       with a <literal>!</literal> prefix. <literal>ALL</literal> is the usual
       choice for <literal>Host_List</literal>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><literal>NOPASSWD:|PASSWD:</literal>
     </term>
     <listitem>
      <para>
       The user will not be prompted for a password when running commands
       matching <literal>CMDSPEC</literal> after <literal>NOPASSWD:</literal>.
      </para>
      <para>
       <literal>PASSWD</literal> is the default, it only needs to be specified
       when both are on the same line:
      </para>
<screen>&exampleuser_plain; ALL = PASSWD: /usr/bin/foo, NOPASSWD: /usr/bin/bar</screen>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><literal>Cmnd_List</literal>
     </term>
     <listitem>
      <para>
       One or more (separated by <literal>,</literal>) specifiers: A path to an
       executable, followed by allowed arguments or nothing.
      </para>
<screen>
/usr/bin/foo     # Anything allowed
/usr/bin/foo bar # Only "/usr/bin/foo bar" allowed
/usr/bin/foo ""  # No arguments allowed
</screen>
     </listitem>
    </varlistentry>
   </variablelist>
   <para>
    <literal>ALL</literal> can be used as <literal>User_List</literal>,
    <literal>Host_List</literal>, and <literal>Cmnd_List</literal>.
   </para>
   <para>
    A rule that allows &exampleuser; to run all commands as root without
    entering a password:
   </para>
<screen>&exampleuser_plain; ALL = NOPASSWD: ALL</screen>
   <para>
    A rule that allows &exampleuser; to run <command>systemctl restart
    apache2</command>:
   </para>
<screen>&exampleuser_plain; ALL = /usr/bin/systemctl restart apache2</screen>
   <para>
    A rule that allows &exampleuser; to run <command>wall</command> as
    <systemitem>admin</systemitem> with no arguments:
   </para>
<screen>&exampleuser_plain; ALL = (admin) /usr/bin/wall ""</screen>
   <warning>
    <title>Dangerous constructs</title>
    <para>
     Constructs of the kind
    </para>
<screen>ALL ALL = ALL</screen>
    <para>
     <emphasis>must not</emphasis> be used without <literal>Defaults
     targetpw</literal>, otherwise anyone can run commands as &rootuser;.
    </para>
   </warning>
   <important>
   <title>Winbind and sudo</title>
   <para>
   When specifying the group name in the <filename>sudoers</filename> file, make sure that you use the the NetBIOS domain name instead of the realm, for example:
   </para>
<screen><replaceable>%DOMAIN</replaceable>\\<replaceable>GROUP_NAME</replaceable> ALL = (ALL) ALL</screen>
   <para>
   Keep in mind that when using winbindd, the format also depends on the <option>winbind separator</option> option in the <filename>smb.conf</filename> file. By default, it is <literal>\</literal>. If it is changed, for example, to <literal>+</literal>, then the account format in <filename>sudoers</filename> file must be <literal>DOMAIN+GROUP_NAME</literal>.
   </para>
   </important>
  </sect2>
 </sect1>
 <sect1 xml:id="sec-sudo-usecases">
  <title>Common Use Cases</title>

  <para>
   Although the default configuration is often sufficient for simple setups and
   desktop environments, custom configurations can be very useful.
  </para>

    <sect2 xml:id="sec-sudo-usecases-userpw">
      <title>Using &sudo; without &rootuser; password</title>
      <para>
        By design, members of the group
        <systemitem class="groupname">wheel</systemitem> can run all commands
        with &sudo; as root. The following procedure explains how to add a user
        account to the <systemitem class="groupname">wheel</systemitem> group.
      </para>
      <procedure>
        <step>
          <para>
            Verify that the <systemitem class="groupname">wheel</systemitem>
            group exists:
          </para>
<screen>&prompt.user;<command>getent group wheel</command></screen>
          <para>
            If the previous command returned no result, install the
            <package>system-group-wheel</package> package that creates the
            <systemitem class="groupname">wheel</systemitem> group:
          </para>
<screen>&prompt.sudo;<command>zypper install system-group-wheel</command></screen>
        </step>
        <step>
          <para>
            Add your user account to the group
            <systemitem class="groupname">wheel</systemitem>.
          </para>
          <para>
            If your user account is not already a member of the
            <systemitem class="groupname">wheel</systemitem> group, add it
            using the <command>sudo usermod -a -G wheel
            <replaceable>USERNAME</replaceable></command> command. Log out and
            log in again to enable the change. Verify that the change was
            successful by running the <command>groups
            <replaceable>USERNAME</replaceable></command> command.
          </para>
        </step>
        <step>
          <para>
            Authenticate with the user account's normal password.
          </para>
          <para>
            Create the file <filename>/etc/sudoers.d/userpw</filename> using
            the <command>visudo</command> command (see
            <xref linkend="sec-sudo-conf-edit"/>) and add the following:
          </para>
<screen>Defaults !targetpw</screen>
    </step>
    <step>
     <para>
      Select a new default rule.
     </para>
     <para>
      Depending on whether you want users to re-enter their passwords,
      uncomment the specific line in <filename>/etc/sudoers</filename> and
      comment out the default rule.
     </para>
<screen>
## Uncomment to allow members of group wheel to execute any command
# %wheel ALL=(ALL) ALL

## Same thing without a password
# %wheel ALL=(ALL) NOPASSWD: ALL
</screen>
    </step>
    <step>
     <para>
      Make the default rule more restrictive
     </para>
     <para>
      Comment out or remove the allow-everything rule in
      <filename>/etc/sudoers</filename>:
     </para>
<screen>ALL     ALL=(ALL) ALL   # WARNING! Only use this together with 'Defaults targetpw'!</screen>
     <warning>
      <title>Dangerous rule in sudoers</title>
      <para>
       Do not forget this step, otherwise <emphasis>any</emphasis> user can
       execute <emphasis>any</emphasis> command as &rootuser;!
      </para>
     </warning>
    </step>
    <step>
     <para>
      Test the configuration
     </para>
     <para>
      Try to run &sudo; as member and non-member of
      <systemitem class="groupname">wheel</systemitem>.
     </para>
<screen>
<prompt>&exampleuser_plain;:~ &gt; </prompt>groups
users wheel
<prompt>&exampleuser_plain;:~ &gt; </prompt>sudo id -un
&exampleuser_plain;'s password:
root
<prompt>&exampleuserII_plain;:~ &gt; </prompt>groups
users
<prompt>&exampleuserII_plain;:~ &gt; </prompt>sudo id -un
&exampleuserII_plain; is not in the sudoers file.  This incident will be reported.
          </screen>
    </step>
   </procedure>
  </sect2>

  <sect2 xml:id="sec-sudo-usecases-xorg">
   <title>Using &sudo; with &xvendor; Applications</title>
   <para>
    When starting graphical applications with &sudo;, you will encounter the
    following error:
   </para>
<screen>
&prompt.user;sudo xterm
xterm: Xt error: Can't open display: %s
xterm: DISPLAY is not set
      </screen>
   <para>
    &yast; will pick the ncurses interface instead of the graphical one.
   </para>
   <para>
    To use &xvendor; in applications started with &sudo;, the environment
    variables <envar>DISPLAY</envar> and <envar>XAUTHORITY</envar> need to be
    propagated. To configure this, create the file
    <filename>/etc/sudoers.d/xorg</filename>, (see
    <xref linkend="sec-sudo-conf-edit"/>) and add the following line:
   </para>
<screen>Defaults env_keep += "DISPLAY XAUTHORITY"</screen>
   <para>
    If not set already, set the <envar>XAUTHORITY</envar> variable as follows:
   </para>
<screen>export XAUTHORITY=~/.Xauthority</screen>
   <para>
    Now &xvendor; applications can be run as usual:
   </para>
<screen>sudo yast2</screen>
<!-- Should be integrated somewhere else
      <warning>
        <title>Potential security issue</title>
        <para>
          As every &xvendor; client can control other &xvendor; clients on the same display.
          A malicious application can thus use the program to perform actions with elevated privileges.
        </para>
      </warning>-->
  </sect2>
 </sect1>
 <sect1 xml:id="sec-adm-sudo-moreinfo">
  <title>More Information</title>

  <para>
   A quick overview about the available command line switches can be retrieved
   by <command>sudo --help</command>. An explanation and other important
   information can be found in the man page: <command>man 8 sudo</command>,
   while the configuration is documented in <command>man 5 sudoers</command>.
  </para>
 </sect1>
</chapter>