From 2cb7e0aaedad73b076ea18c6900b0e86c5760d79 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sat, 27 Apr 2024 15:00:47 +0200 Subject: Adding upstream version 247.3. Signed-off-by: Daniel Baumann --- man/systemd-run.xml | 556 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 556 insertions(+) create mode 100644 man/systemd-run.xml (limited to 'man/systemd-run.xml') diff --git a/man/systemd-run.xml b/man/systemd-run.xml new file mode 100644 index 0000000..fc8716e --- /dev/null +++ b/man/systemd-run.xml @@ -0,0 +1,556 @@ + + + + + + + + systemd-run + systemd + + + + systemd-run + 1 + + + + systemd-run + Run programs in transient scope units, service units, or path-, socket-, or timer-triggered service units + + + + + systemd-run + OPTIONS + COMMAND + ARGS + + + + systemd-run + OPTIONS + PATH OPTIONS + COMMAND + ARGS + + + systemd-run + OPTIONS + SOCKET OPTIONS + COMMAND + ARGS + + + systemd-run + OPTIONS + TIMER OPTIONS + COMMAND + ARGS + + + + + Description + + systemd-run may be used to create and start a transient .service or + .scope unit and run the specified COMMAND 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. + + 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 systemctl list-units 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, systemd-run will start the service asynchronously in the background and return after the + command has begun execution (unless or are specified, see + below). + + If a command is run as transient scope unit, it will be executed by systemd-run 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 similar to normal services, and will show up in the output of systemctl + list-units. Execution in this case is synchronous, and will return only when the command finishes. This + mode is enabled via the switch (see below). + + If a command is run with path, socket, or timer options such as (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 option is specified, the + COMMAND may be omitted. In this case, systemd-run creates only a + .path, .socket, or .timer unit that triggers the + specified unit. + + By default, services created with systemd-run default to the type, + see the description of Type= in + systemd.service5 for + details. Note that when this type is used the service manager (and thus the systemd-run command) + considers service start-up successful as soon as the fork() for the main service process + succeeded, i.e. before the execve() is invoked, and thus even if the specified command cannot + be started. Consider using the service type (i.e. ) to + ensure that systemd-run returns successfully only if the specified command line has been + successfully started. + + + + Options + + The following options are understood: + + + + + + Do not query the user for authentication for + privileged operations. + + + + + + + Create a transient .scope unit instead of the default transient + .service unit (see above). + + + + + + + + + Use this unit name instead of an automatically + generated one. + + + + + + + Sets a property on the scope or service unit that is created. This option takes an assignment + in the same format as + systemctl1's + set-property command. + + + + + + + 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 Description= in + systemd.unit5. + + + + + + + Make the new .service or .scope unit part + of the specified slice, instead of system.slice (when running in + mode) or the root slice (when running in + mode). + + + + + + + Make the new .service or .scope unit part + of the inherited slice. This option can be combined with . + + An inherited slice is located within systemd-run slice. Example: if + systemd-run slice is foo.slice, and the + argument is bar, the unit will be placed under the + foo-bar.slice. + + + + + + + + + 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 + RemainAfterExit= in + systemd.service5. + + + + + + + + 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 + SendSIGHUP= in + systemd.kill5. + + + + + + + + Sets the service type. Also see + Type= in + systemd.service5. This + option has no effect in conjunction with + . Defaults to + simple. + + + + + + + + Runs the service process under the specified UNIX user and group. Also see + User= and Group= in + systemd.exec5. + + + + + + + Runs the service process with the specified + nice level. Also see Nice= in + systemd.exec5. + + + + + + + Runs the service process with the specified working directory. Also see + WorkingDirectory= in + systemd.exec5. + + + + + + + + Similar to but uses the current working directory of the + caller for the service to execute. + + + + + + + Runs the service process with the specified environment variable set. + Also see Environment= in + systemd.exec5. + + + + + + + + When invoking the command, the transient service connects its standard input, output and error + to the terminal systemd-run 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. + + Note that + machinectl1's + shell command is usually a better alternative for requesting a new, interactive login + session on the local host or a local container. + + See below for details on how this switch combines with . + + + + + + + If specified, standard input, output, and error of the transient service are inherited from the + systemd-run command itself. This allows systemd-run + 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 instead + in that case. + + When both and 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 is used, and otherwise . + + When this option is used the original file descriptors systemd-run receives are passed + to the service processes as-is. If the service runs with different privileges than + systemd-run, 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 echo "hello" > /dev/stderr 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 echo + "hello" >&2 instead, which is mostly equivalent and avoids this pitfall. + + + + + + + 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. + + + + + + + Suppresses additional informational output + while running. This is particularly useful in combination with + when it will suppress the initial + message explaining how to terminate the TTY connection. + + + + + + + + + + Defines a monotonic timer relative to different starting points for starting the specified + command. See OnActiveSec=, OnBootSec=, OnStartupSec=, + OnUnitActiveSec= and OnUnitInactiveSec= in + systemd.timer5 for + details. These options are shortcuts for --timer-property= with the relevant properties. + These options may not be combined with or . + + + + + + + Defines a calendar timer for starting the specified command. See OnCalendar= + in systemd.timer5. This + option is a shortcut for --timer-property=OnCalendar=. This option may not be combined with + or . + + + + + + + + Defines a trigger based on system clock jumps or timezone changes for starting the + specified command. See OnClockChange= and OnTimezoneChange= in + systemd.timer5. These + options are shortcuts for --timer-property=OnClockChange=yes and + --timer-property=OnTimezoneChange=yes. These options may not be combined with + or . + + + + + + + + Sets a property on the path, socket, or timer unit that is created. This option is similar to + 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 + systemctl1's + set-property command. These options may not be combined with + or . + + + + + + + + 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 systemd-run will wait + until the unit's start-up is completed. By passing this argument, it is only verified and enqueued. This + option may not be combined with . + + + + + + + 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's runtime is shown, including total runtime (as well as + CPU usage, if was set) and the exit code and status of the main + process. This output may be suppressed with . This option may not be combined with + , or the various path, socket, or timer options. + + + + + + + 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 + systemctl reset-failed 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 + --property=CollectMode=inactive-or-failed, see the explanation for + CollectMode= in + systemd.unit5 for further + information. + + + + + + + + + + + + All command line arguments after the first non-option + argument become part of the command line of the launched + process. If a command is run as service unit, the first argument + needs to be an absolute program path. + + + + Exit status + + On success, 0 is returned. If systemd-run failed to start the service, a + non-zero return value will be returned. If systemd-run 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 + SuccessExitStatus= in + systemd.service5. + + + + + Examples + + + Logging environment variables provided by systemd to services + + # 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 + + + + Limiting resources available to a command + + # systemd-run -p BlockIOWeight=10 updatedb + + This command invokes the + updatedb8 + tool, but lowers the block I/O weight for it to 10. See + systemd.resource-control5 + for more information on the BlockIOWeight= + property. + + + + Running commands at a specified time + + The following command will touch a file after 30 seconds. + + # 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. + + + + Allowing access to the tty + + The following command invokes /bin/bash as a service + passing its standard input, output and error to the calling TTY. + + # systemd-run -t --send-sighup /bin/bash + + + + Start <command>screen</command> as a user service + + $ 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. + + + This starts the screen process as a child of the + systemd --user process that was started by + user@.service, in a scope unit. A + systemd.scope5 + unit is used instead of a + systemd.service5 + unit, because screen will exit when detaching from the terminal, + and a service unit would be terminated. Running screen + as a user unit has the advantage that it is not part of the session scope. + If KillUserProcesses=yes is configured in + logind.conf5, + the default, the session scope will be terminated when the user logs + out of that session. + + 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. + + Enabling lingering allows the user to run processes without being logged in, + for example to allow screen to persist after the user logs out, + even if the session scope is terminated. In the default configuration, users can + enable lingering for themselves: + + $ loginctl enable-linger + + + + Return value + + $ systemd-run --user --wait true +$ systemd-run --user --wait -p SuccessExitStatus=11 bash -c 'exit 11' +$ systemd-run --user --wait -p SuccessExitStatus=SIGUSR1 bash -c 'kill -SIGUSR1 $$$$' + + Those three invocations will succeed, i.e. terminate with an exit code of 0. + + + + + See Also + + systemd1, + systemctl1, + systemd.unit5, + systemd.service5, + systemd.scope5, + systemd.slice5, + systemd.exec5, + systemd.resource-control5, + systemd.timer5, + systemd-mount1, + machinectl1 + + + + -- cgit v1.2.3