chiark / gitweb /
man: updates to the passive target section
[elogind.git] / man / machinectl.xml
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           xmlns:xi="http://www.w3.org/2001/XInclude">
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>
75                         <varlistentry>
76                                 <term><option>-p</option></term>
77                                 <term><option>--property=</option></term>
78
79                                 <listitem><para>When showing
80                                 machine properties, limit the
81                                 output to certain properties as
82                                 specified by the argument. If not
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
97                                 machine properties, show all
98                                 properties regardless of whether they are
99                                 set or not.</para></listitem>
100                         </varlistentry>
101
102                         <varlistentry>
103                                 <term><option>-l</option></term>
104                                 <term><option>--full</option></term>
105
106                                 <listitem><para>Do not ellipsize
107                                 process tree entries.</para>
108                                 </listitem>
109                         </varlistentry>
110
111                         <varlistentry>
112                                 <term><option>--kill-who=</option></term>
113
114                                 <listitem><para>When used with
115                                 <command>kill</command>,
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
120                                 machine or all processes of the
121                                 machine. If omitted, defaults to
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
130                                 <command>kill</command>, choose
131                                 which signal to send to selected
132                                 processes. Must be one of the
133                                 well-known signal specifiers, such as
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
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
149                         <xi:include href="user-system-options.xml" xpointer="host" />
150                         <xi:include href="user-system-options.xml" xpointer="machine" />
151
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" />
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>
169                                 <term><command>status</command> <replaceable>ID</replaceable>...</term>
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>
182                                 <term><command>show</command> <replaceable>ID</replaceable>...</term>
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
188                                 of the manager will be shown. If an
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>
206                                 <term><command>login</command> <replaceable>ID</replaceable></term>
207
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>
245                         </varlistentry>
246
247                         <varlistentry>
248                                 <term><command>kill</command> <replaceable>ID</replaceable>...</term>
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>
261
262                         <varlistentry>
263                                 <term><command>terminate</command> <replaceable>ID</replaceable>...</term>
264
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>
271                         </varlistentry>
272
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
284         <xi:include href="less-variables.xml" />
285
286         <refsect1>
287                 <title>See Also</title>
288                 <para>
289                         <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
290                         <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
291                         <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>
292                 </para>
293         </refsect1>
294
295 </refentry>