[thirdparty/systemd.git] / 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>

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

                        <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, and is
                                compatible with containers running any
                                init system.</para></listitem>
                        </varlistentry>

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

                </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>
Commit	Line	Data
19887cd0 ZJS	1	<?xml version='1.0'?> <!---nxml--->
	2	<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
	3	"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
	4
	5	<!--
	6	This file is part of systemd.
	7
	8	Copyright 2013 Zbigniew Jędrzejewski-Szmek
	9
	10	systemd is free software; you can redistribute it and/or modify it
	11	under the terms of the GNU Lesser General Public License as published by
	12	the Free Software Foundation; either version 2.1 of the License, or
	13	(at your option) any later version.
	14
	15	systemd is distributed in the hope that it will be useful, but
	16	WITHOUT ANY WARRANTY; without even the implied warranty of
	17	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
	18	Lesser General Public License for more details.
	19
	20	You should have received a copy of the GNU Lesser General Public License
	21	along with systemd; If not, see <http://www.gnu.org/licenses/>.
	22	-->
	23
21ac6ff1 ZJS	24	<refentry id="machinectl" conditional='ENABLE_MACHINED'
21ac6ff1 ZJS	25	xmlns:xi="http://www.w3.org/2001/XInclude">
19887cd0 ZJS	26
	27	<refentryinfo>
	28	<title>machinectl</title>
	29	<productname>systemd</productname>
	30
	31	<authorgroup>
	32	<author>
	33	<contrib>Developer</contrib>
	34	<firstname>Lennart</firstname>
	35	<surname>Poettering</surname>
	36	<email>lennart@poettering.net</email>
	37	</author>
	38	</authorgroup>
	39	</refentryinfo>
	40
	41	<refmeta>
	42	<refentrytitle>machinectl</refentrytitle>
	43	<manvolnum>1</manvolnum>
	44	</refmeta>
	45
	46	<refnamediv>
	47	<refname>machinectl</refname>
	48	<refpurpose>Control the systemd machine manager</refpurpose>
	49	</refnamediv>
	50
	51	<refsynopsisdiv>
	52	<cmdsynopsis>
	53	<command>machinectl</command>
	54	<arg choice="opt" rep="repeat">OPTIONS</arg>
	55	<arg choice="req">COMMAND</arg>
	56	<arg choice="opt" rep="repeat">NAME</arg>
	57	</cmdsynopsis>
	58	</refsynopsisdiv>
	59
	60	<refsect1>
	61	<title>Description</title>
	62
	63	<para><command>machinectl</command> may be used to
	64	introspect and control the state of the
	65	<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
	66	virtual machine and container registration manager <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
	67	</refsect1>
	68
	69	<refsect1>
	70	<title>Options</title>
	71
	72	<para>The following options are understood:</para>
	73
	74	<variablelist>
19887cd0 ZJS	75	<varlistentry>
	76	<term><option>-p</option></term>
	77	<term><option>--property=</option></term>
	78
	79	<listitem><para>When showing
f7f74d8e	80	machine properties, limit the
7b870f60 JE	81	output to certain properties as
7b870f60 JE	82	specified by the argument. If not
19887cd0 ZJS	83	specified, all set properties are
	84	shown. The argument should be a
	85	property name, such as
	86	<literal>Name</literal>. If
	87	specified more than once, all
	88	properties with the specified names
	89	are shown.</para></listitem>
	90	</varlistentry>
	91
	92	<varlistentry>
	93	<term><option>-a</option></term>
	94	<term><option>--all</option></term>
	95
	96	<listitem><para>When showing
f7f74d8e	97	machine properties, show all
7b870f60	98	properties regardless of whether they are
19887cd0 ZJS	99	set or not.</para></listitem>
	100	</varlistentry>
	101
	102	<varlistentry>
	103	<term><option>-l</option></term>
	104	<term><option>--full</option></term>
	105
3fde5f30 LP	106	<listitem><para>Do not ellipsize
3fde5f30 LP	107	process tree entries.</para>
19887cd0 ZJS	108	</listitem>
	109	</varlistentry>
	110
19887cd0 ZJS	111	<varlistentry>
	112	<term><option>--kill-who=</option></term>
	113
	114	<listitem><para>When used with
773e264d	115	<command>kill</command>,
19887cd0 ZJS	116	choose which processes to kill. Must
	117	be one of <option>leader</option>, or
	118	<option>all</option> to select whether
	119	to kill only the leader process of the
f7f74d8e LP	120	machine or all processes of the
f7f74d8e LP	121	machine. If omitted, defaults to
19887cd0 ZJS	122	<option>all</option>.</para></listitem>
	123	</varlistentry>
	124
	125	<varlistentry>
	126	<term><option>-s</option></term>
	127	<term><option>--signal=</option></term>
	128
	129	<listitem><para>When used with
773e264d	130	<command>kill</command>, choose
19887cd0	131	which signal to send to selected
f7f74d8e LP	132	processes. Must be one of the
f7f74d8e LP	133	well-known signal specifiers, such as
19887cd0 ZJS	134	<constant>SIGTERM</constant>,
	135	<constant>SIGINT</constant> or
	136	<constant>SIGSTOP</constant>. If
	137	omitted, defaults to
	138	<constant>SIGTERM</constant>.</para></listitem>
	139	</varlistentry>
	140
