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