systemd-run.1 6.45 KB
Newer Older
Michael Biebl's avatar
Michael Biebl committed
1
'\" t
Michael Biebl's avatar
Michael Biebl committed
2
.TH "SYSTEMD\-RUN" "1" "" "systemd 215" "systemd-run"
Michael Biebl's avatar
Michael Biebl committed
3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29
.\" -----------------------------------------------------------------
.\" * 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"
systemd-run \- Run programs in transient scope or service units
.SH "SYNOPSIS"
.HP \w'\fBsystemd\-run\fR\ 'u
\fBsystemd\-run\fR [OPTIONS...] \fICOMMAND\fR\ [ARGS...] 
.SH "DESCRIPTION"
.PP
\fBsystemd\-run\fR
30
may be used to create and start a transient
Michael Biebl's avatar
Michael Biebl committed
31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65
\&.service
or a
\&.scope
unit and run the specified
\fICOMMAND\fR
in it\&.
.PP
If a command is run as transient service unit, it will be started and managed by the service manager like any other service, and thus show up in the output of
\fBsystemctl list\-units\fR
like any other unit\&. It will run in a clean and detached execution environment\&.
\fBsystemd\-run\fR
will start the service asynchronously in the background and immediately return\&.
.PP
If a command is run as transient scope unit, it will be started directly by
\fBsystemd\-run\fR
and thus inherit the execution environment of the caller\&. It is however managed by the service manager similar to normal services, and will also show up in the output of
\fBsystemctl list\-units\fR\&. Execution in this case is synchronous, and execution will return only when the command finishes\&.
.SH "OPTIONS"
.PP
The following options are understood:
.PP
\fB\-\-scope\fR
.RS 4
Create a transient
\&.scope
unit instead of the default transient
\&.service
unit\&.
.RE
.PP
\fB\-\-unit=\fR
.RS 4
Use this unit name instead of an automatically generated one\&.
.RE
.PP
66 67 68 69 70 71 72 73
\fB\-\-property=\fR, \fB\-p\fR
.RS 4
Sets a unit property for the scope or service unit that is created\&. This takes an assignment in the same format as
\fBsystemctl\fR(1)\*(Aqs
\fBset\-property\fR
command\&.
.RE
.PP
Michael Biebl's avatar
Michael Biebl committed
74 75
\fB\-\-description=\fR
.RS 4
76
Provide a description for the service or scope unit\&. If not specified, the command itself will be used as a description\&. See
Michael Biebl's avatar
Michael Biebl committed
77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93
\fIDescription=\fR
in
\fBsystemd.unit\fR(5)\&.
.RE
.PP
\fB\-\-slice=\fR
.RS 4
Make the new
\&.service
or
\&.scope
unit part of the specified slice, instead of the
system\&.slice\&.
.RE
.PP
\fB\-\-remain\-after\-exit\fR
.RS 4
94
After the service or scope process has terminated, keep the service around until it is explicitly stopped\&. This is useful to collect runtime information about the service after it finished running\&. Also see
Michael Biebl's avatar
Michael Biebl committed
95 96 97 98 99 100 101
\fIRemainAfterExit=\fR
in
\fBsystemd.service\fR(5)\&.
.RE
.PP
\fB\-\-send\-sighup\fR
.RS 4
102
When terminating the scope or service unit, send a SIGHUP immediately after SIGTERM\&. This is useful to indicate to shells and shell\-like processes that the connection has been severed\&. Also see
Michael Biebl's avatar
Michael Biebl committed
103 104 105 106 107
\fISendSIGHUP=\fR
in
\fBsystemd.kill\fR(5)\&.
.RE
.PP
108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155
\fB\-\-service\-type=\fR
.RS 4
Sets the service type\&. Also see
\fIType=\fR
in
\fBsystemd.service\fR(5)\&. This option has no effect in conjunction with
\fB\-\-scope\fR\&. Defaults to
\fBsimple\fR\&.
.RE
.PP
\fB\-\-uid=\fR, \fB\-\-gid=\fR
.RS 4
Runs the service process under the UNIX user and group\&. Also see
\fIUser=\fR
and
\fIGroup=\fR
in
\fBsystemd.exec\fR(5)\&.
.RE
.PP
\fB\-\-nice=\fR
.RS 4
Runs the service process with the specified nice level\&. Also see
\fINice=\fR
in
\fBsystemd.exec\fR(5)\&.
.RE
.PP
\fB\-\-setenv=\fR
.RS 4
Runs the service process with the specified environment variables set\&. Also see
\fIEnvironment=\fR
in
\fBsystemd.exec\fR(5)\&.
.RE
.PP
\fB\-\-user\fR
.RS 4
Talk to the service manager of the calling user, rather than the service manager of the system\&.
.RE
.PP
\fB\-\-system\fR
.RS 4
Talk to the service manager of the system\&. This is the implied default\&.
.RE
.PP
\fB\-H\fR, \fB\-\-host=\fR
.RS 4
Michael Biebl's avatar
Michael Biebl committed
156 157 158 159
Execute the operation remotely\&. Specify a hostname, or a username and hostname separated by
"@", to connect to\&. The hostname may optionally be suffixed by a container name, separated by
":", which connects directly to a specific container on the specified host\&. This will use SSH to talk to the remote machine manager instance\&. Container names may be enumerated with
\fBmachinectl \-H \fR\fB\fIHOST\fR\fR\&.
160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176
.RE
.PP
\fB\-M\fR, \fB\-\-machine=\fR
.RS 4
Execute operation on a local container\&. Specify a container name to connect to\&.
.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
Michael Biebl's avatar
Michael Biebl committed
177 178 179 180
All command\-line arguments after the first non\-option argument become part of the commandline of the launched process\&. If a command is run as service unit, its first argument needs to be an absolute binary path\&.
.SH "EXIT STATUS"
.PP
On success, 0 is returned, a non\-zero failure code otherwise\&.
181
.SH "EXAMPLES"
Michael Biebl's avatar
Michael Biebl committed
182 183 184 185 186 187 188 189 190 191 192 193 194 195 196
.PP
The following command will log the environment variables provided by systemd to services:
.sp
.if n \{\
.RS 4
.\}
.nf
# systemd\-run env
Running as unit run\-19945\&.service\&.
# journalctl \-u run\-19945\&.service
Sep 08 07:37:21 bupkis systemd[1]: Starting /usr/bin/env\&.\&.\&.
Sep 08 07:37:21 bupkis systemd[1]: Started /usr/bin/env\&.
Sep 08 07:37:21 bupkis env[19948]: PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin
Sep 08 07:37:21 bupkis env[19948]: LANG=en_US\&.UTF\-8
Sep 08 07:37:21 bupkis env[19948]: BOOT_IMAGE=/vmlinuz\-3\&.11\&.0\-0\&.rc5\&.git6\&.2\&.fc20\&.x86_64
197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214
.fi
.if n \{\
.RE
.\}
.PP
The following command invokes the
\fBupdatedb\fR(8)
tool, but lowers the block IO weight for it to 10\&. See
\fBsystemd.resource-control\fR(5)
for more information on the
\fIBlockIOWeight=\fR
property\&.
.sp
.if n \{\
.RS 4
.\}
.nf
# systemd\-run \-p BlockIOWeight=10 updatedb
Michael Biebl's avatar
Michael Biebl committed
215 216 217 218 219 220 221 222 223 224 225
.fi
.if n \{\
.RE
.\}
.SH "SEE ALSO"
.PP
\fBsystemd\fR(1),
\fBsystemctl\fR(1),
\fBsystemd.unit\fR(5),
\fBsystemd.service\fR(5),
\fBsystemd.scope\fR(5),
226 227 228 229
\fBsystemd.slice\fR(5),
\fBsystemd.exec\fR(5),
\fBsystemd.resource-control\fR(5),
\fBmachinectl\fR(1)