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       <varlistentry>
 218         <term><option>--format=</option></term>
 219
 220         <listitem><para>When used with the <option>export-tar</option>
 221         or <option>export-raw</option> commands specifies the
 222         compression format to use for the resulting file. Takes one of
 223         <literal>uncompressed</literal>, <literal>xz</literal>,
 224         <literal>gzip</literal>, <literal>bzip2</literal>. By default
 225         the format is determined automatically from the image file
 226         name passed.</para></listitem>
 227       </varlistentry>
 228
 229       <xi:include href="user-system-options.xml" xpointer="host" />
 230       <xi:include href="user-system-options.xml" xpointer="machine" />
 231
 232       <xi:include href="standard-options.xml" xpointer="no-pager" />
 233       <xi:include href="standard-options.xml" xpointer="no-legend" />
 234       <xi:include href="standard-options.xml" xpointer="help" />
 235       <xi:include href="standard-options.xml" xpointer="version" />
 236     </variablelist>
 237   </refsect1>
 238
 239   <refsect1>
 240     <title>Commands</title>
 241
 242     <para>The following commands are understood:</para>
 243
 244     <refsect2><title>Machine Commands</title><variablelist>
 245
 246       <varlistentry>
 247         <term><command>list</command></term>
 248
 249         <listitem><para>List currently running (online) virtual
 250         machines and containers. To enumerate container images that
 251         can be started, use <command>list-images</command> (see
 252         below).</para></listitem>
 253       </varlistentry>
 254
 255       <varlistentry>
 256         <term><command>status</command> <replaceable>NAME</replaceable>...</term>
 257
 258         <listitem><para>Show terse runtime status information about
 259         one or more virtual machines and containers, followed by the
 260         most recent log data from the journal. This function is
 261         intended to generate human-readable output. If you are looking
 262         for computer-parsable output, use <command>show</command>
 263         instead. Note that the log data shown is reported by the
 264         virtual machine or container manager, and frequently contains
 265         console output of the machine, but not necessarily journal
 266         contents of the machine itself.</para></listitem>
 267       </varlistentry>
 268
 269       <varlistentry>
 270         <term><command>show</command> <replaceable>NAME</replaceable>...</term>
 271
 272         <listitem><para>Show properties of one or more registered
 273         virtual machines or containers or the manager itself. If no
 274         argument is specified, properties of the manager will be
 275         shown. If an NAME is specified, properties of this virtual
 276         machine or container are shown. By default, empty properties
 277         are suppressed. Use <option>--all</option> to show those too.
 278         To select specific properties to show, use
 279         <option>--property=</option>. This command is intended to be
 280         used whenever computer-parsable output is required. Use
 281         <command>status</command> if you are looking for formatted
 282         human-readable output.</para></listitem>
 283       </varlistentry>
 284
 285       <varlistentry>
 286         <term><command>start</command> <replaceable>NAME</replaceable>...</term>
 287
 288         <listitem><para>Start a container as a system service, using
 289         <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 290         This starts <filename>systemd-nspawn@.service</filename>,
 291         instantiated for the specified machine name, similar to the
 292         effect of <command>systemctl start</command> on the service
 293         name. <command>systemd-nspawn</command> looks for a container
 294         image by the specified name in
 295         <filename>/var/lib/machines/</filename> (and other search
 296         paths, see below) and runs it. Use
 297         <command>list-images</command> (see below), for listing
 298         available container images to start.</para>
 299
 300         <para>Note that
 301         <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 302         also interfaces with a variety of other container and VM
 303         managers, <command>systemd-nspawn</command> is just one
 304         implementation of it. Most of the commands available in
 305         <command>machinectl</command> may be used on containers or VMs
 306         controlled by other managers, not just
 307         <command>systemd-nspawn</command>. Starting VMs and container
 308         images on those managers requires manager-specific
 309         tools.</para>
 310
 311         <para>To interactively start a container on the command line
 312         with full access to the container's console, please invoke
 313         <command>systemd-nspawn</command> directly. To stop a running
 314         container use <command>machinectl poweroff</command>, see
 315         below.</para></listitem>
 316       </varlistentry>
 317
 318       <varlistentry>
 319         <term><command>login</command> <replaceable>NAME</replaceable></term>
 320
 321         <listitem><para>Open an interactive terminal login session to
 322         a container. This will create a TTY connection to a specific
 323         container and asks for the execution of a getty on it. Note
 324         that this is only supported for containers running
 325         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 326         as init system.</para>
 327
 328         <para>This command will open a full login prompt on the
 329         container, which then asks for username and password. Use
 330         <citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 331         with the <option>--machine=</option> switch to invoke a single
 332         command, either interactively or in the background within a
 333         local container.</para></listitem>
 334       </varlistentry>
 335
 336       <varlistentry>
 337         <term><command>enable</command> <replaceable>NAME</replaceable>...</term>
 338         <term><command>disable</command> <replaceable>NAME</replaceable>...</term>
 339
 340         <listitem><para>Enable or disable a container as a system
 341         service to start at system boot, using
 342         <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 343         This enables or disables
 344         <filename>systemd-nspawn@.service</filename>, instantiated for
 345         the specified machine name, similar to the effect of
 346         <command>systemctl enable</command> or <command>systemctl
 347         disable</command> on the service name.</para></listitem>
 348       </varlistentry>
 349
 350       <varlistentry>
 351         <term><command>poweroff</command> <replaceable>NAME</replaceable>...</term>
 352
 353         <listitem><para>Power off one or more containers. This will
 354         trigger a reboot by sending SIGRTMIN+4 to the container's init
 355         process, which causes systemd-compatible init systems to shut
 356         down cleanly. This operation does not work on containers that
 357         do not run a
 358         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>-compatible
 359         init system, such as sysvinit. Use
 360         <command>terminate</command> (see below) to immediately
 361         terminate a container or VM, without cleanly shutting it
 362         down.</para></listitem>
 363       </varlistentry>
 364
 365       <varlistentry>
 366         <term><command>reboot</command> <replaceable>NAME</replaceable>...</term>
 367
 368         <listitem><para>Reboot one or more containers. This will
 369         trigger a reboot by sending SIGINT to the container's init
 370         process, which is roughly equivalent to pressing Ctrl+Alt+Del
 371         on a non-containerized system, and is compatible with
 372         containers running any system manager.</para></listitem>
 373       </varlistentry>
 374
 375       <varlistentry>
 376         <term><command>terminate</command> <replaceable>NAME</replaceable>...</term>
 377
 378         <listitem><para>Immediately terminates a virtual machine or
 379         container, without cleanly shutting it down. This kills all
 380         processes of the virtual machine or container and deallocates
 381         all resources attached to that instance. Use
 382         <command>poweroff</command> to issue a clean shutdown
 383         request.</para></listitem>
 384       </varlistentry>
 385
 386       <varlistentry>
 387         <term><command>kill</command> <replaceable>NAME</replaceable>...</term>
 388
 389         <listitem><para>Send a signal to one or more processes of the
 390         virtual machine or container. This means processes as seen by
 391         the host, not the processes inside the virtual machine or
 392         container. Use <option>--kill-who=</option> to select which
 393         process to kill. Use <option>--signal=</option> to select the
 394         signal to send.</para></listitem>
 395       </varlistentry>
 396
 397       <varlistentry>
 398         <term><command>bind</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term>
 399
 400         <listitem><para>Bind mounts a directory from the host into the
 401         specified container. The first directory argument is the
 402         source directory on the host, the second directory argument
 403         the source directory on the host. When the latter is omitted
 404         the destination path in the container is the same as the
 405         source path on the host. When combined with the
 406         <option>--read-only</option> switch a ready-only bind mount is
 407         created. When combined with the <option>--mkdir</option>
 408         switch the destination path is first created before the mount
 409         is applied. Note that this option is currently only supported
 410         for
 411         <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 412         containers.</para></listitem>
 413       </varlistentry>
 414
 415       <varlistentry>
 416         <term><command>copy-to</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term>
 417
 418         <listitem><para>Copies files or directories from the host
 419         system into a running container. Takes a container name,
 420         followed by the source path on the host and the destination
 421         path in the container. If the destination path is omitted the
 422         same as the source path is used.</para></listitem>
 423       </varlistentry>
 424
 425
 426       <varlistentry>
 427         <term><command>copy-from</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term>
 428
 429         <listitem><para>Copies files or directories from a container
 430         into the host system. Takes a container name, followed by the
 431         source path in the container the destination path on the host.
 432         If the destination path is omitted the same as the source path
 433         is used.</para></listitem>
 434       </varlistentry>
 435     </variablelist></refsect2>
 436
 437     <refsect2><title>Image Commands</title><variablelist>
 438
 439       <varlistentry>
 440         <term><command>list-images</command></term>
 441
 442         <listitem><para>Show a list of locally installed container and
 443         VM images. This enumerates all raw disk images and container
 444         directories and subvolumes in
 445         <filename>/var/lib/machines/</filename> (and other search
 446         paths, see below). Use <command>start</command> (see above) to
 447         run a container off one of the listed images. Note that by
 448         default containers whose name begins with a dot
 449         (<literal>.</literal>) are not shown. To show these too,
 450         specify <option>--all</option>. Note that a special image
 451         <literal>.host</literal> always implicitly exists and refers
 452         to the image the host itself is booted from.</para></listitem>
 453       </varlistentry>
 454
 455       <varlistentry>
 456         <term><command>image-status</command> <replaceable>NAME</replaceable>...</term>
 457
 458         <listitem><para>Show terse status information about one or
 459         more container or VM images. This function is intended to
 460         generate human-readable output. Use
 461         <command>show-image</command> (see below) to generate
 462         computer-parsable output instead.</para></listitem>
 463       </varlistentry>
 464
 465       <varlistentry>
 466         <term><command>show-image</command> <replaceable>NAME</replaceable>...</term>
 467
 468         <listitem><para>Show properties of one or more registered
 469         virtual machine or container images, or the manager itself. If
 470         no argument is specified, properties of the manager will be
 471         shown. If an NAME is specified, properties of this virtual
 472         machine or container image are shown. By default, empty
 473         properties are suppressed. Use <option>--all</option> to show
 474         those too. To select specific properties to show, use
 475         <option>--property=</option>. This command is intended to be
 476         used whenever computer-parsable output is required. Use
 477         <command>image-status</command> if you are looking for
 478         formatted human-readable output.</para></listitem>
 479       </varlistentry>
 480
 481       <varlistentry>
 482         <term><command>clone</command> <replaceable>NAME</replaceable> <replaceable>NAME</replaceable></term>
 483
 484         <listitem><para>Clones a container or VM image. The
 485         arguments specify the name of the image to clone and the name
 486         of the newly cloned image. Note that plain directory container
 487         images are cloned into subvolume images with this command.
 488         Note that cloning a container or VM image is optimized for
 489         btrfs file systems, and might not be efficient on others, due
 490         to file system limitations.</para></listitem>
 491       </varlistentry>
 492
 493       <varlistentry>
 494         <term><command>rename</command> <replaceable>NAME</replaceable> <replaceable>NAME</replaceable></term>
 495
 496         <listitem><para>Renames a container or VM image. The
 497         arguments specify the name of the image to rename and the new
 498         name of the image.</para></listitem>
 499       </varlistentry>
 500
 501       <varlistentry>
 502         <term><command>read-only</command> <replaceable>NAME</replaceable> [<replaceable>BOOL</replaceable>]</term>
 503
 504         <listitem><para>Marks or (unmarks) a container or VM image
 505         read-only. Takes a VM or container image name, followed by a
 506         boolean as arguments. If the boolean is omitted, positive is
 507         implied, i.e. the image is marked read-only.</para></listitem>
 508       </varlistentry>
 509
 510       <varlistentry>
 511         <term><command>remove</command> <replaceable>NAME</replaceable>...</term>
 512
 513         <listitem><para>Removes one or more container or VM images.
 514         The special image <literal>.host</literal>, which refers to
 515         the host's own directory tree may not be
 516         removed.</para></listitem>
 517       </varlistentry>
 518
 519       <varlistentry>
 520         <term><command>set-limit</command> [<replaceable>NAME</replaceable>] <replaceable>BYTES</replaceable></term>
 521
 522         <listitem><para>Sets the maximum size in bytes a specific
 523         container or VM image, or all images may grow up to on disk
 524         (disk quota). Takes either one or two parameters. The first,
 525         optional parameter refers to a container or VM image name. If
 526         specified the size limit of the specified image is changed. If
 527         omitted the overall size limit of the sum of all images stored
 528         locally is changed. The final argument specifies the size
 529         limit in bytes, possibly suffixed by the usual K, M, G, T
 530         units. If the size limit shall be disabled, specify
 531         <literal>-</literal> as size.</para>
 532
 533         <para>Note that per-container size limits are only supported
 534         on btrfs file systems. Also note that if
 535         <command>set-limit</command> is invoked without image
 536         parameter, and <filename>/var/lib/machines</filename> is
 537         empty, and the directory is not located on btrfs, a btrfs
 538         loopback file is implicitly created as
 539         <filename>/var/lib/machines.raw</filename> with the given
 540         size, and mounted to
 541         <filename>/var/lib/machines</filename>. The size of the
 542         loopback may later be readjusted with
 543         <command>set-limit</command>, as well. If such a
 544         loopback-mounted <filename>/var/lib/machines</filename>
 545         directory is used <command>set-limit</command> without image
 546         name alters both the quota setting within the file system as
 547         well as the loopback file and file system size
 548         itself.</para></listitem>
 549       </varlistentry>
 550
 551     </variablelist></refsect2>
 552
 553     <refsect2><title>Image Transfer Commands</title><variablelist>
 554
 555       <varlistentry>
 556         <term><command>pull-tar</command> <replaceable>URL</replaceable> [<replaceable>NAME</replaceable>]</term>
 557
 558         <listitem><para>Downloads a <filename>.tar</filename>
 559         container image from the specified URL, and makes it available
 560         under the specified local machine name. The URL must be of
 561         type <literal>http://</literal> or
 562         <literal>https://</literal>, and must refer to a
 563         <filename>.tar</filename>, <filename>.tar.gz</filename>,
 564         <filename>.tar.xz</filename> or <filename>.tar.bz2</filename>
 565         archive file. If the local machine name is omitted the name it
 566         is automatically derived from the last component of the URL,
 567         with its suffix removed.</para>
 568
 569         <para>The image is verified before it is made available,
 570         unless <option>--verify=no</option> is specified. Verification
 571         is done via SHA256SUMS and SHA256SUMS.gpg files, that need to
 572         be made available on the same web server, under the same URL
 573         as the <filename>.tar</filename> file, but with the last
 574         component (the filename) of the URL replaced. With
 575         <option>--verify=checksum</option> only the SHA256 checksum
 576         for the file is verified, based on the
 577         <filename>SHA256SUMS</filename> file. With
 578         <option>--verify=signature</option> the SHA256SUMS file is
 579         first verified with detached GPG signature file
 580         <filename>SHA256SUMS.gpg</filename>. The public key for this
 581         verification step needs to be available in
 582         <filename>/usr/lib/systemd/import-pubring.gpg</filename> or
 583         <filename>/etc/systemd/import-pubring.gpg</filename>.</para>
 584
 585         <para>The container image will be downloaded and stored in a
 586         read-only subvolume in
 587         <filename>/var/lib/machines/</filename>, that is named after
 588         the specified URL and its HTTP etag. A writable snapshot is
 589         then taken from this subvolume, and named after the specified
 590         local name. This behaviour ensures that creating multiple
 591         container instances of the same URL is efficient, as multiple
 592         downloads are not necessary. In order to create only the
 593         read-only image, and avoid creating its writable snapshot,
 594         specify <literal>-</literal> as local machine name.</para>
 595
 596         <para>Note that the read-only subvolume is prefixed with
 597         <filename>.tar-</filename>, and is thus now shown by
 598         <command>list-images</command>, unless <option>--all</option>
 599         is passed.</para>
 600
 601         <para>Note that pressing C-c during execution of this command
 602         will not abort the download. Use
 603         <command>cancel-transfer</command>, described
 604         below.</para></listitem>
 605       </varlistentry>
 606
 607       <varlistentry>
 608         <term><command>pull-raw</command> <replaceable>URL</replaceable> [<replaceable>NAME</replaceable>]</term>
 609
 610         <listitem><para>Downloads a <filename>.raw</filename>
 611         container or VM disk image from the specified URL, and makes
 612         it available under the specified local machine name. The URL
 613         must be of type <literal>http://</literal> or
 614         <literal>https://</literal>. The container image must either
 615         be a <filename>.qcow2</filename> or raw disk image, optionally
 616         compressed as <filename>.gz</filename>,
 617         <filename>.xz</filename>, or <filename>.bz2</filename>. If the
 618         local machine name is omitted the name it is automatically
 619         derived from the last component of the URL, with its suffix
 620         removed.</para>
 621
 622         <para>Image verification is identical for raw and tar images
 623         (see above).</para>
 624
 625         <para>If the the downloaded image is in
 626         <filename>.qcow2</filename> format it es converted into a raw
 627         image file before it is made available.</para>
 628
 629         <para>Downloaded images of this type will be placed as
 630         read-only <filename>.raw</filename> file in
 631         <filename>/var/lib/machines/</filename>. A local, writable
 632         (reflinked) copy is then made under the specified local
 633         machine name. To omit creation of the local, writable copy
 634         pass <literal>-</literal> as local machine name.</para>
 635
 636         <para>Similar to the behaviour of <command>pull-tar</command>,
 637         the read-only image is prefixed with
 638         <filename>.raw-</filename>, and thus now shown by
 639         <command>list-images</command>, unless <option>--all</option>
 640         is passed.</para>
 641
 642         <para>Note that pressing C-c during execution of this command
 643         will not abort the download. Use
 644         <command>cancel-transfer</command>, described
 645         below.</para></listitem>
 646       </varlistentry>
 647
 648       <varlistentry>
 649         <term><command>pull-dkr</command> <replaceable>REMOTE</replaceable> [<replaceable>NAME</replaceable>]</term>
 650
 651         <listitem><para>Downloads a <literal>dkr</literal> container
 652         image and makes it available locally. The remote name refers
 653         to a <literal>dkr</literal> container name. If omitted, the
 654         local machine name is derived from the <literal>dkr</literal>
 655         container name.</para>
 656
 657         <para>Image verification is not available for
 658         <literal>dkr</literal> containers, and thus
 659         <option>--verify=no</option> must always be specified with
 660         this command.</para>
 661
 662         <para>This command downloads all (missing) layers for the
 663         specified container and places them in read-only subvolumes in
 664         <filename>/var/lib/machines/</filename>. A writable snapshot
 665         of the newest layer is then created under the specified local
 666         machine name. To omit creation of this writable snapshot, pass
 667         <literal>-</literal> as local machine name.</para>
 668
 669         <para>The read-only layer subvolumes are prefixed with
 670         <filename>.dkr-</filename>, and thus now shown by
 671         <command>list-images</command>, unless <option>--all</option>
 672         is passed.</para>
 673
 674         <para>To specify the <literal>dkr</literal> index server to
 675         use for looking up the specified container, use
 676         <option>--dkr-index-url=</option>.</para>
 677
 678         <para>Note that pressing C-c during execution of this command
 679         will not abort the download. Use
 680         <command>cancel-transfer</command>, described
 681         below.</para></listitem>
 682       </varlistentry>
 683
 684       <varlistentry>
 685         <term><command>import-tar</command> <replaceable>FILE</replaceable> [<replaceable>NAME</replaceable>]</term>
 686         <term><command>import-raw</command> <replaceable>FILE</replaceable> [<replaceable>NAME</replaceable>]</term>
 687         <listitem><para>Imports a TAR or RAW container or VM image,
 688         and places it under the specified name in
 689         <filename>/var/lib/machines/</filename>. When
 690         <command>import-tar</command> is used the file specified as
 691         first argument should be a tar archive, possibly compressed
 692         with xz, gzip or bzip2. It will then be unpacked into its own
 693         subvolume in <filename>/var/lib/machines</filename>. When
 694         <command>import-raw</command> is used the file should be a
 695         qcow2 or raw disk image, possibly compressed with xz, gzip or
 696         bzip2. If the second argument (the resulting image name) is
 697         not specified it is automatically derived from the file
 698         name. If the file name is passed as <literal>-</literal> the
 699         image is read from standard input, in which case the second
 700         argument is mandatory.</para>
 701
 702         <para>Similar as with <command>pull-tar</command>,
 703         <command>pull-raw</command> the file system
 704         <filename>/var/lib/machines.raw</filename> is increased in
 705         size of necessary and appropriate. Optionally the
 706         <option>--read-only</option> switch may be used to create a
 707         read-only container or VM image. No cryptographic validation
 708         is done when importing the images.</para>
 709
 710         <para>Much like image downloads, ongoing imports may be listed
 711         with <command>list-transfers</command> and aborted with
 712         <command>cancel-transfer</command>.</para></listitem>
 713       </varlistentry>
 714
 715       <varlistentry>
 716         <term><command>export-tar</command> <replaceable>NAME</replaceable> [<replaceable>FILE</replaceable>]</term>
 717         <term><command>export-raw</command> <replaceable>NAME</replaceable> [<replaceable>FILE</replaceable>]</term>
 718         <listitem><para>Exports a TAR or RAW container or VM image and
 719         stores it in the specified file. The first parameter should be
 720         a VM or container image name. The second parameter should be a
 721         file path the TAR or RAW image is written to. If the path ends
 722         in <literal>.gz</literal> the file is compressed with gzip, if
 723         it ends in <literal>.xz</literal> with xz, and if it ends in
 724         <literal>.bz2</literal> with bzip2. If the path ends in
 725         neither the file is left uncompressed. If the second argument
 726         is missing the image is written to standard output. The
 727         compression may also be explicitly selected with the
 728         <option>--format=</option> switch. This is in particular
 729         useful if the second parameter is left unspecified.</para>
 730
 731         <para>Much like image downloads and imports, ongoing exports
 732         may be listed with <command>list-transfers</command> and
 733         aborted with
 734         <command>cancel-transfer</command>.</para>
 735
 736         <para>Note that currently only directory and subvolume images
 737         may be exported as TAR images, and only raw disk images as RAW
 738         images.</para></listitem>
 739       </varlistentry>
 740
 741       <varlistentry>
 742         <term><command>list-transfers</command></term>
 743
 744         <listitem><para>Shows a list of container or VM image
 745         downloads, imports and exports that are currently in
 746         progress.</para></listitem>
 747       </varlistentry>
 748
 749       <varlistentry>
 750         <term><command>cancel-transfers</command> <replaceable>ID</replaceable>...</term>
 751
 752         <listitem><para>Aborts a download, import or export of the
 753         container or VM image with the specified ID. To list ongoing
 754         transfers and their IDs, use
 755         <command>list-transfers</command>. </para></listitem>
 756       </varlistentry>
 757
 758     </variablelist></refsect2>
 759
 760   </refsect1>
 761
 762   <refsect1>
 763     <title>Files and Directories</title>
 764
 765     <para>Machine images are preferably stored in
 766     <filename>/var/lib/machines/</filename>, but are also searched for
 767     in <filename>/usr/local/lib/machines/</filename> and
 768     <filename>/usr/lib/machines/</filename>. For compatibility reasons
 769     the directory <filename>/var/lib/container/</filename> is
 770     searched, too. Note that images stored below
 771     <filename>/usr</filename> are always considered read-only. It is
 772     possible to symlink machines images from other directories into
 773     <filename>/var/lib/machines/</filename> to make them available for
 774     control with <command>machinectl</command>.</para>
 775
 776     <para>Note that many image operations are only supported,
 777     efficient or atomic on btrfs file systems. Due to this, if the
 778     <command>pull-tar</command>, <command>pull-raw</command>,
 779     <command>pull-dkr</command>, <command>import-tar</command>,
 780     <command>import-raw</command> and <command>set-limit</command>
 781     commands notice that <filename>/var/lib/machines</filename> is
 782     empty and not located on btrfs, they will implicitly set up a
 783     loopback file <filename>/var/lib/machines.raw</filename>
 784     containing a btrfs file system that is mounted to
 785     <filename>/var/lib/machines</filename>. The size of this loopback
 786     file may be controlled dynamically with
 787     <command>set-limit</command>.</para>
 788
 789     <para>Disk images are understood by
 790     <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 791     and <command>machinectl</command> in three formats:</para>
 792
 793     <itemizedlist>
 794       <listitem><para>A simple directory tree, containing the files
 795       and directories of the container to boot.</para></listitem>
 796
 797       <listitem><para>A subvolume (on btrfs file systems), which are
 798       similar to the simple directories, described above. However,
 799       they have additional benefits, such as efficient cloning and
 800       quota reporting.</para></listitem>
 801
 802       <listitem><para>"Raw" disk images, i.e. binary images of disks
 803       with a GPT or MBR partition table. Images of this type are
 804       regular files with the suffix
 805       <literal>.raw</literal>.</para></listitem>
 806     </itemizedlist>
 807
 808     <para>See
 809     <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 810     for more information on image formats, in particular it's
 811     <option>--directory=</option> and <option>--image=</option>
 812     options.</para>
 813   </refsect1>
 814
 815   <refsect1>
 816     <title>Examples</title>
 817     <example>
 818       <title>Download an Ubuntu image and open a shell in it</title>
 819
 820       <programlisting># machinectl pull-tar https://cloud-images.ubuntu.com/trusty/current/trusty-server-cloudimg-amd64-root.tar.gz
 821 # systemd-nspawn -M trusty-server-cloudimg-amd64-root</programlisting>
 822
 823       <para>This downloads and verifies the specified
 824       <filename>.tar</filename> image, and then uses
 825       <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 826       to open a shell in it.</para>
 827     </example>
 828
 829     <example>
 830       <title>Download a Fedora image, set a root password in it, start
 831       it as service</title>
 832
 833       <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
 834 # systemd-nspawn -M Fedora-Cloud-Base-20141203-21
 835 # passwd
 836 # exit
 837 # machinectl start Fedora-Cloud-Base-20141203-21
 838 # machinectl login Fedora-Cloud-Base-20141203-21</programlisting>
 839
 840       <para>This downloads the specified <filename>.raw</filename>
 841       image with verification disabled. Then a shell is opened in it
 842       and a root password is set. Afterwards the shell is left, and
 843       the machine started as system service. With the last command a
 844       login prompt into the container is requested.</para>
 845     </example>
 846
 847     <example>
 848       <title>Download a Fedora <literal>dkr</literal> image</title>
 849
 850       <programlisting># machinectl pull-dkr --verify=no mattdm/fedora
 851 # systemd-nspawn -M fedora</programlisting>
 852
 853       <para>Downloads a <literal>dkr</literal> image and opens a shell
 854       in it. Note that the specified download command might require an
 855       index server to be specified with the
 856       <literal>--dkr-index-url=</literal>.</para>
 857     </example>
 858
 859     <example>
 860       <title>Exports a container image as tar file</title>
 861
 862       <programlisting># machinectl export-tar fedora myfedora.tar.xz</programlisting>
 863
 864       <para>Exports the container <literal>fedora</literal> in an
 865       xz-compress tar file <filename>myfedora.tar.xz</filename> in the
 866       current directory.</para>
 867     </example>
 868
 869   </refsect1>
 870
 871   <refsect1>
 872     <title>Exit status</title>
 873
 874     <para>On success, 0 is returned, a non-zero failure code
 875     otherwise.</para>
 876   </refsect1>
 877
 878   <xi:include href="less-variables.xml" />
 879
 880   <refsect1>
 881     <title>See Also</title>
 882     <para>
 883       <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 884       <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 885       <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 886       <citerefentry project='die-net'><refentrytitle>tar</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 887       <citerefentry project='die-net'><refentrytitle>xz</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 888       <citerefentry project='die-net'><refentrytitle>gzip</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 889       <citerefentry project='die-net'><refentrytitle>bzip2</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 890     </para>
 891   </refsect1>
 892
 893 </refentry>