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