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 the transfer is complete, but no
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek signatures are verified. If <literal>signature</literal> is
7f3fdb7f19a109fa3d1be92926bfe4cea1817da5Jakub Wilk specified, the checksum is verified and the image'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
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>
28f90ea25f8d8f2bfbe6d3e6a4846943eb92e4c5Zbigniew Jędrzejewski-Szmek <listitem><para>Show 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
28f90ea25f8d8f2bfbe6d3e6a4846943eb92e4c5Zbigniew Jędrzejewski-Szmek used whenever computer-parsable output is required, and does
28f90ea25f8d8f2bfbe6d3e6a4846943eb92e4c5Zbigniew Jędrzejewski-Szmek not print the cgroup tree or journal entries. 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>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 by using
ef3100e9637adda26fa19e7ee8606788320dcde3Lennart Poettering <option>--uid=</option>, or by prefixing the machine name with
ef3100e9637adda26fa19e7ee8606788320dcde3Lennart Poettering a username and an <literal>@</literal> character, a different
ef3100e9637adda26fa19e7ee8606788320dcde3Lennart Poettering user may be selected. Use <option>--setenv=</option> to set
ef3100e9637adda26fa19e7ee8606788320dcde3Lennart Poettering environment variables for the executed process.</para>
ef3100e9637adda26fa19e7ee8606788320dcde3Lennart Poettering <para>When using the <command>shell</command> command without
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt arguments, (thus invoking the executed shell or command on the
a8eaaee72a2f06e0fb64fb71de3b71ecba31dafbJan Engelhardt local host), it is in many ways similar to a <citerefentry
ef3100e9637adda26fa19e7ee8606788320dcde3Lennart Poettering project='die-net'><refentrytitle>su</refentrytitle><manvolnum>1</manvolnum></citerefentry>
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt session, but, unlike <command>su</command>, completely isolates
ef3100e9637adda26fa19e7ee8606788320dcde3Lennart Poettering the new session from the originating session, so that it
ef3100e9637adda26fa19e7ee8606788320dcde3Lennart Poettering shares no process or session properties, and is in a clean and
ef3100e9637adda26fa19e7ee8606788320dcde3Lennart Poettering well-defined state. It will be tracked in a new utmp, login,
762a5766dc65058c245c87d326ae3d403d85ea06Lennart Poettering audit, security and keyring session, and will not inherit any
762a5766dc65058c245c87d326ae3d403d85ea06Lennart Poettering environment variables or resource limits, among other
762a5766dc65058c245c87d326ae3d403d85ea06Lennart Poettering properties.</para>
a8eaaee72a2f06e0fb64fb71de3b71ecba31dafbJan Engelhardt <para>Note that
ef3100e9637adda26fa19e7ee8606788320dcde3Lennart Poettering <citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry>
ef3100e9637adda26fa19e7ee8606788320dcde3Lennart Poettering may be used in place of the <command>shell</command> command,
ef3100e9637adda26fa19e7ee8606788320dcde3Lennart Poettering and allows more detailed, low-level configuration of the
ef3100e9637adda26fa19e7ee8606788320dcde3Lennart Poettering invoked unit. However, it is frequently more privileged than
ef3100e9637adda26fa19e7ee8606788320dcde3Lennart Poettering the <command>shell</command> command.</para></listitem>
c454426c54c9beb274f415a80c64a4f1580700e7Lennart Poettering </varlistentry>
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
cb7bb815d2ad7945e63214d21cec1d70152ba6abMarkus Knetschke is the destination directory in the container. When the
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt latter is omitted, the destination path in the container is
cb7bb815d2ad7945e63214d21cec1d70152ba6abMarkus Knetschke the same as the source path on the host. When combined with
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt the <option>--read-only</option> switch, a ready-only bind
cb7bb815d2ad7945e63214d21cec1d70152ba6abMarkus Knetschke mount is created. When combined with the
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt <option>--mkdir</option> switch, the destination path is first
cb7bb815d2ad7945e63214d21cec1d70152ba6abMarkus Knetschke created before the mount is applied. Note that this option is
cb7bb815d2ad7945e63214d21cec1d70152ba6abMarkus Knetschke 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
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt 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.
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt 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
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt run a container off one of the listed images. Note that, by
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt 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>
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering <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>
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering <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
3fe22bb4b6b5faf27683ad2e231b5a69b6e63a9eLennart Poettering to file system limitations.</para>
3fe22bb4b6b5faf27683ad2e231b5a69b6e63a9eLennart Poettering <para>Note that this command leaves host name, machine ID and
3fe22bb4b6b5faf27683ad2e231b5a69b6e63a9eLennart Poettering all other settings that could identify the instance
3fe22bb4b6b5faf27683ad2e231b5a69b6e63a9eLennart Poettering unmodified. The original image and the cloned copy will hence
3fe22bb4b6b5faf27683ad2e231b5a69b6e63a9eLennart Poettering share these credentials, and it might be necessary to manually
3fe22bb4b6b5faf27683ad2e231b5a69b6e63a9eLennart Poettering change them in the copy.</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
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt 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>
a8eaaee72a2f06e0fb64fb71de3b71ecba31dafbJan Engelhardt <listitem><para>Sets the maximum size in bytes that a specific
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt 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
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt specified, the size limit of the specified image is changed. If
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt 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
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt on btrfs file systems. Also note that, if
a8eaaee72a2f06e0fb64fb71de3b71ecba31dafbJan Engelhardt <command>set-limit</command> is invoked without an 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>
a8eaaee72a2f06e0fb64fb71de3b71ecba31dafbJan Engelhardt directory is used, <command>set-limit</command> without an 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>
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt archive file. If the local machine name is omitted, 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
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt 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
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt <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
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt <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
12b42c76672a66c2d4ea7212c14f8f1b5a62b78dTom Gundersen <filename>/usr/lib/systemd/import-pubring.gpg</filename> or
12b42c76672a66c2d4ea7212c14f8f1b5a62b78dTom Gundersen <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
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt <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
dd2b607b7d1ce355e93f9f71cd256ec20b8ae9c4Thomas Hindoe Paaboel Andersen local name. This behavior 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
6b94875fa3a7280e7f1c0df11027b927b6961edeRichard Maw <filename>.tar-</filename>, and is 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
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
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt 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>
1d3eaa93616a2e9f6568b754a65c884766bac6c4Jay Strict <para>If the downloaded image is in
6b94875fa3a7280e7f1c0df11027b927b6961edeRichard Maw <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>
dd2b607b7d1ce355e93f9f71cd256ec20b8ae9c4Thomas Hindoe Paaboel Andersen <para>Similar to the behavior of <command>pull-tar</command>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek the read-only image is prefixed with
6b94875fa3a7280e7f1c0df11027b927b6961edeRichard Maw <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
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
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt <command>import-tar</command> is used, the file specified as
a8eaaee72a2f06e0fb64fb71de3b71ecba31dafbJan Engelhardt the 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
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt <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
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt not specified, it is automatically derived from the file
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt 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>
ace483c471710ca52b2c5e6a52aeba178bf4ac26Jan Engelhardt <para>Both <command>pull-tar</command> and <command>pull-raw</command>
ace483c471710ca52b2c5e6a52aeba178bf4ac26Jan Engelhardt will resize <filename>/var/lib/machines.raw</filename> and the
ace483c471710ca52b2c5e6a52aeba178bf4ac26Jan Engelhardt filesystem therein as necessary. 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
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt in <literal>.gz</literal>, the file is compressed with gzip, if
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt it ends in <literal>.xz</literal>, with xz, and if it ends in
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt <literal>.bz2</literal>, with bzip2. If the path ends in
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt neither, the file is left uncompressed. If the second argument
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt 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>
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt <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>
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering <para>The <command>machinectl</command> tool operates on machines
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt and images whose names must be chosen following strict
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering rules. Machine names must be suitable for use as host names
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering following a conservative subset of DNS and UNIX/Linux
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering semantics. Specifically, they must consist of one or more
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering non-empty label strings, separated by dots. No leading or trailing
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering dots are allowed. No sequences of multiple dots are allowed. The
a8eaaee72a2f06e0fb64fb71de3b71ecba31dafbJan Engelhardt label strings may only consist of alphanumeric characters as well
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering as the dash and underscore. The maximum length of a machine name
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering is 64 characters.</para>
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering <para>A special machine with the name <literal>.host</literal>
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering refers to the running host system itself. This is useful for execution
a8eaaee72a2f06e0fb64fb71de3b71ecba31dafbJan Engelhardt operations or inspecting the host system as well. Note that
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering <command>machinectl list</command> will not show this special
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering machine unless the <option>--all</option> switch is specified.</para>
a8eaaee72a2f06e0fb64fb71de3b71ecba31dafbJan Engelhardt <para>Requirements on image names are less strict, however, they 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>
a8eaaee72a2f06e0fb64fb71de3b71ecba31dafbJan Engelhardt refers to the image of the running host system. It hence
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering conceptually maps to the special <literal>.host</literal> machine
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering name described above. Note that <command>machinectl
7ca4155737730ece73ae4b4ac80571005cb99b69Jan Engelhardt list-images</command> will not show this special image either, unless
91913f584af38b29a816cca959ba648acd60ac9fLennart Poettering <option>--all</option> is specified.</para>
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
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt <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>,
b43d75c378d919900e5c1e82a82e3e17dd3de9f9Lennart Poettering <command>import-tar</command>, <command>import-raw</command> and
b43d75c378d919900e5c1e82a82e3e17dd3de9f9Lennart Poettering <command>set-limit</command> commands notice that
b43d75c378d919900e5c1e82a82e3e17dd3de9f9Lennart Poettering <filename>/var/lib/machines</filename> is empty and not located on
b43d75c378d919900e5c1e82a82e3e17dd3de9f9Lennart Poettering btrfs, they will implicitly set up a loopback file
b43d75c378d919900e5c1e82a82e3e17dd3de9f9Lennart Poettering <filename>/var/lib/machines.raw</filename> containing a btrfs file
b43d75c378d919900e5c1e82a82e3e17dd3de9f9Lennart Poettering 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>
a8eaaee72a2f06e0fb64fb71de3b71ecba31dafbJan Engelhardt <listitem><para>Subvolumes (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>
a8eaaee72a2f06e0fb64fb71de3b71ecba31dafbJan Engelhardt for more information on image formats, in particular its
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>
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt 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>
6e9efa59209d48fc69a456fbadb2b5c113f503a6Lennart Poettering <title>Exports a container image as tar file</title>
6e9efa59209d48fc69a456fbadb2b5c113f503a6Lennart Poettering <programlisting># machinectl export-tar fedora myfedora.tar.xz</programlisting>
a8eaaee72a2f06e0fb64fb71de3b71ecba31dafbJan Engelhardt <para>Exports the container <literal>fedora</literal> as an
a8eaaee72a2f06e0fb64fb71de3b71ecba31dafbJan Engelhardt xz-compressed tar file <filename>myfedora.tar.xz</filename> into the
6e9efa59209d48fc69a456fbadb2b5c113f503a6Lennart Poettering current directory.</para>
ef3100e9637adda26fa19e7ee8606788320dcde3Lennart Poettering <title>Create a new shell session</title>
ef3100e9637adda26fa19e7ee8606788320dcde3Lennart Poettering <programlisting># machinectl shell --uid=lennart</programlisting>
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt <para>This creates a new shell session on the local host for
ef3100e9637adda26fa19e7ee8606788320dcde3Lennart Poettering the user ID <literal>lennart</literal>, in a <citerefentry
ef3100e9637adda26fa19e7ee8606788320dcde3Lennart Poettering project='die-net'><refentrytitle>su</refentrytitle><manvolnum>1</manvolnum></citerefentry>-like
ef3100e9637adda26fa19e7ee8606788320dcde3Lennart Poettering fashion.</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>