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>
138 <para>When cleaning VM or container images, remove all images, not just hidden ones.
</para></listitem>
142 <term><option>--value
</option></term>
144 <listitem><para>When printing properties with
<command>show
</command>, only print the value,
145 and skip the property name and
<literal>=
</literal>.
</para></listitem>
149 <term><option>-l
</option></term>
150 <term><option>--full
</option></term>
152 <listitem><para>Do not ellipsize process tree entries.
</para>
157 <term><option>--no-ask-password
</option></term>
159 <listitem><para>Do not query the user for authentication for
160 privileged operations.
</para></listitem>
164 <term><option>--kill-who=
</option></term>
166 <listitem><para>When used with
<command>kill
</command>, choose
167 which processes to kill. Must be one of
168 <option>leader
</option>, or
<option>all
</option> to select
169 whether to kill only the leader process of the machine or all
170 processes of the machine. If omitted, defaults to
171 <option>all
</option>.
</para></listitem>
175 <term><option>-s
</option></term>
176 <term><option>--signal=
</option></term>
178 <listitem><para>When used with
<command>kill
</command>, choose
179 which signal to send to selected processes. Must be one of the
180 well-known signal specifiers, such as
181 <constant>SIGTERM
</constant>,
<constant>SIGINT
</constant> or
182 <constant>SIGSTOP
</constant>. If omitted, defaults to
183 <constant>SIGTERM
</constant>.
</para></listitem>
187 <term><option>--uid=
</option></term>
189 <listitem><para>When used with the
<command>shell
</command>
190 command, chooses the user ID to open the interactive shell
191 session as. If this switch is not specified, defaults to
192 <literal>root
</literal>. Note that this switch is not
193 supported for the
<command>login
</command> command (see
194 below).
</para></listitem>
198 <term><option>-E
<replaceable>NAME
</replaceable>=
<replaceable>VALUE
</replaceable></option></term>
199 <term><option>--setenv=
<replaceable>NAME
</replaceable>=
<replaceable>VALUE
</replaceable></option></term>
201 <listitem><para>When used with the
<command>shell
</command> command, sets an environment
202 variable to pass to the executed shell. Takes an environment variable name and value,
203 separated by
<literal>=
</literal>. This switch may be used multiple times to set multiple
204 environment variables. Note that this switch is not supported for the
205 <command>login
</command> command (see below).
</para></listitem>
209 <term><option>--mkdir
</option></term>
211 <listitem><para>When used with
<command>bind
</command>, creates
212 the destination directory before applying the bind
213 mount.
</para></listitem>
217 <term><option>--read-only
</option></term>
219 <listitem><para>When used with
<command>bind
</command>, applies
220 a read-only bind mount.
</para>
222 <para>When used with
<command>clone
</command>,
<command>import-raw
</command> or
<command>import-tar
</command> a
223 read-only container or VM image is created.
</para></listitem>
227 <term><option>-n
</option></term>
228 <term><option>--lines=
</option></term>
230 <listitem><para>When used with
<command>status
</command>,
231 controls the number of journal lines to show, counting from
232 the most recent ones. Takes a positive integer argument.
233 Defaults to
10.
</para>
238 <term><option>-o
</option></term>
239 <term><option>--output=
</option></term>
241 <listitem><para>When used with
<command>status
</command>,
242 controls the formatting of the journal entries that are shown.
243 For the available choices, see
244 <citerefentry><refentrytitle>journalctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
245 Defaults to
<literal>short
</literal>.
</para></listitem>
249 <term><option>--verify=
</option></term>
251 <listitem><para>When downloading a container or VM image,
252 specify whether the image shall be verified before it is made
253 available. Takes one of
<literal>no
</literal>,
254 <literal>checksum
</literal> and
<literal>signature
</literal>.
255 If
<literal>no
</literal>, no verification is done. If
256 <literal>checksum
</literal> is specified, the download is
257 checked for integrity after the transfer is complete, but no
258 signatures are verified. If
<literal>signature
</literal> is
259 specified, the checksum is verified and the image's signature
260 is checked against a local keyring of trustable vendors. It is
261 strongly recommended to set this option to
262 <literal>signature
</literal> if the server and protocol
263 support this. Defaults to
264 <literal>signature
</literal>.
</para></listitem>
268 <term><option>--force
</option></term>
270 <listitem><para>When downloading a container or VM image, and
271 a local copy by the specified local machine name already
272 exists, delete it first and replace it by the newly downloaded
273 image.
</para></listitem>
277 <term><option>--format=
</option></term>
279 <listitem><para>When used with the
<option>export-tar
</option>
280 or
<option>export-raw
</option> commands, specifies the
281 compression format to use for the resulting file. Takes one of
282 <literal>uncompressed
</literal>,
<literal>xz
</literal>,
283 <literal>gzip
</literal>,
<literal>bzip2
</literal>. By default,
284 the format is determined automatically from the image file
285 name passed.
</para></listitem>
288 <xi:include href=
"user-system-options.xml" xpointer=
"host" />
289 <xi:include href=
"user-system-options.xml" xpointer=
"machine" />
291 <xi:include href=
"standard-options.xml" xpointer=
"no-pager" />
292 <xi:include href=
"standard-options.xml" xpointer=
"no-legend" />
293 <xi:include href=
"standard-options.xml" xpointer=
"help" />
294 <xi:include href=
"standard-options.xml" xpointer=
"version" />
299 <title>Commands
</title>
301 <para>The following commands are understood:
</para>
303 <refsect2><title>Machine Commands
</title><variablelist>
306 <term><command>list
</command></term>
308 <listitem><para>List currently running (online) virtual
309 machines and containers. To enumerate machine images that can
310 be started, use
<command>list-images
</command> (see
311 below). Note that this command hides the special
312 <literal>.host
</literal> machine by default. Use the
313 <option>--all
</option> switch to show it.
</para></listitem>
317 <term><command>status
</command> <replaceable>NAME
</replaceable>...
</term>
319 <listitem><para>Show runtime status information about
320 one or more virtual machines and containers, followed by the
321 most recent log data from the journal. This function is
322 intended to generate human-readable output. If you are looking
323 for computer-parsable output, use
<command>show
</command>
324 instead. Note that the log data shown is reported by the
325 virtual machine or container manager, and frequently contains
326 console output of the machine, but not necessarily journal
327 contents of the machine itself.
</para></listitem>
331 <term><command>show
</command> [
<replaceable>NAME
</replaceable>...]
</term>
333 <listitem><para>Show properties of one or more registered
334 virtual machines or containers or the manager itself. If no
335 argument is specified, properties of the manager will be
336 shown. If an NAME is specified, properties of this virtual
337 machine or container are shown. By default, empty properties
338 are suppressed. Use
<option>--all
</option> to show those too.
339 To select specific properties to show, use
340 <option>--property=
</option>. This command is intended to be
341 used whenever computer-parsable output is required, and does
342 not print the cgroup tree or journal entries. 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 arguments specify the name of the image to clone and the
593 name of the newly cloned image. Note that plain directory container images are cloned into btrfs subvolume
594 images with this command, if the underlying file system supports this. Note that cloning a container or VM
595 image is optimized for btrfs file systems, and might not be efficient on others, due to file system
598 <para>Note that this command leaves host name, machine ID and
599 all other settings that could identify the instance
600 unmodified. The original image and the cloned copy will hence
601 share these credentials, and it might be necessary to manually
602 change them in the copy.
</para>
604 <para>If combined with the
<option>--read-only
</option> switch a read-only cloned image is
605 created.
</para></listitem>
609 <term><command>rename
</command> <replaceable>NAME
</replaceable> <replaceable>NAME
</replaceable></term>
611 <listitem><para>Renames a container or VM image. The
612 arguments specify the name of the image to rename and the new
613 name of the image.
</para></listitem>
617 <term><command>read-only
</command> <replaceable>NAME
</replaceable> [
<replaceable>BOOL
</replaceable>]
</term>
619 <listitem><para>Marks or (unmarks) a container or VM image
620 read-only. Takes a VM or container image name, followed by a
621 boolean as arguments. If the boolean is omitted, positive is
622 implied, i.e. the image is marked read-only.
</para></listitem>
626 <term><command>remove
</command> <replaceable>NAME
</replaceable>...
</term>
628 <listitem><para>Removes one or more container or VM images.
629 The special image
<literal>.host
</literal>, which refers to
630 the host's own directory tree, may not be
631 removed.
</para></listitem>
635 <term><command>set-limit
</command> [
<replaceable>NAME
</replaceable>]
<replaceable>BYTES
</replaceable></term>
637 <listitem><para>Sets the maximum size in bytes that a specific
638 container or VM image, or all images, may grow up to on disk
639 (disk quota). Takes either one or two parameters. The first,
640 optional parameter refers to a container or VM image name. If
641 specified, the size limit of the specified image is changed. If
642 omitted, the overall size limit of the sum of all images stored
643 locally is changed. The final argument specifies the size
644 limit in bytes, possibly suffixed by the usual K, M, G, T
645 units. If the size limit shall be disabled, specify
646 <literal>-
</literal> as size.
</para>
648 <para>Note that per-container size limits are only supported
649 on btrfs file systems. Also note that, if
650 <command>set-limit
</command> is invoked without an image
651 parameter, and
<filename>/var/lib/machines
</filename> is
652 empty, and the directory is not located on btrfs, a btrfs
653 loopback file is implicitly created as
654 <filename>/var/lib/machines.raw
</filename> with the given
656 <filename>/var/lib/machines
</filename>. The size of the
657 loopback may later be readjusted with
658 <command>set-limit
</command>, as well. If such a
659 loopback-mounted
<filename>/var/lib/machines
</filename>
660 directory is used,
<command>set-limit
</command> without an image
661 name alters both the quota setting within the file system as
662 well as the loopback file and file system size
663 itself.
</para></listitem>
667 <term><command>clean
</command></term>
669 <listitem><para>Remove hidden VM or container images (or all). This command removes all hidden machine images
670 from
<filename>/var/lib/machines
</filename>, i.e. those whose name begins with a dot. Use
<command>machinectl
671 list-images --all
</command> to see a list of all machine images, including the hidden ones.
</para>
673 <para>When combined with the
<option>--all
</option> switch removes all images, not just hidden ones. This
674 command effectively empties
<filename>/var/lib/machines
</filename>.
</para>
676 <para>Note that commands such as
<command>machinectl pull-tar
</command> or
<command>machinectl
677 pull-raw
</command> usually create hidden, read-only, unmodified machine images from the downloaded image first,
678 before cloning a writable working copy of it, in order to avoid duplicate downloads in case of images that are
679 reused multiple times. Use
<command>machinectl clean
</command> to remove old, hidden images created this
680 way.
</para></listitem>
683 </variablelist></refsect2>
685 <refsect2><title>Image Transfer Commands
</title><variablelist>
688 <term><command>pull-tar
</command> <replaceable>URL
</replaceable> [
<replaceable>NAME
</replaceable>]
</term>
690 <listitem><para>Downloads a
<filename>.tar
</filename>
691 container image from the specified URL, and makes it available
692 under the specified local machine name. The URL must be of
693 type
<literal>http://
</literal> or
694 <literal>https://
</literal>, and must refer to a
695 <filename>.tar
</filename>,
<filename>.tar.gz
</filename>,
696 <filename>.tar.xz
</filename> or
<filename>.tar.bz2
</filename>
697 archive file. If the local machine name is omitted, it
698 is automatically derived from the last component of the URL,
699 with its suffix removed.
</para>
701 <para>The image is verified before it is made available,
702 unless
<option>--verify=no
</option> is specified. Verification
703 is done via SHA256SUMS and SHA256SUMS.gpg files that need to
704 be made available on the same web server, under the same URL
705 as the
<filename>.tar
</filename> file, but with the last
706 component (the filename) of the URL replaced. With
707 <option>--verify=checksum
</option>, only the SHA256 checksum
708 for the file is verified, based on the
709 <filename>SHA256SUMS
</filename> file. With
710 <option>--verify=signature
</option>, the SHA256SUMS file is
711 first verified with detached GPG signature file
712 <filename>SHA256SUMS.gpg
</filename>. The public key for this
713 verification step needs to be available in
714 <filename>/usr/lib/systemd/import-pubring.gpg
</filename> or
715 <filename>/etc/systemd/import-pubring.gpg
</filename>.
</para>
717 <para>The container image will be downloaded and stored in a
718 read-only subvolume in
719 <filename>/var/lib/machines/
</filename> that is named after
720 the specified URL and its HTTP etag. A writable snapshot is
721 then taken from this subvolume, and named after the specified
722 local name. This behavior ensures that creating multiple
723 container instances of the same URL is efficient, as multiple
724 downloads are not necessary. In order to create only the
725 read-only image, and avoid creating its writable snapshot,
726 specify
<literal>-
</literal> as local machine name.
</para>
728 <para>Note that the read-only subvolume is prefixed with
729 <filename>.tar-
</filename>, and is thus not shown by
730 <command>list-images
</command>, unless
<option>--all
</option>
733 <para>Note that pressing C-c during execution of this command
734 will not abort the download. Use
735 <command>cancel-transfer
</command>, described
736 below.
</para></listitem>
740 <term><command>pull-raw
</command> <replaceable>URL
</replaceable> [
<replaceable>NAME
</replaceable>]
</term>
742 <listitem><para>Downloads a
<filename>.raw
</filename>
743 container or VM disk image from the specified URL, and makes
744 it available under the specified local machine name. The URL
745 must be of type
<literal>http://
</literal> or
746 <literal>https://
</literal>. The container image must either
747 be a
<filename>.qcow2
</filename> or raw disk image, optionally
748 compressed as
<filename>.gz
</filename>,
749 <filename>.xz
</filename>, or
<filename>.bz2
</filename>. If the
750 local machine name is omitted, it is automatically
751 derived from the last component of the URL, with its suffix
754 <para>Image verification is identical for raw and tar images
757 <para>If the downloaded image is in
758 <filename>.qcow2
</filename> format it is converted into a raw
759 image file before it is made available.
</para>
761 <para>Downloaded images of this type will be placed as
762 read-only
<filename>.raw
</filename> file in
763 <filename>/var/lib/machines/
</filename>. A local, writable
764 (reflinked) copy is then made under the specified local
765 machine name. To omit creation of the local, writable copy
766 pass
<literal>-
</literal> as local machine name.
</para>
768 <para>Similar to the behavior of
<command>pull-tar
</command>,
769 the read-only image is prefixed with
770 <filename>.raw-
</filename>, and thus not shown by
771 <command>list-images
</command>, unless
<option>--all
</option>
774 <para>Note that pressing C-c during execution of this command
775 will not abort the download. Use
776 <command>cancel-transfer
</command>, described
777 below.
</para></listitem>
781 <term><command>import-tar
</command> <replaceable>FILE
</replaceable> [
<replaceable>NAME
</replaceable>]
</term>
782 <term><command>import-raw
</command> <replaceable>FILE
</replaceable> [
<replaceable>NAME
</replaceable>]
</term>
783 <listitem><para>Imports a TAR or RAW container or VM image,
784 and places it under the specified name in
785 <filename>/var/lib/machines/
</filename>. When
786 <command>import-tar
</command> is used, the file specified as
787 the first argument should be a tar archive, possibly compressed
788 with xz, gzip or bzip2. It will then be unpacked into its own
789 subvolume in
<filename>/var/lib/machines
</filename>. When
790 <command>import-raw
</command> is used, the file should be a
791 qcow2 or raw disk image, possibly compressed with xz, gzip or
792 bzip2. If the second argument (the resulting image name) is
793 not specified, it is automatically derived from the file
794 name. If the file name is passed as
<literal>-
</literal>, the
795 image is read from standard input, in which case the second
796 argument is mandatory.
</para>
798 <para>Both
<command>pull-tar
</command> and
<command>pull-raw
</command>
799 will resize
<filename>/var/lib/machines.raw
</filename> and the
800 filesystem therein as necessary. Optionally, the
801 <option>--read-only
</option> switch may be used to create a
802 read-only container or VM image. No cryptographic validation
803 is done when importing the images.
</para>
805 <para>Much like image downloads, ongoing imports may be listed
806 with
<command>list-transfers
</command> and aborted with
807 <command>cancel-transfer
</command>.
</para></listitem>
811 <term><command>export-tar
</command> <replaceable>NAME
</replaceable> [
<replaceable>FILE
</replaceable>]
</term>
812 <term><command>export-raw
</command> <replaceable>NAME
</replaceable> [
<replaceable>FILE
</replaceable>]
</term>
813 <listitem><para>Exports a TAR or RAW container or VM image and
814 stores it in the specified file. The first parameter should be
815 a VM or container image name. The second parameter should be a
816 file path the TAR or RAW image is written to. If the path ends
817 in
<literal>.gz
</literal>, the file is compressed with gzip, if
818 it ends in
<literal>.xz
</literal>, with xz, and if it ends in
819 <literal>.bz2
</literal>, with bzip2. If the path ends in
820 neither, the file is left uncompressed. If the second argument
821 is missing, the image is written to standard output. The
822 compression may also be explicitly selected with the
823 <option>--format=
</option> switch. This is in particular
824 useful if the second parameter is left unspecified.
</para>
826 <para>Much like image downloads and imports, ongoing exports
827 may be listed with
<command>list-transfers
</command> and
829 <command>cancel-transfer
</command>.
</para>
831 <para>Note that, currently, only directory and subvolume images
832 may be exported as TAR images, and only raw disk images as RAW
833 images.
</para></listitem>
837 <term><command>list-transfers
</command></term>
839 <listitem><para>Shows a list of container or VM image
840 downloads, imports and exports that are currently in
841 progress.
</para></listitem>
845 <term><command>cancel-transfers
</command> <replaceable>ID
</replaceable>...
</term>
847 <listitem><para>Aborts a download, import or export of the
848 container or VM image with the specified ID. To list ongoing
849 transfers and their IDs, use
850 <command>list-transfers
</command>.
</para></listitem>
853 </variablelist></refsect2>
858 <title>Machine and Image Names
</title>
860 <para>The
<command>machinectl
</command> tool operates on machines
861 and images whose names must be chosen following strict
862 rules. Machine names must be suitable for use as host names
863 following a conservative subset of DNS and UNIX/Linux
864 semantics. Specifically, they must consist of one or more
865 non-empty label strings, separated by dots. No leading or trailing
866 dots are allowed. No sequences of multiple dots are allowed. The
867 label strings may only consist of alphanumeric characters as well
868 as the dash and underscore. The maximum length of a machine name
869 is
64 characters.
</para>
871 <para>A special machine with the name
<literal>.host
</literal>
872 refers to the running host system itself. This is useful for execution
873 operations or inspecting the host system as well. Note that
874 <command>machinectl list
</command> will not show this special
875 machine unless the
<option>--all
</option> switch is specified.
</para>
877 <para>Requirements on image names are less strict, however, they must be
878 valid UTF-
8, must be suitable as file names (hence not be the
879 single or double dot, and not include a slash), and may not
880 contain control characters. Since many operations search for an
881 image by the name of a requested machine, it is recommended to name
882 images in the same strict fashion as machines.
</para>
884 <para>A special image with the name
<literal>.host
</literal>
885 refers to the image of the running host system. It hence
886 conceptually maps to the special
<literal>.host
</literal> machine
887 name described above. Note that
<command>machinectl
888 list-images
</command> will not show this special image either, unless
889 <option>--all
</option> is specified.
</para>
893 <title>Files and Directories
</title>
895 <para>Machine images are preferably stored in
896 <filename>/var/lib/machines/
</filename>, but are also searched for
897 in
<filename>/usr/local/lib/machines/
</filename> and
898 <filename>/usr/lib/machines/
</filename>. For compatibility reasons,
899 the directory
<filename>/var/lib/container/
</filename> is
900 searched, too. Note that images stored below
901 <filename>/usr
</filename> are always considered read-only. It is
902 possible to symlink machines images from other directories into
903 <filename>/var/lib/machines/
</filename> to make them available for
904 control with
<command>machinectl
</command>.
</para>
906 <para>Note that many image operations are only supported,
907 efficient or atomic on btrfs file systems. Due to this, if the
908 <command>pull-tar
</command>,
<command>pull-raw
</command>,
909 <command>import-tar
</command>,
<command>import-raw
</command> and
910 <command>set-limit
</command> commands notice that
911 <filename>/var/lib/machines
</filename> is empty and not located on
912 btrfs, they will implicitly set up a loopback file
913 <filename>/var/lib/machines.raw
</filename> containing a btrfs file
914 system that is mounted to
915 <filename>/var/lib/machines
</filename>. The size of this loopback
916 file may be controlled dynamically with
917 <command>set-limit
</command>.
</para>
919 <para>Disk images are understood by
920 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
921 and
<command>machinectl
</command> in three formats:
</para>
924 <listitem><para>A simple directory tree, containing the files
925 and directories of the container to boot.
</para></listitem>
927 <listitem><para>Subvolumes (on btrfs file systems), which are
928 similar to the simple directories, described above. However,
929 they have additional benefits, such as efficient cloning and
930 quota reporting.
</para></listitem>
932 <listitem><para>"Raw" disk images, i.e. binary images of disks
933 with a GPT or MBR partition table. Images of this type are
934 regular files with the suffix
935 <literal>.raw
</literal>.
</para></listitem>
939 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
940 for more information on image formats, in particular its
941 <option>--directory=
</option> and
<option>--image=
</option>
946 <title>Examples
</title>
948 <title>Download an Ubuntu image and open a shell in it
</title>
950 <programlisting># machinectl pull-tar https://cloud-images.ubuntu.com/trusty/current/trusty-server-cloudimg-amd64-root.tar.gz
951 # systemd-nspawn -M trusty-server-cloudimg-amd64-root
</programlisting>
953 <para>This downloads and verifies the specified
954 <filename>.tar
</filename> image, and then uses
955 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
956 to open a shell in it.
</para>
960 <title>Download a Fedora image, set a root password in it, start
961 it as service
</title>
963 <programlisting># machinectl pull-raw --verify=no https://dl.fedoraproject.org/pub/fedora/linux/releases/
23/Cloud/x86_64/Images/Fedora-Cloud-Base-
23-
20151030.x86_64.raw.xz
964 # systemd-nspawn -M Fedora-Cloud-Base-
23-
20151030
967 # machinectl start Fedora-Cloud-Base-
23-
20151030
968 # machinectl login Fedora-Cloud-Base-
23-
20151030</programlisting>
970 <para>This downloads the specified
<filename>.raw
</filename>
971 image with verification disabled. Then, a shell is opened in it
972 and a root password is set. Afterwards the shell is left, and
973 the machine started as system service. With the last command a
974 login prompt into the container is requested.
</para>
978 <title>Exports a container image as tar file
</title>
980 <programlisting># machinectl export-tar fedora myfedora.tar.xz
</programlisting>
982 <para>Exports the container
<literal>fedora
</literal> as an
983 xz-compressed tar file
<filename>myfedora.tar.xz
</filename> into the
984 current directory.
</para>
988 <title>Create a new shell session
</title>
990 <programlisting># machinectl shell --uid=lennart
</programlisting>
992 <para>This creates a new shell session on the local host for
993 the user ID
<literal>lennart
</literal>, in a
<citerefentry
994 project='die-net'
><refentrytitle>su
</refentrytitle><manvolnum>1</manvolnum></citerefentry>-like
1001 <title>Exit status
</title>
1003 <para>On success,
0 is returned, a non-zero failure code
1007 <xi:include href=
"less-variables.xml" />
1010 <title>See Also
</title>
1012 <citerefentry><refentrytitle>systemd-machined.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
1013 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1014 <citerefentry><refentrytitle>systemd.special
</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1015 <citerefentry project='die-net'
><refentrytitle>tar
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1016 <citerefentry project='die-net'
><refentrytitle>xz
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1017 <citerefentry project='die-net'
><refentrytitle>gzip
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1018 <citerefentry project='die-net'
><refentrytitle>bzip2
</refentrytitle><manvolnum>1</manvolnum></citerefentry>