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 This file is part of systemd.
8 Copyright 2013 Zbigniew Jędrzejewski-Szmek
10 systemd is free software; you can redistribute it and/or modify it
11 under the terms of the GNU Lesser General Public License as published by
12 the Free Software Foundation; either version 2.1 of the License, or
13 (at your option) any later version.
15 systemd is distributed in the hope that it will be useful, but
16 WITHOUT ANY WARRANTY; without even the implied warranty of
17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18 Lesser General Public License for more details.
20 You should have received a copy of the GNU Lesser General Public License
21 along with systemd; If not, see <http://www.gnu.org/licenses/>.
24 <refentry id=
"machinectl" conditional='ENABLE_MACHINED'
25 xmlns:
xi=
"http://www.w3.org/2001/XInclude">
28 <title>machinectl
</title>
29 <productname>systemd
</productname>
33 <contrib>Developer
</contrib>
34 <firstname>Lennart
</firstname>
35 <surname>Poettering
</surname>
36 <email>lennart@poettering.net
</email>
42 <refentrytitle>machinectl
</refentrytitle>
43 <manvolnum>1</manvolnum>
47 <refname>machinectl
</refname>
48 <refpurpose>Control the systemd machine manager
</refpurpose>
53 <command>machinectl
</command>
54 <arg choice=
"opt" rep=
"repeat">OPTIONS
</arg>
55 <arg choice=
"req">COMMAND
</arg>
56 <arg choice=
"opt" rep=
"repeat">NAME
</arg>
61 <title>Description
</title>
63 <para><command>machinectl
</command> may be used to introspect and
64 control the state of the
65 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
66 virtual machine and container registration manager
67 <citerefentry><refentrytitle>systemd-machined.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
</para>
69 <para><command>machinectl
</command> may be used to execute
70 operations on machines and images. Machines in this sense are
71 considered running instances of:
</para>
74 <listitem><para>Virtual Machines (VMs) that virtualize hardware
75 to run full operating system (OS) instances (including their kernels)
76 in a virtualized environment on top of the host OS.
</para></listitem>
78 <listitem><para>Containers that share the hardware and
79 OS kernel with the host OS, in order to run
80 OS userspace instances on top the host OS.
</para></listitem>
82 <listitem><para>The host system itself
</para></listitem>
85 <para>Machines are identified by names that follow the same rules
86 as UNIX and DNS host names, for details, see below. Machines are
87 instantiated from disk or file system images that frequently — but not
88 necessarily — carry the same name as machines running from
89 them. Images in this sense are considered:
</para>
92 <listitem><para>Directory trees containing an OS, including its
93 top-level directories
<filename>/usr
</filename>,
94 <filename>/etc
</filename>, and so on.
</para></listitem>
96 <listitem><para>btrfs subvolumes containing OS trees, similar to
97 normal directory trees.
</para></listitem>
99 <listitem><para>Binary
"raw" disk images containing MBR or GPT
100 partition tables and Linux file system partitions.
</para></listitem>
102 <listitem><para>The file system tree of the host OS itself.
</para></listitem>
108 <title>Options
</title>
110 <para>The following options are understood:
</para>
114 <term><option>-p
</option></term>
115 <term><option>--property=
</option></term>
117 <listitem><para>When showing machine or image properties,
118 limit the output to certain properties as specified by the
119 argument. If not specified, all set properties are shown. The
120 argument should be a property name, such as
121 <literal>Name
</literal>. If specified more than once, all
122 properties with the specified names are
123 shown.
</para></listitem>
127 <term><option>-a
</option></term>
128 <term><option>--all
</option></term>
130 <listitem><para>When showing machine or image properties, show
131 all properties regardless of whether they are set or
134 <para>When listing VM or container images, do not suppress
135 images beginning in a dot character
136 (
<literal>.
</literal>).
</para>
138 <para>When cleaning VM or container images, remove all images, not just hidden ones.
</para></listitem>
142 <term><option>--value
</option></term>
144 <listitem><para>When printing properties with
<command>show
</command>, only print the value,
145 and skip the property name and
<literal>=
</literal>.
</para></listitem>
149 <term><option>-l
</option></term>
150 <term><option>--full
</option></term>
152 <listitem><para>Do not ellipsize process tree entries.
</para>
157 <term><option>--no-ask-password
</option></term>
159 <listitem><para>Do not query the user for authentication for
160 privileged operations.
</para></listitem>
164 <term><option>--kill-who=
</option></term>
166 <listitem><para>When used with
<command>kill
</command>, choose
167 which processes to kill. Must be one of
168 <option>leader
</option>, or
<option>all
</option> to select
169 whether to kill only the leader process of the machine or all
170 processes of the machine. If omitted, defaults to
171 <option>all
</option>.
</para></listitem>
175 <term><option>-s
</option></term>
176 <term><option>--signal=
</option></term>
178 <listitem><para>When used with
<command>kill
</command>, choose
179 which signal to send to selected processes. Must be one of the
180 well-known signal specifiers, such as
181 <constant>SIGTERM
</constant>,
<constant>SIGINT
</constant> or
182 <constant>SIGSTOP
</constant>. If omitted, defaults to
183 <constant>SIGTERM
</constant>.
</para></listitem>
187 <term><option>--uid=
</option></term>
189 <listitem><para>When used with the
<command>shell
</command>
190 command, chooses the user ID to open the interactive shell
191 session as. If this switch is not specified, defaults to
192 <literal>root
</literal>. Note that this switch is not
193 supported for the
<command>login
</command> command (see
194 below).
</para></listitem>
198 <term><option>-E
<replaceable>NAME
</replaceable>=
<replaceable>VALUE
</replaceable></option></term>
199 <term><option>--setenv=
<replaceable>NAME
</replaceable>=
<replaceable>VALUE
</replaceable></option></term>
201 <listitem><para>When used with the
<command>shell
</command> command, sets an environment
202 variable to pass to the executed shell. Takes an environment variable name and value,
203 separated by
<literal>=
</literal>. This switch may be used multiple times to set multiple
204 environment variables. Note that this switch is not supported for the
205 <command>login
</command> command (see below).
</para></listitem>
209 <term><option>--mkdir
</option></term>
211 <listitem><para>When used with
<command>bind
</command>, creates
212 the destination directory before applying the bind
213 mount.
</para></listitem>
217 <term><option>--read-only
</option></term>
219 <listitem><para>When used with
<command>bind
</command>, applies
220 a read-only bind mount.
</para>
222 <para>When used with
<command>clone
</command>,
<command>import-raw
</command> or
<command>import-tar
</command> a
223 read-only container or VM image is created.
</para></listitem>
227 <term><option>-n
</option></term>
228 <term><option>--lines=
</option></term>
230 <listitem><para>When used with
<command>status
</command>,
231 controls the number of journal lines to show, counting from
232 the most recent ones. Takes a positive integer argument.
233 Defaults to
10.
</para>
238 <term><option>-o
</option></term>
239 <term><option>--output=
</option></term>
241 <listitem><para>When used with
<command>status
</command>,
242 controls the formatting of the journal entries that are shown.
243 For the available choices, see
244 <citerefentry><refentrytitle>journalctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
245 Defaults to
<literal>short
</literal>.
</para></listitem>
249 <term><option>--verify=
</option></term>
251 <listitem><para>When downloading a container or VM image,
252 specify whether the image shall be verified before it is made
253 available. Takes one of
<literal>no
</literal>,
254 <literal>checksum
</literal> and
<literal>signature
</literal>.
255 If
<literal>no
</literal>, no verification is done. If
256 <literal>checksum
</literal> is specified, the download is
257 checked for integrity after the transfer is complete, but no
258 signatures are verified. If
<literal>signature
</literal> is
259 specified, the checksum is verified and the image's signature
260 is checked against a local keyring of trustable vendors. It is
261 strongly recommended to set this option to
262 <literal>signature
</literal> if the server and protocol
263 support this. Defaults to
264 <literal>signature
</literal>.
</para></listitem>
268 <term><option>--force
</option></term>
270 <listitem><para>When downloading a container or VM image, and
271 a local copy by the specified local machine name already
272 exists, delete it first and replace it by the newly downloaded
273 image.
</para></listitem>
277 <term><option>--format=
</option></term>
279 <listitem><para>When used with the
<option>export-tar
</option>
280 or
<option>export-raw
</option> commands, specifies the
281 compression format to use for the resulting file. Takes one of
282 <literal>uncompressed
</literal>,
<literal>xz
</literal>,
283 <literal>gzip
</literal>,
<literal>bzip2
</literal>. By default,
284 the format is determined automatically from the image file
285 name passed.
</para></listitem>
288 <xi:include href=
"user-system-options.xml" xpointer=
"host" />
289 <xi:include href=
"user-system-options.xml" xpointer=
"machine" />
291 <xi:include href=
"standard-options.xml" xpointer=
"no-pager" />
292 <xi:include href=
"standard-options.xml" xpointer=
"no-legend" />
293 <xi:include href=
"standard-options.xml" xpointer=
"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
334 virtual machines or containers or the manager itself. If no
335 argument is specified, properties of the manager will be
336 shown. If a NAME is specified, properties of this virtual
337 machine or container are shown. By default, empty properties
338 are suppressed. Use
<option>--all
</option> to show those too.
339 To select specific properties to show, use
340 <option>--property=
</option>. This command is intended to be
341 used whenever computer-parsable output is required, and does
342 not print the cgroup tree or journal entries. Use
343 <command>status
</command> if you are looking for formatted
344 human-readable output.
</para></listitem>
348 <term><command>start
</command> <replaceable>NAME
</replaceable>...
</term>
350 <listitem><para>Start a container as a system service, using
351 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
352 This starts
<filename>systemd-nspawn@.service
</filename>,
353 instantiated for the specified machine name, similar to the
354 effect of
<command>systemctl start
</command> on the service
355 name.
<command>systemd-nspawn
</command> looks for a container
356 image by the specified name in
357 <filename>/var/lib/machines/
</filename> (and other search
358 paths, see below) and runs it. Use
359 <command>list-images
</command> (see below) for listing
360 available container images to start.
</para>
363 <citerefentry><refentrytitle>systemd-machined.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
364 also interfaces with a variety of other container and VM
365 managers,
<command>systemd-nspawn
</command> is just one
366 implementation of it. Most of the commands available in
367 <command>machinectl
</command> may be used on containers or VMs
368 controlled by other managers, not just
369 <command>systemd-nspawn
</command>. Starting VMs and container
370 images on those managers requires manager-specific
373 <para>To interactively start a container on the command line
374 with full access to the container's console, please invoke
375 <command>systemd-nspawn
</command> directly. To stop a running
376 container use
<command>machinectl poweroff
</command>.
</para></listitem>
380 <term><command>login
</command> [
<replaceable>NAME
</replaceable>]
</term>
382 <listitem><para>Open an interactive terminal login session in
383 a container or on the local host. If an argument is supplied,
384 it refers to the container machine to connect to. If none is
385 specified, or the container name is specified as the empty
386 string, or the special machine name
<literal>.host
</literal>
387 (see below) is specified, the connection is made to the local
388 host instead. This will create a TTY connection to a specific
389 container or the local host and asks for the execution of a
390 getty on it. Note that this is only supported for containers
392 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
393 as init system.
</para>
395 <para>This command will open a full login prompt on the
396 container or the local host, which then asks for username and
397 password. Use
<command>shell
</command> (see below) or
398 <citerefentry><refentrytitle>systemd-run
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
399 with the
<option>--machine=
</option> switch to directly invoke
400 a single command, either interactively or in the
401 background.
</para></listitem>
405 <term><command>shell
</command> [[
<replaceable>NAME
</replaceable>@]
<replaceable>NAME
</replaceable> [
<replaceable>PATH
</replaceable> [
<replaceable>ARGUMENTS
</replaceable>...]]]
</term>
407 <listitem><para>Open an interactive shell session in a
408 container or on the local host. The first argument refers to
409 the container machine to connect to. If none is specified, or
410 the machine name is specified as the empty string, or the
411 special machine name
<literal>.host
</literal> (see below) is
412 specified, the connection is made to the local host
413 instead. This works similar to
<command>login
</command> but
414 immediately invokes a user process. This command runs the
415 specified executable with the specified arguments, or
416 <filename>/bin/sh
</filename> if none is specified. By default,
417 opens a
<literal>root
</literal> shell, but by using
418 <option>--uid=
</option>, or by prefixing the machine name with
419 a username and an
<literal>@
</literal> character, a different
420 user may be selected. Use
<option>--setenv=
</option> to set
421 environment variables for the executed process.
</para>
423 <para>When using the
<command>shell
</command> command without
424 arguments, (thus invoking the executed shell or command on the
425 local host), it is in many ways similar to a
<citerefentry
426 project='die-net'
><refentrytitle>su
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
427 session, but, unlike
<command>su
</command>, completely isolates
428 the new session from the originating session, so that it
429 shares no process or session properties, and is in a clean and
430 well-defined state. It will be tracked in a new utmp, login,
431 audit, security and keyring session, and will not inherit any
432 environment variables or resource limits, among other
436 <citerefentry><refentrytitle>systemd-run
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
437 may be used in place of the
<command>shell
</command> command,
438 and allows more detailed, low-level configuration of the
439 invoked unit. However, it is frequently more privileged than
440 the
<command>shell
</command> command.
</para></listitem>
444 <term><command>enable
</command> <replaceable>NAME
</replaceable>...
</term>
445 <term><command>disable
</command> <replaceable>NAME
</replaceable>...
</term>
447 <listitem><para>Enable or disable a container as a system
448 service to start at system boot, using
449 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
450 This enables or disables
451 <filename>systemd-nspawn@.service
</filename>, instantiated for
452 the specified machine name, similar to the effect of
453 <command>systemctl enable
</command> or
<command>systemctl
454 disable
</command> on the service name.
</para></listitem>
458 <term><command>poweroff
</command> <replaceable>NAME
</replaceable>...
</term>
460 <listitem><para>Power off one or more containers. This will
461 trigger a reboot by sending SIGRTMIN+
4 to the container's init
462 process, which causes systemd-compatible init systems to shut
463 down cleanly. Use
<command>stop
</command> as alias for
<command>poweroff
</command>.
464 This operation does not work on containers that do not run a
465 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>-compatible
466 init system, such as sysvinit. Use
467 <command>terminate
</command> (see below) to immediately
468 terminate a container or VM, without cleanly shutting it
469 down.
</para></listitem>
473 <term><command>reboot
</command> <replaceable>NAME
</replaceable>...
</term>
475 <listitem><para>Reboot one or more containers. This will
476 trigger a reboot by sending SIGINT to the container's init
477 process, which is roughly equivalent to pressing Ctrl+Alt+Del
478 on a non-containerized system, and is compatible with
479 containers running any system manager.
</para></listitem>
483 <term><command>terminate
</command> <replaceable>NAME
</replaceable>...
</term>
485 <listitem><para>Immediately terminates a virtual machine or
486 container, without cleanly shutting it down. This kills all
487 processes of the virtual machine or container and deallocates
488 all resources attached to that instance. Use
489 <command>poweroff
</command> to issue a clean shutdown
490 request.
</para></listitem>
494 <term><command>kill
</command> <replaceable>NAME
</replaceable>...
</term>
496 <listitem><para>Send a signal to one or more processes of the
497 virtual machine or container. This means processes as seen by
498 the host, not the processes inside the virtual machine or
499 container. Use
<option>--kill-who=
</option> to select which
500 process to kill. Use
<option>--signal=
</option> to select the
501 signal to send.
</para></listitem>
505 <term><command>bind
</command> <replaceable>NAME
</replaceable> <replaceable>PATH
</replaceable> [
<replaceable>PATH
</replaceable>]
</term>
507 <listitem><para>Bind mounts a directory from the host into the
508 specified container. The first directory argument is the
509 source directory on the host, the second directory argument
510 is the destination directory in the container. When the
511 latter is omitted, the destination path in the container is
512 the same as the source path on the host. When combined with
513 the
<option>--read-only
</option> switch, a ready-only bind
514 mount is created. When combined with the
515 <option>--mkdir
</option> switch, the destination path is first
516 created before the mount is applied. Note that this option is
517 currently only supported for
518 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
519 containers.
</para></listitem>
523 <term><command>copy-to
</command> <replaceable>NAME
</replaceable> <replaceable>PATH
</replaceable> [
<replaceable>PATH
</replaceable>]
</term>
525 <listitem><para>Copies files or directories from the host
526 system into a running container. Takes a container name,
527 followed by the source path on the host and the destination
528 path in the container. If the destination path is omitted, the
529 same as the source path is used.
</para></listitem>
534 <term><command>copy-from
</command> <replaceable>NAME
</replaceable> <replaceable>PATH
</replaceable> [
<replaceable>PATH
</replaceable>]
</term>
536 <listitem><para>Copies files or directories from a container
537 into the host system. Takes a container name, followed by the
538 source path in the container the destination path on the host.
539 If the destination path is omitted, the same as the source path
540 is used.
</para></listitem>
542 </variablelist></refsect2>
544 <refsect2><title>Image Commands
</title><variablelist>
547 <term><command>list-images
</command></term>
549 <listitem><para>Show a list of locally installed container and
550 VM images. This enumerates all raw disk images and container
551 directories and subvolumes in
552 <filename>/var/lib/machines/
</filename> (and other search
553 paths, see below). Use
<command>start
</command> (see above) to
554 run a container off one of the listed images. Note that, by
555 default, containers whose name begins with a dot
556 (
<literal>.
</literal>) are not shown. To show these too,
557 specify
<option>--all
</option>. Note that a special image
558 <literal>.host
</literal> always implicitly exists and refers
559 to the image the host itself is booted from.
</para></listitem>
563 <term><command>image-status
</command> [
<replaceable>NAME
</replaceable>...]
</term>
565 <listitem><para>Show terse status information about one or
566 more container or VM images. This function is intended to
567 generate human-readable output. Use
568 <command>show-image
</command> (see below) to generate
569 computer-parsable output instead.
</para></listitem>
573 <term><command>show-image
</command> [
<replaceable>NAME
</replaceable>...]
</term>
575 <listitem><para>Show properties of one or more registered
576 virtual machine or container images, or the manager itself. If
577 no argument is specified, properties of the manager will be
578 shown. If a NAME is specified, properties of this virtual
579 machine or container image are shown. By default, empty
580 properties are suppressed. Use
<option>--all
</option> to show
581 those too. To select specific properties to show, use
582 <option>--property=
</option>. This command is intended to be
583 used whenever computer-parsable output is required. Use
584 <command>image-status
</command> if you are looking for
585 formatted human-readable output.
</para></listitem>
589 <term><command>clone
</command> <replaceable>NAME
</replaceable> <replaceable>NAME
</replaceable></term>
591 <listitem><para>Clones a container or VM image. The arguments specify the name of the image to clone and the
592 name of the newly cloned image. Note that plain directory container images are cloned into btrfs subvolume
593 images with this command, if the underlying file system supports this. Note that cloning a container or VM
594 image is optimized for btrfs file systems, and might not be efficient on others, due to file system
597 <para>Note that this command leaves host name, machine ID and
598 all other settings that could identify the instance
599 unmodified. The original image and the cloned copy will hence
600 share these credentials, and it might be necessary to manually
601 change them in the copy.
</para>
603 <para>If combined with the
<option>--read-only
</option> switch a read-only cloned image is
604 created.
</para></listitem>
608 <term><command>rename
</command> <replaceable>NAME
</replaceable> <replaceable>NAME
</replaceable></term>
610 <listitem><para>Renames a container or VM image. The
611 arguments specify the name of the image to rename and the new
612 name of the image.
</para></listitem>
616 <term><command>read-only
</command> <replaceable>NAME
</replaceable> [
<replaceable>BOOL
</replaceable>]
</term>
618 <listitem><para>Marks or (unmarks) a container or VM image
619 read-only. Takes a VM or container image name, followed by a
620 boolean as arguments. If the boolean is omitted, positive is
621 implied, i.e. the image is marked read-only.
</para></listitem>
625 <term><command>remove
</command> <replaceable>NAME
</replaceable>...
</term>
627 <listitem><para>Removes one or more container or VM images.
628 The special image
<literal>.host
</literal>, which refers to
629 the host's own directory tree, may not be
630 removed.
</para></listitem>
634 <term><command>set-limit
</command> [
<replaceable>NAME
</replaceable>]
<replaceable>BYTES
</replaceable></term>
636 <listitem><para>Sets the maximum size in bytes that a specific
637 container or VM image, or all images, may grow up to on disk
638 (disk quota). Takes either one or two parameters. The first,
639 optional parameter refers to a container or VM image name. If
640 specified, the size limit of the specified image is changed. If
641 omitted, the overall size limit of the sum of all images stored
642 locally is changed. The final argument specifies the size
643 limit in bytes, possibly suffixed by the usual K, M, G, T
644 units. If the size limit shall be disabled, specify
645 <literal>-
</literal> as size.
</para>
647 <para>Note that per-container size limits are only supported
648 on btrfs file systems. Also note that, if
649 <command>set-limit
</command> is invoked without an image
650 parameter, and
<filename>/var/lib/machines
</filename> is
651 empty, and the directory is not located on btrfs, a btrfs
652 loopback file is implicitly created as
653 <filename>/var/lib/machines.raw
</filename> with the given
655 <filename>/var/lib/machines
</filename>. The size of the
656 loopback may later be readjusted with
657 <command>set-limit
</command>, as well. If such a
658 loopback-mounted
<filename>/var/lib/machines
</filename>
659 directory is used,
<command>set-limit
</command> without an image
660 name alters both the quota setting within the file system as
661 well as the loopback file and file system size
662 itself.
</para></listitem>
666 <term><command>clean
</command></term>
668 <listitem><para>Remove hidden VM or container images (or all). This command removes all hidden machine images
669 from
<filename>/var/lib/machines
</filename>, i.e. those whose name begins with a dot. Use
<command>machinectl
670 list-images --all
</command> to see a list of all machine images, including the hidden ones.
</para>
672 <para>When combined with the
<option>--all
</option> switch removes all images, not just hidden ones. This
673 command effectively empties
<filename>/var/lib/machines
</filename>.
</para>
675 <para>Note that commands such as
<command>machinectl pull-tar
</command> or
<command>machinectl
676 pull-raw
</command> usually create hidden, read-only, unmodified machine images from the downloaded image first,
677 before cloning a writable working copy of it, in order to avoid duplicate downloads in case of images that are
678 reused multiple times. Use
<command>machinectl clean
</command> to remove old, hidden images created this
679 way.
</para></listitem>
682 </variablelist></refsect2>
684 <refsect2><title>Image Transfer Commands
</title><variablelist>
687 <term><command>pull-tar
</command> <replaceable>URL
</replaceable> [
<replaceable>NAME
</replaceable>]
</term>
689 <listitem><para>Downloads a
<filename>.tar
</filename>
690 container image from the specified URL, and makes it available
691 under the specified local machine name. The URL must be of
692 type
<literal>http://
</literal> or
693 <literal>https://
</literal>, and must refer to a
694 <filename>.tar
</filename>,
<filename>.tar.gz
</filename>,
695 <filename>.tar.xz
</filename> or
<filename>.tar.bz2
</filename>
696 archive file. If the local machine name is omitted, it
697 is automatically derived from the last component of the URL,
698 with its suffix removed.
</para>
700 <para>The image is verified before it is made available,
701 unless
<option>--verify=no
</option> is specified. Verification
702 is done via SHA256SUMS and SHA256SUMS.gpg files that need to
703 be made available on the same web server, under the same URL
704 as the
<filename>.tar
</filename> file, but with the last
705 component (the filename) of the URL replaced. With
706 <option>--verify=checksum
</option>, only the SHA256 checksum
707 for the file is verified, based on the
708 <filename>SHA256SUMS
</filename> file. With
709 <option>--verify=signature
</option>, the SHA256SUMS file is
710 first verified with detached GPG signature file
711 <filename>SHA256SUMS.gpg
</filename>. The public key for this
712 verification step needs to be available in
713 <filename>/usr/lib/systemd/import-pubring.gpg
</filename> or
714 <filename>/etc/systemd/import-pubring.gpg
</filename>.
</para>
716 <para>The container image will be downloaded and stored in a
717 read-only subvolume in
718 <filename>/var/lib/machines/
</filename> that is named after
719 the specified URL and its HTTP etag. A writable snapshot is
720 then taken from this subvolume, and named after the specified
721 local name. This behavior ensures that creating multiple
722 container instances of the same URL is efficient, as multiple
723 downloads are not necessary. In order to create only the
724 read-only image, and avoid creating its writable snapshot,
725 specify
<literal>-
</literal> as local machine name.
</para>
727 <para>Note that the read-only subvolume is prefixed with
728 <filename>.tar-
</filename>, and is thus not shown by
729 <command>list-images
</command>, unless
<option>--all
</option>
732 <para>Note that pressing C-c during execution of this command
733 will not abort the download. Use
734 <command>cancel-transfer
</command>, described
735 below.
</para></listitem>
739 <term><command>pull-raw
</command> <replaceable>URL
</replaceable> [
<replaceable>NAME
</replaceable>]
</term>
741 <listitem><para>Downloads a
<filename>.raw
</filename>
742 container or VM disk image from the specified URL, and makes
743 it available under the specified local machine name. The URL
744 must be of type
<literal>http://
</literal> or
745 <literal>https://
</literal>. The container image must either
746 be a
<filename>.qcow2
</filename> or raw disk image, optionally
747 compressed as
<filename>.gz
</filename>,
748 <filename>.xz
</filename>, or
<filename>.bz2
</filename>. If the
749 local machine name is omitted, it is automatically
750 derived from the last component of the URL, with its suffix
753 <para>Image verification is identical for raw and tar images
756 <para>If the downloaded image is in
757 <filename>.qcow2
</filename> format it is converted into a raw
758 image file before it is made available.
</para>
760 <para>Downloaded images of this type will be placed as
761 read-only
<filename>.raw
</filename> file in
762 <filename>/var/lib/machines/
</filename>. A local, writable
763 (reflinked) copy is then made under the specified local
764 machine name. To omit creation of the local, writable copy
765 pass
<literal>-
</literal> as local machine name.
</para>
767 <para>Similar to the behavior of
<command>pull-tar
</command>,
768 the read-only image is prefixed with
769 <filename>.raw-
</filename>, and thus not shown by
770 <command>list-images
</command>, unless
<option>--all
</option>
773 <para>Note that pressing C-c during execution of this command
774 will not abort the download. Use
775 <command>cancel-transfer
</command>, described
776 below.
</para></listitem>
780 <term><command>import-tar
</command> <replaceable>FILE
</replaceable> [
<replaceable>NAME
</replaceable>]
</term>
781 <term><command>import-raw
</command> <replaceable>FILE
</replaceable> [
<replaceable>NAME
</replaceable>]
</term>
782 <listitem><para>Imports a TAR or RAW container or VM image,
783 and places it under the specified name in
784 <filename>/var/lib/machines/
</filename>. When
785 <command>import-tar
</command> is used, the file specified as
786 the first argument should be a tar archive, possibly compressed
787 with xz, gzip or bzip2. It will then be unpacked into its own
788 subvolume in
<filename>/var/lib/machines
</filename>. When
789 <command>import-raw
</command> is used, the file should be a
790 qcow2 or raw disk image, possibly compressed with xz, gzip or
791 bzip2. If the second argument (the resulting image name) is
792 not specified, it is automatically derived from the file
793 name. If the file name is passed as
<literal>-
</literal>, the
794 image is read from standard input, in which case the second
795 argument is mandatory.
</para>
797 <para>Both
<command>pull-tar
</command> and
<command>pull-raw
</command>
798 will resize
<filename>/var/lib/machines.raw
</filename> and the
799 filesystem therein as necessary. Optionally, the
800 <option>--read-only
</option> switch may be used to create a
801 read-only container or VM image. No cryptographic validation
802 is done when importing the images.
</para>
804 <para>Much like image downloads, ongoing imports may be listed
805 with
<command>list-transfers
</command> and aborted with
806 <command>cancel-transfer
</command>.
</para></listitem>
810 <term><command>export-tar
</command> <replaceable>NAME
</replaceable> [
<replaceable>FILE
</replaceable>]
</term>
811 <term><command>export-raw
</command> <replaceable>NAME
</replaceable> [
<replaceable>FILE
</replaceable>]
</term>
812 <listitem><para>Exports a TAR or RAW container or VM image and
813 stores it in the specified file. The first parameter should be
814 a VM or container image name. The second parameter should be a
815 file path the TAR or RAW image is written to. If the path ends
816 in
<literal>.gz
</literal>, the file is compressed with gzip, if
817 it ends in
<literal>.xz
</literal>, with xz, and if it ends in
818 <literal>.bz2
</literal>, with bzip2. If the path ends in
819 neither, the file is left uncompressed. If the second argument
820 is missing, the image is written to standard output. The
821 compression may also be explicitly selected with the
822 <option>--format=
</option> switch. This is in particular
823 useful if the second parameter is left unspecified.
</para>
825 <para>Much like image downloads and imports, ongoing exports
826 may be listed with
<command>list-transfers
</command> and
828 <command>cancel-transfer
</command>.
</para>
830 <para>Note that, currently, only directory and subvolume images
831 may be exported as TAR images, and only raw disk images as RAW
832 images.
</para></listitem>
836 <term><command>list-transfers
</command></term>
838 <listitem><para>Shows a list of container or VM image
839 downloads, imports and exports that are currently in
840 progress.
</para></listitem>
844 <term><command>cancel-transfers
</command> <replaceable>ID
</replaceable>...
</term>
846 <listitem><para>Aborts a download, import or export of the
847 container or VM image with the specified ID. To list ongoing
848 transfers and their IDs, use
849 <command>list-transfers
</command>.
</para></listitem>
852 </variablelist></refsect2>
857 <title>Machine and Image Names
</title>
859 <para>The
<command>machinectl
</command> tool operates on machines
860 and images whose names must be chosen following strict
861 rules. Machine names must be suitable for use as host names
862 following a conservative subset of DNS and UNIX/Linux
863 semantics. Specifically, they must consist of one or more
864 non-empty label strings, separated by dots. No leading or trailing
865 dots are allowed. No sequences of multiple dots are allowed. The
866 label strings may only consist of alphanumeric characters as well
867 as the dash and underscore. The maximum length of a machine name
868 is
64 characters.
</para>
870 <para>A special machine with the name
<literal>.host
</literal>
871 refers to the running host system itself. This is useful for execution
872 operations or inspecting the host system as well. Note that
873 <command>machinectl list
</command> will not show this special
874 machine unless the
<option>--all
</option> switch is specified.
</para>
876 <para>Requirements on image names are less strict, however, they must be
877 valid UTF-
8, must be suitable as file names (hence not be the
878 single or double dot, and not include a slash), and may not
879 contain control characters. Since many operations search for an
880 image by the name of a requested machine, it is recommended to name
881 images in the same strict fashion as machines.
</para>
883 <para>A special image with the name
<literal>.host
</literal>
884 refers to the image of the running host system. It hence
885 conceptually maps to the special
<literal>.host
</literal> machine
886 name described above. Note that
<command>machinectl
887 list-images
</command> will not show this special image either, unless
888 <option>--all
</option> is specified.
</para>
892 <title>Files and Directories
</title>
894 <para>Machine images are preferably stored in
895 <filename>/var/lib/machines/
</filename>, but are also searched for
896 in
<filename>/usr/local/lib/machines/
</filename> and
897 <filename>/usr/lib/machines/
</filename>. For compatibility reasons,
898 the directory
<filename>/var/lib/container/
</filename> is
899 searched, too. Note that images stored below
900 <filename>/usr
</filename> are always considered read-only. It is
901 possible to symlink machines images from other directories into
902 <filename>/var/lib/machines/
</filename> to make them available for
903 control with
<command>machinectl
</command>.
</para>
905 <para>Note that many image operations are only supported,
906 efficient or atomic on btrfs file systems. Due to this, if the
907 <command>pull-tar
</command>,
<command>pull-raw
</command>,
908 <command>import-tar
</command>,
<command>import-raw
</command> and
909 <command>set-limit
</command> commands notice that
910 <filename>/var/lib/machines
</filename> is empty and not located on
911 btrfs, they will implicitly set up a loopback file
912 <filename>/var/lib/machines.raw
</filename> containing a btrfs file
913 system that is mounted to
914 <filename>/var/lib/machines
</filename>. The size of this loopback
915 file may be controlled dynamically with
916 <command>set-limit
</command>.
</para>
918 <para>Disk images are understood by
919 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
920 and
<command>machinectl
</command> in three formats:
</para>
923 <listitem><para>A simple directory tree, containing the files
924 and directories of the container to boot.
</para></listitem>
926 <listitem><para>Subvolumes (on btrfs file systems), which are
927 similar to the simple directories, described above. However,
928 they have additional benefits, such as efficient cloning and
929 quota reporting.
</para></listitem>
931 <listitem><para>"Raw" disk images, i.e. binary images of disks
932 with a GPT or MBR partition table. Images of this type are
933 regular files with the suffix
934 <literal>.raw
</literal>.
</para></listitem>
938 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
939 for more information on image formats, in particular its
940 <option>--directory=
</option> and
<option>--image=
</option>
945 <title>Examples
</title>
947 <title>Download an Ubuntu image and open a shell in it
</title>
949 <programlisting># machinectl pull-tar https://cloud-images.ubuntu.com/trusty/current/trusty-server-cloudimg-amd64-root.tar.gz
950 # systemd-nspawn -M trusty-server-cloudimg-amd64-root
</programlisting>
952 <para>This downloads and verifies the specified
953 <filename>.tar
</filename> image, and then uses
954 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
955 to open a shell in it.
</para>
959 <title>Download a Fedora image, set a root password in it, start
960 it as service
</title>
962 <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
963 # systemd-nspawn -M Fedora-Cloud-Base-
23-
20151030
966 # machinectl start Fedora-Cloud-Base-
23-
20151030
967 # machinectl login Fedora-Cloud-Base-
23-
20151030</programlisting>
969 <para>This downloads the specified
<filename>.raw
</filename>
970 image with verification disabled. Then, a shell is opened in it
971 and a root password is set. Afterwards the shell is left, and
972 the machine started as system service. With the last command a
973 login prompt into the container is requested.
</para>
977 <title>Exports a container image as tar file
</title>
979 <programlisting># machinectl export-tar fedora myfedora.tar.xz
</programlisting>
981 <para>Exports the container
<literal>fedora
</literal> as an
982 xz-compressed tar file
<filename>myfedora.tar.xz
</filename> into the
983 current directory.
</para>
987 <title>Create a new shell session
</title>
989 <programlisting># machinectl shell --uid=lennart
</programlisting>
991 <para>This creates a new shell session on the local host for
992 the user ID
<literal>lennart
</literal>, in a
<citerefentry
993 project='die-net'
><refentrytitle>su
</refentrytitle><manvolnum>1</manvolnum></citerefentry>-like
1000 <title>Exit status
</title>
1002 <para>On success,
0 is returned, a non-zero failure code
1006 <xi:include href=
"less-variables.xml" />
1009 <title>See Also
</title>
1011 <citerefentry><refentrytitle>systemd-machined.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
1012 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1013 <citerefentry><refentrytitle>systemd.special
</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1014 <citerefentry project='die-net'
><refentrytitle>tar
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1015 <citerefentry project='die-net'
><refentrytitle>xz
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1016 <citerefentry project='die-net'
><refentrytitle>gzip
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1017 <citerefentry project='die-net'
><refentrytitle>bzip2
</refentrytitle><manvolnum>1</manvolnum></citerefentry>