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
  80                                 machine properties, limit the
  81                                 output to certain properties as
  82                                 specified by the argument. If not
  83                                 specified, all set properties are
  84                                 shown. The argument should be a
  85                                 property name, such as
  86                                 <literal>Name</literal>. If
  87                                 specified more than once, all
  88                                 properties with the specified names
  89                                 are shown.</para></listitem>
  90                         </varlistentry>
  91
  92                         <varlistentry>
  93                                 <term><option>-a</option></term>
  94                                 <term><option>--all</option></term>
  95
  96                                 <listitem><para>When showing
  97                                 machine properties, show all
  98                                 properties regardless of whether they are
  99                                 set or not.</para></listitem>
 100                         </varlistentry>
 101
 102                         <varlistentry>
 103                                 <term><option>-l</option></term>
 104                                 <term><option>--full</option></term>
 105
 106                                 <listitem><para>Do not ellipsize
 107                                 process tree entries.</para>
 108                                 </listitem>
 109                         </varlistentry>
 110
 111                         <varlistentry>
 112                                 <term><option>--kill-who=</option></term>
 113
 114                                 <listitem><para>When used with
 115                                 <command>kill</command>,
 116                                 choose which processes to kill. Must
 117                                 be one of <option>leader</option>, or
 118                                 <option>all</option> to select whether
 119                                 to kill only the leader process of the
 120                                 machine or all processes of the
 121                                 machine. If omitted, defaults to
 122                                 <option>all</option>.</para></listitem>
 123                         </varlistentry>
 124
 125                         <varlistentry>
 126                                 <term><option>-s</option></term>
 127                                 <term><option>--signal=</option></term>
 128
 129                                 <listitem><para>When used with
 130                                 <command>kill</command>, choose
 131                                 which signal to send to selected
 132                                 processes. Must be one of the
 133                                 well-known signal specifiers, such as
 134                                 <constant>SIGTERM</constant>,
 135                                 <constant>SIGINT</constant> or
 136                                 <constant>SIGSTOP</constant>. If
 137                                 omitted, defaults to
 138                                 <constant>SIGTERM</constant>.</para></listitem>
 139                         </varlistentry>
 140
 141                         <varlistentry>
 142                                 <term><option>--no-legend</option></term>
 143
 144                                 <listitem><para>Do not print the legend,
 145                                         i.e. the column headers and the
 146                                         footer.</para></listitem>
 147                         </varlistentry>
 148
 149                         <varlistentry>
 150                                 <term><option>--mkdir</option></term>
 151
 152                                 <listitem><para>When used with
 153                                 <command>bind</command> creates the
 154                                 destination directory before applying
 155                                 the bind mount.</para></listitem>
 156                         </varlistentry>
 157
 158
 159                         <varlistentry>
 160                                 <term><option>--read-only</option></term>
 161
 162                                 <listitem><para>When used with
 163                                 <command>bind</command> applies a
 164                                 read-only bind
 165                                 mount.</para></listitem>
 166                         </varlistentry>
 167
 168
 169                         <varlistentry>
 170                                 <term><option>-n</option></term>
 171                                 <term><option>--lines=</option></term>
 172
 173                                 <listitem><para>When used with
 174                                 <command>status</command>, controls
 175                                 the number of journal lines to show,
 176                                 counting from the most recent
 177                                 ones. Takes a positive integer
 178                                 argument. Defaults to 10.</para>
 179                                 </listitem>
 180                         </varlistentry>
 181
 182                         <varlistentry>
 183                                 <term><option>-o</option></term>
 184                                 <term><option>--output=</option></term>
 185
 186                                 <listitem><para>When used with
 187                                 <command>status</command>, controls
 188                                 the formatting of the journal entries
 189                                 that are shown. For the available
 190                                 choices, see
 191                                 <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 192                                 Defaults to
 193                                 <literal>short</literal>.</para></listitem>
 194                         </varlistentry>
 195
 196                         <xi:include href="user-system-options.xml" xpointer="host" />
 197                         <xi:include href="user-system-options.xml" xpointer="machine" />
 198
 199                         <xi:include href="standard-options.xml" xpointer="help" />
 200                         <xi:include href="standard-options.xml" xpointer="version" />
 201                         <xi:include href="standard-options.xml" xpointer="no-pager" />
 202                 </variablelist>
 203
 204                 <para>The following commands are understood:</para>
 205
 206                 <variablelist>
 207                         <varlistentry>
 208                                 <term><command>list</command></term>
 209
 210                                 <listitem><para>List currently running
 211                                 virtual machines and containers.
 212                                 </para></listitem>
 213                         </varlistentry>
 214
 215                         <varlistentry>
 216                                 <term><command>status</command> <replaceable>NAME</replaceable>...</term>
 217
 218                                 <listitem><para>Show terse runtime
 219                                 status information about one or more
 220                                 virtual machines and containers,
 221                                 followed by the most recent log data
 222                                 from the journal. This function is
 223                                 intended to generate human-readable
 224                                 output. If you are looking for
 225                                 computer-parsable output, use
 226                                 <command>show</command> instead. Note
 227                                 that the log data shown is reported by
 228                                 the virtual machine or container
 229                                 manager, and frequently contains
 230                                 console output of the machine, but not
 231                                 necessarily journal contents of the
 232                                 machine itself.</para></listitem>
 233                         </varlistentry>
 234
 235                         <varlistentry>
 236                                 <term><command>show</command> <replaceable>NAME</replaceable>...</term>
 237
 238                                 <listitem><para>Show properties of one
 239                                 or more registered virtual machines or
 240                                 containers or the manager itself. If
 241                                 no argument is specified, properties
 242                                 of the manager will be shown. If an
 243                                 NAME is specified, properties of this
 244                                 virtual machine or container are
 245                                 shown. By default, empty properties
 246                                 are suppressed. Use
 247                                 <option>--all</option> to show those
 248                                 too. To select specific properties to
 249                                 show, use
 250                                 <option>--property=</option>. This
 251                                 command is intended to be used
 252                                 whenever computer-parsable output is
 253                                 required. Use
 254                                 <command>status</command> if you are
 255                                 looking for formatted human-readable
 256                                 output.</para></listitem>
 257                         </varlistentry>
 258
 259                         <varlistentry>
 260                                 <term><command>login</command> <replaceable>NAME</replaceable></term>
 261
 262                                 <listitem><para>Open a terminal login
 263                                 session to a container. This will
 264                                 create a TTY connection to a specific
 265                                 container and asks for the execution of a
 266                                 getty on it. Note that this is only
 267                                 supported for containers running
 268                                 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 269                                 as init system.</para></listitem>
 270                         </varlistentry>
 271
 272                         <varlistentry>
 273                                 <term><command>reboot</command> <replaceable>NAME</replaceable>...</term>
 274
 275                                 <listitem><para>Reboot one or more
 276                                 containers. This will trigger a reboot
 277                                 by sending SIGINT to the container's
 278                                 init process, which is roughly
 279                                 equivalent to pressing Ctrl+Alt+Del on
 280                                 a non-containerized system, and is
 281                                 compatible with containers running any
 282                                 init system.</para></listitem>
 283                         </varlistentry>
 284
 285                         <varlistentry>
 286                                 <term><command>poweroff</command> <replaceable>NAME</replaceable>...</term>
 287
 288                                 <listitem><para>Power off one or more
 289                                 containers. This will trigger a reboot
 290                                 by sending SIGRTMIN+4 to the
 291                                 container's init process, which causes
 292                                 systemd-compatible init systems to
 293                                 shut down cleanly. This operation does
 294                                 not work on containers that do not run
 295                                 a
 296                                 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>-compatible
 297                                 init system, such as
 298                                 sysvinit.</para></listitem>
 299                         </varlistentry>
 300
 301                         <varlistentry>
 302                                 <term><command>kill</command> <replaceable>NAME</replaceable>...</term>
 303
 304                                 <listitem><para>Send a signal to one
 305                                 or more processes of the virtual
 306                                 machine or container. This means
 307                                 processes as seen by the host, not the
 308                                 processes inside the virtual machine
 309                                 or container.
 310                                 Use <option>--kill-who=</option> to
 311                                 select which process to kill. Use
 312                                 <option>--signal=</option> to select
 313                                 the signal to send.</para></listitem>
 314                         </varlistentry>
 315
 316                         <varlistentry>
 317                                 <term><command>terminate</command> <replaceable>NAME</replaceable>...</term>
 318
 319                                 <listitem><para>Terminates a virtual
 320                                 machine or container. This kills all
 321                                 processes of the virtual machine or
 322                                 container and deallocates all
 323                                 resources attached to that
 324                                 instance.</para></listitem>
 325                         </varlistentry>
 326
 327                         <varlistentry>
 328                                 <term><command>bind</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term>
 329
 330                                 <listitem><para>Bind mounts a
 331                                 directory from the host into the
 332                                 specified container. The first
 333                                 directory argument is the source
 334                                 directory on the host, the second
 335                                 directory argument the source
 336                                 directory on the host. When the latter
 337                                 is omitted the destination path in the
 338                                 container is the same as the source
 339                                 path on the host. When combined with
 340                                 the <option>--read-only</option>
 341                                 switch a ready-only bind mount is
 342                                 created. When combined with the
 343                                 <option>--mkdir</option> switch the
 344                                 destination path is first created
 345                                 before the mount is applied. Note that
 346                                 this option is currently only
 347                                 supported for
 348                                 <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 349                                 containers.</para></listitem>
 350                         </varlistentry>
 351
 352                         <varlistentry>
 353                                 <term><command>copy-to</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term>
 354
 355                                 <listitem><para>Copies files or
 356                                 directories from the host system into
 357                                 a running container. Takes a container
 358                                 name, followed by the source path on
 359                                 the host and the destination path in
 360                                 the container. If the destination path
 361                                 is omitted the same as the source path
 362                                 is used.</para></listitem>
 363                         </varlistentry>
 364
 365
 366                         <varlistentry>
 367                                 <term><command>copy-from</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term>
 368
 369                                 <listitem><para>Copies files or
 370                                 directories from a container into the
 371                                 host system. Takes a container name,
 372                                 followed by the source path in the
 373                                 container the destination path on the
 374                                 host. If the destination path is
 375                                 omitted the same as the source path is
 376                                 used.</para></listitem>
 377                         </varlistentry>
 378
 379                 </variablelist>
 380
 381         </refsect1>
 382
 383         <refsect1>
 384                 <title>Exit status</title>
 385
 386                 <para>On success, 0 is returned, a non-zero failure
 387                 code otherwise.</para>
 388         </refsect1>
 389
 390         <xi:include href="less-variables.xml" />
 391
 392         <refsect1>
 393                 <title>See Also</title>
 394                 <para>
 395                         <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 396                         <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 397                         <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 398                 </para>
 399         </refsect1>
 400
 401 </refentry>