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">
6 This file is part of systemd.
8 Copyright 2013 Zbigniew Jędrzejewski-Szmek
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.
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.
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/>.
24 <refentry id="machinectl" conditional='ENABLE_MACHINED'>
27 <title>machinectl</title>
28 <productname>systemd</productname>
32 <contrib>Developer</contrib>
33 <firstname>Lennart</firstname>
34 <surname>Poettering</surname>
35 <email>lennart@poettering.net</email>
41 <refentrytitle>machinectl</refentrytitle>
42 <manvolnum>1</manvolnum>
46 <refname>machinectl</refname>
47 <refpurpose>Control the systemd machine manager</refpurpose>
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>
60 <title>Description</title>
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>
69 <title>Options</title>
71 <para>The following options are understood:</para>
75 <term><option>-h</option></term>
76 <term><option>--help</option></term>
78 <listitem><para>Prints a short help
79 text and exits.</para></listitem>
83 <term><option>--version</option></term>
85 <listitem><para>Prints a short version
86 string and exits.</para></listitem>
90 <term><option>-p</option></term>
91 <term><option>--property=</option></term>
93 <listitem><para>When showing
94 machine properties, limit the
95 output to certain properties as
96 specified by the argument. If not
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>
107 <term><option>-a</option></term>
108 <term><option>--all</option></term>
110 <listitem><para>When showing
111 machine properties, show all
112 properties regardless of whether they are
113 set or not.</para></listitem>
117 <term><option>-l</option></term>
118 <term><option>--full</option></term>
120 <listitem><para>Do not ellipsize cgroup
126 <term><option>--no-pager</option></term>
128 <listitem><para>Do not pipe output into a
129 pager.</para></listitem>
133 <term><option>--no-ask-password</option></term>
135 <listitem><para>Do not query the user
136 for authentication for privileged
137 operations.</para></listitem>
141 <term><option>--kill-who=</option></term>
143 <listitem><para>When used with
144 <command>kill-machine</command>,
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
149 machine or all processes of the
150 machine. If omitted, defaults to
151 <option>all</option>.</para></listitem>
155 <term><option>-s</option></term>
156 <term><option>--signal=</option></term>
158 <listitem><para>When used with
159 <command>kill-machine</command>, choose
160 which signal to send to selected
161 processes. Must be one of the
162 well-known signal specifiers, such as
163 <constant>SIGTERM</constant>,
164 <constant>SIGINT</constant> or
165 <constant>SIGSTOP</constant>. If
167 <constant>SIGTERM</constant>.</para></listitem>
171 <term><option>-H</option></term>
172 <term><option>--host</option></term>
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>
183 <term><option>-P</option></term>
184 <term><option>--privileged</option></term>
186 <listitem><para>Acquire privileges via
187 PolicyKit before executing the
188 operation.</para></listitem>
192 <para>The following commands are understood:</para>
196 <term><command>list</command></term>
198 <listitem><para>List currently running
199 virtual machines and containers.
204 <term><command>status [ID...]</command></term>
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.
217 <term><command>show [ID...]</command></term>
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
223 of the manager will be shown. If an
224 ID is specified, properties of this
225 virtual machine or container are
226 shown. By default, empty properties
228 <option>--all</option> to show those
229 too. To select specific properties to
231 <option>--property=</option>. This
232 command is intended to be used
233 whenever computer-parsable output is
235 <command>status</command> if you are
236 looking for formatted human-readable
237 output.</para></listitem>
241 <term><command>terminate [ID...]</command></term>
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>
252 <term><command>kill [ID...]</command></term>
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
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>
270 <title>Exit status</title>
272 <para>On success, 0 is returned, a non-zero failure
273 code otherwise.</para>
277 <title>Environment</title>
279 <variablelist class='environment-variables'>
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>
293 <title>See Also</title>
295 <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
296 <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
297 <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>.