X-Git-Url: http://git.ipfire.org/?a=blobdiff_plain;f=man%2Fsystemd-run.xml;h=a88f60fbb6017da5055e7f52b55448e2c5a51b96;hb=6b222c4b0227f9914446ac54754aea867f742be4;hp=7bcea9bc30e79313d4108096ab746a64520f5d19;hpb=186d5f2e79a3b2b518abb3b480309186fcbb7b01;p=thirdparty%2Fsystemd.git diff --git a/man/systemd-run.xml b/man/systemd-run.xml index 7bcea9bc30e..a88f60fbb60 100644 --- a/man/systemd-run.xml +++ b/man/systemd-run.xml @@ -1,27 +1,7 @@ - - - - + + + @@ -29,15 +9,6 @@ systemd-run systemd - - - - Developer - Lennart - Poettering - lennart@poettering.net - - @@ -47,7 +18,7 @@ systemd-run - Run programs in transient scope units, service units, or timer-scheduled service units + Run programs in transient scope units, service units, or path-, socket-, or timer-triggered service units @@ -58,6 +29,20 @@ ARGS + + systemd-run + OPTIONS + PATH OPTIONS + COMMAND + ARGS + + + systemd-run + OPTIONS + SOCKET OPTIONS + COMMAND + ARGS + systemd-run OPTIONS @@ -72,8 +57,8 @@ 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 .timer unit, that activates a - .service unit when elapsing. + 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 @@ -88,12 +73,23 @@ 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 timer options such as (see below), a transient timer - unit is created alongside the service unit for the specified command. Only the transient timer unit is started - immediately, the transient service unit will be started when the timer elapses. If the - option is specified, the COMMAND may be omitted. In this case, - systemd-run creates only a .timer unit that invokes the specified unit when - elapsing. + 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. @@ -121,6 +117,7 @@ + Use this unit name instead of an automatically generated one. @@ -140,8 +137,8 @@ - Provide a description for the service, scope or timer unit. If not specified, the command - itself will be used as a description. See Description= in + 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. @@ -149,12 +146,29 @@ - Make the new .service or .scope unit part of the - specified slice, instead of system.slice. + 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 @@ -207,6 +221,23 @@ + + + + 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. + + @@ -257,6 +288,15 @@ "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. + + @@ -278,7 +318,8 @@ command. See OnActiveSec=, OnBootSec=, OnStartupSec=, OnUnitActiveSec= and OnUnitInactiveSec= in systemd.timer5 for - details. These options may not be combined with or . + details. These options are shortcuts for --timer-property= with the relevant properties. + These options may not be combined with or . @@ -287,20 +328,35 @@ Defines a calendar timer for starting the specified command. See OnCalendar= in systemd.timer5. This - option may not be combined with or . + 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 timer unit that is created. This option is similar to - but applies to the transient timer unit rather than the transient service unit - created. This option only has an effect in conjunction with , - , , , - or . This option takes an assignment in the - same format as systemctl1's - set-property command. + 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 . + @@ -323,7 +379,7 @@ 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 timer options. + , or the various path, socket, or timer options. @@ -359,8 +415,13 @@ Exit status - On success, 0 is returned, a non-zero failure - code otherwise. + 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. + @@ -463,6 +524,16 @@ There is a screen on: $ 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. +