HALF ECHO LEARN / REFERENCE COLLECTION
v262.2man/systemctl.xml
Git blob: b67a7efabcd07f37520a1232e63e3e99dd654150
Lines 2001–3000 of 3,119
<option>socket</option>. When units are listed with <command>list-units</command>,
<command>list-dependencies</command>, <command>show</command>, or <command>status</command>,
only units of the specified types will be shown. By default, units of all types are shown.
Use <option>--type=</option> to reset the filter.</para>
<para>As a special case, if one of the arguments is <option>help</option>, a list of allowed values
will be printed and the program will exit.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--state=</option></term>
<listitem>
<para>The argument is a comma-separated list of unit LOAD, SUB, or ACTIVE states. When listing
units with <command>list-units</command>, <command>list-dependencies</command>,
<command>show</command> or <command>status</command>, show only those in the specified states. Use
<option>--state=failed</option> or <option>--failed</option> to show only failed units. Use
<option>--state=</option> to reset the filter.</para>
<para>As a special case, if one of the arguments is <option>help</option>, a list of allowed values
will be printed and the program will exit.</para>
<xi:include href="version-info.xml" xpointer="v206"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-p</option></term>
<term><option>--property=</option></term>
<listitem>
<para>When showing unit/job/manager properties with the
<command>show</command> command, limit display to properties
specified in the argument. The argument should be a
comma-separated list of property names, such as
<literal>MainPID</literal>. Unless specified, all known
properties are shown. If specified more than once, all
properties with the specified names are shown. Shell
completion is implemented for property names.</para>
<para>For the manager itself,
<command>systemctl show</command>
will show all available properties, most of which are derived or closely match the options described in
<citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
</para>
<para>Properties for units vary by unit type, so showing any
unit (even a non-existent one) is a way to list properties
pertaining to this type. Similarly, showing any job will list
properties pertaining to all jobs. Properties for units are
documented in
<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
and the pages for individual unit types
<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
etc.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-P</option></term>
<listitem>
<xi:include href="standard-options.xml" xpointer="xpointer(//varlistentry[@id='option-P']/listitem/para)" />
<xi:include href="version-info.xml" xpointer="v246"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-a</option></term>
<term><option>--all</option></term>
<listitem>
<para>When listing units with <command>list-units</command>, also show inactive units and
units which are following other units. When showing unit/job/manager properties, show all
properties regardless whether they are set or not.</para>
<para>To list all units installed in the file system, use the
<command>list-unit-files</command> command instead.</para>
<para>When listing units with <command>list-dependencies</command>, recursively show
dependencies of all dependent units (by default only dependencies of target units are
shown).</para>
<para>When used with <command>status</command>, show journal messages in full, even if they include
unprintable characters or are very long. By default, fields with unprintable characters are
abbreviated as "blob data". (Note that the pager may escape unprintable characters again.)</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-r</option></term>
<term><option>--recursive</option></term>
<listitem>
<para>When listing units, also show units of local
containers. Units of local containers will be prefixed with
the container name, separated by a single colon character
(<literal>:</literal>).</para>
<xi:include href="version-info.xml" xpointer="v212"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--reverse</option></term>
<listitem>
<para>Show reverse dependencies between units with
<command>list-dependencies</command>, i.e. follow
dependencies of type <varname>WantedBy=</varname>,
<varname>RequiredBy=</varname>, <varname>UpheldBy=</varname>,
<varname>PartOf=</varname>, <varname>BoundBy=</varname>,
instead of <varname>Wants=</varname> and similar.
</para>
<xi:include href="version-info.xml" xpointer="v203"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--after</option></term>
<listitem>
<para>With <command>list-dependencies</command>, show the
units that are ordered before the specified unit. In other
words, recursively list units following the
<varname>After=</varname> dependency.</para>
<para>Note that any <varname>After=</varname> dependency is
automatically mirrored to create a
<varname>Before=</varname> dependency. Temporal dependencies
may be specified explicitly, but are also created implicitly
for units which are <varname>WantedBy=</varname> targets
(see
<citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>),
and as a result of other directives (for example
<varname>RequiresMountsFor=</varname>). Both explicitly
and implicitly introduced dependencies are shown with
<command>list-dependencies</command>.</para>
<para>When passed to the <command>list-jobs</command> command, for each printed job show which other jobs are
waiting for it. May be combined with <option>--before</option> to show both the jobs waiting for each job as
well as all jobs each job is waiting for.</para>
<xi:include href="version-info.xml" xpointer="v203"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--before</option></term>
<listitem>
<para>With <command>list-dependencies</command>, show the
units that are ordered after the specified unit. In other
words, recursively list units following the
<varname>Before=</varname> dependency.</para>
<para>When passed to the <command>list-jobs</command> command, for each printed job show which other jobs it
is waiting for. May be combined with <option>--after</option> to show both the jobs waiting for each job as
well as all jobs each job is waiting for.</para>
<xi:include href="version-info.xml" xpointer="v212"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--with-dependencies</option></term>
<listitem>
<para>When used with <command>status</command>,
<command>cat</command>, <command>list-units</command>, and
<command>list-unit-files</command>, those commands print all
specified units and the dependencies of those units.</para>
<para>Options <option>--reverse</option>,
<option>--after</option>, <option>--before</option>
may be used to change what types of dependencies
are shown.</para>
<xi:include href="version-info.xml" xpointer="v245"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-l</option></term>
<term><option>--full</option></term>
<listitem>
<para>Do not ellipsize unit names, process tree entries,
journal output, or truncate unit descriptions in the output
of <command>status</command>, <command>list-units</command>,
<command>list-jobs</command>, and
<command>list-timers</command>.</para>
<para>Also, show installation targets in the output of
<command>is-enabled</command>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--value</option></term>
<listitem>
<para>When printing properties with <command>show</command>, only print the value, and skip the
property name and <literal>=</literal>. Also see option <option>-P</option> above.</para>
<xi:include href="version-info.xml" xpointer="v230"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--show-types</option></term>
<listitem>
<para>When showing sockets, show the type of the socket.</para>
<xi:include href="version-info.xml" xpointer="v202"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--job-mode=</option></term>
<listitem>
<para>When queuing a new job, this option controls how to deal with
already queued jobs. It takes one of <literal>fail</literal>,
<literal>lenient</literal>,
<literal>replace</literal>,
<literal>replace-irreversibly</literal>,
<literal>isolate</literal>,
<literal>ignore-dependencies</literal>,
<literal>ignore-requirements</literal>,
<literal>flush</literal>,
<literal>triggering</literal>, or
<literal>restart-dependencies</literal>. Defaults to
<literal>replace</literal>, except when the
<command>isolate</command> command is used which implies the
<literal>isolate</literal> job mode.</para>
<para>If <literal>fail</literal> is specified and a requested operation on weak dependencies
conflicts with a pending job (more specifically: causes an already pending start job to be reversed
into a stop job or vice versa), cause the operation to fail.</para>
<para>If <literal>lenient</literal> is specified and a requested operation conflicts with any
active/activating unit, cause the operation to fail.</para>
<para>If <literal>replace</literal> (the default) is
specified, any conflicting pending job will be replaced, as
necessary.</para>
<para>If <literal>replace-irreversibly</literal> is specified,
operate like <literal>replace</literal>, but also mark the new
jobs as irreversible. This prevents future conflicting
transactions from replacing these jobs (or even being enqueued
while the irreversible jobs are still pending). Irreversible
jobs can still be cancelled using the <command>cancel</command>
command. This job mode should be used on any transaction which
pulls in <filename>shutdown.target</filename>.</para>
<para><literal>isolate</literal> is only valid for start
operations and causes all other units to be stopped when the
specified unit is started. This mode is always used when the
<command>isolate</command> command is used.</para>
<para><literal>flush</literal> will cause all queued jobs to
be canceled when the new job is enqueued.</para>
<para>If <literal>ignore-dependencies</literal> is specified,
then all unit dependencies are ignored for this new job and
the operation is executed immediately. If passed, no required
units of the unit passed will be pulled in, and no ordering
dependencies will be honored. This is mostly a debugging and
rescue tool for the administrator and should not be used by
applications.</para>
<para><literal>ignore-requirements</literal> is similar to
<literal>ignore-dependencies</literal>, but only causes the
requirement dependencies to be ignored, the ordering
dependencies will still be honored.</para>
<para><literal>triggering</literal> may only be used with
<command>systemctl stop</command>. In this mode, the specified
unit and any active units that trigger it are stopped. See the
discussion of
<varname>Triggers=</varname> in <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
for more information about triggering units.</para>
<para><literal>restart-dependencies</literal> may only be used with
<command>systemctl start</command>. In this mode, dependencies of
the specified unit will receive restart propagation, as if a restart
job had been enqueued for the unit.</para>
<xi:include href="version-info.xml" xpointer="v209"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-T</option></term>
<term><option>--show-transaction</option></term>
<listitem>
<para>When enqueuing a unit job (for example as effect of a <command>systemctl start</command>
invocation or similar), show brief information about all jobs enqueued, covering both the requested
job and any added because of unit dependencies. Note that the output will only include jobs
immediately part of the transaction requested. It is possible that service start-up program code
run as effect of the enqueued jobs might request further jobs to be pulled in. This means that
completion of the listed jobs might ultimately entail more jobs than the listed ones.</para>
<xi:include href="version-info.xml" xpointer="v242"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--fail</option></term>
<listitem>
<para>Shorthand for <option>--job-mode=</option>fail.</para>
<para>When used with the <command>kill</command> command,
if no units were killed, the operation results in an error.
</para>
<xi:include href="version-info.xml" xpointer="v227"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--check-inhibitors=</option></term>
<listitem>
<para>When system shutdown or sleep state is requested, this option controls checking of inhibitor
locks. It takes one of <literal>auto</literal>, <literal>yes</literal>, and <literal>no</literal>.
Defaults to <literal>auto</literal>, which means logind will perform the check and respect active
inhibitor locks, but <command>systemctl</command> will only do a client-side check for interactive
invocations (i.e. from a TTY), so that a more friendly and informative error can be returned to
users. <literal>no</literal> disables the checks both in <command>systemctl</command> and
<citerefentry><refentrytitle>systemd-logind</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
</para>
<para>Applications can establish inhibitor locks to prevent certain important operations (such as
CD burning) from being interrupted by system shutdown or sleep. Any user may take these locks and
privileged users may override these locks. If any locks are taken, shutdown and sleep state
requests will normally fail (unless explicitly overridden with <literal>no</literal>).</para>
<para>Option <option>--force</option> provides another way to override inhibitors.</para>
<xi:include href="version-info.xml" xpointer="v248"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-i</option></term>
<listitem>
<para>Shortcut for <option>--check-inhibitors=no</option>.</para>
<xi:include href="version-info.xml" xpointer="v198"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--dry-run</option></term>
<listitem>
<para>Just print what would be done. Currently supported by verbs
<command>halt</command>, <command>poweroff</command>, <command>reboot</command>,
<command>kexec</command>, <command>suspend</command>, <command>hibernate</command>,
<command>hybrid-sleep</command>, <command>suspend-then-hibernate</command>,
<command>default</command>, <command>rescue</command>,
<command>emergency</command>, and <command>exit</command>.</para>
<xi:include href="version-info.xml" xpointer="v236"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-q</option></term>
<term><option>--quiet</option></term>
<listitem>
<para>Suppress printing of the results of various commands
and also the hints about truncated log lines. This does not
suppress output of commands for which the printed output is
the only result (like <command>show</command>). Errors are
always printed.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-v</option></term>
<term><option>--verbose</option></term>
<listitem>
<para>Display unit log output while executing unit operations.</para>
<xi:include href="version-info.xml" xpointer="v258"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--no-warn</option></term>
<listitem>
<para>Do not generate the warnings shown by default in the following cases:
<itemizedlist>
<listitem>
<para>when <command>systemctl</command> is invoked without procfs mounted on
<filename>/proc/</filename>,</para>
</listitem>
<listitem>
<para>when using <command>enable</command> or <command>disable</command> on units without
install information (i.e. do not have or have an empty [Install] section),</para>
</listitem>
<listitem>
<para>when using <command>disable</command> combined with <option>--user</option> on units
that are enabled in global scope,</para>
</listitem>
<listitem>
<para>when a <command>stop</command>-ped, <command>disable</command>-d, or <command>mask</command>-ed
unit still has active triggering units,</para>
</listitem>
<listitem>
<para>when a unit file is changed and requires <command>daemon-reload</command>.</para>
</listitem>
</itemizedlist>
</para>
<xi:include href="version-info.xml" xpointer="v253"/>
</listitem>
</varlistentry>
<varlistentry>
<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>systemctl</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>When used with <command>start</command> or <command>restart</command>, synchronously wait for
started units to terminate again. This option may not be combined with <option>--no-block</option>.
Note that this will wait forever if any given unit never terminates (by itself or by getting
stopped explicitly); particularly services which use <literal>RemainAfterExit=yes</literal>.</para>
<para>When used with <command>is-system-running</command>, wait until the boot process is completed
before returning.</para>
<para>When used with <command>kill</command>, wait until the signalled units terminate. Note that
this will wait forever if any given unit never terminates.</para>
<xi:include href="version-info.xml" xpointer="v232"/>
</listitem>
</varlistentry>
<xi:include href="user-system-options.xml" xpointer="user" />
<xi:include href="user-system-options.xml" xpointer="system" />
<varlistentry>
<term><option>--failed</option></term>
<listitem>
<para>List units in failed state. This is equivalent to
<option>--state=failed</option>.</para>
<xi:include href="version-info.xml" xpointer="v233"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--no-wall</option></term>
<listitem>
<para>Do not send wall message before halt, power-off and reboot.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--global</option></term>
<listitem>
<para>When used with <command>enable</command> and
<command>disable</command>, operate on the global user
configuration directory, thus enabling or disabling a unit
file globally for all future logins of all users.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--no-reload</option></term>
<listitem>
<para>When used with <command>enable</command>, <command>disable</command>, <command>preset</command>,
<command>mask</command>, or <command>unmask</command>, do not implicitly reload daemon configuration
after executing the changes.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--kill-whom=</option></term>
<listitem>
<para>When used with <command>kill</command>, choose which processes to send a UNIX process signal
to. Must be one of <option>main</option>, <option>control</option>, <option>cgroup</option> or
<option>all</option> to select whether to kill only the main process, the control process, all
processes in the unit's control group or all processes of the unit. The main process of the unit is
the one that defines the life-time of it. A control process of a unit is one that is invoked by the
manager to induce state changes of it. For example, all processes started due to the
<varname>ExecStartPre=</varname>, <varname>ExecStop=</varname> or <varname>ExecReload=</varname>
settings of service units are control processes. Note that there is only one control process per
unit at a time, as only one state change is executed at a time. For services of type
<varname>Type=forking</varname>, the initial process started by the manager for
<varname>ExecStart=</varname> is a control process, while the process ultimately forked off by that
one is then considered the main process of the unit (if it can be determined). This is different
for service units of other types, where the process forked off by the manager for
<varname>ExecStart=</varname> is always the main process itself. A service unit consists of zero or
one main process, zero or one control process plus any number of additional processes part of the
unit's control group. Not all unit types manage processes of these types however. For example, for
mount units, control processes are defined (which are the invocations of
<filename>&MOUNT_PATH;</filename> and <filename>&UMOUNT_PATH;</filename>), but no main process is
defined. If omitted, defaults to <option>all</option>, except if <option>--kill-subgroup=</option>
is used in which case defaults to <option>cgroup</option>.</para>
<xi:include href="version-info.xml" xpointer="v252"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--kill-value=<replaceable>INT</replaceable></option></term>
<listitem><para>If used with the <command>kill</command> command, enqueues a signal along with the
specified integer value parameter to the specified process(es). This operation is only available for
POSIX Realtime Signals (i.e. <option>--signal=SIGRTMIN+…</option> or
<option>--signal=SIGRTMAX-…</option>), and ensures the signals are generated via the <citerefentry
project='man-pages'><refentrytitle>sigqueue</refentrytitle><manvolnum>3</manvolnum></citerefentry>
system call, rather than <citerefentry
project='man-pages'><refentrytitle>kill</refentrytitle><manvolnum>3</manvolnum></citerefentry>. The
specified value must be a 32-bit signed integer, and may be specified either in decimal, in
hexadecimal (if prefixed with <literal>0x</literal>), octal (if prefixed with <literal>0o</literal>)
or binary (if prefixed with <literal>0b</literal>)</para>
<para>If this option is used the signal will only be enqueued on the control or main process of the
unit, never on other processes belonging to the unit, i.e. <option>--kill-whom=all</option> will only
affect main and control processes but no other processes.</para>
<xi:include href="version-info.xml" xpointer="v254"/></listitem>
</varlistentry>
<varlistentry>
<term><option>--kill-subgroup=<replaceable>PATH</replaceable></option></term>
<listitem><para>Takes a control group sub-path to send signals to, for use with the
<command>kill</command> command. By default the chosen signal is delivered to all processes of the
unit's cgroups (as well as the main/control processes (if outside) – subject to
<option>--kill-whom=</option>). But with this option a subgroup can be selelected instead. This
functionality is only available if <literal>cgroup</literal> or <literal>cgroup-fail</literal> are
used with <option>--kill-whom=</option>, and in fact the former is the default if
<option>--kill-subgroup=</option> is used.</para>
<para>The specified path may, but doesn't have to be prefixed with a slash, and its absence or
presence has no effect, the path is either way taken relative to the unit's main control group
path.</para>
<para>This functionality is only available on units where control group delegation is enabled (see
<varname>Delegate=</varname> in
<member><citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>).</para>
<xi:include href="version-info.xml" xpointer="v258"/></listitem>
</varlistentry>
<xi:include href="standard-options.xml" xpointer="signal" />
<varlistentry>
<term><option>--what=</option></term>
<listitem>
<para>Select what type of per-unit resources to remove when the <command>clean</command> command is
invoked, see above. Takes one of <constant>configuration</constant>, <constant>state</constant>,
<constant>cache</constant>, <constant>logs</constant>, <constant>runtime</constant>,
<constant>fdstore</constant> to select the type of resource. This option may be specified more than
once, in which case all specified resource types are removed. Also accepts the special value
<constant>all</constant> as a shortcut for specifying all six resource types. If this option is not
specified defaults to the combination of <constant>cache</constant>, <constant>runtime</constant>
and <constant>fdstore</constant>, i.e. the three kinds of resources that are generally considered
to be redundant and can be reconstructed on next invocation. The empty argument can be used to
reset to this default.</para>
<para>Note that the explicit removal of the <constant>fdstore</constant> resource type is only
useful if the <varname>FileDescriptorStorePreserve=</varname> option is enabled, since the file
descriptor store is otherwise cleaned automatically when the unit is stopped.</para>
<xi:include href="version-info.xml" xpointer="v243"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-f</option></term>
<term><option>--force</option></term>
<listitem>
<para>When used with <command>enable</command>, overwrite any existing conflicting symlinks.</para>
<para>When used with <command>edit</command>, create all of the specified units which do not already exist.</para>
<para>When used with <command>suspend</command>, <command>hibernate</command>, <command>hybrid-sleep</command>,
or <command>suspend-then-hibernate</command>, the error returned by <command>systemd-logind</command>
will be ignored, and the operation will be performed directly through starting the corresponding units.
</para>
<para>When used with <command>halt</command>, <command>poweroff</command>, <command>reboot</command>,
or <command>kexec</command>, execute the selected operation without shutting down all units. However,
all processes will be killed forcibly and all file systems are unmounted or remounted read-only.
This is hence a drastic but relatively safe option to request an immediate reboot. If <option>--force</option>
is specified twice for these operations (with the exception of <command>kexec</command>), they will
be executed immediately, without terminating any processes or unmounting any file systems.</para>
<warning>
<para>Specifying <option>--force</option> twice with any of these operations might result in data loss.
Note that when <option>--force</option> is specified twice the selected operation is executed by
<command>systemctl</command> itself, and the system manager is not contacted. This means the command
should succeed even when the system manager has crashed.</para>
</warning>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--message=</option></term>
<listitem>
<para>When used with <command>halt</command>, <command>poweroff</command> or <command>reboot</command>, set a
short message explaining the reason for the operation. The message will be logged together with the default
shutdown message.</para>
<xi:include href="version-info.xml" xpointer="v225"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--now</option></term>
<listitem>
<para>When used with <command>enable</command>, <command>disable</command>, <command>mask</command>,
or <command>reenable</command>, also start/stop/try-restart the units after the specified
unit file operations succeed.</para>
<xi:include href="version-info.xml" xpointer="v220"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--root=</option></term>
<listitem>
<para>When used with
<command>enable</command>/<command>disable</command>/<command>is-enabled</command>
(and related commands), use the specified root path when looking for unit
files. If this option is present, <command>systemctl</command> will operate on
the file system directly, instead of communicating with the <command>systemd</command>
daemon to carry out changes.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--image=<replaceable>image</replaceable></option></term>
<listitem><para>Takes a path to a disk image file or block device node. If specified, all operations
are applied to file system in the indicated disk image. This option is similar to
<option>--root=</option>, but operates on file systems stored in disk images or block devices. The
disk image should either contain just a file system or a set of file systems within a GPT partition
table, following the <ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">UAPI.2 Discoverable Partitions
Specification</ulink>. For further information on supported disk images, see
<citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
switch of the same name.</para>
<xi:include href="version-info.xml" xpointer="v252"/></listitem>
</varlistentry>
<xi:include href="standard-options.xml" xpointer="image-policy-open" />
<varlistentry>
<term><option>--runtime</option></term>
<listitem>
<para>When used with <command>enable</command>,
<command>disable</command>, <command>edit</command>,
(and related commands), make changes only temporarily, so
that they are lost on the next reboot. This will have the
effect that changes are not made in subdirectories of
<filename>/etc/</filename> but in <filename>/run/</filename>,
with identical immediate effects, however, since the latter
is lost on reboot, the changes are lost too.</para>
<para>Similarly, when used with
<command>set-property</command>, make changes only
temporarily, so that they are lost on the next
reboot.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--preset-mode=</option></term>
<listitem>
<para>Takes one of <literal>full</literal> (the default),
<literal>enable-only</literal>,
<literal>disable-only</literal>. When used with the
<command>preset</command> or <command>preset-all</command>
commands, controls whether units shall be disabled and
enabled according to the preset rules, or only enabled, or
only disabled.</para>
<xi:include href="version-info.xml" xpointer="v215"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-n</option></term>
<term><option>--lines=</option></term>
<listitem>
<para>When used with <command>status</command>, controls the number of journal lines to show,
counting from the most recent ones. Takes a positive integer argument, or 0 to disable journal
output. Defaults to 10.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-o</option></term>
<term><option>--output=</option></term>
<listitem>
<para>When used with <command>status</command>, controls the
formatting of the journal entries that are shown. For the
available choices, see
<citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
Defaults to <literal>short</literal>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--firmware-setup</option></term>
<listitem>
<para>When used with the <command>reboot</command>, <command>poweroff</command>, or
<command>halt</command> command, indicate to the system's firmware to reboot into the firmware
setup interface for the next boot. Note that this functionality is not available on all systems.
</para>
<xi:include href="version-info.xml" xpointer="v220"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--boot-loader-menu=<replaceable>timeout</replaceable></option></term>
<listitem>
<para>When used with the <command>reboot</command>, <command>poweroff</command>, or
<command>halt</command> command, indicate to the system's boot loader to show the boot loader menu
on the following boot. Takes a time value as parameter — indicating the menu timeout. Pass zero
in order to disable the menu timeout. Note that not all boot loaders support this functionality.
</para>
<xi:include href="version-info.xml" xpointer="v242"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--boot-loader-entry=<replaceable>ID</replaceable></option></term>
<listitem>
<para>When used with the <command>reboot</command>, <command>poweroff</command>, or
<command>halt</command> command, indicate to the system's boot loader to boot into a specific
boot loader entry on the following boot. Takes a boot loader entry identifier as argument,
or <literal>help</literal> in order to list available entries. Note that not all boot loaders
support this functionality.</para>
<xi:include href="version-info.xml" xpointer="v242"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--reboot-argument=</option></term>
<listitem>
<para>This switch is used with <command>reboot</command>. The value is architecture and firmware
specific. As an example, <literal>recovery</literal> might be used to trigger system recovery, and
<literal>fota</literal> might be used to trigger a <quote>firmware over the air</quote>
update.</para>
<xi:include href="version-info.xml" xpointer="v246"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--kernel-cmdline=</option></term>
<listitem>
<para>When used with <command>kexec</command>, append the specified string to the kernel command
line options of the kexec kernel. The kernel command line is taken from the boot loader entry of
the currently booted kernel (as selected automatically when no kexec kernel is preloaded, see
<command>kexec</command> above). This string is appended, separated from the existing
options by a single space. This option may be specified more than once, in which case the
strings are appended in the order given. <command>systemctl kexec</command> will fail if this
option is specified when a kexec kernel is already loaded.</para>
<para>The kexec kernel command line is assembled in a fixed order, independent of the order in
which the options are specified on the command line: first the command line from the boot loader
entry, then the command line of the currently running kernel (if
<option>--kernel-cmdline-reuse</option> is used), and finally the strings specified with
<option>--kernel-cmdline=</option>. Afterwards, arguments that are exactly identical and appear
more than once are removed, keeping the last occurrence. Note that only byte-for-byte identical
arguments are deduplicated: for example <literal>foo=bar</literal> and
<literal>foo=quux</literal> are both kept, as they are not identical (the latter takes effect, as
the kernel uses the last assignment of a given parameter).</para>
<xi:include href="version-info.xml" xpointer="v261"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--kernel-cmdline-reuse</option></term>
<listitem>
<para>Like <option>--kernel-cmdline=</option>, but instead of taking the string to append as an
argument, the command line of the currently running kernel is reused. This is useful to boot the
kexec kernel with the same command line options the running system was booted with, including any
modifications applied at boot time.
As with <option>--kernel-cmdline=</option>, the reused command line is added to the command line
taken from the boot loader entry, and <command>systemctl kexec</command> will fail if this option
is specified when a kexec kernel is already loaded. This option may be combined with
<option>--kernel-cmdline=</option>; see <option>--kernel-cmdline=</option> above for the order in
which the various command line sources are combined and deduplicated.</para>
<xi:include href="version-info.xml" xpointer="v262"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--plain</option></term>
<listitem>
<para>When used with <command>list-dependencies</command>,
<command>list-units</command> or <command>list-machines</command>,
the output is printed as a list instead of a tree, and the bullet
circles are omitted.</para>
<xi:include href="version-info.xml" xpointer="v203"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--timestamp=</option></term>
<listitem>
<para>Change the format of printed timestamps. The following values may be used:
</para>
<variablelist>
<varlistentry>
<term><option>pretty</option> (this is the default)</term>
<listitem><para><literal>Day YYYY-MM-DD HH:MM:SS TZ</literal></para>
<xi:include href="version-info.xml" xpointer="v248"/></listitem>
</varlistentry>
</variablelist>
<variablelist>
<varlistentry>
<term><option>unix</option></term>
<listitem><para><literal>@seconds-since-the-epoch</literal></para>
<xi:include href="version-info.xml" xpointer="v251"/></listitem>
</varlistentry>
</variablelist>
<variablelist>
<varlistentry>
<term><option>us</option></term>
<term><option>μs</option></term>
<listitem><para><literal>Day YYYY-MM-DD HH:MM:SS.UUUUUU TZ</literal></para>
<xi:include href="version-info.xml" xpointer="v248"/></listitem>
</varlistentry>
</variablelist>
<variablelist>
<varlistentry>
<term><option>utc</option></term>
<listitem><para><literal>Day YYYY-MM-DD HH:MM:SS UTC</literal></para>
<xi:include href="version-info.xml" xpointer="v248"/></listitem>
</varlistentry>
</variablelist>
<variablelist>
<varlistentry>
<term><option>us+utc</option></term>
<term><option>μs+utc</option></term>
<listitem><para><literal>Day YYYY-MM-DD HH:MM:SS.UUUUUU UTC</literal></para>
<xi:include href="version-info.xml" xpointer="v248"/></listitem>
</varlistentry>
</variablelist>
<xi:include href="version-info.xml" xpointer="v247"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--mkdir</option></term>
<listitem><para>When used with <command>bind</command>, creates the destination file or directory before
applying the bind mount. Note that even though the name of this option suggests that it is suitable only for
directories, this option also creates the destination file node to mount over if the object to mount is not
a directory, but a regular file, device node, socket or FIFO.</para>
<xi:include href="version-info.xml" xpointer="v248"/></listitem>
</varlistentry>
<varlistentry>
<term><option>--read-only</option></term>
<listitem><para>When used with <command>bind</command>, creates a read-only bind mount.</para>
<xi:include href="version-info.xml" xpointer="v248"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--drop-in=<replaceable>NAME</replaceable></option></term>
<listitem><para>When used with <command>edit</command>, use <replaceable>NAME</replaceable> as the
drop-in file name instead of <filename>override.conf</filename>.</para>
<xi:include href="version-info.xml" xpointer="v253"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--when=</option></term>
<listitem>
<para>When used with <command>halt</command>, <command>poweroff</command>, <command>reboot</command>
or <command>kexec</command>, schedule the action to be performed at the given timestamp,
which should adhere to the syntax documented in
<citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>
section "PARSING TIMESTAMPS". Specially, if <literal>show</literal> is given, the currently scheduled
action will be shown, which can be canceled by passing an empty string or <literal>cancel</literal>.
<literal>auto</literal> will schedule the action according to maintenance window or one minute in
the future.</para>
<para>The specified timestamp is a lower bound only: it declares the earliest point in time the
requested action may take place, i.e. the action is executed as soon as possible, but not before the
given timestamp. It is <emphasis>not</emphasis> a condition that is checked, and specifying a
timestamp in the past is not an error: the action is then executed immediately. This is intentional,
as the alternative would be racy and surprising — consider <option>--when=now</option>, which by the
time the request is processed necessarily refers to the past, or
<option>--when=+50ms</option>, which might well already have elapsed due to scheduling latencies
before the request is dispatched. In both cases the requested action is still carried out, as
the user asked for it.</para>
<para>If a timestamp in the past shall not result in the action being executed, this must be checked
for explicitly before invoking <command>systemctl</command>.</para>
<xi:include href="version-info.xml" xpointer="v254"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--stdin</option></term>
<listitem>
<para>When used with <command>edit</command>, the contents of the file will be read from standard
input and the editor will not be launched. In this mode, the old contents of the file are
completely replaced. This is useful to "edit" unit files from scripts:</para>
<programlisting>$ systemctl edit --drop-in=limits.conf --stdin some-service.service <<EOF
[Unit]
AllowedCPUs=7,11
EOF
</programlisting>
<para>Multiple drop-ins may be "edited" in this mode; the same contents will be written to all of
them.</para>
<xi:include href="version-info.xml" xpointer="v256"/>
</listitem>
</varlistentry>
<xi:include href="user-system-options.xml" xpointer="host" />
<xi:include href="user-system-options.xml" xpointer="machine" />