X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsystemd-run.xml;h=b9cec91d1573632d499644bcbe722c871af70633;hp=6b0189c25d60f4851d01bbc7d0e19b44f8dfbc6d;hb=4c213d6cf416917c61f82d8bee795b8f3a4c5372;hpb=d6ee7fa24f5437b7bb2e12f94e0cb828ed25943a diff --git a/man/systemd-run.xml b/man/systemd-run.xml index 6b0189c25..b9cec91d1 100644 --- a/man/systemd-run.xml +++ b/man/systemd-run.xml @@ -1,4 +1,4 @@ - + @@ -21,7 +21,8 @@ You should have received a copy of the GNU Lesser General Public License along with systemd; If not, see . --> - + systemd-run @@ -44,7 +45,7 @@ along with systemd; If not, see . systemd-run - Run programs in transient scope or service units + Run programs in transient scope or service or timer units @@ -55,15 +56,23 @@ along with systemd; If not, see . ARGS + + systemd-run + OPTIONS + TIMER OPTIONS + COMMAND + ARGS + Description - systemd-run may be used create and start - a transient .service or a - .scope unit and run the specified - COMMAND in it. + systemd-run may be used to create and + start a transient .service or a transient + .timer or a .scope unit + and run the specified COMMAND in + it. If a command is run as transient service unit, it will be started and managed by the service manager like any other service, @@ -73,6 +82,18 @@ along with systemd; If not, see . will start the service asynchronously in the background and immediately return. + If a command is run with timer options, transient timer unit + also be created with transient service unit. But the transient + timer unit is only started immediately. The transient service unit + will be started when the transient timer is elapsed. If + is specified with timer options, the + COMMAND can be omitted. In this case, + systemd-run assumes service unit is already + loaded and creates transient timer unit only. To successfully + create timer unit, already loaded service unit should be specified + with . This transient timer unit can + activate the existing service unit like any other timer. + If a command is run as transient scope unit, it will be started directly by systemd-run and thus inherit the execution environment of the caller. It is however @@ -88,30 +109,6 @@ along with systemd; If not, see . The following options are understood: - - - - - Prints a short help - text and exits. - - - - - - Prints a short version - string and exits. - - - - - - - Talk to the service manager of the calling user, - rather than the service manager of the system. - - - @@ -129,12 +126,24 @@ along with systemd; If not, see . generated one. + + + + + Sets a unit property for the scope or service + unit that is created. This takes an assignment in the same + format as + systemctl1's + set-property command. + + + - Provide description for the unit. If not - specified, the command itself will be used as a description. - See Description= in + Provide a description for the service or scope + unit. If not specified, the command itself will be used as a + description. See Description= in systemd.unit5. @@ -151,10 +160,10 @@ along with systemd; If not, see . - After the service's 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 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 RemainAfterExit= in systemd.service5. @@ -164,18 +173,117 @@ along with systemd; If not, see . - When terminating the scope 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 + 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 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 + environment variables set. Also see + Environment= in + systemd.exec5. + + + + + + + + + + + + + + + + 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 realtime (i.e. wallclock) timers with + calendar event expressions. Also see + OnCalendar= in + systemd.timer5. This + option has no effect in conjunction 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 + set-property command. + + + + - All command-line arguments after the first non-option - argument become part of the commandline of the launched + 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, its first argument needs to be an absolute binary path. @@ -187,6 +295,46 @@ along with systemd; If not, see . code otherwise. + + Examples + + The following command will log the 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 + + The following command invokes the + updatedb8 + tool, but lowers the block IO weight for it to 10. See + systemd.resource-control5 + for more information on the BlockIOWeight= + property. + + # systemd-run -p BlockIOWeight=10 updatedb + + 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 as unit run-71.service. +# journalctl -b -u run-73.timer +-- Logs begin at Fri 2014-12-05 19:09:21 KST, end 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-73.service +-- Logs begin at Fri 2014-12-05 19:09:21 KST, end 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. + + See Also @@ -195,7 +343,11 @@ along with systemd; If not, see . systemd.unit5, systemd.service5, systemd.scope5, - systemd.slice5. + systemd.slice5, + systemd.exec5, + systemd.resource-control5, + systemd.timer5, + machinectl1