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

        <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>-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 cgroup
                                members.</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>--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>

                        <varlistentry>
                                <term><option>-H</option></term>
                                <term><option>--host</option></term>

                                <listitem><para>Execute 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>-P</option></term>
                                <term><option>--privileged</option></term>

                                <listitem><para>Acquire privileges via
                                PolicyKit before executing the
                                operation.</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 [ID...]</command></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 [ID...]</command></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 [ID...]</command></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 [ID...]</command></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>
                </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-logind.service</refentrytitle><manvolnum>8</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
	24	<refentry id="machinectl" conditional='ENABLE_MACHINED'>
	25
	26	<refentryinfo>
	27	<title>machinectl</title>
	28	<productname>systemd</productname>
	29
	30	<authorgroup>
	31	<author>
	32	<contrib>Developer</contrib>
	33	<firstname>Lennart</firstname>
	34	<surname>Poettering</surname>
	35	<email>lennart@poettering.net</email>
	36	</author>
	37	</authorgroup>
	38	</refentryinfo>
	39
	40	<refmeta>
	41	<refentrytitle>machinectl</refentrytitle>
	42	<manvolnum>1</manvolnum>
	43	</refmeta>
	44
	45	<refnamediv>
	46	<refname>machinectl</refname>
	47	<refpurpose>Control the systemd machine manager</refpurpose>
	48	</refnamediv>
	49
	50	<refsynopsisdiv>
	51	<cmdsynopsis>
	52	<command>machinectl</command>
	53	<arg choice="opt" rep="repeat">OPTIONS</arg>
	54	<arg choice="req">COMMAND</arg>
	55	<arg choice="opt" rep="repeat">NAME</arg>
	56	</cmdsynopsis>
	57	</refsynopsisdiv>
	58
	59	<refsect1>
	60	<title>Description</title>
	61
	62	<para><command>machinectl</command> may be used to
	63	introspect and control the state of the
	64	<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
65	virtual machine and container registration manager <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
66	</refsect1>
67
68	<refsect1>
69	<title>Options</title>
70
71	<para>The following options are understood:</para>
72
73	<variablelist>
74	<varlistentry>
75	<term><option>-h</option></term>
76	<term><option>--help</option></term>
77
78	<listitem><para>Prints a short help
79	text and exits.</para></listitem>
80	</varlistentry>
81
82	<varlistentry>
83	<term><option>--version</option></term>
84
85	<listitem><para>Prints a short version
86	string and exits.</para></listitem>
87	</varlistentry>
88
89	<varlistentry>
90	<term><option>-p</option></term>
91	<term><option>--property=</option></term>
92
93	<listitem><para>When showing
f7f74d8e	94	machine properties, limit the
7b870f60 JE	95	output to certain properties as
7b870f60 JE	96	specified by the argument. If not
19887cd0 ZJS	97	specified, all set properties are
	98	shown. The argument should be a
	99	property name, such as
	100	<literal>Name</literal>. If
	101	specified more than once, all
	102	properties with the specified names
	103	are shown.</para></listitem>
	104	</varlistentry>
	105
	106	<varlistentry>
	107	<term><option>-a</option></term>
	108	<term><option>--all</option></term>
	109
	110	<listitem><para>When showing
f7f74d8e	111	machine properties, show all
7b870f60	112	properties regardless of whether they are
19887cd0 ZJS	113	set or not.</para></listitem>
	114	</varlistentry>
	115
	116	<varlistentry>
	117	<term><option>-l</option></term>
	118	<term><option>--full</option></term>
	119
	120	<listitem><para>Do not ellipsize cgroup
	121	members.</para>
	122	</listitem>
	123	</varlistentry>
	124
	125	<varlistentry>
	126	<term><option>--no-pager</option></term>
	127
	128	<listitem><para>Do not pipe output into a
	129	pager.</para></listitem>
	130	</varlistentry>
	131
	132	<varlistentry>
	133	<term><option>--no-ask-password</option></term>
	134
	135	<listitem><para>Do not query the user
	136	for authentication for privileged
	137	operations.</para></listitem>
	138	</varlistentry>
	139
	140	<varlistentry>
	141	<term><option>--kill-who=</option></term>
	142
	143	<listitem><para>When used with
f7f74d8e	144	<command>kill-machine</command>,
19887cd0 ZJS	145	choose which processes to kill. Must
	146	be one of <option>leader</option>, or
	147	<option>all</option> to select whether
	148	to kill only the leader process of the
f7f74d8e LP	149	machine or all processes of the
f7f74d8e LP	150	machine. If omitted, defaults to
19887cd0 ZJS	151	<option>all</option>.</para></listitem>
	152	</varlistentry>
	153
	154	<varlistentry>
	155	<term><option>-s</option></term>
	156	<term><option>--signal=</option></term>
	157
	158	<listitem><para>When used with
