machinectl.xml revision 91913f584af38b29a816cca959ba648acd60ac9f
c454426c54c9beb274f415a80c64a4f1580700e7Lennart Poettering<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
19887cd06a3af2f045e763986eda19e208bd3f85Zbigniew Jędrzejewski-Szmek<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
12b42c76672a66c2d4ea7212c14f8f1b5a62b78dTom Gundersen "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>
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering <para><command>machinectl</command> may be used to execute
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering operations on machines and images. Machines in this sense are
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering considered running instances of:</para>
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering <itemizedlist>
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering <listitem><para>Virtual Machines (VMs) that virtualize hardware
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering to run full operating system (OS) instances (including their kernels)
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering in a virtualized environment on top of the host OS.</para></listitem>
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering <listitem><para>Containers that share the hardware and
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering OS kernel with the host OS, in order to run
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering OS userspace instances on top the host OS.</para></listitem>
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering <listitem><para>The host system itself</para></listitem>
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering </itemizedlist>
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering <para>Machines are identified by names that follow the same rules
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt as UNIX and DNS host names, for details see below. Machines are
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt instantiated from disk or file system images, that frequently but not
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt necessarily carry the same name as machines running from
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering them. Images in this sense are considered:</para>
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering <itemizedlist>
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering <listitem><para>Directory trees containing an OS, including its
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering top-level directories <filename>/usr</filename>,
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering <filename>/etc</filename>, and so on.</para></listitem>
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering <listitem><para>btrfs subvolumes containing OS trees, similar to
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering normal directory trees.</para></listitem>
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering <listitem><para>Binary "raw" disk images containing MBR or GPT
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering partition tables and Linux file system partitions.</para></listitem>
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering <listitem><para>The file system tree of the host OS itself.</para></listitem>
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering </itemizedlist>
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>
c454426c54c9beb274f415a80c64a4f1580700e7Lennart Poettering <varlistentry>
c454426c54c9beb274f415a80c64a4f1580700e7Lennart Poettering <listitem><para>When used with the <command>shell</command>
c454426c54c9beb274f415a80c64a4f1580700e7Lennart Poettering command, chooses the user ID to open the interactive shell
c454426c54c9beb274f415a80c64a4f1580700e7Lennart Poettering session as. If this switch is not specified, defaults to
c454426c54c9beb274f415a80c64a4f1580700e7Lennart Poettering <literal>root</literal>. Note that this switch is not
c454426c54c9beb274f415a80c64a4f1580700e7Lennart Poettering supported for the <command>login</command> command (see
c454426c54c9beb274f415a80c64a4f1580700e7Lennart Poettering </varlistentry>
c454426c54c9beb274f415a80c64a4f1580700e7Lennart Poettering <varlistentry>
c454426c54c9beb274f415a80c64a4f1580700e7Lennart Poettering <listitem><para>When used with the <command>shell</command>
c454426c54c9beb274f415a80c64a4f1580700e7Lennart Poettering command, sets an environment variable to pass to the executed
c454426c54c9beb274f415a80c64a4f1580700e7Lennart Poettering shell. Takes a pair of environment variable name and value,
c454426c54c9beb274f415a80c64a4f1580700e7Lennart Poettering separated by <literal>=</literal> as argument. This switch
c454426c54c9beb274f415a80c64a4f1580700e7Lennart Poettering may be used multiple times to set multiple environment
c454426c54c9beb274f415a80c64a4f1580700e7Lennart Poettering variables. Note that this switch is not supported for the
c454426c54c9beb274f415a80c64a4f1580700e7Lennart Poettering </varlistentry>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>--mkdir</option></term>
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt <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>
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt <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>.
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt If <literal>no</literal> no verification is done. If
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt <literal>checksum</literal> is specified the download is
a8eaaee72a2f06e0fb64fb71de3b71ecba31dafbJan Engelhardt 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>
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt 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>,
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt <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
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering machines and containers. To enumerate machine images that can
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering be started, use <command>list-images</command> (see
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering below). Note that this command hides the special
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering <literal>.host</literal> machine by default. Use the
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering <option>--all</option> switch to show it.</para></listitem>
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>
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering <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
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt <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
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering <term><command>login</command> [<replaceable>NAME</replaceable>]</term>
c454426c54c9beb274f415a80c64a4f1580700e7Lennart Poettering <listitem><para>Open an interactive terminal login session in
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt a container or on the local host. If an argument is supplied
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering it refers to the container machine to connect to. If none is
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering specified, or the container name is specified as the empty
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering string, or the special machine name <literal>.host</literal>
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering (see below) is specified, the connection is made to the local
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering host instead. This will create a TTY connection to a specific
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering container or the local host and asks for the execution of a
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering getty on it. Note that this is only supported for containers
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
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering container or the local host, which then asks for username and
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering password. Use <command>shell</command> (see below) or
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry>
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering with the <option>--machine=</option> switch to directly invoke
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering a single command, either interactively or in the
c454426c54c9beb274f415a80c64a4f1580700e7Lennart Poettering <varlistentry>
ef3100e9637adda26fa19e7ee8606788320dcde3Lennart Poettering <term><command>shell</command> [<replaceable>NAME</replaceable> [<replaceable>PATH</replaceable> [<replaceable>ARGUMENTS</replaceable>...]]] </term>
c454426c54c9beb274f415a80c64a4f1580700e7Lennart Poettering <listitem><para>Open an interactive shell session in a
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering container or on the local host. The first argument refers to
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering the container machine to connect to. If none is specified, or
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering the machine name is specified as the empty string, or the
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering special machine name <literal>.host</literal> (see below) is
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering specified, the connection is made to the local host
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering instead. This works similar to <command>login</command> but
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering immediately invokes a user process. This command runs the
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering specified executable with the specified arguments, or
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt <filename>/bin/sh</filename> if none is specified. By default
ef3100e9637adda26fa19e7ee8606788320dcde3Lennart Poettering opens a <literal>root</literal> shell, but using
ef3100e9637adda26fa19e7ee8606788320dcde3Lennart Poettering <option>--uid=</option> a different user may be selected. Use
ef3100e9637adda26fa19e7ee8606788320dcde3Lennart Poettering <option>--setenv=</option> to set environment variables for
ef3100e9637adda26fa19e7ee8606788320dcde3Lennart Poettering </varlistentry>
ef3100e9637adda26fa19e7ee8606788320dcde3Lennart Poettering <varlistentry>
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt <term><command>enable</command> <replaceable>NAME</replaceable>...</term>
a8eaaee72a2f06e0fb64fb71de3b71ecba31dafbJan Engelhardt <term><command>disable</command> <replaceable>NAME</replaceable>...</term>
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt <listitem><para>Enable or disable a container as a system
ef3100e9637adda26fa19e7ee8606788320dcde3Lennart Poettering service to start at system boot, using
ef3100e9637adda26fa19e7ee8606788320dcde3Lennart Poettering <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
ef3100e9637adda26fa19e7ee8606788320dcde3Lennart Poettering This enables or disables
762a5766dc65058c245c87d326ae3d403d85ea06Lennart Poettering <filename>systemd-nspawn@.service</filename>, instantiated for
762a5766dc65058c245c87d326ae3d403d85ea06Lennart Poettering the specified machine name, similar to the effect of
762a5766dc65058c245c87d326ae3d403d85ea06Lennart Poettering <command>systemctl enable</command> or <command>systemctl
ef3100e9637adda26fa19e7ee8606788320dcde3Lennart Poettering disable</command> on the service name.</para></listitem>
a8eaaee72a2f06e0fb64fb71de3b71ecba31dafbJan Engelhardt </varlistentry>
ef3100e9637adda26fa19e7ee8606788320dcde3Lennart Poettering <varlistentry>
ef3100e9637adda26fa19e7ee8606788320dcde3Lennart Poettering <term><command>poweroff</command> <replaceable>NAME</replaceable>...</term>
ef3100e9637adda26fa19e7ee8606788320dcde3Lennart Poettering <listitem><para>Power off one or more containers. This will
c454426c54c9beb274f415a80c64a4f1580700e7Lennart Poettering trigger a reboot by sending SIGRTMIN+4 to the container's init
c454426c54c9beb274f415a80c64a4f1580700e7Lennart Poettering 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 is the destination directory in the container. When the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek latter is omitted the destination path in the container is
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek the same as the source path on the host. When combined with
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek the <option>--read-only</option> switch a ready-only bind
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek mount is created. When combined with the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <option>--mkdir</option> switch the destination path is first
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek created before the mount is applied. Note that this option is
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek currently only supported for
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>
cb7bb815d2ad7945e63214d21cec1d70152ba6abMarkus Knetschke </varlistentry>
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt <varlistentry>
cb7bb815d2ad7945e63214d21cec1d70152ba6abMarkus Knetschke <term><command>copy-from</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term>
cb7bb815d2ad7945e63214d21cec1d70152ba6abMarkus Knetschke <listitem><para>Copies files or directories from a container
cb7bb815d2ad7945e63214d21cec1d70152ba6abMarkus Knetschke 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
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt 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>
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt <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
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering 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>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <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
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering 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>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>Note that this command leaves host name, machine ID and
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek all other settings that could identify the instance
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek unmodified. The original image and the cloned copy will hence
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek share these credentials, and it might be necessary to manually
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek change them in the copy.</para></listitem>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><command>rename</command> <replaceable>NAME</replaceable> <replaceable>NAME</replaceable></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <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 <term><command>read-only</command> <replaceable>NAME</replaceable> [<replaceable>BOOL</replaceable>]</term>
3fe22bb4b6b5faf27683ad2e231b5a69b6e63a9eLennart Poettering <listitem><para>Marks or (unmarks) a container or VM image
3fe22bb4b6b5faf27683ad2e231b5a69b6e63a9eLennart Poettering read-only. Takes a VM or container image name, followed by a
3fe22bb4b6b5faf27683ad2e231b5a69b6e63a9eLennart Poettering boolean as arguments. If the boolean is omitted, positive is
3fe22bb4b6b5faf27683ad2e231b5a69b6e63a9eLennart Poettering implied, i.e. the image is marked read-only.</para></listitem>
3fe22bb4b6b5faf27683ad2e231b5a69b6e63a9eLennart Poettering </varlistentry>
3fe22bb4b6b5faf27683ad2e231b5a69b6e63a9eLennart Poettering <varlistentry>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><command>remove</command> <replaceable>NAME</replaceable>...</term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <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
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><command>set-limit</command> [<replaceable>NAME</replaceable>] <replaceable>BYTES</replaceable></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Sets the maximum size in bytes a specific
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek container or VM image, or all images may grow up to on disk
d6ce17c7f02ed3facdb45f65f546e587c2f00950Lennart Poettering (disk quota). Takes either one or two parameters. The first,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek optional parameter refers to a container or VM image name. If
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek specified the size limit of the specified image is changed. If
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek omitted the overall size limit of the sum of all images stored
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek locally is changed. The final argument specifies the size
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek limit in bytes, possibly suffixed by the usual K, M, G, T
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek units. If the size limit shall be disabled, specify
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <literal>-</literal> as size.</para>
d6ce17c7f02ed3facdb45f65f546e587c2f00950Lennart Poettering <para>Note that per-container size limits are only supported
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek on btrfs file systems. Also note that if
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt <command>set-limit</command> is invoked without image
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek parameter, and <filename>/var/lib/machines</filename> is
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek empty, and the directory is not located on btrfs, a btrfs
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek loopback file is implicitly created as
d6ce17c7f02ed3facdb45f65f546e587c2f00950Lennart Poettering <filename>/var/lib/machines.raw</filename> with the given
d6ce17c7f02ed3facdb45f65f546e587c2f00950Lennart Poettering size, and mounted to
d6ce17c7f02ed3facdb45f65f546e587c2f00950Lennart Poettering <filename>/var/lib/machines</filename>. The size of the
a8eaaee72a2f06e0fb64fb71de3b71ecba31dafbJan Engelhardt loopback may later be readjusted with
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt <command>set-limit</command>, as well. If such a
7de304525deafe4eb86060321e39787138dbbadfLennart Poettering loopback-mounted <filename>/var/lib/machines</filename>
d6ce17c7f02ed3facdb45f65f546e587c2f00950Lennart Poettering directory is used <command>set-limit</command> without image
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt name alters both the quota setting within the file system as
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt well as the loopback file and file system size
7de304525deafe4eb86060321e39787138dbbadfLennart Poettering </varlistentry>
7de304525deafe4eb86060321e39787138dbbadfLennart Poettering <refsect2><title>Image Transfer Commands</title><variablelist>
a8eaaee72a2f06e0fb64fb71de3b71ecba31dafbJan Engelhardt <varlistentry>
7de304525deafe4eb86060321e39787138dbbadfLennart Poettering <term><command>pull-tar</command> <replaceable>URL</replaceable> [<replaceable>NAME</replaceable>]</term>
7de304525deafe4eb86060321e39787138dbbadfLennart Poettering <listitem><para>Downloads a <filename>.tar</filename>
7de304525deafe4eb86060321e39787138dbbadfLennart Poettering container image from the specified URL, and makes it available
7de304525deafe4eb86060321e39787138dbbadfLennart Poettering under the specified local machine name. The URL must be of
7de304525deafe4eb86060321e39787138dbbadfLennart Poettering <literal>https://</literal>, and must refer to a
7de304525deafe4eb86060321e39787138dbbadfLennart Poettering <filename>.tar</filename>, <filename>.tar.gz</filename>,
7de304525deafe4eb86060321e39787138dbbadfLennart Poettering <filename>.tar.xz</filename> or <filename>.tar.bz2</filename>
a8eaaee72a2f06e0fb64fb71de3b71ecba31dafbJan Engelhardt archive file. If the local machine name is omitted it
7de304525deafe4eb86060321e39787138dbbadfLennart Poettering is automatically derived from the last component of the URL,
7de304525deafe4eb86060321e39787138dbbadfLennart Poettering with its suffix removed.</para>
d6ce17c7f02ed3facdb45f65f546e587c2f00950Lennart Poettering <para>The image is verified before it is made available,
d6ce17c7f02ed3facdb45f65f546e587c2f00950Lennart Poettering 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>
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt <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 behavior ensures that creating multiple
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt 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 not shown by
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt <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
12b42c76672a66c2d4ea7212c14f8f1b5a62b78dTom Gundersen will not abort the download. Use
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt <varlistentry>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><command>pull-raw</command> <replaceable>URL</replaceable> [<replaceable>NAME</replaceable>]</term>
dd2b607b7d1ce355e93f9f71cd256ec20b8ae9c4Thomas Hindoe Paaboel Andersen <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>,
6b94875fa3a7280e7f1c0df11027b927b6961edeRichard Maw <filename>.xz</filename>, or <filename>.bz2</filename>. If the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek local machine name is omitted 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 downloaded image is in
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <filename>.qcow2</filename> format it is 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 behavior of <command>pull-tar</command>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek the read-only image is prefixed with
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt <filename>.raw-</filename>, and thus not 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
6b94875fa3a7280e7f1c0df11027b927b6961edeRichard Maw </varlistentry>
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 <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 not 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
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><command>import-tar</command> <replaceable>FILE</replaceable> [<replaceable>NAME</replaceable>]</term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><command>import-raw</command> <replaceable>FILE</replaceable> [<replaceable>NAME</replaceable>]</term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Imports a TAR or RAW container or VM image,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek and places it under the specified name in
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <filename>/var/lib/machines/</filename>. When
6b94875fa3a7280e7f1c0df11027b927b6961edeRichard Maw <command>import-tar</command> is used the file specified as
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek first argument should be a tar archive, possibly compressed
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek with xz, gzip or bzip2. It will then be unpacked into its own
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek subvolume in <filename>/var/lib/machines</filename>. When
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <command>import-raw</command> is used the file should be a
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek qcow2 or raw disk image, possibly compressed with xz, gzip or
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek bzip2. If the second argument (the resulting image name) is
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek not specified it is automatically derived from the file
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek name. If the file name is passed as <literal>-</literal> the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek image is read from standard input, in which case the second
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek argument is mandatory.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>Similar as with <command>pull-tar</command>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <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>
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt <para>Much like image downloads, ongoing imports may be listed
a8eaaee72a2f06e0fb64fb71de3b71ecba31dafbJan Engelhardt with <command>list-transfers</command> and aborted with
af40e5d3acbdcff09c8809cd1b86ecf8871f65f0Lennart Poettering <command>cancel-transfer</command>.</para></listitem>
af40e5d3acbdcff09c8809cd1b86ecf8871f65f0Lennart Poettering </varlistentry>
af40e5d3acbdcff09c8809cd1b86ecf8871f65f0Lennart Poettering <varlistentry>
af40e5d3acbdcff09c8809cd1b86ecf8871f65f0Lennart Poettering <term><command>export-tar</command> <replaceable>NAME</replaceable> [<replaceable>FILE</replaceable>]</term>
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt <term><command>export-raw</command> <replaceable>NAME</replaceable> [<replaceable>FILE</replaceable>]</term>
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt <listitem><para>Exports a TAR or RAW container or VM image and
af40e5d3acbdcff09c8809cd1b86ecf8871f65f0Lennart Poettering stores it in the specified file. The first parameter should be
af40e5d3acbdcff09c8809cd1b86ecf8871f65f0Lennart Poettering a VM or container image name. The second parameter should be a
af40e5d3acbdcff09c8809cd1b86ecf8871f65f0Lennart Poettering file path the TAR or RAW image is written to. If the path ends
af40e5d3acbdcff09c8809cd1b86ecf8871f65f0Lennart Poettering in <literal>.gz</literal> the file is compressed with gzip, if
af40e5d3acbdcff09c8809cd1b86ecf8871f65f0Lennart Poettering it ends in <literal>.xz</literal> with xz, and if it ends in
af40e5d3acbdcff09c8809cd1b86ecf8871f65f0Lennart Poettering <literal>.bz2</literal> with bzip2. If the path ends in
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt neither the file is left uncompressed. If the second argument
af40e5d3acbdcff09c8809cd1b86ecf8871f65f0Lennart Poettering is missing the image is written to standard output. The
af40e5d3acbdcff09c8809cd1b86ecf8871f65f0Lennart Poettering compression may also be explicitly selected with the
af40e5d3acbdcff09c8809cd1b86ecf8871f65f0Lennart Poettering <option>--format=</option> switch. This is in particular
af40e5d3acbdcff09c8809cd1b86ecf8871f65f0Lennart Poettering useful if the second parameter is left unspecified.</para>
af40e5d3acbdcff09c8809cd1b86ecf8871f65f0Lennart Poettering <para>Much like image downloads and imports, ongoing exports
af40e5d3acbdcff09c8809cd1b86ecf8871f65f0Lennart Poettering may be listed with <command>list-transfers</command> and
af40e5d3acbdcff09c8809cd1b86ecf8871f65f0Lennart 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>
6e9efa59209d48fc69a456fbadb2b5c113f503a6Lennart Poettering <varlistentry>
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt <term><command>list-transfers</command></term>
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt <listitem><para>Shows a list of container or VM image
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt downloads, imports and exports that are currently in
6e9efa59209d48fc69a456fbadb2b5c113f503a6Lennart Poettering </varlistentry>
6e9efa59209d48fc69a456fbadb2b5c113f503a6Lennart Poettering <varlistentry>
6e9efa59209d48fc69a456fbadb2b5c113f503a6Lennart Poettering <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
6e9efa59209d48fc69a456fbadb2b5c113f503a6Lennart Poettering <command>list-transfers</command>. </para></listitem>
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt </varlistentry>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <title>Machine and Image Names</title>
6e9efa59209d48fc69a456fbadb2b5c113f503a6Lennart Poettering <para>The <command>machinectl</command> tool operates on machines
af40e5d3acbdcff09c8809cd1b86ecf8871f65f0Lennart Poettering and images, whose names must be chosen following strict
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek rules. Machine names must be suitable for use as host names
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek following a conservative subset of DNS and UNIX/Linux
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek semantics. Specifically, they must consist of one or more
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek non-empty label strings, separated by dots. No leading or trailing
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek dots are allowed. No sequences of multiple dots are allowed. The
6e9efa59209d48fc69a456fbadb2b5c113f503a6Lennart Poettering label strings may only consists of alphanumeric characters as well
6e9efa59209d48fc69a456fbadb2b5c113f503a6Lennart Poettering as the dash and underscore. The maximum length of a machine name
6e9efa59209d48fc69a456fbadb2b5c113f503a6Lennart Poettering is 64 characters.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>A special machine with the name <literal>.host</literal>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek refers to the running host system itself. This is useful for execution
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek operations or inspecting the host system as well. Not that
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <command>machinectl list</command> will not show this special
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek machine unless the <option>--all</option> switch is specified.</para>
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering <para>Requirements on image names are less strict, however must be
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering valid UTF-8, must be suitable as file names (hence not be the
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering single or double dot, and not include a slash), and may not
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering contain control characters. Since many operations search for an
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt image by the name of a requested machine it is recommended to name
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering images in the same strict fashion as machines.</para>
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering <para>A special image with the name <literal>.host</literal>
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering refers to the image of the running host system. It is hence
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering conceptually maps to the special <literal>.host</literal> machine
a8eaaee72a2f06e0fb64fb71de3b71ecba31dafbJan Engelhardt name described above. Note that <command>machinectl
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering list-images</command> won't show this special image either, unless
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering <option>--all</option> is specified.</para>
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering <para>Machine images are preferably stored in
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering <filename>/var/lib/machines/</filename>, but are also searched for
a8eaaee72a2f06e0fb64fb71de3b71ecba31dafbJan Engelhardt in <filename>/usr/local/lib/machines/</filename> and
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering <filename>/usr/lib/machines/</filename>. For compatibility reasons
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering the directory <filename>/var/lib/container/</filename> is
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering searched, too. Note that images stored below
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt <filename>/usr</filename> are always considered read-only. It is
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering possible to symlink machines images from other directories into
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering <filename>/var/lib/machines/</filename> to make them available for
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering control with <command>machinectl</command>.</para>
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering <para>Note that many image operations are only supported,
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering efficient or atomic on btrfs file systems. Due to this, if the
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering <command>pull-tar</command>, <command>pull-raw</command>,
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering <command>pull-dkr</command>, <command>import-tar</command>,
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering <command>import-raw</command> and <command>set-limit</command>
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering commands notice that <filename>/var/lib/machines</filename> is
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek empty and not located on btrfs, they will implicitly set up a
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek loopback file <filename>/var/lib/machines.raw</filename>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek containing a btrfs file system that is mounted to
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <filename>/var/lib/machines</filename>. The size of this loopback
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek file may be controlled dynamically with
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <command>set-limit</command>.</para>
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>
7de304525deafe4eb86060321e39787138dbbadfLennart Poettering <listitem><para>A subvolume (on btrfs file systems), which are
7de304525deafe4eb86060321e39787138dbbadfLennart Poettering similar to the simple directories, described above. However,
af40e5d3acbdcff09c8809cd1b86ecf8871f65f0Lennart Poettering they have additional benefits, such as efficient cloning and
7de304525deafe4eb86060321e39787138dbbadfLennart Poettering <listitem><para>"Raw" disk images, i.e. binary images of disks
7de304525deafe4eb86060321e39787138dbbadfLennart Poettering with a GPT or MBR partition table. Images of this type are
7de304525deafe4eb86060321e39787138dbbadfLennart Poettering regular files with the suffix
7de304525deafe4eb86060321e39787138dbbadfLennart Poettering <literal>.raw</literal>.</para></listitem>
af40e5d3acbdcff09c8809cd1b86ecf8871f65f0Lennart Poettering </itemizedlist>
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
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek# 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>
a8eaaee72a2f06e0fb64fb71de3b71ecba31dafbJan Engelhardt <title>Download a Fedora image, set a root password in it, start
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek it as service</title>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <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
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek# systemd-nspawn -M Fedora-Cloud-Base-20141203-21
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek# machinectl start Fedora-Cloud-Base-20141203-21
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek# machinectl login Fedora-Cloud-Base-20141203-21</programlisting>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>This downloads the specified <filename>.raw</filename>
e0ea94c1e2ab3930c85c6057189a2a829a13a800Lennart Poettering image with verification disabled. Then a shell is opened in it
e0ea94c1e2ab3930c85c6057189a2a829a13a800Lennart Poettering 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
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek# systemd-nspawn -M fedora</programlisting>
ac92ced5bb41def1d90f871d6c8cfec2b03c0c7dBenjamin Franzke <para>Downloads a <literal>dkr</literal> image and opens a shell
ac92ced5bb41def1d90f871d6c8cfec2b03c0c7dBenjamin Franzke in it. Note that the specified download command might require an
ac92ced5bb41def1d90f871d6c8cfec2b03c0c7dBenjamin Franzke index server to be specified with the
ac92ced5bb41def1d90f871d6c8cfec2b03c0c7dBenjamin Franzke <literal>--dkr-index-url=</literal>.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <title>Exports a container image as tar file</title>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <programlisting># machinectl export-tar fedora myfedora.tar.xz</programlisting>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>Exports the container <literal>fedora</literal> in an
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek xz-compress tar file <filename>myfedora.tar.xz</filename> in the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek current directory.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>On success, 0 is returned, a non-zero failure code
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek otherwise.</para>
6e9efa59209d48fc69a456fbadb2b5c113f503a6Lennart Poettering <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
a8eaaee72a2f06e0fb64fb71de3b71ecba31dafbJan Engelhardt <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
a8eaaee72a2f06e0fb64fb71de3b71ecba31dafbJan Engelhardt <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
6e9efa59209d48fc69a456fbadb2b5c113f503a6Lennart Poettering <citerefentry project='die-net'><refentrytitle>tar</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
6e9efa59209d48fc69a456fbadb2b5c113f503a6Lennart Poettering <citerefentry project='die-net'><refentrytitle>xz</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
6e9efa59209d48fc69a456fbadb2b5c113f503a6Lennart Poettering <citerefentry project='die-net'><refentrytitle>gzip</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
ef3100e9637adda26fa19e7ee8606788320dcde3Lennart Poettering <citerefentry project='die-net'><refentrytitle>bzip2</refentrytitle><manvolnum>1</manvolnum></citerefentry>