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" xmlns:its="http://www.w3.org/2005/11/its" version="5.0" xml:id="cha-adm-sudo">
  <title>&sudo; basics</title>
  <info>
    <meta name="description" its:translate="yes">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>
  </info>
  <para>
    Running certain commands requires root privileges. However, for security
    reasons and to avoid mistakes, it is not recommended to log in as
    &rootuser;. A safer approach is to log in as a regular user, and then use
    &sudo; to run commands with elevated privileges.
  </para>
  <para>
    On &productname;, &sudo; is configured to work similarly to
    <command>su</command>. However, &sudo; provides a flexible mechanism that
    allows users to run commands with privileges of any other user. This can be
    used to assign roles with specific privileges to certain users and groups.
    For example, it is possible to allow members of the group &examplegroup; to
    run a command with the privileges of user &exampleuserII;. Access to the
    command can be further restricted by disallowing 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
    means that the users do not need to share the &rootuser; password, which
    improves security.
  </para>
  <sect1 xml:id="sec-adm-sudo-usage">
    <title>Basic &sudo; usage</title>

    <para>
      The following chapter provides an introduction to basic usage of &sudo;.
    </para>

    <sect2 xml:id="sec-adm-sudo-usage-cmd">
      <title>Running a single command</title>
      <para>
        As a regular user, you can run any command as &rootuser; by adding
        &sudo; before it. This prompts you to provide the root password. If
        authenticated successfully, this runs the command as &rootuser;:
      </para>
<screen>
&prompt.user;<command>id -un</command><co xml:id="co-sudo-usage-id"/>
tux
&prompt.sudo;<command>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.sudo;<command>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 masking characters.
          </para>
        </callout>
        <callout arearefs="co-sudo-usage-after">
          <para>
            Only commands that start with &sudo; run with elevated privileges.
          </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>
          When using &sudo;, I/O redirection does not work:
        </para>
<screen>
&prompt.sudo;echo s &gt; /proc/sysrq-trigger
bash: /proc/sysrq-trigger: Permission denied
&prompt.sudo;cat &lt; /proc/1/maps
bash: /proc/1/maps: Permission denied
</screen>
        <para>
          In the example above, only the <command>echo</command> and
          <command>cat</command> commands run with elevated privileges. The
          redirection is done by the user's shell with user privileges. To
          perform redirection with elevated privileges, either start a shell as
          in <xref linkend="sec-sudo-shell"/> or use the
          <command>dd</command> utility:
        </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>
        Using &sudo; every time to run a command with elevated privileges is
        not always practical. While you can use the <command>sudo
        bash</command> command, it is recommended to 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
              specified, it is passed to the shell (with the
              <option>-c</option> option). Otherwise the shell runs in
              interactive mode.
            </para>
<screen>
<prompt>&exampleuser_plain;:~ &gt; </prompt>sudo -s
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>
              Similar to <option>-s</option>, but starts the shell as a 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>
      <tip>
        <title>Environment variables</title>
        <para>
          By default, &sudo; does not propagate environment variables. This
          behavior can be changed using the <literal>env_reset</literal> option
          (see <xref linkend="tab-adm-sudo-options"/>).
        </para>
      </tip>
    </sect2>
  </sect1>
  <sect1 xml:id="sec-sudo-conf">
    <title>Configuring &sudo;</title>

    <para>
      &sudo; provides a wide range on configurable options.
    </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 start 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>
      <para>
        The main policy configuration file for &sudo; is
        <filename>/etc/sudoers</filename>. As it is possible to lock yourself
        out of the system if the file is malformed, it is strongly recommended
        to use <command>visudo</command> for editing. It prevents editing
        conflicts and checks for syntax errors before saving the modifications.
      </para>
      <para>
        You can use another editor instead of vi by setting the
        <envar>EDITOR</envar> environment variable, for example:
      </para>
<screen>sudo EDITOR=<replaceable>/usr/bin/nano</replaceable> visudo</screen>
      <para>
        Keep in mind that the <filename>/etc/sudoers</filename> file is
        supplied by the system packages, and modifications done directly in the
        file may break updates. Therefore, it is recommended to put custom
        configuration into files in the <filename>/etc/sudoers.d/</filename>
        directory. Use the following command to create or edit a file:
      </para>
