machinectl.xml revision 16eb4024887b1b79fc56706fda25eadaecdef2d4
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek<?xml version='1.0'?> <!--*-nxml-*-->
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek This file is part of systemd.
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek Copyright 2013 Zbigniew Jędrzejewski-Szmek
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek systemd is free software; you can redistribute it and/or modify it
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek under the terms of the GNU Lesser General Public License as published by
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek the Free Software Foundation; either version 2.1 of the License, or
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek (at your option) any later version.
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek systemd is distributed in the hope that it will be useful, but
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek WITHOUT ANY WARRANTY; without even the implied warranty of
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek Lesser General Public License for more details.
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek You should have received a copy of the GNU Lesser General Public License
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek along with systemd; If not, see <http://www.gnu.org/licenses/>.
21ac6ff143cc8bebfbd1818af28e8c6f82cd5265Zbigniew Jędrzejewski-Szmek<refentry id="machinectl" conditional='ENABLE_MACHINED'
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek xmlns:xi="http://www.w3.org/2001/XInclude">
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <productname>systemd</productname>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <email>lennart@poettering.net</email>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refentrytitle>machinectl</refentrytitle>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refpurpose>Control the systemd machine manager</refpurpose>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refsynopsisdiv>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <arg choice="opt" rep="repeat">OPTIONS</arg>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <arg choice="opt" rep="repeat">NAME</arg>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek </refsynopsisdiv>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para><command>machinectl</command> may be used to introspect and
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek control the state of the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek virtual machine and container registration manager
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>The following options are understood:</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>-p</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>--property=</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>When showing machine or image properties,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek limit the output to certain properties as specified by the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek argument. If not specified, all set properties are shown. The
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek argument should be a property name, such as
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <literal>Name</literal>. If specified more than once, all
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek properties with the specified names are
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>-a</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>--all</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>When showing machine or image properties, show
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek all properties regardless of whether they are set or
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>When listing VM or container images, do not suppress
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek images beginning in a dot character
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek (<literal>.</literal>).</para></listitem>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>-l</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>--full</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Do not ellipsize process tree entries.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>--no-ask-password</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Do not query the user for authentication for
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek privileged operations.</para></listitem>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>--kill-who=</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>When used with <command>kill</command>, choose
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek which processes to kill. Must be one of
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <option>leader</option>, or <option>all</option> to select
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek whether to kill only the leader process of the machine or all
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek processes of the machine. If omitted, defaults to
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <option>all</option>.</para></listitem>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>-s</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>--signal=</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>When used with <command>kill</command>, choose
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek which signal to send to selected processes. Must be one of the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek well-known signal specifiers, such as
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <constant>SIGTERM</constant>, <constant>SIGINT</constant> or
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <constant>SIGSTOP</constant>. If omitted, defaults to
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <constant>SIGTERM</constant>.</para></listitem>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>--mkdir</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>When used with <command>bind</command> creates
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek the destination directory before applying the bind
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>--read-only</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>When used with <command>bind</command> applies
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek a read-only bind mount.</para></listitem>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>-n</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>--lines=</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>When used with <command>status</command>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek controls the number of journal lines to show, counting from
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek the most recent ones. Takes a positive integer argument.
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek Defaults to 10.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>-o</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>--output=</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>When used with <command>status</command>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek controls the formatting of the journal entries that are shown.
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek For the available choices, see
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek Defaults to <literal>short</literal>.</para></listitem>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>--verify=</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>When downloading a container or VM image,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek specify whether the image shall be verified before it is made
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek available. Takes one of <literal>no</literal>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <literal>checksum</literal> and <literal>signature</literal>.
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek If <literal>no</literal> no verification is done. If
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <literal>checksum</literal> is specified the download is
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek checked for integrity after transfer is complete, but no
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek signatures are verified. If <literal>signature</literal> is
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek specified, the checksum is verified and the images's signature
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek is checked against a local keyring of trustable vendors. It is
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek strongly recommended to set this option to
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <literal>signature</literal> if the server and protocol
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek support this. Defaults to
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <literal>signature</literal>.</para></listitem>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>--force</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>When downloading a container or VM image, and
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek a local copy by the specified local machine name already
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek exists, delete it first and replace it by the newly downloaded
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>--dkr-index-url</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Specifies the index server to use for
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek downloading <literal>dkr</literal> images with the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <command>pull-dkr</command>. Takes a
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <literal>http://</literal>, <literal>https://</literal>
6e9efa59209d48fc69a456fbadb2b5c113f503a6Lennart Poettering <varlistentry>
6e9efa59209d48fc69a456fbadb2b5c113f503a6Lennart Poettering <listitem><para>When used with the <option>export-tar</option>
6e9efa59209d48fc69a456fbadb2b5c113f503a6Lennart Poettering or <option>export-raw</option> commands specifies the
6e9efa59209d48fc69a456fbadb2b5c113f503a6Lennart Poettering compression format to use for the resulting file. Takes one of
6e9efa59209d48fc69a456fbadb2b5c113f503a6Lennart Poettering <literal>uncompressed</literal>, <literal>xz</literal>,
6e9efa59209d48fc69a456fbadb2b5c113f503a6Lennart Poettering <literal>gzip</literal>, <literal>bzip2</literal>. By default
6e9efa59209d48fc69a456fbadb2b5c113f503a6Lennart Poettering the format is determined automatically from the image file
6e9efa59209d48fc69a456fbadb2b5c113f503a6Lennart Poettering </varlistentry>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <xi:include href="user-system-options.xml" xpointer="host" />
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <xi:include href="user-system-options.xml" xpointer="machine" />
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <xi:include href="standard-options.xml" xpointer="no-pager" />
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <xi:include href="standard-options.xml" xpointer="no-legend" />
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <xi:include href="standard-options.xml" xpointer="help" />
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <xi:include href="standard-options.xml" xpointer="version" />
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>The following commands are understood:</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refsect2><title>Machine Commands</title><variablelist>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><command>list</command></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>List currently running (online) virtual
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek machines and containers. To enumerate container images that
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek can be started, use <command>list-images</command> (see
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><command>status</command> <replaceable>NAME</replaceable>...</term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Show terse runtime status information about
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek one or more virtual machines and containers, followed by the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek most recent log data from the journal. This function is
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek intended to generate human-readable output. If you are looking
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek for computer-parsable output, use <command>show</command>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek instead. Note that the log data shown is reported by the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek virtual machine or container manager, and frequently contains
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek console output of the machine, but not necessarily journal
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek contents of the machine itself.</para></listitem>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><command>show</command> <replaceable>NAME</replaceable>...</term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Show properties of one or more registered
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek virtual machines or containers or the manager itself. If no
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek argument is specified, properties of the manager will be
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek shown. If an NAME is specified, properties of this virtual
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek machine or container are shown. By default, empty properties
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek are suppressed. Use <option>--all</option> to show those too.
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek To select specific properties to show, use
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <option>--property=</option>. This command is intended to be
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek used whenever computer-parsable output is required. Use
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <command>status</command> if you are looking for formatted
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek human-readable output.</para></listitem>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><command>start</command> <replaceable>NAME</replaceable>...</term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Start a container as a system service, using
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek This starts <filename>systemd-nspawn@.service</filename>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek instantiated for the specified machine name, similar to the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek effect of <command>systemctl start</command> on the service
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek name. <command>systemd-nspawn</command> looks for a container
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek image by the specified name in
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <filename>/var/lib/machines/</filename> (and other search
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek paths, see below) and runs it. Use
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <command>list-images</command> (see below), for listing
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek available container images to start.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek also interfaces with a variety of other container and VM
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek managers, <command>systemd-nspawn</command> is just one
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek implementation of it. Most of the commands available in
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <command>machinectl</command> may be used on containers or VMs
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek controlled by other managers, not just
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <command>systemd-nspawn</command>. Starting VMs and container
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek images on those managers requires manager-specific
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>To interactively start a container on the command line
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek with full access to the container's console, please invoke
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <command>systemd-nspawn</command> directly. To stop a running
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek container use <command>machinectl poweroff</command>, see
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><command>login</command> <replaceable>NAME</replaceable></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Open an interactive terminal login session to
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek a container. This will create a TTY connection to a specific
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek container and asks for the execution of a getty on it. Note
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek that this is only supported for containers running
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek as init system.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>This command will open a full login prompt on the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek container, which then asks for username and password. Use
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek with the <option>--machine=</option> switch to invoke a single
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek command, either interactively or in the background within a
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek local container.</para></listitem>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><command>enable</command> <replaceable>NAME</replaceable>...</term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><command>disable</command> <replaceable>NAME</replaceable>...</term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Enable or disable a container as a system
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek service to start at system boot, using
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek This enables or disables
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <filename>systemd-nspawn@.service</filename>, instantiated for
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek the specified machine name, similar to the effect of
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <command>systemctl enable</command> or <command>systemctl
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek disable</command> on the service name.</para></listitem>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><command>poweroff</command> <replaceable>NAME</replaceable>...</term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Power off one or more containers. This will
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek trigger a reboot by sending SIGRTMIN+4 to the container's init
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek process, which causes systemd-compatible init systems to shut
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek down cleanly. This operation does not work on containers that
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>-compatible
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek init system, such as sysvinit. Use
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <command>terminate</command> (see below) to immediately
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek terminate a container or VM, without cleanly shutting it
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><command>reboot</command> <replaceable>NAME</replaceable>...</term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Reboot one or more containers. This will
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek trigger a reboot by sending SIGINT to the container's init
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek process, which is roughly equivalent to pressing Ctrl+Alt+Del
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek on a non-containerized system, and is compatible with
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek containers running any system manager.</para></listitem>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><command>terminate</command> <replaceable>NAME</replaceable>...</term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Immediately terminates a virtual machine or
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek container, without cleanly shutting it down. This kills all
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek processes of the virtual machine or container and deallocates
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek all resources attached to that instance. Use
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <command>poweroff</command> to issue a clean shutdown
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><command>kill</command> <replaceable>NAME</replaceable>...</term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Send a signal to one or more processes of the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek virtual machine or container. This means processes as seen by
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek the host, not the processes inside the virtual machine or
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek container. Use <option>--kill-who=</option> to select which
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek process to kill. Use <option>--signal=</option> to select the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek signal to send.</para></listitem>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><command>bind</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Bind mounts a directory from the host into the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek specified container. The first directory argument is the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek source directory on the host, the second directory argument
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek the source directory on the host. When the latter is omitted
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek the destination path in the container is the same as the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek source path on the host. When combined with the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <option>--read-only</option> switch a ready-only bind mount is
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek created. When combined with the <option>--mkdir</option>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek switch the destination path is first created before the mount
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek is applied. Note that this option is currently only supported
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><command>copy-to</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Copies files or directories from the host
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek system into a running container. Takes a container name,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek followed by the source path on the host and the destination
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek path in the container. If the destination path is omitted the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek same as the source path is used.</para></listitem>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><command>copy-from</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Copies files or directories from a container
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek into the host system. Takes a container name, followed by the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek source path in the container the destination path on the host.
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek If the destination path is omitted the same as the source path
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refsect2><title>Image Commands</title><variablelist>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><command>list-images</command></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Show a list of locally installed container and
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek VM images. This enumerates all raw disk images and container
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek directories and subvolumes in
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <filename>/var/lib/machines/</filename> (and other search
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek paths, see below). Use <command>start</command> (see above) to
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek run a container off one of the listed images. Note that by
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek default containers whose name begins with a dot
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek (<literal>.</literal>) are not shown. To show these too,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek specify <option>--all</option>. Note that a special image
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <literal>.host</literal> always implicitly exists and refers
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek to the image the host itself is booted from.</para></listitem>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><command>image-status</command> <replaceable>NAME</replaceable>...</term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Show terse status information about one or
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek more container or VM images. This function is intended to
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek generate human-readable output. Use
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <command>show-image</command> (see below) to generate
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek computer-parsable output instead.</para></listitem>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><command>show-image</command> <replaceable>NAME</replaceable>...</term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Show properties of one or more registered
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek virtual machine or container images, or the manager itself. If
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek no argument is specified, properties of the manager will be
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek shown. If an NAME is specified, properties of this virtual
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek machine or container image are shown. By default, empty
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek properties are suppressed. Use <option>--all</option> to show
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek those too. To select specific properties to show, use
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <option>--property=</option>. This command is intended to be
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek used whenever computer-parsable output is required. Use
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <command>image-status</command> if you are looking for
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek formatted human-readable output.</para></listitem>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><command>clone</command> <replaceable>NAME</replaceable> <replaceable>NAME</replaceable></term>
d6ce17c7f02ed3facdb45f65f546e587c2f00950Lennart Poettering <listitem><para>Clones a container or VM image. The
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek arguments specify the name of the image to clone and the name
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek of the newly cloned image. Note that plain directory container
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek images are cloned into subvolume images with this command.
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek Note that cloning a container or VM image is optimized for
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek btrfs file systems, and might not be efficient on others, due
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek to file system limitations.</para></listitem>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><command>rename</command> <replaceable>NAME</replaceable> <replaceable>NAME</replaceable></term>
d6ce17c7f02ed3facdb45f65f546e587c2f00950Lennart Poettering <listitem><para>Renames a container or VM image. The
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek arguments specify the name of the image to rename and the new
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek name of the image.</para></listitem>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><command>read-only</command> <replaceable>NAME</replaceable> [<replaceable>BOOL</replaceable>]</term>
d6ce17c7f02ed3facdb45f65f546e587c2f00950Lennart Poettering <listitem><para>Marks or (unmarks) a container or VM image
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek read-only. Takes a VM or container image name, followed by a
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek boolean as arguments. If the boolean is omitted, positive is
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek implied, i.e. the image is marked read-only.</para></listitem>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><command>remove</command> <replaceable>NAME</replaceable>...</term>
d6ce17c7f02ed3facdb45f65f546e587c2f00950Lennart Poettering <listitem><para>Removes one or more container or VM images.
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek The special image <literal>.host</literal>, which refers to
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek the host's own directory tree may not be
d6ce17c7f02ed3facdb45f65f546e587c2f00950Lennart Poettering <varlistentry>
d6ce17c7f02ed3facdb45f65f546e587c2f00950Lennart Poettering <term><command>set-limit</command> [<replaceable>NAME</replaceable>] <replaceable>BYTES</replaceable></term>
d6ce17c7f02ed3facdb45f65f546e587c2f00950Lennart Poettering <listitem><para>Sets the maximum size in bytes a specific
7de304525deafe4eb86060321e39787138dbbadfLennart Poettering container or VM image, or all images may grow up to on disk
7de304525deafe4eb86060321e39787138dbbadfLennart Poettering (disk quota). Takes either one or two parameters. The first,
d6ce17c7f02ed3facdb45f65f546e587c2f00950Lennart Poettering optional parameter refers to a container or VM image name. If
7de304525deafe4eb86060321e39787138dbbadfLennart Poettering specified the size limit of the specified image is changed. If
7de304525deafe4eb86060321e39787138dbbadfLennart Poettering omitted the overall size limit of the sum of all images stored
7de304525deafe4eb86060321e39787138dbbadfLennart Poettering locally is changed. The final argument specifies the size
7de304525deafe4eb86060321e39787138dbbadfLennart Poettering limit in bytes, possibly suffixed by the usual K, M, G, T
7de304525deafe4eb86060321e39787138dbbadfLennart Poettering units. If the size limit shall be disabled, specify
7de304525deafe4eb86060321e39787138dbbadfLennart Poettering <para>Note that per-container size limits are only supported
7de304525deafe4eb86060321e39787138dbbadfLennart Poettering on btrfs file systems. Also note that if
7de304525deafe4eb86060321e39787138dbbadfLennart Poettering <command>set-limit</command> is invoked without image
7de304525deafe4eb86060321e39787138dbbadfLennart Poettering parameter, and <filename>/var/lib/machines</filename> is
7de304525deafe4eb86060321e39787138dbbadfLennart Poettering empty, and the directory is not located on btrfs, a btrfs
7de304525deafe4eb86060321e39787138dbbadfLennart Poettering loopback file is implicitly created as
7de304525deafe4eb86060321e39787138dbbadfLennart Poettering <filename>/var/lib/machines.raw</filename> with the given
7de304525deafe4eb86060321e39787138dbbadfLennart Poettering size, and mounted to
7de304525deafe4eb86060321e39787138dbbadfLennart Poettering <filename>/var/lib/machines</filename>. The size of the
7de304525deafe4eb86060321e39787138dbbadfLennart Poettering loopback may later be readjusted with
7de304525deafe4eb86060321e39787138dbbadfLennart Poettering <command>set-limit</command>, as well. If such a
7de304525deafe4eb86060321e39787138dbbadfLennart Poettering loopback-mounted <filename>/var/lib/machines</filename>
7de304525deafe4eb86060321e39787138dbbadfLennart Poettering directory is used <command>set-limit</command> without image
7de304525deafe4eb86060321e39787138dbbadfLennart Poettering name alters both the quota setting within the file system as
7de304525deafe4eb86060321e39787138dbbadfLennart Poettering well as the loopback file and file system size
d6ce17c7f02ed3facdb45f65f546e587c2f00950Lennart Poettering </varlistentry>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refsect2><title>Image Transfer Commands</title><variablelist>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><command>pull-tar</command> <replaceable>URL</replaceable> [<replaceable>NAME</replaceable>]</term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Downloads a <filename>.tar</filename>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek container image from the specified URL, and makes it available
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek under the specified local machine name. The URL must be of
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek type <literal>http://</literal> or
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <literal>https://</literal>, and must refer to a
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <filename>.tar</filename>, <filename>.tar.gz</filename>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <filename>.tar.xz</filename> or <filename>.tar.bz2</filename>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek archive file. If the local machine name is omitted the name it
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek is automatically derived from the last component of the URL,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek with its suffix removed.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>The image is verified before it is made available,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek unless <option>--verify=no</option> is specified. Verification
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek is done via SHA256SUMS and SHA256SUMS.gpg files, that need to
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek be made available on the same web server, under the same URL
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek as the <filename>.tar</filename> file, but with the last
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek component (the filename) of the URL replaced. With
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <option>--verify=checksum</option> only the SHA256 checksum
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek for the file is verified, based on the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <filename>SHA256SUMS</filename> file. With
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <option>--verify=signature</option> the SHA256SUMS file is
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek first verified with detached GPG signature file
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <filename>SHA256SUMS.gpg</filename>. The public key for this
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek verification step needs to be available in
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <filename>/usr/lib/systemd/import-pubring.gpg</filename> or
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <filename>/etc/systemd/import-pubring.gpg</filename>.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>The container image will be downloaded and stored in a
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek read-only subvolume in
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <filename>/var/lib/machines/</filename>, that is named after
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek the specified URL and its HTTP etag. A writable snapshot is
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek then taken from this subvolume, and named after the specified
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek local name. This behaviour ensures that creating multiple
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek container instances of the same URL is efficient, as multiple
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek downloads are not necessary. In order to create only the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek read-only image, and avoid creating its writable snapshot,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek specify <literal>-</literal> as local machine name.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>Note that the read-only subvolume is prefixed with
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <filename>.tar-</filename>, and is thus now shown by
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <command>list-images</command>, unless <option>--all</option>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek is passed.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>Note that pressing C-c during execution of this command
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek will not abort the download. Use
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <command>cancel-transfer</command>, described
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><command>pull-raw</command> <replaceable>URL</replaceable> [<replaceable>NAME</replaceable>]</term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Downloads a <filename>.raw</filename>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek container or VM disk image from the specified URL, and makes
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek it available under the specified local machine name. The URL
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek must be of type <literal>http://</literal> or
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <literal>https://</literal>. The container image must either
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek be a <filename>.qcow2</filename> or raw disk image, optionally
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek compressed as <filename>.gz</filename>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <filename>.xz</filename>, or <filename>.bz2</filename>. If the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek local machine name is omitted the name it is automatically
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek derived from the last component of the URL, with its suffix
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>Image verification is identical for raw and tar images
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek (see above).</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>If the the downloaded image is in
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <filename>.qcow2</filename> format it es converted into a raw
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek image file before it is made available.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>Downloaded images of this type will be placed as
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek read-only <filename>.raw</filename> file in
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <filename>/var/lib/machines/</filename>. A local, writable
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek (reflinked) copy is then made under the specified local
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek machine name. To omit creation of the local, writable copy
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek pass <literal>-</literal> as local machine name.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>Similar to the behaviour of <command>pull-tar</command>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek the read-only image is prefixed with
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <filename>.raw-</filename>, and thus now shown by
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <command>list-images</command>, unless <option>--all</option>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek is passed.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>Note that pressing C-c during execution of this command
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek will not abort the download. Use
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <command>cancel-transfer</command>, described
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><command>pull-dkr</command> <replaceable>REMOTE</replaceable> [<replaceable>NAME</replaceable>]</term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Downloads a <literal>dkr</literal> container
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek image and makes it available locally. The remote name refers
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek to a <literal>dkr</literal> container name. If omitted, the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek local machine name is derived from the <literal>dkr</literal>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek container name.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>Image verification is not available for
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <literal>dkr</literal> containers, and thus
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <option>--verify=no</option> must always be specified with
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek this command.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>This command downloads all (missing) layers for the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek specified container and places them in read-only subvolumes in
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <filename>/var/lib/machines/</filename>. A writable snapshot
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek of the newest layer is then created under the specified local
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek machine name. To omit creation of this writable snapshot, pass
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <literal>-</literal> as local machine name.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>The read-only layer subvolumes are prefixed with
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <filename>.dkr-</filename>, and thus now shown by
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <command>list-images</command>, unless <option>--all</option>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek is passed.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>To specify the <literal>dkr</literal> index server to
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek use for looking up the specified container, use
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <option>--dkr-index-url=</option>.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>Note that pressing C-c during execution of this command
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek will not abort the download. Use
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <command>cancel-transfer</command>, described
af40e5d3acbdcff09c8809cd1b86ecf8871f65f0Lennart Poettering <varlistentry>
af40e5d3acbdcff09c8809cd1b86ecf8871f65f0Lennart Poettering <term><command>import-tar</command> <replaceable>FILE</replaceable> [<replaceable>NAME</replaceable>]</term>
af40e5d3acbdcff09c8809cd1b86ecf8871f65f0Lennart Poettering <term><command>import-raw</command> <replaceable>FILE</replaceable> [<replaceable>NAME</replaceable>]</term>
af40e5d3acbdcff09c8809cd1b86ecf8871f65f0Lennart Poettering <listitem><para>Imports a TAR or RAW container or VM image,
af40e5d3acbdcff09c8809cd1b86ecf8871f65f0Lennart Poettering and places it under the specified name in
af40e5d3acbdcff09c8809cd1b86ecf8871f65f0Lennart Poettering <filename>/var/lib/machines/</filename>. When
af40e5d3acbdcff09c8809cd1b86ecf8871f65f0Lennart Poettering <command>import-tar</command> is used the file specified as
af40e5d3acbdcff09c8809cd1b86ecf8871f65f0Lennart Poettering first argument should be a tar archive, possibly compressed
af40e5d3acbdcff09c8809cd1b86ecf8871f65f0Lennart Poettering with xz, gzip or bzip2. It will then be unpacked into its own
af40e5d3acbdcff09c8809cd1b86ecf8871f65f0Lennart Poettering subvolume in <filename>/var/lib/machines</filename>. When
af40e5d3acbdcff09c8809cd1b86ecf8871f65f0Lennart Poettering <command>import-raw</command> is used the file should be a
af40e5d3acbdcff09c8809cd1b86ecf8871f65f0Lennart Poettering qcow2 or raw disk image, possibly compressed with xz, gzip or
af40e5d3acbdcff09c8809cd1b86ecf8871f65f0Lennart Poettering bzip2. If the second argument (the resulting image name) is
af40e5d3acbdcff09c8809cd1b86ecf8871f65f0Lennart Poettering not specified it is automatically derived from the file
af40e5d3acbdcff09c8809cd1b86ecf8871f65f0Lennart Poettering name. If the file name is passed as <literal>-</literal> the
af40e5d3acbdcff09c8809cd1b86ecf8871f65f0Lennart Poettering image is read from standard input, in which case the second
af40e5d3acbdcff09c8809cd1b86ecf8871f65f0Lennart Poettering argument is mandatory.</para>
af40e5d3acbdcff09c8809cd1b86ecf8871f65f0Lennart Poettering <para>Similar as with <command>pull-tar</command>,
af40e5d3acbdcff09c8809cd1b86ecf8871f65f0Lennart Poettering <command>pull-raw</command> the file system
af40e5d3acbdcff09c8809cd1b86ecf8871f65f0Lennart Poettering <filename>/var/lib/machines.raw</filename> is increased in
af40e5d3acbdcff09c8809cd1b86ecf8871f65f0Lennart Poettering size of necessary and appropriate. Optionally the
af40e5d3acbdcff09c8809cd1b86ecf8871f65f0Lennart Poettering <option>--read-only</option> switch may be used to create a
af40e5d3acbdcff09c8809cd1b86ecf8871f65f0Lennart Poettering read-only container or VM image. No cryptographic validation
af40e5d3acbdcff09c8809cd1b86ecf8871f65f0Lennart Poettering is done when importing the images.</para>
af40e5d3acbdcff09c8809cd1b86ecf8871f65f0Lennart Poettering <para>Much like image downloads, ongoing imports may be listed
af40e5d3acbdcff09c8809cd1b86ecf8871f65f0Lennart Poettering with <command>list-transfers</command> and aborted with
af40e5d3acbdcff09c8809cd1b86ecf8871f65f0Lennart Poettering <command>cancel-transfer</command>.</para></listitem>
af40e5d3acbdcff09c8809cd1b86ecf8871f65f0Lennart Poettering </varlistentry>
6e9efa59209d48fc69a456fbadb2b5c113f503a6Lennart Poettering <varlistentry>
6e9efa59209d48fc69a456fbadb2b5c113f503a6Lennart Poettering <term><command>export-tar</command> <replaceable>NAME</replaceable> [<replaceable>FILE</replaceable>]</term>
6e9efa59209d48fc69a456fbadb2b5c113f503a6Lennart Poettering <term><command>export-raw</command> <replaceable>NAME</replaceable> [<replaceable>FILE</replaceable>]</term>
6e9efa59209d48fc69a456fbadb2b5c113f503a6Lennart Poettering <listitem><para>Exports a TAR or RAW container or VM image and
6e9efa59209d48fc69a456fbadb2b5c113f503a6Lennart Poettering stores it in the specified file. The first parameter should be
6e9efa59209d48fc69a456fbadb2b5c113f503a6Lennart Poettering a VM or container image name. The second parameter should be a
6e9efa59209d48fc69a456fbadb2b5c113f503a6Lennart Poettering file path the TAR or RAW image is written to. If the path ends
6e9efa59209d48fc69a456fbadb2b5c113f503a6Lennart Poettering in <literal>.gz</literal> the file is compressed with gzip, if
6e9efa59209d48fc69a456fbadb2b5c113f503a6Lennart Poettering it ends in <literal>.xz</literal> with xz, and if it ends in
6e9efa59209d48fc69a456fbadb2b5c113f503a6Lennart Poettering <literal>.bz2</literal> with bzip2. If the path ends in
6e9efa59209d48fc69a456fbadb2b5c113f503a6Lennart Poettering neither the file is left uncompressed. If the second argument
6e9efa59209d48fc69a456fbadb2b5c113f503a6Lennart Poettering is missing the image is written to standard output. The
6e9efa59209d48fc69a456fbadb2b5c113f503a6Lennart Poettering compression may also be explicitly selected with the
6e9efa59209d48fc69a456fbadb2b5c113f503a6Lennart Poettering <option>--format=</option> switch. This is in particular
6e9efa59209d48fc69a456fbadb2b5c113f503a6Lennart Poettering useful if the second parameter is left unspecified.</para>
6e9efa59209d48fc69a456fbadb2b5c113f503a6Lennart Poettering <para>Much like image downloads and imports, ongoing exports
6e9efa59209d48fc69a456fbadb2b5c113f503a6Lennart Poettering may be listed with <command>list-transfers</command> and
6e9efa59209d48fc69a456fbadb2b5c113f503a6Lennart Poettering <command>cancel-transfer</command>.</para>
6e9efa59209d48fc69a456fbadb2b5c113f503a6Lennart Poettering <para>Note that currently only directory and subvolume images
6e9efa59209d48fc69a456fbadb2b5c113f503a6Lennart Poettering may be exported as TAR images, and only raw disk images as RAW
6e9efa59209d48fc69a456fbadb2b5c113f503a6Lennart Poettering </varlistentry>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><command>list-transfers</command></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Shows a list of container or VM image
6e9efa59209d48fc69a456fbadb2b5c113f503a6Lennart Poettering downloads, imports and exports that are currently in
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><command>cancel-transfers</command> <replaceable>ID</replaceable>...</term>
6e9efa59209d48fc69a456fbadb2b5c113f503a6Lennart Poettering <listitem><para>Aborts a download, import or export of the
6e9efa59209d48fc69a456fbadb2b5c113f503a6Lennart Poettering container or VM image with the specified ID. To list ongoing
6e9efa59209d48fc69a456fbadb2b5c113f503a6Lennart Poettering transfers and their IDs, use
af40e5d3acbdcff09c8809cd1b86ecf8871f65f0Lennart Poettering <command>list-transfers</command>. </para></listitem>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <title>Files and Directories</title>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>Machine images are preferably stored in
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <filename>/var/lib/machines/</filename>, but are also searched for
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek in <filename>/usr/local/lib/machines/</filename> and
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <filename>/usr/lib/machines/</filename>. For compatibility reasons
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek the directory <filename>/var/lib/container/</filename> is
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek searched, too. Note that images stored below
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <filename>/usr</filename> are always considered read-only. It is
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek possible to symlink machines images from other directories into
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <filename>/var/lib/machines/</filename> to make them available for
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek control with <command>machinectl</command>.</para>
7de304525deafe4eb86060321e39787138dbbadfLennart Poettering <para>Note that many image operations are only supported,
7de304525deafe4eb86060321e39787138dbbadfLennart Poettering efficient or atomic on btrfs file systems. Due to this, if the
7de304525deafe4eb86060321e39787138dbbadfLennart Poettering <command>pull-tar</command>, <command>pull-raw</command>,
af40e5d3acbdcff09c8809cd1b86ecf8871f65f0Lennart Poettering <command>pull-dkr</command>, <command>import-tar</command>,
af40e5d3acbdcff09c8809cd1b86ecf8871f65f0Lennart Poettering <command>import-raw</command> and <command>set-limit</command>
7de304525deafe4eb86060321e39787138dbbadfLennart Poettering commands notice that <filename>/var/lib/machines</filename> is
7de304525deafe4eb86060321e39787138dbbadfLennart Poettering empty and not located on btrfs, they will implicitly set up a
7de304525deafe4eb86060321e39787138dbbadfLennart Poettering loopback file <filename>/var/lib/machines.raw</filename>
7de304525deafe4eb86060321e39787138dbbadfLennart Poettering containing a btrfs file system that is mounted to
7de304525deafe4eb86060321e39787138dbbadfLennart Poettering <filename>/var/lib/machines</filename>. The size of this loopback
af40e5d3acbdcff09c8809cd1b86ecf8871f65f0Lennart Poettering file may be controlled dynamically with
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>Disk images are understood by
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek and <command>machinectl</command> in three formats:</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>A simple directory tree, containing the files
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek and directories of the container to boot.</para></listitem>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>A subvolume (on btrfs file systems), which are
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek similar to the simple directories, described above. However,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek they have additional benefits, such as efficient cloning and
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek quota reporting.</para></listitem>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>"Raw" disk images, i.e. binary images of disks
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek with a GPT or MBR partition table. Images of this type are
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek regular files with the suffix
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <literal>.raw</literal>.</para></listitem>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek for more information on image formats, in particular it's
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <option>--directory=</option> and <option>--image=</option>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <title>Download an Ubuntu image and open a shell in it</title>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <programlisting># machinectl pull-tar https://cloud-images.ubuntu.com/trusty/current/trusty-server-cloudimg-amd64-root.tar.gz
e0ea94c1e2ab3930c85c6057189a2a829a13a800Lennart Poettering# systemd-nspawn -M trusty-server-cloudimg-amd64-root</programlisting>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>This downloads and verifies the specified
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <filename>.tar</filename> image, and then uses
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek to open a shell in it.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <title>Download a Fedora image, set a root password in it, start
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek it as service</title>
ac92ced5bb41def1d90f871d6c8cfec2b03c0c7dBenjamin Franzke <programlisting># machinectl pull-raw --verify=no http://ftp.halifax.rwth-aachen.de/fedora/linux/releases/21/Cloud/Images/x86_64/Fedora-Cloud-Base-20141203-21.x86_64.raw.xz
ac92ced5bb41def1d90f871d6c8cfec2b03c0c7dBenjamin Franzke# systemd-nspawn -M Fedora-Cloud-Base-20141203-21
ac92ced5bb41def1d90f871d6c8cfec2b03c0c7dBenjamin Franzke# machinectl start Fedora-Cloud-Base-20141203-21
ac92ced5bb41def1d90f871d6c8cfec2b03c0c7dBenjamin Franzke# machinectl login Fedora-Cloud-Base-20141203-21</programlisting>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>This downloads the specified <filename>.raw</filename>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek image with verification disabled. Then a shell is opened in it
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek and a root password is set. Afterwards the shell is left, and
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek the machine started as system service. With the last command a
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek login prompt into the container is requested.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <title>Download a Fedora <literal>dkr</literal> image</title>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <programlisting># machinectl pull-dkr --verify=no mattdm/fedora
e0ea94c1e2ab3930c85c6057189a2a829a13a800Lennart Poettering# systemd-nspawn -M fedora</programlisting>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>Downloads a <literal>dkr</literal> image and opens a shell
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek in it. Note that the specified download command might require an
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek index server to be specified with the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <literal>--dkr-index-url=</literal>.</para>
6e9efa59209d48fc69a456fbadb2b5c113f503a6Lennart Poettering <title>Exports a container image as tar file</title>
6e9efa59209d48fc69a456fbadb2b5c113f503a6Lennart Poettering <programlisting># machinectl export-tar fedora myfedora.tar.xz</programlisting>
6e9efa59209d48fc69a456fbadb2b5c113f503a6Lennart Poettering <para>Exports the container <literal>fedora</literal> in an
6e9efa59209d48fc69a456fbadb2b5c113f503a6Lennart Poettering xz-compress tar file <filename>myfedora.tar.xz</filename> in the
6e9efa59209d48fc69a456fbadb2b5c113f503a6Lennart Poettering current directory.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>On success, 0 is returned, a non-zero failure code
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek otherwise.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <xi:include href="less-variables.xml" />
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
6e9efa59209d48fc69a456fbadb2b5c113f503a6Lennart Poettering <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
16eb4024887b1b79fc56706fda25eadaecdef2d4Zbigniew Jędrzejewski-Szmek <citerefentry project='die-net'><refentrytitle>tar</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
16eb4024887b1b79fc56706fda25eadaecdef2d4Zbigniew Jędrzejewski-Szmek <citerefentry project='die-net'><refentrytitle>xz</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
16eb4024887b1b79fc56706fda25eadaecdef2d4Zbigniew Jędrzejewski-Szmek <citerefentry project='die-net'><refentrytitle>gzip</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
16eb4024887b1b79fc56706fda25eadaecdef2d4Zbigniew Jędrzejewski-Szmek <citerefentry project='die-net'><refentrytitle>bzip2</refentrytitle><manvolnum>1</manvolnum></citerefentry>