man/uid0.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   5
   6 <refentry id="uid0"
   7           xmlns:xi="http://www.w3.org/2001/XInclude">
   8
   9   <refentryinfo>
  10     <title>uid0</title>
  11     <productname>systemd</productname>
  12   </refentryinfo>
  13
  14   <refmeta>
  15     <refentrytitle>uid0</refentrytitle>
  16     <manvolnum>1</manvolnum>
  17   </refmeta>
  18
  19   <refnamediv>
  20     <refname>uid0</refname>
  21     <refpurpose>Elevate privileges</refpurpose>
  22   </refnamediv>
  23
  24   <refsynopsisdiv>
  25     <cmdsynopsis>
  26       <command>uid0</command>
  27       <arg choice="opt" rep="repeat">OPTIONS</arg>
  28       <arg choice="opt" rep="repeat">COMMAND</arg>
  29     </cmdsynopsis>
  30   </refsynopsisdiv>
  31
  32   <refsect1>
  33     <title>Description</title>
  34
  35     <para><command>uid0</command> may be used to temporarily and interactively acquire elavated or different
  36     privileges. It serves a similar purpose as <citerefentry
  37     project='man-pages'><refentrytitle>sudo</refentrytitle><manvolnum>8</manvolnum></citerefentry>, but
  38     operates differently in a couple of key areas:</para>
  39
  40     <itemizedlist>
  41       <listitem><para>No execution or security context credentials are inherited from the caller into the
  42       invoked commands, as they are invoked from a fresh, isolated service forked off the service
  43       manager.</para></listitem>
  44
  45       <listitem><para>Authentication takes place via <ulink
  46       url="https://www.freedesktop.org/wiki/Software/polkit">polkit</ulink>, thus isolating the
  47       authentication prompt from the terminal (if possible).</para></listitem>
  48
  49       <listitem><para>An independent pseudo-tty is allocated for the invoked command, detaching its lifecycle and
  50       isolating it for security.</para></listitem>
  51
  52       <listitem><para>No SetUID/SetGID file access bit functionality is used for the implementation.</para></listitem>
  53     </itemizedlist>
  54
  55     <para>Altogether this should provide a safer and more robust alternative to the <command>sudo</command>
  56     mechanism, in particular in OS environments where SetUID/SetGID support is not available (for example by
  57     setting the <varname>NoNewPrivileges=</varname> variable in
  58     <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>).</para>
  59
  60     <para>Any session invoked via <command>uid0</command> will run through the
  61     <literal>systemd-uid0</literal> PAM stack.</para>
  62
  63     <para>Note that <command>uid0</command> is implemented as an alternative multi-call invocation of
  64     <citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
  65   </refsect1>
  66
  67   <refsect1>
  68     <title>Options</title>
  69
  70     <para>The following options are understood:</para>
  71
  72     <variablelist>
  73       <varlistentry>
  74         <term><option>--no-ask-password</option></term>
  75
  76         <listitem><para>Do not query the user for authentication for privileged operations.</para>
  77
  78         <xi:include href="version-info.xml" xpointer="v256"/></listitem>
  79       </varlistentry>
  80
  81       <varlistentry>
  82         <term><option>--unit=</option></term>
  83
  84         <listitem><para>Use this unit name instead of an automatically generated one.</para>
  85
  86         <xi:include href="version-info.xml" xpointer="v256"/></listitem>
  87       </varlistentry>
  88
  89       <varlistentry>
  90         <term><option>--property=</option></term>
  91
  92         <listitem><para>Sets a property on the service unit that is created. This option takes an assignment
  93         in the same format as
  94         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
  95         <command>set-property</command> command.</para>
  96
  97         <xi:include href="version-info.xml" xpointer="v256"/>
  98         </listitem>
  99       </varlistentry>
 100
 101       <varlistentry>
 102         <term><option>--description=</option></term>
 103
 104         <listitem><para>Provide a description for the service unit that is invoked. If not specified,
 105         the command itself will be used as a description. See <varname>Description=</varname> in
 106         <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
 107         </para>
 108
 109         <xi:include href="version-info.xml" xpointer="v256"/></listitem>
 110       </varlistentry>
 111
 112       <varlistentry>
 113         <term><option>--slice=</option></term>
 114
 115         <listitem><para>Make the new <filename>.service</filename> unit part of the specified slice, instead
 116         of <filename>user.slice</filename>.</para>
 117
 118         <xi:include href="version-info.xml" xpointer="v256"/>
 119         </listitem>
 120       </varlistentry>
 121
 122       <varlistentry>
 123         <term><option>--slice-inherit</option></term>
 124
 125         <listitem><para>Make the new <filename>.service</filename> unit part of the slice the
 126         <command>uid0</command> itself has been invoked in. This option may be combined with
 127         <option>--slice=</option>, in which case the slice specified via <option>--slice=</option> is placed
 128         within the slice the <command>uid0</command> command is invoked in.</para>
 129
 130         <para>Example: consider <command>uid0</command> being invoked in the slice
 131         <filename>foo.slice</filename>, and the <option>--slice=</option> argument is
 132         <filename>bar</filename>. The unit will then be placed under
 133         <filename>foo-bar.slice</filename>.</para>
 134
 135         <xi:include href="version-info.xml" xpointer="v256"/>
 136
 137         </listitem>
 138       </varlistentry>
 139
 140       <varlistentry>
 141         <term><option>--user=</option></term>
 142         <term><option>-u</option></term>
 143         <term><option>--group=</option></term>
 144         <term><option>-g</option></term>
 145
 146         <listitem><para>Switches to the specified user/group instead of root.</para>
 147
 148         <xi:include href="version-info.xml" xpointer="v256"/>
 149         </listitem>
 150       </varlistentry>
 151
 152       <varlistentry>
 153         <term><option>--nice=</option></term>
 154
 155         <listitem><para>Runs the invoked session with the specified nice level.</para>
 156
 157         <xi:include href="version-info.xml" xpointer="v256"/>
 158         </listitem>
 159       </varlistentry>
 160
 161       <varlistentry>
 162         <term><option>--chdir=</option></term>
 163         <term><option>-D</option></term>
 164
 165         <listitem><para>Runs the invoked session with the specified working directory. If not specified
 166         defaults to the client's current working directory if switching to the root user, or the target
 167         user's home directory otherwise.</para>
 168
 169         <xi:include href="version-info.xml" xpointer="v256"/>
 170         </listitem>
 171       </varlistentry>
 172
 173       <varlistentry>
 174         <term><option>--setenv=<replaceable>NAME</replaceable>[=<replaceable>VALUE</replaceable>]</option></term>
 175
 176         <listitem><para>Runs the invoked session with the specified environment variable set. This parameter
 177         may be used more than once to set multiple variables. When <literal>=</literal> and
 178         <replaceable>VALUE</replaceable> are omitted, the value of the variable with the same name in the
 179         invoking environment will be used.</para>
 180
 181         <xi:include href="version-info.xml" xpointer="v256"/>
 182         </listitem>
 183       </varlistentry>
 184
 185       <varlistentry>
 186         <term><option>--background=<replaceable>COLOR</replaceable></option></term>
 187
 188         <listitem><para>Change the terminal background color to the specified ANSI color as long as the
 189         session lasts. If not specified, the background will be tinted in a reddish tone when operating as
 190         root, and in a yellowish tone when operating under another UID, as reminder of the changed
 191         privileges. The color specified should be an ANSI X3.64 SGR background color, i.e. strings such as
 192         <literal>40</literal>, <literal>41</literal>, …, <literal>47</literal>, <literal>48;2;…</literal>,
 193         <literal>48;5;…</literal>. See <ulink
 194         url="https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_(Select_Graphic_Rendition)_parameters">ANSI
 195         Escape Code (Wikipedia)</ulink> for details. Set to an empty string to disable.</para>
 196
 197         <para>Example: <literal>--background=44</literal> for a blue background.</para>
 198
 199         <xi:include href="version-info.xml" xpointer="v256"/>
 200         </listitem>
 201       </varlistentry>
 202
 203       <xi:include href="user-system-options.xml" xpointer="machine" />
 204       <xi:include href="standard-options.xml" xpointer="help" />
 205       <xi:include href="standard-options.xml" xpointer="version" />
 206     </variablelist>
 207
 208     <para>All command line arguments after the first non-option argument become part of the command line of
 209     the launched process. If no command line is specified an interactive shell is invoked. The shell to
 210     invoke may be controlled via <option>--setenv=SHELL=…</option> and currently defaults to the
 211     <emphasis>originating user's</emphasis> shell (i.e. not the target user's!) if operating locally, or
 212     <filename>/bin/sh</filename> when operating with <option>--machine=</option>.</para>
 213   </refsect1>
 214
 215   <refsect1>
 216     <title>Exit status</title>
 217
 218     <para>On success, 0 is returned. If <command>uid0</command> failed to start the session or the specified command fails, a
 219     non-zero return value will be returned.</para>
 220   </refsect1>
 221
 222   <refsect1>
 223     <title>See Also</title>
 224     <para><simplelist type="inline">
 225       <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 226       <member><citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 227       <member><citerefentry project='man-pages'><refentrytitle>sudo</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
 228       <member><citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 229     </simplelist></para>
 230   </refsect1>
 231
 232 </refentry>