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>--no-ask-password
</option></term>
149 <listitem><para>Do not query the user for authentication for
150 privileged operations.
</para></listitem>
154 <term><option>--kill-who=
</option></term>
156 <listitem><para>When used with
<command>kill
</command>, choose
157 which processes to kill. Must be one of
158 <option>leader
</option>, or
<option>all
</option> to select
159 whether to kill only the leader process of the machine or all
160 processes of the machine. If omitted, defaults to
161 <option>all
</option>.
</para></listitem>
165 <term><option>-s
</option></term>
166 <term><option>--signal=
</option></term>
168 <listitem><para>When used with
<command>kill
</command>, choose
169 which signal to send to selected processes. Must be one of the
170 well-known signal specifiers, such as
171 <constant>SIGTERM
</constant>,
<constant>SIGINT
</constant> or
172 <constant>SIGSTOP
</constant>. If omitted, defaults to
173 <constant>SIGTERM
</constant>.
</para></listitem>
177 <term><option>--uid=
</option></term>
179 <listitem><para>When used with the
<command>shell
</command> command, chooses the user ID to
180 open the interactive shell session as. If the argument to the
<command>shell
</command>
181 command also specifies a user name, this option is ignored. If the name is not specified
182 in either way,
<literal>root
</literal> will be used by default. Note that this switch is
183 not supported for the
<command>login
</command> command (see below).
</para></listitem>
187 <term><option>-E
<replaceable>NAME
</replaceable>=
<replaceable>VALUE
</replaceable></option></term>
188 <term><option>--setenv=
<replaceable>NAME
</replaceable>=
<replaceable>VALUE
</replaceable></option></term>
190 <listitem><para>When used with the
<command>shell
</command> command, sets an environment
191 variable to pass to the executed shell. Takes an environment variable name and value,
192 separated by
<literal>=
</literal>. This switch may be used multiple times to set multiple
193 environment variables. Note that this switch is not supported for the
194 <command>login
</command> command (see below).
</para></listitem>
198 <term><option>--mkdir
</option></term>
200 <listitem><para>When used with
<command>bind
</command>, creates the destination file or directory before
201 applying the bind mount. Note that even though the name of this option suggests that it is suitable only for
202 directories, this option also creates the destination file node to mount over if the the object to mount is not
203 a directory, but a regular file, device node, socket or FIFO.
</para></listitem>
207 <term><option>--read-only
</option></term>
209 <listitem><para>When used with
<command>bind
</command>, creates a read-only bind mount.
</para>
211 <para>When used with
<command>clone
</command>,
<command>import-raw
</command> or
<command>import-tar
</command> a
212 read-only container or VM image is created.
</para></listitem>
216 <term><option>-n
</option></term>
217 <term><option>--lines=
</option></term>
219 <listitem><para>When used with
<command>status
</command>,
220 controls the number of journal lines to show, counting from
221 the most recent ones. Takes a positive integer argument.
222 Defaults to
10.
</para>
227 <term><option>-o
</option></term>
228 <term><option>--output=
</option></term>
230 <listitem><para>When used with
<command>status
</command>,
231 controls the formatting of the journal entries that are shown.
232 For the available choices, see
233 <citerefentry><refentrytitle>journalctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
234 Defaults to
<literal>short
</literal>.
</para></listitem>
238 <term><option>--verify=
</option></term>
240 <listitem><para>When downloading a container or VM image,
241 specify whether the image shall be verified before it is made
242 available. Takes one of
<literal>no
</literal>,
243 <literal>checksum
</literal> and
<literal>signature
</literal>.
244 If
<literal>no
</literal>, no verification is done. If
245 <literal>checksum
</literal> is specified, the download is
246 checked for integrity after the transfer is complete, but no
247 signatures are verified. If
<literal>signature
</literal> is
248 specified, the checksum is verified and the image's signature
249 is checked against a local keyring of trustable vendors. It is
250 strongly recommended to set this option to
251 <literal>signature
</literal> if the server and protocol
252 support this. Defaults to
253 <literal>signature
</literal>.
</para></listitem>
257 <term><option>--force
</option></term>
259 <listitem><para>When downloading a container or VM image, and
260 a local copy by the specified local machine name already
261 exists, delete it first and replace it by the newly downloaded
262 image.
</para></listitem>
266 <term><option>--format=
</option></term>
268 <listitem><para>When used with the
<option>export-tar
</option>
269 or
<option>export-raw
</option> commands, specifies the
270 compression format to use for the resulting file. Takes one of
271 <literal>uncompressed
</literal>,
<literal>xz
</literal>,
272 <literal>gzip
</literal>,
<literal>bzip2
</literal>. By default,
273 the format is determined automatically from the image file
274 name passed.
</para></listitem>
278 <term><option>--max-addresses=
</option></term>
280 <listitem><para>When used with the
<option>list-machines
</option>
281 command, limits the number of ip addresses output for every machine.
282 Defaults to
1. All addresses can be requested with
<literal>all
</literal>
283 as argument to
<option>--max-addresses
</option> . If the argument to
284 <option>--max-addresses
</option> is less than the actual number
285 of addresses,
<literal>...
</literal>follows the last address.
286 If multiple addresses are to be written for a given machine, every
287 address except the first one is on a new line and is followed by
288 <literal>,
</literal> if another address will be output afterwards.
</para></listitem>
292 <term><option>-q
</option></term>
293 <term><option>--quiet
</option></term>
295 <listitem><para>Suppresses additional informational output while running.
</para></listitem>
298 <xi:include href=
"user-system-options.xml" xpointer=
"host" />
301 <term><option>-M
</option></term>
302 <term><option>--machine=
</option></term>
304 <listitem><para>Connect to
305 <citerefentry><refentrytitle>systemd-machined.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
306 running in a local container, to perform the specified operation within
307 the container.
</para></listitem>
310 <xi:include href=
"standard-options.xml" xpointer=
"no-pager" />
311 <xi:include href=
"standard-options.xml" xpointer=
"no-legend" />
312 <xi:include href=
"standard-options.xml" xpointer=
"help" />
313 <xi:include href=
"standard-options.xml" xpointer=
"version" />
318 <title>Commands
</title>
320 <para>The following commands are understood:
</para>
322 <refsect2><title>Machine Commands
</title><variablelist>
325 <term><command>list
</command></term>
327 <listitem><para>List currently running (online) virtual
328 machines and containers. To enumerate machine images that can
329 be started, use
<command>list-images
</command> (see
330 below). Note that this command hides the special
331 <literal>.host
</literal> machine by default. Use the
332 <option>--all
</option> switch to show it.
</para></listitem>
336 <term><command>status
</command> <replaceable>NAME
</replaceable>…
</term>
338 <listitem><para>Show runtime status information about
339 one or more virtual machines and containers, followed by the
340 most recent log data from the journal. This function is
341 intended to generate human-readable output. If you are looking
342 for computer-parsable output, use
<command>show
</command>
343 instead. Note that the log data shown is reported by the
344 virtual machine or container manager, and frequently contains
345 console output of the machine, but not necessarily journal
346 contents of the machine itself.
</para></listitem>
350 <term><command>show
</command> [
<replaceable>NAME
</replaceable>…]
</term>
352 <listitem><para>Show properties of one or more registered virtual machines or containers or the manager
353 itself. If no argument is specified, properties of the manager will be shown. If a NAME is specified,
354 properties of this virtual machine or container are shown. By default, empty properties are suppressed. Use
355 <option>--all
</option> to show those too. To select specific properties to show, use
356 <option>--property=
</option>. This command is intended to be used whenever computer-parsable output is
357 required, and does not print the control group tree or journal entries. Use
<command>status
</command> if you
358 are looking for formatted human-readable output.
</para></listitem>
362 <term><command>start
</command> <replaceable>NAME
</replaceable>…
</term>
364 <listitem><para>Start a container as a system service, using
365 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
366 This starts
<filename>systemd-nspawn@.service
</filename>,
367 instantiated for the specified machine name, similar to the
368 effect of
<command>systemctl start
</command> on the service
369 name.
<command>systemd-nspawn
</command> looks for a container
370 image by the specified name in
371 <filename>/var/lib/machines/
</filename> (and other search
372 paths, see below) and runs it. Use
373 <command>list-images
</command> (see below) for listing
374 available container images to start.
</para>
377 <citerefentry><refentrytitle>systemd-machined.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
378 also interfaces with a variety of other container and VM
379 managers,
<command>systemd-nspawn
</command> is just one
380 implementation of it. Most of the commands available in
381 <command>machinectl
</command> may be used on containers or VMs
382 controlled by other managers, not just
383 <command>systemd-nspawn
</command>. Starting VMs and container
384 images on those managers requires manager-specific
387 <para>To interactively start a container on the command line
388 with full access to the container's console, please invoke
389 <command>systemd-nspawn
</command> directly. To stop a running
390 container use
<command>machinectl poweroff
</command>.
</para></listitem>
394 <term><command>login
</command> [
<replaceable>NAME
</replaceable>]
</term>
396 <listitem><para>Open an interactive terminal login session in
397 a container or on the local host. If an argument is supplied,
398 it refers to the container machine to connect to. If none is
399 specified, or the container name is specified as the empty
400 string, or the special machine name
<literal>.host
</literal>
401 (see below) is specified, the connection is made to the local
402 host instead. This will create a TTY connection to a specific
403 container or the local host and asks for the execution of a
404 getty on it. Note that this is only supported for containers
406 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
407 as init system.
</para>
409 <para>This command will open a full login prompt on the
410 container or the local host, which then asks for username and
411 password. Use
<command>shell
</command> (see below) or
412 <citerefentry><refentrytitle>systemd-run
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
413 with the
<option>--machine=
</option> switch to directly invoke
414 a single command, either interactively or in the
415 background.
</para></listitem>
419 <term><command>shell
</command> [[
<replaceable>NAME
</replaceable>@]
<replaceable>NAME
</replaceable> [
<replaceable>PATH
</replaceable> [
<replaceable>ARGUMENTS
</replaceable>…]]]
</term>
421 <listitem><para>Open an interactive shell session in a
422 container or on the local host. The first argument refers to
423 the container machine to connect to. If none is specified, or
424 the machine name is specified as the empty string, or the
425 special machine name
<literal>.host
</literal> (see below) is
426 specified, the connection is made to the local host
427 instead. This works similar to
<command>login
</command> but
428 immediately invokes a user process. This command runs the
429 specified executable with the specified arguments, or the
430 default shell for the user if none is specified, or
431 <filename>/bin/sh
</filename> if no default shell is found. By default,
432 <option>--uid=
</option>, or by prefixing the machine name with
433 a username and an
<literal>@
</literal> character, a different
434 user may be selected. Use
<option>--setenv=
</option> to set
435 environment variables for the executed process.
</para>
437 <para>Note that
<command>machinectl shell
</command> does not propagate the exit code/status of the invoked
438 shell process. Use
<command>systemd-run
</command> instead if that information is required (see below).
</para>
440 <para>When using the
<command>shell
</command> command without
441 arguments, (thus invoking the executed shell or command on the
442 local host), it is in many ways similar to a
<citerefentry
443 project='die-net'
><refentrytitle>su
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
444 session, but, unlike
<command>su
</command>, completely isolates
445 the new session from the originating session, so that it
446 shares no process or session properties, and is in a clean and
447 well-defined state. It will be tracked in a new utmp, login,
448 audit, security and keyring session, and will not inherit any
449 environment variables or resource limits, among other
452 <para>Note that
<citerefentry><refentrytitle>systemd-run
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
453 with its
<option>--machine=
</option> switch may be used in place of the
<command>machinectl shell
</command>
454 command, and allows non-interactive operation, more detailed and low-level configuration of the invoked unit,
455 as well as access to runtime and exit code/status information of the invoked shell process. In particular, use
456 <command>systemd-run
</command>'s
<option>--wait
</option> switch to propagate exit status information of the
457 invoked process. Use
<command>systemd-run
</command>'s
<option>--pty
</option> switch for acquiring an
458 interactive shell, similar to
<command>machinectl shell
</command>. In general,
<command>systemd-run
</command>
459 is preferable for scripting purposes. However, note that
<command>systemd-run
</command> might require higher
460 privileges than
<command>machinectl shell
</command>.
</para></listitem>
464 <term><command>enable
</command> <replaceable>NAME
</replaceable>…
</term>
465 <term><command>disable
</command> <replaceable>NAME
</replaceable>…
</term>
467 <listitem><para>Enable or disable a container as a system
468 service to start at system boot, using
469 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
470 This enables or disables
471 <filename>systemd-nspawn@.service
</filename>, instantiated for
472 the specified machine name, similar to the effect of
473 <command>systemctl enable
</command> or
<command>systemctl
474 disable
</command> on the service name.
</para></listitem>
478 <term><command>poweroff
</command> <replaceable>NAME
</replaceable>…
</term>
480 <listitem><para>Power off one or more containers. This will
481 trigger a reboot by sending SIGRTMIN+
4 to the container's init
482 process, which causes systemd-compatible init systems to shut
483 down cleanly. Use
<command>stop
</command> as alias for
<command>poweroff
</command>.
484 This operation does not work on containers that do not run a
485 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>-compatible
486 init system, such as sysvinit. Use
487 <command>terminate
</command> (see below) to immediately
488 terminate a container or VM, without cleanly shutting it
489 down.
</para></listitem>
493 <term><command>reboot
</command> <replaceable>NAME
</replaceable>…
</term>
495 <listitem><para>Reboot one or more containers. This will
496 trigger a reboot by sending SIGINT to the container's init
497 process, which is roughly equivalent to pressing Ctrl+Alt+Del
498 on a non-containerized system, and is compatible with
499 containers running any system manager.
</para></listitem>
503 <term><command>terminate
</command> <replaceable>NAME
</replaceable>…
</term>
505 <listitem><para>Immediately terminates a virtual machine or
506 container, without cleanly shutting it down. This kills all
507 processes of the virtual machine or container and deallocates
508 all resources attached to that instance. Use
509 <command>poweroff
</command> to issue a clean shutdown
510 request.
</para></listitem>
514 <term><command>kill
</command> <replaceable>NAME
</replaceable>…
</term>
516 <listitem><para>Send a signal to one or more processes of the
517 virtual machine or container. This means processes as seen by
518 the host, not the processes inside the virtual machine or
519 container. Use
<option>--kill-who=
</option> to select which
520 process to kill. Use
<option>--signal=
</option> to select the
521 signal to send.
</para></listitem>
525 <term><command>bind
</command> <replaceable>NAME
</replaceable> <replaceable>PATH
</replaceable> [
<replaceable>PATH
</replaceable>]
</term>
527 <listitem><para>Bind mounts a file or directory from the host into the specified container. The first path
528 argument is the source file or directory on the host, the second path argument is the destination file or
529 directory in the container. When the latter is omitted, the destination path in the container is the same as
530 the source path on the host. When combined with the
<option>--read-only
</option> switch, a ready-only bind
531 mount is created. When combined with the
<option>--mkdir
</option> switch, the destination path is first created
532 before the mount is applied. Note that this option is currently only supported for
533 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry> containers,
534 and only if user namespacing (
<option>--private-users
</option>) is not used. This command supports bind
535 mounting directories, regular files, device nodes,
<constant>AF_UNIX
</constant> socket nodes, as well as
536 FIFOs.
</para></listitem>
540 <term><command>copy-to
</command> <replaceable>NAME
</replaceable> <replaceable>PATH
</replaceable> [
<replaceable>PATH
</replaceable>]
</term>
542 <listitem><para>Copies files or directories from the host
543 system into a running container. Takes a container name,
544 followed by the source path on the host and the destination
545 path in the container. If the destination path is omitted, the
546 same as the source path is used.
</para>
548 <para>If host and container share the same user and group namespace, file ownership by numeric user ID and
549 group ID is preserved for the copy, otherwise all files and directories in the copy will be owned by the root
550 user and group (UID/GID
0).
</para></listitem>
554 <term><command>copy-from
</command> <replaceable>NAME
</replaceable> <replaceable>PATH
</replaceable> [
<replaceable>PATH
</replaceable>]
</term>
556 <listitem><para>Copies files or directories from a container
557 into the host system. Takes a container name, followed by the
558 source path in the container the destination path on the host.
559 If the destination path is omitted, the same as the source path
562 <para>If host and container share the same user and group namespace, file ownership by numeric user ID and
563 group ID is preserved for the copy, otherwise all files and directories in the copy will be owned by the root
564 user and group (UID/GID
0).
</para></listitem>
566 </variablelist></refsect2>
568 <refsect2><title>Image Commands
</title><variablelist>
571 <term><command>list-images
</command></term>
573 <listitem><para>Show a list of locally installed container and
574 VM images. This enumerates all raw disk images and container
575 directories and subvolumes in
576 <filename>/var/lib/machines/
</filename> (and other search
577 paths, see below). Use
<command>start
</command> (see above) to
578 run a container off one of the listed images. Note that, by
579 default, containers whose name begins with a dot
580 (
<literal>.
</literal>) are not shown. To show these too,
581 specify
<option>--all
</option>. Note that a special image
582 <literal>.host
</literal> always implicitly exists and refers
583 to the image the host itself is booted from.
</para></listitem>
587 <term><command>image-status
</command> [
<replaceable>NAME
</replaceable>…]
</term>
589 <listitem><para>Show terse status information about one or
590 more container or VM images. This function is intended to
591 generate human-readable output. Use
592 <command>show-image
</command> (see below) to generate
593 computer-parsable output instead.
</para></listitem>
597 <term><command>show-image
</command> [
<replaceable>NAME
</replaceable>…]
</term>
599 <listitem><para>Show properties of one or more registered
600 virtual machine or container images, or the manager itself. If
601 no argument is specified, properties of the manager will be
602 shown. If a NAME is specified, properties of this virtual
603 machine or container image are shown. By default, empty
604 properties are suppressed. Use
<option>--all
</option> to show
605 those too. To select specific properties to show, use
606 <option>--property=
</option>. This command is intended to be
607 used whenever computer-parsable output is required. Use
608 <command>image-status
</command> if you are looking for
609 formatted human-readable output.
</para></listitem>
613 <term><command>clone
</command> <replaceable>NAME
</replaceable> <replaceable>NAME
</replaceable></term>
615 <listitem><para>Clones a container or VM image. The arguments specify the name of the image to clone and the
616 name of the newly cloned image. Note that plain directory container images are cloned into btrfs subvolume
617 images with this command, if the underlying file system supports this. Note that cloning a container or VM
618 image is optimized for file systems that support copy-on-write, and might not be efficient on others, due to
619 file system limitations.
</para>
621 <para>Note that this command leaves host name, machine ID and
622 all other settings that could identify the instance
623 unmodified. The original image and the cloned copy will hence
624 share these credentials, and it might be necessary to manually
625 change them in the copy.
</para>
627 <para>If combined with the
<option>--read-only
</option> switch a read-only cloned image is
628 created.
</para></listitem>
632 <term><command>rename
</command> <replaceable>NAME
</replaceable> <replaceable>NAME
</replaceable></term>
634 <listitem><para>Renames a container or VM image. The
635 arguments specify the name of the image to rename and the new
636 name of the image.
</para></listitem>
640 <term><command>read-only
</command> <replaceable>NAME
</replaceable> [
<replaceable>BOOL
</replaceable>]
</term>
642 <listitem><para>Marks or (unmarks) a container or VM image
643 read-only. Takes a VM or container image name, followed by a
644 boolean as arguments. If the boolean is omitted, positive is
645 implied, i.e. the image is marked read-only.
</para></listitem>
649 <term><command>remove
</command> <replaceable>NAME
</replaceable>…
</term>
651 <listitem><para>Removes one or more container or VM images.
652 The special image
<literal>.host
</literal>, which refers to
653 the host's own directory tree, may not be
654 removed.
</para></listitem>
658 <term><command>set-limit
</command> [
<replaceable>NAME
</replaceable>]
<replaceable>BYTES
</replaceable></term>
660 <listitem><para>Sets the maximum size in bytes that a specific
661 container or VM image, or all images, may grow up to on disk
662 (disk quota). Takes either one or two parameters. The first,
663 optional parameter refers to a container or VM image name. If
664 specified, the size limit of the specified image is changed. If
665 omitted, the overall size limit of the sum of all images stored
666 locally is changed. The final argument specifies the size
667 limit in bytes, possibly suffixed by the usual K, M, G, T
668 units. If the size limit shall be disabled, specify
669 <literal>-
</literal> as size.
</para>
671 <para>Note that per-container size limits are only supported
672 on btrfs file systems. Also note that, if
673 <command>set-limit
</command> is invoked without an image
674 parameter, and
<filename>/var/lib/machines
</filename> is
675 empty, and the directory is not located on btrfs, a btrfs
676 loopback file is implicitly created as
677 <filename>/var/lib/machines.raw
</filename> with the given
679 <filename>/var/lib/machines
</filename>. The size of the
680 loopback may later be readjusted with
681 <command>set-limit
</command>, as well. If such a
682 loopback-mounted
<filename>/var/lib/machines
</filename>
683 directory is used,
<command>set-limit
</command> without an image
684 name alters both the quota setting within the file system as
685 well as the loopback file and file system size
686 itself.
</para></listitem>
690 <term><command>clean
</command></term>
692 <listitem><para>Remove hidden VM or container images (or all). This command removes all hidden machine images
693 from
<filename>/var/lib/machines
</filename>, i.e. those whose name begins with a dot. Use
<command>machinectl
694 list-images --all
</command> to see a list of all machine images, including the hidden ones.
</para>
696 <para>When combined with the
<option>--all
</option> switch removes all images, not just hidden ones. This
697 command effectively empties
<filename>/var/lib/machines
</filename>.
</para>
699 <para>Note that commands such as
<command>machinectl pull-tar
</command> or
<command>machinectl
700 pull-raw
</command> usually create hidden, read-only, unmodified machine images from the downloaded image first,
701 before cloning a writable working copy of it, in order to avoid duplicate downloads in case of images that are
702 reused multiple times. Use
<command>machinectl clean
</command> to remove old, hidden images created this
703 way.
</para></listitem>
706 </variablelist></refsect2>
708 <refsect2><title>Image Transfer Commands
</title><variablelist>
711 <term><command>pull-tar
</command> <replaceable>URL
</replaceable> [
<replaceable>NAME
</replaceable>]
</term>
713 <listitem><para>Downloads a
<filename>.tar
</filename>
714 container image from the specified URL, and makes it available
715 under the specified local machine name. The URL must be of
716 type
<literal>http://
</literal> or
717 <literal>https://
</literal>, and must refer to a
718 <filename>.tar
</filename>,
<filename>.tar.gz
</filename>,
719 <filename>.tar.xz
</filename> or
<filename>.tar.bz2
</filename>
720 archive file. If the local machine name is omitted, it
721 is automatically derived from the last component of the URL,
722 with its suffix removed.
</para>
724 <para>The image is verified before it is made available, unless
725 <option>--verify=no
</option> is specified.
726 Verification is done either via an inline signed file with the name
727 of the image and the suffix
<filename>.sha256
</filename> or via
728 separate
<filename>SHA256SUMS
</filename> and
729 <filename>SHA256SUMS.gpg
</filename> files.
730 The signature files need to be made available on the same web
731 server, under the same URL as the
<filename>.tar
</filename> file.
732 With
<option>--verify=checksum
</option>, only the SHA256 checksum
733 for the file is verified, based on the
<filename>.sha256
</filename>
734 suffixed file or the
<filename>SHA256SUMS
</filename> file.
735 With
<option>--verify=signature
</option>, the sha checksum file is
736 first verified with the inline signature in the
737 <filename>.sha256
</filename> file or the detached GPG signature file
738 <filename>SHA256SUMS.gpg
</filename>.
739 The public key for this verification step needs to be available in
740 <filename>/usr/lib/systemd/import-pubring.gpg
</filename> or
741 <filename>/etc/systemd/import-pubring.gpg
</filename>.
</para>
743 <para>The container image will be downloaded and stored in a
744 read-only subvolume in
745 <filename>/var/lib/machines/
</filename> that is named after
746 the specified URL and its HTTP etag. A writable snapshot is
747 then taken from this subvolume, and named after the specified
748 local name. This behavior ensures that creating multiple
749 container instances of the same URL is efficient, as multiple
750 downloads are not necessary. In order to create only the
751 read-only image, and avoid creating its writable snapshot,
752 specify
<literal>-
</literal> as local machine name.
</para>
754 <para>Note that the read-only subvolume is prefixed with
755 <filename>.tar-
</filename>, and is thus not shown by
756 <command>list-images
</command>, unless
<option>--all
</option>
759 <para>Note that pressing C-c during execution of this command
760 will not abort the download. Use
761 <command>cancel-transfer
</command>, described
762 below.
</para></listitem>
766 <term><command>pull-raw
</command> <replaceable>URL
</replaceable> [
<replaceable>NAME
</replaceable>]
</term>
768 <listitem><para>Downloads a
<filename>.raw
</filename>
769 container or VM disk image from the specified URL, and makes
770 it available under the specified local machine name. The URL
771 must be of type
<literal>http://
</literal> or
772 <literal>https://
</literal>. The container image must either
773 be a
<filename>.qcow2
</filename> or raw disk image, optionally
774 compressed as
<filename>.gz
</filename>,
775 <filename>.xz
</filename>, or
<filename>.bz2
</filename>. If the
776 local machine name is omitted, it is automatically
777 derived from the last component of the URL, with its suffix
780 <para>Image verification is identical for raw and tar images
783 <para>If the downloaded image is in
784 <filename>.qcow2
</filename> format it is converted into a raw
785 image file before it is made available.
</para>
787 <para>Downloaded images of this type will be placed as
788 read-only
<filename>.raw
</filename> file in
789 <filename>/var/lib/machines/
</filename>. A local, writable
790 (reflinked) copy is then made under the specified local
791 machine name. To omit creation of the local, writable copy
792 pass
<literal>-
</literal> as local machine name.
</para>
794 <para>Similar to the behavior of
<command>pull-tar
</command>,
795 the read-only image is prefixed with
796 <filename>.raw-
</filename>, and thus not shown by
797 <command>list-images
</command>, unless
<option>--all
</option>
800 <para>Note that pressing C-c during execution of this command
801 will not abort the download. Use
802 <command>cancel-transfer
</command>, described
803 below.
</para></listitem>
807 <term><command>import-tar
</command> <replaceable>FILE
</replaceable> [
<replaceable>NAME
</replaceable>]
</term>
808 <term><command>import-raw
</command> <replaceable>FILE
</replaceable> [
<replaceable>NAME
</replaceable>]
</term>
809 <listitem><para>Imports a TAR or RAW container or VM image,
810 and places it under the specified name in
811 <filename>/var/lib/machines/
</filename>. When
812 <command>import-tar
</command> is used, the file specified as
813 the first argument should be a tar archive, possibly compressed
814 with xz, gzip or bzip2. It will then be unpacked into its own
815 subvolume in
<filename>/var/lib/machines
</filename>. When
816 <command>import-raw
</command> is used, the file should be a
817 qcow2 or raw disk image, possibly compressed with xz, gzip or
818 bzip2. If the second argument (the resulting image name) is
819 not specified, it is automatically derived from the file
820 name. If the filename is passed as
<literal>-
</literal>, the
821 image is read from standard input, in which case the second
822 argument is mandatory.
</para>
824 <para>Both
<command>pull-tar
</command> and
<command>pull-raw
</command>
825 will resize
<filename>/var/lib/machines.raw
</filename> and the
826 filesystem therein as necessary. Optionally, the
827 <option>--read-only
</option> switch may be used to create a
828 read-only container or VM image. No cryptographic validation
829 is done when importing the images.
</para>
831 <para>Much like image downloads, ongoing imports may be listed
832 with
<command>list-transfers
</command> and aborted with
833 <command>cancel-transfer
</command>.
</para></listitem>
837 <term><command>export-tar
</command> <replaceable>NAME
</replaceable> [
<replaceable>FILE
</replaceable>]
</term>
838 <term><command>export-raw
</command> <replaceable>NAME
</replaceable> [
<replaceable>FILE
</replaceable>]
</term>
839 <listitem><para>Exports a TAR or RAW container or VM image and
840 stores it in the specified file. The first parameter should be
841 a VM or container image name. The second parameter should be a
842 file path the TAR or RAW image is written to. If the path ends
843 in
<literal>.gz
</literal>, the file is compressed with gzip, if
844 it ends in
<literal>.xz
</literal>, with xz, and if it ends in
845 <literal>.bz2
</literal>, with bzip2. If the path ends in
846 neither, the file is left uncompressed. If the second argument
847 is missing, the image is written to standard output. The
848 compression may also be explicitly selected with the
849 <option>--format=
</option> switch. This is in particular
850 useful if the second parameter is left unspecified.
</para>
852 <para>Much like image downloads and imports, ongoing exports
853 may be listed with
<command>list-transfers
</command> and
855 <command>cancel-transfer
</command>.
</para>
857 <para>Note that, currently, only directory and subvolume images
858 may be exported as TAR images, and only raw disk images as RAW
859 images.
</para></listitem>
863 <term><command>list-transfers
</command></term>
865 <listitem><para>Shows a list of container or VM image
866 downloads, imports and exports that are currently in
867 progress.
</para></listitem>
871 <term><command>cancel-transfer
</command> <replaceable>ID
</replaceable>…
</term>
873 <listitem><para>Aborts a download, import or export of the
874 container or VM image with the specified ID. To list ongoing
875 transfers and their IDs, use
876 <command>list-transfers
</command>.
</para></listitem>
879 </variablelist></refsect2>
884 <title>Machine and Image Names
</title>
886 <para>The
<command>machinectl
</command> tool operates on machines
887 and images whose names must be chosen following strict
888 rules. Machine names must be suitable for use as host names
889 following a conservative subset of DNS and UNIX/Linux
890 semantics. Specifically, they must consist of one or more
891 non-empty label strings, separated by dots. No leading or trailing
892 dots are allowed. No sequences of multiple dots are allowed. The
893 label strings may only consist of alphanumeric characters as well
894 as the dash and underscore. The maximum length of a machine name
895 is
64 characters.
</para>
897 <para>A special machine with the name
<literal>.host
</literal>
898 refers to the running host system itself. This is useful for execution
899 operations or inspecting the host system as well. Note that
900 <command>machinectl list
</command> will not show this special
901 machine unless the
<option>--all
</option> switch is specified.
</para>
903 <para>Requirements on image names are less strict, however, they must be
904 valid UTF-
8, must be suitable as file names (hence not be the
905 single or double dot, and not include a slash), and may not
906 contain control characters. Since many operations search for an
907 image by the name of a requested machine, it is recommended to name
908 images in the same strict fashion as machines.
</para>
910 <para>A special image with the name
<literal>.host
</literal>
911 refers to the image of the running host system. It hence
912 conceptually maps to the special
<literal>.host
</literal> machine
913 name described above. Note that
<command>machinectl
914 list-images
</command> will not show this special image either, unless
915 <option>--all
</option> is specified.
</para>
919 <title>Files and Directories
</title>
921 <para>Machine images are preferably stored in
922 <filename>/var/lib/machines/
</filename>, but are also searched for
923 in
<filename>/usr/local/lib/machines/
</filename> and
924 <filename>/usr/lib/machines/
</filename>. For compatibility reasons,
925 the directory
<filename>/var/lib/container/
</filename> is
926 searched, too. Note that images stored below
927 <filename>/usr
</filename> are always considered read-only. It is
928 possible to symlink machines images from other directories into
929 <filename>/var/lib/machines/
</filename> to make them available for
930 control with
<command>machinectl
</command>.
</para>
932 <para>Note that some image operations are only supported,
933 efficient or atomic on btrfs file systems. Due to this, if the
934 <command>pull-tar
</command>,
<command>pull-raw
</command>,
935 <command>import-tar
</command>,
<command>import-raw
</command> and
936 <command>set-limit
</command> commands notice that
937 <filename>/var/lib/machines
</filename> is empty and not located on
938 btrfs, they will implicitly set up a loopback file
939 <filename>/var/lib/machines.raw
</filename> containing a btrfs file
940 system that is mounted to
941 <filename>/var/lib/machines
</filename>. The size of this loopback
942 file may be controlled dynamically with
943 <command>set-limit
</command>.
</para>
945 <para>Disk images are understood by
946 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
947 and
<command>machinectl
</command> in three formats:
</para>
950 <listitem><para>A simple directory tree, containing the files
951 and directories of the container to boot.
</para></listitem>
953 <listitem><para>Subvolumes (on btrfs file systems), which are
954 similar to the simple directories, described above. However,
955 they have additional benefits, such as efficient cloning and
956 quota reporting.
</para></listitem>
958 <listitem><para>"Raw" disk images, i.e. binary images of disks
959 with a GPT or MBR partition table. Images of this type are
960 regular files with the suffix
961 <literal>.raw
</literal>.
</para></listitem>
965 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
966 for more information on image formats, in particular its
967 <option>--directory=
</option> and
<option>--image=
</option>
972 <title>Examples
</title>
974 <title>Download an Ubuntu image and open a shell in it
</title>
976 <programlisting># machinectl pull-tar https://cloud-images.ubuntu.com/trusty/current/trusty-server-cloudimg-amd64-root.tar.gz
977 # systemd-nspawn -M trusty-server-cloudimg-amd64-root
</programlisting>
979 <para>This downloads and verifies the specified
980 <filename>.tar
</filename> image, and then uses
981 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
982 to open a shell in it.
</para>
986 <title>Download a Fedora image, set a root password in it, start
987 it as service
</title>
989 <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
990 # systemd-nspawn -M Fedora-Cloud-Base-
27-
1.6.x86_64
993 # machinectl start Fedora-Cloud-Base-
27-
1.6.x86_64
994 # machinectl login Fedora-Cloud-Base-
27-
1.6.x86_64
</programlisting>
996 <para>This downloads the specified
<filename>.raw
</filename>
997 image with verification disabled. Then, a shell is opened in it
998 and a root password is set. Afterwards the shell is left, and
999 the machine started as system service. With the last command a
1000 login prompt into the container is requested.
</para>
1004 <title>Exports a container image as tar file
</title>
1006 <programlisting># machinectl export-tar fedora myfedora.tar.xz
</programlisting>
1008 <para>Exports the container
<literal>fedora
</literal> as an
1009 xz-compressed tar file
<filename>myfedora.tar.xz
</filename> into the
1010 current directory.
</para>
1014 <title>Create a new shell session
</title>
1016 <programlisting># machinectl shell --uid=lennart
</programlisting>
1018 <para>This creates a new shell session on the local host for
1019 the user ID
<literal>lennart
</literal>, in a
<citerefentry
1020 project='die-net'
><refentrytitle>su
</refentrytitle><manvolnum>1</manvolnum></citerefentry>-like
1027 <title>Exit status
</title>
1029 <para>On success,
0 is returned, a non-zero failure code
1033 <xi:include href=
"less-variables.xml" />
1036 <title>See Also
</title>
1038 <citerefentry><refentrytitle>systemd-machined.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
1039 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1040 <citerefentry><refentrytitle>systemd.special
</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1041 <citerefentry project='die-net'
><refentrytitle>tar
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1042 <citerefentry project='die-net'
><refentrytitle>xz
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1043 <citerefentry project='die-net'
><refentrytitle>gzip
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1044 <citerefentry project='die-net'
><refentrytitle>bzip2
</refentrytitle><manvolnum>1</manvolnum></citerefentry>