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>-p</option></term>
  77                                 <term><option>--property=</option></term>
  78
  79                                 <listitem><para>When showing
  80                                 machine properties, limit the
  81                                 output to certain properties as
  82                                 specified by the argument. If not
  83                                 specified, all set properties are
  84                                 shown. The argument should be a
  85                                 property name, such as
  86                                 <literal>Name</literal>. If
  87                                 specified more than once, all
  88                                 properties with the specified names
  89                                 are shown.</para></listitem>
  90                         </varlistentry>
  91
  92                         <varlistentry>
  93                                 <term><option>-a</option></term>
  94                                 <term><option>--all</option></term>
  95
  96                                 <listitem><para>When showing
  97                                 machine properties, show all
  98                                 properties regardless of whether they are
  99                                 set or not.</para></listitem>
 100                         </varlistentry>
 101
 102                         <varlistentry>
 103                                 <term><option>-l</option></term>
 104                                 <term><option>--full</option></term>
 105
 106                                 <listitem><para>Do not ellipsize
 107                                 process tree entries.</para>
 108                                 </listitem>
 109                         </varlistentry>
 110
 111                         <varlistentry>
 112                                 <term><option>--kill-who=</option></term>
 113
 114                                 <listitem><para>When used with
 115                                 <command>kill</command>,
 116                                 choose which processes to kill. Must
 117                                 be one of <option>leader</option>, or
 118                                 <option>all</option> to select whether
 119                                 to kill only the leader process of the
 120                                 machine or all processes of the
 121                                 machine. If omitted, defaults to
 122                                 <option>all</option>.</para></listitem>
 123                         </varlistentry>
 124
 125                         <varlistentry>
 126                                 <term><option>-s</option></term>
 127                                 <term><option>--signal=</option></term>
 128
 129                                 <listitem><para>When used with
 130                                 <command>kill</command>, choose
 131                                 which signal to send to selected
 132                                 processes. Must be one of the
 133                                 well-known signal specifiers, such as
 134                                 <constant>SIGTERM</constant>,
 135                                 <constant>SIGINT</constant> or
 136                                 <constant>SIGSTOP</constant>. If
 137                                 omitted, defaults to
 138                                 <constant>SIGTERM</constant>.</para></listitem>
 139                         </varlistentry>
 140
 141                         <varlistentry>
 142                                 <term><option>--no-legend</option></term>
 143
 144                                 <listitem><para>Do not print the legend,
 145                                         i.e. the column headers and the
 146                                         footer.</para></listitem>
 147                         </varlistentry>
 148
 149                         <varlistentry>
 150                                 <term><option>--mkdir</option></term>
 151
 152                                 <listitem><para>When used with
 153                                 <command>bind</command> creates the
 154                                 destination directory before applying
 155                                 the bind mount.</para></listitem>
 156                         </varlistentry>
 157
 158
 159                         <varlistentry>
 160                                 <term><option>--read-only</option></term>
 161
 162                                 <listitem><para>When used with
 163                                 <command>bind</command> applies a
 164                                 read-only bind
 165                                 mount.</para></listitem>
 166                         </varlistentry>
 167
 168                         <xi:include href="user-system-options.xml" xpointer="host" />
 169                         <xi:include href="user-system-options.xml" xpointer="machine" />
 170
 171                         <xi:include href="standard-options.xml" xpointer="help" />
 172                         <xi:include href="standard-options.xml" xpointer="version" />
 173                         <xi:include href="standard-options.xml" xpointer="no-pager" />
 174                 </variablelist>
 175
 176                 <para>The following commands are understood:</para>
 177
 178                 <variablelist>
 179                         <varlistentry>
 180                                 <term><command>list</command></term>
 181
 182                                 <listitem><para>List currently running
 183                                 virtual machines and containers.
 184                                 </para></listitem>
 185                         </varlistentry>
 186
 187                         <varlistentry>
 188                                 <term><command>status</command> <replaceable>NAME</replaceable>...</term>
 189
 190                                 <listitem><para>Show terse runtime
 191                                 status information about one or more
 192                                 virtual machines and containers. This
 193                                 function is intended to generate
 194                                 human-readable output. If you are
 195                                 looking for computer-parsable output,
 196                                 use <command>show</command> instead.
 197                                 </para></listitem>
 198                         </varlistentry>
 199
 200                         <varlistentry>
 201                                 <term><command>show</command> <replaceable>NAME</replaceable>...</term>
 202
 203                                 <listitem><para>Show properties of one
 204                                 or more registered virtual machines or
 205                                 containers or the manager itself. If
 206                                 no argument is specified, properties
 207                                 of the manager will be shown. If an
 208                                 NAME is specified, properties of this
 209                                 virtual machine or container are
 210                                 shown. By default, empty properties
 211                                 are suppressed. Use
 212                                 <option>--all</option> to show those
 213                                 too. To select specific properties to
 214                                 show, use
 215                                 <option>--property=</option>. This
 216                                 command is intended to be used
 217                                 whenever computer-parsable output is
 218                                 required. Use
 219                                 <command>status</command> if you are
 220                                 looking for formatted human-readable
 221                                 output.</para></listitem>
 222                         </varlistentry>
 223
 224                         <varlistentry>
 225                                 <term><command>login</command> <replaceable>NAME</replaceable></term>
 226
 227                                 <listitem><para>Open a terminal login
 228                                 session to a container. This will
 229                                 create a TTY connection to a specific
 230                                 container and asks for the execution of a
 231                                 getty on it. Note that this is only
 232                                 supported for containers running
 233                                 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 234                                 as init system.</para></listitem>
 235                         </varlistentry>
 236
 237                         <varlistentry>
 238                                 <term><command>reboot</command> <replaceable>NAME</replaceable>...</term>
 239
 240                                 <listitem><para>Reboot one or more
 241                                 containers. This will trigger a reboot
 242                                 by sending SIGINT to the container's
 243                                 init process, which is roughly
 244                                 equivalent to pressing Ctrl+Alt+Del on
 245                                 a non-containerized system, and is
 246                                 compatible with containers running any
 247                                 init system.</para></listitem>
 248                         </varlistentry>
 249
 250                         <varlistentry>
 251                                 <term><command>poweroff</command> <replaceable>NAME</replaceable>...</term>
 252
 253                                 <listitem><para>Power off one or more
 254                                 containers. This will trigger a reboot
 255                                 by sending SIGRTMIN+4 to the
 256                                 container's init process, which causes
 257                                 systemd-compatible init systems to
 258                                 shut down cleanly. This operation does
 259                                 not work on containers that do not run
 260                                 a
 261                                 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>-compatible
 262                                 init system, such as
 263                                 sysvinit.</para></listitem>
 264                         </varlistentry>
 265
 266                         <varlistentry>
 267                                 <term><command>kill</command> <replaceable>NAME</replaceable>...</term>
 268
 269                                 <listitem><para>Send a signal to one
 270                                 or more processes of the virtual
 271                                 machine or container. This means
 272                                 processes as seen by the host, not the
 273                                 processes inside the virtual machine
 274                                 or container.
 275                                 Use <option>--kill-who=</option> to
 276                                 select which process to kill. Use
 277                                 <option>--signal=</option> to select
 278                                 the signal to send.</para></listitem>
 279                         </varlistentry>
 280
 281                         <varlistentry>
 282                                 <term><command>terminate</command> <replaceable>NAME</replaceable>...</term>
 283
 284                                 <listitem><para>Terminates a virtual
 285                                 machine or container. This kills all
 286                                 processes of the virtual machine or
 287                                 container and deallocates all
 288                                 resources attached to that
 289                                 instance.</para></listitem>
 290                         </varlistentry>
 291
 292                         <varlistentry>
 293                                 <term><command>bind</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term>
 294
 295                                 <listitem><para>Bind mounts a
 296                                 directory from the host into the
 297                                 specified container. The first
 298                                 directory argument is the source
 299                                 directory on the host, the second
 300                                 directory argument the source
 301                                 directory on the host. When the latter
 302                                 is omitted the destination path in the
 303                                 container is the same as the source
 304                                 path on the host. When combined with
 305                                 the <option>--read-only</option>
 306                                 switch a ready-only bind mount is
 307                                 created. When combined with the
 308                                 <option>--mkdir</option> switch the
 309                                 destination path is first created
 310                                 before the mount is applied. Note that
 311                                 this option is currently only
 312                                 supported for
 313                                 <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 314                                 containers.</para></listitem>
 315                         </varlistentry>
 316
 317                         <varlistentry>
 318                                 <term><command>copy-to</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term>
 319
 320                                 <listitem><para>Copies files or
 321                                 directories from the host system into
 322                                 a running container. Takes a container
 323                                 name, followed by the source path on
 324                                 the host and the destination path in
 325                                 the container. If the destination path
 326                                 is omitted the same as the source path
 327                                 is used.</para></listitem>
 328                         </varlistentry>
 329
 330
 331                         <varlistentry>
 332                                 <term><command>copy-from</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term>
 333
 334                                 <listitem><para>Copies files or
 335                                 directories from a container into the
 336                                 host system. Takes a container name,
 337                                 followed by the source path in the
 338                                 container the destination path on the
 339                                 host. If the destination path is
 340                                 omitted the same as the source path is
 341                                 used.</para></listitem>
 342                         </varlistentry>
 343
 344                 </variablelist>
 345
 346         </refsect1>
 347
 348         <refsect1>
 349                 <title>Exit status</title>
 350
 351                 <para>On success, 0 is returned, a non-zero failure
 352                 code otherwise.</para>
 353         </refsect1>
 354
 355         <xi:include href="less-variables.xml" />
 356
 357         <refsect1>
 358                 <title>See Also</title>
 359                 <para>
 360                         <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 361                         <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 362                         <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 363                 </para>
 364         </refsect1>
 365
 366 </refentry>