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>
218 <term><option>--format=</option></term>
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>
229 <xi:include href="user-system-options.xml" xpointer="host" />
230 <xi:include href="user-system-options.xml" xpointer="machine" />
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" />
240 <title>Commands</title>
242 <para>The following commands are understood:</para>
244 <refsect2><title>Machine Commands</title><variablelist>
247 <term><command>list</command></term>
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>
256 <term><command>status</command> <replaceable>NAME</replaceable>...</term>
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>
270 <term><command>show</command> <replaceable>NAME</replaceable>...</term>
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>
286 <term><command>start</command> <replaceable>NAME</replaceable>...</term>
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>
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
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>
319 <term><command>login</command> <replaceable>NAME</replaceable></term>
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>
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>
337 <term><command>enable</command> <replaceable>NAME</replaceable>...</term>
338 <term><command>disable</command> <replaceable>NAME</replaceable>...</term>
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>
351 <term><command>poweroff</command> <replaceable>NAME</replaceable>...</term>
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
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>
366 <term><command>reboot</command> <replaceable>NAME</replaceable>...</term>
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>
376 <term><command>terminate</command> <replaceable>NAME</replaceable>...</term>
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>
387 <term><command>kill</command> <replaceable>NAME</replaceable>...</term>
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>
398 <term><command>bind</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term>
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
411 <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
412 containers.</para></listitem>
416 <term><command>copy-to</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term>
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>
427 <term><command>copy-from</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term>
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>
435 </variablelist></refsect2>
437 <refsect2><title>Image Commands</title><variablelist>
440 <term><command>list-images</command></term>
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>
456 <term><command>image-status</command> <replaceable>NAME</replaceable>...</term>
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>
466 <term><command>show-image</command> <replaceable>NAME</replaceable>...</term>
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>
482 <term><command>clone</command> <replaceable>NAME</replaceable> <replaceable>NAME</replaceable></term>
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>
494 <term><command>rename</command> <replaceable>NAME</replaceable> <replaceable>NAME</replaceable></term>
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>
502 <term><command>read-only</command> <replaceable>NAME</replaceable> [<replaceable>BOOL</replaceable>]</term>
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>
511 <term><command>remove</command> <replaceable>NAME</replaceable>...</term>
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>
520 <term><command>set-limit</command> [<replaceable>NAME</replaceable>] <replaceable>BYTES</replaceable></term>
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>
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
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>
551 </variablelist></refsect2>
553 <refsect2><title>Image Transfer Commands</title><variablelist>
556 <term><command>pull-tar</command> <replaceable>URL</replaceable> [<replaceable>NAME</replaceable>]</term>
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>
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>
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>
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>
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>
608 <term><command>pull-raw</command> <replaceable>URL</replaceable> [<replaceable>NAME</replaceable>]</term>
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
622 <para>Image verification is identical for raw and tar images
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>
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>
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>
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>
649 <term><command>pull-dkr</command> <replaceable>REMOTE</replaceable> [<replaceable>NAME</replaceable>]</term>
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>
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
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>
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>
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>
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>
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>
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>
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>
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>
731 <para>Much like image downloads and imports, ongoing exports
732 may be listed with <command>list-transfers</command> and
734 <command>cancel-transfer</command>.</para>
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>
742 <term><command>list-transfers</command></term>
744 <listitem><para>Shows a list of container or VM image
745 downloads, imports and exports that are currently in
746 progress.</para></listitem>
750 <term><command>cancel-transfers</command> <replaceable>ID</replaceable>...</term>
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>
758 </variablelist></refsect2>
763 <title>Files and Directories</title>
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>
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>
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>
794 <listitem><para>A simple directory tree, containing the files
795 and directories of the container to boot.</para></listitem>
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>
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>
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>
816 <title>Examples</title>
818 <title>Download an Ubuntu image and open a shell in it</title>
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>
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>
830 <title>Download a Fedora image, set a root password in it, start
831 it as service</title>
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
837 # machinectl start Fedora-Cloud-Base-20141203-21
838 # machinectl login Fedora-Cloud-Base-20141203-21</programlisting>
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>
848 <title>Download a Fedora <literal>dkr</literal> image</title>
850 <programlisting># machinectl pull-dkr --verify=no mattdm/fedora
851 # systemd-nspawn -M fedora</programlisting>
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>
860 <title>Exports a container image as tar file</title>
862 <programlisting># machinectl export-tar fedora myfedora.tar.xz</programlisting>
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>
872 <title>Exit status</title>
874 <para>On success, 0 is returned, a non-zero failure code
878 <xi:include href="less-variables.xml" />
881 <title>See Also</title>
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>