chiark / gitweb /
machinectl: implement "bind" command to create additional bind mounts from host to...
[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                         <varlistentry>
150                                 <term><option>--mkdir</option></term>
151
152                                 <listitem><para>When used with
153                                 <command>bind</command> creates the
154                                 destination directory before applying
155                                 the bind mount.</para></listitem>
156                         </varlistentry>
157
158
159                         <varlistentry>
160                                 <term><option>--read-only</option></term>
161
162                                 <listitem><para>When used with
163                                 <command>bind</command> applies a
164                                 read-only bind
165                                 mount.</para></listitem>
166                         </varlistentry>
167
168                         <xi:include href="user-system-options.xml" xpointer="host" />
169                         <xi:include href="user-system-options.xml" xpointer="machine" />
170
171                         <xi:include href="standard-options.xml" xpointer="help" />
172                         <xi:include href="standard-options.xml" xpointer="version" />
173                         <xi:include href="standard-options.xml" xpointer="no-pager" />
174                 </variablelist>
175
176                 <para>The following commands are understood:</para>
177
178                 <variablelist>
179                         <varlistentry>
180                                 <term><command>list</command></term>
181
182                                 <listitem><para>List currently running
183                                 virtual machines and containers.
184                                 </para></listitem>
185                         </varlistentry>
186
187                         <varlistentry>
188                                 <term><command>status</command> <replaceable>ID</replaceable>...</term>
189
190                                 <listitem><para>Show terse runtime
191                                 status information about one or more
192                                 virtual machines and containers. This
193                                 function is intended to generate
194                                 human-readable output. If you are
195                                 looking for computer-parsable output,
196                                 use <command>show</command> instead.
197                                 </para></listitem>
198                         </varlistentry>
199
200                         <varlistentry>
201                                 <term><command>show</command> <replaceable>ID</replaceable>...</term>
202
203                                 <listitem><para>Show properties of one
204                                 or more registered virtual machines or
205                                 containers or the manager itself. If
206                                 no argument is specified, properties
207                                 of the manager will be shown. If an
208                                 ID is specified, properties of this
209                                 virtual machine or container are
210                                 shown. By default, empty properties
211                                 are suppressed. Use
212                                 <option>--all</option> to show those
213                                 too. To select specific properties to
214                                 show, use
215                                 <option>--property=</option>. This
216                                 command is intended to be used
217                                 whenever computer-parsable output is
218                                 required. Use
219                                 <command>status</command> if you are
220                                 looking for formatted human-readable
221                                 output.</para></listitem>
222                         </varlistentry>
223
224                         <varlistentry>
225                                 <term><command>login</command> <replaceable>ID</replaceable></term>
226
227                                 <listitem><para>Open a terminal login
228                                 session to a container. This will
229                                 create a TTY connection to a specific
230                                 container and asks for the execution of a
231                                 getty on it. Note that this is only
232                                 supported for containers running
233                                 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
234                                 as init system.</para></listitem>
235                         </varlistentry>
236
237                         <varlistentry>
238                                 <term><command>reboot</command> <replaceable>ID</replaceable>...</term>
239
240                                 <listitem><para>Reboot one or more
241                                 containers. This will trigger a reboot
242                                 by sending SIGINT to the container's
243                                 init process, which is roughly
244                                 equivalent to pressing Ctrl+Alt+Del on
245                                 a non-containerized system, and is
246                                 compatible with containers running any
247                                 init system.</para></listitem>
248                         </varlistentry>
249
250                         <varlistentry>
251                                 <term><command>poweroff</command> <replaceable>ID</replaceable>...</term>
252
253                                 <listitem><para>Power off one or more
254                                 containers. This will trigger a reboot
255                                 by sending SIGRTMIN+4 to the
256                                 container's init process, which causes
257                                 systemd-compatible init systems to
258                                 shut down cleanly. This operation does
259                                 not work on containers that do not run
260                                 a
261                                 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>-compatible
262                                 init system, such as
263                                 sysvinit.</para></listitem>
264                         </varlistentry>
265
266                         <varlistentry>
267                                 <term><command>kill</command> <replaceable>ID</replaceable>...</term>
268
269                                 <listitem><para>Send a signal to one
270                                 or more processes of the virtual
271                                 machine or container. This means
272                                 processes as seen by the host, not the
273                                 processes inside the virtual machine
274                                 or container.
275                                 Use <option>--kill-who=</option> to
276                                 select which process to kill. Use
277                                 <option>--signal=</option> to select
278                                 the signal to send.</para></listitem>
279                         </varlistentry>
280
281                         <varlistentry>
282                                 <term><command>terminate</command> <replaceable>ID</replaceable>...</term>
283
284                                 <listitem><para>Terminates a virtual
285                                 machine or container. This kills all
286                                 processes of the virtual machine or
287                                 container and deallocates all
288                                 resources attached to that
289                                 instance.</para></listitem>
290                         </varlistentry>
291
292                         <varlistentry>
293                                 <term><command>bind</command> <replaceable>ID</replaceable> <replaceable>DIRECTORY</replaceable> [<replaceable>DIRECTORY</replaceable>]</term>
294
295                                 <listitem><para>Bind mounts a
296                                 directory from the host into the
297                                 specified container. The first
298                                 directory argument is the source
299                                 directory on the host, the second
300                                 directory argument the source
301                                 directory on the host. When the latter
302                                 is omitted the destination path in the
303                                 container is the same as the source
304                                 path on the host. When combined with
305                                 the <option>--read-only</option>
306                                 switch a ready-only bind mount is
307                                 created. When combined with the
308                                 <option>--mkdir</option> switch the
309                                 destination path is first created
310                                 before the mount is applied. Note that
311                                 this option is currently only
312                                 supported for
313                                 <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
314                                 containers.</para></listitem>
315                         </varlistentry>
316
317                 </variablelist>
318
319         </refsect1>
320
321         <refsect1>
322                 <title>Exit status</title>
323
324                 <para>On success, 0 is returned, a non-zero failure
325                 code otherwise.</para>
326         </refsect1>
327
328         <xi:include href="less-variables.xml" />
329
330         <refsect1>
331                 <title>See Also</title>
332                 <para>
333                         <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
334                         <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
335                         <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>
336                 </para>
337         </refsect1>
338
339 </refentry>