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