1 <?xml version='
1.0'
?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
2 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
6 SPDX-License-Identifier: LGPL-2.1+
8 This file is part of systemd.
10 Copyright 2013 Zbigniew Jędrzejewski-Szmek
12 systemd is free software; you can redistribute it and/or modify it
13 under the terms of the GNU Lesser General Public License as published by
14 the Free Software Foundation; either version 2.1 of the License, or
15 (at your option) any later version.
17 systemd is distributed in the hope that it will be useful, but
18 WITHOUT ANY WARRANTY; without even the implied warranty of
19 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
20 Lesser General Public License for more details.
22 You should have received a copy of the GNU Lesser General Public License
23 along with systemd; If not, see <http://www.gnu.org/licenses/>.
26 <refentry id=
"machinectl" conditional='ENABLE_MACHINED'
27 xmlns:
xi=
"http://www.w3.org/2001/XInclude">
30 <title>machinectl
</title>
31 <productname>systemd
</productname>
35 <contrib>Developer
</contrib>
36 <firstname>Lennart
</firstname>
37 <surname>Poettering
</surname>
38 <email>lennart@poettering.net
</email>
44 <refentrytitle>machinectl
</refentrytitle>
45 <manvolnum>1</manvolnum>
49 <refname>machinectl
</refname>
50 <refpurpose>Control the systemd machine manager
</refpurpose>
55 <command>machinectl
</command>
56 <arg choice=
"opt" rep=
"repeat">OPTIONS
</arg>
57 <arg choice=
"req">COMMAND
</arg>
58 <arg choice=
"opt" rep=
"repeat">NAME
</arg>
63 <title>Description
</title>
65 <para><command>machinectl
</command> may be used to introspect and
66 control the state of the
67 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
68 virtual machine and container registration manager
69 <citerefentry><refentrytitle>systemd-machined.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
</para>
71 <para><command>machinectl
</command> may be used to execute
72 operations on machines and images. Machines in this sense are
73 considered running instances of:
</para>
76 <listitem><para>Virtual Machines (VMs) that virtualize hardware
77 to run full operating system (OS) instances (including their kernels)
78 in a virtualized environment on top of the host OS.
</para></listitem>
80 <listitem><para>Containers that share the hardware and
81 OS kernel with the host OS, in order to run
82 OS userspace instances on top the host OS.
</para></listitem>
84 <listitem><para>The host system itself.
</para></listitem>
87 <para>Machines are identified by names that follow the same rules
88 as UNIX and DNS host names. For details, see below.
</para>
90 <para>Machines are instantiated from disk or file system images that
91 frequently — but not necessarily — carry the same name as machines running
92 from them. Images in this sense may be:
</para>
95 <listitem><para>Directory trees containing an OS, including the
96 top-level directories
<filename>/usr
</filename>,
97 <filename>/etc
</filename>, and so on.
</para></listitem>
99 <listitem><para>btrfs subvolumes containing OS trees, similar to
100 normal directory trees.
</para></listitem>
102 <listitem><para>Binary
"raw" disk images containing MBR or GPT
103 partition tables and Linux file system partitions.
</para></listitem>
105 <listitem><para>The file system tree of the host OS itself.
</para></listitem>
111 <title>Options
</title>
113 <para>The following options are understood:
</para>
117 <term><option>-p
</option></term>
118 <term><option>--property=
</option></term>
120 <listitem><para>When showing machine or image properties,
121 limit the output to certain properties as specified by the
122 argument. If not specified, all set properties are shown. The
123 argument should be a property name, such as
124 <literal>Name
</literal>. If specified more than once, all
125 properties with the specified names are
126 shown.
</para></listitem>
130 <term><option>-a
</option></term>
131 <term><option>--all
</option></term>
133 <listitem><para>When showing machine or image properties, show
134 all properties regardless of whether they are set or
137 <para>When listing VM or container images, do not suppress
138 images beginning in a dot character
139 (
<literal>.
</literal>).
</para>
141 <para>When cleaning VM or container images, remove all images, not just hidden ones.
</para></listitem>
145 <term><option>--value
</option></term>
147 <listitem><para>When printing properties with
<command>show
</command>, only print the value,
148 and skip the property name and
<literal>=
</literal>.
</para></listitem>
152 <term><option>-l
</option></term>
153 <term><option>--full
</option></term>
155 <listitem><para>Do not ellipsize process tree entries.
</para>
160 <term><option>--no-ask-password
</option></term>
162 <listitem><para>Do not query the user for authentication for
163 privileged operations.
</para></listitem>
167 <term><option>--kill-who=
</option></term>
169 <listitem><para>When used with
<command>kill
</command>, choose
170 which processes to kill. Must be one of
171 <option>leader
</option>, or
<option>all
</option> to select
172 whether to kill only the leader process of the machine or all
173 processes of the machine. If omitted, defaults to
174 <option>all
</option>.
</para></listitem>
178 <term><option>-s
</option></term>
179 <term><option>--signal=
</option></term>
181 <listitem><para>When used with
<command>kill
</command>, choose
182 which signal to send to selected processes. Must be one of the
183 well-known signal specifiers, such as
184 <constant>SIGTERM
</constant>,
<constant>SIGINT
</constant> or
185 <constant>SIGSTOP
</constant>. If omitted, defaults to
186 <constant>SIGTERM
</constant>.
</para></listitem>
190 <term><option>--uid=
</option></term>
192 <listitem><para>When used with the
<command>shell
</command> command, chooses the user ID to
193 open the interactive shell session as. If the argument to the
<command>shell
</command>
194 command also specifies a user name, this option is ignored. If the name is not specified
195 in either way,
<literal>root
</literal> will be used by default. Note that this switch is
196 not supported for the
<command>login
</command> command (see below).
</para></listitem>
200 <term><option>-E
<replaceable>NAME
</replaceable>=
<replaceable>VALUE
</replaceable></option></term>
201 <term><option>--setenv=
<replaceable>NAME
</replaceable>=
<replaceable>VALUE
</replaceable></option></term>
203 <listitem><para>When used with the
<command>shell
</command> command, sets an environment
204 variable to pass to the executed shell. Takes an environment variable name and value,
205 separated by
<literal>=
</literal>. This switch may be used multiple times to set multiple
206 environment variables. Note that this switch is not supported for the
207 <command>login
</command> command (see below).
</para></listitem>
211 <term><option>--mkdir
</option></term>
213 <listitem><para>When used with
<command>bind
</command>, creates the destination file or directory before
214 applying the bind mount. Note that even though the name of this option suggests that it is suitable only for
215 directories, this option also creates the destination file node to mount over if the the object to mount is not
216 a directory, but a regular file, device node, socket or FIFO.
</para></listitem>
220 <term><option>--read-only
</option></term>
222 <listitem><para>When used with
<command>bind
</command>, creates a read-only bind mount.
</para>
224 <para>When used with
<command>clone
</command>,
<command>import-raw
</command> or
<command>import-tar
</command> a
225 read-only container or VM image is created.
</para></listitem>
229 <term><option>-n
</option></term>
230 <term><option>--lines=
</option></term>
232 <listitem><para>When used with
<command>status
</command>,
233 controls the number of journal lines to show, counting from
234 the most recent ones. Takes a positive integer argument.
235 Defaults to
10.
</para>
240 <term><option>-o
</option></term>
241 <term><option>--output=
</option></term>
243 <listitem><para>When used with
<command>status
</command>,
244 controls the formatting of the journal entries that are shown.
245 For the available choices, see
246 <citerefentry><refentrytitle>journalctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
247 Defaults to
<literal>short
</literal>.
</para></listitem>
251 <term><option>--verify=
</option></term>
253 <listitem><para>When downloading a container or VM image,
254 specify whether the image shall be verified before it is made
255 available. Takes one of
<literal>no
</literal>,
256 <literal>checksum
</literal> and
<literal>signature
</literal>.
257 If
<literal>no
</literal>, no verification is done. If
258 <literal>checksum
</literal> is specified, the download is
259 checked for integrity after the transfer is complete, but no
260 signatures are verified. If
<literal>signature
</literal> is
261 specified, the checksum is verified and the image's signature
262 is checked against a local keyring of trustable vendors. It is
263 strongly recommended to set this option to
264 <literal>signature
</literal> if the server and protocol
265 support this. Defaults to
266 <literal>signature
</literal>.
</para></listitem>
270 <term><option>--force
</option></term>
272 <listitem><para>When downloading a container or VM image, and
273 a local copy by the specified local machine name already
274 exists, delete it first and replace it by the newly downloaded
275 image.
</para></listitem>
279 <term><option>--format=
</option></term>
281 <listitem><para>When used with the
<option>export-tar
</option>
282 or
<option>export-raw
</option> commands, specifies the
283 compression format to use for the resulting file. Takes one of
284 <literal>uncompressed
</literal>,
<literal>xz
</literal>,
285 <literal>gzip
</literal>,
<literal>bzip2
</literal>. By default,
286 the format is determined automatically from the image file
287 name passed.
</para></listitem>
291 <term><option>--max-addresses=
</option></term>
293 <listitem><para>When used with the
<option>list-machines
</option>
294 command, limits the number of ip addresses output for every machine.
295 Defaults to
1. All addresses can be requested with
<literal>all
</literal>
296 as argument to
<option>--max-addresses
</option> . If the argument to
297 <option>--max-addresses
</option> is less than the actual number
298 of addresses,
<literal>...
</literal>follows the last address.
299 If multiple addresses are to be written for a given machine, every
300 address except the first one is on a new line and is followed by
301 <literal>,
</literal> if another address will be output afterwards.
</para></listitem>
304 <xi:include href=
"user-system-options.xml" xpointer=
"host" />
307 <term><option>-M
</option></term>
308 <term><option>--machine=
</option></term>
310 <listitem><para>Connect to
311 <citerefentry><refentrytitle>systemd-machined.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
312 running in a local container, to perform the specified operation within
313 the container.
</para></listitem>
316 <xi:include href=
"standard-options.xml" xpointer=
"no-pager" />
317 <xi:include href=
"standard-options.xml" xpointer=
"no-legend" />
318 <xi:include href=
"standard-options.xml" xpointer=
"help" />
319 <xi:include href=
"standard-options.xml" xpointer=
"version" />
324 <title>Commands
</title>
326 <para>The following commands are understood:
</para>
328 <refsect2><title>Machine Commands
</title><variablelist>
331 <term><command>list
</command></term>
333 <listitem><para>List currently running (online) virtual
334 machines and containers. To enumerate machine images that can
335 be started, use
<command>list-images
</command> (see
336 below). Note that this command hides the special
337 <literal>.host
</literal> machine by default. Use the
338 <option>--all
</option> switch to show it.
</para></listitem>
342 <term><command>status
</command> <replaceable>NAME
</replaceable>…
</term>
344 <listitem><para>Show runtime status information about
345 one or more virtual machines and containers, followed by the
346 most recent log data from the journal. This function is
347 intended to generate human-readable output. If you are looking
348 for computer-parsable output, use
<command>show
</command>
349 instead. Note that the log data shown is reported by the
350 virtual machine or container manager, and frequently contains
351 console output of the machine, but not necessarily journal
352 contents of the machine itself.
</para></listitem>
356 <term><command>show
</command> [
<replaceable>NAME
</replaceable>…]
</term>
358 <listitem><para>Show properties of one or more registered virtual machines or containers or the manager
359 itself. If no argument is specified, properties of the manager will be shown. If a NAME is specified,
360 properties of this virtual machine or container are shown. By default, empty properties are suppressed. Use
361 <option>--all
</option> to show those too. To select specific properties to show, use
362 <option>--property=
</option>. This command is intended to be used whenever computer-parsable output is
363 required, and does not print the control group tree or journal entries. Use
<command>status
</command> if you
364 are looking for formatted human-readable output.
</para></listitem>
368 <term><command>start
</command> <replaceable>NAME
</replaceable>…
</term>
370 <listitem><para>Start a container as a system service, using
371 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
372 This starts
<filename>systemd-nspawn@.service
</filename>,
373 instantiated for the specified machine name, similar to the
374 effect of
<command>systemctl start
</command> on the service
375 name.
<command>systemd-nspawn
</command> looks for a container
376 image by the specified name in
377 <filename>/var/lib/machines/
</filename> (and other search
378 paths, see below) and runs it. Use
379 <command>list-images
</command> (see below) for listing
380 available container images to start.
</para>
383 <citerefentry><refentrytitle>systemd-machined.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
384 also interfaces with a variety of other container and VM
385 managers,
<command>systemd-nspawn
</command> is just one
386 implementation of it. Most of the commands available in
387 <command>machinectl
</command> may be used on containers or VMs
388 controlled by other managers, not just
389 <command>systemd-nspawn
</command>. Starting VMs and container
390 images on those managers requires manager-specific
393 <para>To interactively start a container on the command line
394 with full access to the container's console, please invoke
395 <command>systemd-nspawn
</command> directly. To stop a running
396 container use
<command>machinectl poweroff
</command>.
</para></listitem>
400 <term><command>login
</command> [
<replaceable>NAME
</replaceable>]
</term>
402 <listitem><para>Open an interactive terminal login session in
403 a container or on the local host. If an argument is supplied,
404 it refers to the container machine to connect to. If none is
405 specified, or the container name is specified as the empty
406 string, or the special machine name
<literal>.host
</literal>
407 (see below) is specified, the connection is made to the local
408 host instead. This will create a TTY connection to a specific
409 container or the local host and asks for the execution of a
410 getty on it. Note that this is only supported for containers
412 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
413 as init system.
</para>
415 <para>This command will open a full login prompt on the
416 container or the local host, which then asks for username and
417 password. Use
<command>shell
</command> (see below) or
418 <citerefentry><refentrytitle>systemd-run
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
419 with the
<option>--machine=
</option> switch to directly invoke
420 a single command, either interactively or in the
421 background.
</para></listitem>
425 <term><command>shell
</command> [[
<replaceable>NAME
</replaceable>@]
<replaceable>NAME
</replaceable> [
<replaceable>PATH
</replaceable> [
<replaceable>ARGUMENTS
</replaceable>…]]]
</term>
427 <listitem><para>Open an interactive shell session in a
428 container or on the local host. The first argument refers to
429 the container machine to connect to. If none is specified, or
430 the machine name is specified as the empty string, or the
431 special machine name
<literal>.host
</literal> (see below) is
432 specified, the connection is made to the local host
433 instead. This works similar to
<command>login
</command> but
434 immediately invokes a user process. This command runs the
435 specified executable with the specified arguments, or
436 <filename>/bin/sh
</filename> if none is specified. By default,
437 opens a
<literal>root
</literal> shell, but by using
438 <option>--uid=
</option>, or by prefixing the machine name with
439 a username and an
<literal>@
</literal> character, a different
440 user may be selected. Use
<option>--setenv=
</option> to set
441 environment variables for the executed process.
</para>
443 <para>Note that
<command>machinectl shell
</command> does not propagate the exit code/status of the invoked
444 shell process. Use
<command>systemd-run
</command> instead if that information is required (see below).
</para>
446 <para>When using the
<command>shell
</command> command without
447 arguments, (thus invoking the executed shell or command on the
448 local host), it is in many ways similar to a
<citerefentry
449 project='die-net'
><refentrytitle>su
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
450 session, but, unlike
<command>su
</command>, completely isolates
451 the new session from the originating session, so that it
452 shares no process or session properties, and is in a clean and
453 well-defined state. It will be tracked in a new utmp, login,
454 audit, security and keyring session, and will not inherit any
455 environment variables or resource limits, among other
458 <para>Note that
<citerefentry><refentrytitle>systemd-run
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
459 with its
<option>--machine=
</option> switch may be used in place of the
<command>machinectl shell
</command>
460 command, and allows non-interactive operation, more detailed and low-level configuration of the invoked unit,
461 as well as access to runtime and exit code/status information of the invoked shell process. In particular, use
462 <command>systemd-run
</command>'s
<option>--wait
</option> switch to propagate exit status information of the
463 invoked process. Use
<command>systemd-run
</command>'s
<option>--pty
</option> switch for acquiring an
464 interactive shell, similar to
<command>machinectl shell
</command>. In general,
<command>systemd-run
</command>
465 is preferable for scripting purposes. However, note that
<command>systemd-run
</command> might require higher
466 privileges than
<command>machinectl shell
</command>.
</para></listitem>
470 <term><command>enable
</command> <replaceable>NAME
</replaceable>…
</term>
471 <term><command>disable
</command> <replaceable>NAME
</replaceable>…
</term>
473 <listitem><para>Enable or disable a container as a system
474 service to start at system boot, using
475 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
476 This enables or disables
477 <filename>systemd-nspawn@.service
</filename>, instantiated for
478 the specified machine name, similar to the effect of
479 <command>systemctl enable
</command> or
<command>systemctl
480 disable
</command> on the service name.
</para></listitem>
484 <term><command>poweroff
</command> <replaceable>NAME
</replaceable>…
</term>
486 <listitem><para>Power off one or more containers. This will
487 trigger a reboot by sending SIGRTMIN+
4 to the container's init
488 process, which causes systemd-compatible init systems to shut
489 down cleanly. Use
<command>stop
</command> as alias for
<command>poweroff
</command>.
490 This operation does not work on containers that do not run a
491 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>-compatible
492 init system, such as sysvinit. Use
493 <command>terminate
</command> (see below) to immediately
494 terminate a container or VM, without cleanly shutting it
495 down.
</para></listitem>
499 <term><command>reboot
</command> <replaceable>NAME
</replaceable>…
</term>
501 <listitem><para>Reboot one or more containers. This will
502 trigger a reboot by sending SIGINT to the container's init
503 process, which is roughly equivalent to pressing Ctrl+Alt+Del
504 on a non-containerized system, and is compatible with
505 containers running any system manager.
</para></listitem>
509 <term><command>terminate
</command> <replaceable>NAME
</replaceable>…
</term>
511 <listitem><para>Immediately terminates a virtual machine or
512 container, without cleanly shutting it down. This kills all
513 processes of the virtual machine or container and deallocates
514 all resources attached to that instance. Use
515 <command>poweroff
</command> to issue a clean shutdown
516 request.
</para></listitem>
520 <term><command>kill
</command> <replaceable>NAME
</replaceable>…
</term>
522 <listitem><para>Send a signal to one or more processes of the
523 virtual machine or container. This means processes as seen by
524 the host, not the processes inside the virtual machine or
525 container. Use
<option>--kill-who=
</option> to select which
526 process to kill. Use
<option>--signal=
</option> to select the
527 signal to send.
</para></listitem>
531 <term><command>bind
</command> <replaceable>NAME
</replaceable> <replaceable>PATH
</replaceable> [
<replaceable>PATH
</replaceable>]
</term>
533 <listitem><para>Bind mounts a file or directory from the host into the specified container. The first path
534 argument is the source file or directory on the host, the second path argument is the destination file or
535 directory in the container. When the latter is omitted, the destination path in the container is the same as
536 the source path on the host. When combined with the
<option>--read-only
</option> switch, a ready-only bind
537 mount is created. When combined with the
<option>--mkdir
</option> switch, the destination path is first created
538 before the mount is applied. Note that this option is currently only supported for
539 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry> containers,
540 and only if user namespacing (
<option>--private-users
</option>) is not used. This command supports bind
541 mounting directories, regular files, device nodes,
<constant>AF_UNIX
</constant> socket nodes, as well as
542 FIFOs.
</para></listitem>
546 <term><command>copy-to
</command> <replaceable>NAME
</replaceable> <replaceable>PATH
</replaceable> [
<replaceable>PATH
</replaceable>]
</term>
548 <listitem><para>Copies files or directories from the host
549 system into a running container. Takes a container name,
550 followed by the source path on the host and the destination
551 path in the container. If the destination path is omitted, the
552 same as the source path is used.
</para>
554 <para>If host and container share the same user and group namespace, file ownership by numeric user ID and
555 group ID is preserved for the copy, otherwise all files and directories in the copy will be owned by the root
556 user and group (UID/GID
0).
</para></listitem>
560 <term><command>copy-from
</command> <replaceable>NAME
</replaceable> <replaceable>PATH
</replaceable> [
<replaceable>PATH
</replaceable>]
</term>
562 <listitem><para>Copies files or directories from a container
563 into the host system. Takes a container name, followed by the
564 source path in the container the destination path on the host.
565 If the destination path is omitted, the same as the source path
568 <para>If host and container share the same user and group namespace, file ownership by numeric user ID and
569 group ID is preserved for the copy, otherwise all files and directories in the copy will be owned by the root
570 user and group (UID/GID
0).
</para></listitem>
572 </variablelist></refsect2>
574 <refsect2><title>Image Commands
</title><variablelist>
577 <term><command>list-images
</command></term>
579 <listitem><para>Show a list of locally installed container and
580 VM images. This enumerates all raw disk images and container
581 directories and subvolumes in
582 <filename>/var/lib/machines/
</filename> (and other search
583 paths, see below). Use
<command>start
</command> (see above) to
584 run a container off one of the listed images. Note that, by
585 default, containers whose name begins with a dot
586 (
<literal>.
</literal>) are not shown. To show these too,
587 specify
<option>--all
</option>. Note that a special image
588 <literal>.host
</literal> always implicitly exists and refers
589 to the image the host itself is booted from.
</para></listitem>
593 <term><command>image-status
</command> [
<replaceable>NAME
</replaceable>…]
</term>
595 <listitem><para>Show terse status information about one or
596 more container or VM images. This function is intended to
597 generate human-readable output. Use
598 <command>show-image
</command> (see below) to generate
599 computer-parsable output instead.
</para></listitem>
603 <term><command>show-image
</command> [
<replaceable>NAME
</replaceable>…]
</term>
605 <listitem><para>Show properties of one or more registered
606 virtual machine or container images, or the manager itself. If
607 no argument is specified, properties of the manager will be
608 shown. If a NAME is specified, properties of this virtual
609 machine or container image are shown. By default, empty
610 properties are suppressed. Use
<option>--all
</option> to show
611 those too. To select specific properties to show, use
612 <option>--property=
</option>. This command is intended to be
613 used whenever computer-parsable output is required. Use
614 <command>image-status
</command> if you are looking for
615 formatted human-readable output.
</para></listitem>
619 <term><command>clone
</command> <replaceable>NAME
</replaceable> <replaceable>NAME
</replaceable></term>
621 <listitem><para>Clones a container or VM image. The arguments specify the name of the image to clone and the
622 name of the newly cloned image. Note that plain directory container images are cloned into btrfs subvolume
623 images with this command, if the underlying file system supports this. Note that cloning a container or VM
624 image is optimized for file systems that support copy-on-write, and might not be efficient on others, due to
625 file system limitations.
</para>
627 <para>Note that this command leaves host name, machine ID and
628 all other settings that could identify the instance
629 unmodified. The original image and the cloned copy will hence
630 share these credentials, and it might be necessary to manually
631 change them in the copy.
</para>
633 <para>If combined with the
<option>--read-only
</option> switch a read-only cloned image is
634 created.
</para></listitem>
638 <term><command>rename
</command> <replaceable>NAME
</replaceable> <replaceable>NAME
</replaceable></term>
640 <listitem><para>Renames a container or VM image. The
641 arguments specify the name of the image to rename and the new
642 name of the image.
</para></listitem>
646 <term><command>read-only
</command> <replaceable>NAME
</replaceable> [
<replaceable>BOOL
</replaceable>]
</term>
648 <listitem><para>Marks or (unmarks) a container or VM image
649 read-only. Takes a VM or container image name, followed by a
650 boolean as arguments. If the boolean is omitted, positive is
651 implied, i.e. the image is marked read-only.
</para></listitem>
655 <term><command>remove
</command> <replaceable>NAME
</replaceable>…
</term>
657 <listitem><para>Removes one or more container or VM images.
658 The special image
<literal>.host
</literal>, which refers to
659 the host's own directory tree, may not be
660 removed.
</para></listitem>
664 <term><command>set-limit
</command> [
<replaceable>NAME
</replaceable>]
<replaceable>BYTES
</replaceable></term>
666 <listitem><para>Sets the maximum size in bytes that a specific
667 container or VM image, or all images, may grow up to on disk
668 (disk quota). Takes either one or two parameters. The first,
669 optional parameter refers to a container or VM image name. If
670 specified, the size limit of the specified image is changed. If
671 omitted, the overall size limit of the sum of all images stored
672 locally is changed. The final argument specifies the size
673 limit in bytes, possibly suffixed by the usual K, M, G, T
674 units. If the size limit shall be disabled, specify
675 <literal>-
</literal> as size.
</para>
677 <para>Note that per-container size limits are only supported
678 on btrfs file systems. Also note that, if
679 <command>set-limit
</command> is invoked without an image
680 parameter, and
<filename>/var/lib/machines
</filename> is
681 empty, and the directory is not located on btrfs, a btrfs
682 loopback file is implicitly created as
683 <filename>/var/lib/machines.raw
</filename> with the given
685 <filename>/var/lib/machines
</filename>. The size of the
686 loopback may later be readjusted with
687 <command>set-limit
</command>, as well. If such a
688 loopback-mounted
<filename>/var/lib/machines
</filename>
689 directory is used,
<command>set-limit
</command> without an image
690 name alters both the quota setting within the file system as
691 well as the loopback file and file system size
692 itself.
</para></listitem>
696 <term><command>clean
</command></term>
698 <listitem><para>Remove hidden VM or container images (or all). This command removes all hidden machine images
699 from
<filename>/var/lib/machines
</filename>, i.e. those whose name begins with a dot. Use
<command>machinectl
700 list-images --all
</command> to see a list of all machine images, including the hidden ones.
</para>
702 <para>When combined with the
<option>--all
</option> switch removes all images, not just hidden ones. This
703 command effectively empties
<filename>/var/lib/machines
</filename>.
</para>
705 <para>Note that commands such as
<command>machinectl pull-tar
</command> or
<command>machinectl
706 pull-raw
</command> usually create hidden, read-only, unmodified machine images from the downloaded image first,
707 before cloning a writable working copy of it, in order to avoid duplicate downloads in case of images that are
708 reused multiple times. Use
<command>machinectl clean
</command> to remove old, hidden images created this
709 way.
</para></listitem>
712 </variablelist></refsect2>
714 <refsect2><title>Image Transfer Commands
</title><variablelist>
717 <term><command>pull-tar
</command> <replaceable>URL
</replaceable> [
<replaceable>NAME
</replaceable>]
</term>
719 <listitem><para>Downloads a
<filename>.tar
</filename>
720 container image from the specified URL, and makes it available
721 under the specified local machine name. The URL must be of
722 type
<literal>http://
</literal> or
723 <literal>https://
</literal>, and must refer to a
724 <filename>.tar
</filename>,
<filename>.tar.gz
</filename>,
725 <filename>.tar.xz
</filename> or
<filename>.tar.bz2
</filename>
726 archive file. If the local machine name is omitted, it
727 is automatically derived from the last component of the URL,
728 with its suffix removed.
</para>
730 <para>The image is verified before it is made available, unless
731 <option>--verify=no
</option> is specified.
732 Verification is done either via an inline signed file with the name
733 of the image and the suffix
<filename>.sha256
</filename> or via
734 separate
<filename>SHA256SUMS
</filename> and
735 <filename>SHA256SUMS.gpg
</filename> files.
736 The signature files need to be made available on the same web
737 server, under the same URL as the
<filename>.tar
</filename> file.
738 With
<option>--verify=checksum
</option>, only the SHA256 checksum
739 for the file is verified, based on the
<filename>.sha256
</filename>
740 suffixed file or the
<filename>SHA256SUMS
</filename> file.
741 With
<option>--verify=signature
</option>, the sha checksum file is
742 first verified with the inline signature in the
743 <filename>.sha256
</filename> file or the detached GPG signature file
744 <filename>SHA256SUMS.gpg
</filename>.
745 The public key for this verification step needs to be available in
746 <filename>/usr/lib/systemd/import-pubring.gpg
</filename> or
747 <filename>/etc/systemd/import-pubring.gpg
</filename>.
</para>
749 <para>The container image will be downloaded and stored in a
750 read-only subvolume in
751 <filename>/var/lib/machines/
</filename> that is named after
752 the specified URL and its HTTP etag. A writable snapshot is
753 then taken from this subvolume, and named after the specified
754 local name. This behavior ensures that creating multiple
755 container instances of the same URL is efficient, as multiple
756 downloads are not necessary. In order to create only the
757 read-only image, and avoid creating its writable snapshot,
758 specify
<literal>-
</literal> as local machine name.
</para>
760 <para>Note that the read-only subvolume is prefixed with
761 <filename>.tar-
</filename>, and is thus not shown by
762 <command>list-images
</command>, unless
<option>--all
</option>
765 <para>Note that pressing C-c during execution of this command
766 will not abort the download. Use
767 <command>cancel-transfer
</command>, described
768 below.
</para></listitem>
772 <term><command>pull-raw
</command> <replaceable>URL
</replaceable> [
<replaceable>NAME
</replaceable>]
</term>
774 <listitem><para>Downloads a
<filename>.raw
</filename>
775 container or VM disk image from the specified URL, and makes
776 it available under the specified local machine name. The URL
777 must be of type
<literal>http://
</literal> or
778 <literal>https://
</literal>. The container image must either
779 be a
<filename>.qcow2
</filename> or raw disk image, optionally
780 compressed as
<filename>.gz
</filename>,
781 <filename>.xz
</filename>, or
<filename>.bz2
</filename>. If the
782 local machine name is omitted, it is automatically
783 derived from the last component of the URL, with its suffix
786 <para>Image verification is identical for raw and tar images
789 <para>If the downloaded image is in
790 <filename>.qcow2
</filename> format it is converted into a raw
791 image file before it is made available.
</para>
793 <para>Downloaded images of this type will be placed as
794 read-only
<filename>.raw
</filename> file in
795 <filename>/var/lib/machines/
</filename>. A local, writable
796 (reflinked) copy is then made under the specified local
797 machine name. To omit creation of the local, writable copy
798 pass
<literal>-
</literal> as local machine name.
</para>
800 <para>Similar to the behavior of
<command>pull-tar
</command>,
801 the read-only image is prefixed with
802 <filename>.raw-
</filename>, and thus not shown by
803 <command>list-images
</command>, unless
<option>--all
</option>
806 <para>Note that pressing C-c during execution of this command
807 will not abort the download. Use
808 <command>cancel-transfer
</command>, described
809 below.
</para></listitem>
813 <term><command>import-tar
</command> <replaceable>FILE
</replaceable> [
<replaceable>NAME
</replaceable>]
</term>
814 <term><command>import-raw
</command> <replaceable>FILE
</replaceable> [
<replaceable>NAME
</replaceable>]
</term>
815 <listitem><para>Imports a TAR or RAW container or VM image,
816 and places it under the specified name in
817 <filename>/var/lib/machines/
</filename>. When
818 <command>import-tar
</command> is used, the file specified as
819 the first argument should be a tar archive, possibly compressed
820 with xz, gzip or bzip2. It will then be unpacked into its own
821 subvolume in
<filename>/var/lib/machines
</filename>. When
822 <command>import-raw
</command> is used, the file should be a
823 qcow2 or raw disk image, possibly compressed with xz, gzip or
824 bzip2. If the second argument (the resulting image name) is
825 not specified, it is automatically derived from the file
826 name. If the filename is passed as
<literal>-
</literal>, the
827 image is read from standard input, in which case the second
828 argument is mandatory.
</para>
830 <para>Both
<command>pull-tar
</command> and
<command>pull-raw
</command>
831 will resize
<filename>/var/lib/machines.raw
</filename> and the
832 filesystem therein as necessary. Optionally, the
833 <option>--read-only
</option> switch may be used to create a
834 read-only container or VM image. No cryptographic validation
835 is done when importing the images.
</para>
837 <para>Much like image downloads, ongoing imports may be listed
838 with
<command>list-transfers
</command> and aborted with
839 <command>cancel-transfer
</command>.
</para></listitem>
843 <term><command>export-tar
</command> <replaceable>NAME
</replaceable> [
<replaceable>FILE
</replaceable>]
</term>
844 <term><command>export-raw
</command> <replaceable>NAME
</replaceable> [
<replaceable>FILE
</replaceable>]
</term>
845 <listitem><para>Exports a TAR or RAW container or VM image and
846 stores it in the specified file. The first parameter should be
847 a VM or container image name. The second parameter should be a
848 file path the TAR or RAW image is written to. If the path ends
849 in
<literal>.gz
</literal>, the file is compressed with gzip, if
850 it ends in
<literal>.xz
</literal>, with xz, and if it ends in
851 <literal>.bz2
</literal>, with bzip2. If the path ends in
852 neither, the file is left uncompressed. If the second argument
853 is missing, the image is written to standard output. The
854 compression may also be explicitly selected with the
855 <option>--format=
</option> switch. This is in particular
856 useful if the second parameter is left unspecified.
</para>
858 <para>Much like image downloads and imports, ongoing exports
859 may be listed with
<command>list-transfers
</command> and
861 <command>cancel-transfer
</command>.
</para>
863 <para>Note that, currently, only directory and subvolume images
864 may be exported as TAR images, and only raw disk images as RAW
865 images.
</para></listitem>
869 <term><command>list-transfers
</command></term>
871 <listitem><para>Shows a list of container or VM image
872 downloads, imports and exports that are currently in
873 progress.
</para></listitem>
877 <term><command>cancel-transfers
</command> <replaceable>ID
</replaceable>…
</term>
879 <listitem><para>Aborts a download, import or export of the
880 container or VM image with the specified ID. To list ongoing
881 transfers and their IDs, use
882 <command>list-transfers
</command>.
</para></listitem>
885 </variablelist></refsect2>
890 <title>Machine and Image Names
</title>
892 <para>The
<command>machinectl
</command> tool operates on machines
893 and images whose names must be chosen following strict
894 rules. Machine names must be suitable for use as host names
895 following a conservative subset of DNS and UNIX/Linux
896 semantics. Specifically, they must consist of one or more
897 non-empty label strings, separated by dots. No leading or trailing
898 dots are allowed. No sequences of multiple dots are allowed. The
899 label strings may only consist of alphanumeric characters as well
900 as the dash and underscore. The maximum length of a machine name
901 is
64 characters.
</para>
903 <para>A special machine with the name
<literal>.host
</literal>
904 refers to the running host system itself. This is useful for execution
905 operations or inspecting the host system as well. Note that
906 <command>machinectl list
</command> will not show this special
907 machine unless the
<option>--all
</option> switch is specified.
</para>
909 <para>Requirements on image names are less strict, however, they must be
910 valid UTF-
8, must be suitable as file names (hence not be the
911 single or double dot, and not include a slash), and may not
912 contain control characters. Since many operations search for an
913 image by the name of a requested machine, it is recommended to name
914 images in the same strict fashion as machines.
</para>
916 <para>A special image with the name
<literal>.host
</literal>
917 refers to the image of the running host system. It hence
918 conceptually maps to the special
<literal>.host
</literal> machine
919 name described above. Note that
<command>machinectl
920 list-images
</command> will not show this special image either, unless
921 <option>--all
</option> is specified.
</para>
925 <title>Files and Directories
</title>
927 <para>Machine images are preferably stored in
928 <filename>/var/lib/machines/
</filename>, but are also searched for
929 in
<filename>/usr/local/lib/machines/
</filename> and
930 <filename>/usr/lib/machines/
</filename>. For compatibility reasons,
931 the directory
<filename>/var/lib/container/
</filename> is
932 searched, too. Note that images stored below
933 <filename>/usr
</filename> are always considered read-only. It is
934 possible to symlink machines images from other directories into
935 <filename>/var/lib/machines/
</filename> to make them available for
936 control with
<command>machinectl
</command>.
</para>
938 <para>Note that some image operations are only supported,
939 efficient or atomic on btrfs file systems. Due to this, if the
940 <command>pull-tar
</command>,
<command>pull-raw
</command>,
941 <command>import-tar
</command>,
<command>import-raw
</command> and
942 <command>set-limit
</command> commands notice that
943 <filename>/var/lib/machines
</filename> is empty and not located on
944 btrfs, they will implicitly set up a loopback file
945 <filename>/var/lib/machines.raw
</filename> containing a btrfs file
946 system that is mounted to
947 <filename>/var/lib/machines
</filename>. The size of this loopback
948 file may be controlled dynamically with
949 <command>set-limit
</command>.
</para>
951 <para>Disk images are understood by
952 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
953 and
<command>machinectl
</command> in three formats:
</para>
956 <listitem><para>A simple directory tree, containing the files
957 and directories of the container to boot.
</para></listitem>
959 <listitem><para>Subvolumes (on btrfs file systems), which are
960 similar to the simple directories, described above. However,
961 they have additional benefits, such as efficient cloning and
962 quota reporting.
</para></listitem>
964 <listitem><para>"Raw" disk images, i.e. binary images of disks
965 with a GPT or MBR partition table. Images of this type are
966 regular files with the suffix
967 <literal>.raw
</literal>.
</para></listitem>
971 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
972 for more information on image formats, in particular its
973 <option>--directory=
</option> and
<option>--image=
</option>
978 <title>Examples
</title>
980 <title>Download an Ubuntu image and open a shell in it
</title>
982 <programlisting># machinectl pull-tar https://cloud-images.ubuntu.com/trusty/current/trusty-server-cloudimg-amd64-root.tar.gz
983 # systemd-nspawn -M trusty-server-cloudimg-amd64-root
</programlisting>
985 <para>This downloads and verifies the specified
986 <filename>.tar
</filename> image, and then uses
987 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
988 to open a shell in it.
</para>
992 <title>Download a Fedora image, set a root password in it, start
993 it as service
</title>
995 <programlisting># machinectl pull-raw --verify=no https://dl.fedoraproject.org/pub/fedora/linux/releases/
23/Cloud/x86_64/Images/Fedora-Cloud-Base-
23-
20151030.x86_64.raw.xz
996 # systemd-nspawn -M Fedora-Cloud-Base-
23-
20151030
999 # machinectl start Fedora-Cloud-Base-
23-
20151030
1000 # machinectl login Fedora-Cloud-Base-
23-
20151030</programlisting>
1002 <para>This downloads the specified
<filename>.raw
</filename>
1003 image with verification disabled. Then, a shell is opened in it
1004 and a root password is set. Afterwards the shell is left, and
1005 the machine started as system service. With the last command a
1006 login prompt into the container is requested.
</para>
1010 <title>Exports a container image as tar file
</title>
1012 <programlisting># machinectl export-tar fedora myfedora.tar.xz
</programlisting>
1014 <para>Exports the container
<literal>fedora
</literal> as an
1015 xz-compressed tar file
<filename>myfedora.tar.xz
</filename> into the
1016 current directory.
</para>
1020 <title>Create a new shell session
</title>
1022 <programlisting># machinectl shell --uid=lennart
</programlisting>
1024 <para>This creates a new shell session on the local host for
1025 the user ID
<literal>lennart
</literal>, in a
<citerefentry
1026 project='die-net'
><refentrytitle>su
</refentrytitle><manvolnum>1</manvolnum></citerefentry>-like
1033 <title>Exit status
</title>
1035 <para>On success,
0 is returned, a non-zero failure code
1039 <xi:include href=
"less-variables.xml" />
1042 <title>See Also
</title>
1044 <citerefentry><refentrytitle>systemd-machined.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
1045 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1046 <citerefentry><refentrytitle>systemd.special
</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1047 <citerefentry project='die-net'
><refentrytitle>tar
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1048 <citerefentry project='die-net'
><refentrytitle>xz
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1049 <citerefentry project='die-net'
><refentrytitle>gzip
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1050 <citerefentry project='die-net'
><refentrytitle>bzip2
</refentrytitle><manvolnum>1</manvolnum></citerefentry>