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 session/user 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 unit/job/manager 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-session</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 session or all processes of the
150 session. 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-session</command> or
160 <command>kill-user</command>, choose
161 which signal to send to selected
162 processes. Must be one of the well-known
163 signal specifiers, such as
164 <constant>SIGTERM</constant>,
165 <constant>SIGINT</constant> or
166 <constant>SIGSTOP</constant>. If
168 <constant>SIGTERM</constant>.</para></listitem>
172 <term><option>-H</option></term>
173 <term><option>--host</option></term>
175 <listitem><para>Execute operation
176 remotely. Specify a hostname, or
177 username and hostname separated by <literal>@</literal>,
178 to connect to. This will use SSH to
179 talk to the remote machine manager
180 instance.</para></listitem>
184 <term><option>-P</option></term>
185 <term><option>--privileged</option></term>
187 <listitem><para>Acquire privileges via
188 PolicyKit before executing the
189 operation.</para></listitem>
193 <para>The following commands are understood:</para>
197 <term><command>list</command></term>
199 <listitem><para>List currently running
200 virtual machines and containers.
205 <term><command>status [ID...]</command></term>
207 <listitem><para>Show terse runtime
208 status information about one or more
209 virtual machines and containers. This
210 function is intended to generate
211 human-readable output. If you are
212 looking for computer-parsable output,
213 use <command>show</command> instead.
218 <term><command>show [ID...]</command></term>
220 <listitem><para>Show properties of one
221 or more registered virtual machines or
222 containers or the manager itself. If
223 no argument is specified, properties
224 of the manager will be shown. If an
225 ID is specified, properties of this
226 virtual machine or container are
227 shown. By default, empty properties
229 <option>--all</option> to show those
230 too. To select specific properties to
232 <option>--property=</option>. This
233 command is intended to be used
234 whenever computer-parsable output is
236 <command>status</command> if you are
237 looking for formatted human-readable
238 output.</para></listitem>
242 <term><command>terminate [ID...]</command></term>
244 <listitem><para>Terminates a virtual
245 machine or container. This kills all
246 processes of the virtual machine or
247 container and deallocates all
248 resources attached to that
249 instance.</para></listitem>
253 <term><command>kill [ID...]</command></term>
255 <listitem><para>Send a signal to one
256 or more processes of the virtual
257 machine or container. This means
258 processes as seen by the host, not the
259 processes inside the virtual machine
261 Use <option>--kill-who=</option> to
262 select which process to kill. Use
263 <option>--signal=</option> to select
264 the signal to send.</para></listitem>
271 <title>Exit status</title>
273 <para>On success, 0 is returned, a non-zero failure
274 code otherwise.</para>
278 <title>Environment</title>
280 <variablelist class='environment-variables'>
282 <term><varname>$SYSTEMD_PAGER</varname></term>
283 <listitem><para>Pager to use when
284 <option>--no-pager</option> is not given;
285 overrides <varname>$PAGER</varname>. Setting
286 this to an empty string or the value
287 <literal>cat</literal> is equivalent to passing
288 <option>--no-pager</option>.</para></listitem>
294 <title>See Also</title>
296 <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
297 <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
298 <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>.