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 a 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 virtual machines or containers or the manager
347 itself. If no argument is specified, properties of the manager will be shown. If a NAME is specified,
348 properties of this virtual machine or container are shown. By default, empty properties are suppressed. Use
349 <option>--all
</option> to show those too. To select specific properties to show, use
350 <option>--property=
</option>. This command is intended to be used whenever computer-parsable output is
351 required, and does not print the control group tree or journal entries. Use
<command>status
</command> if you
352 are looking for formatted human-readable output.
</para></listitem>
356 <term><command>start
</command> <replaceable>NAME
</replaceable>…
</term>
358 <listitem><para>Start a container as a system service, using
359 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
360 This starts
<filename>systemd-nspawn@.service
</filename>,
361 instantiated for the specified machine name, similar to the
362 effect of
<command>systemctl start
</command> on the service
363 name.
<command>systemd-nspawn
</command> looks for a container
364 image by the specified name in
365 <filename>/var/lib/machines/
</filename> (and other search
366 paths, see below) and runs it. Use
367 <command>list-images
</command> (see below) for listing
368 available container images to start.
</para>
371 <citerefentry><refentrytitle>systemd-machined.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
372 also interfaces with a variety of other container and VM
373 managers,
<command>systemd-nspawn
</command> is just one
374 implementation of it. Most of the commands available in
375 <command>machinectl
</command> may be used on containers or VMs
376 controlled by other managers, not just
377 <command>systemd-nspawn
</command>. Starting VMs and container
378 images on those managers requires manager-specific
381 <para>To interactively start a container on the command line
382 with full access to the container's console, please invoke
383 <command>systemd-nspawn
</command> directly. To stop a running
384 container use
<command>machinectl poweroff
</command>.
</para></listitem>
388 <term><command>login
</command> [
<replaceable>NAME
</replaceable>]
</term>
390 <listitem><para>Open an interactive terminal login session in
391 a container or on the local host. If an argument is supplied,
392 it refers to the container machine to connect to. If none is
393 specified, or the container name is specified as the empty
394 string, or the special machine name
<literal>.host
</literal>
395 (see below) is specified, the connection is made to the local
396 host instead. This will create a TTY connection to a specific
397 container or the local host and asks for the execution of a
398 getty on it. Note that this is only supported for containers
400 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
401 as init system.
</para>
403 <para>This command will open a full login prompt on the
404 container or the local host, which then asks for username and
405 password. Use
<command>shell
</command> (see below) or
406 <citerefentry><refentrytitle>systemd-run
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
407 with the
<option>--machine=
</option> switch to directly invoke
408 a single command, either interactively or in the
409 background.
</para></listitem>
413 <term><command>shell
</command> [[
<replaceable>NAME
</replaceable>@]
<replaceable>NAME
</replaceable> [
<replaceable>PATH
</replaceable> [
<replaceable>ARGUMENTS
</replaceable>…]]]
</term>
415 <listitem><para>Open an interactive shell session in a
416 container or on the local host. The first argument refers to
417 the container machine to connect to. If none is specified, or
418 the machine name is specified as the empty string, or the
419 special machine name
<literal>.host
</literal> (see below) is
420 specified, the connection is made to the local host
421 instead. This works similar to
<command>login
</command> but
422 immediately invokes a user process. This command runs the
423 specified executable with the specified arguments, or
424 <filename>/bin/sh
</filename> if none is specified. By default,
425 opens a
<literal>root
</literal> shell, but by using
426 <option>--uid=
</option>, or by prefixing the machine name with
427 a username and an
<literal>@
</literal> character, a different
428 user may be selected. Use
<option>--setenv=
</option> to set
429 environment variables for the executed process.
</para>
431 <para>When using the
<command>shell
</command> command without
432 arguments, (thus invoking the executed shell or command on the
433 local host), it is in many ways similar to a
<citerefentry
434 project='die-net'
><refentrytitle>su
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
435 session, but, unlike
<command>su
</command>, completely isolates
436 the new session from the originating session, so that it
437 shares no process or session properties, and is in a clean and
438 well-defined state. It will be tracked in a new utmp, login,
439 audit, security and keyring session, and will not inherit any
440 environment variables or resource limits, among other
444 <citerefentry><refentrytitle>systemd-run
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
445 may be used in place of the
<command>shell
</command> command,
446 and allows more detailed, low-level configuration of the
447 invoked unit. However, it is frequently more privileged than
448 the
<command>shell
</command> command.
</para></listitem>
452 <term><command>enable
</command> <replaceable>NAME
</replaceable>…
</term>
453 <term><command>disable
</command> <replaceable>NAME
</replaceable>…
</term>
455 <listitem><para>Enable or disable a container as a system
456 service to start at system boot, using
457 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
458 This enables or disables
459 <filename>systemd-nspawn@.service
</filename>, instantiated for
460 the specified machine name, similar to the effect of
461 <command>systemctl enable
</command> or
<command>systemctl
462 disable
</command> on the service name.
</para></listitem>
466 <term><command>poweroff
</command> <replaceable>NAME
</replaceable>…
</term>
468 <listitem><para>Power off one or more containers. This will
469 trigger a reboot by sending SIGRTMIN+
4 to the container's init
470 process, which causes systemd-compatible init systems to shut
471 down cleanly. Use
<command>stop
</command> as alias for
<command>poweroff
</command>.
472 This operation does not work on containers that do not run a
473 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>-compatible
474 init system, such as sysvinit. Use
475 <command>terminate
</command> (see below) to immediately
476 terminate a container or VM, without cleanly shutting it
477 down.
</para></listitem>
481 <term><command>reboot
</command> <replaceable>NAME
</replaceable>…
</term>
483 <listitem><para>Reboot one or more containers. This will
484 trigger a reboot by sending SIGINT to the container's init
485 process, which is roughly equivalent to pressing Ctrl+Alt+Del
486 on a non-containerized system, and is compatible with
487 containers running any system manager.
</para></listitem>
491 <term><command>terminate
</command> <replaceable>NAME
</replaceable>…
</term>
493 <listitem><para>Immediately terminates a virtual machine or
494 container, without cleanly shutting it down. This kills all
495 processes of the virtual machine or container and deallocates
496 all resources attached to that instance. Use
497 <command>poweroff
</command> to issue a clean shutdown
498 request.
</para></listitem>
502 <term><command>kill
</command> <replaceable>NAME
</replaceable>…
</term>
504 <listitem><para>Send a signal to one or more processes of the
505 virtual machine or container. This means processes as seen by
506 the host, not the processes inside the virtual machine or
507 container. Use
<option>--kill-who=
</option> to select which
508 process to kill. Use
<option>--signal=
</option> to select the
509 signal to send.
</para></listitem>
513 <term><command>bind
</command> <replaceable>NAME
</replaceable> <replaceable>PATH
</replaceable> [
<replaceable>PATH
</replaceable>]
</term>
515 <listitem><para>Bind mounts a directory from the host into the
516 specified container. The first directory argument is the
517 source directory on the host, the second directory argument
518 is the destination directory in the container. When the
519 latter is omitted, the destination path in the container is
520 the same as the source path on the host. When combined with
521 the
<option>--read-only
</option> switch, a ready-only bind
522 mount is created. When combined with the
523 <option>--mkdir
</option> switch, the destination path is first
524 created before the mount is applied. Note that this option is
525 currently only supported for
526 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
527 containers.
</para></listitem>
531 <term><command>copy-to
</command> <replaceable>NAME
</replaceable> <replaceable>PATH
</replaceable> [
<replaceable>PATH
</replaceable>]
</term>
533 <listitem><para>Copies files or directories from the host
534 system into a running container. Takes a container name,
535 followed by the source path on the host and the destination
536 path in the container. If the destination path is omitted, the
537 same as the source path is used.
</para></listitem>
542 <term><command>copy-from
</command> <replaceable>NAME
</replaceable> <replaceable>PATH
</replaceable> [
<replaceable>PATH
</replaceable>]
</term>
544 <listitem><para>Copies files or directories from a container
545 into the host system. Takes a container name, followed by the
546 source path in the container the destination path on the host.
547 If the destination path is omitted, the same as the source path
548 is used.
</para></listitem>
550 </variablelist></refsect2>
552 <refsect2><title>Image Commands
</title><variablelist>
555 <term><command>list-images
</command></term>
557 <listitem><para>Show a list of locally installed container and
558 VM images. This enumerates all raw disk images and container
559 directories and subvolumes in
560 <filename>/var/lib/machines/
</filename> (and other search
561 paths, see below). Use
<command>start
</command> (see above) to
562 run a container off one of the listed images. Note that, by
563 default, containers whose name begins with a dot
564 (
<literal>.
</literal>) are not shown. To show these too,
565 specify
<option>--all
</option>. Note that a special image
566 <literal>.host
</literal> always implicitly exists and refers
567 to the image the host itself is booted from.
</para></listitem>
571 <term><command>image-status
</command> [
<replaceable>NAME
</replaceable>…]
</term>
573 <listitem><para>Show terse status information about one or
574 more container or VM images. This function is intended to
575 generate human-readable output. Use
576 <command>show-image
</command> (see below) to generate
577 computer-parsable output instead.
</para></listitem>
581 <term><command>show-image
</command> [
<replaceable>NAME
</replaceable>…]
</term>
583 <listitem><para>Show properties of one or more registered
584 virtual machine or container images, or the manager itself. If
585 no argument is specified, properties of the manager will be
586 shown. If a NAME is specified, properties of this virtual
587 machine or container image are shown. By default, empty
588 properties are suppressed. Use
<option>--all
</option> to show
589 those too. To select specific properties to show, use
590 <option>--property=
</option>. This command is intended to be
591 used whenever computer-parsable output is required. Use
592 <command>image-status
</command> if you are looking for
593 formatted human-readable output.
</para></listitem>
597 <term><command>clone
</command> <replaceable>NAME
</replaceable> <replaceable>NAME
</replaceable></term>
599 <listitem><para>Clones a container or VM image. The arguments specify the name of the image to clone and the
600 name of the newly cloned image. Note that plain directory container images are cloned into btrfs subvolume
601 images with this command, if the underlying file system supports this. Note that cloning a container or VM
602 image is optimized for file systems that support copy-on-write, and might not be efficient on others, due to
603 file system limitations.
</para>
605 <para>Note that this command leaves host name, machine ID and
606 all other settings that could identify the instance
607 unmodified. The original image and the cloned copy will hence
608 share these credentials, and it might be necessary to manually
609 change them in the copy.
</para>
611 <para>If combined with the
<option>--read-only
</option> switch a read-only cloned image is
612 created.
</para></listitem>
616 <term><command>rename
</command> <replaceable>NAME
</replaceable> <replaceable>NAME
</replaceable></term>
618 <listitem><para>Renames a container or VM image. The
619 arguments specify the name of the image to rename and the new
620 name of the image.
</para></listitem>
624 <term><command>read-only
</command> <replaceable>NAME
</replaceable> [
<replaceable>BOOL
</replaceable>]
</term>
626 <listitem><para>Marks or (unmarks) a container or VM image
627 read-only. Takes a VM or container image name, followed by a
628 boolean as arguments. If the boolean is omitted, positive is
629 implied, i.e. the image is marked read-only.
</para></listitem>
633 <term><command>remove
</command> <replaceable>NAME
</replaceable>…
</term>
635 <listitem><para>Removes one or more container or VM images.
636 The special image
<literal>.host
</literal>, which refers to
637 the host's own directory tree, may not be
638 removed.
</para></listitem>
642 <term><command>set-limit
</command> [
<replaceable>NAME
</replaceable>]
<replaceable>BYTES
</replaceable></term>
644 <listitem><para>Sets the maximum size in bytes that a specific
645 container or VM image, or all images, may grow up to on disk
646 (disk quota). Takes either one or two parameters. The first,
647 optional parameter refers to a container or VM image name. If
648 specified, the size limit of the specified image is changed. If
649 omitted, the overall size limit of the sum of all images stored
650 locally is changed. The final argument specifies the size
651 limit in bytes, possibly suffixed by the usual K, M, G, T
652 units. If the size limit shall be disabled, specify
653 <literal>-
</literal> as size.
</para>
655 <para>Note that per-container size limits are only supported
656 on btrfs file systems. Also note that, if
657 <command>set-limit
</command> is invoked without an image
658 parameter, and
<filename>/var/lib/machines
</filename> is
659 empty, and the directory is not located on btrfs, a btrfs
660 loopback file is implicitly created as
661 <filename>/var/lib/machines.raw
</filename> with the given
663 <filename>/var/lib/machines
</filename>. The size of the
664 loopback may later be readjusted with
665 <command>set-limit
</command>, as well. If such a
666 loopback-mounted
<filename>/var/lib/machines
</filename>
667 directory is used,
<command>set-limit
</command> without an image
668 name alters both the quota setting within the file system as
669 well as the loopback file and file system size
670 itself.
</para></listitem>
674 <term><command>clean
</command></term>
676 <listitem><para>Remove hidden VM or container images (or all). This command removes all hidden machine images
677 from
<filename>/var/lib/machines
</filename>, i.e. those whose name begins with a dot. Use
<command>machinectl
678 list-images --all
</command> to see a list of all machine images, including the hidden ones.
</para>
680 <para>When combined with the
<option>--all
</option> switch removes all images, not just hidden ones. This
681 command effectively empties
<filename>/var/lib/machines
</filename>.
</para>
683 <para>Note that commands such as
<command>machinectl pull-tar
</command> or
<command>machinectl
684 pull-raw
</command> usually create hidden, read-only, unmodified machine images from the downloaded image first,
685 before cloning a writable working copy of it, in order to avoid duplicate downloads in case of images that are
686 reused multiple times. Use
<command>machinectl clean
</command> to remove old, hidden images created this
687 way.
</para></listitem>
690 </variablelist></refsect2>
692 <refsect2><title>Image Transfer Commands
</title><variablelist>
695 <term><command>pull-tar
</command> <replaceable>URL
</replaceable> [
<replaceable>NAME
</replaceable>]
</term>
697 <listitem><para>Downloads a
<filename>.tar
</filename>
698 container image from the specified URL, and makes it available
699 under the specified local machine name. The URL must be of
700 type
<literal>http://
</literal> or
701 <literal>https://
</literal>, and must refer to a
702 <filename>.tar
</filename>,
<filename>.tar.gz
</filename>,
703 <filename>.tar.xz
</filename> or
<filename>.tar.bz2
</filename>
704 archive file. If the local machine name is omitted, it
705 is automatically derived from the last component of the URL,
706 with its suffix removed.
</para>
708 <para>The image is verified before it is made available,
709 unless
<option>--verify=no
</option> is specified. Verification
710 is done via SHA256SUMS and SHA256SUMS.gpg files that need to
711 be made available on the same web server, under the same URL
712 as the
<filename>.tar
</filename> file, but with the last
713 component (the filename) of the URL replaced. With
714 <option>--verify=checksum
</option>, only the SHA256 checksum
715 for the file is verified, based on the
716 <filename>SHA256SUMS
</filename> file. With
717 <option>--verify=signature
</option>, the SHA256SUMS file is
718 first verified with detached GPG signature file
719 <filename>SHA256SUMS.gpg
</filename>. The public key for this
720 verification step needs to be available in
721 <filename>/usr/lib/systemd/import-pubring.gpg
</filename> or
722 <filename>/etc/systemd/import-pubring.gpg
</filename>.
</para>
724 <para>The container image will be downloaded and stored in a
725 read-only subvolume in
726 <filename>/var/lib/machines/
</filename> that is named after
727 the specified URL and its HTTP etag. A writable snapshot is
728 then taken from this subvolume, and named after the specified
729 local name. This behavior ensures that creating multiple
730 container instances of the same URL is efficient, as multiple
731 downloads are not necessary. In order to create only the
732 read-only image, and avoid creating its writable snapshot,
733 specify
<literal>-
</literal> as local machine name.
</para>
735 <para>Note that the read-only subvolume is prefixed with
736 <filename>.tar-
</filename>, and is thus not shown by
737 <command>list-images
</command>, unless
<option>--all
</option>
740 <para>Note that pressing C-c during execution of this command
741 will not abort the download. Use
742 <command>cancel-transfer
</command>, described
743 below.
</para></listitem>
747 <term><command>pull-raw
</command> <replaceable>URL
</replaceable> [
<replaceable>NAME
</replaceable>]
</term>
749 <listitem><para>Downloads a
<filename>.raw
</filename>
750 container or VM disk image from the specified URL, and makes
751 it available under the specified local machine name. The URL
752 must be of type
<literal>http://
</literal> or
753 <literal>https://
</literal>. The container image must either
754 be a
<filename>.qcow2
</filename> or raw disk image, optionally
755 compressed as
<filename>.gz
</filename>,
756 <filename>.xz
</filename>, or
<filename>.bz2
</filename>. If the
757 local machine name is omitted, it is automatically
758 derived from the last component of the URL, with its suffix
761 <para>Image verification is identical for raw and tar images
764 <para>If the downloaded image is in
765 <filename>.qcow2
</filename> format it is converted into a raw
766 image file before it is made available.
</para>
768 <para>Downloaded images of this type will be placed as
769 read-only
<filename>.raw
</filename> file in
770 <filename>/var/lib/machines/
</filename>. A local, writable
771 (reflinked) copy is then made under the specified local
772 machine name. To omit creation of the local, writable copy
773 pass
<literal>-
</literal> as local machine name.
</para>
775 <para>Similar to the behavior of
<command>pull-tar
</command>,
776 the read-only image is prefixed with
777 <filename>.raw-
</filename>, and thus not shown by
778 <command>list-images
</command>, unless
<option>--all
</option>
781 <para>Note that pressing C-c during execution of this command
782 will not abort the download. Use
783 <command>cancel-transfer
</command>, described
784 below.
</para></listitem>
788 <term><command>import-tar
</command> <replaceable>FILE
</replaceable> [
<replaceable>NAME
</replaceable>]
</term>
789 <term><command>import-raw
</command> <replaceable>FILE
</replaceable> [
<replaceable>NAME
</replaceable>]
</term>
790 <listitem><para>Imports a TAR or RAW container or VM image,
791 and places it under the specified name in
792 <filename>/var/lib/machines/
</filename>. When
793 <command>import-tar
</command> is used, the file specified as
794 the first argument should be a tar archive, possibly compressed
795 with xz, gzip or bzip2. It will then be unpacked into its own
796 subvolume in
<filename>/var/lib/machines
</filename>. When
797 <command>import-raw
</command> is used, the file should be a
798 qcow2 or raw disk image, possibly compressed with xz, gzip or
799 bzip2. If the second argument (the resulting image name) is
800 not specified, it is automatically derived from the file
801 name. If the file name is passed as
<literal>-
</literal>, the
802 image is read from standard input, in which case the second
803 argument is mandatory.
</para>
805 <para>Both
<command>pull-tar
</command> and
<command>pull-raw
</command>
806 will resize
<filename>/var/lib/machines.raw
</filename> and the
807 filesystem therein as necessary. Optionally, the
808 <option>--read-only
</option> switch may be used to create a
809 read-only container or VM image. No cryptographic validation
810 is done when importing the images.
</para>
812 <para>Much like image downloads, ongoing imports may be listed
813 with
<command>list-transfers
</command> and aborted with
814 <command>cancel-transfer
</command>.
</para></listitem>
818 <term><command>export-tar
</command> <replaceable>NAME
</replaceable> [
<replaceable>FILE
</replaceable>]
</term>
819 <term><command>export-raw
</command> <replaceable>NAME
</replaceable> [
<replaceable>FILE
</replaceable>]
</term>
820 <listitem><para>Exports a TAR or RAW container or VM image and
821 stores it in the specified file. The first parameter should be
822 a VM or container image name. The second parameter should be a
823 file path the TAR or RAW image is written to. If the path ends
824 in
<literal>.gz
</literal>, the file is compressed with gzip, if
825 it ends in
<literal>.xz
</literal>, with xz, and if it ends in
826 <literal>.bz2
</literal>, with bzip2. If the path ends in
827 neither, the file is left uncompressed. If the second argument
828 is missing, the image is written to standard output. The
829 compression may also be explicitly selected with the
830 <option>--format=
</option> switch. This is in particular
831 useful if the second parameter is left unspecified.
</para>
833 <para>Much like image downloads and imports, ongoing exports
834 may be listed with
<command>list-transfers
</command> and
836 <command>cancel-transfer
</command>.
</para>
838 <para>Note that, currently, only directory and subvolume images
839 may be exported as TAR images, and only raw disk images as RAW
840 images.
</para></listitem>
844 <term><command>list-transfers
</command></term>
846 <listitem><para>Shows a list of container or VM image
847 downloads, imports and exports that are currently in
848 progress.
</para></listitem>
852 <term><command>cancel-transfers
</command> <replaceable>ID
</replaceable>…
</term>
854 <listitem><para>Aborts a download, import or export of the
855 container or VM image with the specified ID. To list ongoing
856 transfers and their IDs, use
857 <command>list-transfers
</command>.
</para></listitem>
860 </variablelist></refsect2>
865 <title>Machine and Image Names
</title>
867 <para>The
<command>machinectl
</command> tool operates on machines
868 and images whose names must be chosen following strict
869 rules. Machine names must be suitable for use as host names
870 following a conservative subset of DNS and UNIX/Linux
871 semantics. Specifically, they must consist of one or more
872 non-empty label strings, separated by dots. No leading or trailing
873 dots are allowed. No sequences of multiple dots are allowed. The
874 label strings may only consist of alphanumeric characters as well
875 as the dash and underscore. The maximum length of a machine name
876 is
64 characters.
</para>
878 <para>A special machine with the name
<literal>.host
</literal>
879 refers to the running host system itself. This is useful for execution
880 operations or inspecting the host system as well. Note that
881 <command>machinectl list
</command> will not show this special
882 machine unless the
<option>--all
</option> switch is specified.
</para>
884 <para>Requirements on image names are less strict, however, they must be
885 valid UTF-
8, must be suitable as file names (hence not be the
886 single or double dot, and not include a slash), and may not
887 contain control characters. Since many operations search for an
888 image by the name of a requested machine, it is recommended to name
889 images in the same strict fashion as machines.
</para>
891 <para>A special image with the name
<literal>.host
</literal>
892 refers to the image of the running host system. It hence
893 conceptually maps to the special
<literal>.host
</literal> machine
894 name described above. Note that
<command>machinectl
895 list-images
</command> will not show this special image either, unless
896 <option>--all
</option> is specified.
</para>
900 <title>Files and Directories
</title>
902 <para>Machine images are preferably stored in
903 <filename>/var/lib/machines/
</filename>, but are also searched for
904 in
<filename>/usr/local/lib/machines/
</filename> and
905 <filename>/usr/lib/machines/
</filename>. For compatibility reasons,
906 the directory
<filename>/var/lib/container/
</filename> is
907 searched, too. Note that images stored below
908 <filename>/usr
</filename> are always considered read-only. It is
909 possible to symlink machines images from other directories into
910 <filename>/var/lib/machines/
</filename> to make them available for
911 control with
<command>machinectl
</command>.
</para>
913 <para>Note that some image operations are only supported,
914 efficient or atomic on btrfs file systems. Due to this, if the
915 <command>pull-tar
</command>,
<command>pull-raw
</command>,
916 <command>import-tar
</command>,
<command>import-raw
</command> and
917 <command>set-limit
</command> commands notice that
918 <filename>/var/lib/machines
</filename> is empty and not located on
919 btrfs, they will implicitly set up a loopback file
920 <filename>/var/lib/machines.raw
</filename> containing a btrfs file
921 system that is mounted to
922 <filename>/var/lib/machines
</filename>. The size of this loopback
923 file may be controlled dynamically with
924 <command>set-limit
</command>.
</para>
926 <para>Disk images are understood by
927 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
928 and
<command>machinectl
</command> in three formats:
</para>
931 <listitem><para>A simple directory tree, containing the files
932 and directories of the container to boot.
</para></listitem>
934 <listitem><para>Subvolumes (on btrfs file systems), which are
935 similar to the simple directories, described above. However,
936 they have additional benefits, such as efficient cloning and
937 quota reporting.
</para></listitem>
939 <listitem><para>"Raw" disk images, i.e. binary images of disks
940 with a GPT or MBR partition table. Images of this type are
941 regular files with the suffix
942 <literal>.raw
</literal>.
</para></listitem>
946 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
947 for more information on image formats, in particular its
948 <option>--directory=
</option> and
<option>--image=
</option>
953 <title>Examples
</title>
955 <title>Download an Ubuntu image and open a shell in it
</title>
957 <programlisting># machinectl pull-tar https://cloud-images.ubuntu.com/trusty/current/trusty-server-cloudimg-amd64-root.tar.gz
958 # systemd-nspawn -M trusty-server-cloudimg-amd64-root
</programlisting>
960 <para>This downloads and verifies the specified
961 <filename>.tar
</filename> image, and then uses
962 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
963 to open a shell in it.
</para>
967 <title>Download a Fedora image, set a root password in it, start
968 it as service
</title>
970 <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
971 # systemd-nspawn -M Fedora-Cloud-Base-
23-
20151030
974 # machinectl start Fedora-Cloud-Base-
23-
20151030
975 # machinectl login Fedora-Cloud-Base-
23-
20151030</programlisting>
977 <para>This downloads the specified
<filename>.raw
</filename>
978 image with verification disabled. Then, a shell is opened in it
979 and a root password is set. Afterwards the shell is left, and
980 the machine started as system service. With the last command a
981 login prompt into the container is requested.
</para>
985 <title>Exports a container image as tar file
</title>
987 <programlisting># machinectl export-tar fedora myfedora.tar.xz
</programlisting>
989 <para>Exports the container
<literal>fedora
</literal> as an
990 xz-compressed tar file
<filename>myfedora.tar.xz
</filename> into the
991 current directory.
</para>
995 <title>Create a new shell session
</title>
997 <programlisting># machinectl shell --uid=lennart
</programlisting>
999 <para>This creates a new shell session on the local host for
1000 the user ID
<literal>lennart
</literal>, in a
<citerefentry
1001 project='die-net'
><refentrytitle>su
</refentrytitle><manvolnum>1</manvolnum></citerefentry>-like
1008 <title>Exit status
</title>
1010 <para>On success,
0 is returned, a non-zero failure code
1014 <xi:include href=
"less-variables.xml" />
1017 <title>See Also
</title>
1019 <citerefentry><refentrytitle>systemd-machined.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
1020 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1021 <citerefentry><refentrytitle>systemd.special
</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1022 <citerefentry project='die-net'
><refentrytitle>tar
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1023 <citerefentry project='die-net'
><refentrytitle>xz
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1024 <citerefentry project='die-net'
><refentrytitle>gzip
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1025 <citerefentry project='die-net'
><refentrytitle>bzip2
</refentrytitle><manvolnum>1</manvolnum></citerefentry>