diff options
author | Luke Shumaker <lukeshu@sbcglobal.net> | 2016-12-17 03:11:52 -0500 |
---|---|---|
committer | Luke Shumaker <lukeshu@sbcglobal.net> | 2016-12-17 03:11:52 -0500 |
commit | b849891b5dde5ee14ab8b7b7db74e65a4a38d993 (patch) | |
tree | 29bb0e6fda9b4b170041913de495da057bbe3621 /src/grp-system/grp-utils/systemd-run | |
parent | 004efebf9cc559ea131bb9460ee0ee198e2d5da7 (diff) | |
parent | 881228ff72434a0e3401a16bd87f179ef0ab1619 (diff) |
Merge branch 'notsystemd/postmove' into notsystemd/master
# Conflicts:
# src/grp-journal/libjournal-core/.gitignore
# src/grp-system/libcore/include/core/mount.h
Diffstat (limited to 'src/grp-system/grp-utils/systemd-run')
4 files changed, 315 insertions, 155 deletions
diff --git a/src/grp-system/grp-utils/systemd-run/run.c b/src/grp-system/grp-utils/systemd-run/run.c index a68938fb71..274edaf2f0 100644 --- a/src/grp-system/grp-utils/systemd-run/run.c +++ b/src/grp-system/grp-utils/systemd-run/run.c @@ -32,6 +32,7 @@ #include "systemd-basic/formats-util.h" #include "systemd-basic/parse-util.h" #include "systemd-basic/path-util.h" +#include "systemd-basic/process-util.h" #include "systemd-basic/signal-util.h" #include "systemd-basic/strv.h" #include "systemd-basic/terminal-util.h" @@ -45,6 +46,7 @@ static bool arg_ask_password = true; static bool arg_scope = false; static bool arg_remain_after_exit = false; static bool arg_no_block = false; +static bool arg_wait = false; static const char *arg_unit = NULL; static const char *arg_description = NULL; static const char *arg_slice = NULL; @@ -83,9 +85,7 @@ static void polkit_agent_open_if_enabled(void) { static void help(void) { printf("%s [OPTIONS...] {COMMAND} [ARGS...]\n\n" - "Run the specified command in a transient scope or service or timer\n" - "unit. If a timer option is specified and the unit specified with\n" - "the --unit option exists, the command can be omitted.\n\n" + "Run the specified command in a transient scope or service.\n\n" " -h --help Show this help\n" " --version Show package version\n" " --no-ask-password Do not prompt for password\n" @@ -94,11 +94,12 @@ static void help(void) { " -M --machine=CONTAINER Operate on local container\n" " --scope Run this as scope rather than service\n" " --unit=UNIT Run under the specified unit name\n" - " -p --property=NAME=VALUE Set unit property\n" + " -p --property=NAME=VALUE Set service or scope unit property\n" " --description=TEXT Description for unit\n" " --slice=SLICE Run in the specified slice\n" " --no-block Do not wait until operation finished\n" " -r --remain-after-exit Leave service around until explicitly stopped\n" + " --wait Wait until service stopped again\n" " --send-sighup Send SIGHUP when terminating\n" " --service-type=TYPE Service type\n" " --uid=USER Run as system user\n" @@ -107,15 +108,15 @@ static void help(void) { " -E --setenv=NAME=VALUE Set environment\n" " -t --pty Run service on pseudo tty\n" " -q --quiet Suppress information messages during runtime\n\n" - "Timer options:\n\n" + "Timer options:\n" " --on-active=SECONDS Run after SECONDS delay\n" " --on-boot=SECONDS Run SECONDS after machine was booted up\n" " --on-startup=SECONDS Run SECONDS after systemd activation\n" " --on-unit-active=SECONDS Run SECONDS after the last activation\n" " --on-unit-inactive=SECONDS Run SECONDS after the last deactivation\n" " --on-calendar=SPEC Realtime timer\n" - " --timer-property=NAME=VALUE Set timer unit property\n", - program_invocation_short_name); + " --timer-property=NAME=VALUE Set timer unit property\n" + , program_invocation_short_name); } static bool with_timer(void) { @@ -146,6 +147,7 @@ static int parse_argv(int argc, char *argv[]) { ARG_TIMER_PROPERTY, ARG_NO_BLOCK, ARG_NO_ASK_PASSWORD, + ARG_WAIT, }; static const struct option options[] = { @@ -162,6 +164,7 @@ static int parse_argv(int argc, char *argv[]) { { "host", required_argument, NULL, 'H' }, { "machine", required_argument, NULL, 'M' }, { "service-type", required_argument, NULL, ARG_SERVICE_TYPE }, + { "wait", no_argument, NULL, ARG_WAIT }, { "uid", required_argument, NULL, ARG_EXEC_USER }, { "gid", required_argument, NULL, ARG_EXEC_GROUP }, { "nice", required_argument, NULL, ARG_NICE }, @@ -178,7 +181,7 @@ static int parse_argv(int argc, char *argv[]) { { "on-calendar", required_argument, NULL, ARG_ON_CALENDAR }, { "timer-property", required_argument, NULL, ARG_TIMER_PROPERTY }, { "no-block", no_argument, NULL, ARG_NO_BLOCK }, - { "no-ask-password", no_argument, NULL, ARG_NO_ASK_PASSWORD }, + { "no-ask-password", no_argument, NULL, ARG_NO_ASK_PASSWORD }, {}, }; @@ -195,13 +198,13 @@ static int parse_argv(int argc, char *argv[]) { help(); return 0; + case ARG_VERSION: + return version(); + case ARG_NO_ASK_PASSWORD: arg_ask_password = false; break; - case ARG_VERSION: - return version(); - case ARG_USER: arg_user = true; break; @@ -257,11 +260,9 @@ static int parse_argv(int argc, char *argv[]) { break; case ARG_NICE: - r = safe_atoi(optarg, &arg_nice); - if (r < 0 || arg_nice < PRIO_MIN || arg_nice >= PRIO_MAX) { - log_error("Failed to parse nice value"); - return -EINVAL; - } + r = parse_nice(optarg, &arg_nice); + if (r < 0) + return log_error_errno(r, "Failed to parse nice value: %s", optarg); arg_nice_set = true; break; @@ -361,6 +362,10 @@ static int parse_argv(int argc, char *argv[]) { arg_no_block = true; break; + case ARG_WAIT: + arg_wait = true; + break; + case '?': return -EINVAL; @@ -408,22 +413,36 @@ static int parse_argv(int argc, char *argv[]) { return -EINVAL; } + if (arg_wait) { + if (arg_no_block) { + log_error("--wait may not be combined with --no-block."); + return -EINVAL; + } + + if (with_timer()) { + log_error("--wait may not be combined with timer operations."); + return -EINVAL; + } + + if (arg_scope) { + log_error("--wait may not be combined with --scope."); + return -EINVAL; + } + } + return 1; } static int transient_unit_set_properties(sd_bus_message *m, char **properties) { - char **i; int r; r = sd_bus_message_append(m, "(sv)", "Description", "s", arg_description); if (r < 0) return r; - STRV_FOREACH(i, properties) { - r = bus_append_unit_property_assignment(m, *i); - if (r < 0) - return r; - } + r = bus_append_unit_property_assignment_many(m, properties); + if (r < 0) + return r; return 0; } @@ -473,6 +492,12 @@ static int transient_service_set_properties(sd_bus_message *m, char **argv, cons if (r < 0) return r; + if (arg_wait) { + r = sd_bus_message_append(m, "(sv)", "AddRef", "b", 1); + if (r < 0) + return r; + } + if (arg_remain_after_exit) { r = sd_bus_message_append(m, "(sv)", "RemainAfterExit", "b", arg_remain_after_exit); if (r < 0) @@ -730,9 +755,97 @@ static int make_unit_name(sd_bus *bus, UnitType t, char **ret) { return 0; } +typedef struct RunContext { + sd_bus *bus; + sd_event *event; + PTYForward *forward; + sd_bus_slot *match; + + /* The exit data of the unit */ + char *active_state; + uint64_t inactive_exit_usec; + uint64_t inactive_enter_usec; + char *result; + uint64_t cpu_usage_nsec; + uint32_t exit_code; + uint32_t exit_status; +} RunContext; + +static void run_context_free(RunContext *c) { + assert(c); + + c->forward = pty_forward_free(c->forward); + c->match = sd_bus_slot_unref(c->match); + c->bus = sd_bus_unref(c->bus); + c->event = sd_event_unref(c->event); + + free(c->active_state); + free(c->result); +} + +static void run_context_check_done(RunContext *c) { + bool done = true; + + assert(c); + + if (c->match) + done = done && (c->active_state && STR_IN_SET(c->active_state, "inactive", "failed")); + + if (c->forward) + done = done && pty_forward_is_done(c->forward); + + if (done) + sd_event_exit(c->event, EXIT_SUCCESS); +} + +static int on_properties_changed(sd_bus_message *m, void *userdata, sd_bus_error *error) { + + static const struct bus_properties_map map[] = { + { "ActiveState", "s", NULL, offsetof(RunContext, active_state) }, + { "InactiveExitTimestampMonotonic", "t", NULL, offsetof(RunContext, inactive_exit_usec) }, + { "InactiveEnterTimestampMonotonic", "t", NULL, offsetof(RunContext, inactive_enter_usec) }, + { "Result", "s", NULL, offsetof(RunContext, result) }, + { "ExecMainCode", "i", NULL, offsetof(RunContext, exit_code) }, + { "ExecMainStatus", "i", NULL, offsetof(RunContext, exit_status) }, + { "CPUUsageNSec", "t", NULL, offsetof(RunContext, cpu_usage_nsec) }, + {} + }; + + RunContext *c = userdata; + int r; + + r = bus_map_all_properties(c->bus, + "org.freedesktop.systemd1", + sd_bus_message_get_path(m), + map, + c); + if (r < 0) { + sd_event_exit(c->event, EXIT_FAILURE); + return log_error_errno(r, "Failed to query unit state: %m"); + } + + run_context_check_done(c); + return 0; +} + +static int pty_forward_handler(PTYForward *f, int rcode, void *userdata) { + RunContext *c = userdata; + + assert(f); + + if (rcode < 0) { + sd_event_exit(c->event, EXIT_FAILURE); + return log_error_errno(rcode, "Error on PTY forwarding logic: %m"); + } + + run_context_check_done(c); + return 0; +} + static int start_transient_service( sd_bus *bus, - char **argv) { + char **argv, + int *retval) { _cleanup_(sd_bus_message_unrefp) sd_bus_message *m = NULL, *reply = NULL; _cleanup_(sd_bus_error_free) sd_bus_error error = SD_BUS_ERROR_NULL; @@ -743,6 +856,7 @@ static int start_transient_service( assert(bus); assert(argv); + assert(retval); if (arg_pty) { @@ -866,40 +980,95 @@ static int start_transient_service( return r; } - if (master >= 0) { - _cleanup_(pty_forward_freep) PTYForward *forward = NULL; - _cleanup_(sd_event_unrefp) sd_event *event = NULL; - char last_char = 0; + if (!arg_quiet) + log_info("Running as unit: %s", service); + + if (arg_wait || master >= 0) { + _cleanup_(run_context_free) RunContext c = {}; - r = sd_event_default(&event); + c.bus = sd_bus_ref(bus); + + r = sd_event_default(&c.event); if (r < 0) return log_error_errno(r, "Failed to get event loop: %m"); - assert_se(sigprocmask_many(SIG_BLOCK, NULL, SIGWINCH, SIGTERM, SIGINT, -1) >= 0); + if (master >= 0) { + assert_se(sigprocmask_many(SIG_BLOCK, NULL, SIGWINCH, SIGTERM, SIGINT, -1) >= 0); + (void) sd_event_add_signal(c.event, NULL, SIGINT, NULL, NULL); + (void) sd_event_add_signal(c.event, NULL, SIGTERM, NULL, NULL); - (void) sd_event_add_signal(event, NULL, SIGINT, NULL, NULL); - (void) sd_event_add_signal(event, NULL, SIGTERM, NULL, NULL); + if (!arg_quiet) + log_info("Press ^] three times within 1s to disconnect TTY."); - if (!arg_quiet) - log_info("Running as unit: %s\nPress ^] three times within 1s to disconnect TTY.", service); + r = pty_forward_new(c.event, master, PTY_FORWARD_IGNORE_INITIAL_VHANGUP, &c.forward); + if (r < 0) + return log_error_errno(r, "Failed to create PTY forwarder: %m"); - r = pty_forward_new(event, master, PTY_FORWARD_IGNORE_INITIAL_VHANGUP, &forward); - if (r < 0) - return log_error_errno(r, "Failed to create PTY forwarder: %m"); + pty_forward_set_handler(c.forward, pty_forward_handler, &c); + } + + if (arg_wait) { + _cleanup_free_ char *path = NULL; + const char *mt; + + path = unit_dbus_path_from_name(service); + if (!path) + return log_oom(); + + mt = strjoina("type='signal'," + "sender='org.freedesktop.systemd1'," + "path='", path, "'," + "interface='org.freedesktop.DBus.Properties'," + "member='PropertiesChanged'"); + r = sd_bus_add_match(bus, &c.match, mt, on_properties_changed, &c); + if (r < 0) + return log_error_errno(r, "Failed to add properties changed signal."); + + r = sd_bus_attach_event(bus, c.event, 0); + if (r < 0) + return log_error_errno(r, "Failed to attach bus to event loop."); + } - r = sd_event_loop(event); + r = sd_event_loop(c.event); if (r < 0) return log_error_errno(r, "Failed to run event loop: %m"); - pty_forward_get_last_char(forward, &last_char); + if (c.forward) { + char last_char = 0; - forward = pty_forward_free(forward); + r = pty_forward_get_last_char(c.forward, &last_char); + if (r >= 0 && !arg_quiet && last_char != '\n') + fputc('\n', stdout); + } - if (!arg_quiet && last_char != '\n') - fputc('\n', stdout); + if (!arg_quiet) { + if (!isempty(c.result)) + log_info("Finished with result: %s", strna(c.result)); - } else if (!arg_quiet) - log_info("Running as unit: %s", service); + if (c.exit_code == CLD_EXITED) + log_info("Main processes terminated with: code=%s/status=%i", sigchld_code_to_string(c.exit_code), c.exit_status); + else if (c.exit_code > 0) + log_info("Main processes terminated with: code=%s/status=%s", sigchld_code_to_string(c.exit_code), signal_to_string(c.exit_status)); + + if (c.inactive_enter_usec > 0 && c.inactive_enter_usec != USEC_INFINITY && + c.inactive_exit_usec > 0 && c.inactive_exit_usec != USEC_INFINITY && + c.inactive_enter_usec > c.inactive_exit_usec) { + char ts[FORMAT_TIMESPAN_MAX]; + log_info("Service runtime: %s", format_timespan(ts, sizeof(ts), c.inactive_enter_usec - c.inactive_exit_usec, USEC_PER_MSEC)); + } + + if (c.cpu_usage_nsec > 0 && c.cpu_usage_nsec != NSEC_INFINITY) { + char ts[FORMAT_TIMESPAN_MAX]; + log_info("CPU time consumed: %s", format_timespan(ts, sizeof(ts), (c.cpu_usage_nsec + NSEC_PER_USEC - 1) / NSEC_PER_USEC, USEC_PER_MSEC)); + } + } + + /* Try to propagate the service's return value */ + if (c.result && STR_IN_SET(c.result, "success", "exit-code") && c.exit_code == CLD_EXITED) + *retval = c.exit_status; + else + *retval = EXIT_FAILURE; + } return 0; } @@ -999,17 +1168,21 @@ static int start_transient_scope( uid_t uid; gid_t gid; - r = get_user_creds(&arg_exec_user, &uid, &gid, &home, &shell); + r = get_user_creds_clean(&arg_exec_user, &uid, &gid, &home, &shell); if (r < 0) return log_error_errno(r, "Failed to resolve user %s: %m", arg_exec_user); - r = strv_extendf(&user_env, "HOME=%s", home); - if (r < 0) - return log_oom(); + if (home) { + r = strv_extendf(&user_env, "HOME=%s", home); + if (r < 0) + return log_oom(); + } - r = strv_extendf(&user_env, "SHELL=%s", shell); - if (r < 0) - return log_oom(); + if (shell) { + r = strv_extendf(&user_env, "SHELL=%s", shell); + if (r < 0) + return log_oom(); + } r = strv_extendf(&user_env, "USER=%s", arg_exec_user); if (r < 0) @@ -1146,7 +1319,7 @@ static int start_transient_timer( if (r < 0) return bus_log_create_error(r); - if (argv[0]) { + if (!strv_isempty(argv)) { r = sd_bus_message_open_container(m, 'r', "sa(sv)"); if (r < 0) return bus_log_create_error(r); @@ -1192,9 +1365,11 @@ static int start_transient_timer( if (r < 0) return r; - log_info("Running timer as unit: %s", timer); - if (argv[0]) - log_info("Will run service as unit: %s", service); + if (!arg_quiet) { + log_info("Running timer as unit: %s", timer); + if (argv[0]) + log_info("Will run service as unit: %s", service); + } return 0; } @@ -1202,7 +1377,7 @@ static int start_transient_timer( int main(int argc, char* argv[]) { _cleanup_(sd_bus_flush_close_unrefp) sd_bus *bus = NULL; _cleanup_free_ char *description = NULL, *command = NULL; - int r; + int r, retval = EXIT_SUCCESS; log_parse_environment(); log_open(); @@ -1239,7 +1414,12 @@ int main(int argc, char* argv[]) { arg_description = description; } - r = bus_connect_transport_systemd(arg_transport, arg_host, arg_user, &bus); + /* If --wait is used connect via the bus, unconditionally, as ref/unref is not supported via the limited direct + * connection */ + if (arg_wait) + r = bus_connect_transport(arg_transport, arg_host, arg_user, &bus); + else + r = bus_connect_transport_systemd(arg_transport, arg_host, arg_user, &bus); if (r < 0) { log_error_errno(r, "Failed to create bus connection: %m"); goto finish; @@ -1250,12 +1430,12 @@ int main(int argc, char* argv[]) { else if (with_timer()) r = start_transient_timer(bus, argv + optind); else - r = start_transient_service(bus, argv + optind); + r = start_transient_service(bus, argv + optind, &retval); finish: strv_free(arg_environment); strv_free(arg_property); strv_free(arg_timer_property); - return r < 0 ? EXIT_FAILURE : EXIT_SUCCESS; + return r < 0 ? EXIT_FAILURE : retval; } diff --git a/src/grp-system/grp-utils/systemd-run/systemd-run.completion.bash b/src/grp-system/grp-utils/systemd-run/systemd-run.completion.bash index 022331e6a9..4116ba7eca 100644 --- a/src/grp-system/grp-utils/systemd-run/systemd-run.completion.bash +++ b/src/grp-system/grp-utils/systemd-run/systemd-run.completion.bash @@ -36,7 +36,8 @@ _systemd_run() { -r --remain-after-exit --send-sighup -H --host -M --machine --service-type --on-active --on-boot --on-startup --on-unit-active --on-unit-inactive --on-calendar --timer-property -t --pty -q --quiet --no-block - --uid --gid --nice --setenv -p --property --no-ask-password' + --uid --gid --nice --setenv -p --property --no-ask-password + --wait' local mode=--system local i diff --git a/src/grp-system/grp-utils/systemd-run/systemd-run.completion.zsh b/src/grp-system/grp-utils/systemd-run/systemd-run.completion.zsh index 6362b97766..da9f73a6d0 100644 --- a/src/grp-system/grp-utils/systemd-run/systemd-run.completion.zsh +++ b/src/grp-system/grp-utils/systemd-run/systemd-run.completion.zsh @@ -57,4 +57,5 @@ _arguments \ '--on-unit-inactive=[Run after SEC seconds from the last deactivation]:SEC' \ '--on-calendar=[Realtime timer]:SPEC' \ '--timer-property=[Set timer unit property]:NAME=VALUE' \ + '--wait=[Wait until service stopped again]' \ '*::command:_command' diff --git a/src/grp-system/grp-utils/systemd-run/systemd-run.xml b/src/grp-system/grp-utils/systemd-run/systemd-run.xml index 9c1a29218e..2ad8cb0835 100644 --- a/src/grp-system/grp-utils/systemd-run/systemd-run.xml +++ b/src/grp-system/grp-utils/systemd-run/systemd-run.xml @@ -45,7 +45,7 @@ <refnamediv> <refname>systemd-run</refname> - <refpurpose>Run programs in transient scope or service or timer units</refpurpose> + <refpurpose>Run programs in transient scope units, service units, or timer-scheduled service units</refpurpose> </refnamediv> <refsynopsisdiv> @@ -68,42 +68,30 @@ <refsect1> <title>Description</title> - <para><command>systemd-run</command> may be used to create and - start a transient <filename>.service</filename> or - <filename>.scope</filename> unit and run the specified - <replaceable>COMMAND</replaceable> in it. It may also be used to - create and start transient <filename>.timer</filename> - units.</para> - - <para>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 <command>systemctl - list-units</command> 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, <command>systemd-run</command> - will start the service asynchronously in the background and return - after the command has begun execution.</para> - - <para>If a command is run as transient scope unit, it will be - started by <command>systemd-run</command> 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 <command>systemctl list-units</command>. Execution - in this case is synchronous, and will return only when the command - finishes. This mode is enabled via the <option>--scope</option> - switch (see below). </para> - - <para>If a command is run with timer options such as - <option>--on-calendar=</option> (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 <option>--unit=</option> is specified, the - <replaceable>COMMAND</replaceable> may be omitted. In this case, - <command>systemd-run</command> only creates a - <filename>.timer</filename> unit that invokes the specified unit - when elapsing.</para> + <para><command>systemd-run</command> may be used to create and start a transient <filename>.service</filename> or + <filename>.scope</filename> unit and run the specified <replaceable>COMMAND</replaceable> in it. It may also be + used to create and start a transient <filename>.timer</filename> unit, that activates a + <filename>.service</filename> unit when elapsing.</para> + + <para>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 <command>systemctl list-units</command> 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, <command>systemd-run</command> will start the service asynchronously in the background and return after the + command has begun execution (unless <option>--no-block</option> or <option>--watch</option> are specified, see + below).</para> + + <para>If a command is run as transient scope unit, it will be executed by <command>systemd-run</command> 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 <command>systemctl + list-units</command>. Execution in this case is synchronous, and will return only when the command finishes. This + mode is enabled via the <option>--scope</option> switch (see below). </para> + + <para>If a command is run with timer options such as <option>--on-calendar=</option> (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>--unit=</option> + option is specified, the <replaceable>COMMAND</replaceable> may be omitted. In this case, + <command>systemd-run</command> creates only a <filename>.timer</filename> unit that invokes the specified unit when + elapsing.</para> </refsect1> <refsect1> @@ -123,8 +111,8 @@ <term><option>--scope</option></term> <listitem> - <para>Create a transient <filename>.scope</filename> unit instead of - the default transient <filename>.service</filename> unit. + <para>Create a transient <filename>.scope</filename> unit instead of the default transient + <filename>.service</filename> unit (see above). </para> </listitem> </varlistentry> @@ -140,9 +128,8 @@ <term><option>--property=</option></term> <term><option>-p</option></term> - <listitem><para>Sets a unit property for the scope or service - unit that is created. This takes an assignment in the same - format as + <listitem><para>Sets a property on the scope or service unit that is created. This option takes an assignment + in the same format as <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s <command>set-property</command> command.</para> </listitem> @@ -151,9 +138,8 @@ <varlistentry> <term><option>--description=</option></term> - <listitem><para>Provide a description for the service or scope - unit. If not specified, the command itself will be used as a - description. See <varname>Description=</varname> in + <listitem><para>Provide a description for the service, scope or timer unit. If not specified, the command + itself will be used as a description. See <varname>Description=</varname> in <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. </para></listitem> </varlistentry> @@ -161,19 +147,16 @@ <varlistentry> <term><option>--slice=</option></term> - <listitem><para>Make the new <filename>.service</filename> or - <filename>.scope</filename> unit part of the specified slice, - instead of the <filename>system.slice</filename>.</para> + <listitem><para>Make the new <filename>.service</filename> or <filename>.scope</filename> unit part of the + specified slice, instead of <filename>system.slice</filename>.</para> </listitem> </varlistentry> <varlistentry> <term><option>--remain-after-exit</option></term> - <listitem><para>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 + <listitem><para>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 <varname>RemainAfterExit=</varname> in <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>. </para> @@ -183,10 +166,8 @@ <varlistentry> <term><option>--send-sighup</option></term> - <listitem><para>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 + <listitem><para>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 <varname>SendSIGHUP=</varname> in <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>. </para> @@ -209,9 +190,8 @@ <term><option>--uid=</option></term> <term><option>--gid=</option></term> - <listitem><para>Runs the service process under the UNIX user - and group. Also see <varname>User=</varname> and - <varname>Group=</varname> in + <listitem><para>Runs the service process under the specified UNIX user and group. Also see + <varname>User=</varname> and <varname>Group=</varname> in <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> </listitem> </varlistentry> @@ -239,11 +219,9 @@ <term><option>--pty</option></term> <term><option>-t</option></term> - <listitem><para>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.</para></listitem> + <listitem><para>When invoking the command, the transient service connects its standard input and output to the + terminal <command>systemd-run</command> is invoked on, via a pseudo TTY device. This allows running binaries + that expect interactive user input as services, such as interactive command shells.</para></listitem> </varlistentry> <varlistentry> @@ -263,44 +241,32 @@ <term><option>--on-unit-active=</option></term> <term><option>--on-unit-inactive=</option></term> - <listitem><para>Defines monotonic timers relative to different - starting points. Also see <varname>OnActiveSec=</varname>, - <varname>OnBootSec=</varname>, - <varname>OnStartupSec=</varname>, - <varname>OnUnitActiveSec=</varname> and - <varname>OnUnitInactiveSec=</varname> in - <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>. This - options have no effect in conjunction with - <option>--scope</option>.</para> + <listitem><para>Defines a monotonic timer relative to different starting points for starting the specified + command. See <varname>OnActiveSec=</varname>, <varname>OnBootSec=</varname>, <varname>OnStartupSec=</varname>, + <varname>OnUnitActiveSec=</varname> and <varname>OnUnitInactiveSec=</varname> in + <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry> for + details. These options may not be combined with <option>--scope</option>.</para> </listitem> </varlistentry> <varlistentry> <term><option>--on-calendar=</option></term> - <listitem><para>Defines realtime (i.e. wallclock) timers with - calendar event expressions. Also see - <varname>OnCalendar=</varname> in - <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>. This - option has no effect in conjunction with - <option>--scope</option>.</para> + <listitem><para>Defines a calendar timer for starting the specified command. See <varname>OnCalendar=</varname> + in <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>. This + option may not be combined with <option>--scope</option>.</para> </listitem> </varlistentry> <varlistentry> <term><option>--timer-property=</option></term> - <listitem><para>Sets a timer unit property for the timer unit - that is created. It is similar with - <option>--property</option> but only for created timer - unit. This option only has effect in conjunction with - <option>--on-active=</option>, <option>--on-boot=</option>, - <option>--on-startup=</option>, - <option>--on-unit-active=</option>, - <option>--on-unit-inactive=</option>, - <option>--on-calendar=</option>. This takes an assignment in - the same format as - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s + <listitem><para>Sets a property on the timer unit that is created. This option is similar to + <option>--property=</option> but applies to the transient timer unit rather than the transient service unit + created. This option only has an effect in conjunction with <option>--on-active=</option>, + <option>--on-boot=</option>, <option>--on-startup=</option>, <option>--on-unit-active=</option>, + <option>--on-unit-inactive=</option> or <option>--on-calendar=</option>. This option takes an assignment in the + same format as <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s <command>set-property</command> command.</para> </listitem> </varlistentry> @@ -308,14 +274,25 @@ <term><option>--no-block</option></term> <listitem> - <para>Do not synchronously wait for the requested operation - to finish. If this is not specified, the job will be - verified, enqueued and <command>systemd-run</command> will - wait until the unit's start-up is completed. By passing this - argument, it is only verified and enqueued.</para> + <para>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 <command>systemd-run</command> 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 <option>--wait</option>.</para> </listitem> </varlistentry> + <varlistentry> + <term><option>--wait</option></term> + + <listitem><para>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 <option>--property=CPUAccounting=1</option> was set) and the exit code and status of the main + process. This output may be suppressed with <option>--quiet</option>. This option may not be combined with + <option>--no-block</option>, <option>--scope</option> or the various timer options.</para></listitem> + </varlistentry> + <xi:include href="user-system-options.xml" xpointer="user" /> <xi:include href="user-system-options.xml" xpointer="system" /> <xi:include href="user-system-options.xml" xpointer="host" /> @@ -425,7 +402,7 @@ There is a screen on: 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, <filename>user@.service</filename> and all services underneath it - are terminated. This behaviour is the default, when "lingering" is + are terminated. This behavior is the default, when "lingering" is not enabled for that user. Enabling lingering means that <filename>user@.service</filename> is started automatically during boot, even if the user is not logged in, and that the service is @@ -452,6 +429,7 @@ There is a screen on: <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-mount</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> </para> </refsect1> |