[thirdparty/systemd.git] / man / run0.xml

<?xml version='1.0'?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->

<refentry id="run0"
          xmlns:xi="http://www.w3.org/2001/XInclude">

  <refentryinfo>
    <title>run0</title>
    <productname>systemd</productname>
  </refentryinfo>

  <refmeta>
    <refentrytitle>run0</refentrytitle>
    <manvolnum>1</manvolnum>
  </refmeta>

  <refnamediv>
    <refname>run0</refname>
    <refpurpose>Elevate privileges</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <cmdsynopsis>
      <command>run0</command>
      <arg choice="opt" rep="repeat">OPTIONS</arg>
      <arg choice="opt" rep="repeat">COMMAND</arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>Description</title>

    <para><command>run0</command> may be used to temporarily and interactively acquire elevated or different
    privileges. It serves a similar purpose as <citerefentry
    project='man-pages'><refentrytitle>sudo</refentrytitle><manvolnum>8</manvolnum></citerefentry>, but
    operates differently in a couple of key areas:</para>

    <itemizedlist>
      <listitem><para>No execution or security context credentials are inherited from the caller into the
      invoked commands, as they are invoked from a fresh, isolated service forked off by the service manager.
      </para></listitem>

      <listitem><para>Authentication takes place via <ulink
      url="https://www.freedesktop.org/wiki/Software/polkit">polkit</ulink>, thus isolating the
      authentication prompt from the terminal (if possible).</para></listitem>

      <listitem><para>An independent pseudo-tty is allocated for the invoked command, detaching its lifecycle and
      isolating it for security.</para></listitem>

      <listitem><para>No SetUID/SetGID file access bit functionality is used for the implementation.</para></listitem>
    </itemizedlist>

    <para>Altogether this should provide a safer and more robust alternative to the <command>sudo</command>
    mechanism, in particular in OS environments where SetUID/SetGID support is not available (for example by
    setting the <varname>NoNewPrivileges=</varname> variable in
    <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>).</para>

    <para>Any session invoked via <command>run0</command> will run through the
    <literal>systemd-run0</literal> PAM stack.</para>

    <para>Note that <command>run0</command> is implemented as an alternative multi-call invocation of
    <citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
  </refsect1>

  <refsect1>
    <title>Options</title>

    <para>The following options are understood:</para>

    <variablelist>
      <varlistentry>
        <term><option>--no-ask-password</option></term>

        <listitem><para>Do not query the user for authentication for privileged operations.</para>

        <xi:include href="version-info.xml" xpointer="v256"/></listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--unit=</option></term>

        <listitem><para>Use this unit name instead of an automatically generated one.</para>

        <xi:include href="version-info.xml" xpointer="v256"/></listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--property=</option></term>

        <listitem><para>Sets a property on the service unit that is created. This option takes an assignment
        in the same format as
        <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
        <command>set-property</command> command.</para>

        <xi:include href="version-info.xml" xpointer="v256"/>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--description=</option></term>

        <listitem><para>Provide a description for the service unit that is invoked. If not specified,
        the command itself will be used as a description. See <varname>Description=</varname> in
        <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
        </para>

        <xi:include href="version-info.xml" xpointer="v256"/></listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--slice=</option></term>

        <listitem><para>Make the new <filename>.service</filename> unit part of the specified slice, instead
        of <filename>user.slice</filename>.</para>

        <xi:include href="version-info.xml" xpointer="v256"/>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--slice-inherit</option></term>

        <listitem><para>Make the new <filename>.service</filename> unit part of the slice the
        <command>run0</command> itself has been invoked in. This option may be combined with
        <option>--slice=</option>, in which case the slice specified via <option>--slice=</option> is placed
        within the slice the <command>run0</command> command is invoked in.</para>

        <para>Example: consider <command>run0</command> being invoked in the slice
        <filename>foo.slice</filename>, and the <option>--slice=</option> argument is
        <filename>bar</filename>. The unit will then be placed under
        <filename>foo-bar.slice</filename>.</para>

        <xi:include href="version-info.xml" xpointer="v256"/>

        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--user=</option></term>
        <term><option>-u</option></term>
        <term><option>--group=</option></term>
        <term><option>-g</option></term>

        <listitem><para>Switches to the specified user/group instead of root.</para>

        <xi:include href="version-info.xml" xpointer="v256"/>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--nice=</option></term>

        <listitem><para>Runs the invoked session with the specified nice level.</para>

        <xi:include href="version-info.xml" xpointer="v256"/>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--chdir=</option></term>
        <term><option>-D</option></term>

        <listitem><para>Runs the invoked session with the specified working directory. If not specified
        defaults to the client's current working directory if switching to the root user, or the target
        user's home directory otherwise.</para>

        <xi:include href="version-info.xml" xpointer="v256"/>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--setenv=<replaceable>NAME</replaceable>[=<replaceable>VALUE</replaceable>]</option></term>

        <listitem><para>Runs the invoked session with the specified environment variable set. This parameter
        may be used more than once to set multiple variables. When <literal>=</literal> and
        <replaceable>VALUE</replaceable> are omitted, the value of the variable with the same name in the
        invoking environment will be used.</para>

        <xi:include href="version-info.xml" xpointer="v256"/>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--background=<replaceable>COLOR</replaceable></option></term>

        <listitem><para>Change the terminal background color to the specified ANSI color as long as the
        session lasts. If not specified, the background will be tinted in a reddish tone when operating as
        root, and in a yellowish tone when operating under another UID, as reminder of the changed
        privileges. The color specified should be an ANSI X3.64 SGR background color, i.e. strings such as
        <literal>40</literal>, <literal>41</literal>, …, <literal>47</literal>, <literal>48;2;…</literal>,
        <literal>48;5;…</literal>. See <ulink
        url="https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_(Select_Graphic_Rendition)_parameters">ANSI
        Escape Code (Wikipedia)</ulink> for details. Set to an empty string to disable.</para>

        <para>Example: <literal>--background=44</literal> for a blue background.</para>

        <xi:include href="version-info.xml" xpointer="v256"/>
        </listitem>
      </varlistentry>

      <xi:include href="user-system-options.xml" xpointer="machine" />
      <xi:include href="standard-options.xml" xpointer="help" />
      <xi:include href="standard-options.xml" xpointer="version" />
    </variablelist>

    <para>All command line arguments after the first non-option argument become part of the command line of
    the launched process. If no command line is specified an interactive shell is invoked. The shell to
    invoke may be controlled via <option>--setenv=SHELL=…</option> and currently defaults to the
    <emphasis>originating user's</emphasis> shell (i.e. not the target user's!) if operating locally, or
    <filename>/bin/sh</filename> when operating with <option>--machine=</option>.</para>
  </refsect1>

  <refsect1>
    <title>Exit status</title>

    <para>On success, 0 is returned. If <command>run0</command> failed to start the session or the specified command fails, a
    non-zero return value will be returned.</para>
  </refsect1>

  <refsect1>
    <title>Environment Variables</title>

    <para>As with <command>systemd-run</command>, the session will inherit the system
    environment from the service manager. In addition, the following environment variables will be set:</para>

    <variablelist>
      <varlistentry>
        <term><varname>$TERM</varname></term>
        <listitem><para>Copied from the <varname>$TERM</varname> of the caller. Can be overriden with <option>--setenv=</option></para>

        <xi:include href="version-info.xml" xpointer="v256"/></listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>$SUDO_USER</varname></term>
        <listitem><para>Set to the username of the originating user.</para>

        <xi:include href="version-info.xml" xpointer="v256"/></listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>$SUDO_UID</varname></term>
        <listitem><para>Set to the numeric UNIX user id of the originating user.</para>

        <xi:include href="version-info.xml" xpointer="v256"/></listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>$SUDO_GID</varname></term>
        <listitem><para>Set to the primary numeric UNIX group id of the originating session.</para>

        <xi:include href="version-info.xml" xpointer="v256"/></listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1>
    <title>See Also</title>
    <para><simplelist type="inline">
      <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
      <member><citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
      <member><citerefentry project='man-pages'><refentrytitle>sudo</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
      <member><citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
    </simplelist></para>
  </refsect1>

