diff options
Diffstat (limited to 'upstream/opensuse-leap-15-6/man1/systemd-run.1')
| -rw-r--r-- | upstream/opensuse-leap-15-6/man1/systemd-run.1 | 705 |
1 files changed, 705 insertions, 0 deletions
diff --git a/upstream/opensuse-leap-15-6/man1/systemd-run.1 b/upstream/opensuse-leap-15-6/man1/systemd-run.1 new file mode 100644 index 00000000..4127c887 --- /dev/null +++ b/upstream/opensuse-leap-15-6/man1/systemd-run.1 @@ -0,0 +1,705 @@ +'\" t +.TH "SYSTEMD\-RUN" "1" "" "systemd 254" "systemd-run" +.\" ----------------------------------------------------------------- +.\" * 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 units, service units, or path\-, socket\-, or timer\-triggered service units +.SH "SYNOPSIS" +.HP \w'\fBsystemd\-run\fR\ 'u +\fBsystemd\-run\fR [OPTIONS...] \fICOMMAND\fR\ [ARGS...] +.HP \w'\fBsystemd\-run\fR\ 'u +\fBsystemd\-run\fR [OPTIONS...] [PATH\ OPTIONS...] {\fICOMMAND\fR} [ARGS...] +.HP \w'\fBsystemd\-run\fR\ 'u +\fBsystemd\-run\fR [OPTIONS...] [SOCKET\ OPTIONS...] {\fICOMMAND\fR} [ARGS...] +.HP \w'\fBsystemd\-run\fR\ 'u +\fBsystemd\-run\fR [OPTIONS...] [TIMER\ OPTIONS...] {\fICOMMAND\fR} [ARGS...] +.SH "DESCRIPTION" +.PP +\fBsystemd\-run\fR +may be used to create and start a transient +\&.service +or +\&.scope +unit and run the specified +\fICOMMAND\fR +in it\&. It may also be used to create and start a transient +\&.path, +\&.socket, or +\&.timer +unit, that activates a +\&.service +unit when elapsing\&. +.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 shows up in the output of +\fBsystemctl list\-units\fR +like any other unit\&. It will run in a clean and detached execution environment, with the service manager as its parent process\&. In this mode, +\fBsystemd\-run\fR +will start the service asynchronously in the background and return after the command has begun execution (unless +\fB\-\-no\-block\fR +or +\fB\-\-wait\fR +are specified, see below)\&. +.PP +If a command is run as transient scope unit, it will be executed by +\fBsystemd\-run\fR +itself as parent process and will thus inherit the execution environment of the caller\&. However, the processes of the command are managed by the service manager similarly to normal services, and will show up in the output of +\fBsystemctl list\-units\fR\&. Execution in this case is synchronous, and will return only when the command finishes\&. This mode is enabled via the +\fB\-\-scope\fR +switch (see below)\&. +.PP +If a command is run with path, socket, or timer options such as +\fB\-\-on\-calendar=\fR +(see below), a transient path, socket, or timer unit is created alongside the service unit for the specified command\&. Only the transient path, socket, or timer unit is started immediately, the transient service unit will be triggered by the path, socket, or timer unit\&. If the +\fB\-\-unit=\fR +option is specified, the +\fICOMMAND\fR +may be omitted\&. In this case, +\fBsystemd\-run\fR +creates only a +\&.path, +\&.socket, or +\&.timer +unit that triggers the specified unit\&. +.PP +By default, services created with +\fBsystemd\-run\fR +default to the +\fBsimple\fR +type, see the description of +\fIType=\fR +in +\fBsystemd.service\fR(5) +for details\&. Note that when this type is used, the service manager (and thus the +\fBsystemd\-run\fR +command) considers service start\-up successful as soon as the +\fBfork()\fR +for the main service process succeeded, i\&.e\&. before the +\fBexecve()\fR +is invoked, and thus even if the specified command cannot be started\&. Consider using the +\fBexec\fR +service type (i\&.e\&. +\fB\-\-property=Type=exec\fR) to ensure that +\fBsystemd\-run\fR +returns successfully only if the specified command line has been successfully started\&. +.PP +After +\fBsystemd\-run\fR +passes the command to the service manager, the manager performs variable expansion\&. This means that dollar characters ("$") which should not be expanded need to be escaped as +"$$"\&. Expansion can also be disabled using +\fI\-\-expand\-environment=no\fR\&. +.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\&. +.RE +.PP +\fB\-\-scope\fR +.RS 4 +Create a transient +\&.scope +unit instead of the default transient +\&.service +unit (see above)\&. +.RE +.PP +\fB\-\-unit=\fR, \fB\-u\fR +.RS 4 +Use this unit name instead of an automatically generated one\&. +.RE +.PP +\fB\-\-property=\fR, \fB\-p\fR +.RS 4 +Sets a property on the scope or service unit that is created\&. This option takes an assignment in the same format as +\fBsystemctl\fR(1)\*(Aqs +\fBset\-property\fR +command\&. +.RE +.PP +\fB\-\-description=\fR +.RS 4 +Provide a description for the service, scope, path, socket, or timer unit\&. If not specified, the command itself will be used as a description\&. See +\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 +system\&.slice +(when running in +\fB\-\-system\fR +mode) or the root slice (when running in +\fB\-\-user\fR +mode)\&. +.RE +.PP +\fB\-\-slice\-inherit\fR +.RS 4 +Make the new +\&.service +or +\&.scope +unit part of the inherited slice\&. This option can be combined with +\fB\-\-slice=\fR\&. +.sp +An inherited slice is located within +\fBsystemd\-run\fR +slice\&. Example: if +\fBsystemd\-run\fR +slice is +foo\&.slice, and the +\fB\-\-slice=\fR +argument is +bar, the unit will be placed under the +foo\-bar\&.slice\&. +.RE +.PP +\fB\-\-expand\-environment=\fR\fB\fIBOOL\fR\fR +.RS 4 +Expand environment variables in command arguments\&. If enabled, environment variables specified as +"${\fIVARIABLE\fR}" +will be expanded in the same way as in commands specified via +\fIExecStart=\fR +in units\&. With +\fI\-\-scope\fR, this expansion is performed by +\fBsystemd\-run\fR +itself, and in other cases by the service manager that spawns the command\&. Note that this is similar to, but not the same as variable expansion in +\fBbash\fR(1) +and other shells\&. +.sp +The default is to enable this option in all cases, except for +\fI\-\-scope\fR +where it is disabled by default, for backward compatibility reasons\&. Note that this will be changed in a future release, where it will be switched to enabled by default as well\&. +.sp +See +\fBsystemd.service\fR(5) +for a description of variable expansion\&. Disabling variable expansion is useful if the specified command includes or may include a +"$" +sign\&. +.RE +.PP +\fB\-r\fR, \fB\-\-remain\-after\-exit\fR +.RS 4 +After the service 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 +\fIRemainAfterExit=\fR +in +\fBsystemd.service\fR(5)\&. +.RE +.PP +\fB\-\-send\-sighup\fR +.RS 4 +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 +\fISendSIGHUP=\fR +in +\fBsystemd.kill\fR(5)\&. +.RE +.PP +\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 specified 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\-\-working\-directory=\fR +.RS 4 +Runs the service process with the specified working directory\&. Also see +\fIWorkingDirectory=\fR +in +\fBsystemd.exec\fR(5)\&. +.RE +.PP +\fB\-\-same\-dir\fR, \fB\-d\fR +.RS 4 +Similar to +\fB\-\-working\-directory=\fR, but uses the current working directory of the caller for the service to execute\&. +.RE +.PP +\fB\-E \fR\fB\fINAME\fR\fR\fB[=\fR\fB\fIVALUE\fR\fR\fB]\fR, \fB\-\-setenv=\fR\fB\fINAME\fR\fR\fB[=\fR\fB\fIVALUE\fR\fR\fB]\fR +.RS 4 +Runs the service process 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 program environment will be used\&. +.sp +Also see +\fIEnvironment=\fR +in +\fBsystemd.exec\fR(5)\&. +.RE +.PP +\fB\-\-pty\fR, \fB\-t\fR +.RS 4 +When invoking the command, the transient service connects its standard input, output and error to the terminal +\fBsystemd\-run\fR +is invoked on, via a pseudo TTY device\&. This allows running programs that expect interactive user input/output as services, such as interactive command shells\&. +.sp +Note that +\fBmachinectl\fR(1)\*(Aqs +\fBshell\fR +command is usually a better alternative for requesting a new, interactive login session on the local host or a local container\&. +.sp +See below for details on how this switch combines with +\fB\-\-pipe\fR\&. +.RE +.PP +\fB\-\-pipe\fR, \fB\-P\fR +.RS 4 +If specified, standard input, output, and error of the transient service are inherited from the +\fBsystemd\-run\fR +command itself\&. This allows +\fBsystemd\-run\fR +to be used within shell pipelines\&. Note that this mode is not suitable for interactive command shells and similar, as the service process will not become a TTY controller when invoked on a terminal\&. Use +\fB\-\-pty\fR +instead in that case\&. +.sp +When both +\fB\-\-pipe\fR +and +\fB\-\-pty\fR +are used in combination the more appropriate option is automatically determined and used\&. Specifically, when invoked with standard input, output and error connected to a TTY +\fB\-\-pty\fR +is used, and otherwise +\fB\-\-pipe\fR\&. +.sp +When this option is used the original file descriptors +\fBsystemd\-run\fR +receives are passed to the service processes as\-is\&. If the service runs with different privileges than +\fBsystemd\-run\fR, this means the service might not be able to re\-open the passed file descriptors, due to normal file descriptor access restrictions\&. If the invoked process is a shell script that uses the +\fBecho "hello" >/dev/stderr\fR +construct for writing messages to stderr, this might cause problems, as this only works if stderr can be re\-opened\&. To mitigate this use the construct +\fBecho "hello" >&2\fR +instead, which is mostly equivalent and avoids this pitfall\&. +.RE +.PP +\fB\-\-shell\fR, \fB\-S\fR +.RS 4 +A shortcut for +"\-\-pty \-\-same\-dir \-\-wait \-\-collect \-\-service\-type=exec $SHELL", i\&.e\&. requests an interactive shell in the current working directory, running in service context, accessible with a single switch\&. +.RE +.PP +\fB\-\-quiet\fR, \fB\-q\fR +.RS 4 +Suppresses additional informational output while running\&. This is particularly useful in combination with +\fB\-\-pty\fR +when it will suppress the initial message explaining how to terminate the TTY connection\&. +.RE +.PP +\fB\-\-on\-active=\fR, \fB\-\-on\-boot=\fR, \fB\-\-on\-startup=\fR, \fB\-\-on\-unit\-active=\fR, \fB\-\-on\-unit\-inactive=\fR +.RS 4 +Defines a monotonic timer relative to different starting points for starting the specified command\&. See +\fIOnActiveSec=\fR, +\fIOnBootSec=\fR, +\fIOnStartupSec=\fR, +\fIOnUnitActiveSec=\fR +and +\fIOnUnitInactiveSec=\fR +in +\fBsystemd.timer\fR(5) +for details\&. These options are shortcuts for +\fB\-\-timer\-property=\fR +with the relevant properties\&. These options may not be combined with +\fB\-\-scope\fR +or +\fB\-\-pty\fR\&. +.RE +.PP +\fB\-\-on\-calendar=\fR +.RS 4 +Defines a calendar timer for starting the specified command\&. See +\fIOnCalendar=\fR +in +\fBsystemd.timer\fR(5)\&. This option is a shortcut for +\fB\-\-timer\-property=OnCalendar=\fR\&. This option may not be combined with +\fB\-\-scope\fR +or +\fB\-\-pty\fR\&. +.RE +.PP +\fB\-\-on\-clock\-change\fR, \fB\-\-on\-timezone\-change\fR +.RS 4 +Defines a trigger based on system clock jumps or timezone changes for starting the specified command\&. See +\fIOnClockChange=\fR +and +\fIOnTimezoneChange=\fR +in +\fBsystemd.timer\fR(5)\&. These options are shortcuts for +\fB\-\-timer\-property=OnClockChange=yes\fR +and +\fB\-\-timer\-property=OnTimezoneChange=yes\fR\&. These options may not be combined with +\fB\-\-scope\fR +or +\fB\-\-pty\fR\&. +.RE +.PP +\fB\-\-path\-property=\fR, \fB\-\-socket\-property=\fR, \fB\-\-timer\-property=\fR +.RS 4 +Sets a property on the path, socket, or timer unit that is created\&. This option is similar to +\fB\-\-property=\fR, but applies to the transient path, socket, or timer unit rather than the transient service unit created\&. This option takes an assignment in the same format as +\fBsystemctl\fR(1)\*(Aqs +\fBset\-property\fR +command\&. These options may not be combined with +\fB\-\-scope\fR +or +\fB\-\-pty\fR\&. +.RE +.PP +\fB\-\-no\-block\fR +.RS 4 +Do not synchronously wait for the unit start operation to finish\&. If this option is not specified, the start request for the transient unit will be verified, enqueued and +\fBsystemd\-run\fR +will wait until the unit\*(Aqs start\-up is completed\&. By passing this argument, it is only verified and enqueued\&. This option may not be combined with +\fB\-\-wait\fR\&. +.RE +.PP +\fB\-\-wait\fR +.RS 4 +Synchronously wait for the transient service to terminate\&. If this option is specified, the start request for the transient unit is verified, enqueued, and waited for\&. Subsequently the invoked unit is monitored, and it is waited until it is deactivated again (most likely because the specified command completed)\&. On exit, terse information about the unit\*(Aqs runtime is shown, including total runtime (as well as CPU usage, if +\fB\-\-property=CPUAccounting=1\fR +was set) and the exit code and status of the main process\&. This output may be suppressed with +\fB\-\-quiet\fR\&. This option may not be combined with +\fB\-\-no\-block\fR, +\fB\-\-scope\fR +or the various path, socket, or timer options\&. +.RE +.PP +\fB\-G\fR, \fB\-\-collect\fR +.RS 4 +Unload the transient unit after it completed, even if it failed\&. Normally, without this option, all units that ran and failed are kept in memory until the user explicitly resets their failure state with +\fBsystemctl reset\-failed\fR +or an equivalent command\&. On the other hand, units that ran successfully are unloaded immediately\&. If this option is turned on the "garbage collection" of units is more aggressive, and unloads units regardless if they exited successfully or failed\&. This option is a shortcut for +\fB\-\-property=CollectMode=inactive\-or\-failed\fR, see the explanation for +\fICollectMode=\fR +in +\fBsystemd.unit\fR(5) +for further information\&. +.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 +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 port ssh is listening on, separated by +":", and then 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\&. Put IPv6 addresses in brackets\&. +.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 (which is useful to connect to a specific user\*(Aqs user bus: +"\-\-user \-\-machine=lennart@\&.host")\&. 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\&. +.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\&. +.SH "EXIT STATUS" +.PP +On success, 0 is returned\&. If +\fBsystemd\-run\fR +failed to start the service, a non\-zero return value will be returned\&. If +\fBsystemd\-run\fR +waits for the service to terminate, the return value will be propagated from the service\&. 0 will be returned on success, including all the cases where systemd considers a service to have exited cleanly, see the discussion of +\fISuccessExitStatus=\fR +in +\fBsystemd.service\fR(5)\&. +.SH "EXAMPLES" +.PP +\fBExample\ \&1.\ \&Logging environment variables provided by systemd to services\fR +.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 +.fi +.if n \{\ +.RE +.\} +.PP +\fBExample\ \&2.\ \&Limiting resources available to a command\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +# systemd\-run \-p IOWeight=10 updatedb +.fi +.if n \{\ +.RE +.\} +.PP +This command invokes the +\fBupdatedb\fR(8) +tool, but lowers the block I/O weight for it to 10\&. See +\fBsystemd.resource-control\fR(5) +for more information on the +\fIIOWeight=\fR +property\&. +.PP +\fBExample\ \&3.\ \&Running commands at a specified time\fR +.PP +The following command will touch a file after 30 seconds\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +# date; systemd\-run \-\-on\-active=30 \-\-timer\-property=AccuracySec=100ms /bin/touch /tmp/foo +Mon Dec 8 20:44:24 KST 2014 +Running as unit: run\-71\&.timer +Will run service as unit: run\-71\&.service +# journalctl \-b \-u run\-71\&.timer +\-\- Journal begins at Fri 2014\-12\-05 19:09:21 KST, ends at Mon 2014\-12\-08 20:44:54 KST\&. \-\- +Dec 08 20:44:38 container systemd[1]: Starting /bin/touch /tmp/foo\&. +Dec 08 20:44:38 container systemd[1]: Started /bin/touch /tmp/foo\&. +# journalctl \-b \-u run\-71\&.service +\-\- Journal begins at Fri 2014\-12\-05 19:09:21 KST, ends at Mon 2014\-12\-08 20:44:54 KST\&. \-\- +Dec 08 20:44:48 container systemd[1]: Starting /bin/touch /tmp/foo\&.\&.\&. +Dec 08 20:44:48 container systemd[1]: Started /bin/touch /tmp/foo\&. +.fi +.if n \{\ +.RE +.\} +.PP +\fBExample\ \&4.\ \&Allowing access to the tty\fR +.PP +The following command invokes +\fBbash\fR(1) +as a service passing its standard input, output and error to the calling TTY\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +# systemd\-run \-t \-\-send\-sighup bash +.fi +.if n \{\ +.RE +.\} +.PP +\fBExample\ \&5.\ \&Start screen as a user service\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ systemd\-run \-\-scope \-\-user screen +Running scope as unit run\-r14b0047ab6df45bfb45e7786cc839e76\&.scope\&. + +$ screen \-ls +There is a screen on: + 492\&.\&.laptop (Detached) +1 Socket in /var/run/screen/S\-fatima\&. +.fi +.if n \{\ +.RE +.\} +.PP +This starts the +\fBscreen\fR +process as a child of the +\fBsystemd \-\-user\fR +process that was started by +user@\&.service, in a scope unit\&. A +\fBsystemd.scope\fR(5) +unit is used instead of a +\fBsystemd.service\fR(5) +unit, because +\fBscreen\fR +will exit when detaching from the terminal, and a service unit would be terminated\&. Running +\fBscreen\fR +as a user unit has the advantage that it is not part of the session scope\&. If +\fIKillUserProcesses=yes\fR +is configured in +\fBlogind.conf\fR(5), the default, the session scope will be terminated when the user logs out of that session\&. +.PP +The +user@\&.service +is started automatically when the user first logs in, and stays around as long as at least one login session is open\&. After the user logs out of the last session, +user@\&.service +and all services underneath it are terminated\&. This behavior is the default, when "lingering" is not enabled for that user\&. Enabling lingering means that +user@\&.service +is started automatically during boot, even if the user is not logged in, and that the service is not terminated when the user logs out\&. +.PP +Enabling lingering allows the user to run processes without being logged in, for example to allow +\fBscreen\fR +to persist after the user logs out, even if the session scope is terminated\&. In the default configuration, users can enable lingering for themselves: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ loginctl enable\-linger +.fi +.if n \{\ +.RE +.\} +.PP +\fBExample\ \&6.\ \&Variable expansion by the manager\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ systemd\-run \-t echo "<${INVOCATION_ID}>" \*(Aq<${INVOCATION_ID}>\*(Aq + <> <5d0149bfa2c34b79bccb13074001eb20> + +.fi +.if n \{\ +.RE +.\} +.PP +The first argument is expanded by the shell (double quotes), but the second one is not expanded by the shell (single quotes)\&. +\fBecho\fR +is called with ["/usr/bin/echo", +"[]", +"[${INVOCATION_ID}]"] as the argument array, and then +\fBsystemd\fR +generates +\fI${INVOCATION_ID}\fR +and substitutes it in the command\-line\&. This substitution could not be done on the client side, because the target ID that will be set for the service isn\*(Aqt known before the call is made\&. +.PP +\fBExample\ \&7.\ \&Variable expansion and output redirection using a shell\fR +.PP +Variable expansion by +\fBsystemd\fR +can be disabled with +\fI\-\-expand\-environment=no\fR\&. +.PP +Disabling variable expansion can be useful if the command to execute contains dollar characters and escaping them would be inconvenient\&. For example, when a shell is used: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ systemd\-run \-\-expand\-environment=no \-t bash \e + \-c \*(Aqecho $SHELL $$ >/dev/stdout\*(Aq +/bin/bash 12345 + +.fi +.if n \{\ +.RE +.\} +.PP +The last argument is passed verbatim to the +\fBbash\fR +shell which is started by the service unit\&. The shell expands +"$SHELL" +to the path of the shell, and +"$$" +to its process number, and then those strings are passed to the +\fBecho\fR +built\-in and printed to standard output (which in this case is connected to the calling terminal)\&. +.PP +\fBExample\ \&8.\ \&Return value\fR +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ systemd\-run \-\-user \-\-wait true +$ systemd\-run \-\-user \-\-wait \-p SuccessExitStatus=11 bash \-c \*(Aqexit 11\*(Aq +$ systemd\-run \-\-user \-\-wait \-p SuccessExitStatus=SIGUSR1 \-\-expand\-environment=no \e + bash \-c \*(Aqkill \-SIGUSR1 $$\*(Aq +.fi +.if n \{\ +.RE +.\} +.PP +Those three invocations will succeed, i\&.e\&. terminate with an exit code of 0\&. +.SH "SEE ALSO" +.PP +\fBsystemd\fR(1), +\fBsystemctl\fR(1), +\fBsystemd.unit\fR(5), +\fBsystemd.service\fR(5), +\fBsystemd.scope\fR(5), +\fBsystemd.slice\fR(5), +\fBsystemd.exec\fR(5), +\fBsystemd.resource-control\fR(5), +\fBsystemd.timer\fR(5), +\fBsystemd-mount\fR(1), +\fBmachinectl\fR(1) |