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 images'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>--dkr-index-url</option></term>
 269
 270         <listitem><para>Specifies the index server to use for
 271         downloading <literal>dkr</literal> images with the
 272         <command>pull-dkr</command>. Takes a
 273         <literal>http://</literal>, <literal>https://</literal>
 274         URL.</para></listitem>
 275       </varlistentry>
 276
 277       <varlistentry>
 278         <term><option>--format=</option></term>
 279
 280         <listitem><para>When used with the <option>export-tar</option>
 281         or <option>export-raw</option> commands, specifies the
 282         compression format to use for the resulting file. Takes one of
 283         <literal>uncompressed</literal>, <literal>xz</literal>,
 284         <literal>gzip</literal>, <literal>bzip2</literal>. By default,
 285         the format is determined automatically from the image file
 286         name passed.</para></listitem>
 287       </varlistentry>
 288
 289       <xi:include href="user-system-options.xml" xpointer="host" />
 290       <xi:include href="user-system-options.xml" xpointer="machine" />
 291
 292       <xi:include href="standard-options.xml" xpointer="no-pager" />
 293       <xi:include href="standard-options.xml" xpointer="no-legend" />
 294       <xi:include href="standard-options.xml" xpointer="help" />
 295       <xi:include href="standard-options.xml" xpointer="version" />
 296     </variablelist>
 297   </refsect1>
 298
 299   <refsect1>
 300     <title>Commands</title>
 301
 302     <para>The following commands are understood:</para>
 303
 304     <refsect2><title>Machine Commands</title><variablelist>
 305
 306       <varlistentry>
 307         <term><command>list</command></term>
 308
 309         <listitem><para>List currently running (online) virtual
 310         machines and containers. To enumerate machine images that can
 311         be started, use <command>list-images</command> (see
 312         below). Note that this command hides the special
 313         <literal>.host</literal> machine by default. Use the
 314         <option>--all</option> switch to show it.</para></listitem>
 315       </varlistentry>
 316
 317       <varlistentry>
 318         <term><command>status</command> <replaceable>NAME</replaceable>...</term>
 319
 320         <listitem><para>Show runtime status information about
 321         one or more virtual machines and containers, followed by the
 322         most recent log data from the journal. This function is
 323         intended to generate human-readable output. If you are looking
 324         for computer-parsable output, use <command>show</command>
 325         instead. Note that the log data shown is reported by the
 326         virtual machine or container manager, and frequently contains
 327         console output of the machine, but not necessarily journal
 328         contents of the machine itself.</para></listitem>
 329       </varlistentry>
 330
 331       <varlistentry>
 332         <term><command>show</command> [<replaceable>NAME</replaceable>...]</term>
 333
 334         <listitem><para>Show properties of one or more registered
 335         virtual machines or containers or the manager itself. If no
 336         argument is specified, properties of the manager will be
 337         shown. If an NAME is specified, properties of this virtual
 338         machine or container are shown. By default, empty properties
 339         are suppressed. Use <option>--all</option> to show those too.
 340         To select specific properties to show, use
 341         <option>--property=</option>. This command is intended to be
 342         used whenever computer-parsable output is required, and does
 343         not print the cgroup tree or journal entries. Use
 344         <command>status</command> if you are looking for formatted
 345         human-readable output.</para></listitem>
 346       </varlistentry>
 347
 348       <varlistentry>
 349         <term><command>start</command> <replaceable>NAME</replaceable>...</term>
 350
 351         <listitem><para>Start a container as a system service, using
 352         <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 353         This starts <filename>systemd-nspawn@.service</filename>,
 354         instantiated for the specified machine name, similar to the
 355         effect of <command>systemctl start</command> on the service
 356         name. <command>systemd-nspawn</command> looks for a container
 357         image by the specified name in
 358         <filename>/var/lib/machines/</filename> (and other search
 359         paths, see below) and runs it. Use
 360         <command>list-images</command> (see below) for listing
 361         available container images to start.</para>
 362
 363         <para>Note that
 364         <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 365         also interfaces with a variety of other container and VM
 366         managers, <command>systemd-nspawn</command> is just one
 367         implementation of it. Most of the commands available in
 368         <command>machinectl</command> may be used on containers or VMs
 369         controlled by other managers, not just
 370         <command>systemd-nspawn</command>. Starting VMs and container
 371         images on those managers requires manager-specific
 372         tools.</para>
 373
 374         <para>To interactively start a container on the command line
 375         with full access to the container's console, please invoke
 376         <command>systemd-nspawn</command> directly. To stop a running
 377         container use <command>machinectl poweroff</command>, see
 378         below.</para></listitem>
 379       </varlistentry>
 380
 381       <varlistentry>
 382         <term><command>login</command> [<replaceable>NAME</replaceable>]</term>
 383
 384         <listitem><para>Open an interactive terminal login session in
 385         a container or on the local host. If an argument is supplied,
 386         it refers to the container machine to connect to. If none is
 387         specified, or the container name is specified as the empty
 388         string, or the special machine name <literal>.host</literal>
 389         (see below) is specified, the connection is made to the local
 390         host instead. This will create a TTY connection to a specific
 391         container or the local host and asks for the execution of a
 392         getty on it. Note that this is only supported for containers
 393         running
 394         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 395         as init system.</para>
 396
 397         <para>This command will open a full login prompt on the
 398         container or the local host, which then asks for username and
 399         password. Use <command>shell</command> (see below) or
 400         <citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 401         with the <option>--machine=</option> switch to directly invoke
 402         a single command, either interactively or in the
 403         background.</para></listitem>
 404       </varlistentry>
 405
 406       <varlistentry>
 407         <term><command>shell</command> [[<replaceable>NAME</replaceable>@]<replaceable>NAME</replaceable> [<replaceable>PATH</replaceable> [<replaceable>ARGUMENTS</replaceable>...]]] </term>
 408
 409         <listitem><para>Open an interactive shell session in a
 410         container or on the local host. The first argument refers to
 411         the container machine to connect to. If none is specified, or
 412         the machine name is specified as the empty string, or the
 413         special machine name <literal>.host</literal> (see below) is
 414         specified, the connection is made to the local host
 415         instead. This works similar to <command>login</command> but
 416         immediately invokes a user process. This command runs the
 417         specified executable with the specified arguments, or
 418         <filename>/bin/sh</filename> if none is specified. By default,
 419         opens a <literal>root</literal> shell, but by using
 420         <option>--uid=</option>, or by prefixing the machine name with
 421         a username and an <literal>@</literal> character, a different
 422         user may be selected. Use <option>--setenv=</option> to set
 423         environment variables for the executed process.</para>
 424
 425         <para>When using the <command>shell</command> command without
 426         arguments, (thus invoking the executed shell or command on the
 427         local host), it is in many ways similar to a <citerefentry
 428         project='die-net'><refentrytitle>su</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 429         session, but, unlike <command>su</command>, completely isolates
 430         the new session from the originating session, so that it
 431         shares no process or session properties, and is in a clean and
 432         well-defined state. It will be tracked in a new utmp, login,
 433         audit, security and keyring session, and will not inherit any
 434         environment variables or resource limits, among other
 435         properties.</para>
 436
 437         <para>Note that
 438         <citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 439         may be used in place of the <command>shell</command> command,
 440         and allows more detailed, low-level configuration of the
 441         invoked unit. However, it is frequently more privileged than
 442         the <command>shell</command> command.</para></listitem>
 443       </varlistentry>
 444
 445       <varlistentry>
 446         <term><command>enable</command> <replaceable>NAME</replaceable>...</term>
 447         <term><command>disable</command> <replaceable>NAME</replaceable>...</term>
 448
 449         <listitem><para>Enable or disable a container as a system
 450         service to start at system boot, using
 451         <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 452         This enables or disables
 453         <filename>systemd-nspawn@.service</filename>, instantiated for
 454         the specified machine name, similar to the effect of
 455         <command>systemctl enable</command> or <command>systemctl
 456         disable</command> on the service name.</para></listitem>
 457       </varlistentry>
 458
 459       <varlistentry>
 460         <term><command>poweroff</command> <replaceable>NAME</replaceable>...</term>
 461
 462         <listitem><para>Power off one or more containers. This will
 463         trigger a reboot by sending SIGRTMIN+4 to the container's init
 464         process, which causes systemd-compatible init systems to shut
 465         down cleanly. This operation does not work on containers that
 466         do not run a
 467         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>-compatible
 468         init system, such as sysvinit. Use
 469         <command>terminate</command> (see below) to immediately
 470         terminate a container or VM, without cleanly shutting it
 471         down.</para></listitem>
 472       </varlistentry>
 473
 474       <varlistentry>
 475         <term><command>reboot</command> <replaceable>NAME</replaceable>...</term>
 476
 477         <listitem><para>Reboot one or more containers. This will
 478         trigger a reboot by sending SIGINT to the container's init
 479         process, which is roughly equivalent to pressing Ctrl+Alt+Del
 480         on a non-containerized system, and is compatible with
 481         containers running any system manager.</para></listitem>
 482       </varlistentry>
 483
 484       <varlistentry>
 485         <term><command>terminate</command> <replaceable>NAME</replaceable>...</term>
 486
 487         <listitem><para>Immediately terminates a virtual machine or
 488         container, without cleanly shutting it down. This kills all
 489         processes of the virtual machine or container and deallocates
 490         all resources attached to that instance. Use
 491         <command>poweroff</command> to issue a clean shutdown
 492         request.</para></listitem>
 493       </varlistentry>
 494
 495       <varlistentry>
 496         <term><command>kill</command> <replaceable>NAME</replaceable>...</term>
 497
 498         <listitem><para>Send a signal to one or more processes of the
 499         virtual machine or container. This means processes as seen by
 500         the host, not the processes inside the virtual machine or
 501         container. Use <option>--kill-who=</option> to select which
 502         process to kill. Use <option>--signal=</option> to select the
 503         signal to send.</para></listitem>
 504       </varlistentry>
 505
 506       <varlistentry>
 507         <term><command>bind</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term>
 508
 509         <listitem><para>Bind mounts a directory from the host into the
 510         specified container. The first directory argument is the
 511         source directory on the host, the second directory argument
 512         is the destination directory in the container. When the
 513         latter is omitted, the destination path in the container is
 514         the same as the source path on the host. When combined with
 515         the <option>--read-only</option> switch, a ready-only bind
 516         mount is created. When combined with the
 517         <option>--mkdir</option> switch, the destination path is first
 518         created before the mount is applied. Note that this option is
 519         currently only supported for
 520         <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 521         containers.</para></listitem>
 522       </varlistentry>
 523
 524       <varlistentry>
 525         <term><command>copy-to</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term>
 526
 527         <listitem><para>Copies files or directories from the host
 528         system into a running container. Takes a container name,
 529         followed by the source path on the host and the destination
 530         path in the container. If the destination path is omitted, the
 531         same as the source path is used.</para></listitem>
 532       </varlistentry>
 533
 534
 535       <varlistentry>
 536         <term><command>copy-from</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term>
 537
 538         <listitem><para>Copies files or directories from a container
 539         into the host system. Takes a container name, followed by the
 540         source path in the container the destination path on the host.
 541         If the destination path is omitted, the same as the source path
 542         is used.</para></listitem>
 543       </varlistentry>
 544     </variablelist></refsect2>
 545
 546     <refsect2><title>Image Commands</title><variablelist>
 547
 548       <varlistentry>
 549         <term><command>list-images</command></term>
 550
 551         <listitem><para>Show a list of locally installed container and
 552         VM images. This enumerates all raw disk images and container
 553         directories and subvolumes in
 554         <filename>/var/lib/machines/</filename> (and other search
 555         paths, see below). Use <command>start</command> (see above) to
 556         run a container off one of the listed images. Note that, by
 557         default, containers whose name begins with a dot
 558         (<literal>.</literal>) are not shown. To show these too,
 559         specify <option>--all</option>. Note that a special image
 560         <literal>.host</literal> always implicitly exists and refers
 561         to the image the host itself is booted from.</para></listitem>
 562       </varlistentry>
 563
 564       <varlistentry>
 565         <term><command>image-status</command> [<replaceable>NAME</replaceable>...]</term>
 566
 567         <listitem><para>Show terse status information about one or
 568         more container or VM images. This function is intended to
 569         generate human-readable output. Use
 570         <command>show-image</command> (see below) to generate
 571         computer-parsable output instead.</para></listitem>
 572       </varlistentry>
 573
 574       <varlistentry>
 575         <term><command>show-image</command> [<replaceable>NAME</replaceable>...]</term>
 576
 577         <listitem><para>Show properties of one or more registered
 578         virtual machine or container images, or the manager itself. If
 579         no argument is specified, properties of the manager will be
 580         shown. If an NAME is specified, properties of this virtual
 581         machine or container image are shown. By default, empty
 582         properties are suppressed. Use <option>--all</option> to show
 583         those too. To select specific properties to show, use
 584         <option>--property=</option>. This command is intended to be
 585         used whenever computer-parsable output is required. Use
 586         <command>image-status</command> if you are looking for
 587         formatted human-readable output.</para></listitem>
 588       </varlistentry>
 589
 590       <varlistentry>
 591         <term><command>clone</command> <replaceable>NAME</replaceable> <replaceable>NAME</replaceable></term>
 592
 593         <listitem><para>Clones a container or VM image. The
 594         arguments specify the name of the image to clone and the name
 595         of the newly cloned image. Note that plain directory container
 596         images are cloned into subvolume images with this command.
 597         Note that cloning a container or VM image is optimized for
 598         btrfs file systems, and might not be efficient on others, due
 599         to file system limitations.</para>
 600
 601         <para>Note that this command leaves host name, machine ID and
 602         all other settings that could identify the instance
 603         unmodified. The original image and the cloned copy will hence
 604         share these credentials, and it might be necessary to manually
 605         change them in the copy.</para></listitem>
 606       </varlistentry>
 607
 608       <varlistentry>
 609         <term><command>rename</command> <replaceable>NAME</replaceable> <replaceable>NAME</replaceable></term>
 610
 611         <listitem><para>Renames a container or VM image. The
 612         arguments specify the name of the image to rename and the new
 613         name of the image.</para></listitem>
 614       </varlistentry>
 615
 616       <varlistentry>
 617         <term><command>read-only</command> <replaceable>NAME</replaceable> [<replaceable>BOOL</replaceable>]</term>
 618
 619         <listitem><para>Marks or (unmarks) a container or VM image
 620         read-only. Takes a VM or container image name, followed by a
 621         boolean as arguments. If the boolean is omitted, positive is
 622         implied, i.e. the image is marked read-only.</para></listitem>
 623       </varlistentry>
 624
 625       <varlistentry>
 626         <term><command>remove</command> <replaceable>NAME</replaceable>...</term>
 627
 628         <listitem><para>Removes one or more container or VM images.
 629         The special image <literal>.host</literal>, which refers to
 630         the host's own directory tree, may not be
 631         removed.</para></listitem>
 632       </varlistentry>
 633
 634       <varlistentry>
 635         <term><command>set-limit</command> [<replaceable>NAME</replaceable>] <replaceable>BYTES</replaceable></term>
 636
 637         <listitem><para>Sets the maximum size in bytes that a specific
 638         container or VM image, or all images, may grow up to on disk
 639         (disk quota). Takes either one or two parameters. The first,
 640         optional parameter refers to a container or VM image name. If
 641         specified, the size limit of the specified image is changed. If
 642         omitted, the overall size limit of the sum of all images stored
 643         locally is changed. The final argument specifies the size
 644         limit in bytes, possibly suffixed by the usual K, M, G, T
 645         units. If the size limit shall be disabled, specify
 646         <literal>-</literal> as size.</para>
 647
 648         <para>Note that per-container size limits are only supported
 649         on btrfs file systems. Also note that, if
 650         <command>set-limit</command> is invoked without an image
 651         parameter, and <filename>/var/lib/machines</filename> is
 652         empty, and the directory is not located on btrfs, a btrfs
 653         loopback file is implicitly created as
 654         <filename>/var/lib/machines.raw</filename> with the given
 655         size, and mounted to
 656         <filename>/var/lib/machines</filename>. The size of the
 657         loopback may later be readjusted with
 658         <command>set-limit</command>, as well. If such a
 659         loopback-mounted <filename>/var/lib/machines</filename>
 660         directory is used, <command>set-limit</command> without an image
 661         name alters both the quota setting within the file system as
 662         well as the loopback file and file system size
 663         itself.</para></listitem>
 664       </varlistentry>
 665
 666     </variablelist></refsect2>
 667
 668     <refsect2><title>Image Transfer Commands</title><variablelist>
 669
 670       <varlistentry>
 671         <term><command>pull-tar</command> <replaceable>URL</replaceable> [<replaceable>NAME</replaceable>]</term>
 672
 673         <listitem><para>Downloads a <filename>.tar</filename>
 674         container image from the specified URL, and makes it available
 675         under the specified local machine name. The URL must be of
 676         type <literal>http://</literal> or
 677         <literal>https://</literal>, and must refer to a
 678         <filename>.tar</filename>, <filename>.tar.gz</filename>,
 679         <filename>.tar.xz</filename> or <filename>.tar.bz2</filename>
 680         archive file. If the local machine name is omitted, it
 681         is automatically derived from the last component of the URL,
 682         with its suffix removed.</para>
 683
 684         <para>The image is verified before it is made available,
 685         unless <option>--verify=no</option> is specified. Verification
 686         is done via SHA256SUMS and SHA256SUMS.gpg files that need to
 687         be made available on the same web server, under the same URL
 688         as the <filename>.tar</filename> file, but with the last
 689         component (the filename) of the URL replaced. With
 690         <option>--verify=checksum</option>, only the SHA256 checksum
 691         for the file is verified, based on the
 692         <filename>SHA256SUMS</filename> file. With
 693         <option>--verify=signature</option>, the SHA256SUMS file is
 694         first verified with detached GPG signature file
 695         <filename>SHA256SUMS.gpg</filename>. The public key for this
 696         verification step needs to be available in
 697         <filename>/usr/lib/systemd/import-pubring.gpg</filename> or
 698         <filename>/etc/systemd/import-pubring.gpg</filename>.</para>
 699
 700         <para>The container image will be downloaded and stored in a
 701         read-only subvolume in
 702         <filename>/var/lib/machines/</filename> that is named after
 703         the specified URL and its HTTP etag. A writable snapshot is
 704         then taken from this subvolume, and named after the specified
 705         local name. This behavior ensures that creating multiple
 706         container instances of the same URL is efficient, as multiple
 707         downloads are not necessary. In order to create only the
 708         read-only image, and avoid creating its writable snapshot,
 709         specify <literal>-</literal> as local machine name.</para>
 710
 711         <para>Note that the read-only subvolume is prefixed with
 712         <filename>.tar-</filename>, and is thus not shown by
 713         <command>list-images</command>, unless <option>--all</option>
 714         is passed.</para>
 715
 716         <para>Note that pressing C-c during execution of this command
 717         will not abort the download. Use
 718         <command>cancel-transfer</command>, described
 719         below.</para></listitem>
 720       </varlistentry>
 721
 722       <varlistentry>
 723         <term><command>pull-raw</command> <replaceable>URL</replaceable> [<replaceable>NAME</replaceable>]</term>
 724
 725         <listitem><para>Downloads a <filename>.raw</filename>
 726         container or VM disk image from the specified URL, and makes
 727         it available under the specified local machine name. The URL
 728         must be of type <literal>http://</literal> or
 729         <literal>https://</literal>. The container image must either
 730         be a <filename>.qcow2</filename> or raw disk image, optionally
 731         compressed as <filename>.gz</filename>,
 732         <filename>.xz</filename>, or <filename>.bz2</filename>. If the
 733         local machine name is omitted, it is automatically
 734         derived from the last component of the URL, with its suffix
 735         removed.</para>
 736
 737         <para>Image verification is identical for raw and tar images
 738         (see above).</para>
 739
 740         <para>If the downloaded image is in
 741         <filename>.qcow2</filename> format it is converted into a raw
 742         image file before it is made available.</para>
 743
 744         <para>Downloaded images of this type will be placed as
 745         read-only <filename>.raw</filename> file in
 746         <filename>/var/lib/machines/</filename>. A local, writable
 747         (reflinked) copy is then made under the specified local
 748         machine name. To omit creation of the local, writable copy
 749         pass <literal>-</literal> as local machine name.</para>
 750
 751         <para>Similar to the behavior of <command>pull-tar</command>,
 752         the read-only image is prefixed with
 753         <filename>.raw-</filename>, and thus not shown by
 754         <command>list-images</command>, unless <option>--all</option>
 755         is passed.</para>
 756
 757         <para>Note that pressing C-c during execution of this command
 758         will not abort the download. Use
 759         <command>cancel-transfer</command>, described
 760         below.</para></listitem>
 761       </varlistentry>
 762
 763       <varlistentry>
 764         <term><command>pull-dkr</command> <replaceable>REMOTE</replaceable> [<replaceable>NAME</replaceable>]</term>
 765
 766         <listitem><para>Downloads a <literal>dkr</literal> container
 767         image and makes it available locally. The remote name refers
 768         to a <literal>dkr</literal> container name. If omitted, the
 769         local machine name is derived from the <literal>dkr</literal>
 770         container name.</para>
 771
 772         <para>Image verification is not available for
 773         <literal>dkr</literal> containers, and thus
 774         <option>--verify=no</option> must always be specified with
 775         this command.</para>
 776
 777         <para>This command downloads all (missing) layers for the
 778         specified container and places them in read-only subvolumes in
 779         <filename>/var/lib/machines/</filename>. A writable snapshot
 780         of the newest layer is then created under the specified local
 781         machine name. To omit creation of this writable snapshot, pass
 782         <literal>-</literal> as local machine name.</para>
 783
 784         <para>The read-only layer subvolumes are prefixed with
 785         <filename>.dkr-</filename>, and thus not shown by
 786         <command>list-images</command>, unless <option>--all</option>
 787         is passed.</para>
 788
 789         <para>To specify the <literal>dkr</literal> index server to
 790         use for looking up the specified container, use
 791         <option>--dkr-index-url=</option>.</para>
 792
 793         <para>Note that pressing C-c during execution of this command
 794         will not abort the download. Use
 795         <command>cancel-transfer</command>, described
 796         below.</para></listitem>
 797       </varlistentry>
 798
 799       <varlistentry>
 800         <term><command>import-tar</command> <replaceable>FILE</replaceable> [<replaceable>NAME</replaceable>]</term>
 801         <term><command>import-raw</command> <replaceable>FILE</replaceable> [<replaceable>NAME</replaceable>]</term>
 802         <listitem><para>Imports a TAR or RAW container or VM image,
 803         and places it under the specified name in
 804         <filename>/var/lib/machines/</filename>. When
 805         <command>import-tar</command> is used, the file specified as
 806         the first argument should be a tar archive, possibly compressed
 807         with xz, gzip or bzip2. It will then be unpacked into its own
 808         subvolume in <filename>/var/lib/machines</filename>. When
 809         <command>import-raw</command> is used, the file should be a
 810         qcow2 or raw disk image, possibly compressed with xz, gzip or
 811         bzip2. If the second argument (the resulting image name) is
 812         not specified, it is automatically derived from the file
 813         name. If the file name is passed as <literal>-</literal>, the
 814         image is read from standard input, in which case the second
 815         argument is mandatory.</para>
 816
 817         <para>Similar as with <command>pull-tar</command>,
 818         <command>pull-raw</command> the file system
 819         <filename>/var/lib/machines.raw</filename> is increased in
 820         size of necessary and appropriate. Optionally, the
 821         <option>--read-only</option> switch may be used to create a
 822         read-only container or VM image. No cryptographic validation
 823         is done when importing the images.</para>
 824
 825         <para>Much like image downloads, ongoing imports may be listed
 826         with <command>list-transfers</command> and aborted with
 827         <command>cancel-transfer</command>.</para></listitem>
 828       </varlistentry>
 829
 830       <varlistentry>
 831         <term><command>export-tar</command> <replaceable>NAME</replaceable> [<replaceable>FILE</replaceable>]</term>
 832         <term><command>export-raw</command> <replaceable>NAME</replaceable> [<replaceable>FILE</replaceable>]</term>
 833         <listitem><para>Exports a TAR or RAW container or VM image and
 834         stores it in the specified file. The first parameter should be
 835         a VM or container image name. The second parameter should be a
 836         file path the TAR or RAW image is written to. If the path ends
 837         in <literal>.gz</literal>, the file is compressed with gzip, if
 838         it ends in <literal>.xz</literal>, with xz, and if it ends in
 839         <literal>.bz2</literal>, with bzip2. If the path ends in
 840         neither, the file is left uncompressed. If the second argument
 841         is missing, the image is written to standard output. The
 842         compression may also be explicitly selected with the
 843         <option>--format=</option> switch. This is in particular
 844         useful if the second parameter is left unspecified.</para>
 845
 846         <para>Much like image downloads and imports, ongoing exports
 847         may be listed with <command>list-transfers</command> and
 848         aborted with
 849         <command>cancel-transfer</command>.</para>
 850
 851         <para>Note that, currently, only directory and subvolume images
 852         may be exported as TAR images, and only raw disk images as RAW
 853         images.</para></listitem>
 854       </varlistentry>
 855
 856       <varlistentry>
 857         <term><command>list-transfers</command></term>
 858
 859         <listitem><para>Shows a list of container or VM image
 860         downloads, imports and exports that are currently in
 861         progress.</para></listitem>
 862       </varlistentry>
 863
 864       <varlistentry>
 865         <term><command>cancel-transfers</command> <replaceable>ID</replaceable>...</term>
 866
 867         <listitem><para>Aborts a download, import or export of the
 868         container or VM image with the specified ID. To list ongoing
 869         transfers and their IDs, use
 870         <command>list-transfers</command>. </para></listitem>
 871       </varlistentry>
 872
 873     </variablelist></refsect2>
 874
 875   </refsect1>
 876
 877   <refsect1>
 878     <title>Machine and Image Names</title>
 879
 880     <para>The <command>machinectl</command> tool operates on machines
 881     and images whose names must be chosen following strict
 882     rules. Machine names must be suitable for use as host names
 883     following a conservative subset of DNS and UNIX/Linux
 884     semantics. Specifically, they must consist of one or more
 885     non-empty label strings, separated by dots. No leading or trailing
 886     dots are allowed. No sequences of multiple dots are allowed. The
 887     label strings may only consist of alphanumeric characters as well
 888     as the dash and underscore. The maximum length of a machine name
 889     is 64 characters.</para>
 890
 891     <para>A special machine with the name <literal>.host</literal>
 892     refers to the running host system itself. This is useful for execution
 893     operations or inspecting the host system as well. Note that
 894     <command>machinectl list</command> will not show this special
 895     machine unless the <option>--all</option> switch is specified.</para>
 896
 897     <para>Requirements on image names are less strict, however, they must be
 898     valid UTF-8, must be suitable as file names (hence not be the
 899     single or double dot, and not include a slash), and may not
 900     contain control characters. Since many operations search for an
 901     image by the name of a requested machine, it is recommended to name
 902     images in the same strict fashion as machines.</para>
 903
 904     <para>A special image with the name <literal>.host</literal>
 905     refers to the image of the running host system. It hence
 906     conceptually maps to the special <literal>.host</literal> machine
 907     name described above. Note that <command>machinectl
 908     list-images</command> will not show this special image either, unless
 909     <option>--all</option> is specified.</para>
 910   </refsect1>
 911
 912   <refsect1>
 913     <title>Files and Directories</title>
 914
 915     <para>Machine images are preferably stored in
 916     <filename>/var/lib/machines/</filename>, but are also searched for
 917     in <filename>/usr/local/lib/machines/</filename> and
 918     <filename>/usr/lib/machines/</filename>. For compatibility reasons,
 919     the directory <filename>/var/lib/container/</filename> is
 920     searched, too. Note that images stored below
 921     <filename>/usr</filename> are always considered read-only. It is
 922     possible to symlink machines images from other directories into
 923     <filename>/var/lib/machines/</filename> to make them available for
 924     control with <command>machinectl</command>.</para>
 925
 926     <para>Note that many image operations are only supported,
 927     efficient or atomic on btrfs file systems. Due to this, if the
 928     <command>pull-tar</command>, <command>pull-raw</command>,
 929     <command>pull-dkr</command>, <command>import-tar</command>,
 930     <command>import-raw</command> and <command>set-limit</command>
 931     commands notice that <filename>/var/lib/machines</filename> is
 932     empty and not located on btrfs, they will implicitly set up a
 933     loopback file <filename>/var/lib/machines.raw</filename>
 934     containing a btrfs file system that is mounted to
 935     <filename>/var/lib/machines</filename>. The size of this loopback
 936     file may be controlled dynamically with
 937     <command>set-limit</command>.</para>
 938
 939     <para>Disk images are understood by
 940     <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 941     and <command>machinectl</command> in three formats:</para>
 942
 943     <itemizedlist>
 944       <listitem><para>A simple directory tree, containing the files
 945       and directories of the container to boot.</para></listitem>
 946
 947       <listitem><para>Subvolumes (on btrfs file systems), which are
 948       similar to the simple directories, described above. However,
 949       they have additional benefits, such as efficient cloning and
 950       quota reporting.</para></listitem>
 951
 952       <listitem><para>"Raw" disk images, i.e. binary images of disks
 953       with a GPT or MBR partition table. Images of this type are
 954       regular files with the suffix
 955       <literal>.raw</literal>.</para></listitem>
 956     </itemizedlist>
 957
 958     <para>See
 959     <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 960     for more information on image formats, in particular its
 961     <option>--directory=</option> and <option>--image=</option>
 962     options.</para>
 963   </refsect1>
 964
 965   <refsect1>
 966     <title>Examples</title>
 967     <example>
 968       <title>Download an Ubuntu image and open a shell in it</title>
 969
 970       <programlisting># machinectl pull-tar https://cloud-images.ubuntu.com/trusty/current/trusty-server-cloudimg-amd64-root.tar.gz
 971 # systemd-nspawn -M trusty-server-cloudimg-amd64-root</programlisting>
 972
 973       <para>This downloads and verifies the specified
 974       <filename>.tar</filename> image, and then uses
 975       <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 976       to open a shell in it.</para>
 977     </example>
 978
 979     <example>
 980       <title>Download a Fedora image, set a root password in it, start
 981       it as service</title>
 982
 983       <programlisting># machinectl pull-raw --verify=no http://ftp.halifax.rwth-aachen.de/fedora/linux/releases/21/Cloud/Images/x86_64/Fedora-Cloud-Base-20141203-21.x86_64.raw.xz
 984 # systemd-nspawn -M Fedora-Cloud-Base-20141203-21
 985 # passwd
 986 # exit
 987 # machinectl start Fedora-Cloud-Base-20141203-21
 988 # machinectl login Fedora-Cloud-Base-20141203-21</programlisting>
 989
 990       <para>This downloads the specified <filename>.raw</filename>
 991       image with verification disabled. Then, a shell is opened in it
 992       and a root password is set. Afterwards the shell is left, and
 993       the machine started as system service. With the last command a
 994       login prompt into the container is requested.</para>
 995     </example>
 996
 997     <example>
 998       <title>Download a Fedora <literal>dkr</literal> image</title>
 999