</refentry>
Commit	Line	Data
72eb3081 LP	1	<?xml version='1.0'?>
72eb3081 LP	2	<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
eea10b26	3	"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
72eb3081 LP	4	<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
72eb3081 LP	5
7aed4343	6	<refentry id="run0"
72eb3081 LP	7	xmlns:xi="http://www.w3.org/2001/XInclude">
	8
	9	<refentryinfo>
7aed4343	10	<title>run0</title>
72eb3081 LP	11	<productname>systemd</productname>
	12	</refentryinfo>
	13
	14	<refmeta>
7aed4343	15	<refentrytitle>run0</refentrytitle>
72eb3081 LP	16	<manvolnum>1</manvolnum>
	17	</refmeta>
	18
	19	<refnamediv>
7aed4343	20	<refname>run0</refname>
72eb3081 LP	21	<refpurpose>Elevate privileges</refpurpose>
	22	</refnamediv>
	23
	24	<refsynopsisdiv>
	25	<cmdsynopsis>
7aed4343	26	<command>run0</command>
72eb3081 LP	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
7aed4343	35	<para><command>run0</command> may be used to temporarily and interactively acquire elevated or different
72eb3081 LP	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
13e380b0 MY	42	invoked commands, as they are invoked from a fresh, isolated service forked off by the service manager.
13e380b0 MY	43	</para></listitem>
72eb3081 LP	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
7aed4343 ZJS	60	<para>Any session invoked via <command>run0</command> will run through the
7aed4343 ZJS	61	<literal>systemd-run0</literal> PAM stack.</para>
72eb3081	62
7aed4343	63	<para>Note that <command>run0</command> is implemented as an alternative multi-call invocation of
72eb3081 LP	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
7aed4343	126	<command>run0</command> itself has been invoked in. This option may be combined with
72eb3081	127	<option>--slice=</option>, in which case the slice specified via <option>--slice=</option> is placed
7aed4343	128	within the slice the <command>run0</command> command is invoked in.</para>
72eb3081	129
7aed4343	130	<para>Example: consider <command>run0</command> being invoked in the slice
72eb3081 LP	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
2f0b4d57 LP	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
72eb3081 LP	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
7aed4343	218	<para>On success, 0 is returned. If <command>run0</command> failed to start the session or the specified command fails, a
72eb3081 LP	219	non-zero return value will be returned.</para>
	220	</refsect1>
	221