fbce1139	159	<command>kill-machine</command>, choose
19887cd0	160	which signal to send to selected
f7f74d8e LP	161	processes. Must be one of the
f7f74d8e LP	162	well-known signal specifiers, such as
19887cd0 ZJS	163	<constant>SIGTERM</constant>,
	164	<constant>SIGINT</constant> or
	165	<constant>SIGSTOP</constant>. If
	166	omitted, defaults to
	167	<constant>SIGTERM</constant>.</para></listitem>
	168	</varlistentry>
	169
	170	<varlistentry>
	171	<term><option>-H</option></term>
	172	<term><option>--host</option></term>
	173
	174	<listitem><para>Execute operation
	175	remotely. Specify a hostname, or
	176	username and hostname separated by <literal>@</literal>,
	177	to connect to. This will use SSH to
	178	talk to the remote machine manager
	179	instance.</para></listitem>
	180	</varlistentry>
	181
	182	<varlistentry>
	183	<term><option>-P</option></term>
	184	<term><option>--privileged</option></term>
	185
	186	<listitem><para>Acquire privileges via
	187	PolicyKit before executing the
	188	operation.</para></listitem>
	189	</varlistentry>
	190	</variablelist>
	191
	192	<para>The following commands are understood:</para>
	193
	194	<variablelist>
	195	<varlistentry>
	196	<term><command>list</command></term>
	197
	198	<listitem><para>List currently running
	199	virtual machines and containers.
	200	</para></listitem>
	201	</varlistentry>
	202
	203	<varlistentry>
	204	<term><command>status [ID...]</command></term>
	205
	206	<listitem><para>Show terse runtime
	207	status information about one or more
	208	virtual machines and containers. This
	209	function is intended to generate
	210	human-readable output. If you are
	211	looking for computer-parsable output,
	212	use <command>show</command> instead.
	213	</para></listitem>
	214	</varlistentry>
	215
	216	<varlistentry>
	217	<term><command>show [ID...]</command></term>
	218
	219	<listitem><para>Show properties of one
	220	or more registered virtual machines or
	221	containers or the manager itself. If
	222	no argument is specified, properties
7b870f60	223	of the manager will be shown. If an
19887cd0 ZJS	224	ID is specified, properties of this
	225	virtual machine or container are
	226	shown. By default, empty properties
	227	are suppressed. Use
	228	<option>--all</option> to show those
	229	too. To select specific properties to
	230	show, use
	231	<option>--property=</option>. This
	232	command is intended to be used
	233	whenever computer-parsable output is
	234	required. Use
	235	<command>status</command> if you are
	236	looking for formatted human-readable
	237	output.</para></listitem>
	238	</varlistentry>
	239
	240	<varlistentry>
	241	<term><command>terminate [ID...]</command></term>
	242
	243	<listitem><para>Terminates a virtual
	244	machine or container. This kills all
	245	processes of the virtual machine or
	246	container and deallocates all
	247	resources attached to that
	248	instance.</para></listitem>
	249	</varlistentry>
	250
	251	<varlistentry>
	252	<term><command>kill [ID...]</command></term>
	253
	254	<listitem><para>Send a signal to one
	255	or more processes of the virtual
	256	machine or container. This means
	257	processes as seen by the host, not the
	258	processes inside the virtual machine
	259	or container.
	260	Use <option>--kill-who=</option> to
	261	select which process to kill. Use
	262	<option>--signal=</option> to select
	263	the signal to send.</para></listitem>
	264	</varlistentry>
	265	</variablelist>
	266
	267	</refsect1>
	268
	269	<refsect1>
	270	<title>Exit status</title>
	271
	272	<para>On success, 0 is returned, a non-zero failure
	273	code otherwise.</para>
	274	</refsect1>
	275
	276	<refsect1>
	277	<title>Environment</title>
	278
	279	<variablelist class='environment-variables'>
	280	<varlistentry>
	281	<term><varname>$SYSTEMD_PAGER</varname></term>
	282	<listitem><para>Pager to use when
	283	<option>--no-pager</option> is not given;
	284	overrides <varname>$PAGER</varname>. Setting
	285	this to an empty string or the value
	286	<literal>cat</literal> is equivalent to passing
	287	<option>--no-pager</option>.</para></listitem>
288	</varlistentry>
289	</variablelist>
290	</refsect1>
291
292	<refsect1>
293	<title>See Also</title>
294	<para>
295	<citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
fade1ec6 ZJS	296	<citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
fade1ec6 ZJS	297	<citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
19887cd0 ZJS	298	</para>
	299	</refsect1>
	300
	301	</refentry>