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">
6 This file is part of systemd.
8 Copyright 2013 Zbigniew Jędrzejewski-Szmek
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.
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.
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/>.
24 <refentry id="machinectl" conditional='ENABLE_MACHINED'
25 xmlns:xi="http://www.w3.org/2001/XInclude">
28 <title>machinectl</title>
29 <productname>systemd</productname>
33 <contrib>Developer</contrib>
34 <firstname>Lennart</firstname>
35 <surname>Poettering</surname>
36 <email>lennart@poettering.net</email>
42 <refentrytitle>machinectl</refentrytitle>
43 <manvolnum>1</manvolnum>
47 <refname>machinectl</refname>
48 <refpurpose>Control the systemd machine manager</refpurpose>
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>
61 <title>Description</title>
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>
71 <title>Options</title>
73 <para>The following options are understood:</para>
77 <term><option>-p</option></term>
78 <term><option>--property=</option></term>
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>
90 <term><option>-a</option></term>
91 <term><option>--all</option></term>
93 <listitem><para>When showing machine or image properties, show
94 all properties regardless of whether they are set or
97 <para>When listing VM or container images, do not suppress
98 images beginning in a dot character
99 (<literal>.</literal>).</para></listitem>
103 <term><option>-l</option></term>
104 <term><option>--full</option></term>
106 <listitem><para>Do not ellipsize process tree entries.</para>
111 <term><option>--no-ask-password</option></term>
113 <listitem><para>Do not query the user for authentication for
114 privileged operations.</para></listitem>
118 <term><option>--kill-who=</option></term>
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>
129 <term><option>-s</option></term>
130 <term><option>--signal=</option></term>
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>
141 <term><option>--mkdir</option></term>
143 <listitem><para>When used with <command>bind</command> creates
144 the destination directory before applying the bind
145 mount.</para></listitem>
150 <term><option>--read-only</option></term>
152 <listitem><para>When used with <command>bind</command> applies
153 a read-only bind mount.</para></listitem>
158 <term><option>-n</option></term>
159 <term><option>--lines=</option></term>
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>
169 <term><option>-o</option></term>
170 <term><option>--output=</option></term>
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>
180 <term><option>--verify=</option></term>
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>
199 <term><option>--force</option></term>
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>
208 <term><option>--dkr-index-url</option></term>
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>
217 <xi:include href="user-system-options.xml" xpointer="host" />
218 <xi:include href="user-system-options.xml" xpointer="machine" />
220 <xi:include href="standard-options.xml" xpointer="no-pager" />
221 <xi:include href="standard-options.xml" xpointer="no-legend" />
222 <xi:include href="standard-options.xml" xpointer="help" />
223 <xi:include href="standard-options.xml" xpointer="version" />
228 <title>Commands</title>
230 <para>The following commands are understood:</para>
232 <refsect2><title>Machine Commands</title><variablelist>
235 <term><command>list</command></term>
237 <listitem><para>List currently running (online) virtual
238 machines and containers. To enumerate container images that
239 can be started, use <command>list-images</command> (see
240 below).</para></listitem>
244 <term><command>status</command> <replaceable>NAME</replaceable>...</term>
246 <listitem><para>Show terse runtime status information about
247 one or more virtual machines and containers, followed by the
248 most recent log data from the journal. This function is
249 intended to generate human-readable output. If you are looking
250 for computer-parsable output, use <command>show</command>
251 instead. Note that the log data shown is reported by the
252 virtual machine or container manager, and frequently contains
253 console output of the machine, but not necessarily journal
254 contents of the machine itself.</para></listitem>
258 <term><command>show</command> <replaceable>NAME</replaceable>...</term>
260 <listitem><para>Show properties of one or more registered
261 virtual machines or containers or the manager itself. If no
262 argument is specified, properties of the manager will be
263 shown. If an NAME is specified, properties of this virtual
264 machine or container are shown. By default, empty properties
265 are suppressed. Use <option>--all</option> to show those too.
266 To select specific properties to show, use
267 <option>--property=</option>. This command is intended to be
268 used whenever computer-parsable output is required. Use
269 <command>status</command> if you are looking for formatted
270 human-readable output.</para></listitem>
274 <term><command>start</command> <replaceable>NAME</replaceable>...</term>
276 <listitem><para>Start a container as a system service, using
277 <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
278 This starts <filename>systemd-nspawn@.service</filename>,
279 instantiated for the specified machine name, similar to the
280 effect of <command>systemctl start</command> on the service
281 name. <command>systemd-nspawn</command> looks for a container
282 image by the specified name in
283 <filename>/var/lib/machines/</filename> (and other search
284 paths, see below) and runs it. Use
285 <command>list-images</command> (see below), for listing
286 available container images to start.</para>
289 <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
290 also interfaces with a variety of other container and VM
291 managers, <command>systemd-nspawn</command> is just one
292 implementation of it. Most of the commands available in
293 <command>machinectl</command> may be used on containers or VMs
294 controlled by other managers, not just
295 <command>systemd-nspawn</command>. Starting VMs and container
296 images on those managers requires manager-specific
299 <para>To interactively start a container on the command line
300 with full access to the container's console, please invoke
301 <command>systemd-nspawn</command> directly. To stop a running
302 container use <command>machinectl poweroff</command>, see
303 below.</para></listitem>
307 <term><command>login</command> <replaceable>NAME</replaceable></term>
309 <listitem><para>Open an interactive terminal login session to
310 a container. This will create a TTY connection to a specific
311 container and asks for the execution of a getty on it. Note
312 that this is only supported for containers running
313 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
314 as init system.</para>
316 <para>This command will open a full login prompt on the
317 container, which then asks for username and password. Use
318 <citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry>
319 with the <option>--machine=</option> switch to invoke a single
320 command, either interactively or in the background within a
321 local container.</para></listitem>
325 <term><command>enable</command> <replaceable>NAME</replaceable>...</term>
326 <term><command>disable</command> <replaceable>NAME</replaceable>...</term>
328 <listitem><para>Enable or disable a container as a system
329 service to start at system boot, using
330 <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
331 This enables or disables
332 <filename>systemd-nspawn@.service</filename>, instantiated for
333 the specified machine name, similar to the effect of
334 <command>systemctl enable</command> or <command>systemctl
335 disable</command> on the service name.</para></listitem>
339 <term><command>poweroff</command> <replaceable>NAME</replaceable>...</term>
341 <listitem><para>Power off one or more containers. This will
342 trigger a reboot by sending SIGRTMIN+4 to the container's init
343 process, which causes systemd-compatible init systems to shut
344 down cleanly. This operation does not work on containers that
346 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>-compatible
347 init system, such as sysvinit. Use
348 <command>terminate</command> (see below) to immediately
349 terminate a container or VM, without cleanly shutting it
350 down.</para></listitem>
354 <term><command>reboot</command> <replaceable>NAME</replaceable>...</term>
356 <listitem><para>Reboot one or more containers. This will
357 trigger a reboot by sending SIGINT to the container's init
358 process, which is roughly equivalent to pressing Ctrl+Alt+Del
359 on a non-containerized system, and is compatible with
360 containers running any system manager.</para></listitem>
364 <term><command>terminate</command> <replaceable>NAME</replaceable>...</term>
366 <listitem><para>Immediately terminates a virtual machine or
367 container, without cleanly shutting it down. This kills all
368 processes of the virtual machine or container and deallocates
369 all resources attached to that instance. Use
370 <command>poweroff</command> to issue a clean shutdown
371 request.</para></listitem>
375 <term><command>kill</command> <replaceable>NAME</replaceable>...</term>
377 <listitem><para>Send a signal to one or more processes of the
378 virtual machine or container. This means processes as seen by
379 the host, not the processes inside the virtual machine or
380 container. Use <option>--kill-who=</option> to select which
381 process to kill. Use <option>--signal=</option> to select the
382 signal to send.</para></listitem>
386 <term><command>bind</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term>
388 <listitem><para>Bind mounts a directory from the host into the
389 specified container. The first directory argument is the
390 source directory on the host, the second directory argument
391 the source directory on the host. When the latter is omitted
392 the destination path in the container is the same as the
393 source path on the host. When combined with the
394 <option>--read-only</option> switch a ready-only bind mount is
395 created. When combined with the <option>--mkdir</option>
396 switch the destination path is first created before the mount
397 is applied. Note that this option is currently only supported
399 <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
400 containers.</para></listitem>
404 <term><command>copy-to</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term>
406 <listitem><para>Copies files or directories from the host
407 system into a running container. Takes a container name,
408 followed by the source path on the host and the destination
409 path in the container. If the destination path is omitted the
410 same as the source path is used.</para></listitem>
415 <term><command>copy-from</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term>
417 <listitem><para>Copies files or directories from a container
418 into the host system. Takes a container name, followed by the
419 source path in the container the destination path on the host.
420 If the destination path is omitted the same as the source path
421 is used.</para></listitem>
423 </variablelist></refsect2>
425 <refsect2><title>Image Commands</title><variablelist>
428 <term><command>list-images</command></term>
430 <listitem><para>Show a list of locally installed container and
431 VM images. This enumerates all raw disk images and container
432 directories and subvolumes in
433 <filename>/var/lib/machines/</filename> (and other search
434 paths, see below). Use <command>start</command> (see above) to
435 run a container off one of the listed images. Note that by
436 default containers whose name begins with a dot
437 (<literal>.</literal>) are not shown. To show these too,
438 specify <option>--all</option>. Note that a special image
439 <literal>.host</literal> always implicitly exists and refers
440 to the image the host itself is booted from.</para></listitem>
444 <term><command>image-status</command> <replaceable>NAME</replaceable>...</term>
446 <listitem><para>Show terse status information about one or
447 more container or VM images. This function is intended to
448 generate human-readable output. Use
449 <command>show-image</command> (see below) to generate
450 computer-parsable output instead.</para></listitem>
454 <term><command>show-image</command> <replaceable>NAME</replaceable>...</term>
456 <listitem><para>Show properties of one or more registered
457 virtual machine or container images, or the manager itself. If
458 no argument is specified, properties of the manager will be
459 shown. If an NAME is specified, properties of this virtual
460 machine or container image are shown. By default, empty
461 properties are suppressed. Use <option>--all</option> to show
462 those too. To select specific properties to show, use
463 <option>--property=</option>. This command is intended to be
464 used whenever computer-parsable output is required. Use
465 <command>image-status</command> if you are looking for
466 formatted human-readable output.</para></listitem>
470 <term><command>clone</command> <replaceable>NAME</replaceable> <replaceable>NAME</replaceable></term>
472 <listitem><para>Clones a container or VM image. The
473 arguments specify the name of the image to clone and the name
474 of the newly cloned image. Note that plain directory container
475 images are cloned into subvolume images with this command.
476 Note that cloning a container or VM image is optimized for
477 btrfs file systems, and might not be efficient on others, due
478 to file system limitations.</para></listitem>
482 <term><command>rename</command> <replaceable>NAME</replaceable> <replaceable>NAME</replaceable></term>
484 <listitem><para>Renames a container or VM image. The
485 arguments specify the name of the image to rename and the new
486 name of the image.</para></listitem>
490 <term><command>read-only</command> <replaceable>NAME</replaceable> [<replaceable>BOOL</replaceable>]</term>
492 <listitem><para>Marks or (unmarks) a container or VM image
493 read-only. Takes a VM or container image name, followed by a
494 boolean as arguments. If the boolean is omitted, positive is
495 implied, i.e. the image is marked read-only.</para></listitem>
499 <term><command>remove</command> <replaceable>NAME</replaceable>...</term>
501 <listitem><para>Removes one or more container or VM images.
502 The special image <literal>.host</literal>, which refers to
503 the host's own directory tree may not be
504 removed.</para></listitem>
508 <term><command>set-limit</command> [<replaceable>NAME</replaceable>] <replaceable>BYTES</replaceable></term>
510 <listitem><para>Sets the maximum size in bytes a specific
511 container or VM image, or all images may grow up to on disk
512 (disk quota). Takes either one or two parameters. The first,
513 optional parameter refers to a container or VM image name. If
514 specified the size limit of the specified image is changed. If
515 omitted the overall size limit of the sum of all images stored
516 locally is changed. The final argument specifies the size
517 limit in bytes, possibly suffixed by the usual K, M, G, T
518 units. If the size limit shall be disabled, specify
519 <literal>-</literal> as size.</para>
521 <para>Note that per-container size limits are only supported
522 on btrfs file systems. Also note that if
523 <command>set-limit</command> is invoked without image
524 parameter, and <filename>/var/lib/machines</filename> is
525 empty, and the directory is not located on btrfs, a btrfs
526 loopback file is implicitly created as
527 <filename>/var/lib/machines.raw</filename> with the given
529 <filename>/var/lib/machines</filename>. The size of the
530 loopback may later be readjusted with
531 <command>set-limit</command>, as well. If such a
532 loopback-mounted <filename>/var/lib/machines</filename>
533 directory is used <command>set-limit</command> without image
534 name alters both the quota setting within the file system as
535 well as the loopback file and file system size
536 itself.</para></listitem>
539 </variablelist></refsect2>
541 <refsect2><title>Image Transfer Commands</title><variablelist>
544 <term><command>pull-tar</command> <replaceable>URL</replaceable> [<replaceable>NAME</replaceable>]</term>
546 <listitem><para>Downloads a <filename>.tar</filename>
547 container image from the specified URL, and makes it available
548 under the specified local machine name. The URL must be of
549 type <literal>http://</literal> or
550 <literal>https://</literal>, and must refer to a
551 <filename>.tar</filename>, <filename>.tar.gz</filename>,
552 <filename>.tar.xz</filename> or <filename>.tar.bz2</filename>
553 archive file. If the local machine name is omitted the name it
554 is automatically derived from the last component of the URL,
555 with its suffix removed.</para>
557 <para>The image is verified before it is made available,
558 unless <option>--verify=no</option> is specified. Verification
559 is done via SHA256SUMS and SHA256SUMS.gpg files, that need to
560 be made available on the same web server, under the same URL
561 as the <filename>.tar</filename> file, but with the last
562 component (the filename) of the URL replaced. With
563 <option>--verify=checksum</option> only the SHA256 checksum
564 for the file is verified, based on the
565 <filename>SHA256SUMS</filename> file. With
566 <option>--verify=signature</option> the SHA256SUMS file is
567 first verified with detached GPG signature file
568 <filename>SHA256SUMS.gpg</filename>. The public key for this
569 verification step needs to be available in
570 <filename>/usr/lib/systemd/import-pubring.gpg</filename> or
571 <filename>/etc/systemd/import-pubring.gpg</filename>.</para>
573 <para>The container image will be downloaded and stored in a
574 read-only subvolume in
575 <filename>/var/lib/machines/</filename>, that is named after
576 the specified URL and its HTTP etag. A writable snapshot is
577 then taken from this subvolume, and named after the specified
578 local name. This behaviour ensures that creating multiple
579 container instances of the same URL is efficient, as multiple
580 downloads are not necessary. In order to create only the
581 read-only image, and avoid creating its writable snapshot,
582 specify <literal>-</literal> as local machine name.</para>
584 <para>Note that the read-only subvolume is prefixed with
585 <filename>.tar-</filename>, and is thus now shown by
586 <command>list-images</command>, unless <option>--all</option>
589 <para>Note that pressing C-c during execution of this command
590 will not abort the download. Use
591 <command>cancel-transfer</command>, described
592 below.</para></listitem>
596 <term><command>pull-raw</command> <replaceable>URL</replaceable> [<replaceable>NAME</replaceable>]</term>
598 <listitem><para>Downloads a <filename>.raw</filename>
599 container or VM disk image from the specified URL, and makes
600 it available under the specified local machine name. The URL
601 must be of type <literal>http://</literal> or
602 <literal>https://</literal>. The container image must either
603 be a <filename>.qcow2</filename> or raw disk image, optionally
604 compressed as <filename>.gz</filename>,
605 <filename>.xz</filename>, or <filename>.bz2</filename>. If the
606 local machine name is omitted the name it is automatically
607 derived from the last component of the URL, with its suffix
610 <para>Image verification is identical for raw and tar images
613 <para>If the the downloaded image is in
614 <filename>.qcow2</filename> format it es converted into a raw
615 image file before it is made available.</para>
617 <para>Downloaded images of this type will be placed as
618 read-only <filename>.raw</filename> file in
619 <filename>/var/lib/machines/</filename>. A local, writable
620 (reflinked) copy is then made under the specified local
621 machine name. To omit creation of the local, writable copy
622 pass <literal>-</literal> as local machine name.</para>
624 <para>Similar to the behaviour of <command>pull-tar</command>,
625 the read-only image is prefixed with
626 <filename>.raw-</filename>, and thus now shown by
627 <command>list-images</command>, unless <option>--all</option>
630 <para>Note that pressing C-c during execution of this command
631 will not abort the download. Use
632 <command>cancel-transfer</command>, described
633 below.</para></listitem>
637 <term><command>pull-dkr</command> <replaceable>REMOTE</replaceable> [<replaceable>NAME</replaceable>]</term>
639 <listitem><para>Downloads a <literal>dkr</literal> container
640 image and makes it available locally. The remote name refers
641 to a <literal>dkr</literal> container name. If omitted, the
642 local machine name is derived from the <literal>dkr</literal>
643 container name.</para>
645 <para>Image verification is not available for
646 <literal>dkr</literal> containers, and thus
647 <option>--verify=no</option> must always be specified with
650 <para>This command downloads all (missing) layers for the
651 specified container and places them in read-only subvolumes in
652 <filename>/var/lib/machines/</filename>. A writable snapshot
653 of the newest layer is then created under the specified local
654 machine name. To omit creation of this writable snapshot, pass
655 <literal>-</literal> as local machine name.</para>
657 <para>The read-only layer subvolumes are prefixed with
658 <filename>.dkr-</filename>, and thus now shown by
659 <command>list-images</command>, unless <option>--all</option>
662 <para>To specify the <literal>dkr</literal> index server to
663 use for looking up the specified container, use
664 <option>--dkr-index-url=</option>.</para>
666 <para>Note that pressing C-c during execution of this command
667 will not abort the download. Use
668 <command>cancel-transfer</command>, described
669 below.</para></listitem>
673 <term><command>list-transfers</command></term>
675 <listitem><para>Shows a list of container or VM image
676 downloads that are currently in progress.</para></listitem>
680 <term><command>cancel-transfers</command> <replaceable>ID</replaceable>...</term>
682 <listitem><para>Aborts download of the container or VM image
683 with the specified ID. To list ongoing transfers and their
684 IDs, use <command>list-transfers</command>. </para></listitem>
687 </variablelist></refsect2>
692 <title>Files and Directories</title>
694 <para>Machine images are preferably stored in
695 <filename>/var/lib/machines/</filename>, but are also searched for
696 in <filename>/usr/local/lib/machines/</filename> and
697 <filename>/usr/lib/machines/</filename>. For compatibility reasons
698 the directory <filename>/var/lib/container/</filename> is
699 searched, too. Note that images stored below
700 <filename>/usr</filename> are always considered read-only. It is
701 possible to symlink machines images from other directories into
702 <filename>/var/lib/machines/</filename> to make them available for
703 control with <command>machinectl</command>.</para>
705 <para>Note that many image operations are only supported,
706 efficient or atomic on btrfs file systems. Due to this, if the
707 <command>pull-tar</command>, <command>pull-raw</command>,
708 <command>pull-dkr</command> and <command>set-limit</command>
709 commands notice that <filename>/var/lib/machines</filename> is
710 empty and not located on btrfs, they will implicitly set up a
711 loopback file <filename>/var/lib/machines.raw</filename>
712 containing a btrfs file system that is mounted to
713 <filename>/var/lib/machines</filename>. The size of this loopback
714 file may be controlled dynamically with <command>set-limit</command>.</para>
716 <para>Disk images are understood by
717 <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
718 and <command>machinectl</command> in three formats:</para>
721 <listitem><para>A simple directory tree, containing the files
722 and directories of the container to boot.</para></listitem>
724 <listitem><para>A subvolume (on btrfs file systems), which are
725 similar to the simple directories, described above. However,
726 they have additional benefits, such as efficient cloning and
727 quota reporting.</para></listitem>
729 <listitem><para>"Raw" disk images, i.e. binary images of disks
730 with a GPT or MBR partition table. Images of this type are
731 regular files with the suffix
732 <literal>.raw</literal>.</para></listitem>
736 <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
737 for more information on image formats, in particular it's
738 <option>--directory=</option> and <option>--image=</option>
743 <title>Examples</title>
745 <title>Download an Ubuntu image and open a shell in it</title>
747 <programlisting># machinectl pull-tar https://cloud-images.ubuntu.com/trusty/current/trusty-server-cloudimg-amd64-root.tar.gz
748 # systemd-nspawn -M trusty-server-cloudimg-amd64-root</programlisting>
750 <para>This downloads and verifies the specified
751 <filename>.tar</filename> image, and then uses
752 <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
753 to open a shell in it.</para>
757 <title>Download a Fedora image, set a root password in it, start
758 it as service</title>
760 <programlisting># machinectl pull-raw --verify=no http://ftp.halifax.rwth-aachen.de/fedora/linux/releases/21/Cloud/Images/x86_64/Fedora-Cloud-Base-20141203-21.x86_64.raw.xz
761 # systemd-nspawn -M Fedora-Cloud-Base-20141203-21
764 # machinectl start Fedora-Cloud-Base-20141203-21
765 # machinectl login Fedora-Cloud-Base-20141203-21</programlisting>
767 <para>This downloads the specified <filename>.raw</filename>
768 image with verification disabled. Then a shell is opened in it
769 and a root password is set. Afterwards the shell is left, and
770 the machine started as system service. With the last command a
771 login prompt into the container is requested.</para>
775 <title>Download a Fedora <literal>dkr</literal> image</title>
777 <programlisting># machinectl pull-dkr --verify=no mattdm/fedora
778 # systemd-nspawn -M fedora</programlisting>
780 <para>Downloads a <literal>dkr</literal> image and opens a shell
781 in it. Note that the specified download command might require an
782 index server to be specified with the
783 <literal>--dkr-index-url=</literal>.</para>
788 <title>Exit status</title>
790 <para>On success, 0 is returned, a non-zero failure code
794 <xi:include href="less-variables.xml" />
797 <title>See Also</title>
799 <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
800 <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
801 <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>