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