2013-07-07 06:22:05 +04:00
<?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: / / w w w . g n u . o r g / l i c e n s e s /> .
-->
<refentry id= "machinectl" conditional= 'ENABLE_MACHINED' >
<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 > -h</option> </term>
<term > <option > --help</option> </term>
<listitem > <para > Prints a short help
text and exits.</para> </listitem>
</varlistentry>
<varlistentry >
<term > <option > --version</option> </term>
<listitem > <para > Prints a short version
string and exits.</para> </listitem>
</varlistentry>
2013-10-30 18:34:50 +04:00
<varlistentry >
<term > <option > --no-pager</option> </term>
<listitem > <para > Do not pipe output into a
pager.</para> </listitem>
</varlistentry>
<varlistentry >
<term > <option > --no-ask-password</option> </term>
<listitem > <para > Do not query the user
for authentication for privileged
operations.</para> </listitem>
</varlistentry>
<varlistentry >
<term > <option > -H</option> </term>
<term > <option > --host=</option> </term>
2013-11-07 04:17:48 +04:00
<listitem > <para > Execute the operation
2013-10-30 18:34:50 +04:00
remotely. Specify a hostname, or
username and hostname separated by <literal > @</literal> ,
to connect to. This will use SSH to
talk to the remote machine manager
instance.</para> </listitem>
</varlistentry>
<varlistentry >
<term > <option > -M</option> </term>
<term > <option > --machine=</option> </term>
2013-11-07 04:17:48 +04:00
<listitem > <para > Execute the operation on a
2013-10-30 18:34:50 +04:00
local container. Specify a container
name to connect to.</para> </listitem>
</varlistentry>
2013-07-07 06:22:05 +04:00
<varlistentry >
<term > <option > -p</option> </term>
<term > <option > --property=</option> </term>
<listitem > <para > When showing
2013-07-19 20:00:21 +04:00
machine properties, limit the
2013-07-08 20:19:02 +04:00
output to certain properties as
specified by the argument. If not
2013-07-07 06:22:05 +04:00
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
2013-07-19 20:00:21 +04:00
machine properties, show all
2013-07-08 20:19:02 +04:00
properties regardless of whether they are
2013-07-07 06:22:05 +04:00
set or not.</para> </listitem>
</varlistentry>
<varlistentry >
<term > <option > -l</option> </term>
<term > <option > --full</option> </term>
2013-09-27 02:05:07 +04:00
<listitem > <para > Do not ellipsize
process tree entries.</para>
2013-07-07 06:22:05 +04:00
</listitem>
</varlistentry>
<varlistentry >
<term > <option > --kill-who=</option> </term>
<listitem > <para > When used with
2013-07-19 20:00:21 +04:00
<command > kill-machine</command> ,
2013-07-07 06:22:05 +04:00
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
2013-07-19 20:00:21 +04:00
machine or all processes of the
machine. If omitted, defaults to
2013-07-07 06:22:05 +04:00
<option > all</option> .</para> </listitem>
</varlistentry>
<varlistentry >
<term > <option > -s</option> </term>
<term > <option > --signal=</option> </term>
<listitem > <para > When used with
2013-07-21 08:53:14 +04:00
<command > kill-machine</command> , choose
2013-07-07 06:22:05 +04:00
which signal to send to selected
2013-07-19 20:00:21 +04:00
processes. Must be one of the
well-known signal specifiers, such as
2013-07-07 06:22:05 +04:00
<constant > SIGTERM</constant> ,
<constant > SIGINT</constant> or
<constant > SIGSTOP</constant> . If
omitted, defaults to
<constant > SIGTERM</constant> .</para> </listitem>
</varlistentry>
</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 >
2013-12-08 17:16:59 +04:00
<term > <command > status</command> <replaceable > ID</replaceable> ...</term>
2013-07-07 06:22:05 +04:00
<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 >
2013-12-08 17:16:59 +04:00
<term > <command > show</command> <replaceable > ID</replaceable> ...</term>
2013-07-07 06:22:05 +04:00
<listitem > <para > Show properties of one
or more registered virtual machines or
containers or the manager itself. If
no argument is specified, properties
2013-07-08 20:19:02 +04:00
of the manager will be shown. If an
2013-07-07 06:22:05 +04:00
ID 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 >
2013-12-08 17:16:59 +04:00
<term > <command > terminate</command> <replaceable > ID</replaceable> ...</term>
2013-07-07 06:22:05 +04:00
<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 >
2013-12-08 17:16:59 +04:00
<term > <command > kill</command> <replaceable > ID</replaceable> ...</term>
2013-07-07 06:22:05 +04:00
<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>
2013-10-31 04:25:44 +04:00
<varlistentry >
2013-12-08 17:16:59 +04:00
<term > <command > login</command> <replaceable > ID</replaceable> ...</term>
2013-10-31 04:25:44 +04:00
<listitem > <para > Open a terminal login
session to a container. This will
create a TTY connection to a specific
2013-11-07 04:17:48 +04:00
container and asks for the execution of a
2013-10-31 04:25:44 +04:00
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>
2013-07-07 06:22:05 +04:00
</variablelist>
</refsect1>
<refsect1 >
<title > Exit status</title>
<para > On success, 0 is returned, a non-zero failure
code otherwise.</para>
</refsect1>
<refsect1 >
<title > Environment</title>
<variablelist class= 'environment-variables' >
<varlistentry >
<term > <varname > $SYSTEMD_PAGER</varname> </term>
<listitem > <para > Pager to use when
<option > --no-pager</option> is not given;
overrides <varname > $PAGER</varname> . Setting
this to an empty string or the value
<literal > cat</literal> is equivalent to passing
<option > --no-pager</option> .</para> </listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 >
<title > See Also</title>
<para >
<citerefentry > <refentrytitle > systemd-machined.service</refentrytitle> <manvolnum > 8</manvolnum> </citerefentry> ,
2013-10-30 18:34:50 +04:00
<citerefentry > <refentrytitle > systemd-nspawn</refentrytitle> <manvolnum > 1</manvolnum> </citerefentry> ,
<citerefentry > <refentrytitle > systemd.special</refentrytitle> <manvolnum > 7</manvolnum> </citerefentry>
2013-07-07 06:22:05 +04:00
</para>
</refsect1>
</refentry>
