1 <?xml version='
1.0'
?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
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>
69 <para><command>machinectl
</command> may be used to execute
70 operations on machines and images. Machines in this sense are
71 considered running instances of:
</para>
74 <listitem><para>Virtual Machines (VMs) that virtualize hardware
75 to run full operating system (OS) instances (including their kernels)
76 in a virtualized environment on top of the host OS.
</para></listitem>
78 <listitem><para>Containers that share the hardware and
79 OS kernel with the host OS, in order to run
80 OS userspace instances on top the host OS.
</para></listitem>
82 <listitem><para>The host system itself
</para></listitem>
85 <para>Machines are identified by names that follow the same rules
86 as UNIX and DNS host names, for details, see below. Machines are
87 instantiated from disk or file system images that frequently — but not
88 necessarily — carry the same name as machines running from
89 them. Images in this sense are considered:
</para>
92 <listitem><para>Directory trees containing an OS, including its
93 top-level directories
<filename>/usr
</filename>,
94 <filename>/etc
</filename>, and so on.
</para></listitem>
96 <listitem><para>btrfs subvolumes containing OS trees, similar to
97 normal directory trees.
</para></listitem>
99 <listitem><para>Binary
"raw" disk images containing MBR or GPT
100 partition tables and Linux file system partitions.
</para></listitem>
102 <listitem><para>The file system tree of the host OS itself.
</para></listitem>
108 <title>Options
</title>
110 <para>The following options are understood:
</para>
114 <term><option>-p
</option></term>
115 <term><option>--property=
</option></term>
117 <listitem><para>When showing machine or image properties,
118 limit the output to certain properties as specified by the
119 argument. If not specified, all set properties are shown. The
120 argument should be a property name, such as
121 <literal>Name
</literal>. If specified more than once, all
122 properties with the specified names are
123 shown.
</para></listitem>
127 <term><option>-a
</option></term>
128 <term><option>--all
</option></term>
130 <listitem><para>When showing machine or image properties, show
131 all properties regardless of whether they are set or
134 <para>When listing VM or container images, do not suppress
135 images beginning in a dot character
136 (
<literal>.
</literal>).
</para></listitem>
140 <term><option>-l
</option></term>
141 <term><option>--full
</option></term>
143 <listitem><para>Do not ellipsize process tree entries.
</para>
148 <term><option>--no-ask-password
</option></term>
150 <listitem><para>Do not query the user for authentication for
151 privileged operations.
</para></listitem>
155 <term><option>--kill-who=
</option></term>
157 <listitem><para>When used with
<command>kill
</command>, choose
158 which processes to kill. Must be one of
159 <option>leader
</option>, or
<option>all
</option> to select
160 whether to kill only the leader process of the machine or all
161 processes of the machine. If omitted, defaults to
162 <option>all
</option>.
</para></listitem>
166 <term><option>-s
</option></term>
167 <term><option>--signal=
</option></term>
169 <listitem><para>When used with
<command>kill
</command>, choose
170 which signal to send to selected processes. Must be one of the
171 well-known signal specifiers, such as
172 <constant>SIGTERM
</constant>,
<constant>SIGINT
</constant> or
173 <constant>SIGSTOP
</constant>. If omitted, defaults to
174 <constant>SIGTERM
</constant>.
</para></listitem>
178 <term><option>--uid=
</option></term>
180 <listitem><para>When used with the
<command>shell
</command>
181 command, chooses the user ID to open the interactive shell
182 session as. If this switch is not specified, defaults to
183 <literal>root
</literal>. Note that this switch is not
184 supported for the
<command>login
</command> command (see
185 below).
</para></listitem>
189 <term><option>--setenv=
</option></term>
191 <listitem><para>When used with the
<command>shell
</command>
192 command, sets an environment variable to pass to the executed
193 shell. Takes a pair of environment variable name and value,
194 separated by
<literal>=
</literal> as argument. This switch
195 may be used multiple times to set multiple environment
196 variables. Note that this switch is not supported for the
197 <command>login
</command> command (see
198 below).
</para></listitem>
202 <term><option>--mkdir
</option></term>
204 <listitem><para>When used with
<command>bind
</command>, creates
205 the destination directory before applying the bind
206 mount.
</para></listitem>
210 <term><option>--read-only
</option></term>
212 <listitem><para>When used with
<command>bind
</command>, applies
213 a read-only bind mount.
</para></listitem>
218 <term><option>-n
</option></term>
219 <term><option>--lines=
</option></term>
221 <listitem><para>When used with
<command>status
</command>,
222 controls the number of journal lines to show, counting from
223 the most recent ones. Takes a positive integer argument.
224 Defaults to
10.
</para>
229 <term><option>-o
</option></term>
230 <term><option>--output=
</option></term>
232 <listitem><para>When used with
<command>status
</command>,
233 controls the formatting of the journal entries that are shown.
234 For the available choices, see
235 <citerefentry><refentrytitle>journalctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
236 Defaults to
<literal>short
</literal>.
</para></listitem>
240 <term><option>--verify=
</option></term>
242 <listitem><para>When downloading a container or VM image,
243 specify whether the image shall be verified before it is made
244 available. Takes one of
<literal>no
</literal>,
245 <literal>checksum
</literal> and
<literal>signature
</literal>.
246 If
<literal>no
</literal>, no verification is done. If
247 <literal>checksum
</literal> is specified, the download is
248 checked for integrity after the transfer is complete, but no
249 signatures are verified. If
<literal>signature
</literal> is
250 specified, the checksum is verified and the images's signature
251 is checked against a local keyring of trustable vendors. It is
252 strongly recommended to set this option to
253 <literal>signature
</literal> if the server and protocol
254 support this. Defaults to
255 <literal>signature
</literal>.
</para></listitem>
259 <term><option>--force
</option></term>
261 <listitem><para>When downloading a container or VM image, and
262 a local copy by the specified local machine name already
263 exists, delete it first and replace it by the newly downloaded
264 image.
</para></listitem>
268 <term><option>--dkr-index-url
</option></term>
270 <listitem><para>Specifies the index server to use for
271 downloading
<literal>dkr
</literal> images with the
272 <command>pull-dkr
</command>. Takes a
273 <literal>http://
</literal>,
<literal>https://
</literal>
274 URL.
</para></listitem>
278 <term><option>--format=
</option></term>
280 <listitem><para>When used with the
<option>export-tar
</option>
281 or
<option>export-raw
</option> commands, specifies the
282 compression format to use for the resulting file. Takes one of
283 <literal>uncompressed
</literal>,
<literal>xz
</literal>,
284 <literal>gzip
</literal>,
<literal>bzip2
</literal>. By default,
285 the format is determined automatically from the image file
286 name passed.
</para></listitem>
289 <xi:include href=
"user-system-options.xml" xpointer=
"host" />
290 <xi:include href=
"user-system-options.xml" xpointer=
"machine" />
292 <xi:include href=
"standard-options.xml" xpointer=
"no-pager" />
293 <xi:include href=
"standard-options.xml" xpointer=
"no-legend" />
294 <xi:include href=
"standard-options.xml" xpointer=
"help" />
295 <xi:include href=
"standard-options.xml" xpointer=
"version" />
300 <title>Commands
</title>
302 <para>The following commands are understood:
</para>
304 <refsect2><title>Machine Commands
</title><variablelist>
307 <term><command>list
</command></term>
309 <listitem><para>List currently running (online) virtual
310 machines and containers. To enumerate machine images that can
311 be started, use
<command>list-images
</command> (see
312 below). Note that this command hides the special
313 <literal>.host
</literal> machine by default. Use the
314 <option>--all
</option> switch to show it.
</para></listitem>
318 <term><command>status
</command> <replaceable>NAME
</replaceable>...
</term>
320 <listitem><para>Show terse runtime status information about
321 one or more virtual machines and containers, followed by the
322 most recent log data from the journal. This function is
323 intended to generate human-readable output. If you are looking
324 for computer-parsable output, use
<command>show
</command>
325 instead. Note that the log data shown is reported by the
326 virtual machine or container manager, and frequently contains
327 console output of the machine, but not necessarily journal
328 contents of the machine itself.
</para></listitem>
332 <term><command>show
</command> [
<replaceable>NAME
</replaceable>...]
</term>
334 <listitem><para>Show properties of one or more registered
335 virtual machines or containers or the manager itself. If no
336 argument is specified, properties of the manager will be
337 shown. If an NAME is specified, properties of this virtual
338 machine or container are shown. By default, empty properties
339 are suppressed. Use
<option>--all
</option> to show those too.
340 To select specific properties to show, use
341 <option>--property=
</option>. This command is intended to be
342 used whenever computer-parsable output is required. Use
343 <command>status
</command> if you are looking for formatted
344 human-readable output.
</para></listitem>
348 <term><command>start
</command> <replaceable>NAME
</replaceable>...
</term>
350 <listitem><para>Start a container as a system service, using
351 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
352 This starts
<filename>systemd-nspawn@.service
</filename>,
353 instantiated for the specified machine name, similar to the
354 effect of
<command>systemctl start
</command> on the service
355 name.
<command>systemd-nspawn
</command> looks for a container
356 image by the specified name in
357 <filename>/var/lib/machines/
</filename> (and other search
358 paths, see below) and runs it. Use
359 <command>list-images
</command> (see below) for listing
360 available container images to start.
</para>
363 <citerefentry><refentrytitle>systemd-machined.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
364 also interfaces with a variety of other container and VM
365 managers,
<command>systemd-nspawn
</command> is just one
366 implementation of it. Most of the commands available in
367 <command>machinectl
</command> may be used on containers or VMs
368 controlled by other managers, not just
369 <command>systemd-nspawn
</command>. Starting VMs and container
370 images on those managers requires manager-specific
373 <para>To interactively start a container on the command line
374 with full access to the container's console, please invoke
375 <command>systemd-nspawn
</command> directly. To stop a running
376 container use
<command>machinectl poweroff
</command>, see
377 below.
</para></listitem>
381 <term><command>login
</command> [
<replaceable>NAME
</replaceable>]
</term>
383 <listitem><para>Open an interactive terminal login session in
384 a container or on the local host. If an argument is supplied,
385 it refers to the container machine to connect to. If none is
386 specified, or the container name is specified as the empty
387 string, or the special machine name
<literal>.host
</literal>
388 (see below) is specified, the connection is made to the local
389 host instead. This will create a TTY connection to a specific
390 container or the local host and asks for the execution of a
391 getty on it. Note that this is only supported for containers
393 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
394 as init system.
</para>
396 <para>This command will open a full login prompt on the
397 container or the local host, which then asks for username and
398 password. Use
<command>shell
</command> (see below) or
399 <citerefentry><refentrytitle>systemd-run
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
400 with the
<option>--machine=
</option> switch to directly invoke
401 a single command, either interactively or in the
402 background.
</para></listitem>
406 <term><command>shell
</command> [[
<replaceable>NAME
</replaceable>@]
<replaceable>NAME
</replaceable> [
<replaceable>PATH
</replaceable> [
<replaceable>ARGUMENTS
</replaceable>...]]]
</term>
408 <listitem><para>Open an interactive shell session in a
409 container or on the local host. The first argument refers to
410 the container machine to connect to. If none is specified, or
411 the machine name is specified as the empty string, or the
412 special machine name
<literal>.host
</literal> (see below) is
413 specified, the connection is made to the local host
414 instead. This works similar to
<command>login
</command> but
415 immediately invokes a user process. This command runs the
416 specified executable with the specified arguments, or
417 <filename>/bin/sh
</filename> if none is specified. By default,
418 opens a
<literal>root
</literal> shell, but by using
419 <option>--uid=
</option>, or by prefixing the machine name with
420 a username and an
<literal>@
</literal> character, a different
421 user may be selected. Use
<option>--setenv=
</option> to set
422 environment variables for the executed process.
</para>
424 <para>When using the
<command>shell
</command> command without
425 arguments, (thus invoking the executed shell or command on the
426 local host), it is in many ways similar to a
<citerefentry
427 project='die-net'
><refentrytitle>su
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
428 session, but, unlike
<command>su
</command>, completely isolates
429 the new session from the originating session, so that it
430 shares no process or session properties, and is in a clean and
431 well-defined state. It will be tracked in a new utmp, login,
432 audit, security and keyring session, and will not inherit any
433 environment variables or resource limits, among other
437 <citerefentry><refentrytitle>systemd-run
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
438 may be used in place of the
<command>shell
</command> command,
439 and allows more detailed, low-level configuration of the
440 invoked unit. However, it is frequently more privileged than
441 the
<command>shell
</command> command.
</para></listitem>
445 <term><command>enable
</command> <replaceable>NAME
</replaceable>...
</term>
446 <term><command>disable
</command> <replaceable>NAME
</replaceable>...
</term>
448 <listitem><para>Enable or disable a container as a system
449 service to start at system boot, using
450 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
451 This enables or disables
452 <filename>systemd-nspawn@.service
</filename>, instantiated for
453 the specified machine name, similar to the effect of
454 <command>systemctl enable
</command> or
<command>systemctl
455 disable
</command> on the service name.
</para></listitem>
459 <term><command>poweroff
</command> <replaceable>NAME
</replaceable>...
</term>
461 <listitem><para>Power off one or more containers. This will
462 trigger a reboot by sending SIGRTMIN+
4 to the container's init
463 process, which causes systemd-compatible init systems to shut
464 down cleanly. This operation does not work on containers that
466 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>-compatible
467 init system, such as sysvinit. Use
468 <command>terminate
</command> (see below) to immediately
469 terminate a container or VM, without cleanly shutting it
470 down.
</para></listitem>
474 <term><command>reboot
</command> <replaceable>NAME
</replaceable>...
</term>
476 <listitem><para>Reboot one or more containers. This will
477 trigger a reboot by sending SIGINT to the container's init
478 process, which is roughly equivalent to pressing Ctrl+Alt+Del
479 on a non-containerized system, and is compatible with
480 containers running any system manager.
</para></listitem>
484 <term><command>terminate
</command> <replaceable>NAME
</replaceable>...
</term>
486 <listitem><para>Immediately terminates a virtual machine or
487 container, without cleanly shutting it down. This kills all
488 processes of the virtual machine or container and deallocates
489 all resources attached to that instance. Use
490 <command>poweroff
</command> to issue a clean shutdown
491 request.
</para></listitem>
495 <term><command>kill
</command> <replaceable>NAME
</replaceable>...
</term>
497 <listitem><para>Send a signal to one or more processes of the
498 virtual machine or container. This means processes as seen by
499 the host, not the processes inside the virtual machine or
500 container. Use
<option>--kill-who=
</option> to select which
501 process to kill. Use
<option>--signal=
</option> to select the
502 signal to send.
</para></listitem>
506 <term><command>bind
</command> <replaceable>NAME
</replaceable> <replaceable>PATH
</replaceable> [
<replaceable>PATH
</replaceable>]
</term>
508 <listitem><para>Bind mounts a directory from the host into the
509 specified container. The first directory argument is the
510 source directory on the host, the second directory argument
511 is the destination directory in the container. When the
512 latter is omitted, the destination path in the container is
513 the same as the source path on the host. When combined with
514 the
<option>--read-only
</option> switch, a ready-only bind
515 mount is created. When combined with the
516 <option>--mkdir
</option> switch, the destination path is first
517 created before the mount is applied. Note that this option is
518 currently only supported for
519 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
520 containers.
</para></listitem>
524 <term><command>copy-to
</command> <replaceable>NAME
</replaceable> <replaceable>PATH
</replaceable> [
<replaceable>PATH
</replaceable>]
</term>
526 <listitem><para>Copies files or directories from the host
527 system into a running container. Takes a container name,
528 followed by the source path on the host and the destination
529 path in the container. If the destination path is omitted, the
530 same as the source path is used.
</para></listitem>
535 <term><command>copy-from
</command> <replaceable>NAME
</replaceable> <replaceable>PATH
</replaceable> [
<replaceable>PATH
</replaceable>]
</term>
537 <listitem><para>Copies files or directories from a container
538 into the host system. Takes a container name, followed by the
539 source path in the container the destination path on the host.
540 If the destination path is omitted, the same as the source path
541 is used.
</para></listitem>
543 </variablelist></refsect2>
545 <refsect2><title>Image Commands
</title><variablelist>
548 <term><command>list-images
</command></term>
550 <listitem><para>Show a list of locally installed container and
551 VM images. This enumerates all raw disk images and container
552 directories and subvolumes in
553 <filename>/var/lib/machines/
</filename> (and other search
554 paths, see below). Use
<command>start
</command> (see above) to
555 run a container off one of the listed images. Note that, by
556 default, containers whose name begins with a dot
557 (
<literal>.
</literal>) are not shown. To show these too,
558 specify
<option>--all
</option>. Note that a special image
559 <literal>.host
</literal> always implicitly exists and refers
560 to the image the host itself is booted from.
</para></listitem>
564 <term><command>image-status
</command> [
<replaceable>NAME
</replaceable>...]
</term>
566 <listitem><para>Show terse status information about one or
567 more container or VM images. This function is intended to
568 generate human-readable output. Use
569 <command>show-image
</command> (see below) to generate
570 computer-parsable output instead.
</para></listitem>
574 <term><command>show-image
</command> [
<replaceable>NAME
</replaceable>...]
</term>
576 <listitem><para>Show properties of one or more registered
577 virtual machine or container images, or the manager itself. If
578 no argument is specified, properties of the manager will be
579 shown. If an NAME is specified, properties of this virtual
580 machine or container image are shown. By default, empty
581 properties are suppressed. Use
<option>--all
</option> to show
582 those too. To select specific properties to show, use
583 <option>--property=
</option>. This command is intended to be
584 used whenever computer-parsable output is required. Use
585 <command>image-status
</command> if you are looking for
586 formatted human-readable output.
</para></listitem>
590 <term><command>clone
</command> <replaceable>NAME
</replaceable> <replaceable>NAME
</replaceable></term>
592 <listitem><para>Clones a container or VM image. The
593 arguments specify the name of the image to clone and the name
594 of the newly cloned image. Note that plain directory container
595 images are cloned into subvolume images with this command.
596 Note that cloning a container or VM image is optimized for
597 btrfs file systems, and might not be efficient on others, due
598 to file system limitations.
</para>
600 <para>Note that this command leaves host name, machine ID and
601 all other settings that could identify the instance
602 unmodified. The original image and the cloned copy will hence
603 share these credentials, and it might be necessary to manually
604 change them in the copy.
</para></listitem>
608 <term><command>rename
</command> <replaceable>NAME
</replaceable> <replaceable>NAME
</replaceable></term>
610 <listitem><para>Renames a container or VM image. The
611 arguments specify the name of the image to rename and the new
612 name of the image.
</para></listitem>
616 <term><command>read-only
</command> <replaceable>NAME
</replaceable> [
<replaceable>BOOL
</replaceable>]
</term>
618 <listitem><para>Marks or (unmarks) a container or VM image
619 read-only. Takes a VM or container image name, followed by a
620 boolean as arguments. If the boolean is omitted, positive is
621 implied, i.e. the image is marked read-only.
</para></listitem>
625 <term><command>remove
</command> <replaceable>NAME
</replaceable>...
</term>
627 <listitem><para>Removes one or more container or VM images.
628 The special image
<literal>.host
</literal>, which refers to
629 the host's own directory tree, may not be
630 removed.
</para></listitem>
634 <term><command>set-limit
</command> [
<replaceable>NAME
</replaceable>]
<replaceable>BYTES
</replaceable></term>
636 <listitem><para>Sets the maximum size in bytes that a specific
637 container or VM image, or all images, may grow up to on disk
638 (disk quota). Takes either one or two parameters. The first,
639 optional parameter refers to a container or VM image name. If
640 specified, the size limit of the specified image is changed. If
641 omitted, the overall size limit of the sum of all images stored
642 locally is changed. The final argument specifies the size
643 limit in bytes, possibly suffixed by the usual K, M, G, T
644 units. If the size limit shall be disabled, specify
645 <literal>-
</literal> as size.
</para>
647 <para>Note that per-container size limits are only supported
648 on btrfs file systems. Also note that, if
649 <command>set-limit
</command> is invoked without an image
650 parameter, and
<filename>/var/lib/machines
</filename> is
651 empty, and the directory is not located on btrfs, a btrfs
652 loopback file is implicitly created as
653 <filename>/var/lib/machines.raw
</filename> with the given
655 <filename>/var/lib/machines
</filename>. The size of the
656 loopback may later be readjusted with
657 <command>set-limit
</command>, as well. If such a
658 loopback-mounted
<filename>/var/lib/machines
</filename>
659 directory is used,
<command>set-limit
</command> without an image
660 name alters both the quota setting within the file system as
661 well as the loopback file and file system size
662 itself.
</para></listitem>
665 </variablelist></refsect2>
667 <refsect2><title>Image Transfer Commands
</title><variablelist>
670 <term><command>pull-tar
</command> <replaceable>URL
</replaceable> [
<replaceable>NAME
</replaceable>]
</term>
672 <listitem><para>Downloads a
<filename>.tar
</filename>
673 container image from the specified URL, and makes it available
674 under the specified local machine name. The URL must be of
675 type
<literal>http://
</literal> or
676 <literal>https://
</literal>, and must refer to a
677 <filename>.tar
</filename>,
<filename>.tar.gz
</filename>,
678 <filename>.tar.xz
</filename> or
<filename>.tar.bz2
</filename>
679 archive file. If the local machine name is omitted, it
680 is automatically derived from the last component of the URL,
681 with its suffix removed.
</para>
683 <para>The image is verified before it is made available,
684 unless
<option>--verify=no
</option> is specified. Verification
685 is done via SHA256SUMS and SHA256SUMS.gpg files that need to
686 be made available on the same web server, under the same URL
687 as the
<filename>.tar
</filename> file, but with the last
688 component (the filename) of the URL replaced. With
689 <option>--verify=checksum
</option>, only the SHA256 checksum
690 for the file is verified, based on the
691 <filename>SHA256SUMS
</filename> file. With
692 <option>--verify=signature
</option>, the SHA256SUMS file is
693 first verified with detached GPG signature file
694 <filename>SHA256SUMS.gpg
</filename>. The public key for this
695 verification step needs to be available in
696 <filename>/usr/lib/systemd/import-pubring.gpg
</filename> or
697 <filename>/etc/systemd/import-pubring.gpg
</filename>.
</para>
699 <para>The container image will be downloaded and stored in a
700 read-only subvolume in
701 <filename>/var/lib/machines/
</filename> that is named after
702 the specified URL and its HTTP etag. A writable snapshot is
703 then taken from this subvolume, and named after the specified
704 local name. This behavior ensures that creating multiple
705 container instances of the same URL is efficient, as multiple
706 downloads are not necessary. In order to create only the
707 read-only image, and avoid creating its writable snapshot,
708 specify
<literal>-
</literal> as local machine name.
</para>
710 <para>Note that the read-only subvolume is prefixed with
711 <filename>.tar-
</filename>, and is thus not shown by
712 <command>list-images
</command>, unless
<option>--all
</option>
715 <para>Note that pressing C-c during execution of this command
716 will not abort the download. Use
717 <command>cancel-transfer
</command>, described
718 below.
</para></listitem>
722 <term><command>pull-raw
</command> <replaceable>URL
</replaceable> [
<replaceable>NAME
</replaceable>]
</term>
724 <listitem><para>Downloads a
<filename>.raw
</filename>
725 container or VM disk image from the specified URL, and makes
726 it available under the specified local machine name. The URL
727 must be of type
<literal>http://
</literal> or
728 <literal>https://
</literal>. The container image must either
729 be a
<filename>.qcow2
</filename> or raw disk image, optionally
730 compressed as
<filename>.gz
</filename>,
731 <filename>.xz
</filename>, or
<filename>.bz2
</filename>. If the
732 local machine name is omitted, it is automatically
733 derived from the last component of the URL, with its suffix
736 <para>Image verification is identical for raw and tar images
739 <para>If the downloaded image is in
740 <filename>.qcow2
</filename> format it is converted into a raw
741 image file before it is made available.
</para>
743 <para>Downloaded images of this type will be placed as
744 read-only
<filename>.raw
</filename> file in
745 <filename>/var/lib/machines/
</filename>. A local, writable
746 (reflinked) copy is then made under the specified local
747 machine name. To omit creation of the local, writable copy
748 pass
<literal>-
</literal> as local machine name.
</para>
750 <para>Similar to the behavior of
<command>pull-tar
</command>,
751 the read-only image is prefixed with
752 <filename>.raw-
</filename>, and thus not shown by
753 <command>list-images
</command>, unless
<option>--all
</option>
756 <para>Note that pressing C-c during execution of this command
757 will not abort the download. Use
758 <command>cancel-transfer
</command>, described
759 below.
</para></listitem>
763 <term><command>pull-dkr
</command> <replaceable>REMOTE
</replaceable> [
<replaceable>NAME
</replaceable>]
</term>
765 <listitem><para>Downloads a
<literal>dkr
</literal> container
766 image and makes it available locally. The remote name refers
767 to a
<literal>dkr
</literal> container name. If omitted, the
768 local machine name is derived from the
<literal>dkr
</literal>
769 container name.
</para>
771 <para>Image verification is not available for
772 <literal>dkr
</literal> containers, and thus
773 <option>--verify=no
</option> must always be specified with
776 <para>This command downloads all (missing) layers for the
777 specified container and places them in read-only subvolumes in
778 <filename>/var/lib/machines/
</filename>. A writable snapshot
779 of the newest layer is then created under the specified local
780 machine name. To omit creation of this writable snapshot, pass
781 <literal>-
</literal> as local machine name.
</para>
783 <para>The read-only layer subvolumes are prefixed with
784 <filename>.dkr-
</filename>, and thus not shown by
785 <command>list-images
</command>, unless
<option>--all
</option>
788 <para>To specify the
<literal>dkr
</literal> index server to
789 use for looking up the specified container, use
790 <option>--dkr-index-url=
</option>.
</para>
792 <para>Note that pressing C-c during execution of this command
793 will not abort the download. Use
794 <command>cancel-transfer
</command>, described
795 below.
</para></listitem>
799 <term><command>import-tar
</command> <replaceable>FILE
</replaceable> [
<replaceable>NAME
</replaceable>]
</term>
800 <term><command>import-raw
</command> <replaceable>FILE
</replaceable> [
<replaceable>NAME
</replaceable>]
</term>
801 <listitem><para>Imports a TAR or RAW container or VM image,
802 and places it under the specified name in
803 <filename>/var/lib/machines/
</filename>. When
804 <command>import-tar
</command> is used, the file specified as
805 the first argument should be a tar archive, possibly compressed
806 with xz, gzip or bzip2. It will then be unpacked into its own
807 subvolume in
<filename>/var/lib/machines
</filename>. When
808 <command>import-raw
</command> is used, the file should be a
809 qcow2 or raw disk image, possibly compressed with xz, gzip or
810 bzip2. If the second argument (the resulting image name) is
811 not specified, it is automatically derived from the file
812 name. If the file name is passed as
<literal>-
</literal>, the
813 image is read from standard input, in which case the second
814 argument is mandatory.
</para>
816 <para>Similar as with
<command>pull-tar
</command>,
817 <command>pull-raw
</command> the file system
818 <filename>/var/lib/machines.raw
</filename> is increased in
819 size of necessary and appropriate. Optionally, the
820 <option>--read-only
</option> switch may be used to create a
821 read-only container or VM image. No cryptographic validation
822 is done when importing the images.
</para>
824 <para>Much like image downloads, ongoing imports may be listed
825 with
<command>list-transfers
</command> and aborted with
826 <command>cancel-transfer
</command>.
</para></listitem>
830 <term><command>export-tar
</command> <replaceable>NAME
</replaceable> [
<replaceable>FILE
</replaceable>]
</term>
831 <term><command>export-raw
</command> <replaceable>NAME
</replaceable> [
<replaceable>FILE
</replaceable>]
</term>
832 <listitem><para>Exports a TAR or RAW container or VM image and
833 stores it in the specified file. The first parameter should be
834 a VM or container image name. The second parameter should be a
835 file path the TAR or RAW image is written to. If the path ends
836 in
<literal>.gz
</literal>, the file is compressed with gzip, if
837 it ends in
<literal>.xz
</literal>, with xz, and if it ends in
838 <literal>.bz2
</literal>, with bzip2. If the path ends in
839 neither, the file is left uncompressed. If the second argument
840 is missing, the image is written to standard output. The
841 compression may also be explicitly selected with the
842 <option>--format=
</option> switch. This is in particular
843 useful if the second parameter is left unspecified.
</para>
845 <para>Much like image downloads and imports, ongoing exports
846 may be listed with
<command>list-transfers
</command> and
848 <command>cancel-transfer
</command>.
</para>
850 <para>Note that, currently, only directory and subvolume images
851 may be exported as TAR images, and only raw disk images as RAW
852 images.
</para></listitem>
856 <term><command>list-transfers
</command></term>
858 <listitem><para>Shows a list of container or VM image
859 downloads, imports and exports that are currently in
860 progress.
</para></listitem>
864 <term><command>cancel-transfers
</command> <replaceable>ID
</replaceable>...
</term>
866 <listitem><para>Aborts a download, import or export of the
867 container or VM image with the specified ID. To list ongoing
868 transfers and their IDs, use
869 <command>list-transfers
</command>.
</para></listitem>
872 </variablelist></refsect2>
877 <title>Machine and Image Names
</title>
879 <para>The
<command>machinectl
</command> tool operates on machines
880 and images whose names must be chosen following strict
881 rules. Machine names must be suitable for use as host names
882 following a conservative subset of DNS and UNIX/Linux
883 semantics. Specifically, they must consist of one or more
884 non-empty label strings, separated by dots. No leading or trailing
885 dots are allowed. No sequences of multiple dots are allowed. The
886 label strings may only consist of alphanumeric characters as well
887 as the dash and underscore. The maximum length of a machine name
888 is
64 characters.
</para>
890 <para>A special machine with the name
<literal>.host
</literal>
891 refers to the running host system itself. This is useful for execution
892 operations or inspecting the host system as well. Note that
893 <command>machinectl list
</command> will not show this special
894 machine unless the
<option>--all
</option> switch is specified.
</para>
896 <para>Requirements on image names are less strict, however, they must be
897 valid UTF-
8, must be suitable as file names (hence not be the
898 single or double dot, and not include a slash), and may not
899 contain control characters. Since many operations search for an
900 image by the name of a requested machine, it is recommended to name
901 images in the same strict fashion as machines.
</para>
903 <para>A special image with the name
<literal>.host
</literal>
904 refers to the image of the running host system. It hence
905 conceptually maps to the special
<literal>.host
</literal> machine
906 name described above. Note that
<command>machinectl
907 list-images
</command> will not show this special image either, unless
908 <option>--all
</option> is specified.
</para>
912 <title>Files and Directories
</title>
914 <para>Machine images are preferably stored in
915 <filename>/var/lib/machines/
</filename>, but are also searched for
916 in
<filename>/usr/local/lib/machines/
</filename> and
917 <filename>/usr/lib/machines/
</filename>. For compatibility reasons,
918 the directory
<filename>/var/lib/container/
</filename> is
919 searched, too. Note that images stored below
920 <filename>/usr
</filename> are always considered read-only. It is
921 possible to symlink machines images from other directories into
922 <filename>/var/lib/machines/
</filename> to make them available for
923 control with
<command>machinectl
</command>.
</para>
925 <para>Note that many image operations are only supported,
926 efficient or atomic on btrfs file systems. Due to this, if the
927 <command>pull-tar
</command>,
<command>pull-raw
</command>,
928 <command>pull-dkr
</command>,
<command>import-tar
</command>,
929 <command>import-raw
</command> and
<command>set-limit
</command>
930 commands notice that
<filename>/var/lib/machines
</filename> is
931 empty and not located on btrfs, they will implicitly set up a
932 loopback file
<filename>/var/lib/machines.raw
</filename>
933 containing a btrfs file system that is mounted to
934 <filename>/var/lib/machines
</filename>. The size of this loopback
935 file may be controlled dynamically with
936 <command>set-limit
</command>.
</para>
938 <para>Disk images are understood by
939 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
940 and
<command>machinectl
</command> in three formats:
</para>
943 <listitem><para>A simple directory tree, containing the files
944 and directories of the container to boot.
</para></listitem>
946 <listitem><para>Subvolumes (on btrfs file systems), which are
947 similar to the simple directories, described above. However,
948 they have additional benefits, such as efficient cloning and
949 quota reporting.
</para></listitem>
951 <listitem><para>"Raw" disk images, i.e. binary images of disks
952 with a GPT or MBR partition table. Images of this type are
953 regular files with the suffix
954 <literal>.raw
</literal>.
</para></listitem>
958 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
959 for more information on image formats, in particular its
960 <option>--directory=
</option> and
<option>--image=
</option>
965 <title>Examples
</title>
967 <title>Download an Ubuntu image and open a shell in it
</title>
969 <programlisting># machinectl pull-tar https://cloud-images.ubuntu.com/trusty/current/trusty-server-cloudimg-amd64-root.tar.gz
970 # systemd-nspawn -M trusty-server-cloudimg-amd64-root
</programlisting>
972 <para>This downloads and verifies the specified
973 <filename>.tar
</filename> image, and then uses
974 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
975 to open a shell in it.
</para>
979 <title>Download a Fedora image, set a root password in it, start
980 it as service
</title>
982 <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
983 # systemd-nspawn -M Fedora-Cloud-Base-
20141203-
21
986 # machinectl start Fedora-Cloud-Base-
20141203-
21
987 # machinectl login Fedora-Cloud-Base-
20141203-
21</programlisting>
989 <para>This downloads the specified
<filename>.raw
</filename>
990 image with verification disabled. Then, a shell is opened in it
991 and a root password is set. Afterwards the shell is left, and
992 the machine started as system service. With the last command a
993 login prompt into the container is requested.
</para>
997 <title>Download a Fedora
<literal>dkr
</literal> image
</title>
999 <programlisting># machinectl pull-dkr --verify=no mattdm/fedora
1000 # systemd-nspawn -M fedora
</programlisting>
1002 <para>Downloads a
<literal>dkr
</literal> image and opens a shell
1003 in it. Note that the specified download command might require an
1004 index server to be specified with the
1005 <literal>--dkr-index-url=
</literal>.
</para>
1009 <title>Exports a container image as tar file
</title>
1011 <programlisting># machinectl export-tar fedora myfedora.tar.xz
</programlisting>
1013 <para>Exports the container
<literal>fedora
</literal> as an
1014 xz-compressed tar file
<filename>myfedora.tar.xz
</filename> into the
1015 current directory.
</para>
1019 <title>Create a new shell session
</title>
1021 <programlisting># machinectl shell --uid=lennart
</programlisting>
1023 <para>This creates a new shell session on the local host for
1024 the user ID
<literal>lennart
</literal>, in a
<citerefentry
1025 project='die-net'
><refentrytitle>su
</refentrytitle><manvolnum>1</manvolnum></citerefentry>-like
1032 <title>Exit status
</title>
1034 <para>On success,
0 is returned, a non-zero failure code
1038 <xi:include href=
"less-variables.xml" />
1041 <title>See Also
</title>
1043 <citerefentry><refentrytitle>systemd-machined.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
1044 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1045 <citerefentry><refentrytitle>systemd.special
</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1046 <citerefentry project='die-net'
><refentrytitle>tar
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1047 <citerefentry project='die-net'
><refentrytitle>xz
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1048 <citerefentry project='die-net'
><refentrytitle>gzip
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1049 <citerefentry project='die-net'
><refentrytitle>bzip2
</refentrytitle><manvolnum>1</manvolnum></citerefentry>