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>--no-legend</option></term>
 155
 156                                 <listitem><para>Do not print the legend,
 157                                         i.e. the column headers and the
 158                                         footer.</para></listitem>
 159                         </varlistentry>
 160
 161                         <varlistentry>
 162                                 <term><option>--mkdir</option></term>
 163
 164                                 <listitem><para>When used with
 165                                 <command>bind</command> creates the
 166                                 destination directory before applying
 167                                 the bind mount.</para></listitem>
 168                         </varlistentry>
 169
 170
 171                         <varlistentry>
 172                                 <term><option>--read-only</option></term>
 173
 174                                 <listitem><para>When used with
 175                                 <command>bind</command> applies a
 176                                 read-only bind
 177                                 mount.</para></listitem>
 178                         </varlistentry>
 179
 180
 181                         <varlistentry>
 182                                 <term><option>-n</option></term>
 183                                 <term><option>--lines=</option></term>
 184
 185                                 <listitem><para>When used with
 186                                 <command>status</command>, controls
 187                                 the number of journal lines to show,
 188                                 counting from the most recent
 189                                 ones. Takes a positive integer
 190                                 argument. Defaults to 10.</para>
 191                                 </listitem>
 192                         </varlistentry>
 193
 194                         <varlistentry>
 195                                 <term><option>-o</option></term>
 196                                 <term><option>--output=</option></term>
 197
 198                                 <listitem><para>When used with
 199                                 <command>status</command>, controls
 200                                 the formatting of the journal entries
 201                                 that are shown. For the available
 202                                 choices, see
 203                                 <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 204                                 Defaults to
 205                                 <literal>short</literal>.</para></listitem>
 206                         </varlistentry>
 207
 208                         <xi:include href="user-system-options.xml" xpointer="host" />
 209                         <xi:include href="user-system-options.xml" xpointer="machine" />
 210
 211                         <xi:include href="standard-options.xml" xpointer="help" />
 212                         <xi:include href="standard-options.xml" xpointer="version" />
 213                         <xi:include href="standard-options.xml" xpointer="no-pager" />
 214                 </variablelist>
 215         </refsect1>
 216
 217         <refsect1>
 218                 <title>Commands</title>
 219
 220                 <para>The following commands are understood:</para>
 221
 222                 <refsect2><title>Machine Commands</title><variablelist>
 223
 224                         <varlistentry>
 225                                 <term><command>list</command></term>
 226
 227                                 <listitem><para>List currently running
 228                                 (online) virtual machines and
 229                                 containers. To enumerate container
 230                                 images that can be started,
 231                                 use <command>list-images</command>
 232                                 (see below).</para></listitem>
 233                         </varlistentry>
 234
 235                         <varlistentry>
 236                                 <term><command>status</command> <replaceable>NAME</replaceable>...</term>
 237
 238                                 <listitem><para>Show terse runtime
 239                                 status information about one or more
 240                                 virtual machines and containers,
 241                                 followed by the most recent log data
 242                                 from the journal. This function is
 243                                 intended to generate human-readable
 244                                 output. If you are looking for
 245                                 computer-parsable output, use
 246                                 <command>show</command> instead. Note
 247                                 that the log data shown is reported by
 248                                 the virtual machine or container
 249                                 manager, and frequently contains
 250                                 console output of the machine, but not
 251                                 necessarily journal contents of the
 252                                 machine itself.</para></listitem>
 253                         </varlistentry>
 254
 255                         <varlistentry>
 256                                 <term><command>show</command> <replaceable>NAME</replaceable>...</term>
 257
 258                                 <listitem><para>Show properties of one
 259                                 or more registered virtual machines or
 260                                 containers or the manager itself. If
 261                                 no argument is specified, properties
 262                                 of the manager will be shown. If an
 263                                 NAME is specified, properties of this
 264                                 virtual machine or container are
 265                                 shown. By default, empty properties
 266                                 are suppressed. Use
 267                                 <option>--all</option> to show those
 268                                 too. To select specific properties to
 269                                 show, use
 270                                 <option>--property=</option>. This
 271                                 command is intended to be used
 272                                 whenever computer-parsable output is
 273                                 required. Use
 274                                 <command>status</command> if you are
 275                                 looking for formatted human-readable
 276                                 output.</para></listitem>
 277                         </varlistentry>
 278
 279                         <varlistentry>
 280                                 <term><command>start</command> <replaceable>NAME</replaceable>...</term>
 281
 282                                 <listitem><para>Start a container as a
 283                                 system service, using
 284                                 <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 285                                 This starts
 286                                 <filename>systemd-nspawn@.service</filename>,
 287                                 instantiated for the specified machine
 288                                 name, similar to the effect of
 289                                 <command>systemctl start</command> on
 290                                 the service
 291                                 name. <command>systemd-nspawn</command>
 292                                 looks for a container image by the
 293                                 specified name in
 294                                 <filename>/var/lib/container</filename>
 295                                 and runs it. Use
 296                                 <command>list-images</command> (see
 297                                 below), for listing available
 298                                 container images to start.</para>
 299
 300                                 <para>Note that
 301                                 <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 302                                 also interfaces with a variety of
 303                                 other container and VM managers,
 304                                 <command>systemd-nspawn</command> is
 305                                 just one implementation of it. Most of
 306                                 the commands available in
 307                                 <command>machinectl</command> may be
 308                                 used on containers or VMs controlled
 309                                 by other managers, not just
 310                                 <command>systemd-nspawn</command>. Starting
 311                                 VMs and container images on those
 312                                 managers requires manager-specific
 313                                 tools.</para>
 314
 315                                 <para>To interactively start a
 316                                 container on the command line with
 317                                 full access to the container's
 318                                 console, please invoke
 319                                 <command>systemd-nspawn</command>
 320                                 directly. To stop a running container
 321                                 use <command>machinectl
 322                                 poweroff</command>, see
 323                                 below.</para></listitem>
 324                         </varlistentry>
 325
 326                         <varlistentry>
 327                                 <term><command>login</command> <replaceable>NAME</replaceable></term>
 328
 329                                 <listitem><para>Open an interactive terminal login
 330                                 session to a container. This will
 331                                 create a TTY connection to a specific
 332                                 container and asks for the execution of a
 333                                 getty on it. Note that this is only
 334                                 supported for containers running
 335                                 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 336                                 as init system.</para>
 337
 338                                 <para>This command will open a full
 339                                 login prompt on the container, which
 340                                 then asks for username and
 341                                 password. Use
 342                                 <citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 343                                 with the <option>--machine=</option>
 344                                 switch to invoke a single command,
 345                                 either interactively or in the
 346                                 background within a local
 347                                 container.</para></listitem>
 348                         </varlistentry>
 349
 350                         <varlistentry>
 351                                 <term><command>enable</command> <replaceable>NAME</replaceable>...</term>
 352                                 <term><command>disable</command> <replaceable>NAME</replaceable>...</term>
 353
 354                                 <listitem><para>Enable or disable a
 355                                 container as a system service to start
 356                                 at system boot, using
 357                                 <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 358                                 This enables or disables
 359                                 <filename>systemd-nspawn@.service</filename>,
 360                                 instantiated for the specified machine
 361                                 name, similar to the effect of
 362                                 <command>systemctl enable</command> or
 363                                 <command>systemctl disable</command>
 364                                 on the service name.</para></listitem>
 365                         </varlistentry>
 366
 367                         <varlistentry>
 368                                 <term><command>poweroff</command> <replaceable>NAME</replaceable>...</term>
 369
 370                                 <listitem><para>Power off one or more
 371                                 containers. This will trigger a reboot
 372                                 by sending SIGRTMIN+4 to the
 373                                 container's init process, which causes
 374                                 systemd-compatible init systems to
 375                                 shut down cleanly. This operation does
 376                                 not work on containers that do not run
 377                                 a
 378                                 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>-compatible
 379                                 init system, such as sysvinit. Use
 380                                 <command>terminate</command> (see
 381                                 below) to immediately terminate a
 382                                 container or VM, without cleanly
 383                                 shutting it down.</para></listitem>
 384                         </varlistentry>
 385
 386                         <varlistentry>
 387                                 <term><command>reboot</command> <replaceable>NAME</replaceable>...</term>
 388
 389                                 <listitem><para>Reboot one or more
 390                                 containers. This will trigger a reboot
 391                                 by sending SIGINT to the container's
 392                                 init process, which is roughly
 393                                 equivalent to pressing Ctrl+Alt+Del on
 394                                 a non-containerized system, and is
 395                                 compatible with containers running any
 396                                 system manager.</para></listitem>
 397                         </varlistentry>
 398
 399                         <varlistentry>
 400                                 <term><command>terminate</command> <replaceable>NAME</replaceable>...</term>
 401
 402                                 <listitem><para>Immediately terminates
 403                                 a virtual machine or container,
 404                                 without cleanly shutting it down. This
 405                                 kills all processes of the virtual
 406                                 machine or container and deallocates
 407                                 all resources attached to that
 408                                 instance. Use
 409                                 <command>poweroff</command> to issue a
 410                                 clean shutdown request.</para></listitem>
 411                         </varlistentry>
 412
 413                         <varlistentry>
 414                                 <term><command>kill</command> <replaceable>NAME</replaceable>...</term>
 415
 416                                 <listitem><para>Send a signal to one
 417                                 or more processes of the virtual
 418                                 machine or container. This means
 419                                 processes as seen by the host, not the
 420                                 processes inside the virtual machine
 421                                 or container.
 422                                 Use <option>--kill-who=</option> to
 423                                 select which process to kill. Use
 424                                 <option>--signal=</option> to select
 425                                 the signal to send.</para></listitem>
 426                         </varlistentry>
 427
 428                         <varlistentry>
 429                                 <term><command>bind</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term>
 430
 431                                 <listitem><para>Bind mounts a
 432                                 directory from the host into the
 433                                 specified container. The first
 434                                 directory argument is the source
 435                                 directory on the host, the second
 436                                 directory argument the source
 437                                 directory on the host. When the latter
 438                                 is omitted the destination path in the
 439                                 container is the same as the source
 440                                 path on the host. When combined with
 441                                 the <option>--read-only</option>
 442                                 switch a ready-only bind mount is
 443                                 created. When combined with the
 444                                 <option>--mkdir</option> switch the
 445                                 destination path is first created
 446                                 before the mount is applied. Note that
 447                                 this option is currently only
 448                                 supported for
 449                                 <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 450                                 containers.</para></listitem>
 451                         </varlistentry>
 452
 453                         <varlistentry>
 454                                 <term><command>copy-to</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term>
 455
 456                                 <listitem><para>Copies files or
 457                                 directories from the host system into
 458                                 a running container. Takes a container
 459                                 name, followed by the source path on
 460                                 the host and the destination path in
 461                                 the container. If the destination path
 462                                 is omitted the same as the source path
 463                                 is used.</para></listitem>
 464                         </varlistentry>
 465
 466
 467                         <varlistentry>
 468                                 <term><command>copy-from</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term>
 469
 470                                 <listitem><para>Copies files or
 471                                 directories from a container into the
 472                                 host system. Takes a container name,
 473                                 followed by the source path in the
 474                                 container the destination path on the
 475                                 host. If the destination path is
 476                                 omitted the same as the source path is
 477                                 used.</para></listitem>
 478                         </varlistentry>
 479                 </variablelist></refsect2>
 480
 481                 <refsect2><title>Image Commands</title><variablelist>
 482
 483                         <varlistentry>
 484                                 <term><command>list-images</command></term>
 485
 486                                 <listitem><para>Show a list of locally
 487                                 installed container and VM
 488                                 images. This enumerates all raw disk
 489                                 images and container directories and
 490                                 subvolumes in
 491                                 <filename>/var/lib/container/</filename>. Use
 492                                 <command>start</command> (see above)
 493                                 to run a container off one of the
 494                                 listed images. Note that by default
 495                                 containers whose name begins with a
 496                                 dot (<literal>.</literal>) are not
 497                                 shown. To show these too, specify
 498                                 <option>--all</option>. Note that a
 499                                 special image <literal>.host</literal>
 500                                 always implicitly exists and refers to
 501                                 the image the host itself is booted
 502                                 from.</para></listitem>
 503                         </varlistentry>
 504
 505                         <varlistentry>
 506                                 <term><command>image-status</command> <replaceable>NAME</replaceable>...</term>
 507
 508                                 <listitem><para>Show terse status
 509                                 information about one or more
 510                                 container or VM images. This function
 511                                 is intended to generate human-readable
 512                                 output. Use
 513                                 <command>show-image</command> (see
 514                                 below) to generate computer-parsable
 515                                 output instead.</para></listitem>
 516                         </varlistentry>
 517
 518                         <varlistentry>
 519                                 <term><command>show-image</command> <replaceable>NAME</replaceable>...</term>
 520
 521                                 <listitem><para>Show properties of one
 522                                 or more registered virtual machine or
 523                                 container images, or the manager
 524                                 itself. If no argument is specified,
 525                                 properties of the manager will be
 526                                 shown. If an NAME is specified,
 527                                 properties of this virtual machine or
 528                                 container image are shown. By default,
 529                                 empty properties are suppressed. Use
 530                                 <option>--all</option> to show those
 531                                 too. To select specific properties to
 532                                 show, use
 533                                 <option>--property=</option>. This
 534                                 command is intended to be used
 535                                 whenever computer-parsable output is
 536                                 required. Use
 537                                 <command>image-status</command> if you
 538                                 are looking for formatted
 539                                 human-readable
 540                                 output.</para></listitem>
 541                         </varlistentry>
 542
 543                         <varlistentry>
 544                                 <term><command>clone</command> <replaceable>NAME</replaceable> <replaceable>NAME</replaceable></term>
 545
 546                                 <listitem><para>Clones a container or
 547                                 disk image. The arguments specify the
 548                                 name of the image to clone and the
 549                                 name of the newly cloned image. Note
 550                                 that plain directory container images
 551                                 are cloned into subvolume images with
 552                                 this command. Note that cloning a
 553                                 container or VM image is optimized for
 554                                 btrfs file systems, and might not be
 555                                 efficient on others, due to file
 556                                 system limitations.</para></listitem>
 557                         </varlistentry>
 558
 559                         <varlistentry>
 560                                 <term><command>rename</command> <replaceable>NAME</replaceable> <replaceable>NAME</replaceable></term>
 561
 562                                 <listitem><para>Renames a container or
 563                                 disk image. The arguments specify the
 564                                 name of the image to rename and the
 565                                 new name of the
 566                                 image.</para></listitem>
 567                         </varlistentry>
 568
 569                         <varlistentry>
 570                                 <term><command>read-only</command> <replaceable>NAME</replaceable> [<replaceable>BOOL</replaceable>]</term>
 571
 572                                 <listitem><para>Marks or (unmarks) a
 573                                 container or disk image
 574                                 read-only. Takes a VM or container
 575                                 image name, followed by a boolean as
 576                                 arguments. If the boolean is omitted,
 577                                 positive is implied, i.e. the image is
 578                                 marked read-only.</para></listitem>
 579                         </varlistentry>
 580
 581
 582                         <varlistentry>
 583                                 <term><command>remove</command> <replaceable>NAME</replaceable>...</term>
 584
 585                                 <listitem><para>Removes one or more
 586                                 container or disk images. The special
 587                                 image <literal>.host</literal>, which
 588                                 refers to the host's own directory
 589                                 tree may not be
 590                                 removed.</para></listitem>
 591                         </varlistentry>
 592
 593
 594                 </variablelist></refsect2>
 595
 596         </refsect1>
 597
 598         <refsect1>
 599                 <title>Exit status</title>
 600
 601                 <para>On success, 0 is returned, a non-zero failure
 602                 code otherwise.</para>
 603         </refsect1>
 604
 605         <xi:include href="less-variables.xml" />
 606
 607         <refsect1>
 608                 <title>See Also</title>
 609                 <para>
 610                         <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 611                         <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 612                         <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 613                 </para>
 614         </refsect1>
 615
 616 </refentry>