man/machinectl.xml

   1 <?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6   This file is part of systemd.
   7
   8   Copyright 2013 Zbigniew Jędrzejewski-Szmek
   9
  10   systemd is free software; you can redistribute it and/or modify it
  11   under the terms of the GNU Lesser General Public License as published by
  12   the Free Software Foundation; either version 2.1 of the License, or
  13   (at your option) any later version.
  14
  15   systemd is distributed in the hope that it will be useful, but
  16   WITHOUT ANY WARRANTY; without even the implied warranty of
  17   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  18   Lesser General Public License for more details.
  19
  20   You should have received a copy of the GNU Lesser General Public License
  21   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  22 -->
  23
  24 <refentry id="machinectl" conditional='ENABLE_MACHINED'
  25     xmlns:xi="http://www.w3.org/2001/XInclude">
  26
  27   <refentryinfo>
  28     <title>machinectl</title>
  29     <productname>systemd</productname>
  30
  31     <authorgroup>
  32       <author>
  33         <contrib>Developer</contrib>
  34         <firstname>Lennart</firstname>
  35         <surname>Poettering</surname>
  36         <email>lennart@poettering.net</email>
  37       </author>
  38     </authorgroup>
  39   </refentryinfo>
  40
  41   <refmeta>
  42     <refentrytitle>machinectl</refentrytitle>
  43     <manvolnum>1</manvolnum>
  44   </refmeta>
  45
  46   <refnamediv>
  47     <refname>machinectl</refname>
  48     <refpurpose>Control the systemd machine manager</refpurpose>
  49   </refnamediv>
  50
  51   <refsynopsisdiv>
  52     <cmdsynopsis>
  53       <command>machinectl</command>
  54       <arg choice="opt" rep="repeat">OPTIONS</arg>
  55       <arg choice="req">COMMAND</arg>
  56       <arg choice="opt" rep="repeat">NAME</arg>
  57     </cmdsynopsis>
  58   </refsynopsisdiv>
  59
  60   <refsect1>
  61     <title>Description</title>
  62
  63     <para><command>machinectl</command> may be used to introspect and
  64     control the state of the
  65     <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
  66     virtual machine and container registration manager
  67     <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
  68
  69     <para><command>machinectl</command> may be used to execute
  70     operations on machines and images. Machines in this sense are
  71     considered running instances of:</para>
  72
  73     <itemizedlist>
  74       <listitem><para>Virtual Machines (VMs) that virtualize hardware
  75       to run full operating system (OS) instances (including their kernels)
  76       in a virtualized environment on top of the host OS.</para></listitem>
  77
  78       <listitem><para>Containers that share the hardware and
  79       OS kernel with the host OS, in order to run
  80       OS userspace instances on top the host OS.</para></listitem>
  81
  82       <listitem><para>The host system itself</para></listitem>
  83     </itemizedlist>
  84
  85     <para>Machines are identified by names that follow the same rules
  86     as UNIX and DNS host names, for details, see below. Machines are
  87     instantiated from disk or file system images that frequently — but not
  88     necessarily — carry the same name as machines running from
  89     them. Images in this sense are considered:</para>
  90
  91     <itemizedlist>
  92       <listitem><para>Directory trees containing an OS, including its
  93       top-level directories <filename>/usr</filename>,
  94       <filename>/etc</filename>, and so on.</para></listitem>
  95
  96       <listitem><para>btrfs subvolumes containing OS trees, similar to
  97       normal directory trees.</para></listitem>
  98
  99       <listitem><para>Binary "raw" disk images containing MBR or GPT
 100       partition tables and Linux file system partitions.</para></listitem>
 101
 102       <listitem><para>The file system tree of the host OS itself.</para></listitem>
 103     </itemizedlist>
 104
 105   </refsect1>
 106
 107   <refsect1>
 108     <title>Options</title>
 109
 110     <para>The following options are understood:</para>
 111
 112     <variablelist>
 113       <varlistentry>
 114         <term><option>-p</option></term>
 115         <term><option>--property=</option></term>
 116
 117         <listitem><para>When showing machine or image properties,
 118         limit the output to certain properties as specified by the
 119         argument. If not specified, all set properties are shown. The
 120         argument should be a property name, such as
 121         <literal>Name</literal>. If specified more than once, all
 122         properties with the specified names are
 123         shown.</para></listitem>
 124       </varlistentry>
 125
 126       <varlistentry>
 127         <term><option>-a</option></term>
 128         <term><option>--all</option></term>
 129
 130         <listitem><para>When showing machine or image properties, show
 131         all properties regardless of whether they are set or
 132         not.</para>
 133
 134         <para>When listing VM or container images, do not suppress
 135         images beginning in a dot character
 136         (<literal>.</literal>).</para>
 137
 138         <para>When cleaning VM or container images, remove all images, not just hidden ones.</para></listitem>
 139       </varlistentry>
 140
 141        <varlistentry>
 142         <term><option>--value</option></term>
 143
 144         <listitem><para>When printing properties with <command>show</command>, only print the value,
 145         and skip the property name and <literal>=</literal>.</para></listitem>
 146       </varlistentry>
 147
 148       <varlistentry>
 149         <term><option>-l</option></term>
 150         <term><option>--full</option></term>
 151
 152         <listitem><para>Do not ellipsize process tree entries.</para>
 153         </listitem>
 154       </varlistentry>
 155
 156       <varlistentry>
 157         <term><option>--no-ask-password</option></term>
 158
 159         <listitem><para>Do not query the user for authentication for
 160         privileged operations.</para></listitem>
 161       </varlistentry>
 162
 163       <varlistentry>
 164         <term><option>--kill-who=</option></term>
 165
 166         <listitem><para>When used with <command>kill</command>, choose
 167         which processes to kill. Must be one of
 168         <option>leader</option>, or <option>all</option> to select
 169         whether to kill only the leader process of the machine or all
 170         processes of the machine. If omitted, defaults to
 171         <option>all</option>.</para></listitem>
 172       </varlistentry>
 173
 174       <varlistentry>
 175         <term><option>-s</option></term>
 176         <term><option>--signal=</option></term>
 177
 178         <listitem><para>When used with <command>kill</command>, choose
 179         which signal to send to selected processes. Must be one of the
 180         well-known signal specifiers, such as
 181         <constant>SIGTERM</constant>, <constant>SIGINT</constant> or
 182         <constant>SIGSTOP</constant>. If omitted, defaults to
 183         <constant>SIGTERM</constant>.</para></listitem>
 184       </varlistentry>
 185
 186       <varlistentry>
 187          <term><option>--uid=</option></term>
 188
 189          <listitem><para>When used with the <command>shell</command> command, chooses the user ID to
 190          open the interactive shell session as. If the argument to the <command>shell</command>
 191          command also specifies a user name, this option is ignored. If the name is not specified
 192          in either way, <literal>root</literal> will be used by default. Note that this switch is
 193          not supported for the <command>login</command> command (see below).</para></listitem>
 194       </varlistentry>
 195
 196       <varlistentry>
 197         <term><option>-E <replaceable>NAME</replaceable>=<replaceable>VALUE</replaceable></option></term>
 198         <term><option>--setenv=<replaceable>NAME</replaceable>=<replaceable>VALUE</replaceable></option></term>
 199
 200          <listitem><para>When used with the <command>shell</command> command, sets an environment
 201          variable to pass to the executed shell. Takes an environment variable name and value,
 202          separated by <literal>=</literal>. This switch may be used multiple times to set multiple
 203          environment variables. Note that this switch is not supported for the
 204          <command>login</command> command (see below).</para></listitem>
 205       </varlistentry>
 206
 207       <varlistentry>
 208         <term><option>--mkdir</option></term>
 209
 210         <listitem><para>When used with <command>bind</command>, creates
 211         the destination directory before applying the bind
 212         mount.</para></listitem>
 213       </varlistentry>
 214
 215       <varlistentry>
 216         <term><option>--read-only</option></term>
 217
 218         <listitem><para>When used with <command>bind</command>, applies
 219         a read-only bind mount.</para>
 220
 221         <para>When used with <command>clone</command>, <command>import-raw</command> or <command>import-tar</command> a
 222         read-only container or VM image is created.</para></listitem>
 223       </varlistentry>
 224
 225       <varlistentry>
 226         <term><option>-n</option></term>
 227         <term><option>--lines=</option></term>
 228
 229         <listitem><para>When used with <command>status</command>,
 230         controls the number of journal lines to show, counting from
 231         the most recent ones. Takes a positive integer argument.
 232         Defaults to 10.</para>
 233         </listitem>
 234       </varlistentry>
 235
 236       <varlistentry>
 237         <term><option>-o</option></term>
 238         <term><option>--output=</option></term>
 239
 240         <listitem><para>When used with <command>status</command>,
 241         controls the formatting of the journal entries that are shown.
 242         For the available choices, see
 243         <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 244         Defaults to <literal>short</literal>.</para></listitem>
 245       </varlistentry>
 246
 247       <varlistentry>
 248         <term><option>--verify=</option></term>
 249
 250         <listitem><para>When downloading a container or VM image,
 251         specify whether the image shall be verified before it is made
 252         available. Takes one of <literal>no</literal>,
 253         <literal>checksum</literal> and <literal>signature</literal>.
 254         If <literal>no</literal>, no verification is done. If
 255         <literal>checksum</literal> is specified, the download is
 256         checked for integrity after the transfer is complete, but no
 257         signatures are verified. If <literal>signature</literal> is
 258         specified, the checksum is verified and the image's signature
 259         is checked against a local keyring of trustable vendors. It is
 260         strongly recommended to set this option to
 261         <literal>signature</literal> if the server and protocol
 262         support this. Defaults to
 263         <literal>signature</literal>.</para></listitem>
 264       </varlistentry>
 265
 266       <varlistentry>
 267         <term><option>--force</option></term>
 268
 269         <listitem><para>When downloading a container or VM image, and
 270         a local copy by the specified local machine name already
 271         exists, delete it first and replace it by the newly downloaded
 272         image.</para></listitem>
 273       </varlistentry>
 274
 275       <varlistentry>
 276         <term><option>--format=</option></term>
 277
 278         <listitem><para>When used with the <option>export-tar</option>
 279         or <option>export-raw</option> commands, specifies the
 280         compression format to use for the resulting file. Takes one of
 281         <literal>uncompressed</literal>, <literal>xz</literal>,
 282         <literal>gzip</literal>, <literal>bzip2</literal>. By default,
 283         the format is determined automatically from the image file
 284         name passed.</para></listitem>
 285       </varlistentry>
 286
 287       <varlistentry>
 288         <term><option>--max-addresses=</option></term>
 289
 290         <listitem><para>When used with the <option>list-machines</option>
 291         command, limits the number of ip addresses output for every machine.
 292         Defaults to 1. All addresses can be requested with <literal>all</literal>
 293         as argument to <option>--max-addresses</option> . If the argument to
 294         <option>--max-addresses</option> is less than the actual number
 295         of addresses, <literal>...</literal>follows the last address.
 296         If multiple addresses are to be written for a given machine, every
 297         address except the first one is on a new line and is followed by
 298         <literal>,</literal> if another address will be output afterwards. </para></listitem>
 299       </varlistentry>
 300
 301       <xi:include href="user-system-options.xml" xpointer="host" />
 302       <xi:include href="user-system-options.xml" xpointer="machine" />
 303
 304       <xi:include href="standard-options.xml" xpointer="no-pager" />
 305       <xi:include href="standard-options.xml" xpointer="no-legend" />
 306       <xi:include href="standard-options.xml" xpointer="help" />
 307       <xi:include href="standard-options.xml" xpointer="version" />
 308     </variablelist>
 309   </refsect1>
 310
 311   <refsect1>
 312     <title>Commands</title>
 313
 314     <para>The following commands are understood:</para>
 315
 316     <refsect2><title>Machine Commands</title><variablelist>
 317
 318       <varlistentry>
 319         <term><command>list</command></term>
 320
 321         <listitem><para>List currently running (online) virtual
 322         machines and containers. To enumerate machine images that can
 323         be started, use <command>list-images</command> (see
 324         below). Note that this command hides the special
 325         <literal>.host</literal> machine by default. Use the
 326         <option>--all</option> switch to show it.</para></listitem>
 327       </varlistentry>
 328
 329       <varlistentry>
 330         <term><command>status</command> <replaceable>NAME</replaceable>…</term>
 331
 332         <listitem><para>Show runtime status information about
 333         one or more virtual machines and containers, followed by the
 334         most recent log data from the journal. This function is
 335         intended to generate human-readable output. If you are looking
 336         for computer-parsable output, use <command>show</command>
 337         instead. Note that the log data shown is reported by the
 338         virtual machine or container manager, and frequently contains
 339         console output of the machine, but not necessarily journal
 340         contents of the machine itself.</para></listitem>
 341       </varlistentry>
 342
 343       <varlistentry>
 344         <term><command>show</command> [<replaceable>NAME</replaceable>…]</term>
 345
 346         <listitem><para>Show properties of one or more registered virtual machines or containers or the manager
 347         itself. If no argument is specified, properties of the manager will be shown. If a NAME is specified,
 348         properties of this virtual machine or container are shown. By default, empty properties are suppressed. Use
 349         <option>--all</option> to show those too.  To select specific properties to show, use
 350         <option>--property=</option>. This command is intended to be used whenever computer-parsable output is
 351         required, and does not print the control group tree or journal entries. Use <command>status</command> if you
 352         are looking for formatted human-readable output.</para></listitem>
 353       </varlistentry>
 354
 355       <varlistentry>
 356         <term><command>start</command> <replaceable>NAME</replaceable>…</term>
 357
 358         <listitem><para>Start a container as a system service, using
 359         <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 360         This starts <filename>systemd-nspawn@.service</filename>,
 361         instantiated for the specified machine name, similar to the
 362         effect of <command>systemctl start</command> on the service
 363         name. <command>systemd-nspawn</command> looks for a container
 364         image by the specified name in
 365         <filename>/var/lib/machines/</filename> (and other search
 366         paths, see below) and runs it. Use
 367         <command>list-images</command> (see below) for listing
 368         available container images to start.</para>
 369
 370         <para>Note that
 371         <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 372         also interfaces with a variety of other container and VM
 373         managers, <command>systemd-nspawn</command> is just one
 374         implementation of it. Most of the commands available in
 375         <command>machinectl</command> may be used on containers or VMs
 376         controlled by other managers, not just
 377         <command>systemd-nspawn</command>. Starting VMs and container
 378         images on those managers requires manager-specific
 379         tools.</para>
 380
 381         <para>To interactively start a container on the command line
 382         with full access to the container's console, please invoke
 383         <command>systemd-nspawn</command> directly. To stop a running
 384         container use <command>machinectl poweroff</command>.</para></listitem>
 385       </varlistentry>
 386
 387       <varlistentry>
 388         <term><command>login</command> [<replaceable>NAME</replaceable>]</term>
 389
 390         <listitem><para>Open an interactive terminal login session in
 391         a container or on the local host. If an argument is supplied,
 392         it refers to the container machine to connect to. If none is
 393         specified, or the container name is specified as the empty
 394         string, or the special machine name <literal>.host</literal>
 395         (see below) is specified, the connection is made to the local
 396         host instead. This will create a TTY connection to a specific
 397         container or the local host and asks for the execution of a
 398         getty on it. Note that this is only supported for containers
 399         running
 400         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 401         as init system.</para>
 402
 403         <para>This command will open a full login prompt on the
 404         container or the local host, which then asks for username and
 405         password. Use <command>shell</command> (see below) or
 406         <citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 407         with the <option>--machine=</option> switch to directly invoke
 408         a single command, either interactively or in the
 409         background.</para></listitem>
 410       </varlistentry>
 411
 412       <varlistentry>
 413         <term><command>shell</command> [[<replaceable>NAME</replaceable>@]<replaceable>NAME</replaceable> [<replaceable>PATH</replaceable> [<replaceable>ARGUMENTS</replaceable>…]]] </term>
 414
 415         <listitem><para>Open an interactive shell session in a
 416         container or on the local host. The first argument refers to
 417         the container machine to connect to. If none is specified, or
 418         the machine name is specified as the empty string, or the
 419         special machine name <literal>.host</literal> (see below) is
 420         specified, the connection is made to the local host
 421         instead. This works similar to <command>login</command> but
 422         immediately invokes a user process. This command runs the
 423         specified executable with the specified arguments, or
 424         <filename>/bin/sh</filename> if none is specified. By default,
 425         opens a <literal>root</literal> shell, but by using
 426         <option>--uid=</option>, or by prefixing the machine name with
 427         a username and an <literal>@</literal> character, a different
 428         user may be selected. Use <option>--setenv=</option> to set
 429         environment variables for the executed process.</para>
 430
 431         <para>Note that <command>machinectl shell</command> does not propagate the exit code/status of the invoked
 432         shell process. Use <command>systemd-run</command> instead if that information is required (see below).</para>
 433
 434         <para>When using the <command>shell</command> command without
 435         arguments, (thus invoking the executed shell or command on the
 436         local host), it is in many ways similar to a <citerefentry
 437         project='die-net'><refentrytitle>su</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 438         session, but, unlike <command>su</command>, completely isolates
 439         the new session from the originating session, so that it
 440         shares no process or session properties, and is in a clean and
 441         well-defined state. It will be tracked in a new utmp, login,
 442         audit, security and keyring session, and will not inherit any
 443         environment variables or resource limits, among other
 444         properties.</para>
 445
 446         <para>Note that <citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 447         with its <option>--machine=</option> switch may be used in place of the <command>machinectl shell</command>
 448         command, and allows non-interactive operation, more detailed and low-level configuration of the invoked unit,
 449         as well as access to runtime and exit code/status information of the invoked shell process. In particular, use
 450         <command>systemd-run</command>'s <option>--wait</option> switch to propagate exit status information of the
 451         invoked process. Use <command>systemd-run</command>'s <option>--pty</option> switch for acquiring an
 452         interactive shell, similar to <command>machinectl shell</command>. In general, <command>systemd-run</command>
 453         is preferable for scripting purposes. However, note that <command>systemd-run</command> might require higher
 454         privileges than <command>machinectl shell</command>.</para></listitem>
 455       </varlistentry>
 456
 457       <varlistentry>
 458         <term><command>enable</command> <replaceable>NAME</replaceable>…</term>
 459         <term><command>disable</command> <replaceable>NAME</replaceable>…</term>
 460
 461         <listitem><para>Enable or disable a container as a system
 462         service to start at system boot, using
 463         <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 464         This enables or disables
 465         <filename>systemd-nspawn@.service</filename>, instantiated for
 466         the specified machine name, similar to the effect of
 467         <command>systemctl enable</command> or <command>systemctl
 468         disable</command> on the service name.</para></listitem>
 469       </varlistentry>
 470
 471       <varlistentry>
 472         <term><command>poweroff</command> <replaceable>NAME</replaceable>…</term>
 473
 474         <listitem><para>Power off one or more containers. This will
 475         trigger a reboot by sending SIGRTMIN+4 to the container's init
 476         process, which causes systemd-compatible init systems to shut
 477         down cleanly. Use <command>stop</command> as alias for <command>poweroff</command>.
 478         This operation does not work on containers that do not run a
 479         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>-compatible
 480         init system, such as sysvinit. Use
 481         <command>terminate</command> (see below) to immediately
 482         terminate a container or VM, without cleanly shutting it
 483         down.</para></listitem>
 484       </varlistentry>
 485
 486       <varlistentry>
 487         <term><command>reboot</command> <replaceable>NAME</replaceable>…</term>
 488
 489         <listitem><para>Reboot one or more containers. This will
 490         trigger a reboot by sending SIGINT to the container's init
 491         process, which is roughly equivalent to pressing Ctrl+Alt+Del
 492         on a non-containerized system, and is compatible with
 493         containers running any system manager.</para></listitem>
 494       </varlistentry>
 495
 496       <varlistentry>
 497         <term><command>terminate</command> <replaceable>NAME</replaceable>…</term>
 498
 499         <listitem><para>Immediately terminates a virtual machine or
 500         container, without cleanly shutting it down. This kills all
 501         processes of the virtual machine or container and deallocates
 502         all resources attached to that instance. Use
 503         <command>poweroff</command> to issue a clean shutdown
 504         request.</para></listitem>
 505       </varlistentry>
 506
 507       <varlistentry>
 508         <term><command>kill</command> <replaceable>NAME</replaceable>…</term>
 509
 510         <listitem><para>Send a signal to one or more processes of the
 511         virtual machine or container. This means processes as seen by
 512         the host, not the processes inside the virtual machine or
 513         container. Use <option>--kill-who=</option> to select which
 514         process to kill. Use <option>--signal=</option> to select the
 515         signal to send.</para></listitem>
 516       </varlistentry>
 517
 518       <varlistentry>
 519         <term><command>bind</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term>
 520
 521         <listitem><para>Bind mounts a directory from the host into the
 522         specified container. The first directory argument is the
 523         source directory on the host, the second directory argument
 524         is the destination directory in the container. When the
 525         latter is omitted, the destination path in the container is
 526         the same as the source path on the host. When combined with
 527         the <option>--read-only</option> switch, a ready-only bind
 528         mount is created. When combined with the
 529         <option>--mkdir</option> switch, the destination path is first
 530         created before the mount is applied. Note that this option is
 531         currently only supported for
 532         <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 533         containers.</para></listitem>
 534       </varlistentry>
 535
 536       <varlistentry>
 537         <term><command>copy-to</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term>
 538
 539         <listitem><para>Copies files or directories from the host
 540         system into a running container. Takes a container name,
 541         followed by the source path on the host and the destination
 542         path in the container. If the destination path is omitted, the
 543         same as the source path is used.</para></listitem>
 544       </varlistentry>
 545
 546
 547       <varlistentry>
 548         <term><command>copy-from</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term>
 549
 550         <listitem><para>Copies files or directories from a container
 551         into the host system. Takes a container name, followed by the
 552         source path in the container the destination path on the host.
 553         If the destination path is omitted, the same as the source path
 554         is used.</para></listitem>
 555       </varlistentry>
 556     </variablelist></refsect2>
 557
 558     <refsect2><title>Image Commands</title><variablelist>
 559
 560       <varlistentry>
 561         <term><command>list-images</command></term>
 562
 563         <listitem><para>Show a list of locally installed container and
 564         VM images. This enumerates all raw disk images and container
 565         directories and subvolumes in
 566         <filename>/var/lib/machines/</filename> (and other search
 567         paths, see below). Use <command>start</command> (see above) to
 568         run a container off one of the listed images. Note that, by
 569         default, containers whose name begins with a dot
 570         (<literal>.</literal>) are not shown. To show these too,
 571         specify <option>--all</option>. Note that a special image
 572         <literal>.host</literal> always implicitly exists and refers
 573         to the image the host itself is booted from.</para></listitem>
 574       </varlistentry>
 575
 576       <varlistentry>
 577         <term><command>image-status</command> [<replaceable>NAME</replaceable>…]</term>
 578
 579         <listitem><para>Show terse status information about one or
 580         more container or VM images. This function is intended to
 581         generate human-readable output. Use
 582         <command>show-image</command> (see below) to generate
 583         computer-parsable output instead.</para></listitem>
 584       </varlistentry>
 585
 586       <varlistentry>
 587         <term><command>show-image</command> [<replaceable>NAME</replaceable>…]</term>
 588
 589         <listitem><para>Show properties of one or more registered
 590         virtual machine or container images, or the manager itself. If
 591         no argument is specified, properties of the manager will be
 592         shown. If a NAME is specified, properties of this virtual
 593         machine or container image are shown. By default, empty
 594         properties are suppressed. Use <option>--all</option> to show
 595         those too. To select specific properties to show, use
 596         <option>--property=</option>. This command is intended to be
 597         used whenever computer-parsable output is required. Use
 598         <command>image-status</command> if you are looking for
 599         formatted human-readable output.</para></listitem>
 600       </varlistentry>
 601
 602       <varlistentry>
 603         <term><command>clone</command> <replaceable>NAME</replaceable> <replaceable>NAME</replaceable></term>
 604
 605         <listitem><para>Clones a container or VM image. The arguments specify the name of the image to clone and the
 606         name of the newly cloned image. Note that plain directory container images are cloned into btrfs subvolume
 607         images with this command, if the underlying file system supports this.  Note that cloning a container or VM
 608         image is optimized for file systems that support copy-on-write, and might not be efficient on others, due to
 609         file system limitations.</para>
 610
 611         <para>Note that this command leaves host name, machine ID and
 612         all other settings that could identify the instance
 613         unmodified. The original image and the cloned copy will hence
 614         share these credentials, and it might be necessary to manually
 615         change them in the copy.</para>
 616
 617         <para>If combined with the <option>--read-only</option> switch a read-only cloned image is
 618         created.</para></listitem>
 619       </varlistentry>
 620
 621       <varlistentry>
 622         <term><command>rename</command> <replaceable>NAME</replaceable> <replaceable>NAME</replaceable></term>
 623
 624         <listitem><para>Renames a container or VM image. The
 625         arguments specify the name of the image to rename and the new
 626         name of the image.</para></listitem>
 627       </varlistentry>
 628
 629       <varlistentry>
 630         <term><command>read-only</command> <replaceable>NAME</replaceable> [<replaceable>BOOL</replaceable>]</term>
 631
 632         <listitem><para>Marks or (unmarks) a container or VM image
 633         read-only. Takes a VM or container image name, followed by a
 634         boolean as arguments. If the boolean is omitted, positive is
 635         implied, i.e. the image is marked read-only.</para></listitem>
 636       </varlistentry>
 637
 638       <varlistentry>
 639         <term><command>remove</command> <replaceable>NAME</replaceable>…</term>
 640
 641         <listitem><para>Removes one or more container or VM images.
 642         The special image <literal>.host</literal>, which refers to
 643         the host's own directory tree, may not be
 644         removed.</para></listitem>
 645       </varlistentry>
 646
 647       <varlistentry>
 648         <term><command>set-limit</command> [<replaceable>NAME</replaceable>] <replaceable>BYTES</replaceable></term>
 649
 650         <listitem><para>Sets the maximum size in bytes that a specific
 651         container or VM image, or all images, may grow up to on disk
 652         (disk quota). Takes either one or two parameters. The first,
 653         optional parameter refers to a container or VM image name. If
 654         specified, the size limit of the specified image is changed. If
 655         omitted, the overall size limit of the sum of all images stored
 656         locally is changed. The final argument specifies the size
 657         limit in bytes, possibly suffixed by the usual K, M, G, T
 658         units. If the size limit shall be disabled, specify
 659         <literal>-</literal> as size.</para>
 660
 661         <para>Note that per-container size limits are only supported
 662         on btrfs file systems. Also note that, if
 663         <command>set-limit</command> is invoked without an image
 664         parameter, and <filename>/var/lib/machines</filename> is
 665         empty, and the directory is not located on btrfs, a btrfs
 666         loopback file is implicitly created as
 667         <filename>/var/lib/machines.raw</filename> with the given
 668         size, and mounted to
 669         <filename>/var/lib/machines</filename>. The size of the
 670         loopback may later be readjusted with
 671         <command>set-limit</command>, as well. If such a
 672         loopback-mounted <filename>/var/lib/machines</filename>
 673         directory is used, <command>set-limit</command> without an image
 674         name alters both the quota setting within the file system as
 675         well as the loopback file and file system size
 676         itself.</para></listitem>
 677       </varlistentry>
 678
 679       <varlistentry>
 680         <term><command>clean</command></term>
 681
 682         <listitem><para>Remove hidden VM or container images (or all). This command removes all hidden machine images
 683         from <filename>/var/lib/machines</filename>, i.e. those whose name begins with a dot. Use <command>machinectl
 684         list-images --all</command> to see a list of all machine images, including the hidden ones.</para>
 685
 686         <para>When combined with the <option>--all</option> switch removes all images, not just hidden ones. This
 687         command effectively empties <filename>/var/lib/machines</filename>.</para>
 688
 689         <para>Note that commands such as <command>machinectl pull-tar</command> or <command>machinectl
 690         pull-raw</command> usually create hidden, read-only, unmodified machine images from the downloaded image first,
 691         before cloning a writable working copy of it, in order to avoid duplicate downloads in case of images that are
 692         reused multiple times. Use <command>machinectl clean</command> to remove old, hidden images created this
 693         way.</para></listitem>
 694       </varlistentry>
 695
 696     </variablelist></refsect2>
 697
 698     <refsect2><title>Image Transfer Commands</title><variablelist>
 699
 700       <varlistentry>
 701         <term><command>pull-tar</command> <replaceable>URL</replaceable> [<replaceable>NAME</replaceable>]</term>
 702
 703         <listitem><para>Downloads a <filename>.tar</filename>
 704         container image from the specified URL, and makes it available
 705         under the specified local machine name. The URL must be of
 706         type <literal>http://</literal> or
 707         <literal>https://</literal>, and must refer to a
 708         <filename>.tar</filename>, <filename>.tar.gz</filename>,
 709         <filename>.tar.xz</filename> or <filename>.tar.bz2</filename>
 710         archive file. If the local machine name is omitted, it
 711         is automatically derived from the last component of the URL,
 712         with its suffix removed.</para>
 713
 714         <para>The image is verified before it is made available,
 715         unless <option>--verify=no</option> is specified. Verification
 716         is done via SHA256SUMS and SHA256SUMS.gpg files that need to
 717         be made available on the same web server, under the same URL
 718         as the <filename>.tar</filename> file, but with the last
 719         component (the filename) of the URL replaced. With
 720         <option>--verify=checksum</option>, only the SHA256 checksum
 721         for the file is verified, based on the
 722         <filename>SHA256SUMS</filename> file. With
 723         <option>--verify=signature</option>, the SHA256SUMS file is
 724         first verified with detached GPG signature file
 725         <filename>SHA256SUMS.gpg</filename>. The public key for this
 726         verification step needs to be available in
 727         <filename>/usr/lib/systemd/import-pubring.gpg</filename> or
 728         <filename>/etc/systemd/import-pubring.gpg</filename>.</para>
 729
 730         <para>The container image will be downloaded and stored in a
 731         read-only subvolume in
 732         <filename>/var/lib/machines/</filename> that is named after
 733         the specified URL and its HTTP etag. A writable snapshot is
 734         then taken from this subvolume, and named after the specified
 735         local name. This behavior ensures that creating multiple
 736         container instances of the same URL is efficient, as multiple
 737         downloads are not necessary. In order to create only the
 738         read-only image, and avoid creating its writable snapshot,
 739         specify <literal>-</literal> as local machine name.</para>
 740
 741         <para>Note that the read-only subvolume is prefixed with
 742         <filename>.tar-</filename>, and is thus not shown by
 743         <command>list-images</command>, unless <option>--all</option>
 744         is passed.</para>
 745
 746         <para>Note that pressing C-c during execution of this command
 747         will not abort the download. Use
 748         <command>cancel-transfer</command>, described
 749         below.</para></listitem>
 750       </varlistentry>
 751
 752       <varlistentry>
 753         <term><command>pull-raw</command> <replaceable>URL</replaceable> [<replaceable>NAME</replaceable>]</term>
 754
 755         <listitem><para>Downloads a <filename>.raw</filename>
 756         container or VM disk image from the specified URL, and makes
 757         it available under the specified local machine name. The URL
 758         must be of type <literal>http://</literal> or
 759         <literal>https://</literal>. The container image must either
 760         be a <filename>.qcow2</filename> or raw disk image, optionally
 761         compressed as <filename>.gz</filename>,
 762         <filename>.xz</filename>, or <filename>.bz2</filename>. If the
 763         local machine name is omitted, it is automatically
 764         derived from the last component of the URL, with its suffix
 765         removed.</para>
 766
 767         <para>Image verification is identical for raw and tar images
 768         (see above).</para>
 769
 770         <para>If the downloaded image is in
 771         <filename>.qcow2</filename> format it is converted into a raw
 772         image file before it is made available.</para>
 773
 774         <para>Downloaded images of this type will be placed as
 775         read-only <filename>.raw</filename> file in
 776         <filename>/var/lib/machines/</filename>. A local, writable
 777         (reflinked) copy is then made under the specified local
 778         machine name. To omit creation of the local, writable copy
 779         pass <literal>-</literal> as local machine name.</para>
 780
 781         <para>Similar to the behavior of <command>pull-tar</command>,
 782         the read-only image is prefixed with
 783         <filename>.raw-</filename>, and thus not shown by
 784         <command>list-images</command>, unless <option>--all</option>
 785         is passed.</para>
 786
 787         <para>Note that pressing C-c during execution of this command
 788         will not abort the download. Use
 789         <command>cancel-transfer</command>, described
 790         below.</para></listitem>
 791       </varlistentry>
 792
 793       <varlistentry>
 794         <term><command>import-tar</command> <replaceable>FILE</replaceable> [<replaceable>NAME</replaceable>]</term>
 795         <term><command>import-raw</command> <replaceable>FILE</replaceable> [<replaceable>NAME</replaceable>]</term>
 796         <listitem><para>Imports a TAR or RAW container or VM image,
 797         and places it under the specified name in
 798         <filename>/var/lib/machines/</filename>. When
 799         <command>import-tar</command> is used, the file specified as
 800         the first argument should be a tar archive, possibly compressed
 801         with xz, gzip or bzip2. It will then be unpacked into its own
 802         subvolume in <filename>/var/lib/machines</filename>. When
 803         <command>import-raw</command> is used, the file should be a
 804         qcow2 or raw disk image, possibly compressed with xz, gzip or
 805         bzip2. If the second argument (the resulting image name) is
 806         not specified, it is automatically derived from the file
 807         name. If the file name is passed as <literal>-</literal>, the
 808         image is read from standard input, in which case the second
 809         argument is mandatory.</para>
 810
 811         <para>Both <command>pull-tar</command> and <command>pull-raw</command>
 812         will resize <filename>/var/lib/machines.raw</filename> and the
 813         filesystem therein as necessary. Optionally, the
 814         <option>--read-only</option> switch may be used to create a
 815         read-only container or VM image. No cryptographic validation
 816         is done when importing the images.</para>
 817
 818         <para>Much like image downloads, ongoing imports may be listed
 819         with <command>list-transfers</command> and aborted with
 820         <command>cancel-transfer</command>.</para></listitem>
 821       </varlistentry>
 822
 823       <varlistentry>
 824         <term><command>export-tar</command> <replaceable>NAME</replaceable> [<replaceable>FILE</replaceable>]</term>
 825         <term><command>export-raw</command> <replaceable>NAME</replaceable> [<replaceable>FILE</replaceable>]</term>
 826         <listitem><para>Exports a TAR or RAW container or VM image and
 827         stores it in the specified file. The first parameter should be
 828         a VM or container image name. The second parameter should be a
 829         file path the TAR or RAW image is written to. If the path ends
 830         in <literal>.gz</literal>, the file is compressed with gzip, if
 831         it ends in <literal>.xz</literal>, with xz, and if it ends in
 832         <literal>.bz2</literal>, with bzip2. If the path ends in
 833         neither, the file is left uncompressed. If the second argument
 834         is missing, the image is written to standard output. The
 835         compression may also be explicitly selected with the
 836         <option>--format=</option> switch. This is in particular
 837         useful if the second parameter is left unspecified.</para>
 838
 839         <para>Much like image downloads and imports, ongoing exports
 840         may be listed with <command>list-transfers</command> and
 841         aborted with
 842         <command>cancel-transfer</command>.</para>
 843
 844         <para>Note that, currently, only directory and subvolume images
 845         may be exported as TAR images, and only raw disk images as RAW
 846         images.</para></listitem>
 847       </varlistentry>
 848
 849       <varlistentry>
 850         <term><command>list-transfers</command></term>
 851
 852         <listitem><para>Shows a list of container or VM image
 853         downloads, imports and exports that are currently in
 854         progress.</para></listitem>
 855       </varlistentry>
 856
 857       <varlistentry>
 858         <term><command>cancel-transfers</command> <replaceable>ID</replaceable>…</term>
 859
 860         <listitem><para>Aborts a download, import or export of the
 861         container or VM image with the specified ID. To list ongoing
 862         transfers and their IDs, use
 863         <command>list-transfers</command>. </para></listitem>
 864       </varlistentry>
 865
 866     </variablelist></refsect2>
 867
 868   </refsect1>
 869
 870   <refsect1>
 871     <title>Machine and Image Names</title>
 872
 873     <para>The <command>machinectl</command> tool operates on machines
 874     and images whose names must be chosen following strict
 875     rules. Machine names must be suitable for use as host names
 876     following a conservative subset of DNS and UNIX/Linux
 877     semantics. Specifically, they must consist of one or more
 878     non-empty label strings, separated by dots. No leading or trailing
 879     dots are allowed. No sequences of multiple dots are allowed. The
 880     label strings may only consist of alphanumeric characters as well
 881     as the dash and underscore. The maximum length of a machine name
 882     is 64 characters.</para>
 883
 884     <para>A special machine with the name <literal>.host</literal>
 885     refers to the running host system itself. This is useful for execution
 886     operations or inspecting the host system as well. Note that
 887     <command>machinectl list</command> will not show this special
 888     machine unless the <option>--all</option> switch is specified.</para>
 889
 890     <para>Requirements on image names are less strict, however, they must be
 891     valid UTF-8, must be suitable as file names (hence not be the
 892     single or double dot, and not include a slash), and may not
 893     contain control characters. Since many operations search for an
 894     image by the name of a requested machine, it is recommended to name
 895     images in the same strict fashion as machines.</para>
 896
 897     <para>A special image with the name <literal>.host</literal>
 898     refers to the image of the running host system. It hence
 899     conceptually maps to the special <literal>.host</literal> machine
 900     name described above. Note that <command>machinectl
 901     list-images</command> will not show this special image either, unless
 902     <option>--all</option> is specified.</para>
 903   </refsect1>
 904
 905   <refsect1>
 906     <title>Files and Directories</title>
 907
 908     <para>Machine images are preferably stored in
 909     <filename>/var/lib/machines/</filename>, but are also searched for
 910     in <filename>/usr/local/lib/machines/</filename> and
 911     <filename>/usr/lib/machines/</filename>. For compatibility reasons,
 912     the directory <filename>/var/lib/container/</filename> is
 913     searched, too. Note that images stored below
 914     <filename>/usr</filename> are always considered read-only. It is
 915     possible to symlink machines images from other directories into
 916     <filename>/var/lib/machines/</filename> to make them available for
 917     control with <command>machinectl</command>.</para>
 918
 919     <para>Note that some image operations are only supported,
 920     efficient or atomic on btrfs file systems. Due to this, if the
 921     <command>pull-tar</command>, <command>pull-raw</command>,
 922     <command>import-tar</command>, <command>import-raw</command> and
 923     <command>set-limit</command> commands notice that
 924     <filename>/var/lib/machines</filename> is empty and not located on
 925     btrfs, they will implicitly set up a loopback file
 926     <filename>/var/lib/machines.raw</filename> containing a btrfs file
 927     system that is mounted to
 928     <filename>/var/lib/machines</filename>. The size of this loopback
 929     file may be controlled dynamically with
 930     <command>set-limit</command>.</para>
 931
 932     <para>Disk images are understood by
 933     <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 934     and <command>machinectl</command> in three formats:</para>
 935
 936     <itemizedlist>
 937       <listitem><para>A simple directory tree, containing the files
 938       and directories of the container to boot.</para></listitem>
 939
 940       <listitem><para>Subvolumes (on btrfs file systems), which are
 941       similar to the simple directories, described above. However,
 942       they have additional benefits, such as efficient cloning and
 943       quota reporting.</para></listitem>
 944
 945       <listitem><para>"Raw" disk images, i.e. binary images of disks
 946       with a GPT or MBR partition table. Images of this type are
 947       regular files with the suffix
 948       <literal>.raw</literal>.</para></listitem>
 949     </itemizedlist>
 950
 951     <para>See
 952     <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 953     for more information on image formats, in particular its
 954     <option>--directory=</option> and <option>--image=</option>
 955     options.</para>
 956   </refsect1>
 957
 958   <refsect1>
 959     <title>Examples</title>
 960     <example>
 961       <title>Download an Ubuntu image and open a shell in it</title>
 962
 963       <programlisting># machinectl pull-tar https://cloud-images.ubuntu.com/trusty/current/trusty-server-cloudimg-amd64-root.tar.gz
 964 # systemd-nspawn -M trusty-server-cloudimg-amd64-root</programlisting>
 965
 966       <para>This downloads and verifies the specified
 967       <filename>.tar</filename> image, and then uses
 968       <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 969       to open a shell in it.</para>
 970     </example>
 971
 972     <example>
 973       <title>Download a Fedora image, set a root password in it, start
 974       it as service</title>
 975
 976       <programlisting># machinectl pull-raw --verify=no https://dl.fedoraproject.org/pub/fedora/linux/releases/23/Cloud/x86_64/Images/Fedora-Cloud-Base-23-20151030.x86_64.raw.xz
 977 # systemd-nspawn -M Fedora-Cloud-Base-23-20151030
 978 # passwd
 979 # exit
 980 # machinectl start Fedora-Cloud-Base-23-20151030
 981 # machinectl login Fedora-Cloud-Base-23-20151030</programlisting>
 982
 983       <para>This downloads the specified <filename>.raw</filename>
 984       image with verification disabled. Then, a shell is opened in it
 985       and a root password is set. Afterwards the shell is left, and
 986       the machine started as system service. With the last command a
 987       login prompt into the container is requested.</para>
 988     </example>
 989
 990     <example>
 991       <title>Exports a container image as tar file</title>
 992
 993       <programlisting># machinectl export-tar fedora myfedora.tar.xz</programlisting>
 994
 995       <para>Exports the container <literal>fedora</literal> as an
 996       xz-compressed tar file <filename>myfedora.tar.xz</filename> into the
 997       current directory.</para>
 998     </example>
 999
1000     <example>
1001       <title>Create a new shell session</title>
1002
1003       <programlisting># machinectl shell --uid=lennart</programlisting>
1004
1005       <para>This creates a new shell session on the local host for
1006       the user ID <literal>lennart</literal>, in a <citerefentry
1007       project='die-net'><refentrytitle>su</refentrytitle><manvolnum>1</manvolnum></citerefentry>-like
1008       fashion.</para>
1009     </example>
1010
1011   </refsect1>
1012
1013   <refsect1>
1014     <title>Exit status</title>
1015
1016     <para>On success, 0 is returned, a non-zero failure code
1017     otherwise.</para>
1018   </refsect1>
1019
1020   <xi:include href="less-variables.xml" />
1021
1022   <refsect1>
1023     <title>See Also</title>
1024     <para>
1025       <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
1026       <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1027       <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1028       <citerefentry project='die-net'><refentrytitle>tar</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1029       <citerefentry project='die-net'><refentrytitle>xz</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1030       <citerefentry project='die-net'><refentrytitle>gzip</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1031       <citerefentry project='die-net'><refentrytitle>bzip2</refentrytitle><manvolnum>1</manvolnum></citerefentry>
1032     </para>
1033   </refsect1>
1034
1035 </refentry>