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
  26         <refentryinfo>
  27                 <title>machinectl</title>
  28                 <productname>systemd</productname>
  29
  30                 <authorgroup>
  31                         <author>
  32                                 <contrib>Developer</contrib>
  33                                 <firstname>Lennart</firstname>
  34                                 <surname>Poettering</surname>
  35                                 <email>lennart@poettering.net</email>
  36                         </author>
  37                 </authorgroup>
  38         </refentryinfo>
  39
  40         <refmeta>
  41                 <refentrytitle>machinectl</refentrytitle>
  42                 <manvolnum>1</manvolnum>
  43         </refmeta>
  44
  45         <refnamediv>
  46                 <refname>machinectl</refname>
  47                 <refpurpose>Control the systemd machine manager</refpurpose>
  48         </refnamediv>
  49
  50         <refsynopsisdiv>
  51                 <cmdsynopsis>
  52                         <command>machinectl</command>
  53                         <arg choice="opt" rep="repeat">OPTIONS</arg>
  54                         <arg choice="req">COMMAND</arg>
  55                         <arg choice="opt" rep="repeat">NAME</arg>
  56                 </cmdsynopsis>
  57         </refsynopsisdiv>
  58
  59         <refsect1>
  60                 <title>Description</title>
  61
  62                 <para><command>machinectl</command> may be used to
  63                 introspect and control the state of the
  64                 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
  65                 virtual machine and container registration manager <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
  66         </refsect1>
  67
  68         <refsect1>
  69                 <title>Options</title>
  70
  71                 <para>The following options are understood:</para>
  72
  73                 <variablelist>
  74                         <varlistentry>
  75                                 <term><option>-h</option></term>
  76                                 <term><option>--help</option></term>
  77
  78                                 <listitem><para>Prints a short help
  79                                 text and exits.</para></listitem>
  80                         </varlistentry>
  81
  82                         <varlistentry>
  83                                 <term><option>--version</option></term>
  84
  85                                 <listitem><para>Prints a short version
  86                                 string and exits.</para></listitem>
  87                         </varlistentry>
  88
  89                         <varlistentry>
  90                                 <term><option>--no-pager</option></term>
  91
  92                                 <listitem><para>Do not pipe output into a
  93                                 pager.</para></listitem>
  94                         </varlistentry>
  95
  96                         <varlistentry>
  97                                 <term><option>--no-ask-password</option></term>
  98
  99                                 <listitem><para>Do not query the user
 100                                 for authentication for privileged
 101                                 operations.</para></listitem>
 102                         </varlistentry>
 103
 104                         <varlistentry>
 105                                 <term><option>-H</option></term>
 106                                 <term><option>--host=</option></term>
 107
 108                                 <listitem><para>Execute the operation
 109                                 remotely. Specify a hostname, or
 110                                 username and hostname separated by <literal>@</literal>,
 111                                 to connect to. This will use SSH to
 112                                 talk to the remote machine manager
 113                                 instance.</para></listitem>
 114                         </varlistentry>
 115
 116                         <varlistentry>
 117                                 <term><option>-M</option></term>
 118                                 <term><option>--machine=</option></term>
 119
 120                                 <listitem><para>Execute the operation on a
 121                                 local container. Specify a container
 122                                 name to connect to.</para></listitem>
 123                         </varlistentry>
 124
 125                         <varlistentry>
 126                                 <term><option>-p</option></term>
 127                                 <term><option>--property=</option></term>
 128
 129                                 <listitem><para>When showing
 130                                 machine properties, limit the
 131                                 output to certain properties as
 132                                 specified by the argument. If not
 133                                 specified, all set properties are
 134                                 shown. The argument should be a
 135                                 property name, such as
 136                                 <literal>Name</literal>. If
 137                                 specified more than once, all
 138                                 properties with the specified names
 139                                 are shown.</para></listitem>
 140                         </varlistentry>
 141
 142                         <varlistentry>
 143                                 <term><option>-a</option></term>
 144                                 <term><option>--all</option></term>
 145
 146                                 <listitem><para>When showing
 147                                 machine properties, show all
 148                                 properties regardless of whether they are
 149                                 set or not.</para></listitem>
 150                         </varlistentry>
 151
 152                         <varlistentry>
 153                                 <term><option>-l</option></term>
 154                                 <term><option>--full</option></term>
 155
 156                                 <listitem><para>Do not ellipsize
 157                                 process tree entries.</para>
 158                                 </listitem>
 159                         </varlistentry>
 160
 161                         <varlistentry>
 162                                 <term><option>--kill-who=</option></term>
 163
 164                                 <listitem><para>When used with
 165                                 <command>kill-machine</command>,
 166                                 choose which processes to kill. Must
 167                                 be one of <option>leader</option>, or
 168                                 <option>all</option> to select whether
 169                                 to kill only the leader process of the
 170                                 machine or all processes of the
 171                                 machine. If omitted, defaults to
 172                                 <option>all</option>.</para></listitem>
 173                         </varlistentry>
 174
 175                         <varlistentry>
 176                                 <term><option>-s</option></term>
 177                                 <term><option>--signal=</option></term>
 178
 179                                 <listitem><para>When used with
 180                                 <command>kill-machine</command>, choose
 181                                 which signal to send to selected
 182                                 processes. Must be one of the
 183                                 well-known signal specifiers, such as
 184                                 <constant>SIGTERM</constant>,
 185                                 <constant>SIGINT</constant> or
 186                                 <constant>SIGSTOP</constant>. If
 187                                 omitted, defaults to
 188                                 <constant>SIGTERM</constant>.</para></listitem>
 189                         </varlistentry>
 190
 191                 </variablelist>
 192
 193                 <para>The following commands are understood:</para>
 194
 195                 <variablelist>
 196                         <varlistentry>
 197                                 <term><command>list</command></term>
 198
 199                                 <listitem><para>List currently running
 200                                 virtual machines and containers.
 201                                 </para></listitem>
 202                         </varlistentry>
 203
 204                         <varlistentry>
 205                                 <term><command>status [ID...]</command></term>
 206
 207                                 <listitem><para>Show terse runtime
 208                                 status information about one or more
 209                                 virtual machines and containers. This
 210                                 function is intended to generate
 211                                 human-readable output. If you are
 212                                 looking for computer-parsable output,
 213                                 use <command>show</command> instead.
 214                                 </para></listitem>
 215                         </varlistentry>
 216
 217                         <varlistentry>
 218                                 <term><command>show [ID...]</command></term>
 219
 220                                 <listitem><para>Show properties of one
 221                                 or more registered virtual machines or
 222                                 containers or the manager itself. If
 223                                 no argument is specified, properties
 224                                 of the manager will be shown. If an
 225                                 ID is specified, properties of this
 226                                 virtual machine or container are
 227                                 shown. By default, empty properties
 228                                 are suppressed. Use
 229                                 <option>--all</option> to show those
 230                                 too. To select specific properties to
 231                                 show, use
 232                                 <option>--property=</option>. This
 233                                 command is intended to be used
 234                                 whenever computer-parsable output is
 235                                 required. Use
 236                                 <command>status</command> if you are
 237                                 looking for formatted human-readable
 238                                 output.</para></listitem>
 239                         </varlistentry>
 240
 241                         <varlistentry>
 242                                 <term><command>terminate [ID...]</command></term>
 243
 244                                 <listitem><para>Terminates a virtual
 245                                 machine or container. This kills all
 246                                 processes of the virtual machine or
 247                                 container and deallocates all
 248                                 resources attached to that
 249                                 instance.</para></listitem>
 250                         </varlistentry>
 251
 252                         <varlistentry>
 253                                 <term><command>kill [ID...]</command></term>
 254
 255                                 <listitem><para>Send a signal to one
 256                                 or more processes of the virtual
 257                                 machine or container. This means
 258                                 processes as seen by the host, not the
 259                                 processes inside the virtual machine
 260                                 or container.
 261                                 Use <option>--kill-who=</option> to
 262                                 select which process to kill. Use
 263                                 <option>--signal=</option> to select
 264                                 the signal to send.</para></listitem>
 265                         </varlistentry>
 266
 267                         <varlistentry>
 268                                 <term><command>login [ID]</command></term>
 269
 270                                 <listitem><para>Open a terminal login
 271                                 session to a container. This will
 272                                 create a TTY connection to a specific
 273                                 container and asks for the execution of a
 274                                 getty on it. Note that this is only
 275                                 supported for containers running
 276                                 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 277                                 as init system.</para></listitem>
 278                         </varlistentry>
 279                 </variablelist>
 280
 281         </refsect1>
 282
 283         <refsect1>
 284                 <title>Exit status</title>
 285
 286                 <para>On success, 0 is returned, a non-zero failure
 287                 code otherwise.</para>
 288         </refsect1>
 289
 290         <refsect1>
 291                 <title>Environment</title>
 292
 293                 <variablelist class='environment-variables'>
 294                         <varlistentry>
 295                                 <term><varname>$SYSTEMD_PAGER</varname></term>
 296                                 <listitem><para>Pager to use when
 297                                 <option>--no-pager</option> is not given;
 298                                 overrides <varname>$PAGER</varname>.  Setting
 299                                 this to an empty string or the value
 300                                 <literal>cat</literal> is equivalent to passing
 301                                 <option>--no-pager</option>.</para></listitem>
 302                         </varlistentry>
 303                 </variablelist>
 304         </refsect1>
 305
 306         <refsect1>
 307                 <title>See Also</title>
 308                 <para>
 309                         <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 310                         <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 311                         <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 312                 </para>
 313         </refsect1>
 314
 315 </refentry>