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>--no-ask-password</option></term>
 113
 114                                 <listitem><para>Do not query the user
 115                                 for authentication for privileged
 116                                 operations.</para></listitem>
 117                         </varlistentry>
 118
 119                         <varlistentry>
 120                                 <term><option>--kill-who=</option></term>
 121
 122                                 <listitem><para>When used with
 123                                 <command>kill</command>,
 124                                 choose which processes to kill. Must
 125                                 be one of <option>leader</option>, or
 126                                 <option>all</option> to select whether
 127                                 to kill only the leader process of the
 128                                 machine or all processes of the
 129                                 machine. If omitted, defaults to
 130                                 <option>all</option>.</para></listitem>
 131                         </varlistentry>
 132
 133                         <varlistentry>
 134                                 <term><option>-s</option></term>
 135                                 <term><option>--signal=</option></term>
 136
 137                                 <listitem><para>When used with
 138                                 <command>kill</command>, choose
 139                                 which signal to send to selected
 140                                 processes. Must be one of the
 141                                 well-known signal specifiers, such as
 142                                 <constant>SIGTERM</constant>,
 143                                 <constant>SIGINT</constant> or
 144                                 <constant>SIGSTOP</constant>. If
 145                                 omitted, defaults to
 146                                 <constant>SIGTERM</constant>.</para></listitem>
 147                         </varlistentry>
 148
 149                         <varlistentry>
 150                                 <term><option>--no-legend</option></term>
 151
 152                                 <listitem><para>Do not print the legend,
 153                                         i.e. the column headers and the
 154                                         footer.</para></listitem>
 155                         </varlistentry>
 156
 157                         <varlistentry>
 158                                 <term><option>--mkdir</option></term>
 159
 160                                 <listitem><para>When used with
 161                                 <command>bind</command> creates the
 162                                 destination directory before applying
 163                                 the bind mount.</para></listitem>
 164                         </varlistentry>
 165
 166
 167                         <varlistentry>
 168                                 <term><option>--read-only</option></term>
 169
 170                                 <listitem><para>When used with
 171                                 <command>bind</command> applies a
 172                                 read-only bind
 173                                 mount.</para></listitem>
 174                         </varlistentry>
 175
 176
 177                         <varlistentry>
 178                                 <term><option>-n</option></term>
 179                                 <term><option>--lines=</option></term>
 180
 181                                 <listitem><para>When used with
 182                                 <command>status</command>, controls
 183                                 the number of journal lines to show,
 184                                 counting from the most recent
 185                                 ones. Takes a positive integer
 186                                 argument. Defaults to 10.</para>
 187                                 </listitem>
 188                         </varlistentry>
 189
 190                         <varlistentry>
 191                                 <term><option>-o</option></term>
 192                                 <term><option>--output=</option></term>
 193
 194                                 <listitem><para>When used with
 195                                 <command>status</command>, controls
 196                                 the formatting of the journal entries
 197                                 that are shown. For the available
 198                                 choices, see
 199                                 <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 200                                 Defaults to
 201                                 <literal>short</literal>.</para></listitem>
 202                         </varlistentry>
 203
 204                         <xi:include href="user-system-options.xml" xpointer="host" />
 205                         <xi:include href="user-system-options.xml" xpointer="machine" />
 206
 207                         <xi:include href="standard-options.xml" xpointer="help" />
 208                         <xi:include href="standard-options.xml" xpointer="version" />
 209                         <xi:include href="standard-options.xml" xpointer="no-pager" />
 210                 </variablelist>
 211
 212                 <para>The following commands are understood:</para>
 213
 214                 <variablelist>
 215                         <varlistentry>
 216                                 <term><command>list</command></term>
 217
 218                                 <listitem><para>List currently running
 219                                 virtual machines and containers.
 220                                 </para></listitem>
 221                         </varlistentry>
 222
 223                         <varlistentry>
 224                                 <term><command>status</command> <replaceable>NAME</replaceable>...</term>
 225
 226                                 <listitem><para>Show terse runtime
 227                                 status information about one or more
 228                                 virtual machines and containers,
 229                                 followed by the most recent log data
 230                                 from the journal. This function is
 231                                 intended to generate human-readable
 232                                 output. If you are looking for
 233                                 computer-parsable output, use
 234                                 <command>show</command> instead. Note
 235                                 that the log data shown is reported by
 236                                 the virtual machine or container
 237                                 manager, and frequently contains
 238                                 console output of the machine, but not
 239                                 necessarily journal contents of the
 240                                 machine itself.</para></listitem>
 241                         </varlistentry>
 242
 243                         <varlistentry>
 244                                 <term><command>show</command> <replaceable>NAME</replaceable>...</term>
 245
 246                                 <listitem><para>Show properties of one
 247                                 or more registered virtual machines or
 248                                 containers or the manager itself. If
 249                                 no argument is specified, properties
 250                                 of the manager will be shown. If an
 251                                 NAME is specified, properties of this
 252                                 virtual machine or container are
 253                                 shown. By default, empty properties
 254                                 are suppressed. Use
 255                                 <option>--all</option> to show those
 256                                 too. To select specific properties to
 257                                 show, use
 258                                 <option>--property=</option>. This
 259                                 command is intended to be used
 260                                 whenever computer-parsable output is
 261                                 required. Use
 262                                 <command>status</command> if you are
 263                                 looking for formatted human-readable
 264                                 output.</para></listitem>
 265                         </varlistentry>
 266
 267                         <varlistentry>
 268                                 <term><command>login</command> <replaceable>NAME</replaceable></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
 280                         <varlistentry>
 281                                 <term><command>reboot</command> <replaceable>NAME</replaceable>...</term>
 282
 283                                 <listitem><para>Reboot one or more
 284                                 containers. This will trigger a reboot
 285                                 by sending SIGINT to the container's
 286                                 init process, which is roughly
 287                                 equivalent to pressing Ctrl+Alt+Del on
 288                                 a non-containerized system, and is
 289                                 compatible with containers running any
 290                                 init system.</para></listitem>
 291                         </varlistentry>
 292
 293                         <varlistentry>
 294                                 <term><command>poweroff</command> <replaceable>NAME</replaceable>...</term>
 295
 296                                 <listitem><para>Power off one or more
 297                                 containers. This will trigger a reboot
 298                                 by sending SIGRTMIN+4 to the
 299                                 container's init process, which causes
 300                                 systemd-compatible init systems to
 301                                 shut down cleanly. This operation does
 302                                 not work on containers that do not run
 303                                 a
 304                                 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>-compatible
 305                                 init system, such as
 306                                 sysvinit.</para></listitem>
 307                         </varlistentry>
 308
 309                         <varlistentry>
 310                                 <term><command>kill</command> <replaceable>NAME</replaceable>...</term>
 311
 312                                 <listitem><para>Send a signal to one
 313                                 or more processes of the virtual
 314                                 machine or container. This means
 315                                 processes as seen by the host, not the
 316                                 processes inside the virtual machine
 317                                 or container.
 318                                 Use <option>--kill-who=</option> to
 319                                 select which process to kill. Use
 320                                 <option>--signal=</option> to select
 321                                 the signal to send.</para></listitem>
 322                         </varlistentry>
 323
 324                         <varlistentry>
 325                                 <term><command>terminate</command> <replaceable>NAME</replaceable>...</term>
 326
 327                                 <listitem><para>Terminates a virtual
 328                                 machine or container. This kills all
 329                                 processes of the virtual machine or
 330                                 container and deallocates all
 331                                 resources attached to that
 332                                 instance.</para></listitem>
 333                         </varlistentry>
 334
 335                         <varlistentry>
 336                                 <term><command>bind</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term>
 337
 338                                 <listitem><para>Bind mounts a
 339                                 directory from the host into the
 340                                 specified container. The first
 341                                 directory argument is the source
 342                                 directory on the host, the second
 343                                 directory argument the source
 344                                 directory on the host. When the latter
 345                                 is omitted the destination path in the
 346                                 container is the same as the source
 347                                 path on the host. When combined with
 348                                 the <option>--read-only</option>
 349                                 switch a ready-only bind mount is
 350                                 created. When combined with the
 351                                 <option>--mkdir</option> switch the
 352                                 destination path is first created
 353                                 before the mount is applied. Note that
 354                                 this option is currently only
 355                                 supported for
 356                                 <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 357                                 containers.</para></listitem>
 358                         </varlistentry>
 359
 360                         <varlistentry>
 361                                 <term><command>copy-to</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term>
 362
 363                                 <listitem><para>Copies files or
 364                                 directories from the host system into
 365                                 a running container. Takes a container
 366                                 name, followed by the source path on
 367                                 the host and the destination path in
 368                                 the container. If the destination path
 369                                 is omitted the same as the source path
 370                                 is used.</para></listitem>
 371                         </varlistentry>
 372
 373
 374                         <varlistentry>
 375                                 <term><command>copy-from</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term>
 376
 377                                 <listitem><para>Copies files or
 378                                 directories from a container into the
 379                                 host system. Takes a container name,
 380                                 followed by the source path in the
 381                                 container the destination path on the
 382                                 host. If the destination path is
 383                                 omitted the same as the source path is
 384                                 used.</para></listitem>
 385                         </varlistentry>
 386
 387                 </variablelist>
 388
 389         </refsect1>
 390
 391         <refsect1>
 392                 <title>Exit status</title>
 393
 394                 <para>On success, 0 is returned, a non-zero failure
 395                 code otherwise.</para>
 396         </refsect1>
 397
 398         <xi:include href="less-variables.xml" />
 399
 400         <refsect1>
 401                 <title>See Also</title>
 402                 <para>
 403                         <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 404                         <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 405                         <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 406                 </para>
 407         </refsect1>
 408
 409 </refentry>