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 SPDX-License-Identifier: LGPL-2.1+
8 This file is part of systemd.
10 Copyright 2013 Zbigniew Jędrzejewski-Szmek
13 <refentry id=
"machinectl" conditional='ENABLE_MACHINED'
14 xmlns:
xi=
"http://www.w3.org/2001/XInclude">
17 <title>machinectl
</title>
18 <productname>systemd
</productname>
22 <contrib>Developer
</contrib>
23 <firstname>Lennart
</firstname>
24 <surname>Poettering
</surname>
25 <email>lennart@poettering.net
</email>
31 <refentrytitle>machinectl
</refentrytitle>
32 <manvolnum>1</manvolnum>
36 <refname>machinectl
</refname>
37 <refpurpose>Control the systemd machine manager
</refpurpose>
42 <command>machinectl
</command>
43 <arg choice=
"opt" rep=
"repeat">OPTIONS
</arg>
44 <arg choice=
"req">COMMAND
</arg>
45 <arg choice=
"opt" rep=
"repeat">NAME
</arg>
50 <title>Description
</title>
52 <para><command>machinectl
</command> may be used to introspect and
53 control the state of the
54 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
55 virtual machine and container registration manager
56 <citerefentry><refentrytitle>systemd-machined.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
</para>
58 <para><command>machinectl
</command> may be used to execute
59 operations on machines and images. Machines in this sense are
60 considered running instances of:
</para>
63 <listitem><para>Virtual Machines (VMs) that virtualize hardware
64 to run full operating system (OS) instances (including their kernels)
65 in a virtualized environment on top of the host OS.
</para></listitem>
67 <listitem><para>Containers that share the hardware and
68 OS kernel with the host OS, in order to run
69 OS userspace instances on top the host OS.
</para></listitem>
71 <listitem><para>The host system itself.
</para></listitem>
74 <para>Machines are identified by names that follow the same rules
75 as UNIX and DNS host names. For details, see below.
</para>
77 <para>Machines are instantiated from disk or file system images that
78 frequently — but not necessarily — carry the same name as machines running
79 from them. Images in this sense may be:
</para>
82 <listitem><para>Directory trees containing an OS, including the
83 top-level directories
<filename>/usr
</filename>,
84 <filename>/etc
</filename>, and so on.
</para></listitem>
86 <listitem><para>btrfs subvolumes containing OS trees, similar to
87 normal directory trees.
</para></listitem>
89 <listitem><para>Binary
"raw" disk images containing MBR or GPT
90 partition tables and Linux file system partitions.
</para></listitem>
92 <listitem><para>The file system tree of the host OS itself.
</para></listitem>
98 <title>Options
</title>
100 <para>The following options are understood:
</para>
104 <term><option>-p
</option></term>
105 <term><option>--property=
</option></term>
107 <listitem><para>When showing machine or image properties,
108 limit the output to certain properties as specified by the
109 argument. If not specified, all set properties are shown. The
110 argument should be a property name, such as
111 <literal>Name
</literal>. If specified more than once, all
112 properties with the specified names are
113 shown.
</para></listitem>
117 <term><option>-a
</option></term>
118 <term><option>--all
</option></term>
120 <listitem><para>When showing machine or image properties, show
121 all properties regardless of whether they are set or
124 <para>When listing VM or container images, do not suppress
125 images beginning in a dot character
126 (
<literal>.
</literal>).
</para>
128 <para>When cleaning VM or container images, remove all images, not just hidden ones.
</para></listitem>
132 <term><option>--value
</option></term>
134 <listitem><para>When printing properties with
<command>show
</command>, only print the value,
135 and skip the property name and
<literal>=
</literal>.
</para></listitem>
139 <term><option>-l
</option></term>
140 <term><option>--full
</option></term>
142 <listitem><para>Do not ellipsize process tree entries.
</para>
147 <term><option>--kill-who=
</option></term>
149 <listitem><para>When used with
<command>kill
</command>, choose
150 which processes to kill. Must be one of
151 <option>leader
</option>, or
<option>all
</option> to select
152 whether to kill only the leader process of the machine or all
153 processes of the machine. If omitted, defaults to
154 <option>all
</option>.
</para></listitem>
158 <term><option>-s
</option></term>
159 <term><option>--signal=
</option></term>
161 <listitem><para>When used with
<command>kill
</command>, choose
162 which signal to send to selected processes. Must be one of the
163 well-known signal specifiers, such as
164 <constant>SIGTERM
</constant>,
<constant>SIGINT
</constant> or
165 <constant>SIGSTOP
</constant>. If omitted, defaults to
166 <constant>SIGTERM
</constant>.
</para></listitem>
170 <term><option>--uid=
</option></term>
172 <listitem><para>When used with the
<command>shell
</command> command, chooses the user ID to
173 open the interactive shell session as. If the argument to the
<command>shell
</command>
174 command also specifies a user name, this option is ignored. If the name is not specified
175 in either way,
<literal>root
</literal> will be used by default. Note that this switch is
176 not supported for the
<command>login
</command> command (see below).
</para></listitem>
180 <term><option>-E
<replaceable>NAME
</replaceable>=
<replaceable>VALUE
</replaceable></option></term>
181 <term><option>--setenv=
<replaceable>NAME
</replaceable>=
<replaceable>VALUE
</replaceable></option></term>
183 <listitem><para>When used with the
<command>shell
</command> command, sets an environment
184 variable to pass to the executed shell. Takes an environment variable name and value,
185 separated by
<literal>=
</literal>. This switch may be used multiple times to set multiple
186 environment variables. Note that this switch is not supported for the
187 <command>login
</command> command (see below).
</para></listitem>
191 <term><option>--mkdir
</option></term>
193 <listitem><para>When used with
<command>bind
</command>, creates the destination file or directory before
194 applying the bind mount. Note that even though the name of this option suggests that it is suitable only for
195 directories, this option also creates the destination file node to mount over if the the object to mount is not
196 a directory, but a regular file, device node, socket or FIFO.
</para></listitem>
200 <term><option>--read-only
</option></term>
202 <listitem><para>When used with
<command>bind
</command>, creates a read-only bind mount.
</para>
204 <para>When used with
<command>clone
</command>,
<command>import-raw
</command> or
<command>import-tar
</command> a
205 read-only container or VM image is created.
</para></listitem>
209 <term><option>-n
</option></term>
210 <term><option>--lines=
</option></term>
212 <listitem><para>When used with
<command>status
</command>,
213 controls the number of journal lines to show, counting from
214 the most recent ones. Takes a positive integer argument.
215 Defaults to
10.
</para>
220 <term><option>-o
</option></term>
221 <term><option>--output=
</option></term>
223 <listitem><para>When used with
<command>status
</command>,
224 controls the formatting of the journal entries that are shown.
225 For the available choices, see
226 <citerefentry><refentrytitle>journalctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
227 Defaults to
<literal>short
</literal>.
</para></listitem>
231 <term><option>--verify=
</option></term>
233 <listitem><para>When downloading a container or VM image,
234 specify whether the image shall be verified before it is made
235 available. Takes one of
<literal>no
</literal>,
236 <literal>checksum
</literal> and
<literal>signature
</literal>.
237 If
<literal>no
</literal>, no verification is done. If
238 <literal>checksum
</literal> is specified, the download is
239 checked for integrity after the transfer is complete, but no
240 signatures are verified. If
<literal>signature
</literal> is
241 specified, the checksum is verified and the image's signature
242 is checked against a local keyring of trustable vendors. It is
243 strongly recommended to set this option to
244 <literal>signature
</literal> if the server and protocol
245 support this. Defaults to
246 <literal>signature
</literal>.
</para></listitem>
250 <term><option>--force
</option></term>
252 <listitem><para>When downloading a container or VM image, and
253 a local copy by the specified local machine name already
254 exists, delete it first and replace it by the newly downloaded
255 image.
</para></listitem>
259 <term><option>--format=
</option></term>
261 <listitem><para>When used with the
<option>export-tar
</option>
262 or
<option>export-raw
</option> commands, specifies the
263 compression format to use for the resulting file. Takes one of
264 <literal>uncompressed
</literal>,
<literal>xz
</literal>,
265 <literal>gzip
</literal>,
<literal>bzip2
</literal>. By default,
266 the format is determined automatically from the image file
267 name passed.
</para></listitem>
271 <term><option>--max-addresses=
</option></term>
273 <listitem><para>When used with the
<option>list-machines
</option>
274 command, limits the number of ip addresses output for every machine.
275 Defaults to
1. All addresses can be requested with
<literal>all
</literal>
276 as argument to
<option>--max-addresses
</option> . If the argument to
277 <option>--max-addresses
</option> is less than the actual number
278 of addresses,
<literal>...
</literal>follows the last address.
279 If multiple addresses are to be written for a given machine, every
280 address except the first one is on a new line and is followed by
281 <literal>,
</literal> if another address will be output afterwards.
</para></listitem>
285 <term><option>-q
</option></term>
286 <term><option>--quiet
</option></term>
288 <listitem><para>Suppresses additional informational output while running.
</para></listitem>
291 <xi:include href=
"user-system-options.xml" xpointer=
"host" />
294 <term><option>-M
</option></term>
295 <term><option>--machine=
</option></term>
297 <listitem><para>Connect to
298 <citerefentry><refentrytitle>systemd-machined.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
299 running in a local container, to perform the specified operation within
300 the container.
</para></listitem>
303 <xi:include href=
"standard-options.xml" xpointer=
"no-pager" />
304 <xi:include href=
"standard-options.xml" xpointer=
"no-legend" />
305 <xi:include href=
"standard-options.xml" xpointer=
"no-ask-password" />
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 the
424 default shell for the user if none is specified, or
425 <filename>/bin/sh
</filename> if no default shell is found. By default,
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>Note that
<command>machinectl shell
</command> does not propagate the exit code/status of the invoked
432 shell process. Use
<command>systemd-run
</command> instead if that information is required (see below).
</para>
434 <para>When using the
<command>shell
</command> command without
435 arguments, (thus invoking the executed shell or command on the
436 local host), it is in many ways similar to a
<citerefentry
437 project='die-net'
><refentrytitle>su
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
438 session, but, unlike
<command>su
</command>, completely isolates
439 the new session from the originating session, so that it
440 shares no process or session properties, and is in a clean and
441 well-defined state. It will be tracked in a new utmp, login,
442 audit, security and keyring session, and will not inherit any
443 environment variables or resource limits, among other
446 <para>Note that
<citerefentry><refentrytitle>systemd-run
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
447 with its
<option>--machine=
</option> switch may be used in place of the
<command>machinectl shell
</command>
448 command, and allows non-interactive operation, more detailed and low-level configuration of the invoked unit,
449 as well as access to runtime and exit code/status information of the invoked shell process. In particular, use
450 <command>systemd-run
</command>'s
<option>--wait
</option> switch to propagate exit status information of the
451 invoked process. Use
<command>systemd-run
</command>'s
<option>--pty
</option> switch for acquiring an
452 interactive shell, similar to
<command>machinectl shell
</command>. In general,
<command>systemd-run
</command>
453 is preferable for scripting purposes. However, note that
<command>systemd-run
</command> might require higher
454 privileges than
<command>machinectl shell
</command>.
</para></listitem>
458 <term><command>enable
</command> <replaceable>NAME
</replaceable>…
</term>
459 <term><command>disable
</command> <replaceable>NAME
</replaceable>…
</term>
461 <listitem><para>Enable or disable a container as a system
462 service to start at system boot, using
463 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
464 This enables or disables
465 <filename>systemd-nspawn@.service
</filename>, instantiated for
466 the specified machine name, similar to the effect of
467 <command>systemctl enable
</command> or
<command>systemctl
468 disable
</command> on the service name.
</para></listitem>
472 <term><command>poweroff
</command> <replaceable>NAME
</replaceable>…
</term>
474 <listitem><para>Power off one or more containers. This will
475 trigger a reboot by sending SIGRTMIN+
4 to the container's init
476 process, which causes systemd-compatible init systems to shut
477 down cleanly. Use
<command>stop
</command> as alias for
<command>poweroff
</command>.
478 This operation does not work on containers that do not run a
479 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>-compatible
480 init system, such as sysvinit. Use
481 <command>terminate
</command> (see below) to immediately
482 terminate a container or VM, without cleanly shutting it
483 down.
</para></listitem>
487 <term><command>reboot
</command> <replaceable>NAME
</replaceable>…
</term>
489 <listitem><para>Reboot one or more containers. This will
490 trigger a reboot by sending SIGINT to the container's init
491 process, which is roughly equivalent to pressing Ctrl+Alt+Del
492 on a non-containerized system, and is compatible with
493 containers running any system manager.
</para></listitem>
497 <term><command>terminate
</command> <replaceable>NAME
</replaceable>…
</term>
499 <listitem><para>Immediately terminates a virtual machine or
500 container, without cleanly shutting it down. This kills all
501 processes of the virtual machine or container and deallocates
502 all resources attached to that instance. Use
503 <command>poweroff
</command> to issue a clean shutdown
504 request.
</para></listitem>
508 <term><command>kill
</command> <replaceable>NAME
</replaceable>…
</term>
510 <listitem><para>Send a signal to one or more processes of the
511 virtual machine or container. This means processes as seen by
512 the host, not the processes inside the virtual machine or
513 container. Use
<option>--kill-who=
</option> to select which
514 process to kill. Use
<option>--signal=
</option> to select the
515 signal to send.
</para></listitem>
519 <term><command>bind
</command> <replaceable>NAME
</replaceable> <replaceable>PATH
</replaceable> [
<replaceable>PATH
</replaceable>]
</term>
521 <listitem><para>Bind mounts a file or directory from the host into the specified container. The first path
522 argument is the source file or directory on the host, the second path argument is the destination file or
523 directory in the container. When the latter is omitted, the destination path in the container is the same as
524 the source path on the host. When combined with the
<option>--read-only
</option> switch, a ready-only bind
525 mount is created. When combined with the
<option>--mkdir
</option> switch, the destination path is first created
526 before the mount is applied. Note that this option is currently only supported for
527 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry> containers,
528 and only if user namespacing (
<option>--private-users
</option>) is not used. This command supports bind
529 mounting directories, regular files, device nodes,
<constant>AF_UNIX
</constant> socket nodes, as well as
530 FIFOs.
</para></listitem>
534 <term><command>copy-to
</command> <replaceable>NAME
</replaceable> <replaceable>PATH
</replaceable> [
<replaceable>PATH
</replaceable>]
</term>
536 <listitem><para>Copies files or directories from the host
537 system into a running container. Takes a container name,
538 followed by the source path on the host and the destination
539 path in the container. If the destination path is omitted, the
540 same as the source path is used.
</para>
542 <para>If host and container share the same user and group namespace, file ownership by numeric user ID and
543 group ID is preserved for the copy, otherwise all files and directories in the copy will be owned by the root
544 user and group (UID/GID
0).
</para></listitem>
548 <term><command>copy-from
</command> <replaceable>NAME
</replaceable> <replaceable>PATH
</replaceable> [
<replaceable>PATH
</replaceable>]
</term>
550 <listitem><para>Copies files or directories from a container
551 into the host system. Takes a container name, followed by the
552 source path in the container the destination path on the host.
553 If the destination path is omitted, the same as the source path
556 <para>If host and container share the same user and group namespace, file ownership by numeric user ID and
557 group ID is preserved for the copy, otherwise all files and directories in the copy will be owned by the root
558 user and group (UID/GID
0).
</para></listitem>
560 </variablelist></refsect2>
562 <refsect2><title>Image Commands
</title><variablelist>
565 <term><command>list-images
</command></term>
567 <listitem><para>Show a list of locally installed container and
568 VM images. This enumerates all raw disk images and container
569 directories and subvolumes in
570 <filename>/var/lib/machines/
</filename> (and other search
571 paths, see below). Use
<command>start
</command> (see above) to
572 run a container off one of the listed images. Note that, by
573 default, containers whose name begins with a dot
574 (
<literal>.
</literal>) are not shown. To show these too,
575 specify
<option>--all
</option>. Note that a special image
576 <literal>.host
</literal> always implicitly exists and refers
577 to the image the host itself is booted from.
</para></listitem>
581 <term><command>image-status
</command> [
<replaceable>NAME
</replaceable>…]
</term>
583 <listitem><para>Show terse status information about one or
584 more container or VM images. This function is intended to
585 generate human-readable output. Use
586 <command>show-image
</command> (see below) to generate
587 computer-parsable output instead.
</para></listitem>
591 <term><command>show-image
</command> [
<replaceable>NAME
</replaceable>…]
</term>
593 <listitem><para>Show properties of one or more registered
594 virtual machine or container images, or the manager itself. If
595 no argument is specified, properties of the manager will be
596 shown. If a NAME is specified, properties of this virtual
597 machine or container image are shown. By default, empty
598 properties are suppressed. Use
<option>--all
</option> to show
599 those too. To select specific properties to show, use
600 <option>--property=
</option>. This command is intended to be
601 used whenever computer-parsable output is required. Use
602 <command>image-status
</command> if you are looking for
603 formatted human-readable output.
</para></listitem>
607 <term><command>clone
</command> <replaceable>NAME
</replaceable> <replaceable>NAME
</replaceable></term>
609 <listitem><para>Clones a container or VM image. The arguments specify the name of the image to clone and the
610 name of the newly cloned image. Note that plain directory container images are cloned into btrfs subvolume
611 images with this command, if the underlying file system supports this. Note that cloning a container or VM
612 image is optimized for file systems that support copy-on-write, and might not be efficient on others, due to
613 file system limitations.
</para>
615 <para>Note that this command leaves host name, machine ID and
616 all other settings that could identify the instance
617 unmodified. The original image and the cloned copy will hence
618 share these credentials, and it might be necessary to manually
619 change them in the copy.
</para>
621 <para>If combined with the
<option>--read-only
</option> switch a read-only cloned image is
622 created.
</para></listitem>
626 <term><command>rename
</command> <replaceable>NAME
</replaceable> <replaceable>NAME
</replaceable></term>
628 <listitem><para>Renames a container or VM image. The
629 arguments specify the name of the image to rename and the new
630 name of the image.
</para></listitem>
634 <term><command>read-only
</command> <replaceable>NAME
</replaceable> [
<replaceable>BOOL
</replaceable>]
</term>
636 <listitem><para>Marks or (unmarks) a container or VM image
637 read-only. Takes a VM or container image name, followed by a
638 boolean as arguments. If the boolean is omitted, positive is
639 implied, i.e. the image is marked read-only.
</para></listitem>
643 <term><command>remove
</command> <replaceable>NAME
</replaceable>…
</term>
645 <listitem><para>Removes one or more container or VM images.
646 The special image
<literal>.host
</literal>, which refers to
647 the host's own directory tree, may not be
648 removed.
</para></listitem>
652 <term><command>set-limit
</command> [
<replaceable>NAME
</replaceable>]
<replaceable>BYTES
</replaceable></term>
654 <listitem><para>Sets the maximum size in bytes that a specific
655 container or VM image, or all images, may grow up to on disk
656 (disk quota). Takes either one or two parameters. The first,
657 optional parameter refers to a container or VM image name. If
658 specified, the size limit of the specified image is changed. If
659 omitted, the overall size limit of the sum of all images stored
660 locally is changed. The final argument specifies the size
661 limit in bytes, possibly suffixed by the usual K, M, G, T
662 units. If the size limit shall be disabled, specify
663 <literal>-
</literal> as size.
</para>
665 <para>Note that per-container size limits are only supported
666 on btrfs file systems. Also note that, if
667 <command>set-limit
</command> is invoked without an image
668 parameter, and
<filename>/var/lib/machines
</filename> is
669 empty, and the directory is not located on btrfs, a btrfs
670 loopback file is implicitly created as
671 <filename>/var/lib/machines.raw
</filename> with the given
673 <filename>/var/lib/machines
</filename>. The size of the
674 loopback may later be readjusted with
675 <command>set-limit
</command>, as well. If such a
676 loopback-mounted
<filename>/var/lib/machines
</filename>
677 directory is used,
<command>set-limit
</command> without an image
678 name alters both the quota setting within the file system as
679 well as the loopback file and file system size
680 itself.
</para></listitem>
684 <term><command>clean
</command></term>
686 <listitem><para>Remove hidden VM or container images (or all). This command removes all hidden machine images
687 from
<filename>/var/lib/machines
</filename>, i.e. those whose name begins with a dot. Use
<command>machinectl
688 list-images --all
</command> to see a list of all machine images, including the hidden ones.
</para>
690 <para>When combined with the
<option>--all
</option> switch removes all images, not just hidden ones. This
691 command effectively empties
<filename>/var/lib/machines
</filename>.
</para>
693 <para>Note that commands such as
<command>machinectl pull-tar
</command> or
<command>machinectl
694 pull-raw
</command> usually create hidden, read-only, unmodified machine images from the downloaded image first,
695 before cloning a writable working copy of it, in order to avoid duplicate downloads in case of images that are
696 reused multiple times. Use
<command>machinectl clean
</command> to remove old, hidden images created this
697 way.
</para></listitem>
700 </variablelist></refsect2>
702 <refsect2><title>Image Transfer Commands
</title><variablelist>
705 <term><command>pull-tar
</command> <replaceable>URL
</replaceable> [
<replaceable>NAME
</replaceable>]
</term>
707 <listitem><para>Downloads a
<filename>.tar
</filename>
708 container image from the specified URL, and makes it available
709 under the specified local machine name. The URL must be of
710 type
<literal>http://
</literal> or
711 <literal>https://
</literal>, and must refer to a
712 <filename>.tar
</filename>,
<filename>.tar.gz
</filename>,
713 <filename>.tar.xz
</filename> or
<filename>.tar.bz2
</filename>
714 archive file. If the local machine name is omitted, it
715 is automatically derived from the last component of the URL,
716 with its suffix removed.
</para>
718 <para>The image is verified before it is made available, unless
719 <option>--verify=no
</option> is specified.
720 Verification is done either via an inline signed file with the name
721 of the image and the suffix
<filename>.sha256
</filename> or via
722 separate
<filename>SHA256SUMS
</filename> and
723 <filename>SHA256SUMS.gpg
</filename> files.
724 The signature files need to be made available on the same web
725 server, under the same URL as the
<filename>.tar
</filename> file.
726 With
<option>--verify=checksum
</option>, only the SHA256 checksum
727 for the file is verified, based on the
<filename>.sha256
</filename>
728 suffixed file or the
<filename>SHA256SUMS
</filename> file.
729 With
<option>--verify=signature
</option>, the sha checksum file is
730 first verified with the inline signature in the
731 <filename>.sha256
</filename> file or the detached GPG signature file
732 <filename>SHA256SUMS.gpg
</filename>.
733 The public key for this verification step needs to be available in
734 <filename>/usr/lib/systemd/import-pubring.gpg
</filename> or
735 <filename>/etc/systemd/import-pubring.gpg
</filename>.
</para>
737 <para>The container image will be downloaded and stored in a
738 read-only subvolume in
739 <filename>/var/lib/machines/
</filename> that is named after
740 the specified URL and its HTTP etag. A writable snapshot is
741 then taken from this subvolume, and named after the specified
742 local name. This behavior ensures that creating multiple
743 container instances of the same URL is efficient, as multiple
744 downloads are not necessary. In order to create only the
745 read-only image, and avoid creating its writable snapshot,
746 specify
<literal>-
</literal> as local machine name.
</para>
748 <para>Note that the read-only subvolume is prefixed with
749 <filename>.tar-
</filename>, and is thus not shown by
750 <command>list-images
</command>, unless
<option>--all
</option>
753 <para>Note that pressing C-c during execution of this command
754 will not abort the download. Use
755 <command>cancel-transfer
</command>, described
756 below.
</para></listitem>
760 <term><command>pull-raw
</command> <replaceable>URL
</replaceable> [
<replaceable>NAME
</replaceable>]
</term>
762 <listitem><para>Downloads a
<filename>.raw
</filename>
763 container or VM disk image from the specified URL, and makes
764 it available under the specified local machine name. The URL
765 must be of type
<literal>http://
</literal> or
766 <literal>https://
</literal>. The container image must either
767 be a
<filename>.qcow2
</filename> or raw disk image, optionally
768 compressed as
<filename>.gz
</filename>,
769 <filename>.xz
</filename>, or
<filename>.bz2
</filename>. If the
770 local machine name is omitted, it is automatically
771 derived from the last component of the URL, with its suffix
774 <para>Image verification is identical for raw and tar images
777 <para>If the downloaded image is in
778 <filename>.qcow2
</filename> format it is converted into a raw
779 image file before it is made available.
</para>
781 <para>Downloaded images of this type will be placed as
782 read-only
<filename>.raw
</filename> file in
783 <filename>/var/lib/machines/
</filename>. A local, writable
784 (reflinked) copy is then made under the specified local
785 machine name. To omit creation of the local, writable copy
786 pass
<literal>-
</literal> as local machine name.
</para>
788 <para>Similar to the behavior of
<command>pull-tar
</command>,
789 the read-only image is prefixed with
790 <filename>.raw-
</filename>, and thus not shown by
791 <command>list-images
</command>, unless
<option>--all
</option>
794 <para>Note that pressing C-c during execution of this command
795 will not abort the download. Use
796 <command>cancel-transfer
</command>, described
797 below.
</para></listitem>
801 <term><command>import-tar
</command> <replaceable>FILE
</replaceable> [
<replaceable>NAME
</replaceable>]
</term>
802 <term><command>import-raw
</command> <replaceable>FILE
</replaceable> [
<replaceable>NAME
</replaceable>]
</term>
803 <listitem><para>Imports a TAR or RAW container or VM image,
804 and places it under the specified name in
805 <filename>/var/lib/machines/
</filename>. When
806 <command>import-tar
</command> is used, the file specified as
807 the first argument should be a tar archive, possibly compressed
808 with xz, gzip or bzip2. It will then be unpacked into its own
809 subvolume in
<filename>/var/lib/machines
</filename>. When
810 <command>import-raw
</command> is used, the file should be a
811 qcow2 or raw disk image, possibly compressed with xz, gzip or
812 bzip2. If the second argument (the resulting image name) is
813 not specified, it is automatically derived from the file
814 name. If the filename is passed as
<literal>-
</literal>, the
815 image is read from standard input, in which case the second
816 argument is mandatory.
</para>
818 <para>Both
<command>pull-tar
</command> and
<command>pull-raw
</command>
819 will resize
<filename>/var/lib/machines.raw
</filename> and the
820 filesystem therein as necessary. Optionally, the
821 <option>--read-only
</option> switch may be used to create a
822 read-only container or VM image. No cryptographic validation
823 is done when importing the images.
</para>
825 <para>Much like image downloads, ongoing imports may be listed
826 with
<command>list-transfers
</command> and aborted with
827 <command>cancel-transfer
</command>.
</para></listitem>
831 <term><command>export-tar
</command> <replaceable>NAME
</replaceable> [
<replaceable>FILE
</replaceable>]
</term>
832 <term><command>export-raw
</command> <replaceable>NAME
</replaceable> [
<replaceable>FILE
</replaceable>]
</term>
833 <listitem><para>Exports a TAR or RAW container or VM image and
834 stores it in the specified file. The first parameter should be
835 a VM or container image name. The second parameter should be a
836 file path the TAR or RAW image is written to. If the path ends
837 in
<literal>.gz
</literal>, the file is compressed with gzip, if
838 it ends in
<literal>.xz
</literal>, with xz, and if it ends in
839 <literal>.bz2
</literal>, with bzip2. If the path ends in
840 neither, the file is left uncompressed. If the second argument
841 is missing, the image is written to standard output. The
842 compression may also be explicitly selected with the
843 <option>--format=
</option> switch. This is in particular
844 useful if the second parameter is left unspecified.
</para>
846 <para>Much like image downloads and imports, ongoing exports
847 may be listed with
<command>list-transfers
</command> and
849 <command>cancel-transfer
</command>.
</para>
851 <para>Note that, currently, only directory and subvolume images
852 may be exported as TAR images, and only raw disk images as RAW
853 images.
</para></listitem>
857 <term><command>list-transfers
</command></term>
859 <listitem><para>Shows a list of container or VM image
860 downloads, imports and exports that are currently in
861 progress.
</para></listitem>
865 <term><command>cancel-transfer
</command> <replaceable>ID
</replaceable>…
</term>
867 <listitem><para>Aborts a download, import or export of the
868 container or VM image with the specified ID. To list ongoing
869 transfers and their IDs, use
870 <command>list-transfers
</command>.
</para></listitem>
873 </variablelist></refsect2>
878 <title>Machine and Image Names
</title>
880 <para>The
<command>machinectl
</command> tool operates on machines
881 and images whose names must be chosen following strict
882 rules. Machine names must be suitable for use as host names
883 following a conservative subset of DNS and UNIX/Linux
884 semantics. Specifically, they must consist of one or more
885 non-empty label strings, separated by dots. No leading or trailing
886 dots are allowed. No sequences of multiple dots are allowed. The
887 label strings may only consist of alphanumeric characters as well
888 as the dash and underscore. The maximum length of a machine name
889 is
64 characters.
</para>
891 <para>A special machine with the name
<literal>.host
</literal>
892 refers to the running host system itself. This is useful for execution
893 operations or inspecting the host system as well. Note that
894 <command>machinectl list
</command> will not show this special
895 machine unless the
<option>--all
</option> switch is specified.
</para>
897 <para>Requirements on image names are less strict, however, they must be
898 valid UTF-
8, must be suitable as file names (hence not be the
899 single or double dot, and not include a slash), and may not
900 contain control characters. Since many operations search for an
901 image by the name of a requested machine, it is recommended to name
902 images in the same strict fashion as machines.
</para>
904 <para>A special image with the name
<literal>.host
</literal>
905 refers to the image of the running host system. It hence
906 conceptually maps to the special
<literal>.host
</literal> machine
907 name described above. Note that
<command>machinectl
908 list-images
</command> will not show this special image either, unless
909 <option>--all
</option> is specified.
</para>
913 <title>Files and Directories
</title>
915 <para>Machine images are preferably stored in
916 <filename>/var/lib/machines/
</filename>, but are also searched for
917 in
<filename>/usr/local/lib/machines/
</filename> and
918 <filename>/usr/lib/machines/
</filename>. For compatibility reasons,
919 the directory
<filename>/var/lib/container/
</filename> is
920 searched, too. Note that images stored below
921 <filename>/usr
</filename> are always considered read-only. It is
922 possible to symlink machines images from other directories into
923 <filename>/var/lib/machines/
</filename> to make them available for
924 control with
<command>machinectl
</command>.
</para>
926 <para>Note that some image operations are only supported,
927 efficient or atomic on btrfs file systems. Due to this, if the
928 <command>pull-tar
</command>,
<command>pull-raw
</command>,
929 <command>import-tar
</command>,
<command>import-raw
</command> and
930 <command>set-limit
</command> commands notice that
931 <filename>/var/lib/machines
</filename> is empty and not located on
932 btrfs, they will implicitly set up a loopback file
933 <filename>/var/lib/machines.raw
</filename> containing a btrfs file
934 system that is mounted to
935 <filename>/var/lib/machines
</filename>. The size of this loopback
936 file may be controlled dynamically with
937 <command>set-limit
</command>.
</para>
939 <para>Disk images are understood by
940 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
941 and
<command>machinectl
</command> in three formats:
</para>
944 <listitem><para>A simple directory tree, containing the files
945 and directories of the container to boot.
</para></listitem>
947 <listitem><para>Subvolumes (on btrfs file systems), which are
948 similar to the simple directories, described above. However,
949 they have additional benefits, such as efficient cloning and
950 quota reporting.
</para></listitem>
952 <listitem><para>"Raw" disk images, i.e. binary images of disks
953 with a GPT or MBR partition table. Images of this type are
954 regular files with the suffix
955 <literal>.raw
</literal>.
</para></listitem>
959 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
960 for more information on image formats, in particular its
961 <option>--directory=
</option> and
<option>--image=
</option>
966 <title>Examples
</title>
968 <title>Download an Ubuntu image and open a shell in it
</title>
970 <programlisting># machinectl pull-tar https://cloud-images.ubuntu.com/trusty/current/trusty-server-cloudimg-amd64-root.tar.gz
971 # systemd-nspawn -M trusty-server-cloudimg-amd64-root
</programlisting>
973 <para>This downloads and verifies the specified
974 <filename>.tar
</filename> image, and then uses
975 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
976 to open a shell in it.
</para>
980 <title>Download a Fedora image, set a root password in it, start
981 it as service
</title>
983 <programlisting># machinectl pull-raw --verify=no https://dl.fedoraproject.org/pub/fedora/linux/releases/
27/CloudImages/x86_64/images/Fedora-Cloud-Base-
27-
1.6.x86_64.raw.xz
984 # systemd-nspawn -M Fedora-Cloud-Base-
27-
1.6.x86_64
987 # machinectl start Fedora-Cloud-Base-
27-
1.6.x86_64
988 # machinectl login Fedora-Cloud-Base-
27-
1.6.x86_64
</programlisting>
990 <para>This downloads the specified
<filename>.raw
</filename>
991 image with verification disabled. Then, a shell is opened in it
992 and a root password is set. Afterwards the shell is left, and
993 the machine started as system service. With the last command a
994 login prompt into the container is requested.
</para>
998 <title>Exports a container image as tar file
</title>
1000 <programlisting># machinectl export-tar fedora myfedora.tar.xz
</programlisting>
1002 <para>Exports the container
<literal>fedora
</literal> as an
1003 xz-compressed tar file
<filename>myfedora.tar.xz
</filename> into the
1004 current directory.
</para>
1008 <title>Create a new shell session
</title>
1010 <programlisting># machinectl shell --uid=lennart
</programlisting>
1012 <para>This creates a new shell session on the local host for
1013 the user ID
<literal>lennart
</literal>, in a
<citerefentry
1014 project='die-net'
><refentrytitle>su
</refentrytitle><manvolnum>1</manvolnum></citerefentry>-like
1021 <title>Exit status
</title>
1023 <para>On success,
0 is returned, a non-zero failure code
1027 <xi:include href=
"less-variables.xml" />
1030 <title>See Also
</title>
1032 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1033 <citerefentry><refentrytitle>systemd-machined.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
1034 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1035 <citerefentry><refentrytitle>systemd.special
</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1036 <citerefentry project='die-net'
><refentrytitle>tar
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1037 <citerefentry project='die-net'
><refentrytitle>xz
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1038 <citerefentry project='die-net'
><refentrytitle>gzip
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1039 <citerefentry project='die-net'
><refentrytitle>bzip2
</refentrytitle><manvolnum>1</manvolnum></citerefentry>