1000       <programlisting># machinectl pull-dkr --verify=no mattdm/fedora
1001 # systemd-nspawn -M fedora</programlisting>
1002
1003       <para>Downloads a <literal>dkr</literal> image and opens a shell
1004       in it. Note that the specified download command might require an
1005       index server to be specified with the
1006       <literal>--dkr-index-url=</literal>.</para>
1007     </example>
1008
1009     <example>
1010       <title>Exports a container image as tar file</title>
1011
1012       <programlisting># machinectl export-tar fedora myfedora.tar.xz</programlisting>
1013
1014       <para>Exports the container <literal>fedora</literal> as an
1015       xz-compressed tar file <filename>myfedora.tar.xz</filename> into the
1016       current directory.</para>
1017     </example>
1018
1019     <example>
1020       <title>Create a new shell session</title>
1021
1022       <programlisting># machinectl shell --uid=lennart</programlisting>
1023
1024       <para>This creates a new shell session on the local host for
1025       the user ID <literal>lennart</literal>, in a <citerefentry
1026       project='die-net'><refentrytitle>su</refentrytitle><manvolnum>1</manvolnum></citerefentry>-like
1027       fashion.</para>
1028     </example>
1029
1030   </refsect1>
1031
1032   <refsect1>
1033     <title>Exit status</title>
1034
1035     <para>On success, 0 is returned, a non-zero failure code
1036     otherwise.</para>
1037   </refsect1>
1038
1039   <xi:include href="less-variables.xml" />
1040
1041   <refsect1>
1042     <title>See Also</title>
1043     <para>
1044       <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
1045       <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1046       <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1047       <citerefentry project='die-net'><refentrytitle>tar</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1048       <citerefentry project='die-net'><refentrytitle>xz</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1049       <citerefentry project='die-net'><refentrytitle>gzip</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1050       <citerefentry project='die-net'><refentrytitle>bzip2</refentrytitle><manvolnum>1</manvolnum></citerefentry>
1051     </para>
1052   </refsect1>
1053
1054 </refentry>