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                         <xi:include href="user-system-options.xml" xpointer="host" />
 150                         <xi:include href="user-system-options.xml" xpointer="machine" />
 151
 152                         <xi:include href="standard-options.xml" xpointer="help" />
 153                         <xi:include href="standard-options.xml" xpointer="version" />
 154                         <xi:include href="standard-options.xml" xpointer="no-pager" />
 155                 </variablelist>
 156
 157                 <para>The following commands are understood:</para>
 158
 159                 <variablelist>
 160                         <varlistentry>
 161                                 <term><command>list</command></term>
 162
 163                                 <listitem><para>List currently running
 164                                 virtual machines and containers.
 165                                 </para></listitem>
 166                         </varlistentry>
 167
 168                         <varlistentry>
 169                                 <term><command>status</command> <replaceable>ID</replaceable>...</term>
 170
 171                                 <listitem><para>Show terse runtime
 172                                 status information about one or more
 173                                 virtual machines and containers. This
 174                                 function is intended to generate
 175                                 human-readable output. If you are
 176                                 looking for computer-parsable output,
 177                                 use <command>show</command> instead.
 178                                 </para></listitem>
 179                         </varlistentry>
 180
 181                         <varlistentry>
 182                                 <term><command>show</command> <replaceable>ID</replaceable>...</term>
 183
 184                                 <listitem><para>Show properties of one
 185                                 or more registered virtual machines or
 186                                 containers or the manager itself. If
 187                                 no argument is specified, properties
 188                                 of the manager will be shown. If an
 189                                 ID is specified, properties of this
 190                                 virtual machine or container are
 191                                 shown. By default, empty properties
 192                                 are suppressed. Use
 193                                 <option>--all</option> to show those
 194                                 too. To select specific properties to
 195                                 show, use
 196                                 <option>--property=</option>. This
 197                                 command is intended to be used
 198                                 whenever computer-parsable output is
 199                                 required. Use
 200                                 <command>status</command> if you are
 201                                 looking for formatted human-readable
 202                                 output.</para></listitem>
 203                         </varlistentry>
 204
 205                         <varlistentry>
 206                                 <term><command>login</command> <replaceable>ID</replaceable></term>
 207
 208                                 <listitem><para>Open a terminal login
 209                                 session to a container. This will
 210                                 create a TTY connection to a specific
 211                                 container and asks for the execution of a
 212                                 getty on it. Note that this is only
 213                                 supported for containers running
 214                                 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 215                                 as init system.</para></listitem>
 216                         </varlistentry>
 217
 218                         <varlistentry>
 219                                 <term><command>reboot</command> <replaceable>ID</replaceable>...</term>
 220
 221                                 <listitem><para>Reboot one or more
 222                                 containers. This will trigger a reboot
 223                                 by sending SIGINT to the container's
 224                                 init process, which is roughly
 225                                 equivalent to pressing Ctrl+Alt+Del on
 226                                 a non-containerized system, and is
 227                                 compatible with containers running any
 228                                 init system.</para></listitem>
 229                         </varlistentry>
 230
 231                         <varlistentry>
 232                                 <term><command>poweroff</command> <replaceable>ID</replaceable>...</term>
 233
 234                                 <listitem><para>Power off one or more
 235                                 containers. This will trigger a reboot
 236                                 by sending SIGRTMIN+4 to the
 237                                 container's init process, which causes
 238                                 systemd-compatible init systems to
 239                                 shut down cleanly. This operation does
 240                                 not work on containers that do not run
 241                                 a
 242                                 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>-compatible
 243                                 init system, such as
 244                                 sysvinit.</para></listitem>
 245                         </varlistentry>
 246
 247                         <varlistentry>
 248                                 <term><command>kill</command> <replaceable>ID</replaceable>...</term>
 249
 250                                 <listitem><para>Send a signal to one
 251                                 or more processes of the virtual
 252                                 machine or container. This means
 253                                 processes as seen by the host, not the
 254                                 processes inside the virtual machine
 255                                 or container.
 256                                 Use <option>--kill-who=</option> to
 257                                 select which process to kill. Use
 258                                 <option>--signal=</option> to select
 259                                 the signal to send.</para></listitem>
 260                         </varlistentry>
 261
 262                         <varlistentry>
 263                                 <term><command>terminate</command> <replaceable>ID</replaceable>...</term>
 264
 265                                 <listitem><para>Terminates a virtual
 266                                 machine or container. This kills all
 267                                 processes of the virtual machine or
 268                                 container and deallocates all
 269                                 resources attached to that
 270                                 instance.</para></listitem>
 271                         </varlistentry>
 272
 273                 </variablelist>
 274
 275         </refsect1>
 276
 277         <refsect1>
 278                 <title>Exit status</title>
 279
 280                 <para>On success, 0 is returned, a non-zero failure
 281                 code otherwise.</para>
 282         </refsect1>
 283
 284         <xi:include href="less-variables.xml" />
 285
 286         <refsect1>
 287                 <title>See Also</title>
 288                 <para>
 289                         <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 290                         <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 291                         <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 292                 </para>
 293         </refsect1>
 294
 295 </refentry>