chiark / gitweb /
rtnl: match - only match on one type at a time
[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
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>--no-pager</option></term>
91
92                                 <listitem><para>Do not pipe output into a
93                                 pager.</para></listitem>
94                         </varlistentry>
95
96                         <varlistentry>
97                                 <term><option>--no-ask-password</option></term>
98
99                                 <listitem><para>Do not query the user
100                                 for authentication for privileged
101                                 operations.</para></listitem>
102                         </varlistentry>
103
104                         <varlistentry>
105                                 <term><option>-H</option></term>
106                                 <term><option>--host=</option></term>
107
108                                 <listitem><para>Execute the operation
109                                 remotely. Specify a hostname, or
110                                 username and hostname separated by <literal>@</literal>,
111                                 to connect to. This will use SSH to
112                                 talk to the remote machine manager
113                                 instance.</para></listitem>
114                         </varlistentry>
115
116                         <varlistentry>
117                                 <term><option>-M</option></term>
118                                 <term><option>--machine=</option></term>
119
120                                 <listitem><para>Execute the operation on a
121                                 local container. Specify a container
122                                 name to connect to.</para></listitem>
123                         </varlistentry>
124
125                         <varlistentry>
126                                 <term><option>-p</option></term>
127                                 <term><option>--property=</option></term>
128
129                                 <listitem><para>When showing
130                                 machine properties, limit the
131                                 output to certain properties as
132                                 specified by the argument. If not
133                                 specified, all set properties are
134                                 shown. The argument should be a
135                                 property name, such as
136                                 <literal>Name</literal>. If
137                                 specified more than once, all
138                                 properties with the specified names
139                                 are shown.</para></listitem>
140                         </varlistentry>
141
142                         <varlistentry>
143                                 <term><option>-a</option></term>
144                                 <term><option>--all</option></term>
145
146                                 <listitem><para>When showing
147                                 machine properties, show all
148                                 properties regardless of whether they are
149                                 set or not.</para></listitem>
150                         </varlistentry>
151
152                         <varlistentry>
153                                 <term><option>-l</option></term>
154                                 <term><option>--full</option></term>
155
156                                 <listitem><para>Do not ellipsize
157                                 process tree entries.</para>
158                                 </listitem>
159                         </varlistentry>
160
161                         <varlistentry>
162                                 <term><option>--kill-who=</option></term>
163
164                                 <listitem><para>When used with
165                                 <command>kill-machine</command>,
166                                 choose which processes to kill. Must
167                                 be one of <option>leader</option>, or
168                                 <option>all</option> to select whether
169                                 to kill only the leader process of the
170                                 machine or all processes of the
171                                 machine. If omitted, defaults to
172                                 <option>all</option>.</para></listitem>
173                         </varlistentry>
174
175                         <varlistentry>
176                                 <term><option>-s</option></term>
177                                 <term><option>--signal=</option></term>
178
179                                 <listitem><para>When used with
180                                 <command>kill-machine</command>, choose
181                                 which signal to send to selected
182                                 processes. Must be one of the
183                                 well-known signal specifiers, such as
184                                 <constant>SIGTERM</constant>,
185                                 <constant>SIGINT</constant> or
186                                 <constant>SIGSTOP</constant>. If
187                                 omitted, defaults to
188                                 <constant>SIGTERM</constant>.</para></listitem>
189                         </varlistentry>
190
191                 </variablelist>
192
193                 <para>The following commands are understood:</para>
194
195                 <variablelist>
196                         <varlistentry>
197                                 <term><command>list</command></term>
198
199                                 <listitem><para>List currently running
200                                 virtual machines and containers.
201                                 </para></listitem>
202                         </varlistentry>
203
204                         <varlistentry>
205                                 <term><command>status</command> <replaceable>ID</replaceable>...</term>
206
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.
214                                 </para></listitem>
215                         </varlistentry>
216
217                         <varlistentry>
218                                 <term><command>show</command> <replaceable>ID</replaceable>...</term>
219
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
228                                 are suppressed. Use
229                                 <option>--all</option> to show those
230                                 too. To select specific properties to
231                                 show, use
232                                 <option>--property=</option>. This
233                                 command is intended to be used
234                                 whenever computer-parsable output is
235                                 required. Use
236                                 <command>status</command> if you are
237                                 looking for formatted human-readable
238                                 output.</para></listitem>
239                         </varlistentry>
240
241                         <varlistentry>
242                                 <term><command>terminate</command> <replaceable>ID</replaceable>...</term>
243
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>
250                         </varlistentry>
251
252                         <varlistentry>
253                                 <term><command>kill</command> <replaceable>ID</replaceable>...</term>
254
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
260                                 or container.
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>
265                         </varlistentry>
266
267                         <varlistentry>
268                                 <term><command>login</command> <replaceable>ID</replaceable>...</term>
269
270                                 <listitem><para>Open a terminal login
271                                 session to a container. This will
272                                 create a TTY connection to a specific
273                                 container and asks for the execution of a
274                                 getty on it. Note that this is only
275                                 supported for containers running
276                                 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
277                                 as init system.</para></listitem>
278                         </varlistentry>
279                 </variablelist>
280
281         </refsect1>
282
283         <refsect1>
284                 <title>Exit status</title>
285
286                 <para>On success, 0 is returned, a non-zero failure
287                 code otherwise.</para>
288         </refsect1>
289
290         <refsect1>
291                 <title>Environment</title>
292
293                 <variablelist class='environment-variables'>
294                         <varlistentry>
295                                 <term><varname>$SYSTEMD_PAGER</varname></term>
296                                 <listitem><para>Pager to use when
297                                 <option>--no-pager</option> is not given;
298                                 overrides <varname>$PAGER</varname>.  Setting
299                                 this to an empty string or the value
300                                 <literal>cat</literal> is equivalent to passing
301                                 <option>--no-pager</option>.</para></listitem>
302                         </varlistentry>
303                 </variablelist>
304         </refsect1>
305
306         <refsect1>
307                 <title>See Also</title>
308                 <para>
309                         <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
310                         <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
311                         <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>
312                 </para>
313         </refsect1>
314
315 </refentry>