morgan/systemd
1
0
Fork 0
mirror of https://github.com/morgan9e/systemd synced 2026-04-15 00:47:10 +09:00
Code Issues Packages Projects Releases Wiki Activity
Files
main
systemd/man/run0.xml

423 lines
19 KiB
XML
Raw Permalink Normal View History

run: when invoked as "uid0", expose some sudo-like behaviour This turns "systemd-run" into a multi-call binary. When invoked under the name "uid0", then it behaves a bit more like traditional "sudo". This mostly means defaults appropriuate for that, for example a PAM stack, interactivity and more. Fixes: #29199
2023-12-19 19:10:52 +01:00
<?xml version='1.0'?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
man: use same version in public and system ident.
2023-12-25 15:48:33 +01:00
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
run: when invoked as "uid0", expose some sudo-like behaviour This turns "systemd-run" into a multi-call binary. When invoked under the name "uid0", then it behaves a bit more like traditional "sudo". This mostly means defaults appropriuate for that, for example a PAM stack, interactivity and more. Fixes: #29199
2023-12-19 19:10:52 +01:00
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
Rename uid0 to run0 Naming is always a matter of preference, and the old name would certainly work, but I think the new one has the following advantages: - A verb is better than a noun. - The name more similar to "the competition", i.e. 'sudo', 'pkexec', 'runas', 'doas', which generally include an action verb. - The connection between 'systemd-run' and 'run0' is more obvious. There has been no release yet with the old name, so we can rename without caring for backwards compatibility.
2024-03-19 11:14:55 +01:00
<refentry id="run0"
run: when invoked as "uid0", expose some sudo-like behaviour This turns "systemd-run" into a multi-call binary. When invoked under the name "uid0", then it behaves a bit more like traditional "sudo". This mostly means defaults appropriuate for that, for example a PAM stack, interactivity and more. Fixes: #29199
2023-12-19 19:10:52 +01:00
xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
Rename uid0 to run0 Naming is always a matter of preference, and the old name would certainly work, but I think the new one has the following advantages: - A verb is better than a noun. - The name more similar to "the competition", i.e. 'sudo', 'pkexec', 'runas', 'doas', which generally include an action verb. - The connection between 'systemd-run' and 'run0' is more obvious. There has been no release yet with the old name, so we can rename without caring for backwards compatibility.
2024-03-19 11:14:55 +01:00
<title>run0</title>
run: when invoked as "uid0", expose some sudo-like behaviour This turns "systemd-run" into a multi-call binary. When invoked under the name "uid0", then it behaves a bit more like traditional "sudo". This mostly means defaults appropriuate for that, for example a PAM stack, interactivity and more. Fixes: #29199
2023-12-19 19:10:52 +01:00
<productname>systemd</productname>
</refentryinfo>
<refmeta>
Rename uid0 to run0 Naming is always a matter of preference, and the old name would certainly work, but I think the new one has the following advantages: - A verb is better than a noun. - The name more similar to "the competition", i.e. 'sudo', 'pkexec', 'runas', 'doas', which generally include an action verb. - The connection between 'systemd-run' and 'run0' is more obvious. There has been no release yet with the old name, so we can rename without caring for backwards compatibility.
2024-03-19 11:14:55 +01:00
<refentrytitle>run0</refentrytitle>
run: when invoked as "uid0", expose some sudo-like behaviour This turns "systemd-run" into a multi-call binary. When invoked under the name "uid0", then it behaves a bit more like traditional "sudo". This mostly means defaults appropriuate for that, for example a PAM stack, interactivity and more. Fixes: #29199
2023-12-19 19:10:52 +01:00
<manvolnum>1</manvolnum>
</refmeta>
<refnamediv>
Rename uid0 to run0 Naming is always a matter of preference, and the old name would certainly work, but I think the new one has the following advantages: - A verb is better than a noun. - The name more similar to "the competition", i.e. 'sudo', 'pkexec', 'runas', 'doas', which generally include an action verb. - The connection between 'systemd-run' and 'run0' is more obvious. There has been no release yet with the old name, so we can rename without caring for backwards compatibility.
2024-03-19 11:14:55 +01:00
<refname>run0</refname>
run: when invoked as "uid0", expose some sudo-like behaviour This turns "systemd-run" into a multi-call binary. When invoked under the name "uid0", then it behaves a bit more like traditional "sudo". This mostly means defaults appropriuate for that, for example a PAM stack, interactivity and more. Fixes: #29199
2023-12-19 19:10:52 +01:00
<refpurpose>Elevate privileges</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
Rename uid0 to run0 Naming is always a matter of preference, and the old name would certainly work, but I think the new one has the following advantages: - A verb is better than a noun. - The name more similar to "the competition", i.e. 'sudo', 'pkexec', 'runas', 'doas', which generally include an action verb. - The connection between 'systemd-run' and 'run0' is more obvious. There has been no release yet with the old name, so we can rename without caring for backwards compatibility.
2024-03-19 11:14:55 +01:00
<command>run0</command>
run: when invoked as "uid0", expose some sudo-like behaviour This turns "systemd-run" into a multi-call binary. When invoked under the name "uid0", then it behaves a bit more like traditional "sudo". This mostly means defaults appropriuate for that, for example a PAM stack, interactivity and more. Fixes: #29199
2023-12-19 19:10:52 +01:00
<arg choice="opt" rep="repeat">OPTIONS</arg>
<arg choice="opt" rep="repeat">COMMAND</arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
Rename uid0 to run0 Naming is always a matter of preference, and the old name would certainly work, but I think the new one has the following advantages: - A verb is better than a noun. - The name more similar to "the competition", i.e. 'sudo', 'pkexec', 'runas', 'doas', which generally include an action verb. - The connection between 'systemd-run' and 'run0' is more obvious. There has been no release yet with the old name, so we can rename without caring for backwards compatibility.
2024-03-19 11:14:55 +01:00
<para><command>run0</command> may be used to temporarily and interactively acquire elevated or different
run: when invoked as "uid0", expose some sudo-like behaviour This turns "systemd-run" into a multi-call binary. When invoked under the name "uid0", then it behaves a bit more like traditional "sudo". This mostly means defaults appropriuate for that, for example a PAM stack, interactivity and more. Fixes: #29199
2023-12-19 19:10:52 +01:00
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
man/run0: fix typo (missing "by")
2024-05-01 14:43:32 +08:00
invoked commands, as they are invoked from a fresh, isolated service forked off by the service manager.
</para></listitem>
run: when invoked as "uid0", expose some sudo-like behaviour This turns "systemd-run" into a multi-call binary. When invoked under the name "uid0", then it behaves a bit more like traditional "sudo". This mostly means defaults appropriuate for that, for example a PAM stack, interactivity and more. Fixes: #29199
2023-12-19 19:10:52 +01:00
<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>
Rename uid0 to run0 Naming is always a matter of preference, and the old name would certainly work, but I think the new one has the following advantages: - A verb is better than a noun. - The name more similar to "the competition", i.e. 'sudo', 'pkexec', 'runas', 'doas', which generally include an action verb. - The connection between 'systemd-run' and 'run0' is more obvious. There has been no release yet with the old name, so we can rename without caring for backwards compatibility.
2024-03-19 11:14:55 +01:00
<para>Any session invoked via <command>run0</command> will run through the
<literal>systemd-run0</literal> PAM stack.</para>
run: when invoked as "uid0", expose some sudo-like behaviour This turns "systemd-run" into a multi-call binary. When invoked under the name "uid0", then it behaves a bit more like traditional "sudo". This mostly means defaults appropriuate for that, for example a PAM stack, interactivity and more. Fixes: #29199
2023-12-19 19:10:52 +01:00
Rename uid0 to run0 Naming is always a matter of preference, and the old name would certainly work, but I think the new one has the following advantages: - A verb is better than a noun. - The name more similar to "the competition", i.e. 'sudo', 'pkexec', 'runas', 'doas', which generally include an action verb. - The connection between 'systemd-run' and 'run0' is more obvious. There has been no release yet with the old name, so we can rename without caring for backwards compatibility.
2024-03-19 11:14:55 +01:00
<para>Note that <command>run0</command> is implemented as an alternative multi-call invocation of
man: several more assorted fixes Continuation of 4ebbb5bfe88ac3d793c395472648660c33251546. Closes #35307.
2024-11-26 22:29:36 +09:00
<citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry>. That is,
<command>run0</command> is a symbolic link to <command>systemd-run</command> executable file, and it
behaves as <command>run0</command> if it is invoked through the symbolic link, otherwise behaves as
<command>systemd-run</command>.</para>
run: when invoked as "uid0", expose some sudo-like behaviour This turns "systemd-run" into a multi-call binary. When invoked under the name "uid0", then it behaves a bit more like traditional "sudo". This mostly means defaults appropriuate for that, for example a PAM stack, interactivity and more. Fixes: #29199
2023-12-19 19:10:52 +01:00
</refsect1>
<refsect1>
<title>Options</title>
<para>The following options are understood:</para>
<variablelist>
<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>
man: asorted fixes Closes #35307.
2024-11-23 22:07:56 +09:00
<listitem><para>Sets a property of the service unit that is created. This option takes an assignment
run: when invoked as "uid0", expose some sudo-like behaviour This turns "systemd-run" into a multi-call binary. When invoked under the name "uid0", then it behaves a bit more like traditional "sudo". This mostly means defaults appropriuate for that, for example a PAM stack, interactivity and more. Fixes: #29199
2023-12-19 19:10:52 +01:00
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
Rename uid0 to run0 Naming is always a matter of preference, and the old name would certainly work, but I think the new one has the following advantages: - A verb is better than a noun. - The name more similar to "the competition", i.e. 'sudo', 'pkexec', 'runas', 'doas', which generally include an action verb. - The connection between 'systemd-run' and 'run0' is more obvious. There has been no release yet with the old name, so we can rename without caring for backwards compatibility.
2024-03-19 11:14:55 +01:00
<command>run0</command> itself has been invoked in. This option may be combined with
run: when invoked as "uid0", expose some sudo-like behaviour This turns "systemd-run" into a multi-call binary. When invoked under the name "uid0", then it behaves a bit more like traditional "sudo". This mostly means defaults appropriuate for that, for example a PAM stack, interactivity and more. Fixes: #29199
2023-12-19 19:10:52 +01:00
<option>--slice=</option>, in which case the slice specified via <option>--slice=</option> is placed
Rename uid0 to run0 Naming is always a matter of preference, and the old name would certainly work, but I think the new one has the following advantages: - A verb is better than a noun. - The name more similar to "the competition", i.e. 'sudo', 'pkexec', 'runas', 'doas', which generally include an action verb. - The connection between 'systemd-run' and 'run0' is more obvious. There has been no release yet with the old name, so we can rename without caring for backwards compatibility.
2024-03-19 11:14:55 +01:00
within the slice the <command>run0</command> command is invoked in.</para>
run: when invoked as "uid0", expose some sudo-like behaviour This turns "systemd-run" into a multi-call binary. When invoked under the name "uid0", then it behaves a bit more like traditional "sudo". This mostly means defaults appropriuate for that, for example a PAM stack, interactivity and more. Fixes: #29199
2023-12-19 19:10:52 +01:00
Rename uid0 to run0 Naming is always a matter of preference, and the old name would certainly work, but I think the new one has the following advantages: - A verb is better than a noun. - The name more similar to "the competition", i.e. 'sudo', 'pkexec', 'runas', 'doas', which generally include an action verb. - The connection between 'systemd-run' and 'run0' is more obvious. There has been no release yet with the old name, so we can rename without caring for backwards compatibility.
2024-03-19 11:14:55 +01:00
<para>Example: consider <command>run0</command> being invoked in the slice
run: when invoked as "uid0", expose some sudo-like behaviour This turns "systemd-run" into a multi-call binary. When invoked under the name "uid0", then it behaves a bit more like traditional "sudo". This mostly means defaults appropriuate for that, for example a PAM stack, interactivity and more. Fixes: #29199
2023-12-19 19:10:52 +01:00
<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>
docs: document the new area functionality
2025-01-24 09:33:24 +01:00
<listitem><para>Switches to the specified user/group. If not specified defaults to
run0: Add --empower --empower gives full privileges to a non-root user. Currently this includes all capabilities but we leave the option open to add more privileges via this option in the future. Why is this useful? When running privileged development or debugging commands from your home directory (think bpftrace, strace and such), you want any files written by these tools to be owned by your current user, and not by the root user. run0 --empower will allow you to run all privileged operations (assuming the tools check for capabilities and not UIDs), while any files written by the tools will still be owned by the current user.
2025-10-30 12:28:19 +01:00
<literal>root</literal>, unless <option>--area=</option> or <option>--empower</option> are used (see
below), in which case this defaults to the invoking user.</para>
run: when invoked as "uid0", expose some sudo-like behaviour This turns "systemd-run" into a multi-call binary. When invoked under the name "uid0", then it behaves a bit more like traditional "sudo". This mostly means defaults appropriuate for that, for example a PAM stack, interactivity and more. Fixes: #29199
2023-12-19 19:10:52 +01:00
<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>
run0: introduce --via-shell for invoking target user's shell, and -i shortcut -i/--login has exact sudo semantics. But we only document the short option and advertise expressly specifying --via-shell --chdir='~' otherwise.
2025-04-09 00:55:27 +02:00
<varlistentry>
<term><option>--via-shell</option></term>
<listitem><para>Invokes the target user's login shell and runs the specified command (if any) via it.</para>
<xi:include href="version-info.xml" xpointer="v258"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-i</option></term>
<listitem><para>Shortcut for <option>--via-shell --chdir='~'</option>.</para>
<xi:include href="version-info.xml" xpointer="v258"/>
</listitem>
</varlistentry>
run: when invoked as "uid0", expose some sudo-like behaviour This turns "systemd-run" into a multi-call binary. When invoked under the name "uid0", then it behaves a bit more like traditional "sudo". This mostly means defaults appropriuate for that, for example a PAM stack, interactivity and more. Fixes: #29199
2023-12-19 19:10:52 +01:00
<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>
run/uid0: tint the terminal background color (and add new --background= switch) This adds a new --background= switch that allows specifiying a background color for the terminal while the tool runs. It also teaches the tool when invoked as uid0 to tint the terminal in a reddish hue when operating as root, and in a yellowish hue when operating as any other user. This should highlight nicely when the user is operating with elevated privileges, or changed privileges.
2023-12-20 12:09:27 +01:00
<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>
run0: add options to force allocation of PTY or of pipe use Fixes: #33033
2024-10-24 23:27:59 +02:00
<varlistentry>
<term><option>--pty</option></term>
run0: run agents during setup, until pty forwarder takes over When services start up they might query for passwords, or issue polkit requests. Hence it makese sense to run the password query agent and polkit agent from systemd-run. We already ran the polkit agent, this also ensures we run the password query agent. There's one tweak to the story though: running the agents and the pty forwarder concurrently is messy, since they both try to read from stdin (one potentially, the other definitely). Hence, let's time the agents properly: invoke them when we initialize, but stop them once the start job for the unit we are supposed to run is complete, and only then run the pty forwarder. With this in place, the following series of commands starts to work really nicely (which previously deadlocked): # homectl create foobar # run0 -u foobar What happens in the background in run0 is this: a new session is invoked for "foobar", which pulls in the user@.service instance for the user. That user@.service instance will need to unlock the homedir first. Since 8af1b296cb2cec8ddbb2cb47f4194269eb6cee2b this will happen via the askpw logic. With this commit here this prompt will now be shown by run0. Once the password is entered the directory is unlocked and the real session begins. Nice! This new behaviour is conditioned behind --pty-late (distinct from the existing --pty switches). For systemd-run we will never enable this mode by default, for compat with command lines that use ExecStartPre= (because we won't process the pty anymore during that command) For run0 however this changes the default to --pty-late (unless --no-ask-password is specified). This reflects the fact that run0 is more of an interctive tool and unlikely to be used in more complex service start-up situations with ExecStartPre= and suchlike. This also merges JobDoneContext into RunContext, since it doesn't really make sense to have two contexts around to communicate between outer stack frame and event handlers. Let's just have one, and pass it around to all handlers the same way. In particular as we should delay exit only until both the unit's job is complete *and* in case of --wait the unit is exited, one of the two should not suffice.
2025-02-28 23:32:08 +01:00
<term><option>--pty-late</option></term>
run0: add options to force allocation of PTY or of pipe use Fixes: #33033
2024-10-24 23:27:59 +02:00
<term><option>--pipe</option></term>
<listitem><para>Request allocation of a pseudo TTY for the <command>run0</command> session (in case
run0: run agents during setup, until pty forwarder takes over When services start up they might query for passwords, or issue polkit requests. Hence it makese sense to run the password query agent and polkit agent from systemd-run. We already ran the polkit agent, this also ensures we run the password query agent. There's one tweak to the story though: running the agents and the pty forwarder concurrently is messy, since they both try to read from stdin (one potentially, the other definitely). Hence, let's time the agents properly: invoke them when we initialize, but stop them once the start job for the unit we are supposed to run is complete, and only then run the pty forwarder. With this in place, the following series of commands starts to work really nicely (which previously deadlocked): # homectl create foobar # run0 -u foobar What happens in the background in run0 is this: a new session is invoked for "foobar", which pulls in the user@.service instance for the user. That user@.service instance will need to unlock the homedir first. Since 8af1b296cb2cec8ddbb2cb47f4194269eb6cee2b this will happen via the askpw logic. With this commit here this prompt will now be shown by run0. Once the password is entered the directory is unlocked and the real session begins. Nice! This new behaviour is conditioned behind --pty-late (distinct from the existing --pty switches). For systemd-run we will never enable this mode by default, for compat with command lines that use ExecStartPre= (because we won't process the pty anymore during that command) For run0 however this changes the default to --pty-late (unless --no-ask-password is specified). This reflects the fact that run0 is more of an interctive tool and unlikely to be used in more complex service start-up situations with ExecStartPre= and suchlike. This also merges JobDoneContext into RunContext, since it doesn't really make sense to have two contexts around to communicate between outer stack frame and event handlers. Let's just have one, and pass it around to all handlers the same way. In particular as we should delay exit only until both the unit's job is complete *and* in case of --wait the unit is exited, one of the two should not suffice.
2025-02-28 23:32:08 +01:00
of <option>--pty</option> or <option>--pty-late</option>), or request passing the caller's STDIO file
descriptors directly through (in case of <option>--pipe</option>). <option>--pty-late</option> is
very similar to <option>--pty</option> but begins the TTY processing only once unit startup is
complete, leaving input to any passwords/polkit agents until that time. If neither switch is
specified, or if both <option>--pipe</option> and one of
<option>--pty</option>/<option>--pty-late</option> are specified, the mode will be picked
automatically: if standard input, standard output, and standard error output are all connected to a
TTY then a pseudo TTY is allocated (in <option>--pty-late</option> mode unless
<option>--no-ask-password</option> is specified in which case <option>--pty</option> is selected),
otherwise the relevant file descriptors are passed through directly.</para>
<para id="v257"><option>--pty</option> and <option>--pipe</option> were added in v257.</para>
<para id="v258"><option>--pty-late</option> was added in v258.</para>
run0: add options to force allocation of PTY or of pipe use Fixes: #33033
2024-10-24 23:27:59 +02:00
</listitem>
</varlistentry>
run0: optionally show superhero emoji on each shell prompt This makes use of the infra introduced in 229d4a980607e9478cf1935793652ddd9a14618b to indicate visually on each prompt that we are in superuser mode temporarily. pick ad5de3222f userdbctl: add some basic client-side filtering
2024-10-24 11:36:48 +02:00
<varlistentry>
<term><option>--shell-prompt-prefix=<replaceable>STRING</replaceable></option></term>
<listitem><para>Set a shell prompt prefix string. This ultimately controls the
<varname>$SHELL_PROMPT_PREFIX</varname> environment variable for the invoked program, which is
man: grammar fixes for introductory adverbs/phrases
2024-12-25 17:07:17 +01:00
typically imported into the shell prompt. By default – if emojis are supported –, a superhero emoji is
run0: optionally show superhero emoji on each shell prompt This makes use of the infra introduced in 229d4a980607e9478cf1935793652ddd9a14618b to indicate visually on each prompt that we are in superuser mode temporarily. pick ad5de3222f userdbctl: add some basic client-side filtering
2024-10-24 11:36:48 +02:00
shown (🦸). This default may also be changed (or turned off) by passing the
<varname>$SYSTEMD_RUN_SHELL_PROMPT_PREFIX</varname> environment variable to <varname>run0</varname>,
see below. Set to an empty string to disable shell prompt prefixing.</para>
<xi:include href="version-info.xml" xpointer="v257"/>
</listitem>
</varlistentry>
run0: allow explicit control of service manager activation for run0 sessions This adds a new --lightweight=yes/no switch which allows controlling whether the invoked service will have the service manager around or not. Moreover, this changes that if the target user is root it will now support to the lightweight mode, i.e. run0 towards root will no longer pull in the service manager (a real tty login via getty still will though!). My thinking here is that quickly raising privileges via run0 probably shouldn't be considered a proper login but just something short lived, temporary for a single command or similar.
2025-01-14 11:50:52 +01:00
<varlistentry>
<term><option>--lightweight=<replaceable>BOOLEAN</replaceable></option></term>
<listitem><para>Controls whether to activate the per-user service manager for the target user. By
default if the target user is <literal>root</literal> or a system user the per-user service manager
is not activated as effect of the <command>run0</command> invocation, otherwise it is.</para>
docs: document the new area functionality
2025-01-24 09:33:24 +01:00
<para>This ultimately controls the <varname>$XDG_SESSION_CLASS</varname> environment variable
run0: allow explicit control of service manager activation for run0 sessions This adds a new --lightweight=yes/no switch which allows controlling whether the invoked service will have the service manager around or not. Moreover, this changes that if the target user is root it will now support to the lightweight mode, i.e. run0 towards root will no longer pull in the service manager (a real tty login via getty still will though!). My thinking here is that quickly raising privileges via run0 probably shouldn't be considered a proper login but just something short lived, temporary for a single command or similar.
2025-01-14 11:50:52 +01:00
<citerefentry><refentrytitle>pam_systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
respects.</para>
<xi:include href="version-info.xml" xpointer="v258"/>
</listitem>
</varlistentry>
docs: document the new area functionality
2025-01-24 09:33:24 +01:00
<varlistentry>
<term><option>--area=<replaceable>AREA</replaceable></option></term>
<listitem><para>Controls the "area" of the target account to log into. Areas are secondary home
directories within the primary home directory of the target user, i.e. logging into area
<literal>foobar</literal> of an account translates to <varname>$HOME</varname> being set to
<filename>~/Areas/foobar</filename> on login.</para>
<para>If this option is used, the default user to transition to changes from root to the calling
user's (but <option>--user=</option> takes precedence, see above). Or in other words, just specifying
an area without a user is a mechanism to create a new session of the calling user, just with a
different area.</para>
<para>This ultimately controls the <varname>$XDG_AREA</varname> environment variable
<citerefentry><refentrytitle>pam_systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
respects.</para>
<para>For details on the area concept see
<citerefentry><refentrytitle>pam_systemd_home</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
<xi:include href="version-info.xml" xpointer="v258"/>
</listitem>
</varlistentry>
run0: Add --empower --empower gives full privileges to a non-root user. Currently this includes all capabilities but we leave the option open to add more privileges via this option in the future. Why is this useful? When running privileged development or debugging commands from your home directory (think bpftrace, strace and such), you want any files written by these tools to be owned by your current user, and not by the root user. run0 --empower will allow you to run all privileged operations (assuming the tools check for capabilities and not UIDs), while any files written by the tools will still be owned by the current user.
2025-10-30 12:28:19 +01:00
<varlistentry>
<term><option>--empower</option></term>
<listitem><para>If specified, run0 will elevate the privileges of the selected user (using
<option>--user=</option>) or the current user if no user is explicitly selected. Currently this means
run0: Never ask --empower sessions for polkit auth A --empower session is effectively root without being UID 0, so it doesn't make sense to enforce polkit authentication in those. Let's add the empower group, add --empower sessions to that group and ship a polkit rule to skip authentication for all users in the empower group. (As a side-effect this will also allow users to add themselves to this group outside of 'run0 --empower' to mimick NOPASSWD from sudo)
2025-11-12 14:05:54 +01:00
we give the invoked process all available capabilities and add the the <literal>empower</literal>
group as a supplemental group (for which all polkit actions are allowed by default), but other
privileges may be granted in the future as well when using this option.</para>
run0: Add --empower --empower gives full privileges to a non-root user. Currently this includes all capabilities but we leave the option open to add more privileges via this option in the future. Why is this useful? When running privileged development or debugging commands from your home directory (think bpftrace, strace and such), you want any files written by these tools to be owned by your current user, and not by the root user. run0 --empower will allow you to run all privileged operations (assuming the tools check for capabilities and not UIDs), while any files written by the tools will still be owned by the current user.
2025-10-30 12:28:19 +01:00
run0: Add note about processes having privileges over --empower sessions
2025-11-21 11:44:30 +01:00
<para>Note that other (unprivileged) processes of the selected user will have privileges over the
invoked process. Consider not using this option in an environment where there might be malicious
processes running as the selected user.</para>
run0: Add --empower --empower gives full privileges to a non-root user. Currently this includes all capabilities but we leave the option open to add more privileges via this option in the future. Why is this useful? When running privileged development or debugging commands from your home directory (think bpftrace, strace and such), you want any files written by these tools to be owned by your current user, and not by the root user. run0 --empower will allow you to run all privileged operations (assuming the tools check for capabilities and not UIDs), while any files written by the tools will still be owned by the current user.
2025-10-30 12:28:19 +01:00
<xi:include href="version-info.xml" xpointer="v259"/></listitem>
</varlistentry>
run0: Make --same-root-dir available for run0 This enables running something like "mkosi box -- run0 --empower --same-root-dir -E PATH" to get an empowered session as the current user within the "mkosi box" environment.
2025-11-14 09:10:18 +01:00
<varlistentry>
<term><option>--same-root-dir</option></term>
<listitem><para>Execute the <command>run0</command> session in the same root directory that the
<command>run0</command> command is executed in.</para>
<xi:include href="version-info.xml" xpointer="v259"/></listitem>
</varlistentry>
man/run0: remove the --user example for --machine= run0's --user= option is different from other tools, and the whole point of run0 is to connect to the system manager. So the example is spurious.
2024-05-08 13:55:00 +08:00
<varlistentry>
<term><option>--machine=</option></term>
<listitem>
man: asorted fixes Closes #35307.
2024-11-23 22:07:56 +09:00
<para>Execute operation in a local container. Specify a container name to connect to.</para>
man/run0: remove the --user example for --machine= run0's --user= option is different from other tools, and the whole point of run0 is to connect to the system manager. So the example is spurious.
2024-05-08 13:55:00 +08:00
<xi:include href="version-info.xml" xpointer="v256"/>
</listitem>
</varlistentry>
man: use standard-options for --no-ask-password everywhere
2024-08-20 12:32:57 +02:00
<xi:include href="standard-options.xml" xpointer="no-ask-password" />
run: when invoked as "uid0", expose some sudo-like behaviour This turns "systemd-run" into a multi-call binary. When invoked under the name "uid0", then it behaves a bit more like traditional "sudo". This mostly means defaults appropriuate for that, for example a PAM stack, interactivity and more. Fixes: #29199
2023-12-19 19:10:52 +01:00
<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
run0: introduce --via-shell for invoking target user's shell, and -i shortcut -i/--login has exact sudo semantics. But we only document the short option and advertise expressly specifying --via-shell --chdir='~' otherwise.
2025-04-09 00:55:27 +02:00
invoke may be controlled through <option>--via-shell</option> - when specified the target user's shell
is used - or <option>--setenv=SHELL=…</option>. By default, the <emphasis>originating user's</emphasis> shell
is executed if operating locally, or <filename>/bin/sh</filename> when operating with <option>--machine=</option>.</para>
<para>Note that unlike <command>sudo</command>, <command>run0</command> always spawns shells with login shell
semantics, regardless of <option>-i</option>.</para>
run: when invoked as "uid0", expose some sudo-like behaviour This turns "systemd-run" into a multi-call binary. When invoked under the name "uid0", then it behaves a bit more like traditional "sudo". This mostly means defaults appropriuate for that, for example a PAM stack, interactivity and more. Fixes: #29199
2023-12-19 19:10:52 +01:00
</refsect1>
<refsect1>
<title>Exit status</title>
Rename uid0 to run0 Naming is always a matter of preference, and the old name would certainly work, but I think the new one has the following advantages: - A verb is better than a noun. - The name more similar to "the competition", i.e. 'sudo', 'pkexec', 'runas', 'doas', which generally include an action verb. - The connection between 'systemd-run' and 'run0' is more obvious. There has been no release yet with the old name, so we can rename without caring for backwards compatibility.
2024-03-19 11:14:55 +01:00
<para>On success, 0 is returned. If <command>run0</command> failed to start the session or the specified command fails, a
run: when invoked as "uid0", expose some sudo-like behaviour This turns "systemd-run" into a multi-call binary. When invoked under the name "uid0", then it behaves a bit more like traditional "sudo". This mostly means defaults appropriuate for that, for example a PAM stack, interactivity and more. Fixes: #29199
2023-12-19 19:10:52 +01:00
non-zero return value will be returned.</para>
</refsect1>
man/run0: Describe environment variables set (#32622) * man/run0: Describe environment variables set
2024-05-04 05:06:16 -06:00
<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>
man: fix typo Follow-up for 7df0297ac5aa784209d4c719c87fdd707a9f34cf.
2024-05-14 18:12:05 +09:00
<listitem><para>Copied from the <varname>$TERM</varname> of the caller. Can be overridden with
<option>--setenv=</option></para>
man/run0: Describe environment variables set (#32622) * man/run0: Describe environment variables set
2024-05-04 05:06:16 -06:00
<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>
run0: optionally show superhero emoji on each shell prompt This makes use of the infra introduced in 229d4a980607e9478cf1935793652ddd9a14618b to indicate visually on each prompt that we are in superuser mode temporarily. pick ad5de3222f userdbctl: add some basic client-side filtering
2024-10-24 11:36:48 +02:00
<varlistentry>
<term><varname>$SHELL_PROMPT_PREFIX</varname></term>
man: grammar fixes for introductory adverbs/phrases
2024-12-25 17:07:17 +01:00
<listitem><para>By default, set to the superhero emoji (if supported), but may be overridden with the
run0: optionally show superhero emoji on each shell prompt This makes use of the infra introduced in 229d4a980607e9478cf1935793652ddd9a14618b to indicate visually on each prompt that we are in superuser mode temporarily. pick ad5de3222f userdbctl: add some basic client-side filtering
2024-10-24 11:36:48 +02:00
<varname>$SYSTEMD_RUN_SHELL_PROMPT_PREFIX</varname> environment variable (see below), or the
<option>--shell-prompt-prefix=</option> switch (see above).</para>
<xi:include href="version-info.xml" xpointer="v257"/></listitem>
</varlistentry>
man/run0: Describe environment variables set (#32622) * man/run0: Describe environment variables set
2024-05-04 05:06:16 -06:00
</variablelist>
run0: optionally show superhero emoji on each shell prompt This makes use of the infra introduced in 229d4a980607e9478cf1935793652ddd9a14618b to indicate visually on each prompt that we are in superuser mode temporarily. pick ad5de3222f userdbctl: add some basic client-side filtering
2024-10-24 11:36:48 +02:00
<para>The following variables may be passed to <command>run0</command>:</para>
<variablelist>
<varlistentry>
<term><varname>$SYSTEMD_RUN_SHELL_PROMPT_PREFIX</varname></term>
<listitem><para>If set, overrides the default shell prompt prefix that <command>run0</command> sets
for the invoked shell (the superhero emoji). Set to an empty string to disable shell prompt
prefixing.</para>
<xi:include href="version-info.xml" xpointer="v257"/></listitem>
</varlistentry>
</variablelist>
man/run0: Describe environment variables set (#32622) * man/run0: Describe environment variables set
2024-05-04 05:06:16 -06:00
</refsect1>
run: when invoked as "uid0", expose some sudo-like behaviour This turns "systemd-run" into a multi-call binary. When invoked under the name "uid0", then it behaves a bit more like traditional "sudo". This mostly means defaults appropriuate for that, for example a PAM stack, interactivity and more. Fixes: #29199
2023-12-19 19:10:52 +01:00
<refsect1>
<title>See Also</title>
man: use <simplelist> for 'See also' sections This is just a slight markup improvement; there should be no difference in rendering.
2023-12-22 19:09:32 +01:00
<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>
run0: allow explicit control of service manager activation for run0 sessions This adds a new --lightweight=yes/no switch which allows controlling whether the invoked service will have the service manager around or not. Moreover, this changes that if the target user is root it will now support to the lightweight mode, i.e. run0 towards root will no longer pull in the service manager (a real tty login via getty still will though!). My thinking here is that quickly raising privileges via run0 probably shouldn't be considered a proper login but just something short lived, temporary for a single command or similar.
2025-01-14 11:50:52 +01:00
<member><citerefentry><refentrytitle>pam_systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
man: use <simplelist> for 'See also' sections This is just a slight markup improvement; there should be no difference in rendering.
2023-12-22 19:09:32 +01:00
</simplelist></para>
run: when invoked as "uid0", expose some sudo-like behaviour This turns "systemd-run" into a multi-call binary. When invoked under the name "uid0", then it behaves a bit more like traditional "sudo". This mostly means defaults appropriuate for that, for example a PAM stack, interactivity and more. Fixes: #29199
2023-12-19 19:10:52 +01:00
</refsect1>
</refentry>
Reference in New Issue Copy Permalink