dfdebb1b ZJS	141	<varlistentry>
	142	<term><option>--no-legend</option></term>
	143
	144	<listitem><para>Do not print the legend,
	145	i.e. the column headers and the
	146	footer.</para></listitem>
	147	</varlistentry>
	148
4f50d2ef ZJS	149	<xi:include href="user-system-options.xml" xpointer="host" />
	150	<xi:include href="user-system-options.xml" xpointer="machine" />
	151
dfdebb1b ZJS	152	<xi:include href="standard-options.xml" xpointer="help" />
	153	<xi:include href="standard-options.xml" xpointer="version" />
	154	<xi:include href="standard-options.xml" xpointer="no-pager" />
19887cd0 ZJS	155	</variablelist>
	156
	157	<para>The following commands are understood:</para>
	158
	159	<variablelist>
	160	<varlistentry>
	161	<term><command>list</command></term>
	162
	163	<listitem><para>List currently running
	164	virtual machines and containers.
	165	</para></listitem>
	166	</varlistentry>
	167
	168	<varlistentry>
4f8f66cb	169	<term><command>status</command> <replaceable>ID</replaceable>...</term>
19887cd0 ZJS	170
	171	<listitem><para>Show terse runtime
	172	status information about one or more
	173	virtual machines and containers. This
	174	function is intended to generate
	175	human-readable output. If you are
	176	looking for computer-parsable output,
	177	use <command>show</command> instead.
	178	</para></listitem>
	179	</varlistentry>
	180
	181	<varlistentry>
4f8f66cb	182	<term><command>show</command> <replaceable>ID</replaceable>...</term>
19887cd0 ZJS	183
	184	<listitem><para>Show properties of one
	185	or more registered virtual machines or
	186	containers or the manager itself. If
	187	no argument is specified, properties
7b870f60	188	of the manager will be shown. If an
19887cd0 ZJS	189	ID is specified, properties of this
	190	virtual machine or container are
	191	shown. By default, empty properties
	192	are suppressed. Use
	193	<option>--all</option> to show those
	194	too. To select specific properties to
	195	show, use
	196	<option>--property=</option>. This
	197	command is intended to be used
	198	whenever computer-parsable output is
	199	required. Use
	200	<command>status</command> if you are
	201	looking for formatted human-readable
	202	output.</para></listitem>
	203	</varlistentry>
	204
	205	<varlistentry>
1dba654b	206	<term><command>login</command> <replaceable>ID</replaceable></term>
19887cd0	207
1dba654b LP	208	<listitem><para>Open a terminal login
	209	session to a container. This will
	210	create a TTY connection to a specific
	211	container and asks for the execution of a
	212	getty on it. Note that this is only
	213	supported for containers running
	214	<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
	215	as init system.</para></listitem>
	216	</varlistentry>
	217
	218	<varlistentry>
	219	<term><command>reboot</command> <replaceable>ID</replaceable>...</term>
	220
	221	<listitem><para>Reboot one or more
	222	containers. This will trigger a reboot
	223	by sending SIGINT to the container's
	224	init process, which is roughly
	225	equivalent to pressing Ctrl+Alt+Del on
	226	a non-containerized system, and is
	227	compatible with containers running any
	228	init system.</para></listitem>
	229	</varlistentry>
	230
	231	<varlistentry>
	232	<term><command>poweroff</command> <replaceable>ID</replaceable>...</term>
	233
	234	<listitem><para>Power off one or more
	235	containers. This will trigger a reboot
	236	by sending SIGRTMIN+4 to the
	237	container's init process, which causes
	238	systemd-compatible init systems to
	239	shut down cleanly. This operation does
	240	not work on containers that do not run
	241	a
	242	<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>-compatible
	243	init system, such as
	244	sysvinit.</para></listitem>
19887cd0 ZJS	245	</varlistentry>
	246
	247	<varlistentry>
4f8f66cb	248	<term><command>kill</command> <replaceable>ID</replaceable>...</term>
19887cd0 ZJS	249
	250	<listitem><para>Send a signal to one
	251	or more processes of the virtual
	252	machine or container. This means
	253	processes as seen by the host, not the
	254	processes inside the virtual machine
	255	or container.
	256	Use <option>--kill-who=</option> to
	257	select which process to kill. Use
	258	<option>--signal=</option> to select
	259	the signal to send.</para></listitem>
	260	</varlistentry>
04d39279 LP	261
04d39279 LP	262	<varlistentry>
1dba654b	263	<term><command>terminate</command> <replaceable>ID</replaceable>...</term>
923d8fd3	264
1dba654b LP	265	<listitem><para>Terminates a virtual
	266	machine or container. This kills all
	267	processes of the virtual machine or
	268	container and deallocates all
	269	resources attached to that
	270	instance.</para></listitem>
923d8fd3 LP	271	</varlistentry>
923d8fd3 LP	272
19887cd0 ZJS	273	</variablelist>
	274
	275	</refsect1>
	276
	277	<refsect1>
	278	<title>Exit status</title>
	279
	280	<para>On success, 0 is returned, a non-zero failure
	281	code otherwise.</para>
	282	</refsect1>
	283
21ac6ff1	284	<xi:include href="less-variables.xml" />
19887cd0 ZJS	285
	286	<refsect1>
	287	<title>See Also</title>
	288	<para>
	289	<citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
a7893c6b LP	290	<citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
a7893c6b LP	291	<citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>
19887cd0 ZJS	292	</para>
	293	</refsect1>
	294
	295	</refentry>