<para>When listing VM or container images, do not suppress
images beginning in a dot character
- (<literal>.</literal>).</para></listitem>
+ (<literal>.</literal>).</para>
+
+ <para>When cleaning VM or container images, remove all images, not just hidden ones.</para></listitem>
</varlistentry>
<varlistentry>
<varlistentry>
<term><option>--uid=</option></term>
- <listitem><para>When used with the <command>shell</command>
- command, chooses the user ID to open the interactive shell
- session as. If this switch is not specified, defaults to
- <literal>root</literal>. Note that this switch is not
- supported for the <command>login</command> command (see
- below).</para></listitem>
+ <listitem><para>When used with the <command>shell</command> command, chooses the user ID to
+ open the interactive shell session as. If the argument to the <command>shell</command>
+ command also specifies a user name, this option is ignored. If the name is not specified
+ in either way, <literal>root</literal> will be used by default. Note that this switch is
+ not supported for the <command>login</command> command (see below).</para></listitem>
</varlistentry>
<varlistentry>
- <term><option>--setenv=</option></term>
-
- <listitem><para>When used with the <command>shell</command>
- command, sets an environment variable to pass to the executed
- shell. Takes a pair of environment variable name and value,
- separated by <literal>=</literal> as argument. This switch
- may be used multiple times to set multiple environment
- variables. Note that this switch is not supported for the
- <command>login</command> command (see
- below).</para></listitem>
+ <term><option>-E <replaceable>NAME</replaceable>=<replaceable>VALUE</replaceable></option></term>
+ <term><option>--setenv=<replaceable>NAME</replaceable>=<replaceable>VALUE</replaceable></option></term>
+
+ <listitem><para>When used with the <command>shell</command> command, sets an environment
+ variable to pass to the executed shell. Takes an environment variable name and value,
+ separated by <literal>=</literal>. This switch may be used multiple times to set multiple
+ environment variables. Note that this switch is not supported for the
+ <command>login</command> command (see below).</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--read-only</option></term>
<listitem><para>When used with <command>bind</command>, applies
- a read-only bind mount.</para></listitem>
- </varlistentry>
+ a read-only bind mount.</para>
+ <para>When used with <command>clone</command>, <command>import-raw</command> or <command>import-tar</command> a
+ read-only container or VM image is created.</para></listitem>
+ </varlistentry>
<varlistentry>
<term><option>-n</option></term>
name passed.</para></listitem>
</varlistentry>
+ <varlistentry>
+ <term><option>--max-addresses=</option></term>
+
+ <listitem><para>When used with the <option>list-machines</option>
+ command, limits the number of ip addresses output for every machine.
+ Defaults to 1. All addresses can be requested with <literal>all</literal>
+ as argument to <option>--max-addresses</option> . If the argument to
+ <option>--max-addresses</option> is less than the actual number
+ of addresses,<literal>...</literal>follows the last address.
+ If multiple addresses are to be written for a given machine, every
+ address except the first one is on a new line and is followed by
+ <literal>,</literal> if another address will be output afterwards. </para></listitem>
+ </varlistentry>
+
<xi:include href="user-system-options.xml" xpointer="host" />
<xi:include href="user-system-options.xml" xpointer="machine" />
</varlistentry>
<varlistentry>
- <term><command>status</command> <replaceable>NAME</replaceable>...</term>
+ <term><command>status</command> <replaceable>NAME</replaceable>…</term>
<listitem><para>Show runtime status information about
one or more virtual machines and containers, followed by the
</varlistentry>
<varlistentry>
- <term><command>show</command> [<replaceable>NAME</replaceable>...]</term>
-
- <listitem><para>Show properties of one or more registered
- virtual machines or containers or the manager itself. If no
- argument is specified, properties of the manager will be
- shown. If an NAME is specified, properties of this virtual
- machine or container are shown. By default, empty properties
- are suppressed. Use <option>--all</option> to show those too.
- To select specific properties to show, use
- <option>--property=</option>. This command is intended to be
- used whenever computer-parsable output is required, and does
- not print the cgroup tree or journal entries. Use
- <command>status</command> if you are looking for formatted
- human-readable output.</para></listitem>
+ <term><command>show</command> [<replaceable>NAME</replaceable>…]</term>
+
+ <listitem><para>Show properties of one or more registered virtual machines or containers or the manager
+ itself. If no argument is specified, properties of the manager will be shown. If a NAME is specified,
+ properties of this virtual machine or container are shown. By default, empty properties are suppressed. Use
+ <option>--all</option> to show those too. To select specific properties to show, use
+ <option>--property=</option>. This command is intended to be used whenever computer-parsable output is
+ required, and does not print the control group tree or journal entries. Use <command>status</command> if you
+ are looking for formatted human-readable output.</para></listitem>
</varlistentry>
<varlistentry>
- <term><command>start</command> <replaceable>NAME</replaceable>...</term>
+ <term><command>start</command> <replaceable>NAME</replaceable>…</term>
<listitem><para>Start a container as a system service, using
<citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
<para>To interactively start a container on the command line
with full access to the container's console, please invoke
<command>systemd-nspawn</command> directly. To stop a running
- container use <command>machinectl poweroff</command>, see
- below.</para></listitem>
+ container use <command>machinectl poweroff</command>.</para></listitem>
</varlistentry>
<varlistentry>
</varlistentry>
<varlistentry>
- <term><command>shell</command> [[<replaceable>NAME</replaceable>@]<replaceable>NAME</replaceable> [<replaceable>PATH</replaceable> [<replaceable>ARGUMENTS</replaceable>...]]] </term>
+ <term><command>shell</command> [[<replaceable>NAME</replaceable>@]<replaceable>NAME</replaceable> [<replaceable>PATH</replaceable> [<replaceable>ARGUMENTS</replaceable>…]]] </term>
<listitem><para>Open an interactive shell session in a
container or on the local host. The first argument refers to
</varlistentry>
<varlistentry>
- <term><command>enable</command> <replaceable>NAME</replaceable>...</term>
- <term><command>disable</command> <replaceable>NAME</replaceable>...</term>
+ <term><command>enable</command> <replaceable>NAME</replaceable>…</term>
+ <term><command>disable</command> <replaceable>NAME</replaceable>…</term>
<listitem><para>Enable or disable a container as a system
service to start at system boot, using
</varlistentry>
<varlistentry>
- <term><command>poweroff</command> <replaceable>NAME</replaceable>...</term>
+ <term><command>poweroff</command> <replaceable>NAME</replaceable>…</term>
<listitem><para>Power off one or more containers. This will
trigger a reboot by sending SIGRTMIN+4 to the container's init
process, which causes systemd-compatible init systems to shut
- down cleanly. This operation does not work on containers that
- do not run a
+ down cleanly. Use <command>stop</command> as alias for <command>poweroff</command>.
+ This operation does not work on containers that do not run a
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>-compatible
init system, such as sysvinit. Use
<command>terminate</command> (see below) to immediately
</varlistentry>
<varlistentry>
- <term><command>reboot</command> <replaceable>NAME</replaceable>...</term>
+ <term><command>reboot</command> <replaceable>NAME</replaceable>…</term>
<listitem><para>Reboot one or more containers. This will
trigger a reboot by sending SIGINT to the container's init
</varlistentry>
<varlistentry>
- <term><command>terminate</command> <replaceable>NAME</replaceable>...</term>
+ <term><command>terminate</command> <replaceable>NAME</replaceable>…</term>
<listitem><para>Immediately terminates a virtual machine or
container, without cleanly shutting it down. This kills all
</varlistentry>
<varlistentry>
- <term><command>kill</command> <replaceable>NAME</replaceable>...</term>
+ <term><command>kill</command> <replaceable>NAME</replaceable>…</term>
<listitem><para>Send a signal to one or more processes of the
virtual machine or container. This means processes as seen by
</varlistentry>
<varlistentry>
- <term><command>image-status</command> [<replaceable>NAME</replaceable>...]</term>
+ <term><command>image-status</command> [<replaceable>NAME</replaceable>…]</term>
<listitem><para>Show terse status information about one or
more container or VM images. This function is intended to
</varlistentry>
<varlistentry>
- <term><command>show-image</command> [<replaceable>NAME</replaceable>...]</term>
+ <term><command>show-image</command> [<replaceable>NAME</replaceable>…]</term>
<listitem><para>Show properties of one or more registered
virtual machine or container images, or the manager itself. If
no argument is specified, properties of the manager will be
- shown. If an NAME is specified, properties of this virtual
+ shown. If a NAME is specified, properties of this virtual
machine or container image are shown. By default, empty
properties are suppressed. Use <option>--all</option> to show
those too. To select specific properties to show, use
<varlistentry>
<term><command>clone</command> <replaceable>NAME</replaceable> <replaceable>NAME</replaceable></term>
- <listitem><para>Clones a container or VM image. The
- arguments specify the name of the image to clone and the name
- of the newly cloned image. Note that plain directory container
- images are cloned into subvolume images with this command.
- Note that cloning a container or VM image is optimized for
- btrfs file systems, and might not be efficient on others, due
- to file system limitations.</para>
+ <listitem><para>Clones a container or VM image. The arguments specify the name of the image to clone and the
+ name of the newly cloned image. Note that plain directory container images are cloned into btrfs subvolume
+ images with this command, if the underlying file system supports this. Note that cloning a container or VM
+ image is optimized for file systems that support copy-on-write, and might not be efficient on others, due to
+ file system limitations.</para>
<para>Note that this command leaves host name, machine ID and
all other settings that could identify the instance
unmodified. The original image and the cloned copy will hence
share these credentials, and it might be necessary to manually
- change them in the copy.</para></listitem>
+ change them in the copy.</para>
+
+ <para>If combined with the <option>--read-only</option> switch a read-only cloned image is
+ created.</para></listitem>
</varlistentry>
<varlistentry>
</varlistentry>
<varlistentry>
- <term><command>remove</command> <replaceable>NAME</replaceable>...</term>
+ <term><command>remove</command> <replaceable>NAME</replaceable>…</term>
<listitem><para>Removes one or more container or VM images.
The special image <literal>.host</literal>, which refers to
itself.</para></listitem>
</varlistentry>
+ <varlistentry>
+ <term><command>clean</command></term>
+
+ <listitem><para>Remove hidden VM or container images (or all). This command removes all hidden machine images
+ from <filename>/var/lib/machines</filename>, i.e. those whose name begins with a dot. Use <command>machinectl
+ list-images --all</command> to see a list of all machine images, including the hidden ones.</para>
+
+ <para>When combined with the <option>--all</option> switch removes all images, not just hidden ones. This
+ command effectively empties <filename>/var/lib/machines</filename>.</para>
+
+ <para>Note that commands such as <command>machinectl pull-tar</command> or <command>machinectl
+ pull-raw</command> usually create hidden, read-only, unmodified machine images from the downloaded image first,
+ before cloning a writable working copy of it, in order to avoid duplicate downloads in case of images that are
+ reused multiple times. Use <command>machinectl clean</command> to remove old, hidden images created this
+ way.</para></listitem>
+ </varlistentry>
+
</variablelist></refsect2>
<refsect2><title>Image Transfer Commands</title><variablelist>
</varlistentry>
<varlistentry>
- <term><command>cancel-transfers</command> <replaceable>ID</replaceable>...</term>
+ <term><command>cancel-transfers</command> <replaceable>ID</replaceable>…</term>
<listitem><para>Aborts a download, import or export of the
container or VM image with the specified ID. To list ongoing
<filename>/var/lib/machines/</filename> to make them available for
control with <command>machinectl</command>.</para>
- <para>Note that many image operations are only supported,
+ <para>Note that some image operations are only supported,
efficient or atomic on btrfs file systems. Due to this, if the
<command>pull-tar</command>, <command>pull-raw</command>,
<command>import-tar</command>, <command>import-raw</command> and
projects / thirdparty / systemd.git / blobdiff