From 014c4c98ba85544d75a8447eb7b78c1953d9e3b7 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Thu, 18 Aug 2016 21:53:38 +0200 Subject: man: document the new --wait switch of systemd-run Also, make major improvements to the an page in general. --- man/systemd-run.xml | 165 ++++++++++++++++++++++------------------------------ 1 file changed, 71 insertions(+), 94 deletions(-) (limited to 'man') diff --git a/man/systemd-run.xml b/man/systemd-run.xml index 56d585cdf9..15f9119e54 100644 --- a/man/systemd-run.xml +++ b/man/systemd-run.xml @@ -68,42 +68,30 @@ 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 transient .timer - units. - - 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. - - If a command is run as transient scope unit, it will be - started 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 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 transient timer - elapses. If the is specified, the - COMMAND may be omitted. In this case, - systemd-run only creates a - .timer unit that invokes the specified unit - when elapsing. + 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. + + 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 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. @@ -123,8 +111,8 @@ - Create a transient .scope unit instead of - the default transient .service unit. + Create a transient .scope unit instead of the default transient + .service unit (see above). @@ -140,9 +128,8 @@ - Sets a unit property for the scope or service - unit that is created. This takes an assignment in the same - format as + 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. @@ -151,9 +138,8 @@ - Provide a description for the service or scope - unit. If not specified, the command itself will be used as a - description. See Description= in + 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 systemd.unit5. @@ -161,19 +147,16 @@ - Make the new .service or - .scope unit part of the specified slice, - instead of the system.slice. + Make the new .service or .scope unit part of the + specified slice, instead of system.slice. - 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 + 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. @@ -183,10 +166,8 @@ - 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 + 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. @@ -209,9 +190,8 @@ - Runs the service process under the UNIX user - and group. Also see User= and - Group= in + Runs the service process under the specified UNIX user and group. Also see + User= and Group= in systemd.exec5. @@ -239,11 +219,9 @@ - When invoking a command, the service connects - its standard input and output to the invoking tty via a - pseudo TTY device. This allows invoking binaries as services - that expect interactive user input, such as interactive - command shells. + When invoking the command, the transient service connects its standard input and output to the + terminal systemd-run is invoked on, via a pseudo TTY device. This allows running binaries + that expect interactive user input as services, such as interactive command shells. @@ -263,44 +241,32 @@ - Defines monotonic timers relative to different - starting points. Also see OnActiveSec=, - OnBootSec=, - OnStartupSec=, - OnUnitActiveSec= and - OnUnitInactiveSec= in - systemd.timer5. This - options have no effect in conjunction with - . + 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 may not be combined with . - Defines realtime (i.e. wallclock) timers with - calendar event expressions. Also see - OnCalendar= in - systemd.timer5. This - option has no effect in conjunction with - . + Defines a calendar timer for starting the specified command. See OnCalendar= + in systemd.timer5. This + option may not be combined with . - Sets a timer unit property for the timer unit - that is created. It is similar with - but only for created timer - unit. This option only has effect in conjunction with - , , - , - , - , - . This takes an assignment in - the same format as - systemctl1's + 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. @@ -308,14 +274,25 @@ - Do not synchronously wait for the requested operation - to finish. If this is not specified, the job 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. + 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 timer options. + + -- cgit v1.2.3-54-g00ecf