path: root/man/machinectl.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>


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