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