-<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+<?xml version='1.0'?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
-
-<!--
- SPDX-License-Identifier: LGPL-2.1+
--->
+<!-- SPDX-License-Identifier: LGPL-2.1+ -->
<refentry id="machinectl" conditional='ENABLE_MACHINED'
xmlns:xi="http://www.w3.org/2001/XInclude">
</itemizedlist>
<para>Machines are identified by names that follow the same rules
- as UNIX and DNS host names. For details, see below.</para>
+ as UNIX and DNS hostnames. For details, see below.</para>
<para>Machines are instantiated from disk or file system images that
frequently — but not necessarily — carry the same name as machines running
top-level directories <filename>/usr</filename>,
<filename>/etc</filename>, and so on.</para></listitem>
- <listitem><para>btrfs subvolumes containing OS trees, similar to
- normal directory trees.</para></listitem>
+ <listitem><para>btrfs subvolumes containing OS trees, similar to regular directory trees.</para></listitem>
+
+ <listitem><para>Binary "raw" disk image files containing MBR or GPT partition tables and Linux file
+ systems.</para></listitem>
- <listitem><para>Binary "raw" disk images containing MBR or GPT
- partition tables and Linux file system partitions.</para></listitem>
+ <listitem><para>Similarly, block devices containing MBR or GPT partition tables and file systems.</para></listitem>
<listitem><para>The file system tree of the host OS itself.</para></listitem>
</itemizedlist>
</refsect1>
- <refsect1>
- <title>Options</title>
-
- <para>The following options are understood:</para>
-
- <variablelist>
- <varlistentry>
- <term><option>-p</option></term>
- <term><option>--property=</option></term>
-
- <listitem><para>When showing machine or image properties,
- limit the output to certain properties as specified by the
- argument. If not specified, all set properties are shown. The
- argument should be a property name, such as
- <literal>Name</literal>. If specified more than once, all
- properties with the specified names are
- shown.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>-a</option></term>
- <term><option>--all</option></term>
-
- <listitem><para>When showing machine or image properties, show
- all properties regardless of whether they are set or
- not.</para>
-
- <para>When listing VM or container images, do not suppress
- images beginning in a dot character
- (<literal>.</literal>).</para>
-
- <para>When cleaning VM or container images, remove all images, not just hidden ones.</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>.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>-l</option></term>
- <term><option>--full</option></term>
-
- <listitem><para>Do not ellipsize process tree entries.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--kill-who=</option></term>
-
- <listitem><para>When used with <command>kill</command>, choose
- which processes to kill. Must be one of
- <option>leader</option>, or <option>all</option> to select
- whether to kill only the leader process of the machine or all
- processes of the machine. If omitted, defaults to
- <option>all</option>.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>-s</option></term>
- <term><option>--signal=</option></term>
-
- <listitem><para>When used with <command>kill</command>, choose
- which signal to send to selected processes. Must be one of the
- well-known signal specifiers, such as
- <constant>SIGTERM</constant>, <constant>SIGINT</constant> or
- <constant>SIGSTOP</constant>. If omitted, defaults to
- <constant>SIGTERM</constant>.</para></listitem>
- </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 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>-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>--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></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--read-only</option></term>
-
- <listitem><para>When used with <command>bind</command>, creates 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>
- <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.
- 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>--verify=</option></term>
-
- <listitem><para>When downloading a container or VM image,
- specify whether the image shall be verified before it is made
- available. Takes one of <literal>no</literal>,
- <literal>checksum</literal> and <literal>signature</literal>.
- If <literal>no</literal>, no verification is done. If
- <literal>checksum</literal> is specified, the download is
- checked for integrity after the transfer is complete, but no
- signatures are verified. If <literal>signature</literal> is
- specified, the checksum is verified and the image's signature
- is checked against a local keyring of trustable vendors. It is
- strongly recommended to set this option to
- <literal>signature</literal> if the server and protocol
- support this. Defaults to
- <literal>signature</literal>.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--force</option></term>
-
- <listitem><para>When downloading a container or VM image, and
- a local copy by the specified local machine name already
- exists, delete it first and replace it by the newly downloaded
- image.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--format=</option></term>
-
- <listitem><para>When used with the <option>export-tar</option>
- or <option>export-raw</option> commands, specifies the
- compression format to use for the resulting file. Takes one of
- <literal>uncompressed</literal>, <literal>xz</literal>,
- <literal>gzip</literal>, <literal>bzip2</literal>. By default,
- the format is determined automatically from the image file
- 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>
-
- <varlistentry>
- <term><option>-q</option></term>
- <term><option>--quiet</option></term>
-
- <listitem><para>Suppresses additional informational output while running.</para></listitem>
- </varlistentry>
-
- <xi:include href="user-system-options.xml" xpointer="host" />
-
- <varlistentry>
- <term><option>-M</option></term>
- <term><option>--machine=</option></term>
-
- <listitem><para>Connect to
- <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
- running in a local container, to perform the specified operation within
- the container.</para></listitem>
- </varlistentry>
-
- <xi:include href="standard-options.xml" xpointer="no-pager" />
- <xi:include href="standard-options.xml" xpointer="no-legend" />
- <xi:include href="standard-options.xml" xpointer="no-ask-password" />
- <xi:include href="standard-options.xml" xpointer="help" />
- <xi:include href="standard-options.xml" xpointer="version" />
- </variablelist>
- </refsect1>
-
<refsect1>
<title>Commands</title>
<listitem><para>Copies files or directories from a container
into the host system. Takes a container name, followed by the
- source path in the container the destination path on the host.
+ source path in the container and the destination path on the host.
If the destination path is omitted, the same as the source path
is used.</para>
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
+ <para>Note that this command leaves hostname, 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
units. If the size limit shall be disabled, specify
<literal>-</literal> as size.</para>
- <para>Note that per-container size limits are only supported
- on btrfs file systems. Also note that, if
- <command>set-limit</command> is invoked without an image
- parameter, and <filename>/var/lib/machines</filename> is
- empty, and the directory is not located on btrfs, a btrfs
- loopback file is implicitly created as
- <filename>/var/lib/machines.raw</filename> with the given
- size, and mounted to
- <filename>/var/lib/machines</filename>. The size of the
- loopback may later be readjusted with
- <command>set-limit</command>, as well. If such a
- loopback-mounted <filename>/var/lib/machines</filename>
- directory is used, <command>set-limit</command> without an image
- name alters both the quota setting within the file system as
- well as the loopback file and file system size
- itself.</para></listitem>
+ <para>Note that per-container size limits are only supported on btrfs file systems.</para></listitem>
</varlistentry>
<varlistentry>
server, under the same URL as the <filename>.tar</filename> file.
With <option>--verify=checksum</option>, only the SHA256 checksum
for the file is verified, based on the <filename>.sha256</filename>
- suffixed file or the<filename>SHA256SUMS</filename> file.
+ suffixed file or the <filename>SHA256SUMS</filename> file.
With <option>--verify=signature</option>, the sha checksum file is
first verified with the inline signature in the
<filename>.sha256</filename> file or the detached GPG signature file
image is read from standard input, in which case the second
argument is mandatory.</para>
- <para>Both <command>pull-tar</command> and <command>pull-raw</command>
- will resize <filename>/var/lib/machines.raw</filename> and the
- filesystem therein as necessary. Optionally, the
- <option>--read-only</option> switch may be used to create a
- read-only container or VM image. No cryptographic validation
- is done when importing the images.</para>
+ <para>Optionally, the <option>--read-only</option> switch may be used to create a read-only container or VM
+ image. No cryptographic validation is done when importing the images.</para>
<para>Much like image downloads, ongoing imports may be listed
with <command>list-transfers</command> and aborted with
<command>cancel-transfer</command>.</para></listitem>
</varlistentry>
+ <varlistentry>
+ <term><command>import-fs</command> <replaceable>DIRECTORY</replaceable> [<replaceable>NAME</replaceable>]</term>
+
+ <listitem><para>Imports a container image stored in a local directory into
+ <filename>/var/lib/machines/</filename>, operates similar to <command>import-tar</command> or
+ <command>import-raw</command>, but the first argument is the source directory. If supported, this command will
+ create btrfs snapshot or subvolume for the new image.</para></listitem>
+ </varlistentry>
+
<varlistentry>
<term><command>export-tar</command> <replaceable>NAME</replaceable> [<replaceable>FILE</replaceable>]</term>
<term><command>export-raw</command> <replaceable>NAME</replaceable> [<replaceable>FILE</replaceable>]</term>
</refsect1>
+ <refsect1>
+ <title>Options</title>
+
+ <para>The following options are understood:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><option>-p</option></term>
+ <term><option>--property=</option></term>
+
+ <listitem><para>When showing machine or image properties,
+ limit the output to certain properties as specified by the
+ argument. If not specified, all set properties are shown. The
+ argument should be a property name, such as
+ <literal>Name</literal>. If specified more than once, all
+ properties with the specified names are
+ shown.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-a</option></term>
+ <term><option>--all</option></term>
+
+ <listitem><para>When showing machine or image properties, show
+ all properties regardless of whether they are set or
+ not.</para>
+
+ <para>When listing VM or container images, do not suppress
+ images beginning in a dot character
+ (<literal>.</literal>).</para>
+
+ <para>When cleaning VM or container images, remove all images, not just hidden ones.</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>.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-l</option></term>
+ <term><option>--full</option></term>
+
+ <listitem><para>Do not ellipsize process tree entries or table. This implies
+ <option>--max-addresses=full</option>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--kill-who=</option></term>
+
+ <listitem><para>When used with <command>kill</command>, choose
+ which processes to kill. Must be one of
+ <option>leader</option>, or <option>all</option> to select
+ whether to kill only the leader process of the machine or all
+ processes of the machine. If omitted, defaults to
+ <option>all</option>.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-s</option></term>
+ <term><option>--signal=</option></term>
+
+ <listitem><para>When used with <command>kill</command>, choose
+ which signal to send to selected processes. Must be one of the
+ well-known signal specifiers, such as
+ <constant>SIGTERM</constant>, <constant>SIGINT</constant> or
+ <constant>SIGSTOP</constant>. If omitted, defaults to
+ <constant>SIGTERM</constant>.</para></listitem>
+ </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 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>-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>--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></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--read-only</option></term>
+
+ <listitem><para>When used with <command>bind</command>, creates 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>
+ <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.
+ 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>--verify=</option></term>
+
+ <listitem><para>When downloading a container or VM image,
+ specify whether the image shall be verified before it is made
+ available. Takes one of <literal>no</literal>,
+ <literal>checksum</literal> and <literal>signature</literal>.
+ If <literal>no</literal>, no verification is done. If
+ <literal>checksum</literal> is specified, the download is
+ checked for integrity after the transfer is complete, but no
+ signatures are verified. If <literal>signature</literal> is
+ specified, the checksum is verified and the image's signature
+ is checked against a local keyring of trustable vendors. It is
+ strongly recommended to set this option to
+ <literal>signature</literal> if the server and protocol
+ support this. Defaults to
+ <literal>signature</literal>.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--force</option></term>
+
+ <listitem><para>When downloading a container or VM image, and
+ a local copy by the specified local machine name already
+ exists, delete it first and replace it by the newly downloaded
+ image.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--format=</option></term>
+
+ <listitem><para>When used with the <option>export-tar</option>
+ or <option>export-raw</option> commands, specifies the
+ compression format to use for the resulting file. Takes one of
+ <literal>uncompressed</literal>, <literal>xz</literal>,
+ <literal>gzip</literal>, <literal>bzip2</literal>. By default,
+ the format is determined automatically from the image file
+ 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.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-q</option></term>
+ <term><option>--quiet</option></term>
+
+ <listitem><para>Suppresses additional informational output while running.</para></listitem>
+ </varlistentry>
+
+ <xi:include href="user-system-options.xml" xpointer="host" />
+
+ <varlistentry>
+ <term><option>-M</option></term>
+ <term><option>--machine=</option></term>
+
+ <listitem><para>Connect to
+ <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+ running in a local container, to perform the specified operation within
+ the container.</para></listitem>
+ </varlistentry>
+
+ <xi:include href="standard-options.xml" xpointer="no-pager" />
+ <xi:include href="standard-options.xml" xpointer="no-legend" />
+ <xi:include href="standard-options.xml" xpointer="no-ask-password" />
+ <xi:include href="standard-options.xml" xpointer="help" />
+ <xi:include href="standard-options.xml" xpointer="version" />
+ </variablelist>
+ </refsect1>
+
<refsect1>
<title>Machine and Image Names</title>
<para>The <command>machinectl</command> tool operates on machines
and images whose names must be chosen following strict
- rules. Machine names must be suitable for use as host names
+ rules. Machine names must be suitable for use as hostnames
following a conservative subset of DNS and UNIX/Linux
semantics. Specifically, they must consist of one or more
non-empty label strings, separated by dots. No leading or trailing
<filename>/var/lib/machines/</filename> to make them available for
control with <command>machinectl</command>.</para>
- <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
- <command>set-limit</command> commands notice that
- <filename>/var/lib/machines</filename> is empty and not located on
- btrfs, they will implicitly set up a loopback file
- <filename>/var/lib/machines.raw</filename> containing a btrfs file
- system that is mounted to
- <filename>/var/lib/machines</filename>. The size of this loopback
- file may be controlled dynamically with
- <command>set-limit</command>.</para>
+ <para>Note that some image operations are only supported, efficient or atomic on btrfs file systems.</para>
<para>Disk images are understood by
<citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
projects / thirdparty / systemd.git / blobdiff