man/machinectl.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
   4 <!ENTITY % entities SYSTEM "custom-entities.ent" >
   5 %entities;
   6 ]>
   7 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   8
   9 <refentry id="machinectl" conditional='ENABLE_MACHINED'
  10     xmlns:xi="http://www.w3.org/2001/XInclude">
  11
  12   <refentryinfo>
  13     <title>machinectl</title>
  14     <productname>systemd</productname>
  15   </refentryinfo>
  16
  17   <refmeta>
  18     <refentrytitle>machinectl</refentrytitle>
  19     <manvolnum>1</manvolnum>
  20   </refmeta>
  21
  22   <refnamediv>
  23     <refname>machinectl</refname>
  24     <refpurpose>Control the systemd machine manager</refpurpose>
  25   </refnamediv>
  26
  27   <refsynopsisdiv>
  28     <cmdsynopsis>
  29       <command>machinectl</command>
  30       <arg choice="opt" rep="repeat">OPTIONS</arg>
  31       <arg choice="req">COMMAND</arg>
  32       <arg choice="opt" rep="repeat">NAME</arg>
  33     </cmdsynopsis>
  34   </refsynopsisdiv>
  35
  36   <refsect1>
  37     <title>Description</title>
  38
  39     <para><command>machinectl</command> may be used to introspect and
  40     control the state of the
  41     <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
  42     virtual machine and container registration manager
  43     <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
  44
  45     <para><command>machinectl</command> may be used to execute
  46     operations on machines and images. Machines in this sense are
  47     considered running instances of:</para>
  48
  49     <itemizedlist>
  50       <listitem><para>Virtual Machines (VMs) that virtualize hardware
  51       to run full operating system (OS) instances (including their kernels)
  52       in a virtualized environment on top of the host OS.</para></listitem>
  53
  54       <listitem><para>Containers that share the hardware and
  55       OS kernel with the host OS, in order to run
  56       OS userspace instances on top the host OS.</para></listitem>
  57
  58       <listitem><para>The host system itself.</para></listitem>
  59     </itemizedlist>
  60
  61     <para>Machines are identified by names that follow the same rules
  62     as UNIX and DNS hostnames. For details, see below.</para>
  63
  64     <para>Machines are instantiated from disk or file system images that
  65     frequently — but not necessarily — carry the same name as machines running
  66     from them. Images in this sense may be:</para>
  67
  68     <itemizedlist>
  69       <listitem><para>Directory trees containing an OS, including the
  70       top-level directories <filename>/usr/</filename>,
  71       <filename>/etc/</filename>, and so on.</para></listitem>
  72
  73       <listitem><para>btrfs subvolumes containing OS trees, similar to regular directory trees.</para></listitem>
  74
  75       <listitem><para>Binary "raw" disk image files containing MBR or GPT partition tables and Linux file
  76       systems.</para></listitem>
  77
  78       <listitem><para>Similarly, block devices containing MBR or GPT partition tables and file systems.</para></listitem>
  79
  80       <listitem><para>The file system tree of the host OS itself.</para></listitem>
  81     </itemizedlist>
  82
  83     <para>Images may be downloaded, imported and exported via the
  84     <citerefentry><refentrytitle>importctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
  85     tool.</para>
  86   </refsect1>
  87
  88   <refsect1>
  89     <title>Commands</title>
  90
  91     <para>The following commands are understood:</para>
  92
  93     <refsect2><title>Machine Commands</title>
  94
  95     <variablelist>
  96       <varlistentry>
  97         <term><command>list</command></term>
  98
  99         <listitem><para>List currently running (online) virtual
 100         machines and containers. To enumerate machine images that can
 101         be started, use <command>list-images</command> (see
 102         below). Note that this command hides the special
 103         <literal>.host</literal> machine by default. Use the
 104         <option>--all</option> switch to show it.</para>
 105
 106         <xi:include href="version-info.xml" xpointer="v206"/></listitem>
 107       </varlistentry>
 108
 109       <varlistentry>
 110         <term><command>status</command> <replaceable>NAME</replaceable>…</term>
 111
 112         <listitem><para>Show runtime status information about
 113         one or more virtual machines and containers, followed by the
 114         most recent log data from the journal. This function is
 115         intended to generate human-readable output. If you are looking
 116         for computer-parsable output, use <command>show</command>
 117         instead. Note that the log data shown is reported by the
 118         virtual machine or container manager, and frequently contains
 119         console output of the machine, but not necessarily journal
 120         contents of the machine itself.</para>
 121
 122         <xi:include href="version-info.xml" xpointer="v206"/></listitem>
 123       </varlistentry>
 124
 125       <varlistentry>
 126         <term><command>show</command> [<replaceable>NAME</replaceable>…]</term>
 127
 128         <listitem><para>Show properties of one or more registered virtual machines or containers or the manager
 129         itself. If no argument is specified, properties of the manager will be shown. If a NAME is specified,
 130         properties of this virtual machine or container are shown. By default, empty properties are suppressed. Use
 131         <option>--all</option> to show those too.  To select specific properties to show, use
 132         <option>--property=</option>. This command is intended to be used whenever computer-parsable output is
 133         required, and does not print the control group tree or journal entries. Use <command>status</command> if you
 134         are looking for formatted human-readable output.</para>
 135
 136         <xi:include href="version-info.xml" xpointer="v206"/></listitem>
 137       </varlistentry>
 138
 139       <varlistentry>
 140         <term><command>start</command> <replaceable>NAME</replaceable>…</term>
 141
 142         <listitem><para>Start a container as a system service, using
 143         <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 144         This starts <filename>systemd-nspawn@.service</filename>,
 145         instantiated for the specified machine name, similar to the
 146         effect of <command>systemctl start</command> on the service
 147         name. <command>systemd-nspawn</command> looks for a container
 148         image by the specified name in
 149         <filename>/var/lib/machines/</filename> (and other search
 150         paths, see below) and runs it. Use
 151         <command>list-images</command> (see below) for listing
 152         available container images to start.</para>
 153
 154         <para>Note that
 155         <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 156         also interfaces with a variety of other container and VM
 157         managers, <command>systemd-nspawn</command> is just one
 158         implementation of it. Most of the commands available in
 159         <command>machinectl</command> may be used on containers or VMs
 160         controlled by other managers, not just
 161         <command>systemd-nspawn</command>. Starting VMs and container
 162         images on those managers requires manager-specific
 163         tools.</para>
 164
 165         <para>To interactively start a container on the command line
 166         with full access to the container's console, please invoke
 167         <command>systemd-nspawn</command> directly. To stop a running
 168         container use <command>machinectl poweroff</command>.</para>
 169
 170         <xi:include href="version-info.xml" xpointer="v219"/></listitem>
 171       </varlistentry>
 172
 173       <varlistentry>
 174         <term><command>login</command> [<replaceable>NAME</replaceable>]</term>
 175
 176         <listitem><para>Open an interactive terminal login session in
 177         a container or on the local host. If an argument is supplied,
 178         it refers to the container machine to connect to. If none is
 179         specified, or the container name is specified as the empty
 180         string, or the special machine name <literal>.host</literal>
 181         (see below) is specified, the connection is made to the local
 182         host instead. This will create a TTY connection to a specific
 183         container or the local host and asks for the execution of a
 184         getty on it. Note that this is only supported for containers
 185         running
 186         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 187         as init system.</para>
 188
 189         <para>This command will open a full login prompt on the
 190         container or the local host, which then asks for username and
 191         password. Use <command>shell</command> (see below) or
 192         <citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 193         with the <option>--machine=</option> switch to directly invoke
 194         a single command, either interactively or in the
 195         background.</para>
 196
 197         <xi:include href="version-info.xml" xpointer="v209"/></listitem>
 198       </varlistentry>
 199
 200       <varlistentry>
 201         <term><command>shell</command> [[<replaceable>NAME</replaceable>@]<replaceable>NAME</replaceable> [<replaceable>PATH</replaceable> [<replaceable>ARGUMENTS</replaceable>…]]] </term>
 202
 203         <listitem><para>Open an interactive shell session in a
 204         container or on the local host. The first argument refers to
 205         the container machine to connect to. If none is specified, or
 206         the machine name is specified as the empty string, or the
 207         special machine name <literal>.host</literal> (see below) is
 208         specified, the connection is made to the local host
 209         instead. This works similarly to <command>login</command>, but
 210         immediately invokes a user process. This command runs the
 211         specified executable with the specified arguments, or the
 212         default shell for the user if none is specified, or
 213         <filename>/bin/sh</filename> if no default shell is found. By default,
 214         <option>--uid=</option>, or by prefixing the machine name with
 215         a username and an <literal>@</literal> character, a different
 216         user may be selected. Use <option>--setenv=</option> to set
 217         environment variables for the executed process.</para>
 218
 219         <para>Note that <command>machinectl shell</command> does not propagate the exit code/status of the invoked
 220         shell process. Use <command>systemd-run</command> instead if that information is required (see below).</para>
 221
 222         <para>Using the <command>shell</command> command without arguments (thus invoking the executed shell
 223         or command on the local host), is in many ways similar to a <citerefentry
 224         project='die-net'><refentrytitle>su</refentrytitle><manvolnum>1</manvolnum></citerefentry> session,
 225         but, unlike <command>su</command>, completely isolates the new session from the originating session,
 226         so that it shares no process or session properties and is in a clean well-defined state. It will be
 227         tracked in a new utmp, login, audit, security, and keyring sessions, and will not inherit any
 228         environment variables or resource limits, among other properties.</para>
 229
 230         <para>Note that
 231         <citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry> with
 232         its <option>--machine=</option> switch may be used in place of the <command>machinectl
 233         shell</command> command, and allows non-interactive operation, more detailed and low-level
 234         configuration of the invoked unit, as well as access to runtime and exit code/status information of
 235         the invoked shell process. In particular, use <command>systemd-run</command>'s
 236         <option>--wait</option> switch to propagate exit status information of the invoked process. Use
 237         <command>systemd-run</command>'s <option>--pty</option> switch to acquire an interactive shell,
 238         similarly to <command>machinectl shell</command>. In general, <command>systemd-run</command> is
 239         preferable for scripting purposes. However, note that <command>systemd-run</command> might require
 240         higher privileges than <command>machinectl shell</command>.</para>
 241
 242         <xi:include href="version-info.xml" xpointer="v225"/></listitem>
 243       </varlistentry>
 244
 245       <varlistentry>
 246         <term><command>enable</command> <replaceable>NAME</replaceable>…</term>
 247         <term><command>disable</command> <replaceable>NAME</replaceable>…</term>
 248
 249         <listitem><para>Enable or disable a container as a system service to start at system boot, using
 250         <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 251         This enables or disables <filename>systemd-nspawn@.service</filename>, instantiated for the specified
 252         machine name, similarly to the effect of <command>systemctl enable</command> or <command>systemctl
 253         disable</command> on the service name.</para>
 254
 255         <para>This command implicitly reloads the system manager configuration after completing the operation.
 256         Note that this command does not implicitly start or power off the containers that are being operated on.
 257         If this is desired, combine the command with the <option>--now</option> switch.</para>
 258
 259         <xi:include href="version-info.xml" xpointer="v219"/></listitem>
 260       </varlistentry>
 261
 262       <varlistentry>
 263         <term><command>poweroff</command> <replaceable>NAME</replaceable>…</term>
 264
 265         <listitem><para>Power off one or more containers. This will
 266         trigger a reboot by sending SIGRTMIN+4 to the container's init
 267         process, which causes systemd-compatible init systems to shut
 268         down cleanly. Use <command>stop</command> as alias for <command>poweroff</command>.
 269         This operation does not work on containers that do not run a
 270         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>-compatible
 271         init system, such as sysvinit. Use
 272         <command>terminate</command> (see below) to immediately
 273         terminate a container or VM, without cleanly shutting it
 274         down.</para>
 275
 276         <xi:include href="version-info.xml" xpointer="v212"/></listitem>
 277       </varlistentry>
 278
 279       <varlistentry>
 280         <term><command>reboot</command> <replaceable>NAME</replaceable>…</term>
 281
 282         <listitem><para>Reboot one or more containers. This will
 283         trigger a reboot by sending SIGINT to the container's init
 284         process, which is roughly equivalent to pressing Ctrl+Alt+Del
 285         on a non-containerized system, and is compatible with
 286         containers running any system manager. Use <command>restart</command> as alias
 287         for <command>reboot</command>.</para>
 288
 289         <xi:include href="version-info.xml" xpointer="v209"/></listitem>
 290       </varlistentry>
 291
 292       <varlistentry>
 293         <term><command>terminate</command> <replaceable>NAME</replaceable>…</term>
 294
 295         <listitem><para>Immediately terminates a virtual machine or
 296         container, without cleanly shutting it down. This kills all
 297         processes of the virtual machine or container and deallocates
 298         all resources attached to that instance. Use
 299         <command>poweroff</command> to issue a clean shutdown
 300         request.</para>
 301
 302         <xi:include href="version-info.xml" xpointer="v206"/></listitem>
 303       </varlistentry>
 304
 305       <varlistentry>
 306         <term><command>kill</command> <replaceable>NAME</replaceable>…</term>
 307
 308         <listitem><para>Send a signal to one or more processes of the
 309         virtual machine or container. This means processes as seen by
 310         the host, not the processes inside the virtual machine or
 311         container. Use <option>--kill-whom=</option> to select which
 312         process to kill. Use <option>--signal=</option> to select the
 313         signal to send.</para>
 314
 315         <xi:include href="version-info.xml" xpointer="v206"/></listitem>
 316       </varlistentry>
 317
 318       <varlistentry>
 319         <term><command>bind</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term>
 320
 321         <listitem><para>Bind mounts a file or directory from the host into the specified container. The first path
 322         argument is the source file or directory on the host, the second path argument is the destination file or
 323         directory in the container. When the latter is omitted, the destination path in the container is the same as
 324         the source path on the host. When combined with the <option>--read-only</option> switch, a ready-only bind
 325         mount is created. When combined with the <option>--mkdir</option> switch, the destination path is first created
 326         before the mount is applied. Note that this option is currently only supported for
 327         <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> containers,
 328         and only if user namespacing (<option>--private-users</option>) is not used. This command supports bind
 329         mounting directories, regular files, device nodes, <constant>AF_UNIX</constant> socket nodes, as well as
 330         FIFOs.</para>
 331
 332         <xi:include href="version-info.xml" xpointer="v219"/></listitem>
 333       </varlistentry>
 334
 335       <varlistentry>
 336         <term><command>copy-to</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>] <option>--force</option></term>
 337
 338         <listitem><para>Copies files or directories from the host
 339         system into a running container. Takes a container name,
 340         followed by the source path on the host and the destination
 341         path in the container. If the destination path is omitted, the
 342         same as the source path is used.</para>
 343
 344         <para>If host and container share the same user and group namespace, file ownership by numeric user ID and
 345         group ID is preserved for the copy, otherwise all files and directories in the copy will be owned by the root
 346         user and group (UID/GID 0).</para>
 347
 348         <xi:include href="version-info.xml" xpointer="v219"/></listitem>
 349       </varlistentry>
 350
 351       <varlistentry>
 352         <term><command>copy-from</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>] <option>--force</option></term>
 353
 354         <listitem><para>Copies files or directories from a container
 355         into the host system. Takes a container name, followed by the
 356         source path in the container and the destination path on the host.
 357         If the destination path is omitted, the same as the source path
 358         is used.</para>
 359
 360         <para>If host and container share the same user and group namespace, file ownership by numeric user ID and
 361         group ID is preserved for the copy, otherwise all files and directories in the copy will be owned by the root
 362         user and group (UID/GID 0).</para>
 363
 364         <xi:include href="version-info.xml" xpointer="v219"/></listitem>
 365       </varlistentry>
 366     </variablelist></refsect2>
 367
 368     <refsect2><title>Image Commands</title>
 369
 370     <variablelist>
 371       <varlistentry>
 372         <term><command>list-images</command></term>
 373
 374         <listitem><para>Show a list of locally installed container and
 375         VM images. This enumerates all raw disk images and container
 376         directories and subvolumes in
 377         <filename>/var/lib/machines/</filename> (and other search
 378         paths, see below). Use <command>start</command> (see above) to
 379         run a container off one of the listed images. Note that, by
 380         default, containers whose name begins with a dot
 381         (<literal>.</literal>) are not shown. To show these too,
 382         specify <option>--all</option>. Note that a special image
 383         <literal>.host</literal> always implicitly exists and refers
 384         to the image the host itself is booted from.</para>
 385
 386         <xi:include href="version-info.xml" xpointer="v219"/></listitem>
 387       </varlistentry>
 388
 389       <varlistentry>
 390         <term><command>image-status</command> [<replaceable>NAME</replaceable>…]</term>
 391
 392         <listitem><para>Show terse status information about one or
 393         more container or VM images. This function is intended to
 394         generate human-readable output. Use
 395         <command>show-image</command> (see below) to generate
 396         computer-parsable output instead.</para>
 397
 398         <xi:include href="version-info.xml" xpointer="v219"/></listitem>
 399       </varlistentry>
 400
 401       <varlistentry>
 402         <term><command>show-image</command> [<replaceable>NAME</replaceable>…]</term>
 403
 404         <listitem><para>Show properties of one or more registered
 405         virtual machine or container images, or the manager itself. If
 406         no argument is specified, properties of the manager will be
 407         shown. If a NAME is specified, properties of this virtual
 408         machine or container image are shown. By default, empty
 409         properties are suppressed. Use <option>--all</option> to show
 410         those too. To select specific properties to show, use
 411         <option>--property=</option>. This command is intended to be
 412         used whenever computer-parsable output is required. Use
 413         <command>image-status</command> if you are looking for
 414         formatted human-readable output.</para>
 415
 416         <xi:include href="version-info.xml" xpointer="v219"/></listitem>
 417       </varlistentry>
 418
 419       <varlistentry>
 420         <term><command>edit</command> <replaceable>NAME|FILE</replaceable></term>
 421
 422         <listitem><para>Edit the settings file of the specified machines. For the format of the settings
 423         file, refer to
 424         <citerefentry project='man-pages'><refentrytitle>systemd.nspawn</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
 425         If an existing settings file of the given machine can't be found, <command>edit</command>
 426         automatically create a new settings file from scratch under
 427         <filename>/etc/systemd/nspawn/</filename>.
 428         </para>
 429
 430         <xi:include href="version-info.xml" xpointer="v254"/></listitem>
 431       </varlistentry>
 432
 433       <varlistentry>
 434         <term><command>cat</command> <replaceable>NAME|FILE</replaceable></term>
 435
 436         <listitem><para>Show the settings file of the specified machines.</para>
 437
 438         <xi:include href="version-info.xml" xpointer="v254"/></listitem>
 439       </varlistentry>
 440
 441       <varlistentry>
 442         <term><command>clone</command> <replaceable>NAME</replaceable> <replaceable>NAME</replaceable></term>
 443
 444         <listitem><para>Clones a container or VM image. The arguments specify the name of the image to clone and the
 445         name of the newly cloned image. Note that plain directory container images are cloned into btrfs subvolume
 446         images with this command, if the underlying file system supports this.  Note that cloning a container or VM
 447         image is optimized for file systems that support copy-on-write, and might not be efficient on others, due to
 448         file system limitations.</para>
 449
 450         <para>Note that this command leaves hostname, machine ID and
 451         all other settings that could identify the instance
 452         unmodified. The original image and the cloned copy will hence
 453         share these credentials, and it might be necessary to manually
 454         change them in the copy.</para>
 455
 456         <para>If combined with the <option>--read-only</option> switch a read-only cloned image is
 457         created.</para>
 458
 459         <xi:include href="version-info.xml" xpointer="v219"/></listitem>
 460       </varlistentry>
 461
 462       <varlistentry>
 463         <term><command>rename</command> <replaceable>NAME</replaceable> <replaceable>NAME</replaceable></term>
 464
 465         <listitem><para>Renames a container or VM image. The
 466         arguments specify the name of the image to rename and the new
 467         name of the image.</para>
 468
 469         <xi:include href="version-info.xml" xpointer="v219"/></listitem>
 470       </varlistentry>
 471
 472       <varlistentry>
 473         <term><command>read-only</command> <replaceable>NAME</replaceable> [<replaceable>BOOL</replaceable>]</term>
 474
 475         <listitem><para>Marks or (unmarks) a container or VM image
 476         read-only. Takes a VM or container image name, followed by a
 477         boolean as arguments. If the boolean is omitted, positive is
 478         implied, i.e. the image is marked read-only.</para>
 479
 480         <xi:include href="version-info.xml" xpointer="v219"/></listitem>
 481       </varlistentry>
 482
 483       <varlistentry>
 484         <term><command>remove</command> <replaceable>NAME</replaceable>…</term>
 485
 486         <listitem><para>Removes one or more container or VM images.
 487         The special image <literal>.host</literal>, which refers to
 488         the host's own directory tree, may not be
 489         removed.</para>
 490
 491         <xi:include href="version-info.xml" xpointer="v219"/></listitem>
 492       </varlistentry>
 493
 494       <varlistentry>
 495         <term><command>set-limit</command> [<replaceable>NAME</replaceable>] <replaceable>BYTES</replaceable></term>
 496
 497         <listitem><para>Sets the maximum size in bytes that a specific
 498         container or VM image, or all images, may grow up to on disk
 499         (disk quota). Takes either one or two parameters. The first,
 500         optional parameter refers to a container or VM image name. If
 501         specified, the size limit of the specified image is changed. If
 502         omitted, the overall size limit of the sum of all images stored
 503         locally is changed. The final argument specifies the size
 504         limit in bytes, possibly suffixed by the usual K, M, G, T
 505         units. If the size limit shall be disabled, specify
 506         <literal>-</literal> as size.</para>
 507
 508         <para>Note that per-container size limits are only supported on btrfs file systems.</para>
 509
 510         <xi:include href="version-info.xml" xpointer="v220"/></listitem>
 511       </varlistentry>
 512
 513       <varlistentry>
 514         <term><command>clean</command></term>
 515
 516         <listitem><para>Remove hidden VM or container images (or all). This command removes all hidden machine images
 517         from <filename>/var/lib/machines/</filename>, i.e. those whose name begins with a dot. Use <command>machinectl
 518         list-images --all</command> to see a list of all machine images, including the hidden ones.</para>
 519
 520         <para>When combined with the <option>--all</option> switch removes all images, not just hidden ones. This
 521         command effectively empties <filename>/var/lib/machines/</filename>.</para>
 522
 523         <para>Note that commands such as <command>importctl pull-tar</command> or <command>importctl
 524         pull-raw</command> usually create hidden, read-only, unmodified machine images from the downloaded image first,
 525         before cloning a writable working copy of it, in order to avoid duplicate downloads in case of images that are
 526         reused multiple times. Use <command>machinectl clean</command> to remove old, hidden images created this
 527         way.</para>
 528
 529         <xi:include href="version-info.xml" xpointer="v230"/></listitem>
 530       </varlistentry>
 531
 532     </variablelist></refsect2>
 533   </refsect1>
 534
 535   <refsect1>
 536     <title>Options</title>
 537
 538     <para>The following options are understood:</para>
 539
 540     <variablelist>
 541       <varlistentry>
 542         <term><option>-p</option></term>
 543         <term><option>--property=</option></term>
 544
 545         <listitem><para>When showing machine or image properties,
 546         limit the output to certain properties as specified by the
 547         argument. If not specified, all set properties are shown. The
 548         argument should be a property name, such as
 549         <literal>Name</literal>. If specified more than once, all
 550         properties with the specified names are
 551         shown.</para>
 552
 553         <xi:include href="version-info.xml" xpointer="v206"/></listitem>
 554       </varlistentry>
 555
 556        <varlistentry>
 557         <term><option>--value</option></term>
 558
 559         <listitem><para>When printing properties with <command>show</command>, only print the value,
 560         and skip the property name and <literal>=</literal>.</para>
 561
 562         <xi:include href="version-info.xml" xpointer="v230"/></listitem>
 563       </varlistentry>
 564
 565       <xi:include href="timedatectl.xml" xpointer="option-P"/>
 566
 567       <varlistentry>
 568         <term><option>-a</option></term>
 569         <term><option>--all</option></term>
 570
 571         <listitem><para>When showing machine or image properties, show
 572         all properties regardless of whether they are set or
 573         not.</para>
 574
 575         <para>When listing VM or container images, do not suppress
 576         images beginning in a dot character
 577         (<literal>.</literal>).</para>
 578
 579         <para>When cleaning VM or container images, remove all images, not just hidden ones.</para>
 580
 581         <xi:include href="version-info.xml" xpointer="v206"/></listitem>
 582       </varlistentry>
 583
 584       <varlistentry>
 585         <term><option>-l</option></term>
 586         <term><option>--full</option></term>
 587
 588         <listitem><para>Do not ellipsize process tree entries or table. This implies
 589         <option>--max-addresses=full</option>.</para>
 590
 591         <xi:include href="version-info.xml" xpointer="v206"/>
 592         </listitem>
 593       </varlistentry>
 594
 595       <varlistentry>
 596         <term><option>--kill-whom=</option></term>
 597
 598         <listitem><para>When used with <command>kill</command>, choose
 599         which processes to kill. Must be one of
 600         <option>leader</option>, or <option>all</option> to select
 601         whether to kill only the leader process of the machine or all
 602         processes of the machine. If omitted, defaults to
 603         <option>all</option>.</para>
 604
 605         <xi:include href="version-info.xml" xpointer="v206"/></listitem>
 606       </varlistentry>
 607
 608       <xi:include href="standard-options.xml" xpointer="signal" />
 609
 610       <varlistentry>
 611          <term><option>--uid=</option></term>
 612
 613          <listitem><para>When used with the <command>shell</command> command, chooses the user ID to
 614          open the interactive shell session as. If the argument to the <command>shell</command>
 615          command also specifies a user name, this option is ignored. If the name is not specified
 616          in either way, <literal>root</literal> will be used by default. Note that this switch is
 617          not supported for the <command>login</command> command (see below).</para>
 618
 619          <xi:include href="version-info.xml" xpointer="v225"/></listitem>
 620       </varlistentry>
 621
 622       <varlistentry>
 623         <term><option>-E <replaceable>NAME</replaceable>[=<replaceable>VALUE</replaceable>]</option></term>
 624         <term><option>--setenv=<replaceable>NAME</replaceable>[=<replaceable>VALUE</replaceable>]</option></term>
 625
 626         <listitem><para>When used with the <command>shell</command> command, sets an environment variable for
 627         the executed shell. This option may be used more than once to set multiple variables. When
 628         <literal>=</literal> and <replaceable>VALUE</replaceable> are omitted, the value of the variable with
 629         the same name in the program environment will be used.</para>
 630
 631         <para>Note that this option is not supported for the <command>login</command> command.
 632         </para>
 633
 634         <xi:include href="version-info.xml" xpointer="v230"/></listitem>
 635       </varlistentry>
 636
 637       <varlistentry>
 638         <term><option>--mkdir</option></term>
 639
 640         <listitem><para>When used with <command>bind</command>, creates the destination file or directory before
 641         applying the bind mount. Note that even though the name of this option suggests that it is suitable only for
 642         directories, this option also creates the destination file node to mount over if the object to mount is not
 643         a directory, but a regular file, device node, socket or FIFO.</para>
 644
 645         <xi:include href="version-info.xml" xpointer="v219"/></listitem>
 646       </varlistentry>
 647
 648       <varlistentry>
 649         <term><option>--read-only</option></term>
 650
 651         <listitem><para>When used with <command>bind</command>, creates a read-only bind mount.</para>
 652
 653         <para>When used with <command>clone</command> a read-only container or VM image is created.</para>
 654
 655         <xi:include href="version-info.xml" xpointer="v219"/></listitem>
 656       </varlistentry>
 657
 658       <varlistentry>
 659         <term><option>-n</option></term>
 660         <term><option>--lines=</option></term>
 661
 662         <listitem><para>When used with <command>status</command>,
 663         controls the number of journal lines to show, counting from
 664         the most recent ones. Takes a positive integer argument.
 665         Defaults to 10.</para>
 666
 667         <xi:include href="version-info.xml" xpointer="v219"/>
 668         </listitem>
 669       </varlistentry>
 670
 671       <varlistentry>
 672         <term><option>-o</option></term>
 673         <term><option>--output=</option></term>
 674
 675         <listitem><para>When used with <command>status</command>,
 676         controls the formatting of the journal entries that are shown.
 677         For the available choices, see
 678         <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 679         Defaults to <literal>short</literal>.</para>
 680
 681         <xi:include href="version-info.xml" xpointer="v219"/></listitem>
 682       </varlistentry>
 683
 684       <varlistentry>
 685         <term><option>--runner=</option><option>nspawn</option>|<option>vmspawn</option></term>
 686
 687         <listitem><para>When operating on machines choose whether to use
 688         <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 689         or
 690         <citerefentry><refentrytitle>systemd-vmspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 691         By default
 692         <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 693         is used.
 694         </para>
 695
 696         <xi:include href="version-info.xml" xpointer="v256"/></listitem>
 697       </varlistentry>
 698
 699       <varlistentry>
 700         <term><option>-V</option></term>
 701
 702         <listitem><para><option>-V</option> is a shorthand for <option>--runner=vmspawn</option>.</para>
 703
 704         <xi:include href="version-info.xml" xpointer="v256"/></listitem>
 705       </varlistentry>
 706
 707       <varlistentry>
 708         <term><option>--now</option></term>
 709
 710         <listitem>
 711           <para>When used with <command>enable</command> or <command>disable</command>,
 712           the containers will also be started or powered off. The start or poweroff
 713           operation is only carried out when the respective enable or disable
 714           operation has been successful.</para>
 715
 716         <xi:include href="version-info.xml" xpointer="v253"/>
 717         </listitem>
 718       </varlistentry>
 719
 720       <varlistentry>
 721         <term><option>--force</option></term>
 722
 723         <listitem><para>Replace target file when copying files.</para>
 724
 725         <xi:include href="version-info.xml" xpointer="v219"/></listitem>
 726       </varlistentry>
 727
 728       <varlistentry>
 729         <term><option>--max-addresses=</option></term>
 730
 731         <listitem><para>When used with the <option>list-machines</option> command, limits the number of IP
 732         addresses shown for every machine. Defaults to 1. All addresses can be requested with
 733         <literal>all</literal>. If the limit is 0, the address column is not shown. Otherwise, if the machine
 734         has more addresses than shown, <literal>…</literal> follows the last address.</para>
 735
 736         <xi:include href="version-info.xml" xpointer="v232"/></listitem>
 737       </varlistentry>
 738
 739       <varlistentry>
 740         <term><option>-q</option></term>
 741         <term><option>--quiet</option></term>
 742
 743         <listitem><para>Suppresses additional informational output while running.</para>
 744
 745         <xi:include href="version-info.xml" xpointer="v236"/></listitem>
 746       </varlistentry>
 747
 748       <xi:include href="user-system-options.xml" xpointer="host" />
 749
 750       <varlistentry>
 751         <term><option>-M</option></term>
 752         <term><option>--machine=</option></term>
 753
 754         <listitem><para>Connect to
 755         <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 756         running in a local container, to perform the specified operation within
 757         the container.</para>
 758
 759         <xi:include href="version-info.xml" xpointer="v235"/></listitem>
 760       </varlistentry>
 761
 762       <xi:include href="standard-options.xml" xpointer="no-pager" />
 763       <xi:include href="standard-options.xml" xpointer="no-legend" />
 764       <xi:include href="standard-options.xml" xpointer="no-ask-password" />
 765       <xi:include href="standard-options.xml" xpointer="help" />
 766       <xi:include href="standard-options.xml" xpointer="version" />
 767     </variablelist>
 768   </refsect1>
 769
 770   <refsect1>
 771     <title>Machine and Image Names</title>
 772
 773     <para>The <command>machinectl</command> tool operates on machines
 774     and images whose names must be chosen following strict
 775     rules. Machine names must be suitable for use as hostnames
 776     following a conservative subset of DNS and UNIX/Linux
 777     semantics. Specifically, they must consist of one or more
 778     non-empty label strings, separated by dots. No leading or trailing
 779     dots are allowed. No sequences of multiple dots are allowed. The
 780     label strings may only consist of alphanumeric characters as well
 781     as the dash and underscore. The maximum length of a machine name
 782     is 64 characters.</para>
 783
 784     <para>A special machine with the name <literal>.host</literal>
 785     refers to the running host system itself. This is useful for execution
 786     operations or inspecting the host system as well. Note that
 787     <command>machinectl list</command> will not show this special
 788     machine unless the <option>--all</option> switch is specified.</para>
 789
 790     <para>Requirements on image names are less strict, however, they must be
 791     valid UTF-8, must be suitable as file names (hence not be the
 792     single or double dot, and not include a slash), and may not
 793     contain control characters. Since many operations search for an
 794     image by the name of a requested machine, it is recommended to name
 795     images in the same strict fashion as machines.</para>
 796
 797     <para>A special image with the name <literal>.host</literal>
 798     refers to the image of the running host system. It hence
 799     conceptually maps to the special <literal>.host</literal> machine
 800     name described above. Note that <command>machinectl
 801     list-images</command> will not show this special image either, unless
 802     <option>--all</option> is specified.</para>
 803   </refsect1>
 804
 805   <refsect1>
 806     <title>Files and Directories</title>
 807
 808     <para>Machine images are preferably stored in
 809     <filename>/var/lib/machines/</filename>, but are also searched for
 810     in <filename>/usr/local/lib/machines/</filename> and
 811     <filename>/usr/lib/machines/</filename>. For compatibility reasons,
 812     the directory <filename>/var/lib/container/</filename> is
 813     searched, too. Note that images stored below
 814     <filename>/usr/</filename> are always considered read-only. It is
 815     possible to symlink machines images from other directories into
 816     <filename>/var/lib/machines/</filename> to make them available for
 817     control with <command>machinectl</command>.</para>
 818
 819     <para>Note that some image operations are only supported, efficient or atomic on btrfs file systems.</para>
 820
 821     <para>Disk images are understood by
 822     <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 823     and <command>machinectl</command> in three formats:</para>
 824
 825     <itemizedlist>
 826       <listitem><para>A simple directory tree, containing the files
 827       and directories of the container to boot.</para></listitem>
 828
 829       <listitem><para>Subvolumes (on btrfs file systems), which are
 830       similar to the simple directories, described above. However,
 831       they have additional benefits, such as efficient cloning and
 832       quota reporting.</para></listitem>
 833
 834       <listitem><para>"Raw" disk images, i.e. binary images of disks
 835       with a GPT or MBR partition table. Images of this type are
 836       regular files with the suffix
 837       <literal>.raw</literal>.</para></listitem>
 838     </itemizedlist>
 839
 840     <para>See
 841     <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 842     for more information on image formats, in particular its
 843     <option>--directory=</option> and <option>--image=</option>
 844     options.</para>
 845   </refsect1>
 846
 847   <refsect1>
 848     <title>Examples</title>
 849
 850     <xi:include href="importctl.xml" xpointer="example-import-raw" />
 851
 852   </refsect1>
 853
 854   <refsect1>
 855     <title>Exit status</title>
 856
 857     <para>On success, 0 is returned, a non-zero failure code
 858     otherwise.</para>
 859   </refsect1>
 860
 861   <xi:include href="common-variables.xml" />
 862
 863   <refsect1>
 864     <title>See Also</title>
 865     <para><simplelist type="inline">
 866       <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 867       <member><citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
 868       <member><citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 869       <member><citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
 870       <member><citerefentry><refentrytitle>importctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 871       <member><citerefentry project='die-net'><refentrytitle>tar</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 872       <member><citerefentry project='die-net'><refentrytitle>xz</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 873       <member><citerefentry project='die-net'><refentrytitle>gzip</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 874       <member><citerefentry project='die-net'><refentrytitle>bzip2</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 875     </simplelist></para>
 876   </refsect1>
 877
 878 </refentry>