man/machinectl.xml

   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">
   4
   5 <!--
   6   This file is part of systemd.
   7
   8   Copyright 2013 Zbigniew Jędrzejewski-Szmek
   9
  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.
  14
  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.
  19
  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/>.
  22 -->
  23
  24 <refentry id="machinectl" conditional='ENABLE_MACHINED'
  25     xmlns:xi="http://www.w3.org/2001/XInclude">
  26
  27   <refentryinfo>
  28     <title>machinectl</title>
  29     <productname>systemd</productname>
  30
  31     <authorgroup>
  32       <author>
  33         <contrib>Developer</contrib>
  34         <firstname>Lennart</firstname>
  35         <surname>Poettering</surname>
  36         <email>lennart@poettering.net</email>
  37       </author>
  38     </authorgroup>
  39   </refentryinfo>
  40
  41   <refmeta>
  42     <refentrytitle>machinectl</refentrytitle>
  43     <manvolnum>1</manvolnum>
  44   </refmeta>
  45
  46   <refnamediv>
  47     <refname>machinectl</refname>
  48     <refpurpose>Control the systemd machine manager</refpurpose>
  49   </refnamediv>
  50
  51   <refsynopsisdiv>
  52     <cmdsynopsis>
  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>
  57     </cmdsynopsis>
  58   </refsynopsisdiv>
  59
  60   <refsect1>
  61     <title>Description</title>
  62
  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>
  68
  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>
  72
  73     <itemizedlist>
  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>
  77
  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>
  81
  82       <listitem><para>The host system itself</para></listitem>
  83     </itemizedlist>
  84
  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>
  90
  91     <itemizedlist>
  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>
  95
  96       <listitem><para>btrfs subvolumes containing OS trees, similar to
  97       normal directory trees.</para></listitem>
  98
  99       <listitem><para>Binary "raw" disk images containing MBR or GPT
 100       partition tables and Linux file system partitions.</para></listitem>
 101
 102       <listitem><para>The file system tree of the host OS itself.</para></listitem>
 103     </itemizedlist>
 104
 105   </refsect1>
 106
 107   <refsect1>
 108     <title>Options</title>
 109
 110     <para>The following options are understood:</para>
 111
 112     <variablelist>
 113       <varlistentry>
 114         <term><option>-p</option></term>
 115         <term><option>--property=</option></term>
 116
 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>
 124       </varlistentry>
 125
 126       <varlistentry>
 127         <term><option>-a</option></term>
 128         <term><option>--all</option></term>
 129
 130         <listitem><para>When showing machine or image properties, show
 131         all properties regardless of whether they are set or
 132         not.</para>
 133
 134         <para>When listing VM or container images, do not suppress
 135         images beginning in a dot character
 136         (<literal>.</literal>).</para></listitem>
 137       </varlistentry>
 138
 139       <varlistentry>
 140         <term><option>-l</option></term>
 141         <term><option>--full</option></term>
 142
 143         <listitem><para>Do not ellipsize process tree entries.</para>
 144         </listitem>
 145       </varlistentry>
 146
 147       <varlistentry>
 148         <term><option>--no-ask-password</option></term>
 149
 150         <listitem><para>Do not query the user for authentication for
 151         privileged operations.</para></listitem>
 152       </varlistentry>
 153
 154       <varlistentry>
 155         <term><option>--kill-who=</option></term>
 156
 157         <listitem><para>When used with <command>kill</command>, choose
 158         which processes to kill. Must be one of
 159         <option>leader</option>, or <option>all</option> to select
 160         whether to kill only the leader process of the machine or all
 161         processes of the machine. If omitted, defaults to
 162         <option>all</option>.</para></listitem>
 163       </varlistentry>
 164
 165       <varlistentry>
 166         <term><option>-s</option></term>
 167         <term><option>--signal=</option></term>
 168
 169         <listitem><para>When used with <command>kill</command>, choose
 170         which signal to send to selected processes. Must be one of the
 171         well-known signal specifiers, such as
 172         <constant>SIGTERM</constant>, <constant>SIGINT</constant> or
 173         <constant>SIGSTOP</constant>. If omitted, defaults to
 174         <constant>SIGTERM</constant>.</para></listitem>
 175       </varlistentry>
 176
 177       <varlistentry>
 178          <term><option>--uid=</option></term>
 179
 180          <listitem><para>When used with the <command>shell</command>
 181          command, chooses the user ID to open the interactive shell
 182          session as. If this switch is not specified, defaults to
 183          <literal>root</literal>. Note that this switch is not
 184          supported for the <command>login</command> command (see
 185          below).</para></listitem>
 186       </varlistentry>
 187
 188       <varlistentry>
 189          <term><option>--setenv=</option></term>
 190
 191          <listitem><para>When used with the <command>shell</command>
 192          command, sets an environment variable to pass to the executed
 193          shell. Takes a pair of environment variable name and value,
 194          separated by <literal>=</literal> as argument. This switch
 195          may be used multiple times to set multiple environment
 196          variables. Note that this switch is not supported for the
 197          <command>login</command> command (see
 198          below).</para></listitem>
 199       </varlistentry>
 200
 201       <varlistentry>
 202         <term><option>--mkdir</option></term>
 203
 204         <listitem><para>When used with <command>bind</command>, creates
 205         the destination directory before applying the bind
 206         mount.</para></listitem>
 207       </varlistentry>
 208
 209       <varlistentry>
 210         <term><option>--read-only</option></term>
 211
 212         <listitem><para>When used with <command>bind</command>, applies
 213         a read-only bind mount.</para></listitem>
 214       </varlistentry>
 215
 216
 217       <varlistentry>
 218         <term><option>-n</option></term>
 219         <term><option>--lines=</option></term>
 220
 221         <listitem><para>When used with <command>status</command>,
 222         controls the number of journal lines to show, counting from
 223         the most recent ones. Takes a positive integer argument.
 224         Defaults to 10.</para>
 225         </listitem>
 226       </varlistentry>
 227
 228       <varlistentry>
 229         <term><option>-o</option></term>
 230         <term><option>--output=</option></term>
 231
 232         <listitem><para>When used with <command>status</command>,
 233         controls the formatting of the journal entries that are shown.
 234         For the available choices, see
 235         <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 236         Defaults to <literal>short</literal>.</para></listitem>
 237       </varlistentry>
 238
 239       <varlistentry>
 240         <term><option>--verify=</option></term>
 241
 242         <listitem><para>When downloading a container or VM image,
 243         specify whether the image shall be verified before it is made
 244         available. Takes one of <literal>no</literal>,
 245         <literal>checksum</literal> and <literal>signature</literal>.
 246         If <literal>no</literal>, no verification is done. If
 247         <literal>checksum</literal> is specified, the download is
 248         checked for integrity after the transfer is complete, but no
 249         signatures are verified. If <literal>signature</literal> is
 250         specified, the checksum is verified and the image's signature
 251         is checked against a local keyring of trustable vendors. It is
 252         strongly recommended to set this option to
 253         <literal>signature</literal> if the server and protocol
 254         support this. Defaults to
 255         <literal>signature</literal>.</para></listitem>
 256       </varlistentry>
 257
 258       <varlistentry>
 259         <term><option>--force</option></term>
 260
 261         <listitem><para>When downloading a container or VM image, and
 262         a local copy by the specified local machine name already
 263         exists, delete it first and replace it by the newly downloaded
 264         image.</para></listitem>
 265       </varlistentry>
 266
 267       <varlistentry>
 268         <term><option>--format=</option></term>
 269
 270         <listitem><para>When used with the <option>export-tar</option>
 271         or <option>export-raw</option> commands, specifies the
 272         compression format to use for the resulting file. Takes one of
 273         <literal>uncompressed</literal>, <literal>xz</literal>,
 274         <literal>gzip</literal>, <literal>bzip2</literal>. By default,
 275         the format is determined automatically from the image file
 276         name passed.</para></listitem>
 277       </varlistentry>
 278
 279       <xi:include href="user-system-options.xml" xpointer="host" />
 280       <xi:include href="user-system-options.xml" xpointer="machine" />
 281
 282       <xi:include href="standard-options.xml" xpointer="no-pager" />
 283       <xi:include href="standard-options.xml" xpointer="no-legend" />
 284       <xi:include href="standard-options.xml" xpointer="help" />
 285       <xi:include href="standard-options.xml" xpointer="version" />
 286     </variablelist>
 287   </refsect1>
 288
 289   <refsect1>
 290     <title>Commands</title>
 291
 292     <para>The following commands are understood:</para>
 293
 294     <refsect2><title>Machine Commands</title><variablelist>
 295
 296       <varlistentry>
 297         <term><command>list</command></term>
 298
 299         <listitem><para>List currently running (online) virtual
 300         machines and containers. To enumerate machine images that can
 301         be started, use <command>list-images</command> (see
 302         below). Note that this command hides the special
 303         <literal>.host</literal> machine by default. Use the
 304         <option>--all</option> switch to show it.</para></listitem>
 305       </varlistentry>
 306
 307       <varlistentry>
 308         <term><command>status</command> <replaceable>NAME</replaceable>...</term>
 309
 310         <listitem><para>Show runtime status information about
 311         one or more virtual machines and containers, followed by the
 312         most recent log data from the journal. This function is
 313         intended to generate human-readable output. If you are looking
 314         for computer-parsable output, use <command>show</command>
 315         instead. Note that the log data shown is reported by the
 316         virtual machine or container manager, and frequently contains
 317         console output of the machine, but not necessarily journal
 318         contents of the machine itself.</para></listitem>
 319       </varlistentry>
 320
 321       <varlistentry>
 322         <term><command>show</command> [<replaceable>NAME</replaceable>...]</term>
 323
 324         <listitem><para>Show properties of one or more registered
 325         virtual machines or containers or the manager itself. If no
 326         argument is specified, properties of the manager will be
 327         shown. If an NAME is specified, properties of this virtual
 328         machine or container are shown. By default, empty properties
 329         are suppressed. Use <option>--all</option> to show those too.
 330         To select specific properties to show, use
 331         <option>--property=</option>. This command is intended to be
 332         used whenever computer-parsable output is required, and does
 333         not print the cgroup tree or journal entries. Use
 334         <command>status</command> if you are looking for formatted
 335         human-readable output.</para></listitem>
 336       </varlistentry>
 337
 338       <varlistentry>
 339         <term><command>start</command> <replaceable>NAME</replaceable>...</term>
 340
 341         <listitem><para>Start a container as a system service, using
 342         <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 343         This starts <filename>systemd-nspawn@.service</filename>,
 344         instantiated for the specified machine name, similar to the
 345         effect of <command>systemctl start</command> on the service
 346         name. <command>systemd-nspawn</command> looks for a container
 347         image by the specified name in
 348         <filename>/var/lib/machines/</filename> (and other search
 349         paths, see below) and runs it. Use
 350         <command>list-images</command> (see below) for listing
 351         available container images to start.</para>
 352
 353         <para>Note that
 354         <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 355         also interfaces with a variety of other container and VM
 356         managers, <command>systemd-nspawn</command> is just one
 357         implementation of it. Most of the commands available in
 358         <command>machinectl</command> may be used on containers or VMs
 359         controlled by other managers, not just
 360         <command>systemd-nspawn</command>. Starting VMs and container
 361         images on those managers requires manager-specific
 362         tools.</para>
 363
 364         <para>To interactively start a container on the command line
 365         with full access to the container's console, please invoke
 366         <command>systemd-nspawn</command> directly. To stop a running
 367         container use <command>machinectl poweroff</command>, see
 368         below.</para></listitem>
 369       </varlistentry>
 370
 371       <varlistentry>
 372         <term><command>login</command> [<replaceable>NAME</replaceable>]</term>
 373
 374         <listitem><para>Open an interactive terminal login session in
 375         a container or on the local host. If an argument is supplied,
 376         it refers to the container machine to connect to. If none is
 377         specified, or the container name is specified as the empty
 378         string, or the special machine name <literal>.host</literal>
 379         (see below) is specified, the connection is made to the local
 380         host instead. This will create a TTY connection to a specific
 381         container or the local host and asks for the execution of a
 382         getty on it. Note that this is only supported for containers
 383         running
 384         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 385         as init system.</para>
 386
 387         <para>This command will open a full login prompt on the
 388         container or the local host, which then asks for username and
 389         password. Use <command>shell</command> (see below) or
 390         <citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 391         with the <option>--machine=</option> switch to directly invoke
 392         a single command, either interactively or in the
 393         background.</para></listitem>
 394       </varlistentry>
 395
 396       <varlistentry>
 397         <term><command>shell</command> [[<replaceable>NAME</replaceable>@]<replaceable>NAME</replaceable> [<replaceable>PATH</replaceable> [<replaceable>ARGUMENTS</replaceable>...]]] </term>
 398
 399         <listitem><para>Open an interactive shell session in a
 400         container or on the local host. The first argument refers to
 401         the container machine to connect to. If none is specified, or
 402         the machine name is specified as the empty string, or the
 403         special machine name <literal>.host</literal> (see below) is
 404         specified, the connection is made to the local host
 405         instead. This works similar to <command>login</command> but
 406         immediately invokes a user process. This command runs the
 407         specified executable with the specified arguments, or
 408         <filename>/bin/sh</filename> if none is specified. By default,
 409         opens a <literal>root</literal> shell, but by using
 410         <option>--uid=</option>, or by prefixing the machine name with
 411         a username and an <literal>@</literal> character, a different
 412         user may be selected. Use <option>--setenv=</option> to set
 413         environment variables for the executed process.</para>
 414
 415         <para>When using the <command>shell</command> command without
 416         arguments, (thus invoking the executed shell or command on the
 417         local host), it is in many ways similar to a <citerefentry
 418         project='die-net'><refentrytitle>su</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 419         session, but, unlike <command>su</command>, completely isolates
 420         the new session from the originating session, so that it
 421         shares no process or session properties, and is in a clean and
 422         well-defined state. It will be tracked in a new utmp, login,
 423         audit, security and keyring session, and will not inherit any
 424         environment variables or resource limits, among other
 425         properties.</para>
 426
 427         <para>Note that
 428         <citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 429         may be used in place of the <command>shell</command> command,
 430         and allows more detailed, low-level configuration of the
 431         invoked unit. However, it is frequently more privileged than
 432         the <command>shell</command> command.</para></listitem>
 433       </varlistentry>
 434
 435       <varlistentry>
 436         <term><command>enable</command> <replaceable>NAME</replaceable>...</term>
 437         <term><command>disable</command> <replaceable>NAME</replaceable>...</term>
 438
 439         <listitem><para>Enable or disable a container as a system
 440         service to start at system boot, using
 441         <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 442         This enables or disables
 443         <filename>systemd-nspawn@.service</filename>, instantiated for
 444         the specified machine name, similar to the effect of
 445         <command>systemctl enable</command> or <command>systemctl
 446         disable</command> on the service name.</para></listitem>
 447       </varlistentry>
 448
 449       <varlistentry>
 450         <term><command>poweroff</command> <replaceable>NAME</replaceable>...</term>
 451
 452         <listitem><para>Power off one or more containers. This will
 453         trigger a reboot by sending SIGRTMIN+4 to the container's init
 454         process, which causes systemd-compatible init systems to shut
 455         down cleanly. This operation does not work on containers that
 456         do not run a
 457         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>-compatible
 458         init system, such as sysvinit. Use
 459         <command>terminate</command> (see below) to immediately
 460         terminate a container or VM, without cleanly shutting it
 461         down.</para></listitem>
 462       </varlistentry>
 463
 464       <varlistentry>
 465         <term><command>reboot</command> <replaceable>NAME</replaceable>...</term>
 466
 467         <listitem><para>Reboot one or more containers. This will
 468         trigger a reboot by sending SIGINT to the container's init
 469         process, which is roughly equivalent to pressing Ctrl+Alt+Del
 470         on a non-containerized system, and is compatible with
 471         containers running any system manager.</para></listitem>
 472       </varlistentry>
 473
 474       <varlistentry>
 475         <term><command>terminate</command> <replaceable>NAME</replaceable>...</term>
 476
 477         <listitem><para>Immediately terminates a virtual machine or
 478         container, without cleanly shutting it down. This kills all
 479         processes of the virtual machine or container and deallocates
 480         all resources attached to that instance. Use
 481         <command>poweroff</command> to issue a clean shutdown
 482         request.</para></listitem>
 483       </varlistentry>
 484
 485       <varlistentry>
 486         <term><command>kill</command> <replaceable>NAME</replaceable>...</term>
 487
 488         <listitem><para>Send a signal to one or more processes of the
 489         virtual machine or container. This means processes as seen by
 490         the host, not the processes inside the virtual machine or
 491         container. Use <option>--kill-who=</option> to select which
 492         process to kill. Use <option>--signal=</option> to select the
 493         signal to send.</para></listitem>
 494       </varlistentry>
 495
 496       <varlistentry>
 497         <term><command>bind</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term>
 498
 499         <listitem><para>Bind mounts a directory from the host into the
 500         specified container. The first directory argument is the
 501         source directory on the host, the second directory argument
 502         is the destination directory in the container. When the
 503         latter is omitted, the destination path in the container is
 504         the same as the source path on the host. When combined with
 505         the <option>--read-only</option> switch, a ready-only bind
 506         mount is created. When combined with the
 507         <option>--mkdir</option> switch, the destination path is first
 508         created before the mount is applied. Note that this option is
 509         currently only supported for
 510         <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 511         containers.</para></listitem>
 512       </varlistentry>
 513
 514       <varlistentry>
 515         <term><command>copy-to</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term>
 516
 517         <listitem><para>Copies files or directories from the host
 518         system into a running container. Takes a container name,
 519         followed by the source path on the host and the destination
 520         path in the container. If the destination path is omitted, the
 521         same as the source path is used.</para></listitem>
 522       </varlistentry>
 523
 524
 525       <varlistentry>
 526         <term><command>copy-from</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term>
 527
 528         <listitem><para>Copies files or directories from a container
 529         into the host system. Takes a container name, followed by the
 530         source path in the container the destination path on the host.
 531         If the destination path is omitted, the same as the source path
 532         is used.</para></listitem>
 533       </varlistentry>
 534     </variablelist></refsect2>
 535
 536     <refsect2><title>Image Commands</title><variablelist>
 537
 538       <varlistentry>
 539         <term><command>list-images</command></term>
 540
 541         <listitem><para>Show a list of locally installed container and
 542         VM images. This enumerates all raw disk images and container
 543         directories and subvolumes in
 544         <filename>/var/lib/machines/</filename> (and other search
 545         paths, see below). Use <command>start</command> (see above) to
 546         run a container off one of the listed images. Note that, by
 547         default, containers whose name begins with a dot
 548         (<literal>.</literal>) are not shown. To show these too,
 549         specify <option>--all</option>. Note that a special image
 550         <literal>.host</literal> always implicitly exists and refers
 551         to the image the host itself is booted from.</para></listitem>
 552       </varlistentry>
 553
 554       <varlistentry>
 555         <term><command>image-status</command> [<replaceable>NAME</replaceable>...]</term>
 556
 557         <listitem><para>Show terse status information about one or
 558         more container or VM images. This function is intended to
 559         generate human-readable output. Use
 560         <command>show-image</command> (see below) to generate
 561         computer-parsable output instead.</para></listitem>
 562       </varlistentry>
 563
 564       <varlistentry>
 565         <term><command>show-image</command> [<replaceable>NAME</replaceable>...]</term>
 566
 567         <listitem><para>Show properties of one or more registered
 568         virtual machine or container images, or the manager itself. If
 569         no argument is specified, properties of the manager will be
 570         shown. If an NAME is specified, properties of this virtual
 571         machine or container image are shown. By default, empty
 572         properties are suppressed. Use <option>--all</option> to show
 573         those too. To select specific properties to show, use
 574         <option>--property=</option>. This command is intended to be
 575         used whenever computer-parsable output is required. Use
 576         <command>image-status</command> if you are looking for
 577         formatted human-readable output.</para></listitem>
 578       </varlistentry>
 579
 580       <varlistentry>
 581         <term><command>clone</command> <replaceable>NAME</replaceable> <replaceable>NAME</replaceable></term>
 582
 583         <listitem><para>Clones a container or VM image. The
 584         arguments specify the name of the image to clone and the name
 585         of the newly cloned image. Note that plain directory container
 586         images are cloned into subvolume images with this command.
 587         Note that cloning a container or VM image is optimized for
 588         btrfs file systems, and might not be efficient on others, due
 589         to file system limitations.</para>
 590
 591         <para>Note that this command leaves host name, machine ID and
 592         all other settings that could identify the instance
 593         unmodified. The original image and the cloned copy will hence
 594         share these credentials, and it might be necessary to manually
 595         change them in the copy.</para></listitem>
 596       </varlistentry>
 597
 598       <varlistentry>
 599         <term><command>rename</command> <replaceable>NAME</replaceable> <replaceable>NAME</replaceable></term>
 600
 601         <listitem><para>Renames a container or VM image. The
 602         arguments specify the name of the image to rename and the new
 603         name of the image.</para></listitem>
 604       </varlistentry>
 605
 606       <varlistentry>
 607         <term><command>read-only</command> <replaceable>NAME</replaceable> [<replaceable>BOOL</replaceable>]</term>
 608
 609         <listitem><para>Marks or (unmarks) a container or VM image
 610         read-only. Takes a VM or container image name, followed by a
 611         boolean as arguments. If the boolean is omitted, positive is
 612         implied, i.e. the image is marked read-only.</para></listitem>
 613       </varlistentry>
 614
 615       <varlistentry>
 616         <term><command>remove</command> <replaceable>NAME</replaceable>...</term>
 617
 618         <listitem><para>Removes one or more container or VM images.
 619         The special image <literal>.host</literal>, which refers to
 620         the host's own directory tree, may not be
 621         removed.</para></listitem>
 622       </varlistentry>
 623
 624       <varlistentry>
 625         <term><command>set-limit</command> [<replaceable>NAME</replaceable>] <replaceable>BYTES</replaceable></term>
 626
 627         <listitem><para>Sets the maximum size in bytes that a specific
 628         container or VM image, or all images, may grow up to on disk
 629         (disk quota). Takes either one or two parameters. The first,
 630         optional parameter refers to a container or VM image name. If
 631         specified, the size limit of the specified image is changed. If
 632         omitted, the overall size limit of the sum of all images stored
 633         locally is changed. The final argument specifies the size
 634         limit in bytes, possibly suffixed by the usual K, M, G, T
 635         units. If the size limit shall be disabled, specify
 636         <literal>-</literal> as size.</para>
 637
 638         <para>Note that per-container size limits are only supported
 639         on btrfs file systems. Also note that, if
 640         <command>set-limit</command> is invoked without an image
 641         parameter, and <filename>/var/lib/machines</filename> is
 642         empty, and the directory is not located on btrfs, a btrfs
 643         loopback file is implicitly created as
 644         <filename>/var/lib/machines.raw</filename> with the given
 645         size, and mounted to
 646         <filename>/var/lib/machines</filename>. The size of the
 647         loopback may later be readjusted with
 648         <command>set-limit</command>, as well. If such a
 649         loopback-mounted <filename>/var/lib/machines</filename>
 650         directory is used, <command>set-limit</command> without an image
 651         name alters both the quota setting within the file system as
 652         well as the loopback file and file system size
 653         itself.</para></listitem>
 654       </varlistentry>
 655
 656     </variablelist></refsect2>
 657
 658     <refsect2><title>Image Transfer Commands</title><variablelist>
 659
 660       <varlistentry>
 661         <term><command>pull-tar</command> <replaceable>URL</replaceable> [<replaceable>NAME</replaceable>]</term>
 662
 663         <listitem><para>Downloads a <filename>.tar</filename>
 664         container image from the specified URL, and makes it available
 665         under the specified local machine name. The URL must be of
 666         type <literal>http://</literal> or
 667         <literal>https://</literal>, and must refer to a
 668         <filename>.tar</filename>, <filename>.tar.gz</filename>,
 669         <filename>.tar.xz</filename> or <filename>.tar.bz2</filename>
 670         archive file. If the local machine name is omitted, it
 671         is automatically derived from the last component of the URL,
 672         with its suffix removed.</para>
 673
 674         <para>The image is verified before it is made available,
 675         unless <option>--verify=no</option> is specified. Verification
 676         is done via SHA256SUMS and SHA256SUMS.gpg files that need to
 677         be made available on the same web server, under the same URL
 678         as the <filename>.tar</filename> file, but with the last
 679         component (the filename) of the URL replaced. With
 680         <option>--verify=checksum</option>, only the SHA256 checksum
 681         for the file is verified, based on the
 682         <filename>SHA256SUMS</filename> file. With
 683         <option>--verify=signature</option>, the SHA256SUMS file is
 684         first verified with detached GPG signature file
 685         <filename>SHA256SUMS.gpg</filename>. The public key for this
 686         verification step needs to be available in
 687         <filename>/usr/lib/systemd/import-pubring.gpg</filename> or
 688         <filename>/etc/systemd/import-pubring.gpg</filename>.</para>
 689
 690         <para>The container image will be downloaded and stored in a
 691         read-only subvolume in
 692         <filename>/var/lib/machines/</filename> that is named after
 693         the specified URL and its HTTP etag. A writable snapshot is
 694         then taken from this subvolume, and named after the specified
 695         local name. This behavior ensures that creating multiple
 696         container instances of the same URL is efficient, as multiple
 697         downloads are not necessary. In order to create only the
 698         read-only image, and avoid creating its writable snapshot,
 699         specify <literal>-</literal> as local machine name.</para>
 700
 701         <para>Note that the read-only subvolume is prefixed with
 702         <filename>.tar-</filename>, and is thus not shown by
 703         <command>list-images</command>, unless <option>--all</option>
 704         is passed.</para>
 705
 706         <para>Note that pressing C-c during execution of this command
 707         will not abort the download. Use
 708         <command>cancel-transfer</command>, described
 709         below.</para></listitem>
 710       </varlistentry>
 711
 712       <varlistentry>
 713         <term><command>pull-raw</command> <replaceable>URL</replaceable> [<replaceable>NAME</replaceable>]</term>
 714
 715         <listitem><para>Downloads a <filename>.raw</filename>
 716         container or VM disk image from the specified URL, and makes
 717         it available under the specified local machine name. The URL
 718         must be of type <literal>http://</literal> or
 719         <literal>https://</literal>. The container image must either
 720         be a <filename>.qcow2</filename> or raw disk image, optionally
 721         compressed as <filename>.gz</filename>,
 722         <filename>.xz</filename>, or <filename>.bz2</filename>. If the
 723         local machine name is omitted, it is automatically
 724         derived from the last component of the URL, with its suffix
 725         removed.</para>
 726
 727         <para>Image verification is identical for raw and tar images
 728         (see above).</para>
 729
 730         <para>If the downloaded image is in
 731         <filename>.qcow2</filename> format it is converted into a raw
 732         image file before it is made available.</para>
 733
 734         <para>Downloaded images of this type will be placed as
 735         read-only <filename>.raw</filename> file in
 736         <filename>/var/lib/machines/</filename>. A local, writable
 737         (reflinked) copy is then made under the specified local
 738         machine name. To omit creation of the local, writable copy
 739         pass <literal>-</literal> as local machine name.</para>
 740
 741         <para>Similar to the behavior of <command>pull-tar</command>,
 742         the read-only image is prefixed with
 743         <filename>.raw-</filename>, and thus not shown by
 744         <command>list-images</command>, unless <option>--all</option>
 745         is passed.</para>
 746
 747         <para>Note that pressing C-c during execution of this command
 748         will not abort the download. Use
 749         <command>cancel-transfer</command>, described
 750         below.</para></listitem>
 751       </varlistentry>
 752
 753       <varlistentry>
 754         <term><command>import-tar</command> <replaceable>FILE</replaceable> [<replaceable>NAME</replaceable>]</term>
 755         <term><command>import-raw</command> <replaceable>FILE</replaceable> [<replaceable>NAME</replaceable>]</term>
 756         <listitem><para>Imports a TAR or RAW container or VM image,
 757         and places it under the specified name in
 758         <filename>/var/lib/machines/</filename>. When
 759         <command>import-tar</command> is used, the file specified as
 760         the first argument should be a tar archive, possibly compressed
 761         with xz, gzip or bzip2. It will then be unpacked into its own
 762         subvolume in <filename>/var/lib/machines</filename>. When
 763         <command>import-raw</command> is used, the file should be a
 764         qcow2 or raw disk image, possibly compressed with xz, gzip or
 765         bzip2. If the second argument (the resulting image name) is
 766         not specified, it is automatically derived from the file
 767         name. If the file name is passed as <literal>-</literal>, the
 768         image is read from standard input, in which case the second
 769         argument is mandatory.</para>
 770
 771         <para>Both <command>pull-tar</command> and <command>pull-raw</command>
 772         will resize <filename>/var/lib/machines.raw</filename> and the
 773         filesystem therein as necessary. Optionally, the
 774         <option>--read-only</option> switch may be used to create a
 775         read-only container or VM image. No cryptographic validation
 776         is done when importing the images.</para>
 777
 778         <para>Much like image downloads, ongoing imports may be listed
 779         with <command>list-transfers</command> and aborted with
 780         <command>cancel-transfer</command>.</para></listitem>
 781       </varlistentry>
 782
 783       <varlistentry>
 784         <term><command>export-tar</command> <replaceable>NAME</replaceable> [<replaceable>FILE</replaceable>]</term>
 785         <term><command>export-raw</command> <replaceable>NAME</replaceable> [<replaceable>FILE</replaceable>]</term>
 786         <listitem><para>Exports a TAR or RAW container or VM image and
 787         stores it in the specified file. The first parameter should be
 788         a VM or container image name. The second parameter should be a
 789         file path the TAR or RAW image is written to. If the path ends
 790         in <literal>.gz</literal>, the file is compressed with gzip, if
 791         it ends in <literal>.xz</literal>, with xz, and if it ends in
 792         <literal>.bz2</literal>, with bzip2. If the path ends in
 793         neither, the file is left uncompressed. If the second argument
 794         is missing, the image is written to standard output. The
 795         compression may also be explicitly selected with the
 796         <option>--format=</option> switch. This is in particular
 797         useful if the second parameter is left unspecified.</para>
 798
 799         <para>Much like image downloads and imports, ongoing exports
 800         may be listed with <command>list-transfers</command> and
 801         aborted with
 802         <command>cancel-transfer</command>.</para>
 803
 804         <para>Note that, currently, only directory and subvolume images
 805         may be exported as TAR images, and only raw disk images as RAW
 806         images.</para></listitem>
 807       </varlistentry>
 808
 809       <varlistentry>
 810         <term><command>list-transfers</command></term>
 811
 812         <listitem><para>Shows a list of container or VM image
 813         downloads, imports and exports that are currently in
 814         progress.</para></listitem>
 815       </varlistentry>
 816
 817       <varlistentry>
 818         <term><command>cancel-transfers</command> <replaceable>ID</replaceable>...</term>
 819
 820         <listitem><para>Aborts a download, import or export of the
 821         container or VM image with the specified ID. To list ongoing
 822         transfers and their IDs, use
 823         <command>list-transfers</command>. </para></listitem>
 824       </varlistentry>
 825
 826     </variablelist></refsect2>
 827
 828   </refsect1>
 829
 830   <refsect1>
 831     <title>Machine and Image Names</title>
 832
 833     <para>The <command>machinectl</command> tool operates on machines
 834     and images whose names must be chosen following strict
 835     rules. Machine names must be suitable for use as host names
 836     following a conservative subset of DNS and UNIX/Linux
 837     semantics. Specifically, they must consist of one or more
 838     non-empty label strings, separated by dots. No leading or trailing
 839     dots are allowed. No sequences of multiple dots are allowed. The
 840     label strings may only consist of alphanumeric characters as well
 841     as the dash and underscore. The maximum length of a machine name
 842     is 64 characters.</para>
 843
 844     <para>A special machine with the name <literal>.host</literal>
 845     refers to the running host system itself. This is useful for execution
 846     operations or inspecting the host system as well. Note that
 847     <command>machinectl list</command> will not show this special
 848     machine unless the <option>--all</option> switch is specified.</para>
 849
 850     <para>Requirements on image names are less strict, however, they must be
 851     valid UTF-8, must be suitable as file names (hence not be the
 852     single or double dot, and not include a slash), and may not
 853     contain control characters. Since many operations search for an
 854     image by the name of a requested machine, it is recommended to name
 855     images in the same strict fashion as machines.</para>
 856
 857     <para>A special image with the name <literal>.host</literal>
 858     refers to the image of the running host system. It hence
 859     conceptually maps to the special <literal>.host</literal> machine
 860     name described above. Note that <command>machinectl
 861     list-images</command> will not show this special image either, unless
 862     <option>--all</option> is specified.</para>
 863   </refsect1>
 864
 865   <refsect1>
 866     <title>Files and Directories</title>
 867
 868     <para>Machine images are preferably stored in
 869     <filename>/var/lib/machines/</filename>, but are also searched for
 870     in <filename>/usr/local/lib/machines/</filename> and
 871     <filename>/usr/lib/machines/</filename>. For compatibility reasons,
 872     the directory <filename>/var/lib/container/</filename> is
 873     searched, too. Note that images stored below
 874     <filename>/usr</filename> are always considered read-only. It is
 875     possible to symlink machines images from other directories into
 876     <filename>/var/lib/machines/</filename> to make them available for
 877     control with <command>machinectl</command>.</para>
 878
 879     <para>Note that many image operations are only supported,
 880     efficient or atomic on btrfs file systems. Due to this, if the
 881     <command>pull-tar</command>, <command>pull-raw</command>,
 882     <command>import-tar</command>, <command>import-raw</command> and
 883     <command>set-limit</command> commands notice that
 884     <filename>/var/lib/machines</filename> is empty and not located on
 885     btrfs, they will implicitly set up a loopback file
 886     <filename>/var/lib/machines.raw</filename> containing a btrfs file
 887     system that is mounted to
 888     <filename>/var/lib/machines</filename>. The size of this loopback
 889     file may be controlled dynamically with
 890     <command>set-limit</command>.</para>
 891
 892     <para>Disk images are understood by
 893     <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 894     and <command>machinectl</command> in three formats:</para>
 895
 896     <itemizedlist>
 897       <listitem><para>A simple directory tree, containing the files
 898       and directories of the container to boot.</para></listitem>
 899
 900       <listitem><para>Subvolumes (on btrfs file systems), which are
 901       similar to the simple directories, described above. However,
 902       they have additional benefits, such as efficient cloning and
 903       quota reporting.</para></listitem>
 904
 905       <listitem><para>"Raw" disk images, i.e. binary images of disks
 906       with a GPT or MBR partition table. Images of this type are
 907       regular files with the suffix
 908       <literal>.raw</literal>.</para></listitem>
 909     </itemizedlist>
 910
 911     <para>See
 912     <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 913     for more information on image formats, in particular its
 914     <option>--directory=</option> and <option>--image=</option>
 915     options.</para>
 916   </refsect1>
 917
 918   <refsect1>
 919     <title>Examples</title>
 920     <example>
 921       <title>Download an Ubuntu image and open a shell in it</title>
 922
 923       <programlisting># machinectl pull-tar https://cloud-images.ubuntu.com/trusty/current/trusty-server-cloudimg-amd64-root.tar.gz
 924 # systemd-nspawn -M trusty-server-cloudimg-amd64-root</programlisting>
 925
 926       <para>This downloads and verifies the specified
 927       <filename>.tar</filename> image, and then uses
 928       <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 929       to open a shell in it.</para>
 930     </example>
 931
 932     <example>
 933       <title>Download a Fedora image, set a root password in it, start
 934       it as service</title>
 935
 936       <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
 937 # systemd-nspawn -M Fedora-Cloud-Base-23-20151030
 938 # passwd
 939 # exit
 940 # machinectl start Fedora-Cloud-Base-23-20151030
 941 # machinectl login Fedora-Cloud-Base-23-20151030</programlisting>
 942
 943       <para>This downloads the specified <filename>.raw</filename>
 944       image with verification disabled. Then, a shell is opened in it
 945       and a root password is set. Afterwards the shell is left, and
 946       the machine started as system service. With the last command a
 947       login prompt into the container is requested.</para>
 948     </example>
 949
 950     <example>
 951       <title>Exports a container image as tar file</title>
 952
 953       <programlisting># machinectl export-tar fedora myfedora.tar.xz</programlisting>
 954
 955       <para>Exports the container <literal>fedora</literal> as an
 956       xz-compressed tar file <filename>myfedora.tar.xz</filename> into the
 957       current directory.</para>
 958     </example>
 959
 960     <example>
 961       <title>Create a new shell session</title>
 962
 963       <programlisting># machinectl shell --uid=lennart</programlisting>
 964
 965       <para>This creates a new shell session on the local host for
 966       the user ID <literal>lennart</literal>, in a <citerefentry
 967       project='die-net'><refentrytitle>su</refentrytitle><manvolnum>1</manvolnum></citerefentry>-like
 968       fashion.</para>
 969     </example>
 970
 971   </refsect1>
 972
 973   <refsect1>
 974     <title>Exit status</title>
 975
 976     <para>On success, 0 is returned, a non-zero failure code
 977     otherwise.</para>
 978   </refsect1>
 979
 980   <xi:include href="less-variables.xml" />
 981
 982   <refsect1>
 983     <title>See Also</title>
 984     <para>
 985       <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 986       <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 987       <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 988       <citerefentry project='die-net'><refentrytitle>tar</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 989       <citerefentry project='die-net'><refentrytitle>xz</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 990       <citerefentry project='die-net'><refentrytitle>gzip</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 991       <citerefentry project='die-net'><refentrytitle>bzip2</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 992     </para>
 993   </refsect1>
 994
 995 </refentry>