7df0297a TM	222	<refsect1>
	223	<title>Environment Variables</title>
	224
	225	<para>As with <command>systemd-run</command>, the session will inherit the system
	226	environment from the service manager. In addition, the following environment variables will be set:</para>
	227
	228	<variablelist>
	229	<varlistentry>
	230	<term><varname>$TERM</varname></term>
	231	<listitem><para>Copied from the <varname>$TERM</varname> of the caller. Can be overriden with <option>--setenv=</option></para>
	232
	233	<xi:include href="version-info.xml" xpointer="v256"/></listitem>
	234	</varlistentry>
	235
	236	<varlistentry>
	237	<term><varname>$SUDO_USER</varname></term>
	238	<listitem><para>Set to the username of the originating user.</para>
	239
	240	<xi:include href="version-info.xml" xpointer="v256"/></listitem>
	241	</varlistentry>
	242
	243	<varlistentry>
	244	<term><varname>$SUDO_UID</varname></term>
	245	<listitem><para>Set to the numeric UNIX user id of the originating user.</para>
	246
	247	<xi:include href="version-info.xml" xpointer="v256"/></listitem>
	248	</varlistentry>
	249
	250	<varlistentry>
	251	<term><varname>$SUDO_GID</varname></term>
	252	<listitem><para>Set to the primary numeric UNIX group id of the originating session.</para>
	253
	254	<xi:include href="version-info.xml" xpointer="v256"/></listitem>
	255	</varlistentry>
	256	</variablelist>
	257	</refsect1>
	258
72eb3081 LP	259	<refsect1>
72eb3081 LP	260	<title>See Also</title>
13a69c12 DT	261	<para><simplelist type="inline">
	262	<member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
	263	<member><citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
	264	<member><citerefentry project='man-pages'><refentrytitle>sudo</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
	265	<member><citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
	266	</simplelist></para>
72eb3081 LP	267	</refsect1>
	268
	269	</refentry>