systemd/man/machinectl.xml

367 lines
18 KiB
XML

<?xml version='1.0'?> <!--*-nxml-*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!--
This file is part of systemd.
Copyright 2013 Zbigniew Jędrzejewski-Szmek
systemd is free software; you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation; either version 2.1 of the License, or
(at your option) any later version.
systemd is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License
along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->
<refentry id="machinectl" conditional='ENABLE_MACHINED'
xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>machinectl</title>
<productname>systemd</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Lennart</firstname>
<surname>Poettering</surname>
<email>lennart@poettering.net</email>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>machinectl</refentrytitle>
<manvolnum>1</manvolnum>
</refmeta>
<refnamediv>
<refname>machinectl</refname>
<refpurpose>Control the systemd machine manager</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>machinectl</command>
<arg choice="opt" rep="repeat">OPTIONS</arg>
<arg choice="req">COMMAND</arg>
<arg choice="opt" rep="repeat">NAME</arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para><command>machinectl</command> may be used to
introspect and control the state of the
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
virtual machine and container registration manager <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
</refsect1>
<refsect1>
<title>Options</title>
<para>The following options are understood:</para>
<variablelist>
<varlistentry>
<term><option>-p</option></term>
<term><option>--property=</option></term>
<listitem><para>When showing
machine properties, limit the
output to certain properties as
specified by the argument. If not
specified, all set properties are
shown. The argument should be a
property name, such as
<literal>Name</literal>. If
specified more than once, all
properties with the specified names
are shown.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-a</option></term>
<term><option>--all</option></term>
<listitem><para>When showing
machine properties, show all
properties regardless of whether they are
set or not.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-l</option></term>
<term><option>--full</option></term>
<listitem><para>Do not ellipsize
process tree entries.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--kill-who=</option></term>
<listitem><para>When used with
<command>kill</command>,
choose which processes to kill. Must
be one of <option>leader</option>, or
<option>all</option> to select whether
to kill only the leader process of the
machine or all processes of the
machine. If omitted, defaults to
<option>all</option>.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-s</option></term>
<term><option>--signal=</option></term>
<listitem><para>When used with
<command>kill</command>, choose
which signal to send to selected
processes. Must be one of the
well-known signal specifiers, such as
<constant>SIGTERM</constant>,
<constant>SIGINT</constant> or
<constant>SIGSTOP</constant>. If
omitted, defaults to
<constant>SIGTERM</constant>.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--no-legend</option></term>
<listitem><para>Do not print the legend,
i.e. the column headers and the
footer.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--mkdir</option></term>
<listitem><para>When used with
<command>bind</command> creates the
destination directory before applying
the bind mount.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--read-only</option></term>
<listitem><para>When used with
<command>bind</command> applies a
read-only bind
mount.</para></listitem>
</varlistentry>
<xi:include href="user-system-options.xml" xpointer="host" />
<xi:include href="user-system-options.xml" xpointer="machine" />
<xi:include href="standard-options.xml" xpointer="help" />
<xi:include href="standard-options.xml" xpointer="version" />
<xi:include href="standard-options.xml" xpointer="no-pager" />
</variablelist>
<para>The following commands are understood:</para>
<variablelist>
<varlistentry>
<term><command>list</command></term>
<listitem><para>List currently running
virtual machines and containers.
</para></listitem>
</varlistentry>
<varlistentry>
<term><command>status</command> <replaceable>NAME</replaceable>...</term>
<listitem><para>Show terse runtime
status information about one or more
virtual machines and containers. This
function is intended to generate
human-readable output. If you are
looking for computer-parsable output,
use <command>show</command> instead.
</para></listitem>
</varlistentry>
<varlistentry>
<term><command>show</command> <replaceable>NAME</replaceable>...</term>
<listitem><para>Show properties of one
or more registered virtual machines or
containers or the manager itself. If
no argument is specified, properties
of the manager will be shown. If an
NAME is specified, properties of this
virtual machine or container are
shown. By default, empty properties
are suppressed. Use
<option>--all</option> to show those
too. To select specific properties to
show, use
<option>--property=</option>. This
command is intended to be used
whenever computer-parsable output is
required. Use
<command>status</command> if you are
looking for formatted human-readable
output.</para></listitem>
</varlistentry>
<varlistentry>
<term><command>login</command> <replaceable>NAME</replaceable></term>
<listitem><para>Open a terminal login
session to a container. This will
create a TTY connection to a specific
container and asks for the execution of a
getty on it. Note that this is only
supported for containers running
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
as init system.</para></listitem>
</varlistentry>
<varlistentry>
<term><command>reboot</command> <replaceable>NAME</replaceable>...</term>
<listitem><para>Reboot one or more
containers. This will trigger a reboot
by sending SIGINT to the container's
init process, which is roughly
equivalent to pressing Ctrl+Alt+Del on
a non-containerized system, and is
compatible with containers running any
init system.</para></listitem>
</varlistentry>
<varlistentry>
<term><command>poweroff</command> <replaceable>NAME</replaceable>...</term>
<listitem><para>Power off one or more
containers. This will trigger a reboot
by sending SIGRTMIN+4 to the
container's init process, which causes
systemd-compatible init systems to
shut down cleanly. This operation does
not work on containers that do not run
a
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>-compatible
init system, such as
sysvinit.</para></listitem>
</varlistentry>
<varlistentry>
<term><command>kill</command> <replaceable>NAME</replaceable>...</term>
<listitem><para>Send a signal to one
or more processes of the virtual
machine or container. This means
processes as seen by the host, not the
processes inside the virtual machine
or container.
Use <option>--kill-who=</option> to
select which process to kill. Use
<option>--signal=</option> to select
the signal to send.</para></listitem>
</varlistentry>
<varlistentry>
<term><command>terminate</command> <replaceable>NAME</replaceable>...</term>
<listitem><para>Terminates a virtual
machine or container. This kills all
processes of the virtual machine or
container and deallocates all
resources attached to that
instance.</para></listitem>
</varlistentry>
<varlistentry>
<term><command>bind</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term>
<listitem><para>Bind mounts a
directory from the host into the
specified container. The first
directory argument is the source
directory on the host, the second
directory argument the source
directory on the host. When the latter
is omitted the destination path in the
container is the same as the source
path on the host. When combined with
the <option>--read-only</option>
switch a ready-only bind mount is
created. When combined with the
<option>--mkdir</option> switch the
destination path is first created
before the mount is applied. Note that
this option is currently only
supported for
<citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
containers.</para></listitem>
</varlistentry>
<varlistentry>
<term><command>copy-to</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term>
<listitem><para>Copies files or
directories from the host system into
a running container. Takes a container
name, followed by the source path on
the host and the destination path in
the container. If the destination path
is omitted the same as the source path
is used.</para></listitem>
</varlistentry>
<varlistentry>
<term><command>copy-from</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term>
<listitem><para>Copies files or
directories from a container into the
host system. Takes a container name,
followed by the source path in the
container the destination path on the
host. If the destination path is
omitted the same as the source path is
used.</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Exit status</title>
<para>On success, 0 is returned, a non-zero failure
code otherwise.</para>
</refsect1>
<xi:include href="less-variables.xml" />
<refsect1>
<title>See Also</title>
<para>
<citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>
</para>
</refsect1>
</refentry>