man/machinectl.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   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
  64                 introspect and control the state of the
  65                 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
  66                 virtual machine and container registration manager <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
  67         </refsect1>
  68
  69         <refsect1>
  70                 <title>Options</title>
  71
  72                 <para>The following options are understood:</para>
  73
  74                 <variablelist>
  75                         <varlistentry>
  76                                 <term><option>-p</option></term>
  77                                 <term><option>--property=</option></term>
  78
  79                                 <listitem><para>When showing machine
  80                                 or image properties, limit the output
  81                                 to certain properties as specified by
  82                                 the argument. If not specified, all
  83                                 set properties are shown. The argument
  84                                 should be a property name, such as
  85                                 <literal>Name</literal>. If specified
  86                                 more than once, all properties with
  87                                 the specified names are
  88                                 shown.</para></listitem>
  89                         </varlistentry>
  90
  91                         <varlistentry>
  92                                 <term><option>-a</option></term>
  93                                 <term><option>--all</option></term>
  94
  95                                 <listitem><para>When showing machine
  96                                 or image properties, show all
  97                                 properties regardless of whether they
  98                                 are set or not.</para>
  99
 100                                 <para>When listing VM or container
 101                                 images, do not suppress images
 102                                 beginning in a dot character
 103                                 (<literal>.</literal>).</para></listitem>
 104                         </varlistentry>
 105
 106                         <varlistentry>
 107                                 <term><option>-l</option></term>
 108                                 <term><option>--full</option></term>
 109
 110                                 <listitem><para>Do not ellipsize
 111                                 process tree entries.</para>
 112                                 </listitem>
 113                         </varlistentry>
 114
 115                         <varlistentry>
 116                                 <term><option>--no-ask-password</option></term>
 117
 118                                 <listitem><para>Do not query the user
 119                                 for authentication for privileged
 120                                 operations.</para></listitem>
 121                         </varlistentry>
 122
 123                         <varlistentry>
 124                                 <term><option>--kill-who=</option></term>
 125
 126                                 <listitem><para>When used with
 127                                 <command>kill</command>,
 128                                 choose which processes to kill. Must
 129                                 be one of <option>leader</option>, or
 130                                 <option>all</option> to select whether
 131                                 to kill only the leader process of the
 132                                 machine or all processes of the
 133                                 machine. If omitted, defaults to
 134                                 <option>all</option>.</para></listitem>
 135                         </varlistentry>
 136
 137                         <varlistentry>
 138                                 <term><option>-s</option></term>
 139                                 <term><option>--signal=</option></term>
 140
 141                                 <listitem><para>When used with
 142                                 <command>kill</command>, choose
 143                                 which signal to send to selected
 144                                 processes. Must be one of the
 145                                 well-known signal specifiers, such as
 146                                 <constant>SIGTERM</constant>,
 147                                 <constant>SIGINT</constant> or
 148                                 <constant>SIGSTOP</constant>. If
 149                                 omitted, defaults to
 150                                 <constant>SIGTERM</constant>.</para></listitem>
 151                         </varlistentry>
 152
 153                         <varlistentry>
 154                                 <term><option>--mkdir</option></term>
 155
 156                                 <listitem><para>When used with
 157                                 <command>bind</command> creates the
 158                                 destination directory before applying
 159                                 the bind mount.</para></listitem>
 160                         </varlistentry>
 161
 162
 163                         <varlistentry>
 164                                 <term><option>--read-only</option></term>
 165
 166                                 <listitem><para>When used with
 167                                 <command>bind</command> applies a
 168                                 read-only bind
 169                                 mount.</para></listitem>
 170                         </varlistentry>
 171
 172
 173                         <varlistentry>
 174                                 <term><option>-n</option></term>
 175                                 <term><option>--lines=</option></term>
 176
 177                                 <listitem><para>When used with
 178                                 <command>status</command>, controls
 179                                 the number of journal lines to show,
 180                                 counting from the most recent
 181                                 ones. Takes a positive integer
 182                                 argument. Defaults to 10.</para>
 183                                 </listitem>
 184                         </varlistentry>
 185
 186                         <varlistentry>
 187                                 <term><option>-o</option></term>
 188                                 <term><option>--output=</option></term>
 189
 190                                 <listitem><para>When used with
 191                                 <command>status</command>, controls
 192                                 the formatting of the journal entries
 193                                 that are shown. For the available
 194                                 choices, see
 195                                 <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 196                                 Defaults to
 197                                 <literal>short</literal>.</para></listitem>
 198                         </varlistentry>
 199
 200                         <xi:include href="user-system-options.xml" xpointer="host" />
 201                         <xi:include href="user-system-options.xml" xpointer="machine" />
 202
 203                         <xi:include href="standard-options.xml" xpointer="no-pager" />
 204                         <xi:include href="standard-options.xml" xpointer="no-legend" />
 205                         <xi:include href="standard-options.xml" xpointer="help" />
 206                         <xi:include href="standard-options.xml" xpointer="version" />
 207                 </variablelist>
 208         </refsect1>
 209
 210         <refsect1>
 211                 <title>Commands</title>
 212
 213                 <para>The following commands are understood:</para>
 214
 215                 <refsect2><title>Machine Commands</title><variablelist>
 216
 217                         <varlistentry>
 218                                 <term><command>list</command></term>
 219
 220                                 <listitem><para>List currently running
 221                                 (online) virtual machines and
 222                                 containers. To enumerate container
 223                                 images that can be started,
 224                                 use <command>list-images</command>
 225                                 (see below).</para></listitem>
 226                         </varlistentry>
 227
 228                         <varlistentry>
 229                                 <term><command>status</command> <replaceable>NAME</replaceable>...</term>
 230
 231                                 <listitem><para>Show terse runtime
 232                                 status information about one or more
 233                                 virtual machines and containers,
 234                                 followed by the most recent log data
 235                                 from the journal. This function is
 236                                 intended to generate human-readable
 237                                 output. If you are looking for
 238                                 computer-parsable output, use
 239                                 <command>show</command> instead. Note
 240                                 that the log data shown is reported by
 241                                 the virtual machine or container
 242                                 manager, and frequently contains
 243                                 console output of the machine, but not
 244                                 necessarily journal contents of the
 245                                 machine itself.</para></listitem>
 246                         </varlistentry>
 247
 248                         <varlistentry>
 249                                 <term><command>show</command> <replaceable>NAME</replaceable>...</term>
 250
 251                                 <listitem><para>Show properties of one
 252                                 or more registered virtual machines or
 253                                 containers or the manager itself. If
 254                                 no argument is specified, properties
 255                                 of the manager will be shown. If an
 256                                 NAME is specified, properties of this
 257                                 virtual machine or container are
 258                                 shown. By default, empty properties
 259                                 are suppressed. Use
 260                                 <option>--all</option> to show those
 261                                 too. To select specific properties to
 262                                 show, use
 263                                 <option>--property=</option>. This
 264                                 command is intended to be used
 265                                 whenever computer-parsable output is
 266                                 required. Use
 267                                 <command>status</command> if you are
 268                                 looking for formatted human-readable
 269                                 output.</para></listitem>
 270                         </varlistentry>
 271
 272                         <varlistentry>
 273                                 <term><command>start</command> <replaceable>NAME</replaceable>...</term>
 274
 275                                 <listitem><para>Start a container as a
 276                                 system service, using
 277                                 <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 278                                 This starts
 279                                 <filename>systemd-nspawn@.service</filename>,
 280                                 instantiated for the specified machine
 281                                 name, similar to the effect of
 282                                 <command>systemctl start</command> on
 283                                 the service
 284                                 name. <command>systemd-nspawn</command>
 285                                 looks for a container image by the
 286                                 specified name in
 287                                 <filename>/var/lib/machines/</filename>
 288                                 (and other search paths, see below) and runs
 289                                 it. Use <command>list-images</command>
 290                                 (see below), for listing available
 291                                 container images to start.</para>
 292
 293                                 <para>Note that
 294                                 <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 295                                 also interfaces with a variety of
 296                                 other container and VM managers,
 297                                 <command>systemd-nspawn</command> is
 298                                 just one implementation of it. Most of
 299                                 the commands available in
 300                                 <command>machinectl</command> may be
 301                                 used on containers or VMs controlled
 302                                 by other managers, not just
 303                                 <command>systemd-nspawn</command>. Starting
 304                                 VMs and container images on those
 305                                 managers requires manager-specific
 306                                 tools.</para>
 307
 308                                 <para>To interactively start a
 309                                 container on the command line with
 310                                 full access to the container's
 311                                 console, please invoke
 312                                 <command>systemd-nspawn</command>
 313                                 directly. To stop a running container
 314                                 use <command>machinectl
 315                                 poweroff</command>, see
 316                                 below.</para></listitem>
 317                         </varlistentry>
 318
 319                         <varlistentry>
 320                                 <term><command>login</command> <replaceable>NAME</replaceable></term>
 321
 322                                 <listitem><para>Open an interactive terminal login
 323                                 session to a container. This will
 324                                 create a TTY connection to a specific
 325                                 container and asks for the execution of a
 326                                 getty on it. Note that this is only
 327                                 supported for containers running
 328                                 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 329                                 as init system.</para>
 330
 331                                 <para>This command will open a full
 332                                 login prompt on the container, which
 333                                 then asks for username and
 334                                 password. Use
 335                                 <citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 336                                 with the <option>--machine=</option>
 337                                 switch to invoke a single command,
 338                                 either interactively or in the
 339                                 background within a local
 340                                 container.</para></listitem>
 341                         </varlistentry>
 342
 343                         <varlistentry>
 344                                 <term><command>enable</command> <replaceable>NAME</replaceable>...</term>
 345                                 <term><command>disable</command> <replaceable>NAME</replaceable>...</term>
 346
 347                                 <listitem><para>Enable or disable a
 348                                 container as a system service to start
 349                                 at system boot, using
 350                                 <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 351                                 This enables or disables
 352                                 <filename>systemd-nspawn@.service</filename>,
 353                                 instantiated for the specified machine
 354                                 name, similar to the effect of
 355                                 <command>systemctl enable</command> or
 356                                 <command>systemctl disable</command>
 357                                 on the service name.</para></listitem>
 358                         </varlistentry>
 359
 360                         <varlistentry>
 361                                 <term><command>poweroff</command> <replaceable>NAME</replaceable>...</term>
 362
 363                                 <listitem><para>Power off one or more
 364                                 containers. This will trigger a reboot
 365                                 by sending SIGRTMIN+4 to the
 366                                 container's init process, which causes
 367                                 systemd-compatible init systems to
 368                                 shut down cleanly. This operation does
 369                                 not work on containers that do not run
 370                                 a
 371                                 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>-compatible
 372                                 init system, such as sysvinit. Use
 373                                 <command>terminate</command> (see
 374                                 below) to immediately terminate a
 375                                 container or VM, without cleanly
 376                                 shutting it down.</para></listitem>
 377                         </varlistentry>
 378
 379                         <varlistentry>
 380                                 <term><command>reboot</command> <replaceable>NAME</replaceable>...</term>
 381
 382                                 <listitem><para>Reboot one or more
 383                                 containers. This will trigger a reboot
 384                                 by sending SIGINT to the container's
 385                                 init process, which is roughly
 386                                 equivalent to pressing Ctrl+Alt+Del on
 387                                 a non-containerized system, and is
 388                                 compatible with containers running any
 389                                 system manager.</para></listitem>
 390                         </varlistentry>
 391
 392                         <varlistentry>
 393                                 <term><command>terminate</command> <replaceable>NAME</replaceable>...</term>
 394
 395                                 <listitem><para>Immediately terminates
 396                                 a virtual machine or container,
 397                                 without cleanly shutting it down. This
 398                                 kills all processes of the virtual
 399                                 machine or container and deallocates
 400                                 all resources attached to that
 401                                 instance. Use
 402                                 <command>poweroff</command> to issue a
 403                                 clean shutdown request.</para></listitem>
 404                         </varlistentry>
 405
 406                         <varlistentry>
 407                                 <term><command>kill</command> <replaceable>NAME</replaceable>...</term>
 408
 409                                 <listitem><para>Send a signal to one
 410                                 or more processes of the virtual
 411                                 machine or container. This means
 412                                 processes as seen by the host, not the
 413                                 processes inside the virtual machine
 414                                 or container.
 415                                 Use <option>--kill-who=</option> to
 416                                 select which process to kill. Use
 417                                 <option>--signal=</option> to select
 418                                 the signal to send.</para></listitem>
 419                         </varlistentry>
 420
 421                         <varlistentry>
 422                                 <term><command>bind</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term>
 423
 424                                 <listitem><para>Bind mounts a
 425                                 directory from the host into the
 426                                 specified container. The first
 427                                 directory argument is the source
 428                                 directory on the host, the second
 429                                 directory argument the source
 430                                 directory on the host. When the latter
 431                                 is omitted the destination path in the
 432                                 container is the same as the source
 433                                 path on the host. When combined with
 434                                 the <option>--read-only</option>
 435                                 switch a ready-only bind mount is
 436                                 created. When combined with the
 437                                 <option>--mkdir</option> switch the
 438                                 destination path is first created
 439                                 before the mount is applied. Note that
 440                                 this option is currently only
 441                                 supported for
 442                                 <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 443                                 containers.</para></listitem>
 444                         </varlistentry>
 445
 446                         <varlistentry>
 447                                 <term><command>copy-to</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term>
 448
 449                                 <listitem><para>Copies files or
 450                                 directories from the host system into
 451                                 a running container. Takes a container
 452                                 name, followed by the source path on
 453                                 the host and the destination path in
 454                                 the container. If the destination path
 455                                 is omitted the same as the source path
 456                                 is used.</para></listitem>
 457                         </varlistentry>
 458
 459
 460                         <varlistentry>
 461                                 <term><command>copy-from</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term>
 462
 463                                 <listitem><para>Copies files or
 464                                 directories from a container into the
 465                                 host system. Takes a container name,
 466                                 followed by the source path in the
 467                                 container the destination path on the
 468                                 host. If the destination path is
 469                                 omitted the same as the source path is
 470                                 used.</para></listitem>
 471                         </varlistentry>
 472                 </variablelist></refsect2>
 473
 474                 <refsect2><title>Image Commands</title><variablelist>
 475
 476                         <varlistentry>
 477                                 <term><command>list-images</command></term>
 478
 479                                 <listitem><para>Show a list of locally
 480                                 installed container and VM
 481                                 images. This enumerates all raw disk
 482                                 images and container directories and
 483                                 subvolumes in
 484                                 <filename>/var/lib/machines/</filename> (and other search paths, see below). Use
 485                                 <command>start</command> (see above)
 486                                 to run a container off one of the
 487                                 listed images. Note that by default
 488                                 containers whose name begins with a
 489                                 dot (<literal>.</literal>) are not
 490                                 shown. To show these too, specify
 491                                 <option>--all</option>. Note that a
 492                                 special image <literal>.host</literal>
 493                                 always implicitly exists and refers to
 494                                 the image the host itself is booted
 495                                 from.</para></listitem>
 496                         </varlistentry>
 497
 498                         <varlistentry>
 499                                 <term><command>image-status</command> <replaceable>NAME</replaceable>...</term>
 500
 501                                 <listitem><para>Show terse status
 502                                 information about one or more
 503                                 container or VM images. This function
 504                                 is intended to generate human-readable
 505                                 output. Use
 506                                 <command>show-image</command> (see
 507                                 below) to generate computer-parsable
 508                                 output instead.</para></listitem>
 509                         </varlistentry>
 510
 511                         <varlistentry>
 512                                 <term><command>show-image</command> <replaceable>NAME</replaceable>...</term>
 513
 514                                 <listitem><para>Show properties of one
 515                                 or more registered virtual machine or
 516                                 container images, or the manager
 517                                 itself. If no argument is specified,
 518                                 properties of the manager will be
 519                                 shown. If an NAME is specified,
 520                                 properties of this virtual machine or
 521                                 container image are shown. By default,
 522                                 empty properties are suppressed. Use
 523                                 <option>--all</option> to show those
 524                                 too. To select specific properties to
 525                                 show, use
 526                                 <option>--property=</option>. This
 527                                 command is intended to be used
 528                                 whenever computer-parsable output is
 529                                 required. Use
 530                                 <command>image-status</command> if you
 531                                 are looking for formatted
 532                                 human-readable
 533                                 output.</para></listitem>
 534                         </varlistentry>
 535
 536                         <varlistentry>
 537                                 <term><command>clone</command> <replaceable>NAME</replaceable> <replaceable>NAME</replaceable></term>
 538
 539                                 <listitem><para>Clones a container or
 540                                 disk image. The arguments specify the
 541                                 name of the image to clone and the
 542                                 name of the newly cloned image. Note
 543                                 that plain directory container images
 544                                 are cloned into subvolume images with
 545                                 this command. Note that cloning a
 546                                 container or VM image is optimized for
 547                                 btrfs file systems, and might not be
 548                                 efficient on others, due to file
 549                                 system limitations.</para></listitem>
 550                         </varlistentry>
 551
 552                         <varlistentry>
 553                                 <term><command>rename</command> <replaceable>NAME</replaceable> <replaceable>NAME</replaceable></term>
 554
 555                                 <listitem><para>Renames a container or
 556                                 disk image. The arguments specify the
 557                                 name of the image to rename and the
 558                                 new name of the
 559                                 image.</para></listitem>
 560                         </varlistentry>
 561
 562                         <varlistentry>
 563                                 <term><command>read-only</command> <replaceable>NAME</replaceable> [<replaceable>BOOL</replaceable>]</term>
 564
 565                                 <listitem><para>Marks or (unmarks) a
 566                                 container or disk image
 567                                 read-only. Takes a VM or container
 568                                 image name, followed by a boolean as
 569                                 arguments. If the boolean is omitted,
 570                                 positive is implied, i.e. the image is
 571                                 marked read-only.</para></listitem>
 572                         </varlistentry>
 573
 574
 575                         <varlistentry>
 576                                 <term><command>remove</command> <replaceable>NAME</replaceable>...</term>
 577
 578                                 <listitem><para>Removes one or more
 579                                 container or disk images. The special
 580                                 image <literal>.host</literal>, which
 581                                 refers to the host's own directory
 582                                 tree may not be
 583                                 removed.</para></listitem>
 584                         </varlistentry>
 585
 586
 587                 </variablelist></refsect2>
 588
 589         </refsect1>
 590
 591         <refsect1>
 592                 <title>Files and Directories</title>
 593
 594                 <para>Machine images are preferably stored in
 595                 <filename>/var/lib/machines/</filename>, but are also
 596                 searched for in
 597                 <filename>/usr/local/lib/machines/</filename> and
 598                 <filename>/usr/lib/machines/</filename>. For
 599                 compatibility reasons the directory
 600                 <filename>/var/lib/container/</filename> is searched,
 601                 too. Note that images stored below
 602                 <filename>/usr</filename> are always considered
 603                 read-only. It is possible to symlink machines images
 604                 from other directories into
 605                 <filename>/var/lib/machines/</filename> to make them
 606                 available for control with
 607                 <command>machinectl</command>.</para>
 608
 609                 <para>Disk images are understood in three formats:</para>
 610
 611                 <itemizedlist>
 612                         <listitem><para>A simple directory tree,
 613                         containing the files and directories of the
 614                         container to boot.</para></listitem>
 615
 616                         <listitem><para>A subvolume (on btrfs file
 617                         systems), which are similar to the simple
 618                         directories, described above. However, they
 619                         have additional benefits, such as efficient
 620                         cloning and quota reporting.</para></listitem>
 621
 622                         <listitem><para>"Raw" disk images, i.e. binary
 623                         images of disks with a GPT or MBR partition
 624                         table. Images of this type are regular
 625                         files with the suffix
 626                         <literal>.raw</literal>.</para></listitem>
 627                 </itemizedlist>
 628
 629                 <para>See
 630                 <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 631                 for more information on image formats, in particular
 632                 it's <option>--directory=</option> and
 633                 <option>--image=</option> options.</para>
 634         </refsect1>
 635
 636         <refsect1>
 637                 <title>Exit status</title>
 638
 639                 <para>On success, 0 is returned, a non-zero failure
 640                 code otherwise.</para>
 641         </refsect1>
 642
 643         <xi:include href="less-variables.xml" />
 644
 645         <refsect1>
 646                 <title>See Also</title>
 647                 <para>
 648                         <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 649                         <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 650                         <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 651                 </para>
 652         </refsect1>
 653
 654 </refentry>