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