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
74 normal directory trees.
</para></listitem>
76 <listitem><para>Binary
"raw" disk images containing MBR or GPT
77 partition tables and Linux file system partitions.
</para></listitem>
79 <listitem><para>The file system tree of the host OS itself.
</para></listitem>
85 <title>Options
</title>
87 <para>The following options are understood:
</para>
91 <term><option>-p
</option></term>
92 <term><option>--property=
</option></term>
94 <listitem><para>When showing machine or image properties,
95 limit the output to certain properties as specified by the
96 argument. If not specified, all set properties are shown. The
97 argument should be a property name, such as
98 <literal>Name
</literal>. If specified more than once, all
99 properties with the specified names are
100 shown.
</para></listitem>
104 <term><option>-a
</option></term>
105 <term><option>--all
</option></term>
107 <listitem><para>When showing machine or image properties, show
108 all properties regardless of whether they are set or
111 <para>When listing VM or container images, do not suppress
112 images beginning in a dot character
113 (
<literal>.
</literal>).
</para>
115 <para>When cleaning VM or container images, remove all images, not just hidden ones.
</para></listitem>
119 <term><option>--value
</option></term>
121 <listitem><para>When printing properties with
<command>show
</command>, only print the value,
122 and skip the property name and
<literal>=
</literal>.
</para></listitem>
126 <term><option>-l
</option></term>
127 <term><option>--full
</option></term>
129 <listitem><para>Do not ellipsize process tree entries.
</para>
134 <term><option>--kill-who=
</option></term>
136 <listitem><para>When used with
<command>kill
</command>, choose
137 which processes to kill. Must be one of
138 <option>leader
</option>, or
<option>all
</option> to select
139 whether to kill only the leader process of the machine or all
140 processes of the machine. If omitted, defaults to
141 <option>all
</option>.
</para></listitem>
145 <term><option>-s
</option></term>
146 <term><option>--signal=
</option></term>
148 <listitem><para>When used with
<command>kill
</command>, choose
149 which signal to send to selected processes. Must be one of the
150 well-known signal specifiers, such as
151 <constant>SIGTERM
</constant>,
<constant>SIGINT
</constant> or
152 <constant>SIGSTOP
</constant>. If omitted, defaults to
153 <constant>SIGTERM
</constant>.
</para></listitem>
157 <term><option>--uid=
</option></term>
159 <listitem><para>When used with the
<command>shell
</command> command, chooses the user ID to
160 open the interactive shell session as. If the argument to the
<command>shell
</command>
161 command also specifies a user name, this option is ignored. If the name is not specified
162 in either way,
<literal>root
</literal> will be used by default. Note that this switch is
163 not supported for the
<command>login
</command> command (see below).
</para></listitem>
167 <term><option>-E
<replaceable>NAME
</replaceable>=
<replaceable>VALUE
</replaceable></option></term>
168 <term><option>--setenv=
<replaceable>NAME
</replaceable>=
<replaceable>VALUE
</replaceable></option></term>
170 <listitem><para>When used with the
<command>shell
</command> command, sets an environment
171 variable to pass to the executed shell. Takes an environment variable name and value,
172 separated by
<literal>=
</literal>. This switch may be used multiple times to set multiple
173 environment variables. Note that this switch is not supported for the
174 <command>login
</command> command (see below).
</para></listitem>
178 <term><option>--mkdir
</option></term>
180 <listitem><para>When used with
<command>bind
</command>, creates the destination file or directory before
181 applying the bind mount. Note that even though the name of this option suggests that it is suitable only for
182 directories, this option also creates the destination file node to mount over if the object to mount is not
183 a directory, but a regular file, device node, socket or FIFO.
</para></listitem>
187 <term><option>--read-only
</option></term>
189 <listitem><para>When used with
<command>bind
</command>, creates a read-only bind mount.
</para>
191 <para>When used with
<command>clone
</command>,
<command>import-raw
</command> or
<command>import-tar
</command> a
192 read-only container or VM image is created.
</para></listitem>
196 <term><option>-n
</option></term>
197 <term><option>--lines=
</option></term>
199 <listitem><para>When used with
<command>status
</command>,
200 controls the number of journal lines to show, counting from
201 the most recent ones. Takes a positive integer argument.
202 Defaults to
10.
</para>
207 <term><option>-o
</option></term>
208 <term><option>--output=
</option></term>
210 <listitem><para>When used with
<command>status
</command>,
211 controls the formatting of the journal entries that are shown.
212 For the available choices, see
213 <citerefentry><refentrytitle>journalctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
214 Defaults to
<literal>short
</literal>.
</para></listitem>
218 <term><option>--verify=
</option></term>
220 <listitem><para>When downloading a container or VM image,
221 specify whether the image shall be verified before it is made
222 available. Takes one of
<literal>no
</literal>,
223 <literal>checksum
</literal> and
<literal>signature
</literal>.
224 If
<literal>no
</literal>, no verification is done. If
225 <literal>checksum
</literal> is specified, the download is
226 checked for integrity after the transfer is complete, but no
227 signatures are verified. If
<literal>signature
</literal> is
228 specified, the checksum is verified and the image's signature
229 is checked against a local keyring of trustable vendors. It is
230 strongly recommended to set this option to
231 <literal>signature
</literal> if the server and protocol
232 support this. Defaults to
233 <literal>signature
</literal>.
</para></listitem>
237 <term><option>--force
</option></term>
239 <listitem><para>When downloading a container or VM image, and
240 a local copy by the specified local machine name already
241 exists, delete it first and replace it by the newly downloaded
242 image.
</para></listitem>
246 <term><option>--format=
</option></term>
248 <listitem><para>When used with the
<option>export-tar
</option>
249 or
<option>export-raw
</option> commands, specifies the
250 compression format to use for the resulting file. Takes one of
251 <literal>uncompressed
</literal>,
<literal>xz
</literal>,
252 <literal>gzip
</literal>,
<literal>bzip2
</literal>. By default,
253 the format is determined automatically from the image file
254 name passed.
</para></listitem>
258 <term><option>--max-addresses=
</option></term>
260 <listitem><para>When used with the
<option>list-machines
</option>
261 command, limits the number of ip addresses output for every machine.
262 Defaults to
1. All addresses can be requested with
<literal>all
</literal>
263 as argument to
<option>--max-addresses
</option> . If the argument to
264 <option>--max-addresses
</option> is less than the actual number
265 of addresses,
<literal>...
</literal>follows the last address.
266 If multiple addresses are to be written for a given machine, every
267 address except the first one is on a new line and is followed by
268 <literal>,
</literal> if another address will be output afterwards.
</para></listitem>
272 <term><option>-q
</option></term>
273 <term><option>--quiet
</option></term>
275 <listitem><para>Suppresses additional informational output while running.
</para></listitem>
278 <xi:include href=
"user-system-options.xml" xpointer=
"host" />
281 <term><option>-M
</option></term>
282 <term><option>--machine=
</option></term>
284 <listitem><para>Connect to
285 <citerefentry><refentrytitle>systemd-machined.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
286 running in a local container, to perform the specified operation within
287 the container.
</para></listitem>
290 <xi:include href=
"standard-options.xml" xpointer=
"no-pager" />
291 <xi:include href=
"standard-options.xml" xpointer=
"no-legend" />
292 <xi:include href=
"standard-options.xml" xpointer=
"no-ask-password" />
293 <xi:include href=
"standard-options.xml" xpointer=
"help" />
294 <xi:include href=
"standard-options.xml" xpointer=
"version" />
299 <title>Commands
</title>
301 <para>The following commands are understood:
</para>
303 <refsect2><title>Machine Commands
</title><variablelist>
306 <term><command>list
</command></term>
308 <listitem><para>List currently running (online) virtual
309 machines and containers. To enumerate machine images that can
310 be started, use
<command>list-images
</command> (see
311 below). Note that this command hides the special
312 <literal>.host
</literal> machine by default. Use the
313 <option>--all
</option> switch to show it.
</para></listitem>
317 <term><command>status
</command> <replaceable>NAME
</replaceable>…
</term>
319 <listitem><para>Show runtime status information about
320 one or more virtual machines and containers, followed by the
321 most recent log data from the journal. This function is
322 intended to generate human-readable output. If you are looking
323 for computer-parsable output, use
<command>show
</command>
324 instead. Note that the log data shown is reported by the
325 virtual machine or container manager, and frequently contains
326 console output of the machine, but not necessarily journal
327 contents of the machine itself.
</para></listitem>
331 <term><command>show
</command> [
<replaceable>NAME
</replaceable>…]
</term>
333 <listitem><para>Show properties of one or more registered virtual machines or containers or the manager
334 itself. If no argument is specified, properties of the manager will be shown. If a NAME is specified,
335 properties of this virtual machine or container are shown. By default, empty properties are suppressed. Use
336 <option>--all
</option> to show those too. To select specific properties to show, use
337 <option>--property=
</option>. This command is intended to be used whenever computer-parsable output is
338 required, and does not print the control group tree or journal entries. Use
<command>status
</command> if you
339 are looking for formatted human-readable output.
</para></listitem>
343 <term><command>start
</command> <replaceable>NAME
</replaceable>…
</term>
345 <listitem><para>Start a container as a system service, using
346 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
347 This starts
<filename>systemd-nspawn@.service
</filename>,
348 instantiated for the specified machine name, similar to the
349 effect of
<command>systemctl start
</command> on the service
350 name.
<command>systemd-nspawn
</command> looks for a container
351 image by the specified name in
352 <filename>/var/lib/machines/
</filename> (and other search
353 paths, see below) and runs it. Use
354 <command>list-images
</command> (see below) for listing
355 available container images to start.
</para>
358 <citerefentry><refentrytitle>systemd-machined.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
359 also interfaces with a variety of other container and VM
360 managers,
<command>systemd-nspawn
</command> is just one
361 implementation of it. Most of the commands available in
362 <command>machinectl
</command> may be used on containers or VMs
363 controlled by other managers, not just
364 <command>systemd-nspawn
</command>. Starting VMs and container
365 images on those managers requires manager-specific
368 <para>To interactively start a container on the command line
369 with full access to the container's console, please invoke
370 <command>systemd-nspawn
</command> directly. To stop a running
371 container use
<command>machinectl poweroff
</command>.
</para></listitem>
375 <term><command>login
</command> [
<replaceable>NAME
</replaceable>]
</term>
377 <listitem><para>Open an interactive terminal login session in
378 a container or on the local host. If an argument is supplied,
379 it refers to the container machine to connect to. If none is
380 specified, or the container name is specified as the empty
381 string, or the special machine name
<literal>.host
</literal>
382 (see below) is specified, the connection is made to the local
383 host instead. This will create a TTY connection to a specific
384 container or the local host and asks for the execution of a
385 getty on it. Note that this is only supported for containers
387 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
388 as init system.
</para>
390 <para>This command will open a full login prompt on the
391 container or the local host, which then asks for username and
392 password. Use
<command>shell
</command> (see below) or
393 <citerefentry><refentrytitle>systemd-run
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
394 with the
<option>--machine=
</option> switch to directly invoke
395 a single command, either interactively or in the
396 background.
</para></listitem>
400 <term><command>shell
</command> [[
<replaceable>NAME
</replaceable>@]
<replaceable>NAME
</replaceable> [
<replaceable>PATH
</replaceable> [
<replaceable>ARGUMENTS
</replaceable>…]]]
</term>
402 <listitem><para>Open an interactive shell session in a
403 container or on the local host. The first argument refers to
404 the container machine to connect to. If none is specified, or
405 the machine name is specified as the empty string, or the
406 special machine name
<literal>.host
</literal> (see below) is
407 specified, the connection is made to the local host
408 instead. This works similar to
<command>login
</command> but
409 immediately invokes a user process. This command runs the
410 specified executable with the specified arguments, or the
411 default shell for the user if none is specified, or
412 <filename>/bin/sh
</filename> if no default shell is found. By default,
413 <option>--uid=
</option>, or by prefixing the machine name with
414 a username and an
<literal>@
</literal> character, a different
415 user may be selected. Use
<option>--setenv=
</option> to set
416 environment variables for the executed process.
</para>
418 <para>Note that
<command>machinectl shell
</command> does not propagate the exit code/status of the invoked
419 shell process. Use
<command>systemd-run
</command> instead if that information is required (see below).
</para>
421 <para>When using the
<command>shell
</command> command without
422 arguments, (thus invoking the executed shell or command on the
423 local host), it is in many ways similar to a
<citerefentry
424 project='die-net'
><refentrytitle>su
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
425 session, but, unlike
<command>su
</command>, completely isolates
426 the new session from the originating session, so that it
427 shares no process or session properties, and is in a clean and
428 well-defined state. It will be tracked in a new utmp, login,
429 audit, security and keyring session, and will not inherit any
430 environment variables or resource limits, among other
433 <para>Note that
<citerefentry><refentrytitle>systemd-run
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
434 with its
<option>--machine=
</option> switch may be used in place of the
<command>machinectl shell
</command>
435 command, and allows non-interactive operation, more detailed and low-level configuration of the invoked unit,
436 as well as access to runtime and exit code/status information of the invoked shell process. In particular, use
437 <command>systemd-run
</command>'s
<option>--wait
</option> switch to propagate exit status information of the
438 invoked process. Use
<command>systemd-run
</command>'s
<option>--pty
</option> switch for acquiring an
439 interactive shell, similar to
<command>machinectl shell
</command>. In general,
<command>systemd-run
</command>
440 is preferable for scripting purposes. However, note that
<command>systemd-run
</command> might require higher
441 privileges than
<command>machinectl shell
</command>.
</para></listitem>
445 <term><command>enable
</command> <replaceable>NAME
</replaceable>…
</term>
446 <term><command>disable
</command> <replaceable>NAME
</replaceable>…
</term>
448 <listitem><para>Enable or disable a container as a system
449 service to start at system boot, using
450 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
451 This enables or disables
452 <filename>systemd-nspawn@.service
</filename>, instantiated for
453 the specified machine name, similar to the effect of
454 <command>systemctl enable
</command> or
<command>systemctl
455 disable
</command> on the service name.
</para></listitem>
459 <term><command>poweroff
</command> <replaceable>NAME
</replaceable>…
</term>
461 <listitem><para>Power off one or more containers. This will
462 trigger a reboot by sending SIGRTMIN+
4 to the container's init
463 process, which causes systemd-compatible init systems to shut
464 down cleanly. Use
<command>stop
</command> as alias for
<command>poweroff
</command>.
465 This operation does not work on containers that do not run a
466 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>-compatible
467 init system, such as sysvinit. Use
468 <command>terminate
</command> (see below) to immediately
469 terminate a container or VM, without cleanly shutting it
470 down.
</para></listitem>
474 <term><command>reboot
</command> <replaceable>NAME
</replaceable>…
</term>
476 <listitem><para>Reboot one or more containers. This will
477 trigger a reboot by sending SIGINT to the container's init
478 process, which is roughly equivalent to pressing Ctrl+Alt+Del
479 on a non-containerized system, and is compatible with
480 containers running any system manager.
</para></listitem>
484 <term><command>terminate
</command> <replaceable>NAME
</replaceable>…
</term>
486 <listitem><para>Immediately terminates a virtual machine or
487 container, without cleanly shutting it down. This kills all
488 processes of the virtual machine or container and deallocates
489 all resources attached to that instance. Use
490 <command>poweroff
</command> to issue a clean shutdown
491 request.
</para></listitem>
495 <term><command>kill
</command> <replaceable>NAME
</replaceable>…
</term>
497 <listitem><para>Send a signal to one or more processes of the
498 virtual machine or container. This means processes as seen by
499 the host, not the processes inside the virtual machine or
500 container. Use
<option>--kill-who=
</option> to select which
501 process to kill. Use
<option>--signal=
</option> to select the
502 signal to send.
</para></listitem>
506 <term><command>bind
</command> <replaceable>NAME
</replaceable> <replaceable>PATH
</replaceable> [
<replaceable>PATH
</replaceable>]
</term>
508 <listitem><para>Bind mounts a file or directory from the host into the specified container. The first path
509 argument is the source file or directory on the host, the second path argument is the destination file or
510 directory in the container. When the latter is omitted, the destination path in the container is the same as
511 the source path on the host. When combined with the
<option>--read-only
</option> switch, a ready-only bind
512 mount is created. When combined with the
<option>--mkdir
</option> switch, the destination path is first created
513 before the mount is applied. Note that this option is currently only supported for
514 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry> containers,
515 and only if user namespacing (
<option>--private-users
</option>) is not used. This command supports bind
516 mounting directories, regular files, device nodes,
<constant>AF_UNIX
</constant> socket nodes, as well as
517 FIFOs.
</para></listitem>
521 <term><command>copy-to
</command> <replaceable>NAME
</replaceable> <replaceable>PATH
</replaceable> [
<replaceable>PATH
</replaceable>]
</term>
523 <listitem><para>Copies files or directories from the host
524 system into a running container. Takes a container name,
525 followed by the source path on the host and the destination
526 path in the container. If the destination path is omitted, the
527 same as the source path is used.
</para>
529 <para>If host and container share the same user and group namespace, file ownership by numeric user ID and
530 group ID is preserved for the copy, otherwise all files and directories in the copy will be owned by the root
531 user and group (UID/GID
0).
</para></listitem>
535 <term><command>copy-from
</command> <replaceable>NAME
</replaceable> <replaceable>PATH
</replaceable> [
<replaceable>PATH
</replaceable>]
</term>
537 <listitem><para>Copies files or directories from a container
538 into the host system. Takes a container name, followed by the
539 source path in the container the destination path on the host.
540 If the destination path is omitted, the same as the source path
543 <para>If host and container share the same user and group namespace, file ownership by numeric user ID and
544 group ID is preserved for the copy, otherwise all files and directories in the copy will be owned by the root
545 user and group (UID/GID
0).
</para></listitem>
547 </variablelist></refsect2>
549 <refsect2><title>Image Commands
</title><variablelist>
552 <term><command>list-images
</command></term>
554 <listitem><para>Show a list of locally installed container and
555 VM images. This enumerates all raw disk images and container
556 directories and subvolumes in
557 <filename>/var/lib/machines/
</filename> (and other search
558 paths, see below). Use
<command>start
</command> (see above) to
559 run a container off one of the listed images. Note that, by
560 default, containers whose name begins with a dot
561 (
<literal>.
</literal>) are not shown. To show these too,
562 specify
<option>--all
</option>. Note that a special image
563 <literal>.host
</literal> always implicitly exists and refers
564 to the image the host itself is booted from.
</para></listitem>
568 <term><command>image-status
</command> [
<replaceable>NAME
</replaceable>…]
</term>
570 <listitem><para>Show terse status information about one or
571 more container or VM images. This function is intended to
572 generate human-readable output. Use
573 <command>show-image
</command> (see below) to generate
574 computer-parsable output instead.
</para></listitem>
578 <term><command>show-image
</command> [
<replaceable>NAME
</replaceable>…]
</term>
580 <listitem><para>Show properties of one or more registered
581 virtual machine or container images, or the manager itself. If
582 no argument is specified, properties of the manager will be
583 shown. If a NAME is specified, properties of this virtual
584 machine or container image are shown. By default, empty
585 properties are suppressed. Use
<option>--all
</option> to show
586 those too. To select specific properties to show, use
587 <option>--property=
</option>. This command is intended to be
588 used whenever computer-parsable output is required. Use
589 <command>image-status
</command> if you are looking for
590 formatted human-readable output.
</para></listitem>
594 <term><command>clone
</command> <replaceable>NAME
</replaceable> <replaceable>NAME
</replaceable></term>
596 <listitem><para>Clones a container or VM image. The arguments specify the name of the image to clone and the
597 name of the newly cloned image. Note that plain directory container images are cloned into btrfs subvolume
598 images with this command, if the underlying file system supports this. Note that cloning a container or VM
599 image is optimized for file systems that support copy-on-write, and might not be efficient on others, due to
600 file system limitations.
</para>
602 <para>Note that this command leaves host name, machine ID and
603 all other settings that could identify the instance
604 unmodified. The original image and the cloned copy will hence
605 share these credentials, and it might be necessary to manually
606 change them in the copy.
</para>
608 <para>If combined with the
<option>--read-only
</option> switch a read-only cloned image is
609 created.
</para></listitem>
613 <term><command>rename
</command> <replaceable>NAME
</replaceable> <replaceable>NAME
</replaceable></term>
615 <listitem><para>Renames a container or VM image. The
616 arguments specify the name of the image to rename and the new
617 name of the image.
</para></listitem>
621 <term><command>read-only
</command> <replaceable>NAME
</replaceable> [
<replaceable>BOOL
</replaceable>]
</term>
623 <listitem><para>Marks or (unmarks) a container or VM image
624 read-only. Takes a VM or container image name, followed by a
625 boolean as arguments. If the boolean is omitted, positive is
626 implied, i.e. the image is marked read-only.
</para></listitem>
630 <term><command>remove
</command> <replaceable>NAME
</replaceable>…
</term>
632 <listitem><para>Removes one or more container or VM images.
633 The special image
<literal>.host
</literal>, which refers to
634 the host's own directory tree, may not be
635 removed.
</para></listitem>
639 <term><command>set-limit
</command> [
<replaceable>NAME
</replaceable>]
<replaceable>BYTES
</replaceable></term>
641 <listitem><para>Sets the maximum size in bytes that a specific
642 container or VM image, or all images, may grow up to on disk
643 (disk quota). Takes either one or two parameters. The first,
644 optional parameter refers to a container or VM image name. If
645 specified, the size limit of the specified image is changed. If
646 omitted, the overall size limit of the sum of all images stored
647 locally is changed. The final argument specifies the size
648 limit in bytes, possibly suffixed by the usual K, M, G, T
649 units. If the size limit shall be disabled, specify
650 <literal>-
</literal> as size.
</para>
652 <para>Note that per-container size limits are only supported
653 on btrfs file systems. Also note that, if
654 <command>set-limit
</command> is invoked without an image
655 parameter, and
<filename>/var/lib/machines
</filename> is
656 empty, and the directory is not located on btrfs, a btrfs
657 loopback file is implicitly created as
658 <filename>/var/lib/machines.raw
</filename> with the given
660 <filename>/var/lib/machines
</filename>. The size of the
661 loopback may later be readjusted with
662 <command>set-limit
</command>, as well. If such a
663 loopback-mounted
<filename>/var/lib/machines
</filename>
664 directory is used,
<command>set-limit
</command> without an image
665 name alters both the quota setting within the file system as
666 well as the loopback file and file system size
667 itself.
</para></listitem>
671 <term><command>clean
</command></term>
673 <listitem><para>Remove hidden VM or container images (or all). This command removes all hidden machine images
674 from
<filename>/var/lib/machines
</filename>, i.e. those whose name begins with a dot. Use
<command>machinectl
675 list-images --all
</command> to see a list of all machine images, including the hidden ones.
</para>
677 <para>When combined with the
<option>--all
</option> switch removes all images, not just hidden ones. This
678 command effectively empties
<filename>/var/lib/machines
</filename>.
</para>
680 <para>Note that commands such as
<command>machinectl pull-tar
</command> or
<command>machinectl
681 pull-raw
</command> usually create hidden, read-only, unmodified machine images from the downloaded image first,
682 before cloning a writable working copy of it, in order to avoid duplicate downloads in case of images that are
683 reused multiple times. Use
<command>machinectl clean
</command> to remove old, hidden images created this
684 way.
</para></listitem>
687 </variablelist></refsect2>
689 <refsect2><title>Image Transfer Commands
</title><variablelist>
692 <term><command>pull-tar
</command> <replaceable>URL
</replaceable> [
<replaceable>NAME
</replaceable>]
</term>
694 <listitem><para>Downloads a
<filename>.tar
</filename>
695 container image from the specified URL, and makes it available
696 under the specified local machine name. The URL must be of
697 type
<literal>http://
</literal> or
698 <literal>https://
</literal>, and must refer to a
699 <filename>.tar
</filename>,
<filename>.tar.gz
</filename>,
700 <filename>.tar.xz
</filename> or
<filename>.tar.bz2
</filename>
701 archive file. If the local machine name is omitted, it
702 is automatically derived from the last component of the URL,
703 with its suffix removed.
</para>
705 <para>The image is verified before it is made available, unless
706 <option>--verify=no
</option> is specified.
707 Verification is done either via an inline signed file with the name
708 of the image and the suffix
<filename>.sha256
</filename> or via
709 separate
<filename>SHA256SUMS
</filename> and
710 <filename>SHA256SUMS.gpg
</filename> files.
711 The signature files need to be made available on the same web
712 server, under the same URL as the
<filename>.tar
</filename> file.
713 With
<option>--verify=checksum
</option>, only the SHA256 checksum
714 for the file is verified, based on the
<filename>.sha256
</filename>
715 suffixed file or the
<filename>SHA256SUMS
</filename> file.
716 With
<option>--verify=signature
</option>, the sha checksum file is
717 first verified with the inline signature in the
718 <filename>.sha256
</filename> file or the detached GPG signature file
719 <filename>SHA256SUMS.gpg
</filename>.
720 The public key for this verification step needs to be available in
721 <filename>/usr/lib/systemd/import-pubring.gpg
</filename> or
722 <filename>/etc/systemd/import-pubring.gpg
</filename>.
</para>
724 <para>The container image will be downloaded and stored in a
725 read-only subvolume in
726 <filename>/var/lib/machines/
</filename> that is named after
727 the specified URL and its HTTP etag. A writable snapshot is
728 then taken from this subvolume, and named after the specified
729 local name. This behavior ensures that creating multiple
730 container instances of the same URL is efficient, as multiple
731 downloads are not necessary. In order to create only the
732 read-only image, and avoid creating its writable snapshot,
733 specify
<literal>-
</literal> as local machine name.
</para>
735 <para>Note that the read-only subvolume is prefixed with
736 <filename>.tar-
</filename>, and is thus not shown by
737 <command>list-images
</command>, unless
<option>--all
</option>
740 <para>Note that pressing C-c during execution of this command
741 will not abort the download. Use
742 <command>cancel-transfer
</command>, described
743 below.
</para></listitem>
747 <term><command>pull-raw
</command> <replaceable>URL
</replaceable> [
<replaceable>NAME
</replaceable>]
</term>
749 <listitem><para>Downloads a
<filename>.raw
</filename>
750 container or VM disk image from the specified URL, and makes
751 it available under the specified local machine name. The URL
752 must be of type
<literal>http://
</literal> or
753 <literal>https://
</literal>. The container image must either
754 be a
<filename>.qcow2
</filename> or raw disk image, optionally
755 compressed as
<filename>.gz
</filename>,
756 <filename>.xz
</filename>, or
<filename>.bz2
</filename>. If the
757 local machine name is omitted, it is automatically
758 derived from the last component of the URL, with its suffix
761 <para>Image verification is identical for raw and tar images
764 <para>If the downloaded image is in
765 <filename>.qcow2
</filename> format it is converted into a raw
766 image file before it is made available.
</para>
768 <para>Downloaded images of this type will be placed as
769 read-only
<filename>.raw
</filename> file in
770 <filename>/var/lib/machines/
</filename>. A local, writable
771 (reflinked) copy is then made under the specified local
772 machine name. To omit creation of the local, writable copy
773 pass
<literal>-
</literal> as local machine name.
</para>
775 <para>Similar to the behavior of
<command>pull-tar
</command>,
776 the read-only image is prefixed with
777 <filename>.raw-
</filename>, and thus not shown by
778 <command>list-images
</command>, unless
<option>--all
</option>
781 <para>Note that pressing C-c during execution of this command
782 will not abort the download. Use
783 <command>cancel-transfer
</command>, described
784 below.
</para></listitem>
788 <term><command>import-tar
</command> <replaceable>FILE
</replaceable> [
<replaceable>NAME
</replaceable>]
</term>
789 <term><command>import-raw
</command> <replaceable>FILE
</replaceable> [
<replaceable>NAME
</replaceable>]
</term>
790 <listitem><para>Imports a TAR or RAW container or VM image,
791 and places it under the specified name in
792 <filename>/var/lib/machines/
</filename>. When
793 <command>import-tar
</command> is used, the file specified as
794 the first argument should be a tar archive, possibly compressed
795 with xz, gzip or bzip2. It will then be unpacked into its own
796 subvolume in
<filename>/var/lib/machines
</filename>. When
797 <command>import-raw
</command> is used, the file should be a
798 qcow2 or raw disk image, possibly compressed with xz, gzip or
799 bzip2. If the second argument (the resulting image name) is
800 not specified, it is automatically derived from the file
801 name. If the filename is passed as
<literal>-
</literal>, the
802 image is read from standard input, in which case the second
803 argument is mandatory.
</para>
805 <para>Both
<command>pull-tar
</command> and
<command>pull-raw
</command>
806 will resize
<filename>/var/lib/machines.raw
</filename> and the
807 filesystem therein as necessary. Optionally, the
808 <option>--read-only
</option> switch may be used to create a
809 read-only container or VM image. No cryptographic validation
810 is done when importing the images.
</para>
812 <para>Much like image downloads, ongoing imports may be listed
813 with
<command>list-transfers
</command> and aborted with
814 <command>cancel-transfer
</command>.
</para></listitem>
818 <term><command>export-tar
</command> <replaceable>NAME
</replaceable> [
<replaceable>FILE
</replaceable>]
</term>
819 <term><command>export-raw
</command> <replaceable>NAME
</replaceable> [
<replaceable>FILE
</replaceable>]
</term>
820 <listitem><para>Exports a TAR or RAW container or VM image and
821 stores it in the specified file. The first parameter should be
822 a VM or container image name. The second parameter should be a
823 file path the TAR or RAW image is written to. If the path ends
824 in
<literal>.gz
</literal>, the file is compressed with gzip, if
825 it ends in
<literal>.xz
</literal>, with xz, and if it ends in
826 <literal>.bz2
</literal>, with bzip2. If the path ends in
827 neither, the file is left uncompressed. If the second argument
828 is missing, the image is written to standard output. The
829 compression may also be explicitly selected with the
830 <option>--format=
</option> switch. This is in particular
831 useful if the second parameter is left unspecified.
</para>
833 <para>Much like image downloads and imports, ongoing exports
834 may be listed with
<command>list-transfers
</command> and
836 <command>cancel-transfer
</command>.
</para>
838 <para>Note that, currently, only directory and subvolume images
839 may be exported as TAR images, and only raw disk images as RAW
840 images.
</para></listitem>
844 <term><command>list-transfers
</command></term>
846 <listitem><para>Shows a list of container or VM image
847 downloads, imports and exports that are currently in
848 progress.
</para></listitem>
852 <term><command>cancel-transfer
</command> <replaceable>ID
</replaceable>…
</term>
854 <listitem><para>Aborts a download, import or export of the
855 container or VM image with the specified ID. To list ongoing
856 transfers and their IDs, use
857 <command>list-transfers
</command>.
</para></listitem>
860 </variablelist></refsect2>
865 <title>Machine and Image Names
</title>
867 <para>The
<command>machinectl
</command> tool operates on machines
868 and images whose names must be chosen following strict
869 rules. Machine names must be suitable for use as host names
870 following a conservative subset of DNS and UNIX/Linux
871 semantics. Specifically, they must consist of one or more
872 non-empty label strings, separated by dots. No leading or trailing
873 dots are allowed. No sequences of multiple dots are allowed. The
874 label strings may only consist of alphanumeric characters as well
875 as the dash and underscore. The maximum length of a machine name
876 is
64 characters.
</para>
878 <para>A special machine with the name
<literal>.host
</literal>
879 refers to the running host system itself. This is useful for execution
880 operations or inspecting the host system as well. Note that
881 <command>machinectl list
</command> will not show this special
882 machine unless the
<option>--all
</option> switch is specified.
</para>
884 <para>Requirements on image names are less strict, however, they must be
885 valid UTF-
8, must be suitable as file names (hence not be the
886 single or double dot, and not include a slash), and may not
887 contain control characters. Since many operations search for an
888 image by the name of a requested machine, it is recommended to name
889 images in the same strict fashion as machines.
</para>
891 <para>A special image with the name
<literal>.host
</literal>
892 refers to the image of the running host system. It hence
893 conceptually maps to the special
<literal>.host
</literal> machine
894 name described above. Note that
<command>machinectl
895 list-images
</command> will not show this special image either, unless
896 <option>--all
</option> is specified.
</para>
900 <title>Files and Directories
</title>
902 <para>Machine images are preferably stored in
903 <filename>/var/lib/machines/
</filename>, but are also searched for
904 in
<filename>/usr/local/lib/machines/
</filename> and
905 <filename>/usr/lib/machines/
</filename>. For compatibility reasons,
906 the directory
<filename>/var/lib/container/
</filename> is
907 searched, too. Note that images stored below
908 <filename>/usr
</filename> are always considered read-only. It is
909 possible to symlink machines images from other directories into
910 <filename>/var/lib/machines/
</filename> to make them available for
911 control with
<command>machinectl
</command>.
</para>
913 <para>Note that some image operations are only supported,
914 efficient or atomic on btrfs file systems. Due to this, if the
915 <command>pull-tar
</command>,
<command>pull-raw
</command>,
916 <command>import-tar
</command>,
<command>import-raw
</command> and
917 <command>set-limit
</command> commands notice that
918 <filename>/var/lib/machines
</filename> is empty and not located on
919 btrfs, they will implicitly set up a loopback file
920 <filename>/var/lib/machines.raw
</filename> containing a btrfs file
921 system that is mounted to
922 <filename>/var/lib/machines
</filename>. The size of this loopback
923 file may be controlled dynamically with
924 <command>set-limit
</command>.
</para>
926 <para>Disk images are understood by
927 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
928 and
<command>machinectl
</command> in three formats:
</para>
931 <listitem><para>A simple directory tree, containing the files
932 and directories of the container to boot.
</para></listitem>
934 <listitem><para>Subvolumes (on btrfs file systems), which are
935 similar to the simple directories, described above. However,
936 they have additional benefits, such as efficient cloning and
937 quota reporting.
</para></listitem>
939 <listitem><para>"Raw" disk images, i.e. binary images of disks
940 with a GPT or MBR partition table. Images of this type are
941 regular files with the suffix
942 <literal>.raw
</literal>.
</para></listitem>
946 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
947 for more information on image formats, in particular its
948 <option>--directory=
</option> and
<option>--image=
</option>
953 <title>Examples
</title>
955 <title>Download an Ubuntu image and open a shell in it
</title>
957 <programlisting># machinectl pull-tar https://cloud-images.ubuntu.com/trusty/current/trusty-server-cloudimg-amd64-root.tar.gz
958 # systemd-nspawn -M trusty-server-cloudimg-amd64-root
</programlisting>
960 <para>This downloads and verifies the specified
961 <filename>.tar
</filename> image, and then uses
962 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
963 to open a shell in it.
</para>
967 <title>Download a Fedora image, set a root password in it, start
968 it as service
</title>
970 <programlisting># machinectl pull-raw --verify=no https://dl.fedoraproject.org/pub/fedora/linux/releases/
27/CloudImages/x86_64/images/Fedora-Cloud-Base-
27-
1.6.x86_64.raw.xz
971 # systemd-nspawn -M Fedora-Cloud-Base-
27-
1.6.x86_64
974 # machinectl start Fedora-Cloud-Base-
27-
1.6.x86_64
975 # machinectl login Fedora-Cloud-Base-
27-
1.6.x86_64
</programlisting>
977 <para>This downloads the specified
<filename>.raw
</filename>
978 image with verification disabled. Then, a shell is opened in it
979 and a root password is set. Afterwards the shell is left, and
980 the machine started as system service. With the last command a
981 login prompt into the container is requested.
</para>
985 <title>Exports a container image as tar file
</title>
987 <programlisting># machinectl export-tar fedora myfedora.tar.xz
</programlisting>
989 <para>Exports the container
<literal>fedora
</literal> as an
990 xz-compressed tar file
<filename>myfedora.tar.xz
</filename> into the
991 current directory.
</para>
995 <title>Create a new shell session
</title>
997 <programlisting># machinectl shell --uid=lennart
</programlisting>
999 <para>This creates a new shell session on the local host for
1000 the user ID
<literal>lennart
</literal>, in a
<citerefentry
1001 project='die-net'
><refentrytitle>su
</refentrytitle><manvolnum>1</manvolnum></citerefentry>-like
1008 <title>Exit status
</title>
1010 <para>On success,
0 is returned, a non-zero failure code
1014 <xi:include href=
"less-variables.xml" />
1017 <title>See Also
</title>
1019 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1020 <citerefentry><refentrytitle>systemd-machined.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
1021 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1022 <citerefentry><refentrytitle>systemd.special
</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1023 <citerefentry project='die-net'
><refentrytitle>tar
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1024 <citerefentry project='die-net'
><refentrytitle>xz
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1025 <citerefentry project='die-net'
><refentrytitle>gzip
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1026 <citerefentry project='die-net'
><refentrytitle>bzip2
</refentrytitle><manvolnum>1</manvolnum></citerefentry>