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

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>

<varlistentry>

<term><option>-n</option></term>

<term><option>--lines=</option></term>

<listitem><para>When used with

<command>status</command>, controls

the number of journal lines to show,

counting from the most recent

ones. Takes a positive integer

argument. Defaults to 10.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><option>-o</option></term>

<term><option>--output=</option></term>

<listitem><para>When used with

<command>status</command>, controls

the formatting of the journal entries

that are shown. For the available

choices, see

<citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.

Defaults to

<literal>short</literal>.</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,

followed by the most recent log data

from the journal. This function is

intended to generate human-readable

output. If you are looking for

computer-parsable output, use

<command>show</command> instead. Note

that the log data shown is reported by

the virtual machine or container

manager, and frequently contains

console output of the machine, but not

necessarily journal contents of the

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