path: root/upstream/fedora-rawhide/man1/run0.1

'\" t
.TH "RUN0" "1" "" "systemd 256~rc3" "run0"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
run0 \- Elevate privileges
.SH "SYNOPSIS"
.HP \w'\fBrun0\fR\ 'u
\fBrun0\fR [OPTIONS...] [COMMAND...]
.SH "DESCRIPTION"
.PP
\fBrun0\fR
may be used to temporarily and interactively acquire elevated or different privileges\&. It serves a similar purpose as
\fBsudo\fR(8), but operates differently in a couple of key areas:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
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\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Authentication takes place via
\m[blue]\fBpolkit\fR\m[]\&\s-2\u[1]\d\s+2, thus isolating the authentication prompt from the terminal (if possible)\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
An independent pseudo\-tty is allocated for the invoked command, detaching its lifecycle and isolating it for security\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
No SetUID/SetGID file access bit functionality is used for the implementation\&.
.RE
.PP
Altogether this should provide a safer and more robust alternative to the
\fBsudo\fR
mechanism, in particular in OS environments where SetUID/SetGID support is not available (for example by setting the
\fINoNewPrivileges=\fR
variable in
\fBsystemd-system.conf\fR(5))\&.
.PP
Any session invoked via
\fBrun0\fR
will run through the
"systemd\-run0"
PAM stack\&.
.PP
Note that
\fBrun0\fR
is implemented as an alternative multi\-call invocation of
\fBsystemd-run\fR(1)\&.
.SH "OPTIONS"
.PP
The following options are understood:
.PP
\fB\-\-no\-ask\-password\fR
.RS 4
Do not query the user for authentication for privileged operations\&.
.sp
Added in version 256\&.
.RE
.PP
\fB\-\-unit=\fR
.RS 4
Use this unit name instead of an automatically generated one\&.
.sp
Added in version 256\&.
.RE
.PP
\fB\-\-property=\fR
.RS 4
Sets a property on the service unit that is created\&. This option takes an assignment in the same format as
\fBsystemctl\fR(1)\*(Aqs
\fBset\-property\fR
command\&.
.sp
Added in version 256\&.
.RE
.PP
\fB\-\-description=\fR
.RS 4
Provide a description for the service unit that is invoked\&. If not specified, the command itself will be used as a description\&. See
\fIDescription=\fR
in
\fBsystemd.unit\fR(5)\&.
.sp
Added in version 256\&.
.RE
.PP
\fB\-\-slice=\fR
.RS 4
Make the new
\&.service
unit part of the specified slice, instead of
user\&.slice\&.
.sp
Added in version 256\&.
.RE
.PP
\fB\-\-slice\-inherit\fR
.RS 4
Make the new
\&.service
unit part of the slice the
\fBrun0\fR
itself has been invoked in\&. This option may be combined with
\fB\-\-slice=\fR, in which case the slice specified via
\fB\-\-slice=\fR
is placed within the slice the
\fBrun0\fR
command is invoked in\&.
.sp
Example: consider
\fBrun0\fR
being invoked in the slice
foo\&.slice, and the
\fB\-\-slice=\fR
argument is
bar\&. The unit will then be placed under
foo\-bar\&.slice\&.
.sp
Added in version 256\&.
.RE
.PP
\fB\-\-user=\fR, \fB\-u\fR, \fB\-\-group=\fR, \fB\-g\fR
.RS 4
Switches to the specified user/group instead of root\&.
.sp
Added in version 256\&.
.RE
.PP
\fB\-\-nice=\fR
.RS 4
Runs the invoked session with the specified nice level\&.
.sp
Added in version 256\&.
.RE
.PP
\fB\-\-chdir=\fR, \fB\-D\fR
.RS 4
Runs the invoked session with the specified working directory\&. If not specified defaults to the client\*(Aqs current working directory if switching to the root user, or the target user\*(Aqs home directory otherwise\&.
.sp
Added in version 256\&.
.RE
.PP
\fB\-\-setenv=\fR\fB\fINAME\fR\fR\fB[=\fR\fB\fIVALUE\fR\fR\fB]\fR
.RS 4
Runs the invoked session with the specified environment variable set\&. This parameter may be used more than once to set multiple variables\&. When
"="
and
\fIVALUE\fR
are omitted, the value of the variable with the same name in the invoking environment will be used\&.
.sp
Added in version 256\&.
.RE
.PP
\fB\-\-background=\fR\fB\fICOLOR\fR\fR
.RS 4
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
"40",
"41", \&...,
"47",
"48;2;\&...",
"48;5;\&..."\&. See
\m[blue]\fBANSI Escape Code (Wikipedia)\fR\m[]\&\s-2\u[2]\d\s+2
for details\&. Set to an empty string to disable\&.
.sp
Example:
"\-\-background=44"
for a blue background\&.
.sp
Added in version 256\&.
.RE
.PP
\fB\-M\fR, \fB\-\-machine=\fR
.RS 4
Execute operation on a local container\&. Specify a container name to connect to, optionally prefixed by a user name to connect as and a separating
"@"
character\&. If the special string
"\&.host"
is used in place of the container name, a connection to the local system is made\&. If the
"@"
syntax is not used, the connection is made as root user\&. If the
"@"
syntax is used either the left hand side or the right hand side may be omitted (but not both) in which case the local user name and
"\&.host"
are implied\&.
.sp
Added in version 256\&.
.RE
.PP
\fB\-h\fR, \fB\-\-help\fR
.RS 4
Print a short help text and exit\&.
.RE
.PP
\fB\-\-version\fR
.RS 4
Print a short version string and exit\&.
.RE
.PP
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
\fB\-\-setenv=SHELL=\&...\fR
and currently defaults to the
\fIoriginating user\*(Aqs\fR
shell (i\&.e\&. not the target user\*(Aqs!) if operating locally, or
/bin/sh
when operating with
\fB\-\-machine=\fR\&.
.SH "EXIT STATUS"
.PP
On success, 0 is returned\&. If
\fBrun0\fR
failed to start the session or the specified command fails, a non\-zero return value will be returned\&.
.SH "ENVIRONMENT VARIABLES"
.PP
As with
\fBsystemd\-run\fR, the session will inherit the system environment from the service manager\&. In addition, the following environment variables will be set:
.PP
\fI$TERM\fR
.RS 4
Copied from the
\fI$TERM\fR
of the caller\&. Can be overridden with
\fB\-\-setenv=\fR
.sp
Added in version 256\&.
.RE
.PP
\fI$SUDO_USER\fR
.RS 4
Set to the username of the originating user\&.
.sp
Added in version 256\&.
.RE
.PP
\fI$SUDO_UID\fR
.RS 4
Set to the numeric UNIX user id of the originating user\&.
.sp
Added in version 256\&.
.RE
.PP
\fI$SUDO_GID\fR
.RS 4
Set to the primary numeric UNIX group id of the originating session\&.
.sp
Added in version 256\&.
.RE
.SH "SEE ALSO"
.PP
\fBsystemd\fR(1), \fBsystemd-run\fR(1), \fBsudo\fR(8), \fBmachinectl\fR(1)
.SH "NOTES"
.IP " 1." 4
polkit
.RS 4
\%https://www.freedesktop.org/wiki/Software/polkit
.RE
.IP " 2." 4
ANSI Escape Code (Wikipedia)
.RS 4
\%https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_(Select_Graphic_Rendition)_parameters
.RE