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 disk 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 disk 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 disk 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
 499       <varlistentry>
 500         <term><command>remove</command> <replaceable>NAME</replaceable>...</term>
 501
 502         <listitem><para>Removes one or more container or disk images.
 503         The special image <literal>.host</literal>, which refers to
 504         the host's own directory tree may not be
 505         removed.</para></listitem>
 506       </varlistentry>
 507
 508     </variablelist></refsect2>
 509
 510     <refsect2><title>Image Transfer Commands</title><variablelist>
 511
 512       <varlistentry>
 513         <term><command>pull-tar</command> <replaceable>URL</replaceable> [<replaceable>NAME</replaceable>]</term>
 514
 515         <listitem><para>Downloads a <filename>.tar</filename>
 516         container image from the specified URL, and makes it available
 517         under the specified local machine name. The URL must be of
 518         type <literal>http://</literal> or
 519         <literal>https://</literal>, and must refer to a
 520         <filename>.tar</filename>, <filename>.tar.gz</filename>,
 521         <filename>.tar.xz</filename> or <filename>.tar.bz2</filename>
 522         archive file. If the local machine name is omitted the name it
 523         is automatically derived from the last component of the URL,
 524         with its suffix removed.</para>
 525
 526         <para>The image is verified before it is made available,
 527         unless <option>--verify=no</option> is specified. Verification
 528         is done via SHA256SUMS and SHA256SUMS.gpg files, that need to
 529         be made available on the same web server, under the same URL
 530         as the <filename>.tar</filename> file, but with the last
 531         component (the filename) of the URL replaced. With
 532         <option>--verify=checksum</option> only the SHA256 checksum
 533         for the file is verified, based on the
 534         <filename>SHA256SUMS</filename> file. With
 535         <option>--verify=signature</option> the SHA256SUMS file is
 536         first verified with detached GPG signature file
 537         <filename>SHA256SUMS.gpg</filename>. The public key for this
 538         verification step needs to be available in
 539         <filename>/usr/lib/systemd/import-pubring.gpg</filename> or
 540         <filename>/etc/systemd/import-pubring.gpg</filename>.</para>
 541
 542         <para>The container image will be downloaded and stored in a
 543         read-only subvolume in
 544         <filename>/var/lib/machines/</filename>, that is named after
 545         the specified URL and its HTTP etag. A writable snapshot is
 546         then taken from this subvolume, and named after the specified
 547         local name. This behaviour ensures that creating multiple
 548         container instances of the same URL is efficient, as multiple
 549         downloads are not necessary. In order to create only the
 550         read-only image, and avoid creating its writable snapshot,
 551         specify <literal>-</literal> as local machine name.</para>
 552
 553         <para>Note that the read-only subvolume is prefixed with
 554         <filename>.tar-</filename>, and is thus now shown by
 555         <command>list-images</command>, unless <option>--all</option>
 556         is passed.</para>
 557
 558         <para>Note that pressing C-c during execution of this command
 559         will not abort the download. Use
 560         <command>cancel-transfer</command>, described
 561         below.</para></listitem>
 562       </varlistentry>
 563
 564       <varlistentry>
 565         <term><command>pull-raw</command> <replaceable>URL</replaceable> [<replaceable>NAME</replaceable>]</term>
 566
 567         <listitem><para>Downloads a <filename>.raw</filename>
 568         container or VM disk image from the specified URL, and makes
 569         it available under the specified local machine name. The URL
 570         must be of type <literal>http://</literal> or
 571         <literal>https://</literal>. The container image must either
 572         be a <filename>.qcow2</filename> or raw disk image, optionally
 573         compressed as <filename>.gz</filename>,
 574         <filename>.xz</filename>, or <filename>.bz2</filename>. If the
 575         local machine name is omitted the name it is automatically
 576         derived from the last component of the URL, with its suffix
 577         removed.</para>
 578
 579         <para>Image verification is identical for raw and tar images
 580         (see above).</para>
 581
 582         <para>If the the downloaded image is in
 583         <filename>.qcow2</filename> format it es converted into a raw
 584         image file before it is made available.</para>
 585
 586         <para>Downloaded images of this type will be placed as
 587         read-only <filename>.raw</filename> file in
 588         <filename>/var/lib/machines/</filename>. A local, writable
 589         (reflinked) copy is then made under the specified local
 590         machine name. To omit creation of the local, writable copy
 591         pass <literal>-</literal> as local machine name.</para>
 592
 593         <para>Similar to the behaviour of <command>pull-tar</command>,
 594         the read-only image is prefixed with
 595         <filename>.raw-</filename>, and thus now shown by
 596         <command>list-images</command>, unless <option>--all</option>
 597         is passed.</para>
 598
 599         <para>Note that pressing C-c during execution of this command
 600         will not abort the download. Use
 601         <command>cancel-transfer</command>, described
 602         below.</para></listitem>
 603       </varlistentry>
 604
 605       <varlistentry>
 606         <term><command>pull-dkr</command> <replaceable>REMOTE</replaceable> [<replaceable>NAME</replaceable>]</term>
 607
 608         <listitem><para>Downloads a <literal>dkr</literal> container
 609         image and makes it available locally. The remote name refers
 610         to a <literal>dkr</literal> container name. If omitted, the
 611         local machine name is derived from the <literal>dkr</literal>
 612         container name.</para>
 613
 614         <para>Image verification is not available for
 615         <literal>dkr</literal> containers, and thus
 616         <option>--verify=no</option> must always be specified with
 617         this command.</para>
 618
 619         <para>This command downloads all (missing) layers for the
 620         specified container and places them in read-only subvolumes in
 621         <filename>/var/lib/machines/</filename>. A writable snapshot
 622         of the newest layer is then created under the specified local
 623         machine name. To omit creation of this writable snapshot, pass
 624         <literal>-</literal> as local machine name.</para>
 625
 626         <para>The read-only layer subvolumes are prefixed with
 627         <filename>.dkr-</filename>, and thus now shown by
 628         <command>list-images</command>, unless <option>--all</option>
 629         is passed.</para>
 630
 631         <para>To specify the <literal>dkr</literal> index server to
 632         use for looking up the specified container, use
 633         <option>--dkr-index-url=</option>.</para>
 634
 635         <para>Note that pressing C-c during execution of this command
 636         will not abort the download. Use
 637         <command>cancel-transfer</command>, described
 638         below.</para></listitem>
 639       </varlistentry>
 640
 641       <varlistentry>
 642         <term><command>list-transfers</command></term>
 643
 644         <listitem><para>Shows a list of container or VM image
 645         downloads that are currently in progress.</para></listitem>
 646       </varlistentry>
 647
 648       <varlistentry>
 649         <term><command>cancel-transfers</command> <replaceable>ID</replaceable>...</term>
 650
 651         <listitem><para>Aborts download of the container or VM image
 652         with the specified ID. To list ongoing transfers and their
 653         IDs, use <command>list-transfers</command>. </para></listitem>
 654       </varlistentry>
 655
 656     </variablelist></refsect2>
 657
 658   </refsect1>
 659
 660   <refsect1>
 661     <title>Files and Directories</title>
 662
 663     <para>Machine images are preferably stored in
 664     <filename>/var/lib/machines/</filename>, but are also searched for
 665     in <filename>/usr/local/lib/machines/</filename> and
 666     <filename>/usr/lib/machines/</filename>. For compatibility reasons
 667     the directory <filename>/var/lib/container/</filename> is
 668     searched, too. Note that images stored below
 669     <filename>/usr</filename> are always considered read-only. It is
 670     possible to symlink machines images from other directories into
 671     <filename>/var/lib/machines/</filename> to make them available for
 672     control with <command>machinectl</command>.</para>
 673
 674     <para>Disk images are understood by
 675     <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 676     and <command>machinectl</command> in three formats:</para>
 677
 678     <itemizedlist>
 679       <listitem><para>A simple directory tree, containing the files
 680       and directories of the container to boot.</para></listitem>
 681
 682       <listitem><para>A subvolume (on btrfs file systems), which are
 683       similar to the simple directories, described above. However,
 684       they have additional benefits, such as efficient cloning and
 685       quota reporting.</para></listitem>
 686
 687       <listitem><para>"Raw" disk images, i.e. binary images of disks
 688       with a GPT or MBR partition table. Images of this type are
 689       regular files with the suffix
 690       <literal>.raw</literal>.</para></listitem>
 691     </itemizedlist>
 692
 693     <para>See
 694     <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 695     for more information on image formats, in particular it's
 696     <option>--directory=</option> and <option>--image=</option>
 697     options.</para>
 698   </refsect1>
 699
 700   <refsect1>
 701     <title>Examples</title>
 702     <example>
 703       <title>Download an Ubuntu image and open a shell in it</title>
 704
 705       <programlisting># machinectl pull-tar https://cloud-images.ubuntu.com/trusty/current/trusty-server-cloudimg-amd64-root.tar.gz
 706 # systemd-nspawn -M trusty-server-cloudimg-amd64-root</programlisting>
 707
 708       <para>This downloads and verifies the specified
 709       <filename>.tar</filename> image, and then uses
 710       <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 711       to open a shell in it.</para>
 712     </example>
 713
 714     <example>
 715       <title>Download a Fedora image, set a root password in it, start
 716       it as service</title>
 717
 718       <programlisting># machinectl pull-raw --verify=no
 719       http://ftp.halifax.rwth-aachen.de/fedora/linux/releases/21/Cloud/Images/x86_64/Fedora-Cloud-Base-20141203-21.x86_64.raw.xz
 720       # systemd-nspawn -M Fedora-Cloud-Base-20141203-21 # passwd #
 721       exit # machinectl start Fedora-Cloud-Base-20141203-21 #
 722       machinectl login Fedora-Cloud-Base-20141203-21</programlisting>
 723
 724       <para>This downloads the specified <filename>.raw</filename>
 725       image with verification disabled. Then a shell is opened in it
 726       and a root password is set. Afterwards the shell is left, and
 727       the machine started as system service. With the last command a
 728       login prompt into the container is requested.</para>
 729     </example>
 730
 731     <example>
 732       <title>Download a Fedora <literal>dkr</literal> image</title>
 733
 734       <programlisting># machinectl pull-dkr --verify=no mattdm/fedora
 735 # systemd-nspawn -M fedora</programlisting>
 736
 737       <para>Downloads a <literal>dkr</literal> image and opens a shell
 738       in it. Note that the specified download command might require an
 739       index server to be specified with the
 740       <literal>--dkr-index-url=</literal>.</para>
 741     </example>
 742   </refsect1>
 743
 744   <refsect1>
 745     <title>Exit status</title>
 746
 747     <para>On success, 0 is returned, a non-zero failure code
 748     otherwise.</para>
 749   </refsect1>
 750
 751   <xi:include href="less-variables.xml" />
 752
 753   <refsect1>
 754     <title>See Also</title>
 755     <para>
 756       <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 757       <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 758       <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 759     </para>
 760   </refsect1>
 761
 762 </refentry>