2 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4 <!-- SPDX-License-Identifier: LGPL-2.1+ -->
6 <refentry id=
"machinectl" conditional='ENABLE_MACHINED'
7 xmlns:
xi=
"http://www.w3.org/2001/XInclude">
10 <title>machinectl
</title>
11 <productname>systemd
</productname>
15 <refentrytitle>machinectl
</refentrytitle>
16 <manvolnum>1</manvolnum>
20 <refname>machinectl
</refname>
21 <refpurpose>Control the systemd machine manager
</refpurpose>
26 <command>machinectl
</command>
27 <arg choice=
"opt" rep=
"repeat">OPTIONS
</arg>
28 <arg choice=
"req">COMMAND
</arg>
29 <arg choice=
"opt" rep=
"repeat">NAME
</arg>
34 <title>Description
</title>
36 <para><command>machinectl
</command> may be used to introspect and
37 control the state of the
38 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
39 virtual machine and container registration manager
40 <citerefentry><refentrytitle>systemd-machined.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
</para>
42 <para><command>machinectl
</command> may be used to execute
43 operations on machines and images. Machines in this sense are
44 considered running instances of:
</para>
47 <listitem><para>Virtual Machines (VMs) that virtualize hardware
48 to run full operating system (OS) instances (including their kernels)
49 in a virtualized environment on top of the host OS.
</para></listitem>
51 <listitem><para>Containers that share the hardware and
52 OS kernel with the host OS, in order to run
53 OS userspace instances on top the host OS.
</para></listitem>
55 <listitem><para>The host system itself.
</para></listitem>
58 <para>Machines are identified by names that follow the same rules
59 as UNIX and DNS host names. For details, see below.
</para>
61 <para>Machines are instantiated from disk or file system images that
62 frequently — but not necessarily — carry the same name as machines running
63 from them. Images in this sense may be:
</para>
66 <listitem><para>Directory trees containing an OS, including the
67 top-level directories
<filename>/usr
</filename>,
68 <filename>/etc
</filename>, and so on.
</para></listitem>
70 <listitem><para>btrfs subvolumes containing OS trees, similar to regular directory trees.
</para></listitem>
72 <listitem><para>Binary
"raw" disk image files containing MBR or GPT partition tables and Linux file
73 systems.
</para></listitem>
75 <listitem><para>Similarly, block devices containing MBR or GPT partition tables and file systems.
</para></listitem>
77 <listitem><para>The file system tree of the host OS itself.
</para></listitem>
83 <title>Options
</title>
85 <para>The following options are understood:
</para>
89 <term><option>-p
</option></term>
90 <term><option>--property=
</option></term>
92 <listitem><para>When showing machine or image properties,
93 limit the output to certain properties as specified by the
94 argument. If not specified, all set properties are shown. The
95 argument should be a property name, such as
96 <literal>Name
</literal>. If specified more than once, all
97 properties with the specified names are
98 shown.
</para></listitem>
102 <term><option>-a
</option></term>
103 <term><option>--all
</option></term>
105 <listitem><para>When showing machine or image properties, show
106 all properties regardless of whether they are set or
109 <para>When listing VM or container images, do not suppress
110 images beginning in a dot character
111 (
<literal>.
</literal>).
</para>
113 <para>When cleaning VM or container images, remove all images, not just hidden ones.
</para></listitem>
117 <term><option>--value
</option></term>
119 <listitem><para>When printing properties with
<command>show
</command>, only print the value,
120 and skip the property name and
<literal>=
</literal>.
</para></listitem>
124 <term><option>-l
</option></term>
125 <term><option>--full
</option></term>
127 <listitem><para>Do not ellipsize process tree entries.
</para>
132 <term><option>--kill-who=
</option></term>
134 <listitem><para>When used with
<command>kill
</command>, choose
135 which processes to kill. Must be one of
136 <option>leader
</option>, or
<option>all
</option> to select
137 whether to kill only the leader process of the machine or all
138 processes of the machine. If omitted, defaults to
139 <option>all
</option>.
</para></listitem>
143 <term><option>-s
</option></term>
144 <term><option>--signal=
</option></term>
146 <listitem><para>When used with
<command>kill
</command>, choose
147 which signal to send to selected processes. Must be one of the
148 well-known signal specifiers, such as
149 <constant>SIGTERM
</constant>,
<constant>SIGINT
</constant> or
150 <constant>SIGSTOP
</constant>. If omitted, defaults to
151 <constant>SIGTERM
</constant>.
</para></listitem>
155 <term><option>--uid=
</option></term>
157 <listitem><para>When used with the
<command>shell
</command> command, chooses the user ID to
158 open the interactive shell session as. If the argument to the
<command>shell
</command>
159 command also specifies a user name, this option is ignored. If the name is not specified
160 in either way,
<literal>root
</literal> will be used by default. Note that this switch is
161 not supported for the
<command>login
</command> command (see below).
</para></listitem>
165 <term><option>-E
<replaceable>NAME
</replaceable>=
<replaceable>VALUE
</replaceable></option></term>
166 <term><option>--setenv=
<replaceable>NAME
</replaceable>=
<replaceable>VALUE
</replaceable></option></term>
168 <listitem><para>When used with the
<command>shell
</command> command, sets an environment
169 variable to pass to the executed shell. Takes an environment variable name and value,
170 separated by
<literal>=
</literal>. This switch may be used multiple times to set multiple
171 environment variables. Note that this switch is not supported for the
172 <command>login
</command> command (see below).
</para></listitem>
176 <term><option>--mkdir
</option></term>
178 <listitem><para>When used with
<command>bind
</command>, creates the destination file or directory before
179 applying the bind mount. Note that even though the name of this option suggests that it is suitable only for
180 directories, this option also creates the destination file node to mount over if the object to mount is not
181 a directory, but a regular file, device node, socket or FIFO.
</para></listitem>
185 <term><option>--read-only
</option></term>
187 <listitem><para>When used with
<command>bind
</command>, creates a read-only bind mount.
</para>
189 <para>When used with
<command>clone
</command>,
<command>import-raw
</command> or
<command>import-tar
</command> a
190 read-only container or VM image is created.
</para></listitem>
194 <term><option>-n
</option></term>
195 <term><option>--lines=
</option></term>
197 <listitem><para>When used with
<command>status
</command>,
198 controls the number of journal lines to show, counting from
199 the most recent ones. Takes a positive integer argument.
200 Defaults to
10.
</para>
205 <term><option>-o
</option></term>
206 <term><option>--output=
</option></term>
208 <listitem><para>When used with
<command>status
</command>,
209 controls the formatting of the journal entries that are shown.
210 For the available choices, see
211 <citerefentry><refentrytitle>journalctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
212 Defaults to
<literal>short
</literal>.
</para></listitem>
216 <term><option>--verify=
</option></term>
218 <listitem><para>When downloading a container or VM image,
219 specify whether the image shall be verified before it is made
220 available. Takes one of
<literal>no
</literal>,
221 <literal>checksum
</literal> and
<literal>signature
</literal>.
222 If
<literal>no
</literal>, no verification is done. If
223 <literal>checksum
</literal> is specified, the download is
224 checked for integrity after the transfer is complete, but no
225 signatures are verified. If
<literal>signature
</literal> is
226 specified, the checksum is verified and the image's signature
227 is checked against a local keyring of trustable vendors. It is
228 strongly recommended to set this option to
229 <literal>signature
</literal> if the server and protocol
230 support this. Defaults to
231 <literal>signature
</literal>.
</para></listitem>
235 <term><option>--force
</option></term>
237 <listitem><para>When downloading a container or VM image, and
238 a local copy by the specified local machine name already
239 exists, delete it first and replace it by the newly downloaded
240 image.
</para></listitem>
244 <term><option>--format=
</option></term>
246 <listitem><para>When used with the
<option>export-tar
</option>
247 or
<option>export-raw
</option> commands, specifies the
248 compression format to use for the resulting file. Takes one of
249 <literal>uncompressed
</literal>,
<literal>xz
</literal>,
250 <literal>gzip
</literal>,
<literal>bzip2
</literal>. By default,
251 the format is determined automatically from the image file
252 name passed.
</para></listitem>
256 <term><option>--max-addresses=
</option></term>
258 <listitem><para>When used with the
<option>list-machines
</option>
259 command, limits the number of ip addresses output for every machine.
260 Defaults to
1. All addresses can be requested with
<literal>all
</literal>
261 as argument to
<option>--max-addresses
</option> . If the argument to
262 <option>--max-addresses
</option> is less than the actual number
263 of addresses,
<literal>...
</literal>follows the last address.
264 If multiple addresses are to be written for a given machine, every
265 address except the first one is on a new line and is followed by
266 <literal>,
</literal> if another address will be output afterwards.
</para></listitem>
270 <term><option>-q
</option></term>
271 <term><option>--quiet
</option></term>
273 <listitem><para>Suppresses additional informational output while running.
</para></listitem>
276 <xi:include href=
"user-system-options.xml" xpointer=
"host" />
279 <term><option>-M
</option></term>
280 <term><option>--machine=
</option></term>
282 <listitem><para>Connect to
283 <citerefentry><refentrytitle>systemd-machined.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
284 running in a local container, to perform the specified operation within
285 the container.
</para></listitem>
288 <xi:include href=
"standard-options.xml" xpointer=
"no-pager" />
289 <xi:include href=
"standard-options.xml" xpointer=
"no-legend" />
290 <xi:include href=
"standard-options.xml" xpointer=
"no-ask-password" />
291 <xi:include href=
"standard-options.xml" xpointer=
"help" />
292 <xi:include href=
"standard-options.xml" xpointer=
"version" />
297 <title>Commands
</title>
299 <para>The following commands are understood:
</para>
301 <refsect2><title>Machine Commands
</title><variablelist>
304 <term><command>list
</command></term>
306 <listitem><para>List currently running (online) virtual
307 machines and containers. To enumerate machine images that can
308 be started, use
<command>list-images
</command> (see
309 below). Note that this command hides the special
310 <literal>.host
</literal> machine by default. Use the
311 <option>--all
</option> switch to show it.
</para></listitem>
315 <term><command>status
</command> <replaceable>NAME
</replaceable>…
</term>
317 <listitem><para>Show runtime status information about
318 one or more virtual machines and containers, followed by the
319 most recent log data from the journal. This function is
320 intended to generate human-readable output. If you are looking
321 for computer-parsable output, use
<command>show
</command>
322 instead. Note that the log data shown is reported by the
323 virtual machine or container manager, and frequently contains
324 console output of the machine, but not necessarily journal
325 contents of the machine itself.
</para></listitem>
329 <term><command>show
</command> [
<replaceable>NAME
</replaceable>…]
</term>
331 <listitem><para>Show properties of one or more registered virtual machines or containers or the manager
332 itself. If no argument is specified, properties of the manager will be shown. If a NAME is specified,
333 properties of this virtual machine or container are shown. By default, empty properties are suppressed. Use
334 <option>--all
</option> to show those too. To select specific properties to show, use
335 <option>--property=
</option>. This command is intended to be used whenever computer-parsable output is
336 required, and does not print the control group tree or journal entries. Use
<command>status
</command> if you
337 are looking for formatted human-readable output.
</para></listitem>
341 <term><command>start
</command> <replaceable>NAME
</replaceable>…
</term>
343 <listitem><para>Start a container as a system service, using
344 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
345 This starts
<filename>systemd-nspawn@.service
</filename>,
346 instantiated for the specified machine name, similar to the
347 effect of
<command>systemctl start
</command> on the service
348 name.
<command>systemd-nspawn
</command> looks for a container
349 image by the specified name in
350 <filename>/var/lib/machines/
</filename> (and other search
351 paths, see below) and runs it. Use
352 <command>list-images
</command> (see below) for listing
353 available container images to start.
</para>
356 <citerefentry><refentrytitle>systemd-machined.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
357 also interfaces with a variety of other container and VM
358 managers,
<command>systemd-nspawn
</command> is just one
359 implementation of it. Most of the commands available in
360 <command>machinectl
</command> may be used on containers or VMs
361 controlled by other managers, not just
362 <command>systemd-nspawn
</command>. Starting VMs and container
363 images on those managers requires manager-specific
366 <para>To interactively start a container on the command line
367 with full access to the container's console, please invoke
368 <command>systemd-nspawn
</command> directly. To stop a running
369 container use
<command>machinectl poweroff
</command>.
</para></listitem>
373 <term><command>login
</command> [
<replaceable>NAME
</replaceable>]
</term>
375 <listitem><para>Open an interactive terminal login session in
376 a container or on the local host. If an argument is supplied,
377 it refers to the container machine to connect to. If none is
378 specified, or the container name is specified as the empty
379 string, or the special machine name
<literal>.host
</literal>
380 (see below) is specified, the connection is made to the local
381 host instead. This will create a TTY connection to a specific
382 container or the local host and asks for the execution of a
383 getty on it. Note that this is only supported for containers
385 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
386 as init system.
</para>
388 <para>This command will open a full login prompt on the
389 container or the local host, which then asks for username and
390 password. Use
<command>shell
</command> (see below) or
391 <citerefentry><refentrytitle>systemd-run
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
392 with the
<option>--machine=
</option> switch to directly invoke
393 a single command, either interactively or in the
394 background.
</para></listitem>
398 <term><command>shell
</command> [[
<replaceable>NAME
</replaceable>@]
<replaceable>NAME
</replaceable> [
<replaceable>PATH
</replaceable> [
<replaceable>ARGUMENTS
</replaceable>…]]]
</term>
400 <listitem><para>Open an interactive shell session in a
401 container or on the local host. The first argument refers to
402 the container machine to connect to. If none is specified, or
403 the machine name is specified as the empty string, or the
404 special machine name
<literal>.host
</literal> (see below) is
405 specified, the connection is made to the local host
406 instead. This works similar to
<command>login
</command> but
407 immediately invokes a user process. This command runs the
408 specified executable with the specified arguments, or the
409 default shell for the user if none is specified, or
410 <filename>/bin/sh
</filename> if no default shell is found. By default,
411 <option>--uid=
</option>, or by prefixing the machine name with
412 a username and an
<literal>@
</literal> character, a different
413 user may be selected. Use
<option>--setenv=
</option> to set
414 environment variables for the executed process.
</para>
416 <para>Note that
<command>machinectl shell
</command> does not propagate the exit code/status of the invoked
417 shell process. Use
<command>systemd-run
</command> instead if that information is required (see below).
</para>
419 <para>When using the
<command>shell
</command> command without
420 arguments, (thus invoking the executed shell or command on the
421 local host), it is in many ways similar to a
<citerefentry
422 project='die-net'
><refentrytitle>su
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
423 session, but, unlike
<command>su
</command>, completely isolates
424 the new session from the originating session, so that it
425 shares no process or session properties, and is in a clean and
426 well-defined state. It will be tracked in a new utmp, login,
427 audit, security and keyring session, and will not inherit any
428 environment variables or resource limits, among other
431 <para>Note that
<citerefentry><refentrytitle>systemd-run
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
432 with its
<option>--machine=
</option> switch may be used in place of the
<command>machinectl shell
</command>
433 command, and allows non-interactive operation, more detailed and low-level configuration of the invoked unit,
434 as well as access to runtime and exit code/status information of the invoked shell process. In particular, use
435 <command>systemd-run
</command>'s
<option>--wait
</option> switch to propagate exit status information of the
436 invoked process. Use
<command>systemd-run
</command>'s
<option>--pty
</option> switch for acquiring an
437 interactive shell, similar to
<command>machinectl shell
</command>. In general,
<command>systemd-run
</command>
438 is preferable for scripting purposes. However, note that
<command>systemd-run
</command> might require higher
439 privileges than
<command>machinectl shell
</command>.
</para></listitem>
443 <term><command>enable
</command> <replaceable>NAME
</replaceable>…
</term>
444 <term><command>disable
</command> <replaceable>NAME
</replaceable>…
</term>
446 <listitem><para>Enable or disable a container as a system
447 service to start at system boot, using
448 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
449 This enables or disables
450 <filename>systemd-nspawn@.service
</filename>, instantiated for
451 the specified machine name, similar to the effect of
452 <command>systemctl enable
</command> or
<command>systemctl
453 disable
</command> on the service name.
</para></listitem>
457 <term><command>poweroff
</command> <replaceable>NAME
</replaceable>…
</term>
459 <listitem><para>Power off one or more containers. This will
460 trigger a reboot by sending SIGRTMIN+
4 to the container's init
461 process, which causes systemd-compatible init systems to shut
462 down cleanly. Use
<command>stop
</command> as alias for
<command>poweroff
</command>.
463 This operation does not work on containers that do not run a
464 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>-compatible
465 init system, such as sysvinit. Use
466 <command>terminate
</command> (see below) to immediately
467 terminate a container or VM, without cleanly shutting it
468 down.
</para></listitem>
472 <term><command>reboot
</command> <replaceable>NAME
</replaceable>…
</term>
474 <listitem><para>Reboot one or more containers. This will
475 trigger a reboot by sending SIGINT to the container's init
476 process, which is roughly equivalent to pressing Ctrl+Alt+Del
477 on a non-containerized system, and is compatible with
478 containers running any system manager.
</para></listitem>
482 <term><command>terminate
</command> <replaceable>NAME
</replaceable>…
</term>
484 <listitem><para>Immediately terminates a virtual machine or
485 container, without cleanly shutting it down. This kills all
486 processes of the virtual machine or container and deallocates
487 all resources attached to that instance. Use
488 <command>poweroff
</command> to issue a clean shutdown
489 request.
</para></listitem>
493 <term><command>kill
</command> <replaceable>NAME
</replaceable>…
</term>
495 <listitem><para>Send a signal to one or more processes of the
496 virtual machine or container. This means processes as seen by
497 the host, not the processes inside the virtual machine or
498 container. Use
<option>--kill-who=
</option> to select which
499 process to kill. Use
<option>--signal=
</option> to select the
500 signal to send.
</para></listitem>
504 <term><command>bind
</command> <replaceable>NAME
</replaceable> <replaceable>PATH
</replaceable> [
<replaceable>PATH
</replaceable>]
</term>
506 <listitem><para>Bind mounts a file or directory from the host into the specified container. The first path
507 argument is the source file or directory on the host, the second path argument is the destination file or
508 directory in the container. When the latter is omitted, the destination path in the container is the same as
509 the source path on the host. When combined with the
<option>--read-only
</option> switch, a ready-only bind
510 mount is created. When combined with the
<option>--mkdir
</option> switch, the destination path is first created
511 before the mount is applied. Note that this option is currently only supported for
512 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry> containers,
513 and only if user namespacing (
<option>--private-users
</option>) is not used. This command supports bind
514 mounting directories, regular files, device nodes,
<constant>AF_UNIX
</constant> socket nodes, as well as
515 FIFOs.
</para></listitem>
519 <term><command>copy-to
</command> <replaceable>NAME
</replaceable> <replaceable>PATH
</replaceable> [
<replaceable>PATH
</replaceable>]
</term>
521 <listitem><para>Copies files or directories from the host
522 system into a running container. Takes a container name,
523 followed by the source path on the host and the destination
524 path in the container. If the destination path is omitted, the
525 same as the source path is used.
</para>
527 <para>If host and container share the same user and group namespace, file ownership by numeric user ID and
528 group ID is preserved for the copy, otherwise all files and directories in the copy will be owned by the root
529 user and group (UID/GID
0).
</para></listitem>
533 <term><command>copy-from
</command> <replaceable>NAME
</replaceable> <replaceable>PATH
</replaceable> [
<replaceable>PATH
</replaceable>]
</term>
535 <listitem><para>Copies files or directories from a container
536 into the host system. Takes a container name, followed by the
537 source path in the container the destination path on the host.
538 If the destination path is omitted, the same as the source path
541 <para>If host and container share the same user and group namespace, file ownership by numeric user ID and
542 group ID is preserved for the copy, otherwise all files and directories in the copy will be owned by the root
543 user and group (UID/GID
0).
</para></listitem>
545 </variablelist></refsect2>
547 <refsect2><title>Image Commands
</title><variablelist>
550 <term><command>list-images
</command></term>
552 <listitem><para>Show a list of locally installed container and
553 VM images. This enumerates all raw disk images and container
554 directories and subvolumes in
555 <filename>/var/lib/machines/
</filename> (and other search
556 paths, see below). Use
<command>start
</command> (see above) to
557 run a container off one of the listed images. Note that, by
558 default, containers whose name begins with a dot
559 (
<literal>.
</literal>) are not shown. To show these too,
560 specify
<option>--all
</option>. Note that a special image
561 <literal>.host
</literal> always implicitly exists and refers
562 to the image the host itself is booted from.
</para></listitem>
566 <term><command>image-status
</command> [
<replaceable>NAME
</replaceable>…]
</term>
568 <listitem><para>Show terse status information about one or
569 more container or VM images. This function is intended to
570 generate human-readable output. Use
571 <command>show-image
</command> (see below) to generate
572 computer-parsable output instead.
</para></listitem>
576 <term><command>show-image
</command> [
<replaceable>NAME
</replaceable>…]
</term>
578 <listitem><para>Show properties of one or more registered
579 virtual machine or container images, or the manager itself. If
580 no argument is specified, properties of the manager will be
581 shown. If a NAME is specified, properties of this virtual
582 machine or container image are shown. By default, empty
583 properties are suppressed. Use
<option>--all
</option> to show
584 those too. To select specific properties to show, use
585 <option>--property=
</option>. This command is intended to be
586 used whenever computer-parsable output is required. Use
587 <command>image-status
</command> if you are looking for
588 formatted human-readable output.
</para></listitem>
592 <term><command>clone
</command> <replaceable>NAME
</replaceable> <replaceable>NAME
</replaceable></term>
594 <listitem><para>Clones a container or VM image. The arguments specify the name of the image to clone and the
595 name of the newly cloned image. Note that plain directory container images are cloned into btrfs subvolume
596 images with this command, if the underlying file system supports this. Note that cloning a container or VM
597 image is optimized for file systems that support copy-on-write, and might not be efficient on others, due to
598 file system limitations.
</para>
600 <para>Note that this command leaves host name, machine ID and
601 all other settings that could identify the instance
602 unmodified. The original image and the cloned copy will hence
603 share these credentials, and it might be necessary to manually
604 change them in the copy.
</para>
606 <para>If combined with the
<option>--read-only
</option> switch a read-only cloned image is
607 created.
</para></listitem>
611 <term><command>rename
</command> <replaceable>NAME
</replaceable> <replaceable>NAME
</replaceable></term>
613 <listitem><para>Renames a container or VM image. The
614 arguments specify the name of the image to rename and the new
615 name of the image.
</para></listitem>
619 <term><command>read-only
</command> <replaceable>NAME
</replaceable> [
<replaceable>BOOL
</replaceable>]
</term>
621 <listitem><para>Marks or (unmarks) a container or VM image
622 read-only. Takes a VM or container image name, followed by a
623 boolean as arguments. If the boolean is omitted, positive is
624 implied, i.e. the image is marked read-only.
</para></listitem>
628 <term><command>remove
</command> <replaceable>NAME
</replaceable>…
</term>
630 <listitem><para>Removes one or more container or VM images.
631 The special image
<literal>.host
</literal>, which refers to
632 the host's own directory tree, may not be
633 removed.
</para></listitem>
637 <term><command>set-limit
</command> [
<replaceable>NAME
</replaceable>]
<replaceable>BYTES
</replaceable></term>
639 <listitem><para>Sets the maximum size in bytes that a specific
640 container or VM image, or all images, may grow up to on disk
641 (disk quota). Takes either one or two parameters. The first,
642 optional parameter refers to a container or VM image name. If
643 specified, the size limit of the specified image is changed. If
644 omitted, the overall size limit of the sum of all images stored
645 locally is changed. The final argument specifies the size
646 limit in bytes, possibly suffixed by the usual K, M, G, T
647 units. If the size limit shall be disabled, specify
648 <literal>-
</literal> as size.
</para>
650 <para>Note that per-container size limits are only supported on btrfs file systems.
</para></listitem>
654 <term><command>clean
</command></term>
656 <listitem><para>Remove hidden VM or container images (or all). This command removes all hidden machine images
657 from
<filename>/var/lib/machines
</filename>, i.e. those whose name begins with a dot. Use
<command>machinectl
658 list-images --all
</command> to see a list of all machine images, including the hidden ones.
</para>
660 <para>When combined with the
<option>--all
</option> switch removes all images, not just hidden ones. This
661 command effectively empties
<filename>/var/lib/machines
</filename>.
</para>
663 <para>Note that commands such as
<command>machinectl pull-tar
</command> or
<command>machinectl
664 pull-raw
</command> usually create hidden, read-only, unmodified machine images from the downloaded image first,
665 before cloning a writable working copy of it, in order to avoid duplicate downloads in case of images that are
666 reused multiple times. Use
<command>machinectl clean
</command> to remove old, hidden images created this
667 way.
</para></listitem>
670 </variablelist></refsect2>
672 <refsect2><title>Image Transfer Commands
</title><variablelist>
675 <term><command>pull-tar
</command> <replaceable>URL
</replaceable> [
<replaceable>NAME
</replaceable>]
</term>
677 <listitem><para>Downloads a
<filename>.tar
</filename>
678 container image from the specified URL, and makes it available
679 under the specified local machine name. The URL must be of
680 type
<literal>http://
</literal> or
681 <literal>https://
</literal>, and must refer to a
682 <filename>.tar
</filename>,
<filename>.tar.gz
</filename>,
683 <filename>.tar.xz
</filename> or
<filename>.tar.bz2
</filename>
684 archive file. If the local machine name is omitted, it
685 is automatically derived from the last component of the URL,
686 with its suffix removed.
</para>
688 <para>The image is verified before it is made available, unless
689 <option>--verify=no
</option> is specified.
690 Verification is done either via an inline signed file with the name
691 of the image and the suffix
<filename>.sha256
</filename> or via
692 separate
<filename>SHA256SUMS
</filename> and
693 <filename>SHA256SUMS.gpg
</filename> files.
694 The signature files need to be made available on the same web
695 server, under the same URL as the
<filename>.tar
</filename> file.
696 With
<option>--verify=checksum
</option>, only the SHA256 checksum
697 for the file is verified, based on the
<filename>.sha256
</filename>
698 suffixed file or the
<filename>SHA256SUMS
</filename> file.
699 With
<option>--verify=signature
</option>, the sha checksum file is
700 first verified with the inline signature in the
701 <filename>.sha256
</filename> file or the detached GPG signature file
702 <filename>SHA256SUMS.gpg
</filename>.
703 The public key for this verification step needs to be available in
704 <filename>/usr/lib/systemd/import-pubring.gpg
</filename> or
705 <filename>/etc/systemd/import-pubring.gpg
</filename>.
</para>
707 <para>The container image will be downloaded and stored in a
708 read-only subvolume in
709 <filename>/var/lib/machines/
</filename> that is named after
710 the specified URL and its HTTP etag. A writable snapshot is
711 then taken from this subvolume, and named after the specified
712 local name. This behavior ensures that creating multiple
713 container instances of the same URL is efficient, as multiple
714 downloads are not necessary. In order to create only the
715 read-only image, and avoid creating its writable snapshot,
716 specify
<literal>-
</literal> as local machine name.
</para>
718 <para>Note that the read-only subvolume is prefixed with
719 <filename>.tar-
</filename>, and is thus not shown by
720 <command>list-images
</command>, unless
<option>--all
</option>
723 <para>Note that pressing C-c during execution of this command
724 will not abort the download. Use
725 <command>cancel-transfer
</command>, described
726 below.
</para></listitem>
730 <term><command>pull-raw
</command> <replaceable>URL
</replaceable> [
<replaceable>NAME
</replaceable>]
</term>
732 <listitem><para>Downloads a
<filename>.raw
</filename>
733 container or VM disk image from the specified URL, and makes
734 it available under the specified local machine name. The URL
735 must be of type
<literal>http://
</literal> or
736 <literal>https://
</literal>. The container image must either
737 be a
<filename>.qcow2
</filename> or raw disk image, optionally
738 compressed as
<filename>.gz
</filename>,
739 <filename>.xz
</filename>, or
<filename>.bz2
</filename>. If the
740 local machine name is omitted, it is automatically
741 derived from the last component of the URL, with its suffix
744 <para>Image verification is identical for raw and tar images
747 <para>If the downloaded image is in
748 <filename>.qcow2
</filename> format it is converted into a raw
749 image file before it is made available.
</para>
751 <para>Downloaded images of this type will be placed as
752 read-only
<filename>.raw
</filename> file in
753 <filename>/var/lib/machines/
</filename>. A local, writable
754 (reflinked) copy is then made under the specified local
755 machine name. To omit creation of the local, writable copy
756 pass
<literal>-
</literal> as local machine name.
</para>
758 <para>Similar to the behavior of
<command>pull-tar
</command>,
759 the read-only image is prefixed with
760 <filename>.raw-
</filename>, and thus not shown by
761 <command>list-images
</command>, unless
<option>--all
</option>
764 <para>Note that pressing C-c during execution of this command
765 will not abort the download. Use
766 <command>cancel-transfer
</command>, described
767 below.
</para></listitem>
771 <term><command>import-tar
</command> <replaceable>FILE
</replaceable> [
<replaceable>NAME
</replaceable>]
</term>
772 <term><command>import-raw
</command> <replaceable>FILE
</replaceable> [
<replaceable>NAME
</replaceable>]
</term>
773 <listitem><para>Imports a TAR or RAW container or VM image,
774 and places it under the specified name in
775 <filename>/var/lib/machines/
</filename>. When
776 <command>import-tar
</command> is used, the file specified as
777 the first argument should be a tar archive, possibly compressed
778 with xz, gzip or bzip2. It will then be unpacked into its own
779 subvolume in
<filename>/var/lib/machines
</filename>. When
780 <command>import-raw
</command> is used, the file should be a
781 qcow2 or raw disk image, possibly compressed with xz, gzip or
782 bzip2. If the second argument (the resulting image name) is
783 not specified, it is automatically derived from the file
784 name. If the filename is passed as
<literal>-
</literal>, the
785 image is read from standard input, in which case the second
786 argument is mandatory.
</para>
788 <para>Optionally, the
<option>--read-only
</option> switch may be used to create a read-only container or VM
789 image. No cryptographic validation is done when importing the images.
</para>
791 <para>Much like image downloads, ongoing imports may be listed
792 with
<command>list-transfers
</command> and aborted with
793 <command>cancel-transfer
</command>.
</para></listitem>
797 <term><command>import-fs
</command> <replaceable>DIRECTORY
</replaceable> [
<replaceable>NAME
</replaceable>]
</term>
799 <listitem><para>Imports a container image stored in a local directory into
800 <filename>/var/lib/machines/
</filename>, operates similar to
<command>import-tar
</command> or
801 <command>import-raw
</command>, but the first argument is the source directory. If supported, this command will
802 create btrfs snapshot or subvolume for the new image.
</para></listitem>
806 <term><command>export-tar
</command> <replaceable>NAME
</replaceable> [
<replaceable>FILE
</replaceable>]
</term>
807 <term><command>export-raw
</command> <replaceable>NAME
</replaceable> [
<replaceable>FILE
</replaceable>]
</term>
808 <listitem><para>Exports a TAR or RAW container or VM image and
809 stores it in the specified file. The first parameter should be
810 a VM or container image name. The second parameter should be a
811 file path the TAR or RAW image is written to. If the path ends
812 in
<literal>.gz
</literal>, the file is compressed with gzip, if
813 it ends in
<literal>.xz
</literal>, with xz, and if it ends in
814 <literal>.bz2
</literal>, with bzip2. If the path ends in
815 neither, the file is left uncompressed. If the second argument
816 is missing, the image is written to standard output. The
817 compression may also be explicitly selected with the
818 <option>--format=
</option> switch. This is in particular
819 useful if the second parameter is left unspecified.
</para>
821 <para>Much like image downloads and imports, ongoing exports
822 may be listed with
<command>list-transfers
</command> and
824 <command>cancel-transfer
</command>.
</para>
826 <para>Note that, currently, only directory and subvolume images
827 may be exported as TAR images, and only raw disk images as RAW
828 images.
</para></listitem>
832 <term><command>list-transfers
</command></term>
834 <listitem><para>Shows a list of container or VM image
835 downloads, imports and exports that are currently in
836 progress.
</para></listitem>
840 <term><command>cancel-transfer
</command> <replaceable>ID
</replaceable>…
</term>
842 <listitem><para>Aborts a download, import or export of the
843 container or VM image with the specified ID. To list ongoing
844 transfers and their IDs, use
845 <command>list-transfers
</command>.
</para></listitem>
848 </variablelist></refsect2>
853 <title>Machine and Image Names
</title>
855 <para>The
<command>machinectl
</command> tool operates on machines
856 and images whose names must be chosen following strict
857 rules. Machine names must be suitable for use as host names
858 following a conservative subset of DNS and UNIX/Linux
859 semantics. Specifically, they must consist of one or more
860 non-empty label strings, separated by dots. No leading or trailing
861 dots are allowed. No sequences of multiple dots are allowed. The
862 label strings may only consist of alphanumeric characters as well
863 as the dash and underscore. The maximum length of a machine name
864 is
64 characters.
</para>
866 <para>A special machine with the name
<literal>.host
</literal>
867 refers to the running host system itself. This is useful for execution
868 operations or inspecting the host system as well. Note that
869 <command>machinectl list
</command> will not show this special
870 machine unless the
<option>--all
</option> switch is specified.
</para>
872 <para>Requirements on image names are less strict, however, they must be
873 valid UTF-
8, must be suitable as file names (hence not be the
874 single or double dot, and not include a slash), and may not
875 contain control characters. Since many operations search for an
876 image by the name of a requested machine, it is recommended to name
877 images in the same strict fashion as machines.
</para>
879 <para>A special image with the name
<literal>.host
</literal>
880 refers to the image of the running host system. It hence
881 conceptually maps to the special
<literal>.host
</literal> machine
882 name described above. Note that
<command>machinectl
883 list-images
</command> will not show this special image either, unless
884 <option>--all
</option> is specified.
</para>
888 <title>Files and Directories
</title>
890 <para>Machine images are preferably stored in
891 <filename>/var/lib/machines/
</filename>, but are also searched for
892 in
<filename>/usr/local/lib/machines/
</filename> and
893 <filename>/usr/lib/machines/
</filename>. For compatibility reasons,
894 the directory
<filename>/var/lib/container/
</filename> is
895 searched, too. Note that images stored below
896 <filename>/usr
</filename> are always considered read-only. It is
897 possible to symlink machines images from other directories into
898 <filename>/var/lib/machines/
</filename> to make them available for
899 control with
<command>machinectl
</command>.
</para>
901 <para>Note that some image operations are only supported, efficient or atomic on btrfs file systems.
</para>
903 <para>Disk images are understood by
904 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
905 and
<command>machinectl
</command> in three formats:
</para>
908 <listitem><para>A simple directory tree, containing the files
909 and directories of the container to boot.
</para></listitem>
911 <listitem><para>Subvolumes (on btrfs file systems), which are
912 similar to the simple directories, described above. However,
913 they have additional benefits, such as efficient cloning and
914 quota reporting.
</para></listitem>
916 <listitem><para>"Raw" disk images, i.e. binary images of disks
917 with a GPT or MBR partition table. Images of this type are
918 regular files with the suffix
919 <literal>.raw
</literal>.
</para></listitem>
923 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
924 for more information on image formats, in particular its
925 <option>--directory=
</option> and
<option>--image=
</option>
930 <title>Examples
</title>
932 <title>Download an Ubuntu image and open a shell in it
</title>
934 <programlisting># machinectl pull-tar https://cloud-images.ubuntu.com/trusty/current/trusty-server-cloudimg-amd64-root.tar.gz
935 # systemd-nspawn -M trusty-server-cloudimg-amd64-root
</programlisting>
937 <para>This downloads and verifies the specified
938 <filename>.tar
</filename> image, and then uses
939 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
940 to open a shell in it.
</para>
944 <title>Download a Fedora image, set a root password in it, start
945 it as service
</title>
947 <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
948 # systemd-nspawn -M Fedora-Cloud-Base-
27-
1.6.x86_64
951 # machinectl start Fedora-Cloud-Base-
27-
1.6.x86_64
952 # machinectl login Fedora-Cloud-Base-
27-
1.6.x86_64
</programlisting>
954 <para>This downloads the specified
<filename>.raw
</filename>
955 image with verification disabled. Then, a shell is opened in it
956 and a root password is set. Afterwards the shell is left, and
957 the machine started as system service. With the last command a
958 login prompt into the container is requested.
</para>
962 <title>Exports a container image as tar file
</title>
964 <programlisting># machinectl export-tar fedora myfedora.tar.xz
</programlisting>
966 <para>Exports the container
<literal>fedora
</literal> as an
967 xz-compressed tar file
<filename>myfedora.tar.xz
</filename> into the
968 current directory.
</para>
972 <title>Create a new shell session
</title>
974 <programlisting># machinectl shell --uid=lennart
</programlisting>
976 <para>This creates a new shell session on the local host for
977 the user ID
<literal>lennart
</literal>, in a
<citerefentry
978 project='die-net'
><refentrytitle>su
</refentrytitle><manvolnum>1</manvolnum></citerefentry>-like
985 <title>Exit status
</title>
987 <para>On success,
0 is returned, a non-zero failure code
991 <xi:include href=
"less-variables.xml" />
994 <title>See Also
</title>
996 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
997 <citerefentry><refentrytitle>systemd-machined.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
998 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
999 <citerefentry><refentrytitle>systemd.special
</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1000 <citerefentry project='die-net'
><refentrytitle>tar
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1001 <citerefentry project='die-net'
><refentrytitle>xz
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1002 <citerefentry project='die-net'
><refentrytitle>gzip
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1003 <citerefentry project='die-net'
><refentrytitle>bzip2
</refentrytitle><manvolnum>1</manvolnum></citerefentry>