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