man/machinectl.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   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   </refsect1>
  69
  70   <refsect1>
  71     <title>Options</title>
  72
  73     <para>The following options are understood:</para>
  74
  75     <variablelist>
  76       <varlistentry>
  77         <term><option>-p</option></term>
  78         <term><option>--property=</option></term>
  79
  80         <listitem><para>When showing machine or image properties,
  81         limit the output to certain properties as specified by the
  82         argument. If not specified, all set properties are shown. The
  83         argument should be a property name, such as
  84         <literal>Name</literal>. If specified more than once, all
  85         properties with the specified names are
  86         shown.</para></listitem>
  87       </varlistentry>
  88
  89       <varlistentry>
  90         <term><option>-a</option></term>
  91         <term><option>--all</option></term>
  92
  93         <listitem><para>When showing machine or image properties, show
  94         all properties regardless of whether they are set or
  95         not.</para>
  96
  97         <para>When listing VM or container images, do not suppress
  98         images beginning in a dot character
  99         (<literal>.</literal>).</para></listitem>
 100       </varlistentry>
 101
 102       <varlistentry>
 103         <term><option>-l</option></term>
 104         <term><option>--full</option></term>
 105
 106         <listitem><para>Do not ellipsize process tree entries.</para>
 107         </listitem>
 108       </varlistentry>
 109
 110       <varlistentry>
 111         <term><option>--no-ask-password</option></term>
 112
 113         <listitem><para>Do not query the user for authentication for
 114         privileged operations.</para></listitem>
 115       </varlistentry>
 116
 117       <varlistentry>
 118         <term><option>--kill-who=</option></term>
 119
 120         <listitem><para>When used with <command>kill</command>, choose
 121         which processes to kill. Must be one of
 122         <option>leader</option>, or <option>all</option> to select
 123         whether to kill only the leader process of the machine or all
 124         processes of the machine. If omitted, defaults to
 125         <option>all</option>.</para></listitem>
 126       </varlistentry>
 127
 128       <varlistentry>
 129         <term><option>-s</option></term>
 130         <term><option>--signal=</option></term>
 131
 132         <listitem><para>When used with <command>kill</command>, choose
 133         which signal to send to selected processes. Must be one of the
 134         well-known signal specifiers, such as
 135         <constant>SIGTERM</constant>, <constant>SIGINT</constant> or
 136         <constant>SIGSTOP</constant>. If omitted, defaults to
 137         <constant>SIGTERM</constant>.</para></listitem>
 138       </varlistentry>
 139
 140       <varlistentry>
 141         <term><option>--mkdir</option></term>
 142
 143         <listitem><para>When used with <command>bind</command> creates
 144         the destination directory before applying the bind
 145         mount.</para></listitem>
 146       </varlistentry>
 147
 148
 149       <varlistentry>
 150         <term><option>--read-only</option></term>
 151
 152         <listitem><para>When used with <command>bind</command> applies
 153         a read-only bind mount.</para></listitem>
 154       </varlistentry>
 155
 156
 157       <varlistentry>
 158         <term><option>-n</option></term>
 159         <term><option>--lines=</option></term>
 160
 161         <listitem><para>When used with <command>status</command>,
 162         controls the number of journal lines to show, counting from
 163         the most recent ones. Takes a positive integer argument.
 164         Defaults to 10.</para>
 165         </listitem>
 166       </varlistentry>
 167
 168       <varlistentry>
 169         <term><option>-o</option></term>
 170         <term><option>--output=</option></term>
 171
 172         <listitem><para>When used with <command>status</command>,
 173         controls the formatting of the journal entries that are shown.
 174         For the available choices, see
 175         <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 176         Defaults to <literal>short</literal>.</para></listitem>
 177       </varlistentry>
 178
 179       <varlistentry>
 180         <term><option>--verify=</option></term>
 181
 182         <listitem><para>When downloading a container or VM image,
 183         specify whether the image shall be verified before it is made
 184         available. Takes one of <literal>no</literal>,
 185         <literal>checksum</literal> and <literal>signature</literal>.
 186         If <literal>no</literal> no verification is done. If
 187         <literal>checksum</literal> is specified the download is
 188         checked for integrity after transfer is complete, but no
 189         signatures are verified. If <literal>signature</literal> is
 190         specified, the checksum is verified and the images's signature
 191         is checked against a local keyring of trustable vendors. It is
 192         strongly recommended to set this option to
 193         <literal>signature</literal> if the server and protocol
 194         support this. Defaults to
 195         <literal>signature</literal>.</para></listitem>
 196       </varlistentry>
 197
 198       <varlistentry>
 199         <term><option>--force</option></term>
 200
 201         <listitem><para>When downloading a container or VM image, and
 202         a local copy by the specified local machine name already
 203         exists, delete it first and replace it by the newly downloaded
 204         image.</para></listitem>
 205       </varlistentry>
 206
 207       <varlistentry>
 208         <term><option>--dkr-index-url</option></term>
 209
 210         <listitem><para>Specifies the index server to use for
 211         downloading <literal>dkr</literal> images with the
 212         <command>pull-dkr</command>. Takes a
 213         <literal>http://</literal>, <literal>https://</literal>
 214         URL.</para></listitem>
 215       </varlistentry>
 216
 217       <xi:include href="user-system-options.xml" xpointer="host" />
 218       <xi:include href="user-system-options.xml" xpointer="machine" />
 219
 220       <xi:include href="standard-options.xml" xpointer="no-pager" />
 221       <xi:include href="standard-options.xml" xpointer="no-legend" />
 222       <xi:include href="standard-options.xml" xpointer="help" />
 223       <xi:include href="standard-options.xml" xpointer="version" />
 224     </variablelist>
 225   </refsect1>
 226
 227   <refsect1>
 228     <title>Commands</title>
 229
 230     <para>The following commands are understood:</para>
 231
 232     <refsect2><title>Machine Commands</title><variablelist>
 233
 234       <varlistentry>
 235         <term><command>list</command></term>
 236
 237         <listitem><para>List currently running (online) virtual
 238         machines and containers. To enumerate container images that
 239         can be started, use <command>list-images</command> (see
 240         below).</para></listitem>
 241       </varlistentry>
 242
 243       <varlistentry>
 244         <term><command>status</command> <replaceable>NAME</replaceable>...</term>
 245
 246         <listitem><para>Show terse runtime status information about
 247         one or more virtual machines and containers, followed by the
 248         most recent log data from the journal. This function is
 249         intended to generate human-readable output. If you are looking
 250         for computer-parsable output, use <command>show</command>
 251         instead. Note that the log data shown is reported by the
 252         virtual machine or container manager, and frequently contains
 253         console output of the machine, but not necessarily journal
 254         contents of the machine itself.</para></listitem>
 255       </varlistentry>
 256
 257       <varlistentry>
 258         <term><command>show</command> <replaceable>NAME</replaceable>...</term>
 259
 260         <listitem><para>Show properties of one or more registered
 261         virtual machines or containers or the manager itself. If no
 262         argument is specified, properties of the manager will be
 263         shown. If an NAME is specified, properties of this virtual
 264         machine or container are shown. By default, empty properties
 265         are suppressed. Use <option>--all</option> to show those too.
 266         To select specific properties to show, use
 267         <option>--property=</option>. This command is intended to be
 268         used whenever computer-parsable output is required. Use
 269         <command>status</command> if you are looking for formatted
 270         human-readable output.</para></listitem>
 271       </varlistentry>
 272
 273       <varlistentry>
 274         <term><command>start</command> <replaceable>NAME</replaceable>...</term>
 275
 276         <listitem><para>Start a container as a system service, using
 277         <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 278         This starts <filename>systemd-nspawn@.service</filename>,
 279         instantiated for the specified machine name, similar to the
 280         effect of <command>systemctl start</command> on the service
 281         name. <command>systemd-nspawn</command> looks for a container
 282         image by the specified name in
 283         <filename>/var/lib/machines/</filename> (and other search
 284         paths, see below) and runs it. Use
 285         <command>list-images</command> (see below), for listing
 286         available container images to start.</para>
 287
 288         <para>Note that
 289         <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 290         also interfaces with a variety of other container and VM
 291         managers, <command>systemd-nspawn</command> is just one
 292         implementation of it. Most of the commands available in
 293         <command>machinectl</command> may be used on containers or VMs
 294         controlled by other managers, not just
 295         <command>systemd-nspawn</command>. Starting VMs and container
 296         images on those managers requires manager-specific
 297         tools.</para>
 298
 299         <para>To interactively start a container on the command line
 300         with full access to the container's console, please invoke
 301         <command>systemd-nspawn</command> directly. To stop a running
 302         container use <command>machinectl poweroff</command>, see
 303         below.</para></listitem>
 304       </varlistentry>
 305
 306       <varlistentry>
 307         <term><command>login</command> <replaceable>NAME</replaceable></term>
 308
 309         <listitem><para>Open an interactive terminal login session to
 310         a container. This will create a TTY connection to a specific
 311         container and asks for the execution of a getty on it. Note
 312         that this is only supported for containers running
 313         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 314         as init system.</para>
 315
 316         <para>This command will open a full login prompt on the
 317         container, which then asks for username and password. Use
 318         <citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 319         with the <option>--machine=</option> switch to invoke a single
 320         command, either interactively or in the background within a
 321         local container.</para></listitem>
 322       </varlistentry>
 323
 324       <varlistentry>
 325         <term><command>enable</command> <replaceable>NAME</replaceable>...</term>
 326         <term><command>disable</command> <replaceable>NAME</replaceable>...</term>
 327
 328         <listitem><para>Enable or disable a container as a system
 329         service to start at system boot, using
 330         <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 331         This enables or disables
 332         <filename>systemd-nspawn@.service</filename>, instantiated for
 333         the specified machine name, similar to the effect of
 334         <command>systemctl enable</command> or <command>systemctl
 335         disable</command> on the service name.</para></listitem>
 336       </varlistentry>
 337
 338       <varlistentry>
 339         <term><command>poweroff</command> <replaceable>NAME</replaceable>...</term>
 340
 341         <listitem><para>Power off one or more containers. This will
 342         trigger a reboot by sending SIGRTMIN+4 to the container's init
 343         process, which causes systemd-compatible init systems to shut
 344         down cleanly. This operation does not work on containers that
 345         do not run a
 346         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>-compatible
 347         init system, such as sysvinit. Use
 348         <command>terminate</command> (see below) to immediately
 349         terminate a container or VM, without cleanly shutting it
 350         down.</para></listitem>
 351       </varlistentry>
 352
 353       <varlistentry>
 354         <term><command>reboot</command> <replaceable>NAME</replaceable>...</term>
 355
 356         <listitem><para>Reboot one or more containers. This will
 357         trigger a reboot by sending SIGINT to the container's init
 358         process, which is roughly equivalent to pressing Ctrl+Alt+Del
 359         on a non-containerized system, and is compatible with
 360         containers running any system manager.</para></listitem>
 361       </varlistentry>
 362
 363       <varlistentry>
 364         <term><command>terminate</command> <replaceable>NAME</replaceable>...</term>
 365
 366         <listitem><para>Immediately terminates a virtual machine or
 367         container, without cleanly shutting it down. This kills all
 368         processes of the virtual machine or container and deallocates
 369         all resources attached to that instance. Use
 370         <command>poweroff</command> to issue a clean shutdown
 371         request.</para></listitem>
 372       </varlistentry>
 373
 374       <varlistentry>
 375         <term><command>kill</command> <replaceable>NAME</replaceable>...</term>
 376
 377         <listitem><para>Send a signal to one or more processes of the
 378         virtual machine or container. This means processes as seen by
 379         the host, not the processes inside the virtual machine or
 380         container. Use <option>--kill-who=</option> to select which
 381         process to kill. Use <option>--signal=</option> to select the
 382         signal to send.</para></listitem>
 383       </varlistentry>
 384
 385       <varlistentry>
 386         <term><command>bind</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term>
 387
 388         <listitem><para>Bind mounts a directory from the host into the
 389         specified container. The first directory argument is the
 390         source directory on the host, the second directory argument
 391         the source directory on the host. When the latter is omitted
 392         the destination path in the container is the same as the
 393         source path on the host. When combined with the
 394         <option>--read-only</option> switch a ready-only bind mount is
 395         created. When combined with the <option>--mkdir</option>
 396         switch the destination path is first created before the mount
 397         is applied. Note that this option is currently only supported
 398         for
 399         <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 400         containers.</para></listitem>
 401       </varlistentry>
 402
 403       <varlistentry>
 404         <term><command>copy-to</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term>
 405
 406         <listitem><para>Copies files or directories from the host
 407         system into a running container. Takes a container name,
 408         followed by the source path on the host and the destination
 409         path in the container. If the destination path is omitted the
 410         same as the source path is used.</para></listitem>
 411       </varlistentry>
 412
 413
 414       <varlistentry>
 415         <term><command>copy-from</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term>
 416
 417         <listitem><para>Copies files or directories from a container
 418         into the host system. Takes a container name, followed by the
 419         source path in the container the destination path on the host.
 420         If the destination path is omitted the same as the source path
 421         is used.</para></listitem>
 422       </varlistentry>
 423     </variablelist></refsect2>
 424
 425     <refsect2><title>Image Commands</title><variablelist>
 426
 427       <varlistentry>
 428         <term><command>list-images</command></term>
 429
 430         <listitem><para>Show a list of locally installed container and
 431         VM images. This enumerates all raw disk images and container
 432         directories and subvolumes in
 433         <filename>/var/lib/machines/</filename> (and other search
 434         paths, see below). Use <command>start</command> (see above) to
 435         run a container off one of the listed images. Note that by
 436         default containers whose name begins with a dot
 437         (<literal>.</literal>) are not shown. To show these too,
 438         specify <option>--all</option>. Note that a special image
 439         <literal>.host</literal> always implicitly exists and refers
 440         to the image the host itself is booted from.</para></listitem>
 441       </varlistentry>
 442
 443       <varlistentry>
 444         <term><command>image-status</command> <replaceable>NAME</replaceable>...</term>
 445
 446         <listitem><para>Show terse status information about one or
 447         more container or VM images. This function is intended to
 448         generate human-readable output. Use
 449         <command>show-image</command> (see below) to generate
 450         computer-parsable output instead.</para></listitem>
 451       </varlistentry>
 452
 453       <varlistentry>
 454         <term><command>show-image</command> <replaceable>NAME</replaceable>...</term>
 455
 456         <listitem><para>Show properties of one or more registered
 457         virtual machine or container images, or the manager itself. If
 458         no argument is specified, properties of the manager will be
 459         shown. If an NAME is specified, properties of this virtual
 460         machine or container image are shown. By default, empty
 461         properties are suppressed. Use <option>--all</option> to show
 462         those too. To select specific properties to show, use
 463         <option>--property=</option>. This command is intended to be
 464         used whenever computer-parsable output is required. Use
 465         <command>image-status</command> if you are looking for
 466         formatted human-readable output.</para></listitem>
 467       </varlistentry>
 468
 469       <varlistentry>
 470         <term><command>clone</command> <replaceable>NAME</replaceable> <replaceable>NAME</replaceable></term>
 471
 472         <listitem><para>Clones a container or VM image. The
 473         arguments specify the name of the image to clone and the name
 474         of the newly cloned image. Note that plain directory container
 475         images are cloned into subvolume images with this command.
 476         Note that cloning a container or VM image is optimized for
 477         btrfs file systems, and might not be efficient on others, due
 478         to file system limitations.</para></listitem>
 479       </varlistentry>
 480
 481       <varlistentry>
 482         <term><command>rename</command> <replaceable>NAME</replaceable> <replaceable>NAME</replaceable></term>
 483
 484         <listitem><para>Renames a container or VM image. The
 485         arguments specify the name of the image to rename and the new
 486         name of the image.</para></listitem>
 487       </varlistentry>
 488
 489       <varlistentry>
 490         <term><command>read-only</command> <replaceable>NAME</replaceable> [<replaceable>BOOL</replaceable>]</term>
 491
 492         <listitem><para>Marks or (unmarks) a container or VM image
 493         read-only. Takes a VM or container image name, followed by a
 494         boolean as arguments. If the boolean is omitted, positive is
 495         implied, i.e. the image is marked read-only.</para></listitem>
 496       </varlistentry>
 497
 498       <varlistentry>
 499         <term><command>remove</command> <replaceable>NAME</replaceable>...</term>
 500
 501         <listitem><para>Removes one or more container or VM images.
 502         The special image <literal>.host</literal>, which refers to
 503         the host's own directory tree may not be
 504         removed.</para></listitem>
 505       </varlistentry>
 506
 507       <varlistentry>
 508         <term><command>set-limit</command> [<replaceable>NAME</replaceable>] <replaceable>BYTES</replaceable></term>
 509
 510         <listitem><para>Sets the maximum size in bytes a specific
 511         container or VM image, or all images may grow up to
 512         (quota). Takes either one or two parameters. The first,
 513         optional parameter refers to a container or VM image name. If
 514         specified the size limit of the specified images is
 515         changed. If omitted the overall size limit of the sum of all
 516         images stored locally is changed. The final argument specifies
 517         the size limit in bytes, possibly suffixed by the usual K, M,
 518         G, T units. If the size limit shall be disabled, specify
 519         <literal>-</literal> as size. This operation is currently only
 520         supported on btrfs subvolume images.</para></listitem>
 521       </varlistentry>
 522
 523     </variablelist></refsect2>
 524
 525     <refsect2><title>Image Transfer Commands</title><variablelist>
 526
 527       <varlistentry>
 528         <term><command>pull-tar</command> <replaceable>URL</replaceable> [<replaceable>NAME</replaceable>]</term>
 529
 530         <listitem><para>Downloads a <filename>.tar</filename>
 531         container image from the specified URL, and makes it available
 532         under the specified local machine name. The URL must be of
 533         type <literal>http://</literal> or
 534         <literal>https://</literal>, and must refer to a
 535         <filename>.tar</filename>, <filename>.tar.gz</filename>,
 536         <filename>.tar.xz</filename> or <filename>.tar.bz2</filename>
 537         archive file. If the local machine name is omitted the name it
 538         is automatically derived from the last component of the URL,
 539         with its suffix removed.</para>
 540
 541         <para>The image is verified before it is made available,
 542         unless <option>--verify=no</option> is specified. Verification
 543         is done via SHA256SUMS and SHA256SUMS.gpg files, that need to
 544         be made available on the same web server, under the same URL
 545         as the <filename>.tar</filename> file, but with the last
 546         component (the filename) of the URL replaced. With
 547         <option>--verify=checksum</option> only the SHA256 checksum
 548         for the file is verified, based on the
 549         <filename>SHA256SUMS</filename> file. With
 550         <option>--verify=signature</option> the SHA256SUMS file is
 551         first verified with detached GPG signature file
 552         <filename>SHA256SUMS.gpg</filename>. The public key for this
 553         verification step needs to be available in
 554         <filename>/usr/lib/systemd/import-pubring.gpg</filename> or
 555         <filename>/etc/systemd/import-pubring.gpg</filename>.</para>
 556
 557         <para>The container image will be downloaded and stored in a
 558         read-only subvolume in
 559         <filename>/var/lib/machines/</filename>, that is named after
 560         the specified URL and its HTTP etag. A writable snapshot is
 561         then taken from this subvolume, and named after the specified
 562         local name. This behaviour ensures that creating multiple
 563         container instances of the same URL is efficient, as multiple
 564         downloads are not necessary. In order to create only the
 565         read-only image, and avoid creating its writable snapshot,
 566         specify <literal>-</literal> as local machine name.</para>
 567
 568         <para>Note that the read-only subvolume is prefixed with
 569         <filename>.tar-</filename>, and is thus now shown by
 570         <command>list-images</command>, unless <option>--all</option>
 571         is passed.</para>
 572
 573         <para>Note that pressing C-c during execution of this command
 574         will not abort the download. Use
 575         <command>cancel-transfer</command>, described
 576         below.</para></listitem>
 577       </varlistentry>
 578
 579       <varlistentry>
 580         <term><command>pull-raw</command> <replaceable>URL</replaceable> [<replaceable>NAME</replaceable>]</term>
 581
 582         <listitem><para>Downloads a <filename>.raw</filename>
 583         container or VM disk image from the specified URL, and makes
 584         it available under the specified local machine name. The URL
 585         must be of type <literal>http://</literal> or
 586         <literal>https://</literal>. The container image must either
 587         be a <filename>.qcow2</filename> or raw disk image, optionally
 588         compressed as <filename>.gz</filename>,
 589         <filename>.xz</filename>, or <filename>.bz2</filename>. If the
 590         local machine name is omitted the name it is automatically
 591         derived from the last component of the URL, with its suffix
 592         removed.</para>
 593
 594         <para>Image verification is identical for raw and tar images
 595         (see above).</para>
 596
 597         <para>If the the downloaded image is in
 598         <filename>.qcow2</filename> format it es converted into a raw
 599         image file before it is made available.</para>
 600
 601         <para>Downloaded images of this type will be placed as
 602         read-only <filename>.raw</filename> file in
 603         <filename>/var/lib/machines/</filename>. A local, writable
 604         (reflinked) copy is then made under the specified local
 605         machine name. To omit creation of the local, writable copy
 606         pass <literal>-</literal> as local machine name.</para>
 607
 608         <para>Similar to the behaviour of <command>pull-tar</command>,
 609         the read-only image is prefixed with
 610         <filename>.raw-</filename>, and thus now shown by
 611         <command>list-images</command>, unless <option>--all</option>
 612         is passed.</para>
 613
 614         <para>Note that pressing C-c during execution of this command
 615         will not abort the download. Use
 616         <command>cancel-transfer</command>, described
 617         below.</para></listitem>
 618       </varlistentry>
 619
 620       <varlistentry>
 621         <term><command>pull-dkr</command> <replaceable>REMOTE</replaceable> [<replaceable>NAME</replaceable>]</term>
 622
 623         <listitem><para>Downloads a <literal>dkr</literal> container
 624         image and makes it available locally. The remote name refers
 625         to a <literal>dkr</literal> container name. If omitted, the
 626         local machine name is derived from the <literal>dkr</literal>
 627         container name.</para>
 628
 629         <para>Image verification is not available for
 630         <literal>dkr</literal> containers, and thus
 631         <option>--verify=no</option> must always be specified with
 632         this command.</para>
 633
 634         <para>This command downloads all (missing) layers for the
 635         specified container and places them in read-only subvolumes in
 636         <filename>/var/lib/machines/</filename>. A writable snapshot
 637         of the newest layer is then created under the specified local
 638         machine name. To omit creation of this writable snapshot, pass
 639         <literal>-</literal> as local machine name.</para>
 640
 641         <para>The read-only layer subvolumes are prefixed with
 642         <filename>.dkr-</filename>, and thus now shown by
 643         <command>list-images</command>, unless <option>--all</option>
 644         is passed.</para>
 645
 646         <para>To specify the <literal>dkr</literal> index server to
 647         use for looking up the specified container, use
 648         <option>--dkr-index-url=</option>.</para>
 649
 650         <para>Note that pressing C-c during execution of this command
 651         will not abort the download. Use
 652         <command>cancel-transfer</command>, described
 653         below.</para></listitem>
 654       </varlistentry>
 655
 656       <varlistentry>
 657         <term><command>list-transfers</command></term>
 658
 659         <listitem><para>Shows a list of container or VM image
 660         downloads that are currently in progress.</para></listitem>
 661       </varlistentry>
 662
 663       <varlistentry>
 664         <term><command>cancel-transfers</command> <replaceable>ID</replaceable>...</term>
 665
 666         <listitem><para>Aborts download of the container or VM image
 667         with the specified ID. To list ongoing transfers and their
 668         IDs, use <command>list-transfers</command>. </para></listitem>
 669       </varlistentry>
 670
 671     </variablelist></refsect2>
 672
 673   </refsect1>
 674
 675   <refsect1>
 676     <title>Files and Directories</title>
 677
 678     <para>Machine images are preferably stored in
 679     <filename>/var/lib/machines/</filename>, but are also searched for
 680     in <filename>/usr/local/lib/machines/</filename> and
 681     <filename>/usr/lib/machines/</filename>. For compatibility reasons
 682     the directory <filename>/var/lib/container/</filename> is
 683     searched, too. Note that images stored below
 684     <filename>/usr</filename> are always considered read-only. It is
 685     possible to symlink machines images from other directories into
 686     <filename>/var/lib/machines/</filename> to make them available for
 687     control with <command>machinectl</command>.</para>
 688
 689     <para>Disk images are understood by
 690     <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 691     and <command>machinectl</command> in three formats:</para>
 692
 693     <itemizedlist>
 694       <listitem><para>A simple directory tree, containing the files
 695       and directories of the container to boot.</para></listitem>
 696
 697       <listitem><para>A subvolume (on btrfs file systems), which are
 698       similar to the simple directories, described above. However,
 699       they have additional benefits, such as efficient cloning and
 700       quota reporting.</para></listitem>
 701
 702       <listitem><para>"Raw" disk images, i.e. binary images of disks
 703       with a GPT or MBR partition table. Images of this type are
 704       regular files with the suffix
 705       <literal>.raw</literal>.</para></listitem>
 706     </itemizedlist>
 707
 708     <para>See
 709     <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 710     for more information on image formats, in particular it's
 711     <option>--directory=</option> and <option>--image=</option>
 712     options.</para>
 713   </refsect1>
 714
 715   <refsect1>
 716     <title>Examples</title>
 717     <example>
 718       <title>Download an Ubuntu image and open a shell in it</title>
 719
 720       <programlisting># machinectl pull-tar https://cloud-images.ubuntu.com/trusty/current/trusty-server-cloudimg-amd64-root.tar.gz
 721 # systemd-nspawn -M trusty-server-cloudimg-amd64-root</programlisting>
 722
 723       <para>This downloads and verifies the specified
 724       <filename>.tar</filename> image, and then uses
 725       <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 726       to open a shell in it.</para>
 727     </example>
 728
 729     <example>
 730       <title>Download a Fedora image, set a root password in it, start
 731       it as service</title>
 732
 733       <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
 734 # systemd-nspawn -M Fedora-Cloud-Base-20141203-21
 735 # passwd
 736 # exit
 737 # machinectl start Fedora-Cloud-Base-20141203-21
 738 # machinectl login Fedora-Cloud-Base-20141203-21</programlisting>
 739
 740       <para>This downloads the specified <filename>.raw</filename>
 741       image with verification disabled. Then a shell is opened in it
 742       and a root password is set. Afterwards the shell is left, and
 743       the machine started as system service. With the last command a
 744       login prompt into the container is requested.</para>
 745     </example>
 746
 747     <example>
 748       <title>Download a Fedora <literal>dkr</literal> image</title>
 749
 750       <programlisting># machinectl pull-dkr --verify=no mattdm/fedora
 751 # systemd-nspawn -M fedora</programlisting>
 752
 753       <para>Downloads a <literal>dkr</literal> image and opens a shell
 754       in it. Note that the specified download command might require an
 755       index server to be specified with the
 756       <literal>--dkr-index-url=</literal>.</para>
 757     </example>
 758   </refsect1>
 759
 760   <refsect1>
 761     <title>Exit status</title>
 762
 763     <para>On success, 0 is returned, a non-zero failure code
 764     otherwise.</para>
 765   </refsect1>
 766
 767   <xi:include href="less-variables.xml" />
 768
 769   <refsect1>
 770     <title>See Also</title>
 771     <para>
 772       <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 773       <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 774       <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 775     </para>
 776   </refsect1>
 777
 778 </refentry>