<screen>sudo visudo -f /etc/sudoers.d/<replaceable>NAME</replaceable></screen>
      <para>
        The command bellow opens the file using a different editor (in this
        case, <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> directive in
          <filename>/etc/sudoers</filename> ignores files that end with the
          <literal>~</literal> (tilde) character or contain the
          <literal>.</literal> (dot) character.
        </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>
        The sudoers configuration files contain 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 as follows:
      </para>
<screen>
# Everything on a line after # is 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 regular commands.
          </para>
        </callout>
        <callout arearefs="co-sudo-syntax-flag">
          <para>
            Remove the <literal>!</literal> character to set the desired flag
            to ON.
          </para>
        </callout>
        <callout arearefs="co-sudo-syntax-rule">
          <para>
            See <xref linkend="sec-sudo-conf-rule"/>.
          </para>
        </callout>
      </calloutlist>
      <variablelist xml:id="tab-adm-sudo-options">
        <title>Useful flags and options</title>
        <varlistentry>
          <term><literal>targetpw</literal></term>
          <listitem>
            <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>
<screen>Defaults targetpw # Turn targetpw flag ON</screen>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><literal>rootpw</literal></term>
          <listitem>
            <para>
              If set, &sudo; prompts for the &rootuser; password. The default
              is OFF.
            </para>
<screen>Defaults !rootpw # Turn rootpw flag OFF</screen>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><literal>env_reset</literal></term>
          <listitem>
            <para>
              If set, &sudo; constructs a minimal environment with
              <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>. Additionally,
              variables listed in <literal>env_keep</literal> are imported from
              the calling environment. The default is ON.
            </para>
<screen>Defaults env_reset # Turn env_reset flag ON</screen>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><literal>env_keep</literal></term>
          <listitem>
            <para>
              List of environment variables to keep when the
              <literal>env_reset</literal> flag is ON.
            </para>
<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>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><literal>env_delete</literal></term>
          <listitem>
            <para>
              List of environment variables to remove when the
              <literal>env_reset</literal> flag is OFF.
            </para>
<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>
          </listitem>
        </varlistentry>
      </variablelist>
      <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>Basic sudoers rules</title>
      <para>
        Each rule follows the following 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>sudoers rule syntax</title>
        <varlistentry>
          <term><literal>User_List</literal></term>
          <listitem>
            <para>
              One or several (separated by comma) 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
              specified with the <literal>!</literal> prefix.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><literal>Host_List</literal></term>
          <listitem>
            <para>
              One or several (separated by comma) identifiers: either a (fully
              qualified) host name or an IP address. Negation can be specified
              with the <literal>!</literal> prefix. <literal>ALL</literal> is a
              common choice for <literal>Host_List</literal>.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><literal>NOPASSWD:|PASSWD:</literal></term>
          <listitem>
            <para>
              The user is not prompted for a password when running commands
              matching <literal>Cmd_List</literal> after
              <literal>NOPASSWD:</literal>.
            </para>
            <para>
              <literal>PASSWD</literal> is the default. It only needs to be
              specified when both <literal>PASSWD</literal> and
              <literal>NOPASSWD</literal> 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 several (separated by comma) specifiers: a path to an
              executable, followed by an optional allowed argument.
            </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>Unsafe rules</title>
        <para>
          <emphasis>Do not</emphasis> use rules like <literal>ALL ALL =
          ALL</literal> 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 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 the
          <filename>sudoers</filename> file must be
          <literal>DOMAIN+GROUP_NAME</literal>.
        </para>
      </important>
    </sect2>
  </sect1>
  <sect1 xml:id="sec-sudo-usecases">
    <title>&sudo; use cases</title>

    <para>
      While the default configuration works for standard usage scenarios, you
      can customize the default configuration to meet your specific needs.
    </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 appropriate 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 skip 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>
            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>
        Starting graphical applications with &sudo; normally results in the
        following error:
      </para>
<screen>
&prompt.sudo;xterm
xterm: Xt error: Can't open display: %s
xterm: DISPLAY is not set
</screen>
      <para>
        A simple workaround is to use xhost to temporarily allow the root user
        to access the local user's X session. This is done using the following
        command:
      </para>
<screen>xhost si:localuser:root</screen>
      <para>
        The command below removes the granted access:
      </para>
<screen>xhost -si:localuser:root</screen>
      <warning>
        <title>Potential security issue</title>
        <para>
          Running graphical applications with root privileges has security
          implications. It is recommended to enable root access for a graphical
          application only as an exception. It is also recommended to revoke
          the granted root access as soon as the graphical application is
          closed.
        </para>
      </warning>
    </sect2>
  </sect1>
  <sect1 xml:id="sec-adm-sudo-moreinfo">
    <title>More information</title>

    <para>
      The <command>sudo --help</command> command offers a brief overview of the
      available command line options, while the <command>man sudoers</command>
      command provides detailed information about <filename>sudoers</filename>
      and its configuration.
    </para>
  </sect1>
</chapter>