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+
9 <refentry id=
"machinectl" conditional='ENABLE_MACHINED'
10 xmlns:
xi=
"http://www.w3.org/2001/XInclude">
13 <title>machinectl
</title>
14 <productname>systemd
</productname>
18 <refentrytitle>machinectl
</refentrytitle>
19 <manvolnum>1</manvolnum>
23 <refname>machinectl
</refname>
24 <refpurpose>Control the systemd machine manager
</refpurpose>
29 <command>machinectl
</command>
30 <arg choice=
"opt" rep=
"repeat">OPTIONS
</arg>
31 <arg choice=
"req">COMMAND
</arg>
32 <arg choice=
"opt" rep=
"repeat">NAME
</arg>
37 <title>Description
</title>
39 <para><command>machinectl
</command> may be used to introspect and
40 control the state of the
41 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
42 virtual machine and container registration manager
43 <citerefentry><refentrytitle>systemd-machined.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
</para>
45 <para><command>machinectl
</command> may be used to execute
46 operations on machines and images. Machines in this sense are
47 considered running instances of:
</para>
50 <listitem><para>Virtual Machines (VMs) that virtualize hardware
51 to run full operating system (OS) instances (including their kernels)
52 in a virtualized environment on top of the host OS.
</para></listitem>
54 <listitem><para>Containers that share the hardware and
55 OS kernel with the host OS, in order to run
56 OS userspace instances on top the host OS.
</para></listitem>
58 <listitem><para>The host system itself.
</para></listitem>
61 <para>Machines are identified by names that follow the same rules
62 as UNIX and DNS host names. For details, see below.
</para>
64 <para>Machines are instantiated from disk or file system images that
65 frequently — but not necessarily — carry the same name as machines running
66 from them. Images in this sense may be:
</para>
69 <listitem><para>Directory trees containing an OS, including the
70 top-level directories
<filename>/usr
</filename>,
71 <filename>/etc
</filename>, and so on.
</para></listitem>
73 <listitem><para>btrfs subvolumes containing OS trees, similar to regular directory trees.
</para></listitem>
75 <listitem><para>Binary
"raw" disk image files containing MBR or GPT partition tables and Linux file
76 systems.
</para></listitem>
78 <listitem><para>Similarly, block devices containing MBR or GPT partition tables and file systems.
</para></listitem>
80 <listitem><para>The file system tree of the host OS itself.
</para></listitem>
86 <title>Options
</title>
88 <para>The following options are understood:
</para>
92 <term><option>-p
</option></term>
93 <term><option>--property=
</option></term>
95 <listitem><para>When showing machine or image properties,
96 limit the output to certain properties as specified by the
97 argument. If not specified, all set properties are shown. The
98 argument should be a property name, such as
99 <literal>Name
</literal>. If specified more than once, all
100 properties with the specified names are
101 shown.
</para></listitem>
105 <term><option>-a
</option></term>
106 <term><option>--all
</option></term>
108 <listitem><para>When showing machine or image properties, show
109 all properties regardless of whether they are set or
112 <para>When listing VM or container images, do not suppress
113 images beginning in a dot character
114 (
<literal>.
</literal>).
</para>
116 <para>When cleaning VM or container images, remove all images, not just hidden ones.
</para></listitem>
120 <term><option>--value
</option></term>
122 <listitem><para>When printing properties with
<command>show
</command>, only print the value,
123 and skip the property name and
<literal>=
</literal>.
</para></listitem>
127 <term><option>-l
</option></term>
128 <term><option>--full
</option></term>
130 <listitem><para>Do not ellipsize process tree entries.
</para>
135 <term><option>--kill-who=
</option></term>
137 <listitem><para>When used with
<command>kill
</command>, choose
138 which processes to kill. Must be one of
139 <option>leader
</option>, or
<option>all
</option> to select
140 whether to kill only the leader process of the machine or all
141 processes of the machine. If omitted, defaults to
142 <option>all
</option>.
</para></listitem>
146 <term><option>-s
</option></term>
147 <term><option>--signal=
</option></term>
149 <listitem><para>When used with
<command>kill
</command>, choose
150 which signal to send to selected processes. Must be one of the
151 well-known signal specifiers, such as
152 <constant>SIGTERM
</constant>,
<constant>SIGINT
</constant> or
153 <constant>SIGSTOP
</constant>. If omitted, defaults to
154 <constant>SIGTERM
</constant>.
</para></listitem>
158 <term><option>--uid=
</option></term>
160 <listitem><para>When used with the
<command>shell
</command> command, chooses the user ID to
161 open the interactive shell session as. If the argument to the
<command>shell
</command>
162 command also specifies a user name, this option is ignored. If the name is not specified
163 in either way,
<literal>root
</literal> will be used by default. Note that this switch is
164 not supported for the
<command>login
</command> command (see below).
</para></listitem>
168 <term><option>-E
<replaceable>NAME
</replaceable>=
<replaceable>VALUE
</replaceable></option></term>
169 <term><option>--setenv=
<replaceable>NAME
</replaceable>=
<replaceable>VALUE
</replaceable></option></term>
171 <listitem><para>When used with the
<command>shell
</command> command, sets an environment
172 variable to pass to the executed shell. Takes an environment variable name and value,
173 separated by
<literal>=
</literal>. This switch may be used multiple times to set multiple
174 environment variables. Note that this switch is not supported for the
175 <command>login
</command> command (see below).
</para></listitem>
179 <term><option>--mkdir
</option></term>
181 <listitem><para>When used with
<command>bind
</command>, creates the destination file or directory before
182 applying the bind mount. Note that even though the name of this option suggests that it is suitable only for
183 directories, this option also creates the destination file node to mount over if the object to mount is not
184 a directory, but a regular file, device node, socket or FIFO.
</para></listitem>
188 <term><option>--read-only
</option></term>
190 <listitem><para>When used with
<command>bind
</command>, creates a read-only bind mount.
</para>
192 <para>When used with
<command>clone
</command>,
<command>import-raw
</command> or
<command>import-tar
</command> a
193 read-only container or VM image is created.
</para></listitem>
197 <term><option>-n
</option></term>
198 <term><option>--lines=
</option></term>
200 <listitem><para>When used with
<command>status
</command>,
201 controls the number of journal lines to show, counting from
202 the most recent ones. Takes a positive integer argument.
203 Defaults to
10.
</para>
208 <term><option>-o
</option></term>
209 <term><option>--output=
</option></term>
211 <listitem><para>When used with
<command>status
</command>,
212 controls the formatting of the journal entries that are shown.
213 For the available choices, see
214 <citerefentry><refentrytitle>journalctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
215 Defaults to
<literal>short
</literal>.
</para></listitem>
219 <term><option>--verify=
</option></term>
221 <listitem><para>When downloading a container or VM image,
222 specify whether the image shall be verified before it is made
223 available. Takes one of
<literal>no
</literal>,
224 <literal>checksum
</literal> and
<literal>signature
</literal>.
225 If
<literal>no
</literal>, no verification is done. If
226 <literal>checksum
</literal> is specified, the download is
227 checked for integrity after the transfer is complete, but no
228 signatures are verified. If
<literal>signature
</literal> is
229 specified, the checksum is verified and the image's signature
230 is checked against a local keyring of trustable vendors. It is
231 strongly recommended to set this option to
232 <literal>signature
</literal> if the server and protocol
233 support this. Defaults to
234 <literal>signature
</literal>.
</para></listitem>
238 <term><option>--force
</option></term>
240 <listitem><para>When downloading a container or VM image, and
241 a local copy by the specified local machine name already
242 exists, delete it first and replace it by the newly downloaded
243 image.
</para></listitem>
247 <term><option>--format=
</option></term>
249 <listitem><para>When used with the
<option>export-tar
</option>
250 or
<option>export-raw
</option> commands, specifies the
251 compression format to use for the resulting file. Takes one of
252 <literal>uncompressed
</literal>,
<literal>xz
</literal>,
253 <literal>gzip
</literal>,
<literal>bzip2
</literal>. By default,
254 the format is determined automatically from the image file
255 name passed.
</para></listitem>
259 <term><option>--max-addresses=
</option></term>
261 <listitem><para>When used with the
<option>list-machines
</option>
262 command, limits the number of ip addresses output for every machine.
263 Defaults to
1. All addresses can be requested with
<literal>all
</literal>
264 as argument to
<option>--max-addresses
</option> . If the argument to
265 <option>--max-addresses
</option> is less than the actual number
266 of addresses,
<literal>...
</literal>follows the last address.
267 If multiple addresses are to be written for a given machine, every
268 address except the first one is on a new line and is followed by
269 <literal>,
</literal> if another address will be output afterwards.
</para></listitem>
273 <term><option>-q
</option></term>
274 <term><option>--quiet
</option></term>
276 <listitem><para>Suppresses additional informational output while running.
</para></listitem>
279 <xi:include href=
"user-system-options.xml" xpointer=
"host" />
282 <term><option>-M
</option></term>
283 <term><option>--machine=
</option></term>
285 <listitem><para>Connect to
286 <citerefentry><refentrytitle>systemd-machined.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
287 running in a local container, to perform the specified operation within
288 the container.
</para></listitem>
291 <xi:include href=
"standard-options.xml" xpointer=
"no-pager" />
292 <xi:include href=
"standard-options.xml" xpointer=
"no-legend" />
293 <xi:include href=
"standard-options.xml" xpointer=
"no-ask-password" />
294 <xi:include href=
"standard-options.xml" xpointer=
"help" />
295 <xi:include href=
"standard-options.xml" xpointer=
"version" />
300 <title>Commands
</title>
302 <para>The following commands are understood:
</para>
304 <refsect2><title>Machine Commands
</title><variablelist>
307 <term><command>list
</command></term>
309 <listitem><para>List currently running (online) virtual
310 machines and containers. To enumerate machine images that can
311 be started, use
<command>list-images
</command> (see
312 below). Note that this command hides the special
313 <literal>.host
</literal> machine by default. Use the
314 <option>--all
</option> switch to show it.
</para></listitem>
318 <term><command>status
</command> <replaceable>NAME
</replaceable>…
</term>
320 <listitem><para>Show runtime status information about
321 one or more virtual machines and containers, followed by the
322 most recent log data from the journal. This function is
323 intended to generate human-readable output. If you are looking
324 for computer-parsable output, use
<command>show
</command>
325 instead. Note that the log data shown is reported by the
326 virtual machine or container manager, and frequently contains
327 console output of the machine, but not necessarily journal
328 contents of the machine itself.
</para></listitem>
332 <term><command>show
</command> [
<replaceable>NAME
</replaceable>…]
</term>
334 <listitem><para>Show properties of one or more registered virtual machines or containers or the manager
335 itself. If no argument is specified, properties of the manager will be shown. If a NAME is specified,
336 properties of this virtual machine or container are shown. By default, empty properties are suppressed. Use
337 <option>--all
</option> to show those too. To select specific properties to show, use
338 <option>--property=
</option>. This command is intended to be used whenever computer-parsable output is
339 required, and does not print the control group tree or journal entries. Use
<command>status
</command> if you
340 are looking for formatted human-readable output.
</para></listitem>
344 <term><command>start
</command> <replaceable>NAME
</replaceable>…
</term>
346 <listitem><para>Start a container as a system service, using
347 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
348 This starts
<filename>systemd-nspawn@.service
</filename>,
349 instantiated for the specified machine name, similar to the
350 effect of
<command>systemctl start
</command> on the service
351 name.
<command>systemd-nspawn
</command> looks for a container
352 image by the specified name in
353 <filename>/var/lib/machines/
</filename> (and other search
354 paths, see below) and runs it. Use
355 <command>list-images
</command> (see below) for listing
356 available container images to start.
</para>
359 <citerefentry><refentrytitle>systemd-machined.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
360 also interfaces with a variety of other container and VM
361 managers,
<command>systemd-nspawn
</command> is just one
362 implementation of it. Most of the commands available in
363 <command>machinectl
</command> may be used on containers or VMs
364 controlled by other managers, not just
365 <command>systemd-nspawn
</command>. Starting VMs and container
366 images on those managers requires manager-specific
369 <para>To interactively start a container on the command line
370 with full access to the container's console, please invoke
371 <command>systemd-nspawn
</command> directly. To stop a running
372 container use
<command>machinectl poweroff
</command>.
</para></listitem>
376 <term><command>login
</command> [
<replaceable>NAME
</replaceable>]
</term>
378 <listitem><para>Open an interactive terminal login session in
379 a container or on the local host. If an argument is supplied,
380 it refers to the container machine to connect to. If none is
381 specified, or the container name is specified as the empty
382 string, or the special machine name
<literal>.host
</literal>
383 (see below) is specified, the connection is made to the local
384 host instead. This will create a TTY connection to a specific
385 container or the local host and asks for the execution of a
386 getty on it. Note that this is only supported for containers
388 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
389 as init system.
</para>
391 <para>This command will open a full login prompt on the
392 container or the local host, which then asks for username and
393 password. Use
<command>shell
</command> (see below) or
394 <citerefentry><refentrytitle>systemd-run
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
395 with the
<option>--machine=
</option> switch to directly invoke
396 a single command, either interactively or in the
397 background.
</para></listitem>
401 <term><command>shell
</command> [[
<replaceable>NAME
</replaceable>@]
<replaceable>NAME
</replaceable> [
<replaceable>PATH
</replaceable> [
<replaceable>ARGUMENTS
</replaceable>…]]]
</term>
403 <listitem><para>Open an interactive shell session in a
404 container or on the local host. The first argument refers to
405 the container machine to connect to. If none is specified, or
406 the machine name is specified as the empty string, or the
407 special machine name
<literal>.host
</literal> (see below) is
408 specified, the connection is made to the local host
409 instead. This works similar to
<command>login
</command> but
410 immediately invokes a user process. This command runs the
411 specified executable with the specified arguments, or the
412 default shell for the user if none is specified, or
413 <filename>/bin/sh
</filename> if no default shell is found. By default,
414 <option>--uid=
</option>, or by prefixing the machine name with
415 a username and an
<literal>@
</literal> character, a different
416 user may be selected. Use
<option>--setenv=
</option> to set
417 environment variables for the executed process.
</para>
419 <para>Note that
<command>machinectl shell
</command> does not propagate the exit code/status of the invoked
420 shell process. Use
<command>systemd-run
</command> instead if that information is required (see below).
</para>
422 <para>When using the
<command>shell
</command> command without
423 arguments, (thus invoking the executed shell or command on the
424 local host), it is in many ways similar to a
<citerefentry
425 project='die-net'
><refentrytitle>su
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
426 session, but, unlike
<command>su
</command>, completely isolates
427 the new session from the originating session, so that it
428 shares no process or session properties, and is in a clean and
429 well-defined state. It will be tracked in a new utmp, login,
430 audit, security and keyring session, and will not inherit any
431 environment variables or resource limits, among other
434 <para>Note that
<citerefentry><refentrytitle>systemd-run
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
435 with its
<option>--machine=
</option> switch may be used in place of the
<command>machinectl shell
</command>
436 command, and allows non-interactive operation, more detailed and low-level configuration of the invoked unit,
437 as well as access to runtime and exit code/status information of the invoked shell process. In particular, use
438 <command>systemd-run
</command>'s
<option>--wait
</option> switch to propagate exit status information of the
439 invoked process. Use
<command>systemd-run
</command>'s
<option>--pty
</option> switch for acquiring an
440 interactive shell, similar to
<command>machinectl shell
</command>. In general,
<command>systemd-run
</command>
441 is preferable for scripting purposes. However, note that
<command>systemd-run
</command> might require higher
442 privileges than
<command>machinectl shell
</command>.
</para></listitem>
446 <term><command>enable
</command> <replaceable>NAME
</replaceable>…
</term>
447 <term><command>disable
</command> <replaceable>NAME
</replaceable>…
</term>
449 <listitem><para>Enable or disable a container as a system
450 service to start at system boot, using
451 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
452 This enables or disables
453 <filename>systemd-nspawn@.service
</filename>, instantiated for
454 the specified machine name, similar to the effect of
455 <command>systemctl enable
</command> or
<command>systemctl
456 disable
</command> on the service name.
</para></listitem>
460 <term><command>poweroff
</command> <replaceable>NAME
</replaceable>…
</term>
462 <listitem><para>Power off one or more containers. This will
463 trigger a reboot by sending SIGRTMIN+
4 to the container's init
464 process, which causes systemd-compatible init systems to shut
465 down cleanly. Use
<command>stop
</command> as alias for
<command>poweroff
</command>.
466 This operation does not work on containers that do not run a
467 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>-compatible
468 init system, such as sysvinit. Use
469 <command>terminate
</command> (see below) to immediately
470 terminate a container or VM, without cleanly shutting it
471 down.
</para></listitem>
475 <term><command>reboot
</command> <replaceable>NAME
</replaceable>…
</term>
477 <listitem><para>Reboot one or more containers. This will
478 trigger a reboot by sending SIGINT to the container's init
479 process, which is roughly equivalent to pressing Ctrl+Alt+Del
480 on a non-containerized system, and is compatible with
481 containers running any system manager.
</para></listitem>
485 <term><command>terminate
</command> <replaceable>NAME
</replaceable>…
</term>
487 <listitem><para>Immediately terminates a virtual machine or
488 container, without cleanly shutting it down. This kills all
489 processes of the virtual machine or container and deallocates
490 all resources attached to that instance. Use
491 <command>poweroff
</command> to issue a clean shutdown
492 request.
</para></listitem>
496 <term><command>kill
</command> <replaceable>NAME
</replaceable>…
</term>
498 <listitem><para>Send a signal to one or more processes of the
499 virtual machine or container. This means processes as seen by
500 the host, not the processes inside the virtual machine or
501 container. Use
<option>--kill-who=
</option> to select which
502 process to kill. Use
<option>--signal=
</option> to select the
503 signal to send.
</para></listitem>
507 <term><command>bind
</command> <replaceable>NAME
</replaceable> <replaceable>PATH
</replaceable> [
<replaceable>PATH
</replaceable>]
</term>
509 <listitem><para>Bind mounts a file or directory from the host into the specified container. The first path
510 argument is the source file or directory on the host, the second path argument is the destination file or
511 directory in the container. When the latter is omitted, the destination path in the container is the same as
512 the source path on the host. When combined with the
<option>--read-only
</option> switch, a ready-only bind
513 mount is created. When combined with the
<option>--mkdir
</option> switch, the destination path is first created
514 before the mount is applied. Note that this option is currently only supported for
515 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry> containers,
516 and only if user namespacing (
<option>--private-users
</option>) is not used. This command supports bind
517 mounting directories, regular files, device nodes,
<constant>AF_UNIX
</constant> socket nodes, as well as
518 FIFOs.
</para></listitem>
522 <term><command>copy-to
</command> <replaceable>NAME
</replaceable> <replaceable>PATH
</replaceable> [
<replaceable>PATH
</replaceable>]
</term>
524 <listitem><para>Copies files or directories from the host
525 system into a running container. Takes a container name,
526 followed by the source path on the host and the destination
527 path in the container. If the destination path is omitted, the
528 same as the source path is used.
</para>
530 <para>If host and container share the same user and group namespace, file ownership by numeric user ID and
531 group ID is preserved for the copy, otherwise all files and directories in the copy will be owned by the root
532 user and group (UID/GID
0).
</para></listitem>
536 <term><command>copy-from
</command> <replaceable>NAME
</replaceable> <replaceable>PATH
</replaceable> [
<replaceable>PATH
</replaceable>]
</term>
538 <listitem><para>Copies files or directories from a container
539 into the host system. Takes a container name, followed by the
540 source path in the container the destination path on the host.
541 If the destination path is omitted, the same as the source path
544 <para>If host and container share the same user and group namespace, file ownership by numeric user ID and
545 group ID is preserved for the copy, otherwise all files and directories in the copy will be owned by the root
546 user and group (UID/GID
0).
</para></listitem>
548 </variablelist></refsect2>
550 <refsect2><title>Image Commands
</title><variablelist>
553 <term><command>list-images
</command></term>
555 <listitem><para>Show a list of locally installed container and
556 VM images. This enumerates all raw disk images and container
557 directories and subvolumes in
558 <filename>/var/lib/machines/
</filename> (and other search
559 paths, see below). Use
<command>start
</command> (see above) to
560 run a container off one of the listed images. Note that, by
561 default, containers whose name begins with a dot
562 (
<literal>.
</literal>) are not shown. To show these too,
563 specify
<option>--all
</option>. Note that a special image
564 <literal>.host
</literal> always implicitly exists and refers
565 to the image the host itself is booted from.
</para></listitem>
569 <term><command>image-status
</command> [
<replaceable>NAME
</replaceable>…]
</term>
571 <listitem><para>Show terse status information about one or
572 more container or VM images. This function is intended to
573 generate human-readable output. Use
574 <command>show-image
</command> (see below) to generate
575 computer-parsable output instead.
</para></listitem>
579 <term><command>show-image
</command> [
<replaceable>NAME
</replaceable>…]
</term>
581 <listitem><para>Show properties of one or more registered
582 virtual machine or container images, or the manager itself. If
583 no argument is specified, properties of the manager will be
584 shown. If a NAME is specified, properties of this virtual
585 machine or container image are shown. By default, empty
586 properties are suppressed. Use
<option>--all
</option> to show
587 those too. To select specific properties to show, use
588 <option>--property=
</option>. This command is intended to be
589 used whenever computer-parsable output is required. Use
590 <command>image-status
</command> if you are looking for
591 formatted human-readable output.
</para></listitem>
595 <term><command>clone
</command> <replaceable>NAME
</replaceable> <replaceable>NAME
</replaceable></term>
597 <listitem><para>Clones a container or VM image. The arguments specify the name of the image to clone and the
598 name of the newly cloned image. Note that plain directory container images are cloned into btrfs subvolume
599 images with this command, if the underlying file system supports this. Note that cloning a container or VM
600 image is optimized for file systems that support copy-on-write, and might not be efficient on others, due to
601 file system limitations.
</para>
603 <para>Note that this command leaves host name, machine ID and
604 all other settings that could identify the instance
605 unmodified. The original image and the cloned copy will hence
606 share these credentials, and it might be necessary to manually
607 change them in the copy.
</para>
609 <para>If combined with the
<option>--read-only
</option> switch a read-only cloned image is
610 created.
</para></listitem>
614 <term><command>rename
</command> <replaceable>NAME
</replaceable> <replaceable>NAME
</replaceable></term>
616 <listitem><para>Renames a container or VM image. The
617 arguments specify the name of the image to rename and the new
618 name of the image.
</para></listitem>
622 <term><command>read-only
</command> <replaceable>NAME
</replaceable> [
<replaceable>BOOL
</replaceable>]
</term>
624 <listitem><para>Marks or (unmarks) a container or VM image
625 read-only. Takes a VM or container image name, followed by a
626 boolean as arguments. If the boolean is omitted, positive is
627 implied, i.e. the image is marked read-only.
</para></listitem>
631 <term><command>remove
</command> <replaceable>NAME
</replaceable>…
</term>
633 <listitem><para>Removes one or more container or VM images.
634 The special image
<literal>.host
</literal>, which refers to
635 the host's own directory tree, may not be
636 removed.
</para></listitem>
640 <term><command>set-limit
</command> [
<replaceable>NAME
</replaceable>]
<replaceable>BYTES
</replaceable></term>
642 <listitem><para>Sets the maximum size in bytes that a specific
643 container or VM image, or all images, may grow up to on disk
644 (disk quota). Takes either one or two parameters. The first,
645 optional parameter refers to a container or VM image name. If
646 specified, the size limit of the specified image is changed. If
647 omitted, the overall size limit of the sum of all images stored
648 locally is changed. The final argument specifies the size
649 limit in bytes, possibly suffixed by the usual K, M, G, T
650 units. If the size limit shall be disabled, specify
651 <literal>-
</literal> as size.
</para>
653 <para>Note that per-container size limits are only supported on btrfs file systems.
</para></listitem>
657 <term><command>clean
</command></term>
659 <listitem><para>Remove hidden VM or container images (or all). This command removes all hidden machine images
660 from
<filename>/var/lib/machines
</filename>, i.e. those whose name begins with a dot. Use
<command>machinectl
661 list-images --all
</command> to see a list of all machine images, including the hidden ones.
</para>
663 <para>When combined with the
<option>--all
</option> switch removes all images, not just hidden ones. This
664 command effectively empties
<filename>/var/lib/machines
</filename>.
</para>
666 <para>Note that commands such as
<command>machinectl pull-tar
</command> or
<command>machinectl
667 pull-raw
</command> usually create hidden, read-only, unmodified machine images from the downloaded image first,
668 before cloning a writable working copy of it, in order to avoid duplicate downloads in case of images that are
669 reused multiple times. Use
<command>machinectl clean
</command> to remove old, hidden images created this
670 way.
</para></listitem>
673 </variablelist></refsect2>
675 <refsect2><title>Image Transfer Commands
</title><variablelist>
678 <term><command>pull-tar
</command> <replaceable>URL
</replaceable> [
<replaceable>NAME
</replaceable>]
</term>
680 <listitem><para>Downloads a
<filename>.tar
</filename>
681 container image from the specified URL, and makes it available
682 under the specified local machine name. The URL must be of
683 type
<literal>http://
</literal> or
684 <literal>https://
</literal>, and must refer to a
685 <filename>.tar
</filename>,
<filename>.tar.gz
</filename>,
686 <filename>.tar.xz
</filename> or
<filename>.tar.bz2
</filename>
687 archive file. If the local machine name is omitted, it
688 is automatically derived from the last component of the URL,
689 with its suffix removed.
</para>
691 <para>The image is verified before it is made available, unless
692 <option>--verify=no
</option> is specified.
693 Verification is done either via an inline signed file with the name
694 of the image and the suffix
<filename>.sha256
</filename> or via
695 separate
<filename>SHA256SUMS
</filename> and
696 <filename>SHA256SUMS.gpg
</filename> files.
697 The signature files need to be made available on the same web
698 server, under the same URL as the
<filename>.tar
</filename> file.
699 With
<option>--verify=checksum
</option>, only the SHA256 checksum
700 for the file is verified, based on the
<filename>.sha256
</filename>
701 suffixed file or the
<filename>SHA256SUMS
</filename> file.
702 With
<option>--verify=signature
</option>, the sha checksum file is
703 first verified with the inline signature in the
704 <filename>.sha256
</filename> file or the detached GPG signature file
705 <filename>SHA256SUMS.gpg
</filename>.
706 The public key for this verification step needs to be available in
707 <filename>/usr/lib/systemd/import-pubring.gpg
</filename> or
708 <filename>/etc/systemd/import-pubring.gpg
</filename>.
</para>
710 <para>The container image will be downloaded and stored in a
711 read-only subvolume in
712 <filename>/var/lib/machines/
</filename> that is named after
713 the specified URL and its HTTP etag. A writable snapshot is
714 then taken from this subvolume, and named after the specified
715 local name. This behavior ensures that creating multiple
716 container instances of the same URL is efficient, as multiple
717 downloads are not necessary. In order to create only the
718 read-only image, and avoid creating its writable snapshot,
719 specify
<literal>-
</literal> as local machine name.
</para>
721 <para>Note that the read-only subvolume is prefixed with
722 <filename>.tar-
</filename>, and is thus not shown by
723 <command>list-images
</command>, unless
<option>--all
</option>
726 <para>Note that pressing C-c during execution of this command
727 will not abort the download. Use
728 <command>cancel-transfer
</command>, described
729 below.
</para></listitem>
733 <term><command>pull-raw
</command> <replaceable>URL
</replaceable> [
<replaceable>NAME
</replaceable>]
</term>
735 <listitem><para>Downloads a
<filename>.raw
</filename>
736 container or VM disk image from the specified URL, and makes
737 it available under the specified local machine name. The URL
738 must be of type
<literal>http://
</literal> or
739 <literal>https://
</literal>. The container image must either
740 be a
<filename>.qcow2
</filename> or raw disk image, optionally
741 compressed as
<filename>.gz
</filename>,
742 <filename>.xz
</filename>, or
<filename>.bz2
</filename>. If the
743 local machine name is omitted, it is automatically
744 derived from the last component of the URL, with its suffix
747 <para>Image verification is identical for raw and tar images
750 <para>If the downloaded image is in
751 <filename>.qcow2
</filename> format it is converted into a raw
752 image file before it is made available.
</para>
754 <para>Downloaded images of this type will be placed as
755 read-only
<filename>.raw
</filename> file in
756 <filename>/var/lib/machines/
</filename>. A local, writable
757 (reflinked) copy is then made under the specified local
758 machine name. To omit creation of the local, writable copy
759 pass
<literal>-
</literal> as local machine name.
</para>
761 <para>Similar to the behavior of
<command>pull-tar
</command>,
762 the read-only image is prefixed with
763 <filename>.raw-
</filename>, and thus not shown by
764 <command>list-images
</command>, unless
<option>--all
</option>
767 <para>Note that pressing C-c during execution of this command
768 will not abort the download. Use
769 <command>cancel-transfer
</command>, described
770 below.
</para></listitem>
774 <term><command>import-tar
</command> <replaceable>FILE
</replaceable> [
<replaceable>NAME
</replaceable>]
</term>
775 <term><command>import-raw
</command> <replaceable>FILE
</replaceable> [
<replaceable>NAME
</replaceable>]
</term>
776 <listitem><para>Imports a TAR or RAW container or VM image,
777 and places it under the specified name in
778 <filename>/var/lib/machines/
</filename>. When
779 <command>import-tar
</command> is used, the file specified as
780 the first argument should be a tar archive, possibly compressed
781 with xz, gzip or bzip2. It will then be unpacked into its own
782 subvolume in
<filename>/var/lib/machines
</filename>. When
783 <command>import-raw
</command> is used, the file should be a
784 qcow2 or raw disk image, possibly compressed with xz, gzip or
785 bzip2. If the second argument (the resulting image name) is
786 not specified, it is automatically derived from the file
787 name. If the filename is passed as
<literal>-
</literal>, the
788 image is read from standard input, in which case the second
789 argument is mandatory.
</para>
791 <para>Optionally, the
<option>--read-only
</option> switch may be used to create a read-only container or VM
792 image. No cryptographic validation is done when importing the images.
</para>
794 <para>Much like image downloads, ongoing imports may be listed
795 with
<command>list-transfers
</command> and aborted with
796 <command>cancel-transfer
</command>.
</para></listitem>
800 <term><command>import-fs
</command> <replaceable>DIRECTORY
</replaceable> [
<replaceable>NAME
</replaceable>]
</term>
802 <listitem><para>Imports a container image stored in a local directory into
803 <filename>/var/lib/machines/
</filename>, operates similar to
<command>import-tar
</command> or
804 <command>import-raw
</command>, but the first argument is the source directory. If supported, this command will
805 create btrfs snapshot or subvolume for the new image.
</para></listitem>
809 <term><command>export-tar
</command> <replaceable>NAME
</replaceable> [
<replaceable>FILE
</replaceable>]
</term>
810 <term><command>export-raw
</command> <replaceable>NAME
</replaceable> [
<replaceable>FILE
</replaceable>]
</term>
811 <listitem><para>Exports a TAR or RAW container or VM image and
812 stores it in the specified file. The first parameter should be
813 a VM or container image name. The second parameter should be a
814 file path the TAR or RAW image is written to. If the path ends
815 in
<literal>.gz
</literal>, the file is compressed with gzip, if
816 it ends in
<literal>.xz
</literal>, with xz, and if it ends in
817 <literal>.bz2
</literal>, with bzip2. If the path ends in
818 neither, the file is left uncompressed. If the second argument
819 is missing, the image is written to standard output. The
820 compression may also be explicitly selected with the
821 <option>--format=
</option> switch. This is in particular
822 useful if the second parameter is left unspecified.
</para>
824 <para>Much like image downloads and imports, ongoing exports
825 may be listed with
<command>list-transfers
</command> and
827 <command>cancel-transfer
</command>.
</para>
829 <para>Note that, currently, only directory and subvolume images
830 may be exported as TAR images, and only raw disk images as RAW
831 images.
</para></listitem>
835 <term><command>list-transfers
</command></term>
837 <listitem><para>Shows a list of container or VM image
838 downloads, imports and exports that are currently in
839 progress.
</para></listitem>
843 <term><command>cancel-transfer
</command> <replaceable>ID
</replaceable>…
</term>
845 <listitem><para>Aborts a download, import or export of the
846 container or VM image with the specified ID. To list ongoing
847 transfers and their IDs, use
848 <command>list-transfers
</command>.
</para></listitem>
851 </variablelist></refsect2>
856 <title>Machine and Image Names
</title>
858 <para>The
<command>machinectl
</command> tool operates on machines
859 and images whose names must be chosen following strict
860 rules. Machine names must be suitable for use as host names
861 following a conservative subset of DNS and UNIX/Linux
862 semantics. Specifically, they must consist of one or more
863 non-empty label strings, separated by dots. No leading or trailing
864 dots are allowed. No sequences of multiple dots are allowed. The
865 label strings may only consist of alphanumeric characters as well
866 as the dash and underscore. The maximum length of a machine name
867 is
64 characters.
</para>
869 <para>A special machine with the name
<literal>.host
</literal>
870 refers to the running host system itself. This is useful for execution
871 operations or inspecting the host system as well. Note that
872 <command>machinectl list
</command> will not show this special
873 machine unless the
<option>--all
</option> switch is specified.
</para>
875 <para>Requirements on image names are less strict, however, they must be
876 valid UTF-
8, must be suitable as file names (hence not be the
877 single or double dot, and not include a slash), and may not
878 contain control characters. Since many operations search for an
879 image by the name of a requested machine, it is recommended to name
880 images in the same strict fashion as machines.
</para>
882 <para>A special image with the name
<literal>.host
</literal>
883 refers to the image of the running host system. It hence
884 conceptually maps to the special
<literal>.host
</literal> machine
885 name described above. Note that
<command>machinectl
886 list-images
</command> will not show this special image either, unless
887 <option>--all
</option> is specified.
</para>
891 <title>Files and Directories
</title>
893 <para>Machine images are preferably stored in
894 <filename>/var/lib/machines/
</filename>, but are also searched for
895 in
<filename>/usr/local/lib/machines/
</filename> and
896 <filename>/usr/lib/machines/
</filename>. For compatibility reasons,
897 the directory
<filename>/var/lib/container/
</filename> is
898 searched, too. Note that images stored below
899 <filename>/usr
</filename> are always considered read-only. It is
900 possible to symlink machines images from other directories into
901 <filename>/var/lib/machines/
</filename> to make them available for
902 control with
<command>machinectl
</command>.
</para>
904 <para>Note that some image operations are only supported, efficient or atomic on btrfs file systems.
</para>
906 <para>Disk images are understood by
907 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
908 and
<command>machinectl
</command> in three formats:
</para>
911 <listitem><para>A simple directory tree, containing the files
912 and directories of the container to boot.
</para></listitem>
914 <listitem><para>Subvolumes (on btrfs file systems), which are
915 similar to the simple directories, described above. However,
916 they have additional benefits, such as efficient cloning and
917 quota reporting.
</para></listitem>
919 <listitem><para>"Raw" disk images, i.e. binary images of disks
920 with a GPT or MBR partition table. Images of this type are
921 regular files with the suffix
922 <literal>.raw
</literal>.
</para></listitem>
926 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
927 for more information on image formats, in particular its
928 <option>--directory=
</option> and
<option>--image=
</option>
933 <title>Examples
</title>
935 <title>Download an Ubuntu image and open a shell in it
</title>
937 <programlisting># machinectl pull-tar https://cloud-images.ubuntu.com/trusty/current/trusty-server-cloudimg-amd64-root.tar.gz
938 # systemd-nspawn -M trusty-server-cloudimg-amd64-root
</programlisting>
940 <para>This downloads and verifies the specified
941 <filename>.tar
</filename> image, and then uses
942 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
943 to open a shell in it.
</para>
947 <title>Download a Fedora image, set a root password in it, start
948 it as service
</title>
950 <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
951 # systemd-nspawn -M Fedora-Cloud-Base-
27-
1.6.x86_64
954 # machinectl start Fedora-Cloud-Base-
27-
1.6.x86_64
955 # machinectl login Fedora-Cloud-Base-
27-
1.6.x86_64
</programlisting>
957 <para>This downloads the specified
<filename>.raw
</filename>
958 image with verification disabled. Then, a shell is opened in it
959 and a root password is set. Afterwards the shell is left, and
960 the machine started as system service. With the last command a
961 login prompt into the container is requested.
</para>
965 <title>Exports a container image as tar file
</title>
967 <programlisting># machinectl export-tar fedora myfedora.tar.xz
</programlisting>
969 <para>Exports the container
<literal>fedora
</literal> as an
970 xz-compressed tar file
<filename>myfedora.tar.xz
</filename> into the
971 current directory.
</para>
975 <title>Create a new shell session
</title>
977 <programlisting># machinectl shell --uid=lennart
</programlisting>
979 <para>This creates a new shell session on the local host for
980 the user ID
<literal>lennart
</literal>, in a
<citerefentry
981 project='die-net'
><refentrytitle>su
</refentrytitle><manvolnum>1</manvolnum></citerefentry>-like
988 <title>Exit status
</title>
990 <para>On success,
0 is returned, a non-zero failure code
994 <xi:include href=
"less-variables.xml" />
997 <title>See Also
</title>
999 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1000 <citerefentry><refentrytitle>systemd-machined.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
1001 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1002 <citerefentry><refentrytitle>systemd.special
</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1003 <citerefentry project='die-net'
><refentrytitle>tar
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1004 <citerefentry project='die-net'
><refentrytitle>xz
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1005 <citerefentry project='die-net'
><refentrytitle>gzip
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1006 <citerefentry project='die-net'
><refentrytitle>bzip2
</refentrytitle><manvolnum>1</manvolnum></citerefentry>