<?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">

<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>

<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>

<listitem><para>Execute the operation

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>

<listitem><para>Execute the operation on a

local container. Specify a container

name to connect to.</para></listitem>

</varlistentry>

<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-machine</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-machine</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>

</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>ID</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>ID</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

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>

<term><command>terminate</command> <replaceable>ID</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>kill</command> <replaceable>ID</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>reboot</command> <replaceable>ID</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.</para></listitem>

</varlistentry>

<varlistentry>

<term><command>login</command> <replaceable>ID</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>

</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>,

<citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>,

<citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>

</para>

</refsect1>

</refentry>