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> command, chooses the user ID to
190 open the interactive shell session as. If the argument to the
<command>shell
</command>
191 command also specifies an user name, this option is ignored. If the name is not specified
192 in either way,
<literal>root
</literal> will be used by default. Note that this switch is
193 not supported for the
<command>login
</command> command (see below).
</para></listitem>
197 <term><option>-E
<replaceable>NAME
</replaceable>=
<replaceable>VALUE
</replaceable></option></term>
198 <term><option>--setenv=
<replaceable>NAME
</replaceable>=
<replaceable>VALUE
</replaceable></option></term>
200 <listitem><para>When used with the
<command>shell
</command> command, sets an environment
201 variable to pass to the executed shell. Takes an environment variable name and value,
202 separated by
<literal>=
</literal>. This switch may be used multiple times to set multiple
203 environment variables. Note that this switch is not supported for the
204 <command>login
</command> command (see below).
</para></listitem>
208 <term><option>--mkdir
</option></term>
210 <listitem><para>When used with
<command>bind
</command>, creates
211 the destination directory before applying the bind
212 mount.
</para></listitem>
216 <term><option>--read-only
</option></term>
218 <listitem><para>When used with
<command>bind
</command>, applies
219 a read-only bind mount.
</para>
221 <para>When used with
<command>clone
</command>,
<command>import-raw
</command> or
<command>import-tar
</command> a
222 read-only container or VM image is created.
</para></listitem>
226 <term><option>-n
</option></term>
227 <term><option>--lines=
</option></term>
229 <listitem><para>When used with
<command>status
</command>,
230 controls the number of journal lines to show, counting from
231 the most recent ones. Takes a positive integer argument.
232 Defaults to
10.
</para>
237 <term><option>-o
</option></term>
238 <term><option>--output=
</option></term>
240 <listitem><para>When used with
<command>status
</command>,
241 controls the formatting of the journal entries that are shown.
242 For the available choices, see
243 <citerefentry><refentrytitle>journalctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
244 Defaults to
<literal>short
</literal>.
</para></listitem>
248 <term><option>--verify=
</option></term>
250 <listitem><para>When downloading a container or VM image,
251 specify whether the image shall be verified before it is made
252 available. Takes one of
<literal>no
</literal>,
253 <literal>checksum
</literal> and
<literal>signature
</literal>.
254 If
<literal>no
</literal>, no verification is done. If
255 <literal>checksum
</literal> is specified, the download is
256 checked for integrity after the transfer is complete, but no
257 signatures are verified. If
<literal>signature
</literal> is
258 specified, the checksum is verified and the image's signature
259 is checked against a local keyring of trustable vendors. It is
260 strongly recommended to set this option to
261 <literal>signature
</literal> if the server and protocol
262 support this. Defaults to
263 <literal>signature
</literal>.
</para></listitem>
267 <term><option>--force
</option></term>
269 <listitem><para>When downloading a container or VM image, and
270 a local copy by the specified local machine name already
271 exists, delete it first and replace it by the newly downloaded
272 image.
</para></listitem>
276 <term><option>--format=
</option></term>
278 <listitem><para>When used with the
<option>export-tar
</option>
279 or
<option>export-raw
</option> commands, specifies the
280 compression format to use for the resulting file. Takes one of
281 <literal>uncompressed
</literal>,
<literal>xz
</literal>,
282 <literal>gzip
</literal>,
<literal>bzip2
</literal>. By default,
283 the format is determined automatically from the image file
284 name passed.
</para></listitem>
288 <term><option>--max-addresses=
</option></term>
290 <listitem><para>When used with the
<option>list-machines
</option>
291 command, limits the number of ip addresses output for every machine.
292 Defaults to
1. All addresses can be requested with
<literal>all
</literal>
293 as argument to
<option>--max-addresses
</option> . If the argument to
294 <option>--max-addresses
</option> is less than the actual number
295 of addresses,
<literal>...
</literal>follows the last address.
296 If multiple addresses are to be written for a given machine, every
297 address except the first one is on a new line and is followed by
298 <literal>,
</literal> if another address will be output afterwards.
</para></listitem>
301 <xi:include href=
"user-system-options.xml" xpointer=
"host" />
302 <xi:include href=
"user-system-options.xml" xpointer=
"machine" />
304 <xi:include href=
"standard-options.xml" xpointer=
"no-pager" />
305 <xi:include href=
"standard-options.xml" xpointer=
"no-legend" />
306 <xi:include href=
"standard-options.xml" xpointer=
"help" />
307 <xi:include href=
"standard-options.xml" xpointer=
"version" />
312 <title>Commands
</title>
314 <para>The following commands are understood:
</para>
316 <refsect2><title>Machine Commands
</title><variablelist>
319 <term><command>list
</command></term>
321 <listitem><para>List currently running (online) virtual
322 machines and containers. To enumerate machine images that can
323 be started, use
<command>list-images
</command> (see
324 below). Note that this command hides the special
325 <literal>.host
</literal> machine by default. Use the
326 <option>--all
</option> switch to show it.
</para></listitem>
330 <term><command>status
</command> <replaceable>NAME
</replaceable>...
</term>
332 <listitem><para>Show runtime status information about
333 one or more virtual machines and containers, followed by the
334 most recent log data from the journal. This function is
335 intended to generate human-readable output. If you are looking
336 for computer-parsable output, use
<command>show
</command>
337 instead. Note that the log data shown is reported by the
338 virtual machine or container manager, and frequently contains
339 console output of the machine, but not necessarily journal
340 contents of the machine itself.
</para></listitem>
344 <term><command>show
</command> [
<replaceable>NAME
</replaceable>...]
</term>
346 <listitem><para>Show properties of one or more registered
347 virtual machines or containers or the manager itself. If no
348 argument is specified, properties of the manager will be
349 shown. If a NAME is specified, properties of this virtual
350 machine or container are shown. By default, empty properties
351 are suppressed. Use
<option>--all
</option> to show those too.
352 To select specific properties to show, use
353 <option>--property=
</option>. This command is intended to be
354 used whenever computer-parsable output is required, and does
355 not print the cgroup tree or journal entries. Use
356 <command>status
</command> if you are looking for formatted
357 human-readable output.
</para></listitem>
361 <term><command>start
</command> <replaceable>NAME
</replaceable>...
</term>
363 <listitem><para>Start a container as a system service, using
364 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
365 This starts
<filename>systemd-nspawn@.service
</filename>,
366 instantiated for the specified machine name, similar to the
367 effect of
<command>systemctl start
</command> on the service
368 name.
<command>systemd-nspawn
</command> looks for a container
369 image by the specified name in
370 <filename>/var/lib/machines/
</filename> (and other search
371 paths, see below) and runs it. Use
372 <command>list-images
</command> (see below) for listing
373 available container images to start.
</para>
376 <citerefentry><refentrytitle>systemd-machined.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
377 also interfaces with a variety of other container and VM
378 managers,
<command>systemd-nspawn
</command> is just one
379 implementation of it. Most of the commands available in
380 <command>machinectl
</command> may be used on containers or VMs
381 controlled by other managers, not just
382 <command>systemd-nspawn
</command>. Starting VMs and container
383 images on those managers requires manager-specific
386 <para>To interactively start a container on the command line
387 with full access to the container's console, please invoke
388 <command>systemd-nspawn
</command> directly. To stop a running
389 container use
<command>machinectl poweroff
</command>.
</para></listitem>
393 <term><command>login
</command> [
<replaceable>NAME
</replaceable>]
</term>
395 <listitem><para>Open an interactive terminal login session in
396 a container or on the local host. If an argument is supplied,
397 it refers to the container machine to connect to. If none is
398 specified, or the container name is specified as the empty
399 string, or the special machine name
<literal>.host
</literal>
400 (see below) is specified, the connection is made to the local
401 host instead. This will create a TTY connection to a specific
402 container or the local host and asks for the execution of a
403 getty on it. Note that this is only supported for containers
405 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
406 as init system.
</para>
408 <para>This command will open a full login prompt on the
409 container or the local host, which then asks for username and
410 password. Use
<command>shell
</command> (see below) or
411 <citerefentry><refentrytitle>systemd-run
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
412 with the
<option>--machine=
</option> switch to directly invoke
413 a single command, either interactively or in the
414 background.
</para></listitem>
418 <term><command>shell
</command> [[
<replaceable>NAME
</replaceable>@]
<replaceable>NAME
</replaceable> [
<replaceable>PATH
</replaceable> [
<replaceable>ARGUMENTS
</replaceable>...]]]
</term>
420 <listitem><para>Open an interactive shell session in a
421 container or on the local host. The first argument refers to
422 the container machine to connect to. If none is specified, or
423 the machine name is specified as the empty string, or the
424 special machine name
<literal>.host
</literal> (see below) is
425 specified, the connection is made to the local host
426 instead. This works similar to
<command>login
</command> but
427 immediately invokes a user process. This command runs the
428 specified executable with the specified arguments, or
429 <filename>/bin/sh
</filename> if none is specified. By default,
430 opens a
<literal>root
</literal> shell, but by using
431 <option>--uid=
</option>, or by prefixing the machine name with
432 a username and an
<literal>@
</literal> character, a different
433 user may be selected. Use
<option>--setenv=
</option> to set
434 environment variables for the executed process.
</para>
436 <para>When using the
<command>shell
</command> command without
437 arguments, (thus invoking the executed shell or command on the
438 local host), it is in many ways similar to a
<citerefentry
439 project='die-net'
><refentrytitle>su
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
440 session, but, unlike
<command>su
</command>, completely isolates
441 the new session from the originating session, so that it
442 shares no process or session properties, and is in a clean and
443 well-defined state. It will be tracked in a new utmp, login,
444 audit, security and keyring session, and will not inherit any
445 environment variables or resource limits, among other
449 <citerefentry><refentrytitle>systemd-run
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
450 may be used in place of the
<command>shell
</command> command,
451 and allows more detailed, low-level configuration of the
452 invoked unit. However, it is frequently more privileged than
453 the
<command>shell
</command> command.
</para></listitem>
457 <term><command>enable
</command> <replaceable>NAME
</replaceable>...
</term>
458 <term><command>disable
</command> <replaceable>NAME
</replaceable>...
</term>
460 <listitem><para>Enable or disable a container as a system
461 service to start at system boot, using
462 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
463 This enables or disables
464 <filename>systemd-nspawn@.service
</filename>, instantiated for
465 the specified machine name, similar to the effect of
466 <command>systemctl enable
</command> or
<command>systemctl
467 disable
</command> on the service name.
</para></listitem>
471 <term><command>poweroff
</command> <replaceable>NAME
</replaceable>...
</term>
473 <listitem><para>Power off one or more containers. This will
474 trigger a reboot by sending SIGRTMIN+
4 to the container's init
475 process, which causes systemd-compatible init systems to shut
476 down cleanly. Use
<command>stop
</command> as alias for
<command>poweroff
</command>.
477 This operation does not work on containers that do not run a
478 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>-compatible
479 init system, such as sysvinit. Use
480 <command>terminate
</command> (see below) to immediately
481 terminate a container or VM, without cleanly shutting it
482 down.
</para></listitem>
486 <term><command>reboot
</command> <replaceable>NAME
</replaceable>...
</term>
488 <listitem><para>Reboot one or more containers. This will
489 trigger a reboot by sending SIGINT to the container's init
490 process, which is roughly equivalent to pressing Ctrl+Alt+Del
491 on a non-containerized system, and is compatible with
492 containers running any system manager.
</para></listitem>
496 <term><command>terminate
</command> <replaceable>NAME
</replaceable>...
</term>
498 <listitem><para>Immediately terminates a virtual machine or
499 container, without cleanly shutting it down. This kills all
500 processes of the virtual machine or container and deallocates
501 all resources attached to that instance. Use
502 <command>poweroff
</command> to issue a clean shutdown
503 request.
</para></listitem>
507 <term><command>kill
</command> <replaceable>NAME
</replaceable>...
</term>
509 <listitem><para>Send a signal to one or more processes of the
510 virtual machine or container. This means processes as seen by
511 the host, not the processes inside the virtual machine or
512 container. Use
<option>--kill-who=
</option> to select which
513 process to kill. Use
<option>--signal=
</option> to select the
514 signal to send.
</para></listitem>
518 <term><command>bind
</command> <replaceable>NAME
</replaceable> <replaceable>PATH
</replaceable> [
<replaceable>PATH
</replaceable>]
</term>
520 <listitem><para>Bind mounts a directory from the host into the
521 specified container. The first directory argument is the
522 source directory on the host, the second directory argument
523 is the destination directory in the container. When the
524 latter is omitted, the destination path in the container is
525 the same as the source path on the host. When combined with
526 the
<option>--read-only
</option> switch, a ready-only bind
527 mount is created. When combined with the
528 <option>--mkdir
</option> switch, the destination path is first
529 created before the mount is applied. Note that this option is
530 currently only supported for
531 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
532 containers.
</para></listitem>
536 <term><command>copy-to
</command> <replaceable>NAME
</replaceable> <replaceable>PATH
</replaceable> [
<replaceable>PATH
</replaceable>]
</term>
538 <listitem><para>Copies files or directories from the host
539 system into a running container. Takes a container name,
540 followed by the source path on the host and the destination
541 path in the container. If the destination path is omitted, the
542 same as the source path is used.
</para></listitem>
547 <term><command>copy-from
</command> <replaceable>NAME
</replaceable> <replaceable>PATH
</replaceable> [
<replaceable>PATH
</replaceable>]
</term>
549 <listitem><para>Copies files or directories from a container
550 into the host system. Takes a container name, followed by the
551 source path in the container the destination path on the host.
552 If the destination path is omitted, the same as the source path
553 is used.
</para></listitem>
555 </variablelist></refsect2>
557 <refsect2><title>Image Commands
</title><variablelist>
560 <term><command>list-images
</command></term>
562 <listitem><para>Show a list of locally installed container and
563 VM images. This enumerates all raw disk images and container
564 directories and subvolumes in
565 <filename>/var/lib/machines/
</filename> (and other search
566 paths, see below). Use
<command>start
</command> (see above) to
567 run a container off one of the listed images. Note that, by
568 default, containers whose name begins with a dot
569 (
<literal>.
</literal>) are not shown. To show these too,
570 specify
<option>--all
</option>. Note that a special image
571 <literal>.host
</literal> always implicitly exists and refers
572 to the image the host itself is booted from.
</para></listitem>
576 <term><command>image-status
</command> [
<replaceable>NAME
</replaceable>...]
</term>
578 <listitem><para>Show terse status information about one or
579 more container or VM images. This function is intended to
580 generate human-readable output. Use
581 <command>show-image
</command> (see below) to generate
582 computer-parsable output instead.
</para></listitem>
586 <term><command>show-image
</command> [
<replaceable>NAME
</replaceable>...]
</term>
588 <listitem><para>Show properties of one or more registered
589 virtual machine or container images, or the manager itself. If
590 no argument is specified, properties of the manager will be
591 shown. If a NAME is specified, properties of this virtual
592 machine or container image are shown. By default, empty
593 properties are suppressed. Use
<option>--all
</option> to show
594 those too. To select specific properties to show, use
595 <option>--property=
</option>. This command is intended to be
596 used whenever computer-parsable output is required. Use
597 <command>image-status
</command> if you are looking for
598 formatted human-readable output.
</para></listitem>
602 <term><command>clone
</command> <replaceable>NAME
</replaceable> <replaceable>NAME
</replaceable></term>
604 <listitem><para>Clones a container or VM image. The arguments specify the name of the image to clone and the
605 name of the newly cloned image. Note that plain directory container images are cloned into btrfs subvolume
606 images with this command, if the underlying file system supports this. Note that cloning a container or VM
607 image is optimized for btrfs file systems, and might not be efficient on others, due to file system
610 <para>Note that this command leaves host name, machine ID and
611 all other settings that could identify the instance
612 unmodified. The original image and the cloned copy will hence
613 share these credentials, and it might be necessary to manually
614 change them in the copy.
</para>
616 <para>If combined with the
<option>--read-only
</option> switch a read-only cloned image is
617 created.
</para></listitem>
621 <term><command>rename
</command> <replaceable>NAME
</replaceable> <replaceable>NAME
</replaceable></term>
623 <listitem><para>Renames a container or VM image. The
624 arguments specify the name of the image to rename and the new
625 name of the image.
</para></listitem>
629 <term><command>read-only
</command> <replaceable>NAME
</replaceable> [
<replaceable>BOOL
</replaceable>]
</term>
631 <listitem><para>Marks or (unmarks) a container or VM image
632 read-only. Takes a VM or container image name, followed by a
633 boolean as arguments. If the boolean is omitted, positive is
634 implied, i.e. the image is marked read-only.
</para></listitem>
638 <term><command>remove
</command> <replaceable>NAME
</replaceable>...
</term>
640 <listitem><para>Removes one or more container or VM images.
641 The special image
<literal>.host
</literal>, which refers to
642 the host's own directory tree, may not be
643 removed.
</para></listitem>
647 <term><command>set-limit
</command> [
<replaceable>NAME
</replaceable>]
<replaceable>BYTES
</replaceable></term>
649 <listitem><para>Sets the maximum size in bytes that a specific
650 container or VM image, or all images, may grow up to on disk
651 (disk quota). Takes either one or two parameters. The first,
652 optional parameter refers to a container or VM image name. If
653 specified, the size limit of the specified image is changed. If
654 omitted, the overall size limit of the sum of all images stored
655 locally is changed. The final argument specifies the size
656 limit in bytes, possibly suffixed by the usual K, M, G, T
657 units. If the size limit shall be disabled, specify
658 <literal>-
</literal> as size.
</para>
660 <para>Note that per-container size limits are only supported
661 on btrfs file systems. Also note that, if
662 <command>set-limit
</command> is invoked without an image
663 parameter, and
<filename>/var/lib/machines
</filename> is
664 empty, and the directory is not located on btrfs, a btrfs
665 loopback file is implicitly created as
666 <filename>/var/lib/machines.raw
</filename> with the given
668 <filename>/var/lib/machines
</filename>. The size of the
669 loopback may later be readjusted with
670 <command>set-limit
</command>, as well. If such a
671 loopback-mounted
<filename>/var/lib/machines
</filename>
672 directory is used,
<command>set-limit
</command> without an image
673 name alters both the quota setting within the file system as
674 well as the loopback file and file system size
675 itself.
</para></listitem>
679 <term><command>clean
</command></term>
681 <listitem><para>Remove hidden VM or container images (or all). This command removes all hidden machine images
682 from
<filename>/var/lib/machines
</filename>, i.e. those whose name begins with a dot. Use
<command>machinectl
683 list-images --all
</command> to see a list of all machine images, including the hidden ones.
</para>
685 <para>When combined with the
<option>--all
</option> switch removes all images, not just hidden ones. This
686 command effectively empties
<filename>/var/lib/machines
</filename>.
</para>
688 <para>Note that commands such as
<command>machinectl pull-tar
</command> or
<command>machinectl
689 pull-raw
</command> usually create hidden, read-only, unmodified machine images from the downloaded image first,
690 before cloning a writable working copy of it, in order to avoid duplicate downloads in case of images that are
691 reused multiple times. Use
<command>machinectl clean
</command> to remove old, hidden images created this
692 way.
</para></listitem>
695 </variablelist></refsect2>
697 <refsect2><title>Image Transfer Commands
</title><variablelist>
700 <term><command>pull-tar
</command> <replaceable>URL
</replaceable> [
<replaceable>NAME
</replaceable>]
</term>
702 <listitem><para>Downloads a
<filename>.tar
</filename>
703 container image from the specified URL, and makes it available
704 under the specified local machine name. The URL must be of
705 type
<literal>http://
</literal> or
706 <literal>https://
</literal>, and must refer to a
707 <filename>.tar
</filename>,
<filename>.tar.gz
</filename>,
708 <filename>.tar.xz
</filename> or
<filename>.tar.bz2
</filename>
709 archive file. If the local machine name is omitted, it
710 is automatically derived from the last component of the URL,
711 with its suffix removed.
</para>
713 <para>The image is verified before it is made available,
714 unless
<option>--verify=no
</option> is specified. Verification
715 is done via SHA256SUMS and SHA256SUMS.gpg files that need to
716 be made available on the same web server, under the same URL
717 as the
<filename>.tar
</filename> file, but with the last
718 component (the filename) of the URL replaced. With
719 <option>--verify=checksum
</option>, only the SHA256 checksum
720 for the file is verified, based on the
721 <filename>SHA256SUMS
</filename> file. With
722 <option>--verify=signature
</option>, the SHA256SUMS file is
723 first verified with detached GPG signature file
724 <filename>SHA256SUMS.gpg
</filename>. The public key for this
725 verification step needs to be available in
726 <filename>/usr/lib/systemd/import-pubring.gpg
</filename> or
727 <filename>/etc/systemd/import-pubring.gpg
</filename>.
</para>
729 <para>The container image will be downloaded and stored in a
730 read-only subvolume in
731 <filename>/var/lib/machines/
</filename> that is named after
732 the specified URL and its HTTP etag. A writable snapshot is
733 then taken from this subvolume, and named after the specified
734 local name. This behavior ensures that creating multiple
735 container instances of the same URL is efficient, as multiple
736 downloads are not necessary. In order to create only the
737 read-only image, and avoid creating its writable snapshot,
738 specify
<literal>-
</literal> as local machine name.
</para>
740 <para>Note that the read-only subvolume is prefixed with
741 <filename>.tar-
</filename>, and is thus not shown by
742 <command>list-images
</command>, unless
<option>--all
</option>
745 <para>Note that pressing C-c during execution of this command
746 will not abort the download. Use
747 <command>cancel-transfer
</command>, described
748 below.
</para></listitem>
752 <term><command>pull-raw
</command> <replaceable>URL
</replaceable> [
<replaceable>NAME
</replaceable>]
</term>
754 <listitem><para>Downloads a
<filename>.raw
</filename>
755 container or VM disk image from the specified URL, and makes
756 it available under the specified local machine name. The URL
757 must be of type
<literal>http://
</literal> or
758 <literal>https://
</literal>. The container image must either
759 be a
<filename>.qcow2
</filename> or raw disk image, optionally
760 compressed as
<filename>.gz
</filename>,
761 <filename>.xz
</filename>, or
<filename>.bz2
</filename>. If the
762 local machine name is omitted, it is automatically
763 derived from the last component of the URL, with its suffix
766 <para>Image verification is identical for raw and tar images
769 <para>If the downloaded image is in
770 <filename>.qcow2
</filename> format it is converted into a raw
771 image file before it is made available.
</para>
773 <para>Downloaded images of this type will be placed as
774 read-only
<filename>.raw
</filename> file in
775 <filename>/var/lib/machines/
</filename>. A local, writable
776 (reflinked) copy is then made under the specified local
777 machine name. To omit creation of the local, writable copy
778 pass
<literal>-
</literal> as local machine name.
</para>
780 <para>Similar to the behavior of
<command>pull-tar
</command>,
781 the read-only image is prefixed with
782 <filename>.raw-
</filename>, and thus not shown by
783 <command>list-images
</command>, unless
<option>--all
</option>
786 <para>Note that pressing C-c during execution of this command
787 will not abort the download. Use
788 <command>cancel-transfer
</command>, described
789 below.
</para></listitem>
793 <term><command>import-tar
</command> <replaceable>FILE
</replaceable> [
<replaceable>NAME
</replaceable>]
</term>
794 <term><command>import-raw
</command> <replaceable>FILE
</replaceable> [
<replaceable>NAME
</replaceable>]
</term>
795 <listitem><para>Imports a TAR or RAW container or VM image,
796 and places it under the specified name in
797 <filename>/var/lib/machines/
</filename>. When
798 <command>import-tar
</command> is used, the file specified as
799 the first argument should be a tar archive, possibly compressed
800 with xz, gzip or bzip2. It will then be unpacked into its own
801 subvolume in
<filename>/var/lib/machines
</filename>. When
802 <command>import-raw
</command> is used, the file should be a
803 qcow2 or raw disk image, possibly compressed with xz, gzip or
804 bzip2. If the second argument (the resulting image name) is
805 not specified, it is automatically derived from the file
806 name. If the file name is passed as
<literal>-
</literal>, the
807 image is read from standard input, in which case the second
808 argument is mandatory.
</para>
810 <para>Both
<command>pull-tar
</command> and
<command>pull-raw
</command>
811 will resize
<filename>/var/lib/machines.raw
</filename> and the
812 filesystem therein as necessary. Optionally, the
813 <option>--read-only
</option> switch may be used to create a
814 read-only container or VM image. No cryptographic validation
815 is done when importing the images.
</para>
817 <para>Much like image downloads, ongoing imports may be listed
818 with
<command>list-transfers
</command> and aborted with
819 <command>cancel-transfer
</command>.
</para></listitem>
823 <term><command>export-tar
</command> <replaceable>NAME
</replaceable> [
<replaceable>FILE
</replaceable>]
</term>
824 <term><command>export-raw
</command> <replaceable>NAME
</replaceable> [
<replaceable>FILE
</replaceable>]
</term>
825 <listitem><para>Exports a TAR or RAW container or VM image and
826 stores it in the specified file. The first parameter should be
827 a VM or container image name. The second parameter should be a
828 file path the TAR or RAW image is written to. If the path ends
829 in
<literal>.gz
</literal>, the file is compressed with gzip, if
830 it ends in
<literal>.xz
</literal>, with xz, and if it ends in
831 <literal>.bz2
</literal>, with bzip2. If the path ends in
832 neither, the file is left uncompressed. If the second argument
833 is missing, the image is written to standard output. The
834 compression may also be explicitly selected with the
835 <option>--format=
</option> switch. This is in particular
836 useful if the second parameter is left unspecified.
</para>
838 <para>Much like image downloads and imports, ongoing exports
839 may be listed with
<command>list-transfers
</command> and
841 <command>cancel-transfer
</command>.
</para>
843 <para>Note that, currently, only directory and subvolume images
844 may be exported as TAR images, and only raw disk images as RAW
845 images.
</para></listitem>
849 <term><command>list-transfers
</command></term>
851 <listitem><para>Shows a list of container or VM image
852 downloads, imports and exports that are currently in
853 progress.
</para></listitem>
857 <term><command>cancel-transfers
</command> <replaceable>ID
</replaceable>...
</term>
859 <listitem><para>Aborts a download, import or export of the
860 container or VM image with the specified ID. To list ongoing
861 transfers and their IDs, use
862 <command>list-transfers
</command>.
</para></listitem>
865 </variablelist></refsect2>
870 <title>Machine and Image Names
</title>
872 <para>The
<command>machinectl
</command> tool operates on machines
873 and images whose names must be chosen following strict
874 rules. Machine names must be suitable for use as host names
875 following a conservative subset of DNS and UNIX/Linux
876 semantics. Specifically, they must consist of one or more
877 non-empty label strings, separated by dots. No leading or trailing
878 dots are allowed. No sequences of multiple dots are allowed. The
879 label strings may only consist of alphanumeric characters as well
880 as the dash and underscore. The maximum length of a machine name
881 is
64 characters.
</para>
883 <para>A special machine with the name
<literal>.host
</literal>
884 refers to the running host system itself. This is useful for execution
885 operations or inspecting the host system as well. Note that
886 <command>machinectl list
</command> will not show this special
887 machine unless the
<option>--all
</option> switch is specified.
</para>
889 <para>Requirements on image names are less strict, however, they must be
890 valid UTF-
8, must be suitable as file names (hence not be the
891 single or double dot, and not include a slash), and may not
892 contain control characters. Since many operations search for an
893 image by the name of a requested machine, it is recommended to name
894 images in the same strict fashion as machines.
</para>
896 <para>A special image with the name
<literal>.host
</literal>
897 refers to the image of the running host system. It hence
898 conceptually maps to the special
<literal>.host
</literal> machine
899 name described above. Note that
<command>machinectl
900 list-images
</command> will not show this special image either, unless
901 <option>--all
</option> is specified.
</para>
905 <title>Files and Directories
</title>
907 <para>Machine images are preferably stored in
908 <filename>/var/lib/machines/
</filename>, but are also searched for
909 in
<filename>/usr/local/lib/machines/
</filename> and
910 <filename>/usr/lib/machines/
</filename>. For compatibility reasons,
911 the directory
<filename>/var/lib/container/
</filename> is
912 searched, too. Note that images stored below
913 <filename>/usr
</filename> are always considered read-only. It is
914 possible to symlink machines images from other directories into
915 <filename>/var/lib/machines/
</filename> to make them available for
916 control with
<command>machinectl
</command>.
</para>
918 <para>Note that many image operations are only supported,
919 efficient or atomic on btrfs file systems. Due to this, if the
920 <command>pull-tar
</command>,
<command>pull-raw
</command>,
921 <command>import-tar
</command>,
<command>import-raw
</command> and
922 <command>set-limit
</command> commands notice that
923 <filename>/var/lib/machines
</filename> is empty and not located on
924 btrfs, they will implicitly set up a loopback file
925 <filename>/var/lib/machines.raw
</filename> containing a btrfs file
926 system that is mounted to
927 <filename>/var/lib/machines
</filename>. The size of this loopback
928 file may be controlled dynamically with
929 <command>set-limit
</command>.
</para>
931 <para>Disk images are understood by
932 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
933 and
<command>machinectl
</command> in three formats:
</para>
936 <listitem><para>A simple directory tree, containing the files
937 and directories of the container to boot.
</para></listitem>
939 <listitem><para>Subvolumes (on btrfs file systems), which are
940 similar to the simple directories, described above. However,
941 they have additional benefits, such as efficient cloning and
942 quota reporting.
</para></listitem>
944 <listitem><para>"Raw" disk images, i.e. binary images of disks
945 with a GPT or MBR partition table. Images of this type are
946 regular files with the suffix
947 <literal>.raw
</literal>.
</para></listitem>
951 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
952 for more information on image formats, in particular its
953 <option>--directory=
</option> and
<option>--image=
</option>
958 <title>Examples
</title>
960 <title>Download an Ubuntu image and open a shell in it
</title>
962 <programlisting># machinectl pull-tar https://cloud-images.ubuntu.com/trusty/current/trusty-server-cloudimg-amd64-root.tar.gz
963 # systemd-nspawn -M trusty-server-cloudimg-amd64-root
</programlisting>
965 <para>This downloads and verifies the specified
966 <filename>.tar
</filename> image, and then uses
967 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
968 to open a shell in it.
</para>
972 <title>Download a Fedora image, set a root password in it, start
973 it as service
</title>
975 <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
976 # systemd-nspawn -M Fedora-Cloud-Base-
23-
20151030
979 # machinectl start Fedora-Cloud-Base-
23-
20151030
980 # machinectl login Fedora-Cloud-Base-
23-
20151030</programlisting>
982 <para>This downloads the specified
<filename>.raw
</filename>
983 image with verification disabled. Then, a shell is opened in it
984 and a root password is set. Afterwards the shell is left, and
985 the machine started as system service. With the last command a
986 login prompt into the container is requested.
</para>
990 <title>Exports a container image as tar file
</title>
992 <programlisting># machinectl export-tar fedora myfedora.tar.xz
</programlisting>
994 <para>Exports the container
<literal>fedora
</literal> as an
995 xz-compressed tar file
<filename>myfedora.tar.xz
</filename> into the
996 current directory.
</para>
1000 <title>Create a new shell session
</title>
1002 <programlisting># machinectl shell --uid=lennart
</programlisting>
1004 <para>This creates a new shell session on the local host for
1005 the user ID
<literal>lennart
</literal>, in a
<citerefentry
1006 project='die-net'
><refentrytitle>su
</refentrytitle><manvolnum>1</manvolnum></citerefentry>-like
1013 <title>Exit status
</title>
1015 <para>On success,
0 is returned, a non-zero failure code
1019 <xi:include href=
"less-variables.xml" />
1022 <title>See Also
</title>
1024 <citerefentry><refentrytitle>systemd-machined.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
1025 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1026 <citerefentry><refentrytitle>systemd.special
</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1027 <citerefentry project='die-net'
><refentrytitle>tar
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1028 <citerefentry project='die-net'
><refentrytitle>xz
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1029 <citerefentry project='die-net'
><refentrytitle>gzip
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1030 <citerefentry project='die-net'
><refentrytitle>bzip2
</refentrytitle><manvolnum>1</manvolnum></citerefentry>