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 hostnames. 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>Commands
</title>
85 <para>The following commands are understood:
</para>
87 <refsect2><title>Machine Commands
</title><variablelist>
90 <term><command>list
</command></term>
92 <listitem><para>List currently running (online) virtual
93 machines and containers. To enumerate machine images that can
94 be started, use
<command>list-images
</command> (see
95 below). Note that this command hides the special
96 <literal>.host
</literal> machine by default. Use the
97 <option>--all
</option> switch to show it.
</para></listitem>
101 <term><command>status
</command> <replaceable>NAME
</replaceable>…
</term>
103 <listitem><para>Show runtime status information about
104 one or more virtual machines and containers, followed by the
105 most recent log data from the journal. This function is
106 intended to generate human-readable output. If you are looking
107 for computer-parsable output, use
<command>show
</command>
108 instead. Note that the log data shown is reported by the
109 virtual machine or container manager, and frequently contains
110 console output of the machine, but not necessarily journal
111 contents of the machine itself.
</para></listitem>
115 <term><command>show
</command> [
<replaceable>NAME
</replaceable>…]
</term>
117 <listitem><para>Show properties of one or more registered virtual machines or containers or the manager
118 itself. If no argument is specified, properties of the manager will be shown. If a NAME is specified,
119 properties of this virtual machine or container are shown. By default, empty properties are suppressed. Use
120 <option>--all
</option> to show those too. To select specific properties to show, use
121 <option>--property=
</option>. This command is intended to be used whenever computer-parsable output is
122 required, and does not print the control group tree or journal entries. Use
<command>status
</command> if you
123 are looking for formatted human-readable output.
</para></listitem>
127 <term><command>start
</command> <replaceable>NAME
</replaceable>…
</term>
129 <listitem><para>Start a container as a system service, using
130 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
131 This starts
<filename>systemd-nspawn@.service
</filename>,
132 instantiated for the specified machine name, similar to the
133 effect of
<command>systemctl start
</command> on the service
134 name.
<command>systemd-nspawn
</command> looks for a container
135 image by the specified name in
136 <filename>/var/lib/machines/
</filename> (and other search
137 paths, see below) and runs it. Use
138 <command>list-images
</command> (see below) for listing
139 available container images to start.
</para>
142 <citerefentry><refentrytitle>systemd-machined.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
143 also interfaces with a variety of other container and VM
144 managers,
<command>systemd-nspawn
</command> is just one
145 implementation of it. Most of the commands available in
146 <command>machinectl
</command> may be used on containers or VMs
147 controlled by other managers, not just
148 <command>systemd-nspawn
</command>. Starting VMs and container
149 images on those managers requires manager-specific
152 <para>To interactively start a container on the command line
153 with full access to the container's console, please invoke
154 <command>systemd-nspawn
</command> directly. To stop a running
155 container use
<command>machinectl poweroff
</command>.
</para></listitem>
159 <term><command>login
</command> [
<replaceable>NAME
</replaceable>]
</term>
161 <listitem><para>Open an interactive terminal login session in
162 a container or on the local host. If an argument is supplied,
163 it refers to the container machine to connect to. If none is
164 specified, or the container name is specified as the empty
165 string, or the special machine name
<literal>.host
</literal>
166 (see below) is specified, the connection is made to the local
167 host instead. This will create a TTY connection to a specific
168 container or the local host and asks for the execution of a
169 getty on it. Note that this is only supported for containers
171 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
172 as init system.
</para>
174 <para>This command will open a full login prompt on the
175 container or the local host, which then asks for username and
176 password. Use
<command>shell
</command> (see below) or
177 <citerefentry><refentrytitle>systemd-run
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
178 with the
<option>--machine=
</option> switch to directly invoke
179 a single command, either interactively or in the
180 background.
</para></listitem>
184 <term><command>shell
</command> [[
<replaceable>NAME
</replaceable>@]
<replaceable>NAME
</replaceable> [
<replaceable>PATH
</replaceable> [
<replaceable>ARGUMENTS
</replaceable>…]]]
</term>
186 <listitem><para>Open an interactive shell session in a
187 container or on the local host. The first argument refers to
188 the container machine to connect to. If none is specified, or
189 the machine name is specified as the empty string, or the
190 special machine name
<literal>.host
</literal> (see below) is
191 specified, the connection is made to the local host
192 instead. This works similar to
<command>login
</command> but
193 immediately invokes a user process. This command runs the
194 specified executable with the specified arguments, or the
195 default shell for the user if none is specified, or
196 <filename>/bin/sh
</filename> if no default shell is found. By default,
197 <option>--uid=
</option>, or by prefixing the machine name with
198 a username and an
<literal>@
</literal> character, a different
199 user may be selected. Use
<option>--setenv=
</option> to set
200 environment variables for the executed process.
</para>
202 <para>Note that
<command>machinectl shell
</command> does not propagate the exit code/status of the invoked
203 shell process. Use
<command>systemd-run
</command> instead if that information is required (see below).
</para>
205 <para>When using the
<command>shell
</command> command without
206 arguments, (thus invoking the executed shell or command on the
207 local host), it is in many ways similar to a
<citerefentry
208 project='die-net'
><refentrytitle>su
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
209 session, but, unlike
<command>su
</command>, completely isolates
210 the new session from the originating session, so that it
211 shares no process or session properties, and is in a clean and
212 well-defined state. It will be tracked in a new utmp, login,
213 audit, security and keyring session, and will not inherit any
214 environment variables or resource limits, among other
217 <para>Note that
<citerefentry><refentrytitle>systemd-run
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
218 with its
<option>--machine=
</option> switch may be used in place of the
<command>machinectl shell
</command>
219 command, and allows non-interactive operation, more detailed and low-level configuration of the invoked unit,
220 as well as access to runtime and exit code/status information of the invoked shell process. In particular, use
221 <command>systemd-run
</command>'s
<option>--wait
</option> switch to propagate exit status information of the
222 invoked process. Use
<command>systemd-run
</command>'s
<option>--pty
</option> switch for acquiring an
223 interactive shell, similar to
<command>machinectl shell
</command>. In general,
<command>systemd-run
</command>
224 is preferable for scripting purposes. However, note that
<command>systemd-run
</command> might require higher
225 privileges than
<command>machinectl shell
</command>.
</para></listitem>
229 <term><command>enable
</command> <replaceable>NAME
</replaceable>…
</term>
230 <term><command>disable
</command> <replaceable>NAME
</replaceable>…
</term>
232 <listitem><para>Enable or disable a container as a system
233 service to start at system boot, using
234 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
235 This enables or disables
236 <filename>systemd-nspawn@.service
</filename>, instantiated for
237 the specified machine name, similar to the effect of
238 <command>systemctl enable
</command> or
<command>systemctl
239 disable
</command> on the service name.
</para></listitem>
243 <term><command>poweroff
</command> <replaceable>NAME
</replaceable>…
</term>
245 <listitem><para>Power off one or more containers. This will
246 trigger a reboot by sending SIGRTMIN+
4 to the container's init
247 process, which causes systemd-compatible init systems to shut
248 down cleanly. Use
<command>stop
</command> as alias for
<command>poweroff
</command>.
249 This operation does not work on containers that do not run a
250 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>-compatible
251 init system, such as sysvinit. Use
252 <command>terminate
</command> (see below) to immediately
253 terminate a container or VM, without cleanly shutting it
254 down.
</para></listitem>
258 <term><command>reboot
</command> <replaceable>NAME
</replaceable>…
</term>
260 <listitem><para>Reboot one or more containers. This will
261 trigger a reboot by sending SIGINT to the container's init
262 process, which is roughly equivalent to pressing Ctrl+Alt+Del
263 on a non-containerized system, and is compatible with
264 containers running any system manager.
</para></listitem>
268 <term><command>terminate
</command> <replaceable>NAME
</replaceable>…
</term>
270 <listitem><para>Immediately terminates a virtual machine or
271 container, without cleanly shutting it down. This kills all
272 processes of the virtual machine or container and deallocates
273 all resources attached to that instance. Use
274 <command>poweroff
</command> to issue a clean shutdown
275 request.
</para></listitem>
279 <term><command>kill
</command> <replaceable>NAME
</replaceable>…
</term>
281 <listitem><para>Send a signal to one or more processes of the
282 virtual machine or container. This means processes as seen by
283 the host, not the processes inside the virtual machine or
284 container. Use
<option>--kill-who=
</option> to select which
285 process to kill. Use
<option>--signal=
</option> to select the
286 signal to send.
</para></listitem>
290 <term><command>bind
</command> <replaceable>NAME
</replaceable> <replaceable>PATH
</replaceable> [
<replaceable>PATH
</replaceable>]
</term>
292 <listitem><para>Bind mounts a file or directory from the host into the specified container. The first path
293 argument is the source file or directory on the host, the second path argument is the destination file or
294 directory in the container. When the latter is omitted, the destination path in the container is the same as
295 the source path on the host. When combined with the
<option>--read-only
</option> switch, a ready-only bind
296 mount is created. When combined with the
<option>--mkdir
</option> switch, the destination path is first created
297 before the mount is applied. Note that this option is currently only supported for
298 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry> containers,
299 and only if user namespacing (
<option>--private-users
</option>) is not used. This command supports bind
300 mounting directories, regular files, device nodes,
<constant>AF_UNIX
</constant> socket nodes, as well as
301 FIFOs.
</para></listitem>
305 <term><command>copy-to
</command> <replaceable>NAME
</replaceable> <replaceable>PATH
</replaceable> [
<replaceable>PATH
</replaceable>]
</term>
307 <listitem><para>Copies files or directories from the host
308 system into a running container. Takes a container name,
309 followed by the source path on the host and the destination
310 path in the container. If the destination path is omitted, the
311 same as the source path is used.
</para>
313 <para>If host and container share the same user and group namespace, file ownership by numeric user ID and
314 group ID is preserved for the copy, otherwise all files and directories in the copy will be owned by the root
315 user and group (UID/GID
0).
</para></listitem>
319 <term><command>copy-from
</command> <replaceable>NAME
</replaceable> <replaceable>PATH
</replaceable> [
<replaceable>PATH
</replaceable>]
</term>
321 <listitem><para>Copies files or directories from a container
322 into the host system. Takes a container name, followed by the
323 source path in the container and the destination path on the host.
324 If the destination path is omitted, the same as the source path
327 <para>If host and container share the same user and group namespace, file ownership by numeric user ID and
328 group ID is preserved for the copy, otherwise all files and directories in the copy will be owned by the root
329 user and group (UID/GID
0).
</para></listitem>
331 </variablelist></refsect2>
333 <refsect2><title>Image Commands
</title><variablelist>
336 <term><command>list-images
</command></term>
338 <listitem><para>Show a list of locally installed container and
339 VM images. This enumerates all raw disk images and container
340 directories and subvolumes in
341 <filename>/var/lib/machines/
</filename> (and other search
342 paths, see below). Use
<command>start
</command> (see above) to
343 run a container off one of the listed images. Note that, by
344 default, containers whose name begins with a dot
345 (
<literal>.
</literal>) are not shown. To show these too,
346 specify
<option>--all
</option>. Note that a special image
347 <literal>.host
</literal> always implicitly exists and refers
348 to the image the host itself is booted from.
</para></listitem>
352 <term><command>image-status
</command> [
<replaceable>NAME
</replaceable>…]
</term>
354 <listitem><para>Show terse status information about one or
355 more container or VM images. This function is intended to
356 generate human-readable output. Use
357 <command>show-image
</command> (see below) to generate
358 computer-parsable output instead.
</para></listitem>
362 <term><command>show-image
</command> [
<replaceable>NAME
</replaceable>…]
</term>
364 <listitem><para>Show properties of one or more registered
365 virtual machine or container images, or the manager itself. If
366 no argument is specified, properties of the manager will be
367 shown. If a NAME is specified, properties of this virtual
368 machine or container image are shown. By default, empty
369 properties are suppressed. Use
<option>--all
</option> to show
370 those too. To select specific properties to show, use
371 <option>--property=
</option>. This command is intended to be
372 used whenever computer-parsable output is required. Use
373 <command>image-status
</command> if you are looking for
374 formatted human-readable output.
</para></listitem>
378 <term><command>clone
</command> <replaceable>NAME
</replaceable> <replaceable>NAME
</replaceable></term>
380 <listitem><para>Clones a container or VM image. The arguments specify the name of the image to clone and the
381 name of the newly cloned image. Note that plain directory container images are cloned into btrfs subvolume
382 images with this command, if the underlying file system supports this. Note that cloning a container or VM
383 image is optimized for file systems that support copy-on-write, and might not be efficient on others, due to
384 file system limitations.
</para>
386 <para>Note that this command leaves hostname, machine ID and
387 all other settings that could identify the instance
388 unmodified. The original image and the cloned copy will hence
389 share these credentials, and it might be necessary to manually
390 change them in the copy.
</para>
392 <para>If combined with the
<option>--read-only
</option> switch a read-only cloned image is
393 created.
</para></listitem>
397 <term><command>rename
</command> <replaceable>NAME
</replaceable> <replaceable>NAME
</replaceable></term>
399 <listitem><para>Renames a container or VM image. The
400 arguments specify the name of the image to rename and the new
401 name of the image.
</para></listitem>
405 <term><command>read-only
</command> <replaceable>NAME
</replaceable> [
<replaceable>BOOL
</replaceable>]
</term>
407 <listitem><para>Marks or (unmarks) a container or VM image
408 read-only. Takes a VM or container image name, followed by a
409 boolean as arguments. If the boolean is omitted, positive is
410 implied, i.e. the image is marked read-only.
</para></listitem>
414 <term><command>remove
</command> <replaceable>NAME
</replaceable>…
</term>
416 <listitem><para>Removes one or more container or VM images.
417 The special image
<literal>.host
</literal>, which refers to
418 the host's own directory tree, may not be
419 removed.
</para></listitem>
423 <term><command>set-limit
</command> [
<replaceable>NAME
</replaceable>]
<replaceable>BYTES
</replaceable></term>
425 <listitem><para>Sets the maximum size in bytes that a specific
426 container or VM image, or all images, may grow up to on disk
427 (disk quota). Takes either one or two parameters. The first,
428 optional parameter refers to a container or VM image name. If
429 specified, the size limit of the specified image is changed. If
430 omitted, the overall size limit of the sum of all images stored
431 locally is changed. The final argument specifies the size
432 limit in bytes, possibly suffixed by the usual K, M, G, T
433 units. If the size limit shall be disabled, specify
434 <literal>-
</literal> as size.
</para>
436 <para>Note that per-container size limits are only supported on btrfs file systems.
</para></listitem>
440 <term><command>clean
</command></term>
442 <listitem><para>Remove hidden VM or container images (or all). This command removes all hidden machine images
443 from
<filename>/var/lib/machines
</filename>, i.e. those whose name begins with a dot. Use
<command>machinectl
444 list-images --all
</command> to see a list of all machine images, including the hidden ones.
</para>
446 <para>When combined with the
<option>--all
</option> switch removes all images, not just hidden ones. This
447 command effectively empties
<filename>/var/lib/machines
</filename>.
</para>
449 <para>Note that commands such as
<command>machinectl pull-tar
</command> or
<command>machinectl
450 pull-raw
</command> usually create hidden, read-only, unmodified machine images from the downloaded image first,
451 before cloning a writable working copy of it, in order to avoid duplicate downloads in case of images that are
452 reused multiple times. Use
<command>machinectl clean
</command> to remove old, hidden images created this
453 way.
</para></listitem>
456 </variablelist></refsect2>
458 <refsect2><title>Image Transfer Commands
</title><variablelist>
461 <term><command>pull-tar
</command> <replaceable>URL
</replaceable> [
<replaceable>NAME
</replaceable>]
</term>
463 <listitem><para>Downloads a
<filename>.tar
</filename>
464 container image from the specified URL, and makes it available
465 under the specified local machine name. The URL must be of
466 type
<literal>http://
</literal> or
467 <literal>https://
</literal>, and must refer to a
468 <filename>.tar
</filename>,
<filename>.tar.gz
</filename>,
469 <filename>.tar.xz
</filename> or
<filename>.tar.bz2
</filename>
470 archive file. If the local machine name is omitted, it
471 is automatically derived from the last component of the URL,
472 with its suffix removed.
</para>
474 <para>The image is verified before it is made available, unless
475 <option>--verify=no
</option> is specified.
476 Verification is done either via an inline signed file with the name
477 of the image and the suffix
<filename>.sha256
</filename> or via
478 separate
<filename>SHA256SUMS
</filename> and
479 <filename>SHA256SUMS.gpg
</filename> files.
480 The signature files need to be made available on the same web
481 server, under the same URL as the
<filename>.tar
</filename> file.
482 With
<option>--verify=checksum
</option>, only the SHA256 checksum
483 for the file is verified, based on the
<filename>.sha256
</filename>
484 suffixed file or the
<filename>SHA256SUMS
</filename> file.
485 With
<option>--verify=signature
</option>, the sha checksum file is
486 first verified with the inline signature in the
487 <filename>.sha256
</filename> file or the detached GPG signature file
488 <filename>SHA256SUMS.gpg
</filename>.
489 The public key for this verification step needs to be available in
490 <filename>/usr/lib/systemd/import-pubring.gpg
</filename> or
491 <filename>/etc/systemd/import-pubring.gpg
</filename>.
</para>
493 <para>The container image will be downloaded and stored in a
494 read-only subvolume in
495 <filename>/var/lib/machines/
</filename> that is named after
496 the specified URL and its HTTP etag. A writable snapshot is
497 then taken from this subvolume, and named after the specified
498 local name. This behavior ensures that creating multiple
499 container instances of the same URL is efficient, as multiple
500 downloads are not necessary. In order to create only the
501 read-only image, and avoid creating its writable snapshot,
502 specify
<literal>-
</literal> as local machine name.
</para>
504 <para>Note that the read-only subvolume is prefixed with
505 <filename>.tar-
</filename>, and is thus not shown by
506 <command>list-images
</command>, unless
<option>--all
</option>
509 <para>Note that pressing C-c during execution of this command
510 will not abort the download. Use
511 <command>cancel-transfer
</command>, described
512 below.
</para></listitem>
516 <term><command>pull-raw
</command> <replaceable>URL
</replaceable> [
<replaceable>NAME
</replaceable>]
</term>
518 <listitem><para>Downloads a
<filename>.raw
</filename>
519 container or VM disk image from the specified URL, and makes
520 it available under the specified local machine name. The URL
521 must be of type
<literal>http://
</literal> or
522 <literal>https://
</literal>. The container image must either
523 be a
<filename>.qcow2
</filename> or raw disk image, optionally
524 compressed as
<filename>.gz
</filename>,
525 <filename>.xz
</filename>, or
<filename>.bz2
</filename>. If the
526 local machine name is omitted, it is automatically
527 derived from the last component of the URL, with its suffix
530 <para>Image verification is identical for raw and tar images
533 <para>If the downloaded image is in
534 <filename>.qcow2
</filename> format it is converted into a raw
535 image file before it is made available.
</para>
537 <para>Downloaded images of this type will be placed as
538 read-only
<filename>.raw
</filename> file in
539 <filename>/var/lib/machines/
</filename>. A local, writable
540 (reflinked) copy is then made under the specified local
541 machine name. To omit creation of the local, writable copy
542 pass
<literal>-
</literal> as local machine name.
</para>
544 <para>Similar to the behavior of
<command>pull-tar
</command>,
545 the read-only image is prefixed with
546 <filename>.raw-
</filename>, and thus not shown by
547 <command>list-images
</command>, unless
<option>--all
</option>
550 <para>Note that pressing C-c during execution of this command
551 will not abort the download. Use
552 <command>cancel-transfer
</command>, described
553 below.
</para></listitem>
557 <term><command>import-tar
</command> <replaceable>FILE
</replaceable> [
<replaceable>NAME
</replaceable>]
</term>
558 <term><command>import-raw
</command> <replaceable>FILE
</replaceable> [
<replaceable>NAME
</replaceable>]
</term>
559 <listitem><para>Imports a TAR or RAW container or VM image,
560 and places it under the specified name in
561 <filename>/var/lib/machines/
</filename>. When
562 <command>import-tar
</command> is used, the file specified as
563 the first argument should be a tar archive, possibly compressed
564 with xz, gzip or bzip2. It will then be unpacked into its own
565 subvolume in
<filename>/var/lib/machines
</filename>. When
566 <command>import-raw
</command> is used, the file should be a
567 qcow2 or raw disk image, possibly compressed with xz, gzip or
568 bzip2. If the second argument (the resulting image name) is
569 not specified, it is automatically derived from the file
570 name. If the filename is passed as
<literal>-
</literal>, the
571 image is read from standard input, in which case the second
572 argument is mandatory.
</para>
574 <para>Optionally, the
<option>--read-only
</option> switch may be used to create a read-only container or VM
575 image. No cryptographic validation is done when importing the images.
</para>
577 <para>Much like image downloads, ongoing imports may be listed
578 with
<command>list-transfers
</command> and aborted with
579 <command>cancel-transfer
</command>.
</para></listitem>
583 <term><command>import-fs
</command> <replaceable>DIRECTORY
</replaceable> [
<replaceable>NAME
</replaceable>]
</term>
585 <listitem><para>Imports a container image stored in a local directory into
586 <filename>/var/lib/machines/
</filename>, operates similar to
<command>import-tar
</command> or
587 <command>import-raw
</command>, but the first argument is the source directory. If supported, this command will
588 create btrfs snapshot or subvolume for the new image.
</para></listitem>
592 <term><command>export-tar
</command> <replaceable>NAME
</replaceable> [
<replaceable>FILE
</replaceable>]
</term>
593 <term><command>export-raw
</command> <replaceable>NAME
</replaceable> [
<replaceable>FILE
</replaceable>]
</term>
594 <listitem><para>Exports a TAR or RAW container or VM image and
595 stores it in the specified file. The first parameter should be
596 a VM or container image name. The second parameter should be a
597 file path the TAR or RAW image is written to. If the path ends
598 in
<literal>.gz
</literal>, the file is compressed with gzip, if
599 it ends in
<literal>.xz
</literal>, with xz, and if it ends in
600 <literal>.bz2
</literal>, with bzip2. If the path ends in
601 neither, the file is left uncompressed. If the second argument
602 is missing, the image is written to standard output. The
603 compression may also be explicitly selected with the
604 <option>--format=
</option> switch. This is in particular
605 useful if the second parameter is left unspecified.
</para>
607 <para>Much like image downloads and imports, ongoing exports
608 may be listed with
<command>list-transfers
</command> and
610 <command>cancel-transfer
</command>.
</para>
612 <para>Note that, currently, only directory and subvolume images
613 may be exported as TAR images, and only raw disk images as RAW
614 images.
</para></listitem>
618 <term><command>list-transfers
</command></term>
620 <listitem><para>Shows a list of container or VM image
621 downloads, imports and exports that are currently in
622 progress.
</para></listitem>
626 <term><command>cancel-transfer
</command> <replaceable>ID
</replaceable>…
</term>
628 <listitem><para>Aborts a download, import or export of the
629 container or VM image with the specified ID. To list ongoing
630 transfers and their IDs, use
631 <command>list-transfers
</command>.
</para></listitem>
634 </variablelist></refsect2>
639 <title>Options
</title>
641 <para>The following options are understood:
</para>
645 <term><option>-p
</option></term>
646 <term><option>--property=
</option></term>
648 <listitem><para>When showing machine or image properties,
649 limit the output to certain properties as specified by the
650 argument. If not specified, all set properties are shown. The
651 argument should be a property name, such as
652 <literal>Name
</literal>. If specified more than once, all
653 properties with the specified names are
654 shown.
</para></listitem>
658 <term><option>-a
</option></term>
659 <term><option>--all
</option></term>
661 <listitem><para>When showing machine or image properties, show
662 all properties regardless of whether they are set or
665 <para>When listing VM or container images, do not suppress
666 images beginning in a dot character
667 (
<literal>.
</literal>).
</para>
669 <para>When cleaning VM or container images, remove all images, not just hidden ones.
</para></listitem>
673 <term><option>--value
</option></term>
675 <listitem><para>When printing properties with
<command>show
</command>, only print the value,
676 and skip the property name and
<literal>=
</literal>.
</para></listitem>
680 <term><option>-l
</option></term>
681 <term><option>--full
</option></term>
683 <listitem><para>Do not ellipsize process tree entries or table. This implies
684 <option>--max-addresses=full
</option>.
</para>
689 <term><option>--kill-who=
</option></term>
691 <listitem><para>When used with
<command>kill
</command>, choose
692 which processes to kill. Must be one of
693 <option>leader
</option>, or
<option>all
</option> to select
694 whether to kill only the leader process of the machine or all
695 processes of the machine. If omitted, defaults to
696 <option>all
</option>.
</para></listitem>
700 <term><option>-s
</option></term>
701 <term><option>--signal=
</option></term>
703 <listitem><para>When used with
<command>kill
</command>, choose
704 which signal to send to selected processes. Must be one of the
705 well-known signal specifiers, such as
706 <constant>SIGTERM
</constant>,
<constant>SIGINT
</constant> or
707 <constant>SIGSTOP
</constant>. If omitted, defaults to
708 <constant>SIGTERM
</constant>.
</para></listitem>
712 <term><option>--uid=
</option></term>
714 <listitem><para>When used with the
<command>shell
</command> command, chooses the user ID to
715 open the interactive shell session as. If the argument to the
<command>shell
</command>
716 command also specifies a user name, this option is ignored. If the name is not specified
717 in either way,
<literal>root
</literal> will be used by default. Note that this switch is
718 not supported for the
<command>login
</command> command (see below).
</para></listitem>
722 <term><option>-E
<replaceable>NAME
</replaceable>=
<replaceable>VALUE
</replaceable></option></term>
723 <term><option>--setenv=
<replaceable>NAME
</replaceable>=
<replaceable>VALUE
</replaceable></option></term>
725 <listitem><para>When used with the
<command>shell
</command> command, sets an environment
726 variable to pass to the executed shell. Takes an environment variable name and value,
727 separated by
<literal>=
</literal>. This switch may be used multiple times to set multiple
728 environment variables. Note that this switch is not supported for the
729 <command>login
</command> command (see below).
</para></listitem>
733 <term><option>--mkdir
</option></term>
735 <listitem><para>When used with
<command>bind
</command>, creates the destination file or directory before
736 applying the bind mount. Note that even though the name of this option suggests that it is suitable only for
737 directories, this option also creates the destination file node to mount over if the object to mount is not
738 a directory, but a regular file, device node, socket or FIFO.
</para></listitem>
742 <term><option>--read-only
</option></term>
744 <listitem><para>When used with
<command>bind
</command>, creates a read-only bind mount.
</para>
746 <para>When used with
<command>clone
</command>,
<command>import-raw
</command> or
<command>import-tar
</command> a
747 read-only container or VM image is created.
</para></listitem>
751 <term><option>-n
</option></term>
752 <term><option>--lines=
</option></term>
754 <listitem><para>When used with
<command>status
</command>,
755 controls the number of journal lines to show, counting from
756 the most recent ones. Takes a positive integer argument.
757 Defaults to
10.
</para>
762 <term><option>-o
</option></term>
763 <term><option>--output=
</option></term>
765 <listitem><para>When used with
<command>status
</command>,
766 controls the formatting of the journal entries that are shown.
767 For the available choices, see
768 <citerefentry><refentrytitle>journalctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
769 Defaults to
<literal>short
</literal>.
</para></listitem>
773 <term><option>--verify=
</option></term>
775 <listitem><para>When downloading a container or VM image,
776 specify whether the image shall be verified before it is made
777 available. Takes one of
<literal>no
</literal>,
778 <literal>checksum
</literal> and
<literal>signature
</literal>.
779 If
<literal>no
</literal>, no verification is done. If
780 <literal>checksum
</literal> is specified, the download is
781 checked for integrity after the transfer is complete, but no
782 signatures are verified. If
<literal>signature
</literal> is
783 specified, the checksum is verified and the image's signature
784 is checked against a local keyring of trustable vendors. It is
785 strongly recommended to set this option to
786 <literal>signature
</literal> if the server and protocol
787 support this. Defaults to
788 <literal>signature
</literal>.
</para></listitem>
792 <term><option>--force
</option></term>
794 <listitem><para>When downloading a container or VM image, and
795 a local copy by the specified local machine name already
796 exists, delete it first and replace it by the newly downloaded
797 image.
</para></listitem>
801 <term><option>--format=
</option></term>
803 <listitem><para>When used with the
<option>export-tar
</option>
804 or
<option>export-raw
</option> commands, specifies the
805 compression format to use for the resulting file. Takes one of
806 <literal>uncompressed
</literal>,
<literal>xz
</literal>,
807 <literal>gzip
</literal>,
<literal>bzip2
</literal>. By default,
808 the format is determined automatically from the image file
809 name passed.
</para></listitem>
813 <term><option>--max-addresses=
</option></term>
815 <listitem><para>When used with the
<option>list-machines
</option> command, limits the number of ip
816 addresses output for every machine. Defaults to
1. All addresses can be requested with
817 <literal>all
</literal> as argument to
<option>--max-addresses=
</option>. If the argument to
818 <option>--max-addresses=
</option> is less than the actual number of addresses,
819 <literal>…
</literal>follows the last address.
</para></listitem>
823 <term><option>-q
</option></term>
824 <term><option>--quiet
</option></term>
826 <listitem><para>Suppresses additional informational output while running.
</para></listitem>
829 <xi:include href=
"user-system-options.xml" xpointer=
"host" />
832 <term><option>-M
</option></term>
833 <term><option>--machine=
</option></term>
835 <listitem><para>Connect to
836 <citerefentry><refentrytitle>systemd-machined.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
837 running in a local container, to perform the specified operation within
838 the container.
</para></listitem>
841 <xi:include href=
"standard-options.xml" xpointer=
"no-pager" />
842 <xi:include href=
"standard-options.xml" xpointer=
"no-legend" />
843 <xi:include href=
"standard-options.xml" xpointer=
"no-ask-password" />
844 <xi:include href=
"standard-options.xml" xpointer=
"help" />
845 <xi:include href=
"standard-options.xml" xpointer=
"version" />
850 <title>Machine and Image Names
</title>
852 <para>The
<command>machinectl
</command> tool operates on machines
853 and images whose names must be chosen following strict
854 rules. Machine names must be suitable for use as hostnames
855 following a conservative subset of DNS and UNIX/Linux
856 semantics. Specifically, they must consist of one or more
857 non-empty label strings, separated by dots. No leading or trailing
858 dots are allowed. No sequences of multiple dots are allowed. The
859 label strings may only consist of alphanumeric characters as well
860 as the dash and underscore. The maximum length of a machine name
861 is
64 characters.
</para>
863 <para>A special machine with the name
<literal>.host
</literal>
864 refers to the running host system itself. This is useful for execution
865 operations or inspecting the host system as well. Note that
866 <command>machinectl list
</command> will not show this special
867 machine unless the
<option>--all
</option> switch is specified.
</para>
869 <para>Requirements on image names are less strict, however, they must be
870 valid UTF-
8, must be suitable as file names (hence not be the
871 single or double dot, and not include a slash), and may not
872 contain control characters. Since many operations search for an
873 image by the name of a requested machine, it is recommended to name
874 images in the same strict fashion as machines.
</para>
876 <para>A special image with the name
<literal>.host
</literal>
877 refers to the image of the running host system. It hence
878 conceptually maps to the special
<literal>.host
</literal> machine
879 name described above. Note that
<command>machinectl
880 list-images
</command> will not show this special image either, unless
881 <option>--all
</option> is specified.
</para>
885 <title>Files and Directories
</title>
887 <para>Machine images are preferably stored in
888 <filename>/var/lib/machines/
</filename>, but are also searched for
889 in
<filename>/usr/local/lib/machines/
</filename> and
890 <filename>/usr/lib/machines/
</filename>. For compatibility reasons,
891 the directory
<filename>/var/lib/container/
</filename> is
892 searched, too. Note that images stored below
893 <filename>/usr
</filename> are always considered read-only. It is
894 possible to symlink machines images from other directories into
895 <filename>/var/lib/machines/
</filename> to make them available for
896 control with
<command>machinectl
</command>.
</para>
898 <para>Note that some image operations are only supported, efficient or atomic on btrfs file systems.
</para>
900 <para>Disk images are understood by
901 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
902 and
<command>machinectl
</command> in three formats:
</para>
905 <listitem><para>A simple directory tree, containing the files
906 and directories of the container to boot.
</para></listitem>
908 <listitem><para>Subvolumes (on btrfs file systems), which are
909 similar to the simple directories, described above. However,
910 they have additional benefits, such as efficient cloning and
911 quota reporting.
</para></listitem>
913 <listitem><para>"Raw" disk images, i.e. binary images of disks
914 with a GPT or MBR partition table. Images of this type are
915 regular files with the suffix
916 <literal>.raw
</literal>.
</para></listitem>
920 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
921 for more information on image formats, in particular its
922 <option>--directory=
</option> and
<option>--image=
</option>
927 <title>Examples
</title>
929 <title>Download an Ubuntu image and open a shell in it
</title>
931 <programlisting># machinectl pull-tar https://cloud-images.ubuntu.com/trusty/current/trusty-server-cloudimg-amd64-root.tar.gz
932 # systemd-nspawn -M trusty-server-cloudimg-amd64-root
</programlisting>
934 <para>This downloads and verifies the specified
935 <filename>.tar
</filename> image, and then uses
936 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
937 to open a shell in it.
</para>
941 <title>Download a Fedora image, set a root password in it, start
942 it as service
</title>
944 <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
945 # systemd-nspawn -M Fedora-Cloud-Base-
27-
1.6.x86_64
948 # machinectl start Fedora-Cloud-Base-
27-
1.6.x86_64
949 # machinectl login Fedora-Cloud-Base-
27-
1.6.x86_64
</programlisting>
951 <para>This downloads the specified
<filename>.raw
</filename>
952 image with verification disabled. Then, a shell is opened in it
953 and a root password is set. Afterwards the shell is left, and
954 the machine started as system service. With the last command a
955 login prompt into the container is requested.
</para>
959 <title>Exports a container image as tar file
</title>
961 <programlisting># machinectl export-tar fedora myfedora.tar.xz
</programlisting>
963 <para>Exports the container
<literal>fedora
</literal> as an
964 xz-compressed tar file
<filename>myfedora.tar.xz
</filename> into the
965 current directory.
</para>
969 <title>Create a new shell session
</title>
971 <programlisting># machinectl shell --uid=lennart
</programlisting>
973 <para>This creates a new shell session on the local host for
974 the user ID
<literal>lennart
</literal>, in a
<citerefentry
975 project='die-net'
><refentrytitle>su
</refentrytitle><manvolnum>1</manvolnum></citerefentry>-like
982 <title>Exit status
</title>
984 <para>On success,
0 is returned, a non-zero failure code
988 <xi:include href=
"less-variables.xml" />
991 <title>See Also
</title>
993 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
994 <citerefentry><refentrytitle>systemd-machined.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
995 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
996 <citerefentry><refentrytitle>systemd.special
</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
997 <citerefentry project='die-net'
><refentrytitle>tar
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
998 <citerefentry project='die-net'
><refentrytitle>xz
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
999 <citerefentry project='die-net'
><refentrytitle>gzip
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1000 <citerefentry project='die-net'
><refentrytitle>bzip2
</refentrytitle><manvolnum>1</manvolnum></citerefentry>