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