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.
</para>
88 <para>Machines are instantiated from disk or file system images that
89 frequently — but not necessarily — carry the same name as machines running
90 from them. Images in this sense may be:
</para>
93 <listitem><para>Directory trees containing an OS, including the
94 top-level directories
<filename>/usr
</filename>,
95 <filename>/etc
</filename>, and so on.
</para></listitem>
97 <listitem><para>btrfs subvolumes containing OS trees, similar to
98 normal directory trees.
</para></listitem>
100 <listitem><para>Binary
"raw" disk images containing MBR or GPT
101 partition tables and Linux file system partitions.
</para></listitem>
103 <listitem><para>The file system tree of the host OS itself.
</para></listitem>
109 <title>Options
</title>
111 <para>The following options are understood:
</para>
115 <term><option>-p
</option></term>
116 <term><option>--property=
</option></term>
118 <listitem><para>When showing machine or image properties,
119 limit the output to certain properties as specified by the
120 argument. If not specified, all set properties are shown. The
121 argument should be a property name, such as
122 <literal>Name
</literal>. If specified more than once, all
123 properties with the specified names are
124 shown.
</para></listitem>
128 <term><option>-a
</option></term>
129 <term><option>--all
</option></term>
131 <listitem><para>When showing machine or image properties, show
132 all properties regardless of whether they are set or
135 <para>When listing VM or container images, do not suppress
136 images beginning in a dot character
137 (
<literal>.
</literal>).
</para>
139 <para>When cleaning VM or container images, remove all images, not just hidden ones.
</para></listitem>
143 <term><option>--value
</option></term>
145 <listitem><para>When printing properties with
<command>show
</command>, only print the value,
146 and skip the property name and
<literal>=
</literal>.
</para></listitem>
150 <term><option>-l
</option></term>
151 <term><option>--full
</option></term>
153 <listitem><para>Do not ellipsize process tree entries.
</para>
158 <term><option>--no-ask-password
</option></term>
160 <listitem><para>Do not query the user for authentication for
161 privileged operations.
</para></listitem>
165 <term><option>--kill-who=
</option></term>
167 <listitem><para>When used with
<command>kill
</command>, choose
168 which processes to kill. Must be one of
169 <option>leader
</option>, or
<option>all
</option> to select
170 whether to kill only the leader process of the machine or all
171 processes of the machine. If omitted, defaults to
172 <option>all
</option>.
</para></listitem>
176 <term><option>-s
</option></term>
177 <term><option>--signal=
</option></term>
179 <listitem><para>When used with
<command>kill
</command>, choose
180 which signal to send to selected processes. Must be one of the
181 well-known signal specifiers, such as
182 <constant>SIGTERM
</constant>,
<constant>SIGINT
</constant> or
183 <constant>SIGSTOP
</constant>. If omitted, defaults to
184 <constant>SIGTERM
</constant>.
</para></listitem>
188 <term><option>--uid=
</option></term>
190 <listitem><para>When used with the
<command>shell
</command> command, chooses the user ID to
191 open the interactive shell session as. If the argument to the
<command>shell
</command>
192 command also specifies a user name, this option is ignored. If the name is not specified
193 in either way,
<literal>root
</literal> will be used by default. Note that this switch is
194 not supported for the
<command>login
</command> command (see 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>
289 <term><option>--max-addresses=
</option></term>
291 <listitem><para>When used with the
<option>list-machines
</option>
292 command, limits the number of ip addresses output for every machine.
293 Defaults to
1. All addresses can be requested with
<literal>all
</literal>
294 as argument to
<option>--max-addresses
</option> . If the argument to
295 <option>--max-addresses
</option> is less than the actual number
296 of addresses,
<literal>...
</literal>follows the last address.
297 If multiple addresses are to be written for a given machine, every
298 address except the first one is on a new line and is followed by
299 <literal>,
</literal> if another address will be output afterwards.
</para></listitem>
302 <xi:include href=
"user-system-options.xml" xpointer=
"host" />
305 <term><option>-M
</option></term>
306 <term><option>--machine=
</option></term>
308 <listitem><para>Connect to
309 <citerefentry><refentrytitle>systemd-machined.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
310 running in a local container, to perform the specified operation within
311 the container.
</para></listitem>
314 <xi:include href=
"standard-options.xml" xpointer=
"no-pager" />
315 <xi:include href=
"standard-options.xml" xpointer=
"no-legend" />
316 <xi:include href=
"standard-options.xml" xpointer=
"help" />
317 <xi:include href=
"standard-options.xml" xpointer=
"version" />
322 <title>Commands
</title>
324 <para>The following commands are understood:
</para>
326 <refsect2><title>Machine Commands
</title><variablelist>
329 <term><command>list
</command></term>
331 <listitem><para>List currently running (online) virtual
332 machines and containers. To enumerate machine images that can
333 be started, use
<command>list-images
</command> (see
334 below). Note that this command hides the special
335 <literal>.host
</literal> machine by default. Use the
336 <option>--all
</option> switch to show it.
</para></listitem>
340 <term><command>status
</command> <replaceable>NAME
</replaceable>…
</term>
342 <listitem><para>Show runtime status information about
343 one or more virtual machines and containers, followed by the
344 most recent log data from the journal. This function is
345 intended to generate human-readable output. If you are looking
346 for computer-parsable output, use
<command>show
</command>
347 instead. Note that the log data shown is reported by the
348 virtual machine or container manager, and frequently contains
349 console output of the machine, but not necessarily journal
350 contents of the machine itself.
</para></listitem>
354 <term><command>show
</command> [
<replaceable>NAME
</replaceable>…]
</term>
356 <listitem><para>Show properties of one or more registered virtual machines or containers or the manager
357 itself. If no argument is specified, properties of the manager will be shown. If a NAME is specified,
358 properties of this virtual machine or container are shown. By default, empty properties are suppressed. Use
359 <option>--all
</option> to show those too. To select specific properties to show, use
360 <option>--property=
</option>. This command is intended to be used whenever computer-parsable output is
361 required, and does not print the control group tree or journal entries. Use
<command>status
</command> if you
362 are looking for formatted human-readable output.
</para></listitem>
366 <term><command>start
</command> <replaceable>NAME
</replaceable>…
</term>
368 <listitem><para>Start a container as a system service, using
369 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
370 This starts
<filename>systemd-nspawn@.service
</filename>,
371 instantiated for the specified machine name, similar to the
372 effect of
<command>systemctl start
</command> on the service
373 name.
<command>systemd-nspawn
</command> looks for a container
374 image by the specified name in
375 <filename>/var/lib/machines/
</filename> (and other search
376 paths, see below) and runs it. Use
377 <command>list-images
</command> (see below) for listing
378 available container images to start.
</para>
381 <citerefentry><refentrytitle>systemd-machined.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
382 also interfaces with a variety of other container and VM
383 managers,
<command>systemd-nspawn
</command> is just one
384 implementation of it. Most of the commands available in
385 <command>machinectl
</command> may be used on containers or VMs
386 controlled by other managers, not just
387 <command>systemd-nspawn
</command>. Starting VMs and container
388 images on those managers requires manager-specific
391 <para>To interactively start a container on the command line
392 with full access to the container's console, please invoke
393 <command>systemd-nspawn
</command> directly. To stop a running
394 container use
<command>machinectl poweroff
</command>.
</para></listitem>
398 <term><command>login
</command> [
<replaceable>NAME
</replaceable>]
</term>
400 <listitem><para>Open an interactive terminal login session in
401 a container or on the local host. If an argument is supplied,
402 it refers to the container machine to connect to. If none is
403 specified, or the container name is specified as the empty
404 string, or the special machine name
<literal>.host
</literal>
405 (see below) is specified, the connection is made to the local
406 host instead. This will create a TTY connection to a specific
407 container or the local host and asks for the execution of a
408 getty on it. Note that this is only supported for containers
410 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
411 as init system.
</para>
413 <para>This command will open a full login prompt on the
414 container or the local host, which then asks for username and
415 password. Use
<command>shell
</command> (see below) or
416 <citerefentry><refentrytitle>systemd-run
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
417 with the
<option>--machine=
</option> switch to directly invoke
418 a single command, either interactively or in the
419 background.
</para></listitem>
423 <term><command>shell
</command> [[
<replaceable>NAME
</replaceable>@]
<replaceable>NAME
</replaceable> [
<replaceable>PATH
</replaceable> [
<replaceable>ARGUMENTS
</replaceable>…]]]
</term>
425 <listitem><para>Open an interactive shell session in a
426 container or on the local host. The first argument refers to
427 the container machine to connect to. If none is specified, or
428 the machine name is specified as the empty string, or the
429 special machine name
<literal>.host
</literal> (see below) is
430 specified, the connection is made to the local host
431 instead. This works similar to
<command>login
</command> but
432 immediately invokes a user process. This command runs the
433 specified executable with the specified arguments, or
434 <filename>/bin/sh
</filename> if none is specified. By default,
435 opens a
<literal>root
</literal> shell, but by using
436 <option>--uid=
</option>, or by prefixing the machine name with
437 a username and an
<literal>@
</literal> character, a different
438 user may be selected. Use
<option>--setenv=
</option> to set
439 environment variables for the executed process.
</para>
441 <para>Note that
<command>machinectl shell
</command> does not propagate the exit code/status of the invoked
442 shell process. Use
<command>systemd-run
</command> instead if that information is required (see below).
</para>
444 <para>When using the
<command>shell
</command> command without
445 arguments, (thus invoking the executed shell or command on the
446 local host), it is in many ways similar to a
<citerefentry
447 project='die-net'
><refentrytitle>su
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
448 session, but, unlike
<command>su
</command>, completely isolates
449 the new session from the originating session, so that it
450 shares no process or session properties, and is in a clean and
451 well-defined state. It will be tracked in a new utmp, login,
452 audit, security and keyring session, and will not inherit any
453 environment variables or resource limits, among other
456 <para>Note that
<citerefentry><refentrytitle>systemd-run
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
457 with its
<option>--machine=
</option> switch may be used in place of the
<command>machinectl shell
</command>
458 command, and allows non-interactive operation, more detailed and low-level configuration of the invoked unit,
459 as well as access to runtime and exit code/status information of the invoked shell process. In particular, use
460 <command>systemd-run
</command>'s
<option>--wait
</option> switch to propagate exit status information of the
461 invoked process. Use
<command>systemd-run
</command>'s
<option>--pty
</option> switch for acquiring an
462 interactive shell, similar to
<command>machinectl shell
</command>. In general,
<command>systemd-run
</command>
463 is preferable for scripting purposes. However, note that
<command>systemd-run
</command> might require higher
464 privileges than
<command>machinectl shell
</command>.
</para></listitem>
468 <term><command>enable
</command> <replaceable>NAME
</replaceable>…
</term>
469 <term><command>disable
</command> <replaceable>NAME
</replaceable>…
</term>
471 <listitem><para>Enable or disable a container as a system
472 service to start at system boot, using
473 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
474 This enables or disables
475 <filename>systemd-nspawn@.service
</filename>, instantiated for
476 the specified machine name, similar to the effect of
477 <command>systemctl enable
</command> or
<command>systemctl
478 disable
</command> on the service name.
</para></listitem>
482 <term><command>poweroff
</command> <replaceable>NAME
</replaceable>…
</term>
484 <listitem><para>Power off one or more containers. This will
485 trigger a reboot by sending SIGRTMIN+
4 to the container's init
486 process, which causes systemd-compatible init systems to shut
487 down cleanly. Use
<command>stop
</command> as alias for
<command>poweroff
</command>.
488 This operation does not work on containers that do not run a
489 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>-compatible
490 init system, such as sysvinit. Use
491 <command>terminate
</command> (see below) to immediately
492 terminate a container or VM, without cleanly shutting it
493 down.
</para></listitem>
497 <term><command>reboot
</command> <replaceable>NAME
</replaceable>…
</term>
499 <listitem><para>Reboot one or more containers. This will
500 trigger a reboot by sending SIGINT to the container's init
501 process, which is roughly equivalent to pressing Ctrl+Alt+Del
502 on a non-containerized system, and is compatible with
503 containers running any system manager.
</para></listitem>
507 <term><command>terminate
</command> <replaceable>NAME
</replaceable>…
</term>
509 <listitem><para>Immediately terminates a virtual machine or
510 container, without cleanly shutting it down. This kills all
511 processes of the virtual machine or container and deallocates
512 all resources attached to that instance. Use
513 <command>poweroff
</command> to issue a clean shutdown
514 request.
</para></listitem>
518 <term><command>kill
</command> <replaceable>NAME
</replaceable>…
</term>
520 <listitem><para>Send a signal to one or more processes of the
521 virtual machine or container. This means processes as seen by
522 the host, not the processes inside the virtual machine or
523 container. Use
<option>--kill-who=
</option> to select which
524 process to kill. Use
<option>--signal=
</option> to select the
525 signal to send.
</para></listitem>
529 <term><command>bind
</command> <replaceable>NAME
</replaceable> <replaceable>PATH
</replaceable> [
<replaceable>PATH
</replaceable>]
</term>
531 <listitem><para>Bind mounts a directory from the host into the specified container. The first directory
532 argument is the source directory on the host, the second directory argument is the destination directory in the
533 container. When the latter is omitted, the destination path in the container is the same as the source path on
534 the host. When combined with the
<option>--read-only
</option> switch, a ready-only bind mount is created. When
535 combined with the
<option>--mkdir
</option> switch, the destination path is first created before the mount is
536 applied. Note that this option is currently only supported for
537 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry> containers,
538 and only if user namespacing (
<option>--private-users
</option>) is not used.
</para></listitem>
542 <term><command>copy-to
</command> <replaceable>NAME
</replaceable> <replaceable>PATH
</replaceable> [
<replaceable>PATH
</replaceable>]
</term>
544 <listitem><para>Copies files or directories from the host
545 system into a running container. Takes a container name,
546 followed by the source path on the host and the destination
547 path in the container. If the destination path is omitted, the
548 same as the source path is used.
</para>
550 <para>If host and container share the same user and group namespace, file ownership by numeric user ID and
551 group ID is preserved for the copy, otherwise all files and directories in the copy will be owned by the root
552 user and group (UID/GID
0).
</para></listitem>
556 <term><command>copy-from
</command> <replaceable>NAME
</replaceable> <replaceable>PATH
</replaceable> [
<replaceable>PATH
</replaceable>]
</term>
558 <listitem><para>Copies files or directories from a container
559 into the host system. Takes a container name, followed by the
560 source path in the container the destination path on the host.
561 If the destination path is omitted, the same as the source path
564 <para>If host and container share the same user and group namespace, file ownership by numeric user ID and
565 group ID is preserved for the copy, otherwise all files and directories in the copy will be owned by the root
566 user and group (UID/GID
0).
</para></listitem>
568 </variablelist></refsect2>
570 <refsect2><title>Image Commands
</title><variablelist>
573 <term><command>list-images
</command></term>
575 <listitem><para>Show a list of locally installed container and
576 VM images. This enumerates all raw disk images and container
577 directories and subvolumes in
578 <filename>/var/lib/machines/
</filename> (and other search
579 paths, see below). Use
<command>start
</command> (see above) to
580 run a container off one of the listed images. Note that, by
581 default, containers whose name begins with a dot
582 (
<literal>.
</literal>) are not shown. To show these too,
583 specify
<option>--all
</option>. Note that a special image
584 <literal>.host
</literal> always implicitly exists and refers
585 to the image the host itself is booted from.
</para></listitem>
589 <term><command>image-status
</command> [
<replaceable>NAME
</replaceable>…]
</term>
591 <listitem><para>Show terse status information about one or
592 more container or VM images. This function is intended to
593 generate human-readable output. Use
594 <command>show-image
</command> (see below) to generate
595 computer-parsable output instead.
</para></listitem>
599 <term><command>show-image
</command> [
<replaceable>NAME
</replaceable>…]
</term>
601 <listitem><para>Show properties of one or more registered
602 virtual machine or container images, or the manager itself. If
603 no argument is specified, properties of the manager will be
604 shown. If a NAME is specified, properties of this virtual
605 machine or container image are shown. By default, empty
606 properties are suppressed. Use
<option>--all
</option> to show
607 those too. To select specific properties to show, use
608 <option>--property=
</option>. This command is intended to be
609 used whenever computer-parsable output is required. Use
610 <command>image-status
</command> if you are looking for
611 formatted human-readable output.
</para></listitem>
615 <term><command>clone
</command> <replaceable>NAME
</replaceable> <replaceable>NAME
</replaceable></term>
617 <listitem><para>Clones a container or VM image. The arguments specify the name of the image to clone and the
618 name of the newly cloned image. Note that plain directory container images are cloned into btrfs subvolume
619 images with this command, if the underlying file system supports this. Note that cloning a container or VM
620 image is optimized for file systems that support copy-on-write, and might not be efficient on others, due to
621 file system limitations.
</para>
623 <para>Note that this command leaves host name, machine ID and
624 all other settings that could identify the instance
625 unmodified. The original image and the cloned copy will hence
626 share these credentials, and it might be necessary to manually
627 change them in the copy.
</para>
629 <para>If combined with the
<option>--read-only
</option> switch a read-only cloned image is
630 created.
</para></listitem>
634 <term><command>rename
</command> <replaceable>NAME
</replaceable> <replaceable>NAME
</replaceable></term>
636 <listitem><para>Renames a container or VM image. The
637 arguments specify the name of the image to rename and the new
638 name of the image.
</para></listitem>
642 <term><command>read-only
</command> <replaceable>NAME
</replaceable> [
<replaceable>BOOL
</replaceable>]
</term>
644 <listitem><para>Marks or (unmarks) a container or VM image
645 read-only. Takes a VM or container image name, followed by a
646 boolean as arguments. If the boolean is omitted, positive is
647 implied, i.e. the image is marked read-only.
</para></listitem>
651 <term><command>remove
</command> <replaceable>NAME
</replaceable>…
</term>
653 <listitem><para>Removes one or more container or VM images.
654 The special image
<literal>.host
</literal>, which refers to
655 the host's own directory tree, may not be
656 removed.
</para></listitem>
660 <term><command>set-limit
</command> [
<replaceable>NAME
</replaceable>]
<replaceable>BYTES
</replaceable></term>
662 <listitem><para>Sets the maximum size in bytes that a specific
663 container or VM image, or all images, may grow up to on disk
664 (disk quota). Takes either one or two parameters. The first,
665 optional parameter refers to a container or VM image name. If
666 specified, the size limit of the specified image is changed. If
667 omitted, the overall size limit of the sum of all images stored
668 locally is changed. The final argument specifies the size
669 limit in bytes, possibly suffixed by the usual K, M, G, T
670 units. If the size limit shall be disabled, specify
671 <literal>-
</literal> as size.
</para>
673 <para>Note that per-container size limits are only supported
674 on btrfs file systems. Also note that, if
675 <command>set-limit
</command> is invoked without an image
676 parameter, and
<filename>/var/lib/machines
</filename> is
677 empty, and the directory is not located on btrfs, a btrfs
678 loopback file is implicitly created as
679 <filename>/var/lib/machines.raw
</filename> with the given
681 <filename>/var/lib/machines
</filename>. The size of the
682 loopback may later be readjusted with
683 <command>set-limit
</command>, as well. If such a
684 loopback-mounted
<filename>/var/lib/machines
</filename>
685 directory is used,
<command>set-limit
</command> without an image
686 name alters both the quota setting within the file system as
687 well as the loopback file and file system size
688 itself.
</para></listitem>
692 <term><command>clean
</command></term>
694 <listitem><para>Remove hidden VM or container images (or all). This command removes all hidden machine images
695 from
<filename>/var/lib/machines
</filename>, i.e. those whose name begins with a dot. Use
<command>machinectl
696 list-images --all
</command> to see a list of all machine images, including the hidden ones.
</para>
698 <para>When combined with the
<option>--all
</option> switch removes all images, not just hidden ones. This
699 command effectively empties
<filename>/var/lib/machines
</filename>.
</para>
701 <para>Note that commands such as
<command>machinectl pull-tar
</command> or
<command>machinectl
702 pull-raw
</command> usually create hidden, read-only, unmodified machine images from the downloaded image first,
703 before cloning a writable working copy of it, in order to avoid duplicate downloads in case of images that are
704 reused multiple times. Use
<command>machinectl clean
</command> to remove old, hidden images created this
705 way.
</para></listitem>
708 </variablelist></refsect2>
710 <refsect2><title>Image Transfer Commands
</title><variablelist>
713 <term><command>pull-tar
</command> <replaceable>URL
</replaceable> [
<replaceable>NAME
</replaceable>]
</term>
715 <listitem><para>Downloads a
<filename>.tar
</filename>
716 container image from the specified URL, and makes it available
717 under the specified local machine name. The URL must be of
718 type
<literal>http://
</literal> or
719 <literal>https://
</literal>, and must refer to a
720 <filename>.tar
</filename>,
<filename>.tar.gz
</filename>,
721 <filename>.tar.xz
</filename> or
<filename>.tar.bz2
</filename>
722 archive file. If the local machine name is omitted, it
723 is automatically derived from the last component of the URL,
724 with its suffix removed.
</para>
726 <para>The image is verified before it is made available, unless
727 <option>--verify=no
</option> is specified.
728 Verification is done either via an inline signed file with the name
729 of the image and the suffix
<filename>.sha256
</filename> or via
730 separate
<filename>SHA256SUMS
</filename> and
731 <filename>SHA256SUMS.gpg
</filename> files.
732 The signature files need to be made available on the same web
733 server, under the same URL as the
<filename>.tar
</filename> file.
734 With
<option>--verify=checksum
</option>, only the SHA256 checksum
735 for the file is verified, based on the
<filename>.sha256
</filename>
736 suffixed file or the
<filename>SHA256SUMS
</filename> file.
737 With
<option>--verify=signature
</option>, the sha checksum file is
738 first verified with the inline signature in the
739 <filename>.sha256
</filename> file or the detached GPG signature file
740 <filename>SHA256SUMS.gpg
</filename>.
741 The public key for this verification step needs to be available in
742 <filename>/usr/lib/systemd/import-pubring.gpg
</filename> or
743 <filename>/etc/systemd/import-pubring.gpg
</filename>.
</para>
745 <para>The container image will be downloaded and stored in a
746 read-only subvolume in
747 <filename>/var/lib/machines/
</filename> that is named after
748 the specified URL and its HTTP etag. A writable snapshot is
749 then taken from this subvolume, and named after the specified
750 local name. This behavior ensures that creating multiple
751 container instances of the same URL is efficient, as multiple
752 downloads are not necessary. In order to create only the
753 read-only image, and avoid creating its writable snapshot,
754 specify
<literal>-
</literal> as local machine name.
</para>
756 <para>Note that the read-only subvolume is prefixed with
757 <filename>.tar-
</filename>, and is thus not shown by
758 <command>list-images
</command>, unless
<option>--all
</option>
761 <para>Note that pressing C-c during execution of this command
762 will not abort the download. Use
763 <command>cancel-transfer
</command>, described
764 below.
</para></listitem>
768 <term><command>pull-raw
</command> <replaceable>URL
</replaceable> [
<replaceable>NAME
</replaceable>]
</term>
770 <listitem><para>Downloads a
<filename>.raw
</filename>
771 container or VM disk image from the specified URL, and makes
772 it available under the specified local machine name. The URL
773 must be of type
<literal>http://
</literal> or
774 <literal>https://
</literal>. The container image must either
775 be a
<filename>.qcow2
</filename> or raw disk image, optionally
776 compressed as
<filename>.gz
</filename>,
777 <filename>.xz
</filename>, or
<filename>.bz2
</filename>. If the
778 local machine name is omitted, it is automatically
779 derived from the last component of the URL, with its suffix
782 <para>Image verification is identical for raw and tar images
785 <para>If the downloaded image is in
786 <filename>.qcow2
</filename> format it is converted into a raw
787 image file before it is made available.
</para>
789 <para>Downloaded images of this type will be placed as
790 read-only
<filename>.raw
</filename> file in
791 <filename>/var/lib/machines/
</filename>. A local, writable
792 (reflinked) copy is then made under the specified local
793 machine name. To omit creation of the local, writable copy
794 pass
<literal>-
</literal> as local machine name.
</para>
796 <para>Similar to the behavior of
<command>pull-tar
</command>,
797 the read-only image is prefixed with
798 <filename>.raw-
</filename>, and thus not shown by
799 <command>list-images
</command>, unless
<option>--all
</option>
802 <para>Note that pressing C-c during execution of this command
803 will not abort the download. Use
804 <command>cancel-transfer
</command>, described
805 below.
</para></listitem>
809 <term><command>import-tar
</command> <replaceable>FILE
</replaceable> [
<replaceable>NAME
</replaceable>]
</term>
810 <term><command>import-raw
</command> <replaceable>FILE
</replaceable> [
<replaceable>NAME
</replaceable>]
</term>
811 <listitem><para>Imports a TAR or RAW container or VM image,
812 and places it under the specified name in
813 <filename>/var/lib/machines/
</filename>. When
814 <command>import-tar
</command> is used, the file specified as
815 the first argument should be a tar archive, possibly compressed
816 with xz, gzip or bzip2. It will then be unpacked into its own
817 subvolume in
<filename>/var/lib/machines
</filename>. When
818 <command>import-raw
</command> is used, the file should be a
819 qcow2 or raw disk image, possibly compressed with xz, gzip or
820 bzip2. If the second argument (the resulting image name) is
821 not specified, it is automatically derived from the file
822 name. If the filename is passed as
<literal>-
</literal>, the
823 image is read from standard input, in which case the second
824 argument is mandatory.
</para>
826 <para>Both
<command>pull-tar
</command> and
<command>pull-raw
</command>
827 will resize
<filename>/var/lib/machines.raw
</filename> and the
828 filesystem therein as necessary. Optionally, the
829 <option>--read-only
</option> switch may be used to create a
830 read-only container or VM image. No cryptographic validation
831 is done when importing the images.
</para>
833 <para>Much like image downloads, ongoing imports may be listed
834 with
<command>list-transfers
</command> and aborted with
835 <command>cancel-transfer
</command>.
</para></listitem>
839 <term><command>export-tar
</command> <replaceable>NAME
</replaceable> [
<replaceable>FILE
</replaceable>]
</term>
840 <term><command>export-raw
</command> <replaceable>NAME
</replaceable> [
<replaceable>FILE
</replaceable>]
</term>
841 <listitem><para>Exports a TAR or RAW container or VM image and
842 stores it in the specified file. The first parameter should be
843 a VM or container image name. The second parameter should be a
844 file path the TAR or RAW image is written to. If the path ends
845 in
<literal>.gz
</literal>, the file is compressed with gzip, if
846 it ends in
<literal>.xz
</literal>, with xz, and if it ends in
847 <literal>.bz2
</literal>, with bzip2. If the path ends in
848 neither, the file is left uncompressed. If the second argument
849 is missing, the image is written to standard output. The
850 compression may also be explicitly selected with the
851 <option>--format=
</option> switch. This is in particular
852 useful if the second parameter is left unspecified.
</para>
854 <para>Much like image downloads and imports, ongoing exports
855 may be listed with
<command>list-transfers
</command> and
857 <command>cancel-transfer
</command>.
</para>
859 <para>Note that, currently, only directory and subvolume images
860 may be exported as TAR images, and only raw disk images as RAW
861 images.
</para></listitem>
865 <term><command>list-transfers
</command></term>
867 <listitem><para>Shows a list of container or VM image
868 downloads, imports and exports that are currently in
869 progress.
</para></listitem>
873 <term><command>cancel-transfers
</command> <replaceable>ID
</replaceable>…
</term>
875 <listitem><para>Aborts a download, import or export of the
876 container or VM image with the specified ID. To list ongoing
877 transfers and their IDs, use
878 <command>list-transfers
</command>.
</para></listitem>
881 </variablelist></refsect2>
886 <title>Machine and Image Names
</title>
888 <para>The
<command>machinectl
</command> tool operates on machines
889 and images whose names must be chosen following strict
890 rules. Machine names must be suitable for use as host names
891 following a conservative subset of DNS and UNIX/Linux
892 semantics. Specifically, they must consist of one or more
893 non-empty label strings, separated by dots. No leading or trailing
894 dots are allowed. No sequences of multiple dots are allowed. The
895 label strings may only consist of alphanumeric characters as well
896 as the dash and underscore. The maximum length of a machine name
897 is
64 characters.
</para>
899 <para>A special machine with the name
<literal>.host
</literal>
900 refers to the running host system itself. This is useful for execution
901 operations or inspecting the host system as well. Note that
902 <command>machinectl list
</command> will not show this special
903 machine unless the
<option>--all
</option> switch is specified.
</para>
905 <para>Requirements on image names are less strict, however, they must be
906 valid UTF-
8, must be suitable as file names (hence not be the
907 single or double dot, and not include a slash), and may not
908 contain control characters. Since many operations search for an
909 image by the name of a requested machine, it is recommended to name
910 images in the same strict fashion as machines.
</para>
912 <para>A special image with the name
<literal>.host
</literal>
913 refers to the image of the running host system. It hence
914 conceptually maps to the special
<literal>.host
</literal> machine
915 name described above. Note that
<command>machinectl
916 list-images
</command> will not show this special image either, unless
917 <option>--all
</option> is specified.
</para>
921 <title>Files and Directories
</title>
923 <para>Machine images are preferably stored in
924 <filename>/var/lib/machines/
</filename>, but are also searched for
925 in
<filename>/usr/local/lib/machines/
</filename> and
926 <filename>/usr/lib/machines/
</filename>. For compatibility reasons,
927 the directory
<filename>/var/lib/container/
</filename> is
928 searched, too. Note that images stored below
929 <filename>/usr
</filename> are always considered read-only. It is
930 possible to symlink machines images from other directories into
931 <filename>/var/lib/machines/
</filename> to make them available for
932 control with
<command>machinectl
</command>.
</para>
934 <para>Note that some image operations are only supported,
935 efficient or atomic on btrfs file systems. Due to this, if the
936 <command>pull-tar
</command>,
<command>pull-raw
</command>,
937 <command>import-tar
</command>,
<command>import-raw
</command> and
938 <command>set-limit
</command> commands notice that
939 <filename>/var/lib/machines
</filename> is empty and not located on
940 btrfs, they will implicitly set up a loopback file
941 <filename>/var/lib/machines.raw
</filename> containing a btrfs file
942 system that is mounted to
943 <filename>/var/lib/machines
</filename>. The size of this loopback
944 file may be controlled dynamically with
945 <command>set-limit
</command>.
</para>
947 <para>Disk images are understood by
948 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
949 and
<command>machinectl
</command> in three formats:
</para>
952 <listitem><para>A simple directory tree, containing the files
953 and directories of the container to boot.
</para></listitem>
955 <listitem><para>Subvolumes (on btrfs file systems), which are
956 similar to the simple directories, described above. However,
957 they have additional benefits, such as efficient cloning and
958 quota reporting.
</para></listitem>
960 <listitem><para>"Raw" disk images, i.e. binary images of disks
961 with a GPT or MBR partition table. Images of this type are
962 regular files with the suffix
963 <literal>.raw
</literal>.
</para></listitem>
967 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
968 for more information on image formats, in particular its
969 <option>--directory=
</option> and
<option>--image=
</option>
974 <title>Examples
</title>
976 <title>Download an Ubuntu image and open a shell in it
</title>
978 <programlisting># machinectl pull-tar https://cloud-images.ubuntu.com/trusty/current/trusty-server-cloudimg-amd64-root.tar.gz
979 # systemd-nspawn -M trusty-server-cloudimg-amd64-root
</programlisting>
981 <para>This downloads and verifies the specified
982 <filename>.tar
</filename> image, and then uses
983 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
984 to open a shell in it.
</para>
988 <title>Download a Fedora image, set a root password in it, start
989 it as service
</title>
991 <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
992 # systemd-nspawn -M Fedora-Cloud-Base-
23-
20151030
995 # machinectl start Fedora-Cloud-Base-
23-
20151030
996 # machinectl login Fedora-Cloud-Base-
23-
20151030</programlisting>
998 <para>This downloads the specified
<filename>.raw
</filename>
999 image with verification disabled. Then, a shell is opened in it
1000 and a root password is set. Afterwards the shell is left, and
1001 the machine started as system service. With the last command a
1002 login prompt into the container is requested.
</para>
1006 <title>Exports a container image as tar file
</title>
1008 <programlisting># machinectl export-tar fedora myfedora.tar.xz
</programlisting>
1010 <para>Exports the container
<literal>fedora
</literal> as an
1011 xz-compressed tar file
<filename>myfedora.tar.xz
</filename> into the
1012 current directory.
</para>
1016 <title>Create a new shell session
</title>
1018 <programlisting># machinectl shell --uid=lennart
</programlisting>
1020 <para>This creates a new shell session on the local host for
1021 the user ID
<literal>lennart
</literal>, in a
<citerefentry
1022 project='die-net'
><refentrytitle>su
</refentrytitle><manvolnum>1</manvolnum></citerefentry>-like
1029 <title>Exit status
</title>
1031 <para>On success,
0 is returned, a non-zero failure code
1035 <xi:include href=
"less-variables.xml" />
1038 <title>See Also
</title>
1040 <citerefentry><refentrytitle>systemd-machined.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
1041 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1042 <citerefentry><refentrytitle>systemd.special
</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1043 <citerefentry project='die-net'
><refentrytitle>tar
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1044 <citerefentry project='die-net'
><refentrytitle>xz
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1045 <citerefentry project='die-net'
><refentrytitle>gzip
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1046 <citerefentry project='die-net'
><refentrytitle>bzip2
</refentrytitle><manvolnum>1</manvolnum></citerefentry>