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>-h</option></term>
  77                                 <term><option>--help</option></term>
  78
  79                                 <listitem><para>Prints a short help
  80                                 text and exits.</para></listitem>
  81                         </varlistentry>
  82
  83                         <varlistentry>
  84                                 <term><option>--version</option></term>
  85
  86                                 <listitem><para>Prints a short version
  87                                 string and exits.</para></listitem>
  88                         </varlistentry>
  89
  90                         <varlistentry>
  91                                 <term><option>--no-pager</option></term>
  92
  93                                 <listitem><para>Do not pipe output into a
  94                                 pager.</para></listitem>
  95                         </varlistentry>
  96
  97                         <varlistentry>
  98                                 <term><option>--no-legend</option></term>
  99
 100                                 <listitem><para>Do not print the legend,
 101                                         i.e. the column headers and the
 102                                         footer.</para></listitem>
 103                         </varlistentry>
 104
 105                         <varlistentry>
 106                                 <term><option>--no-ask-password</option></term>
 107
 108                                 <listitem><para>Do not query the user
 109                                 for authentication for privileged
 110                                 operations.</para></listitem>
 111                         </varlistentry>
 112
 113                         <varlistentry>
 114                                 <term><option>-H</option></term>
 115                                 <term><option>--host=</option></term>
 116
 117                                 <listitem><para>Execute the operation
 118                                 remotely. Specify a hostname, or
 119                                 username and hostname separated by <literal>@</literal>,
 120                                 to connect to. This will use SSH to
 121                                 talk to the remote machine manager
 122                                 instance.</para></listitem>
 123                         </varlistentry>
 124
 125                         <varlistentry>
 126                                 <term><option>-M</option></term>
 127                                 <term><option>--machine=</option></term>
 128
 129                                 <listitem><para>Execute the operation on a
 130                                 local container. Specify a container
 131                                 name to connect to.</para></listitem>
 132                         </varlistentry>
 133
 134                         <varlistentry>
 135                                 <term><option>-p</option></term>
 136                                 <term><option>--property=</option></term>
 137
 138                                 <listitem><para>When showing
 139                                 machine properties, limit the
 140                                 output to certain properties as
 141                                 specified by the argument. If not
 142                                 specified, all set properties are
 143                                 shown. The argument should be a
 144                                 property name, such as
 145                                 <literal>Name</literal>. If
 146                                 specified more than once, all
 147                                 properties with the specified names
 148                                 are shown.</para></listitem>
 149                         </varlistentry>
 150
 151                         <varlistentry>
 152                                 <term><option>-a</option></term>
 153                                 <term><option>--all</option></term>
 154
 155                                 <listitem><para>When showing
 156                                 machine properties, show all
 157                                 properties regardless of whether they are
 158                                 set or not.</para></listitem>
 159                         </varlistentry>
 160
 161                         <varlistentry>
 162                                 <term><option>-l</option></term>
 163                                 <term><option>--full</option></term>
 164
 165                                 <listitem><para>Do not ellipsize
 166                                 process tree entries.</para>
 167                                 </listitem>
 168                         </varlistentry>
 169
 170                         <varlistentry>
 171                                 <term><option>--kill-who=</option></term>
 172
 173                                 <listitem><para>When used with
 174                                 <command>kill</command>,
 175                                 choose which processes to kill. Must
 176                                 be one of <option>leader</option>, or
 177                                 <option>all</option> to select whether
 178                                 to kill only the leader process of the
 179                                 machine or all processes of the
 180                                 machine. If omitted, defaults to
 181                                 <option>all</option>.</para></listitem>
 182                         </varlistentry>
 183
 184                         <varlistentry>
 185                                 <term><option>-s</option></term>
 186                                 <term><option>--signal=</option></term>
 187
 188                                 <listitem><para>When used with
 189                                 <command>kill</command>, choose
 190                                 which signal to send to selected
 191                                 processes. Must be one of the
 192                                 well-known signal specifiers, such as
 193                                 <constant>SIGTERM</constant>,
 194                                 <constant>SIGINT</constant> or
 195                                 <constant>SIGSTOP</constant>. If
 196                                 omitted, defaults to
 197                                 <constant>SIGTERM</constant>.</para></listitem>
 198                         </varlistentry>
 199
 200                 </variablelist>
 201
 202                 <para>The following commands are understood:</para>
 203
 204                 <variablelist>
 205                         <varlistentry>
 206                                 <term><command>list</command></term>
 207
 208                                 <listitem><para>List currently running
 209                                 virtual machines and containers.
 210                                 </para></listitem>
 211                         </varlistentry>
 212
 213                         <varlistentry>
 214                                 <term><command>status</command> <replaceable>ID</replaceable>...</term>
 215
 216                                 <listitem><para>Show terse runtime
 217                                 status information about one or more
 218                                 virtual machines and containers. This
 219                                 function is intended to generate
 220                                 human-readable output. If you are
 221                                 looking for computer-parsable output,
 222                                 use <command>show</command> instead.
 223                                 </para></listitem>
 224                         </varlistentry>
 225
 226                         <varlistentry>
 227                                 <term><command>show</command> <replaceable>ID</replaceable>...</term>
 228
 229                                 <listitem><para>Show properties of one
 230                                 or more registered virtual machines or
 231                                 containers or the manager itself. If
 232                                 no argument is specified, properties
 233                                 of the manager will be shown. If an
 234                                 ID is specified, properties of this
 235                                 virtual machine or container are
 236                                 shown. By default, empty properties
 237                                 are suppressed. Use
 238                                 <option>--all</option> to show those
 239                                 too. To select specific properties to
 240                                 show, use
 241                                 <option>--property=</option>. This
 242                                 command is intended to be used
 243                                 whenever computer-parsable output is
 244                                 required. Use
 245                                 <command>status</command> if you are
 246                                 looking for formatted human-readable
 247                                 output.</para></listitem>
 248                         </varlistentry>
 249
 250                         <varlistentry>
 251                                 <term><command>terminate</command> <replaceable>ID</replaceable>...</term>
 252
 253                                 <listitem><para>Terminates a virtual
 254                                 machine or container. This kills all
 255                                 processes of the virtual machine or
 256                                 container and deallocates all
 257                                 resources attached to that
 258                                 instance.</para></listitem>
 259                         </varlistentry>
 260
 261                         <varlistentry>
 262                                 <term><command>kill</command> <replaceable>ID</replaceable>...</term>
 263
 264                                 <listitem><para>Send a signal to one
 265                                 or more processes of the virtual
 266                                 machine or container. This means
 267                                 processes as seen by the host, not the
 268                                 processes inside the virtual machine
 269                                 or container.
 270                                 Use <option>--kill-who=</option> to
 271                                 select which process to kill. Use
 272                                 <option>--signal=</option> to select
 273                                 the signal to send.</para></listitem>
 274                         </varlistentry>
 275
 276                         <varlistentry>
 277                                 <term><command>reboot</command> <replaceable>ID</replaceable>...</term>
 278
 279                                 <listitem><para>Reboot one or more
 280                                 containers. This will trigger a reboot
 281                                 by sending SIGINT to the container's
 282                                 init process, which is roughly
 283                                 equivalent to pressing Ctrl+Alt+Del on
 284                                 a non-containerized
 285                                 system.</para></listitem>
 286                         </varlistentry>
 287
 288                         <varlistentry>
 289                                 <term><command>login</command> <replaceable>ID</replaceable></term>
 290
 291                                 <listitem><para>Open a terminal login
 292                                 session to a container. This will
 293                                 create a TTY connection to a specific
 294                                 container and asks for the execution of a
 295                                 getty on it. Note that this is only
 296                                 supported for containers running
 297                                 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 298                                 as init system.</para></listitem>
 299                         </varlistentry>
 300                 </variablelist>
 301
 302         </refsect1>
 303
 304         <refsect1>
 305                 <title>Exit status</title>
 306
 307                 <para>On success, 0 is returned, a non-zero failure
 308                 code otherwise.</para>
 309         </refsect1>
 310
 311         <xi:include href="less-variables.xml" />
 312
 313         <refsect1>
 314                 <title>See Also</title>
 315                 <para>
 316                         <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 317                         <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 318                         <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 319                 </para>
 320         </refsect1>
 321
 322 </refentry>