]> git.proxmox.com Git - systemd.git/blame - man/machinectl.xml
Merge tag 'upstream/229'
[systemd.git] / man / machinectl.xml
CommitLineData
13d276d0 1<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
14228c0d 2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
e735f4d4 3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
14228c0d
MB
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
60f067b4 24<refentry id="machinectl" conditional='ENABLE_MACHINED'
e735f4d4
MP
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 introspect and
64 control the state of the
65 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
66 virtual machine and container registration manager
67 <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
13d276d0
MP
68
69 <para><command>machinectl</command> may be used to execute
70 operations on machines and images. Machines in this sense are
71 considered running instances of:</para>
72
73 <itemizedlist>
74 <listitem><para>Virtual Machines (VMs) that virtualize hardware
75 to run full operating system (OS) instances (including their kernels)
76 in a virtualized environment on top of the host OS.</para></listitem>
77
78 <listitem><para>Containers that share the hardware and
79 OS kernel with the host OS, in order to run
80 OS userspace instances on top the host OS.</para></listitem>
81
82 <listitem><para>The host system itself</para></listitem>
83 </itemizedlist>
84
85 <para>Machines are identified by names that follow the same rules
db2df898
MP
86 as UNIX and DNS host names, for details, see below. Machines are
87 instantiated from disk or file system images that frequently — but not
88 necessarily — carry the same name as machines running from
13d276d0
MP
89 them. Images in this sense are considered:</para>
90
91 <itemizedlist>
92 <listitem><para>Directory trees containing an OS, including its
93 top-level directories <filename>/usr</filename>,
94 <filename>/etc</filename>, and so on.</para></listitem>
95
96 <listitem><para>btrfs subvolumes containing OS trees, similar to
97 normal directory trees.</para></listitem>
98
99 <listitem><para>Binary "raw" disk images containing MBR or GPT
100 partition tables and Linux file system partitions.</para></listitem>
101
102 <listitem><para>The file system tree of the host OS itself.</para></listitem>
103 </itemizedlist>
104
e735f4d4
MP
105 </refsect1>
106
107 <refsect1>
108 <title>Options</title>
109
110 <para>The following options are understood:</para>
111
112 <variablelist>
113 <varlistentry>
114 <term><option>-p</option></term>
115 <term><option>--property=</option></term>
116
117 <listitem><para>When showing machine or image properties,
118 limit the output to certain properties as specified by the
119 argument. If not specified, all set properties are shown. The
120 argument should be a property name, such as
121 <literal>Name</literal>. If specified more than once, all
122 properties with the specified names are
123 shown.</para></listitem>
124 </varlistentry>
125
126 <varlistentry>
127 <term><option>-a</option></term>
128 <term><option>--all</option></term>
129
130 <listitem><para>When showing machine or image properties, show
131 all properties regardless of whether they are set or
132 not.</para>
133
134 <para>When listing VM or container images, do not suppress
135 images beginning in a dot character
136 (<literal>.</literal>).</para></listitem>
137 </varlistentry>
138
139 <varlistentry>
140 <term><option>-l</option></term>
141 <term><option>--full</option></term>
142
143 <listitem><para>Do not ellipsize process tree entries.</para>
144 </listitem>
145 </varlistentry>
146
147 <varlistentry>
148 <term><option>--no-ask-password</option></term>
149
150 <listitem><para>Do not query the user for authentication for
151 privileged operations.</para></listitem>
152 </varlistentry>
153
154 <varlistentry>
155 <term><option>--kill-who=</option></term>
156
157 <listitem><para>When used with <command>kill</command>, choose
158 which processes to kill. Must be one of
159 <option>leader</option>, or <option>all</option> to select
160 whether to kill only the leader process of the machine or all
161 processes of the machine. If omitted, defaults to
162 <option>all</option>.</para></listitem>
163 </varlistentry>
164
165 <varlistentry>
166 <term><option>-s</option></term>
167 <term><option>--signal=</option></term>
168
169 <listitem><para>When used with <command>kill</command>, choose
170 which signal to send to selected processes. Must be one of the
171 well-known signal specifiers, such as
172 <constant>SIGTERM</constant>, <constant>SIGINT</constant> or
173 <constant>SIGSTOP</constant>. If omitted, defaults to
174 <constant>SIGTERM</constant>.</para></listitem>
175 </varlistentry>
176
13d276d0
MP
177 <varlistentry>
178 <term><option>--uid=</option></term>
179
180 <listitem><para>When used with the <command>shell</command>
181 command, chooses the user ID to open the interactive shell
182 session as. If this switch is not specified, defaults to
183 <literal>root</literal>. Note that this switch is not
184 supported for the <command>login</command> command (see
185 below).</para></listitem>
186 </varlistentry>
187
188 <varlistentry>
189 <term><option>--setenv=</option></term>
190
191 <listitem><para>When used with the <command>shell</command>
192 command, sets an environment variable to pass to the executed
193 shell. Takes a pair of environment variable name and value,
194 separated by <literal>=</literal> as argument. This switch
195 may be used multiple times to set multiple environment
196 variables. Note that this switch is not supported for the
197 <command>login</command> command (see
198 below).</para></listitem>
199 </varlistentry>
200
e735f4d4
MP
201 <varlistentry>
202 <term><option>--mkdir</option></term>
203
db2df898 204 <listitem><para>When used with <command>bind</command>, creates
e735f4d4
MP
205 the destination directory before applying the bind
206 mount.</para></listitem>
207 </varlistentry>
208
e735f4d4
MP
209 <varlistentry>
210 <term><option>--read-only</option></term>
211
db2df898 212 <listitem><para>When used with <command>bind</command>, applies
e735f4d4
MP
213 a read-only bind mount.</para></listitem>
214 </varlistentry>
215
216
217 <varlistentry>
218 <term><option>-n</option></term>
219 <term><option>--lines=</option></term>
220
221 <listitem><para>When used with <command>status</command>,
222 controls the number of journal lines to show, counting from
223 the most recent ones. Takes a positive integer argument.
224 Defaults to 10.</para>
225 </listitem>
226 </varlistentry>
227
228 <varlistentry>
229 <term><option>-o</option></term>
230 <term><option>--output=</option></term>
231
232 <listitem><para>When used with <command>status</command>,
233 controls the formatting of the journal entries that are shown.
234 For the available choices, see
235 <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
236 Defaults to <literal>short</literal>.</para></listitem>
237 </varlistentry>
238
239 <varlistentry>
240 <term><option>--verify=</option></term>
241
242 <listitem><para>When downloading a container or VM image,
243 specify whether the image shall be verified before it is made
244 available. Takes one of <literal>no</literal>,
245 <literal>checksum</literal> and <literal>signature</literal>.
db2df898
MP
246 If <literal>no</literal>, no verification is done. If
247 <literal>checksum</literal> is specified, the download is
248 checked for integrity after the transfer is complete, but no
e735f4d4 249 signatures are verified. If <literal>signature</literal> is
4c89c718 250 specified, the checksum is verified and the image's signature
e735f4d4
MP
251 is checked against a local keyring of trustable vendors. It is
252 strongly recommended to set this option to
253 <literal>signature</literal> if the server and protocol
254 support this. Defaults to
255 <literal>signature</literal>.</para></listitem>
256 </varlistentry>
257
258 <varlistentry>
259 <term><option>--force</option></term>
260
261 <listitem><para>When downloading a container or VM image, and
262 a local copy by the specified local machine name already
263 exists, delete it first and replace it by the newly downloaded
264 image.</para></listitem>
265 </varlistentry>
266
e3bff60a
MP
267 <varlistentry>
268 <term><option>--format=</option></term>
269
270 <listitem><para>When used with the <option>export-tar</option>
db2df898 271 or <option>export-raw</option> commands, specifies the
e3bff60a
MP
272 compression format to use for the resulting file. Takes one of
273 <literal>uncompressed</literal>, <literal>xz</literal>,
db2df898 274 <literal>gzip</literal>, <literal>bzip2</literal>. By default,
e3bff60a
MP
275 the format is determined automatically from the image file
276 name passed.</para></listitem>
277 </varlistentry>
278
e735f4d4
MP
279 <xi:include href="user-system-options.xml" xpointer="host" />
280 <xi:include href="user-system-options.xml" xpointer="machine" />
281
282 <xi:include href="standard-options.xml" xpointer="no-pager" />
283 <xi:include href="standard-options.xml" xpointer="no-legend" />
284 <xi:include href="standard-options.xml" xpointer="help" />
285 <xi:include href="standard-options.xml" xpointer="version" />
286 </variablelist>
287 </refsect1>
288
289 <refsect1>
290 <title>Commands</title>
291
292 <para>The following commands are understood:</para>
293
294 <refsect2><title>Machine Commands</title><variablelist>
295
296 <varlistentry>
297 <term><command>list</command></term>
298
299 <listitem><para>List currently running (online) virtual
13d276d0
MP
300 machines and containers. To enumerate machine images that can
301 be started, use <command>list-images</command> (see
302 below). Note that this command hides the special
303 <literal>.host</literal> machine by default. Use the
304 <option>--all</option> switch to show it.</para></listitem>
e735f4d4
MP
305 </varlistentry>
306
307 <varlistentry>
308 <term><command>status</command> <replaceable>NAME</replaceable>...</term>
309
db2df898 310 <listitem><para>Show runtime status information about
e735f4d4
MP
311 one or more virtual machines and containers, followed by the
312 most recent log data from the journal. This function is
313 intended to generate human-readable output. If you are looking
314 for computer-parsable output, use <command>show</command>
315 instead. Note that the log data shown is reported by the
316 virtual machine or container manager, and frequently contains
317 console output of the machine, but not necessarily journal
318 contents of the machine itself.</para></listitem>
319 </varlistentry>
320
321 <varlistentry>
13d276d0 322 <term><command>show</command> [<replaceable>NAME</replaceable>...]</term>
e735f4d4
MP
323
324 <listitem><para>Show properties of one or more registered
325 virtual machines or containers or the manager itself. If no
326 argument is specified, properties of the manager will be
327 shown. If an NAME is specified, properties of this virtual
328 machine or container are shown. By default, empty properties
329 are suppressed. Use <option>--all</option> to show those too.
330 To select specific properties to show, use
331 <option>--property=</option>. This command is intended to be
db2df898
MP
332 used whenever computer-parsable output is required, and does
333 not print the cgroup tree or journal entries. Use
e735f4d4
MP
334 <command>status</command> if you are looking for formatted
335 human-readable output.</para></listitem>
336 </varlistentry>
337
338 <varlistentry>
339 <term><command>start</command> <replaceable>NAME</replaceable>...</term>
340
341 <listitem><para>Start a container as a system service, using
342 <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
343 This starts <filename>systemd-nspawn@.service</filename>,
344 instantiated for the specified machine name, similar to the
345 effect of <command>systemctl start</command> on the service
346 name. <command>systemd-nspawn</command> looks for a container
347 image by the specified name in
348 <filename>/var/lib/machines/</filename> (and other search
349 paths, see below) and runs it. Use
db2df898 350 <command>list-images</command> (see below) for listing
e735f4d4
MP
351 available container images to start.</para>
352
353 <para>Note that
354 <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
355 also interfaces with a variety of other container and VM
356 managers, <command>systemd-nspawn</command> is just one
357 implementation of it. Most of the commands available in
358 <command>machinectl</command> may be used on containers or VMs
359 controlled by other managers, not just
360 <command>systemd-nspawn</command>. Starting VMs and container
361 images on those managers requires manager-specific
362 tools.</para>
363
364 <para>To interactively start a container on the command line
365 with full access to the container's console, please invoke
366 <command>systemd-nspawn</command> directly. To stop a running
367 container use <command>machinectl poweroff</command>, see
368 below.</para></listitem>
369 </varlistentry>
370
371 <varlistentry>
13d276d0
MP
372 <term><command>login</command> [<replaceable>NAME</replaceable>]</term>
373
374 <listitem><para>Open an interactive terminal login session in
db2df898 375 a container or on the local host. If an argument is supplied,
13d276d0
MP
376 it refers to the container machine to connect to. If none is
377 specified, or the container name is specified as the empty
378 string, or the special machine name <literal>.host</literal>
379 (see below) is specified, the connection is made to the local
380 host instead. This will create a TTY connection to a specific
381 container or the local host and asks for the execution of a
382 getty on it. Note that this is only supported for containers
383 running
e735f4d4
MP
384 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
385 as init system.</para>
386
387 <para>This command will open a full login prompt on the
13d276d0
MP
388 container or the local host, which then asks for username and
389 password. Use <command>shell</command> (see below) or
390 <citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry>
391 with the <option>--machine=</option> switch to directly invoke
392 a single command, either interactively or in the
393 background.</para></listitem>
394 </varlistentry>
395
396 <varlistentry>
397 <term><command>shell</command> [[<replaceable>NAME</replaceable>@]<replaceable>NAME</replaceable> [<replaceable>PATH</replaceable> [<replaceable>ARGUMENTS</replaceable>...]]] </term>
398
399 <listitem><para>Open an interactive shell session in a
400 container or on the local host. The first argument refers to
401 the container machine to connect to. If none is specified, or
402 the machine name is specified as the empty string, or the
403 special machine name <literal>.host</literal> (see below) is
404 specified, the connection is made to the local host
405 instead. This works similar to <command>login</command> but
406 immediately invokes a user process. This command runs the
407 specified executable with the specified arguments, or
db2df898 408 <filename>/bin/sh</filename> if none is specified. By default,
13d276d0
MP
409 opens a <literal>root</literal> shell, but by using
410 <option>--uid=</option>, or by prefixing the machine name with
411 a username and an <literal>@</literal> character, a different
412 user may be selected. Use <option>--setenv=</option> to set
413 environment variables for the executed process.</para>
414
415 <para>When using the <command>shell</command> command without
db2df898
MP
416 arguments, (thus invoking the executed shell or command on the
417 local host), it is in many ways similar to a <citerefentry
13d276d0 418 project='die-net'><refentrytitle>su</refentrytitle><manvolnum>1</manvolnum></citerefentry>
db2df898 419 session, but, unlike <command>su</command>, completely isolates
13d276d0
MP
420 the new session from the originating session, so that it
421 shares no process or session properties, and is in a clean and
422 well-defined state. It will be tracked in a new utmp, login,
423 audit, security and keyring session, and will not inherit any
424 environment variables or resource limits, among other
425 properties.</para>
426
db2df898 427 <para>Note that
e735f4d4 428 <citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry>
13d276d0
MP
429 may be used in place of the <command>shell</command> command,
430 and allows more detailed, low-level configuration of the
431 invoked unit. However, it is frequently more privileged than
432 the <command>shell</command> command.</para></listitem>
e735f4d4
MP
433 </varlistentry>
434
435 <varlistentry>
436 <term><command>enable</command> <replaceable>NAME</replaceable>...</term>
437 <term><command>disable</command> <replaceable>NAME</replaceable>...</term>
438
439 <listitem><para>Enable or disable a container as a system
440 service to start at system boot, using
441 <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
442 This enables or disables
443 <filename>systemd-nspawn@.service</filename>, instantiated for
444 the specified machine name, similar to the effect of
445 <command>systemctl enable</command> or <command>systemctl
446 disable</command> on the service name.</para></listitem>
447 </varlistentry>
448
449 <varlistentry>
450 <term><command>poweroff</command> <replaceable>NAME</replaceable>...</term>
451
452 <listitem><para>Power off one or more containers. This will
453 trigger a reboot by sending SIGRTMIN+4 to the container's init
454 process, which causes systemd-compatible init systems to shut
455 down cleanly. This operation does not work on containers that
456 do not run a
457 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>-compatible
458 init system, such as sysvinit. Use
459 <command>terminate</command> (see below) to immediately
460 terminate a container or VM, without cleanly shutting it
461 down.</para></listitem>
462 </varlistentry>
463
464 <varlistentry>
465 <term><command>reboot</command> <replaceable>NAME</replaceable>...</term>
466
467 <listitem><para>Reboot one or more containers. This will
468 trigger a reboot by sending SIGINT to the container's init
469 process, which is roughly equivalent to pressing Ctrl+Alt+Del
470 on a non-containerized system, and is compatible with
471 containers running any system manager.</para></listitem>
472 </varlistentry>
473
474 <varlistentry>
475 <term><command>terminate</command> <replaceable>NAME</replaceable>...</term>
476
477 <listitem><para>Immediately terminates a virtual machine or
478 container, without cleanly shutting it down. This kills all
479 processes of the virtual machine or container and deallocates
480 all resources attached to that instance. Use
481 <command>poweroff</command> to issue a clean shutdown
482 request.</para></listitem>
483 </varlistentry>
484
485 <varlistentry>
486 <term><command>kill</command> <replaceable>NAME</replaceable>...</term>
487
488 <listitem><para>Send a signal to one or more processes of the
489 virtual machine or container. This means processes as seen by
490 the host, not the processes inside the virtual machine or
491 container. Use <option>--kill-who=</option> to select which
492 process to kill. Use <option>--signal=</option> to select the
493 signal to send.</para></listitem>
494 </varlistentry>
495
496 <varlistentry>
497 <term><command>bind</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term>
498
499 <listitem><para>Bind mounts a directory from the host into the
500 specified container. The first directory argument is the
501 source directory on the host, the second directory argument
fb183854 502 is the destination directory in the container. When the
db2df898 503 latter is omitted, the destination path in the container is
fb183854 504 the same as the source path on the host. When combined with
db2df898 505 the <option>--read-only</option> switch, a ready-only bind
fb183854 506 mount is created. When combined with the
db2df898 507 <option>--mkdir</option> switch, the destination path is first
fb183854
MP
508 created before the mount is applied. Note that this option is
509 currently only supported for
e735f4d4
MP
510 <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
511 containers.</para></listitem>
512 </varlistentry>
513
514 <varlistentry>
515 <term><command>copy-to</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term>
516
517 <listitem><para>Copies files or directories from the host
518 system into a running container. Takes a container name,
519 followed by the source path on the host and the destination
db2df898 520 path in the container. If the destination path is omitted, the
e735f4d4
MP
521 same as the source path is used.</para></listitem>
522 </varlistentry>
523
524
525 <varlistentry>
526 <term><command>copy-from</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term>
527
528 <listitem><para>Copies files or directories from a container
529 into the host system. Takes a container name, followed by the
530 source path in the container the destination path on the host.
db2df898 531 If the destination path is omitted, the same as the source path
e735f4d4
MP
532 is used.</para></listitem>
533 </varlistentry>
534 </variablelist></refsect2>
535
536 <refsect2><title>Image Commands</title><variablelist>
537
538 <varlistentry>
539 <term><command>list-images</command></term>
540
541 <listitem><para>Show a list of locally installed container and
542 VM images. This enumerates all raw disk images and container
543 directories and subvolumes in
544 <filename>/var/lib/machines/</filename> (and other search
545 paths, see below). Use <command>start</command> (see above) to
db2df898
MP
546 run a container off one of the listed images. Note that, by
547 default, containers whose name begins with a dot
e735f4d4
MP
548 (<literal>.</literal>) are not shown. To show these too,
549 specify <option>--all</option>. Note that a special image
550 <literal>.host</literal> always implicitly exists and refers
551 to the image the host itself is booted from.</para></listitem>
552 </varlistentry>
553
554 <varlistentry>
13d276d0 555 <term><command>image-status</command> [<replaceable>NAME</replaceable>...]</term>
e735f4d4
MP
556
557 <listitem><para>Show terse status information about one or
558 more container or VM images. This function is intended to
559 generate human-readable output. Use
560 <command>show-image</command> (see below) to generate
561 computer-parsable output instead.</para></listitem>
562 </varlistentry>
563
564 <varlistentry>
13d276d0 565 <term><command>show-image</command> [<replaceable>NAME</replaceable>...]</term>
e735f4d4
MP
566
567 <listitem><para>Show properties of one or more registered
568 virtual machine or container images, or the manager itself. If
569 no argument is specified, properties of the manager will be
570 shown. If an NAME is specified, properties of this virtual
571 machine or container image are shown. By default, empty
572 properties are suppressed. Use <option>--all</option> to show
573 those too. To select specific properties to show, use
574 <option>--property=</option>. This command is intended to be
575 used whenever computer-parsable output is required. Use
576 <command>image-status</command> if you are looking for
577 formatted human-readable output.</para></listitem>
578 </varlistentry>
579
580 <varlistentry>
581 <term><command>clone</command> <replaceable>NAME</replaceable> <replaceable>NAME</replaceable></term>
582
e3bff60a 583 <listitem><para>Clones a container or VM image. The
e735f4d4
MP
584 arguments specify the name of the image to clone and the name
585 of the newly cloned image. Note that plain directory container
586 images are cloned into subvolume images with this command.
587 Note that cloning a container or VM image is optimized for
588 btrfs file systems, and might not be efficient on others, due
e3bff60a
MP
589 to file system limitations.</para>
590
591 <para>Note that this command leaves host name, machine ID and
592 all other settings that could identify the instance
593 unmodified. The original image and the cloned copy will hence
594 share these credentials, and it might be necessary to manually
595 change them in the copy.</para></listitem>
e735f4d4
MP
596 </varlistentry>
597
598 <varlistentry>
599 <term><command>rename</command> <replaceable>NAME</replaceable> <replaceable>NAME</replaceable></term>
600
e3bff60a 601 <listitem><para>Renames a container or VM image. The
e735f4d4
MP
602 arguments specify the name of the image to rename and the new
603 name of the image.</para></listitem>
604 </varlistentry>
605
606 <varlistentry>
607 <term><command>read-only</command> <replaceable>NAME</replaceable> [<replaceable>BOOL</replaceable>]</term>
608
e3bff60a 609 <listitem><para>Marks or (unmarks) a container or VM image
e735f4d4
MP
610 read-only. Takes a VM or container image name, followed by a
611 boolean as arguments. If the boolean is omitted, positive is
612 implied, i.e. the image is marked read-only.</para></listitem>
613 </varlistentry>
614
e735f4d4
MP
615 <varlistentry>
616 <term><command>remove</command> <replaceable>NAME</replaceable>...</term>
617
e3bff60a 618 <listitem><para>Removes one or more container or VM images.
e735f4d4 619 The special image <literal>.host</literal>, which refers to
db2df898 620 the host's own directory tree, may not be
e735f4d4
MP
621 removed.</para></listitem>
622 </varlistentry>
623
e3bff60a
MP
624 <varlistentry>
625 <term><command>set-limit</command> [<replaceable>NAME</replaceable>] <replaceable>BYTES</replaceable></term>
626
db2df898
MP
627 <listitem><para>Sets the maximum size in bytes that a specific
628 container or VM image, or all images, may grow up to on disk
e3bff60a
MP
629 (disk quota). Takes either one or two parameters. The first,
630 optional parameter refers to a container or VM image name. If
db2df898
MP
631 specified, the size limit of the specified image is changed. If
632 omitted, the overall size limit of the sum of all images stored
e3bff60a
MP
633 locally is changed. The final argument specifies the size
634 limit in bytes, possibly suffixed by the usual K, M, G, T
635 units. If the size limit shall be disabled, specify
636 <literal>-</literal> as size.</para>
637
638 <para>Note that per-container size limits are only supported
db2df898
MP
639 on btrfs file systems. Also note that, if
640 <command>set-limit</command> is invoked without an image
e3bff60a
MP
641 parameter, and <filename>/var/lib/machines</filename> is
642 empty, and the directory is not located on btrfs, a btrfs
643 loopback file is implicitly created as
644 <filename>/var/lib/machines.raw</filename> with the given
645 size, and mounted to
646 <filename>/var/lib/machines</filename>. The size of the
647 loopback may later be readjusted with
648 <command>set-limit</command>, as well. If such a
649 loopback-mounted <filename>/var/lib/machines</filename>
db2df898 650 directory is used, <command>set-limit</command> without an image
e3bff60a
MP
651 name alters both the quota setting within the file system as
652 well as the loopback file and file system size
653 itself.</para></listitem>
654 </varlistentry>
655
e735f4d4
MP
656 </variablelist></refsect2>
657
658 <refsect2><title>Image Transfer Commands</title><variablelist>
659
660 <varlistentry>
661 <term><command>pull-tar</command> <replaceable>URL</replaceable> [<replaceable>NAME</replaceable>]</term>
662
663 <listitem><para>Downloads a <filename>.tar</filename>
664 container image from the specified URL, and makes it available
665 under the specified local machine name. The URL must be of
666 type <literal>http://</literal> or
667 <literal>https://</literal>, and must refer to a
668 <filename>.tar</filename>, <filename>.tar.gz</filename>,
669 <filename>.tar.xz</filename> or <filename>.tar.bz2</filename>
db2df898 670 archive file. If the local machine name is omitted, it
e735f4d4
MP
671 is automatically derived from the last component of the URL,
672 with its suffix removed.</para>
673
674 <para>The image is verified before it is made available,
675 unless <option>--verify=no</option> is specified. Verification
db2df898 676 is done via SHA256SUMS and SHA256SUMS.gpg files that need to
e735f4d4
MP
677 be made available on the same web server, under the same URL
678 as the <filename>.tar</filename> file, but with the last
679 component (the filename) of the URL replaced. With
db2df898 680 <option>--verify=checksum</option>, only the SHA256 checksum
e735f4d4
MP
681 for the file is verified, based on the
682 <filename>SHA256SUMS</filename> file. With
db2df898 683 <option>--verify=signature</option>, the SHA256SUMS file is
e735f4d4
MP
684 first verified with detached GPG signature file
685 <filename>SHA256SUMS.gpg</filename>. The public key for this
686 verification step needs to be available in
687 <filename>/usr/lib/systemd/import-pubring.gpg</filename> or
688 <filename>/etc/systemd/import-pubring.gpg</filename>.</para>
689
690 <para>The container image will be downloaded and stored in a
691 read-only subvolume in
db2df898 692 <filename>/var/lib/machines/</filename> that is named after
e735f4d4
MP
693 the specified URL and its HTTP etag. A writable snapshot is
694 then taken from this subvolume, and named after the specified
7035cd9e 695 local name. This behavior ensures that creating multiple
e735f4d4
MP
696 container instances of the same URL is efficient, as multiple
697 downloads are not necessary. In order to create only the
698 read-only image, and avoid creating its writable snapshot,
699 specify <literal>-</literal> as local machine name.</para>
700
701 <para>Note that the read-only subvolume is prefixed with
e3bff60a 702 <filename>.tar-</filename>, and is thus not shown by
e735f4d4
MP
703 <command>list-images</command>, unless <option>--all</option>
704 is passed.</para>
705
706 <para>Note that pressing C-c during execution of this command
707 will not abort the download. Use
708 <command>cancel-transfer</command>, described
709 below.</para></listitem>
710 </varlistentry>
711
712 <varlistentry>
713 <term><command>pull-raw</command> <replaceable>URL</replaceable> [<replaceable>NAME</replaceable>]</term>
714
715 <listitem><para>Downloads a <filename>.raw</filename>
716 container or VM disk image from the specified URL, and makes
717 it available under the specified local machine name. The URL
718 must be of type <literal>http://</literal> or
719 <literal>https://</literal>. The container image must either
720 be a <filename>.qcow2</filename> or raw disk image, optionally
721 compressed as <filename>.gz</filename>,
722 <filename>.xz</filename>, or <filename>.bz2</filename>. If the
db2df898 723 local machine name is omitted, it is automatically
e735f4d4
MP
724 derived from the last component of the URL, with its suffix
725 removed.</para>
726
727 <para>Image verification is identical for raw and tar images
728 (see above).</para>
729
fb183854 730 <para>If the downloaded image is in
e3bff60a 731 <filename>.qcow2</filename> format it is converted into a raw
e735f4d4
MP
732 image file before it is made available.</para>
733
734 <para>Downloaded images of this type will be placed as
735 read-only <filename>.raw</filename> file in
736 <filename>/var/lib/machines/</filename>. A local, writable
737 (reflinked) copy is then made under the specified local
738 machine name. To omit creation of the local, writable copy
739 pass <literal>-</literal> as local machine name.</para>
740
7035cd9e 741 <para>Similar to the behavior of <command>pull-tar</command>,
e735f4d4 742 the read-only image is prefixed with
e3bff60a 743 <filename>.raw-</filename>, and thus not shown by
e735f4d4
MP
744 <command>list-images</command>, unless <option>--all</option>
745 is passed.</para>
746
747 <para>Note that pressing C-c during execution of this command
748 will not abort the download. Use
749 <command>cancel-transfer</command>, described
750 below.</para></listitem>
751 </varlistentry>
752
e3bff60a
MP
753 <varlistentry>
754 <term><command>import-tar</command> <replaceable>FILE</replaceable> [<replaceable>NAME</replaceable>]</term>
755 <term><command>import-raw</command> <replaceable>FILE</replaceable> [<replaceable>NAME</replaceable>]</term>
756 <listitem><para>Imports a TAR or RAW container or VM image,
757 and places it under the specified name in
758 <filename>/var/lib/machines/</filename>. When
db2df898
MP
759 <command>import-tar</command> is used, the file specified as
760 the first argument should be a tar archive, possibly compressed
e3bff60a
MP
761 with xz, gzip or bzip2. It will then be unpacked into its own
762 subvolume in <filename>/var/lib/machines</filename>. When
db2df898 763 <command>import-raw</command> is used, the file should be a
e3bff60a
MP
764 qcow2 or raw disk image, possibly compressed with xz, gzip or
765 bzip2. If the second argument (the resulting image name) is
db2df898
MP
766 not specified, it is automatically derived from the file
767 name. If the file name is passed as <literal>-</literal>, the
e3bff60a
MP
768 image is read from standard input, in which case the second
769 argument is mandatory.</para>
770
4c89c718
MP
771 <para>Both <command>pull-tar</command> and <command>pull-raw</command>
772 will resize <filename>/var/lib/machines.raw</filename> and the
773 filesystem therein as necessary. Optionally, the
e3bff60a
MP
774 <option>--read-only</option> switch may be used to create a
775 read-only container or VM image. No cryptographic validation
776 is done when importing the images.</para>
777
778 <para>Much like image downloads, ongoing imports may be listed
779 with <command>list-transfers</command> and aborted with
780 <command>cancel-transfer</command>.</para></listitem>
781 </varlistentry>
782
783 <varlistentry>
784 <term><command>export-tar</command> <replaceable>NAME</replaceable> [<replaceable>FILE</replaceable>]</term>
785 <term><command>export-raw</command> <replaceable>NAME</replaceable> [<replaceable>FILE</replaceable>]</term>
786 <listitem><para>Exports a TAR or RAW container or VM image and
787 stores it in the specified file. The first parameter should be
788 a VM or container image name. The second parameter should be a
789 file path the TAR or RAW image is written to. If the path ends
db2df898
MP
790 in <literal>.gz</literal>, the file is compressed with gzip, if
791 it ends in <literal>.xz</literal>, with xz, and if it ends in
792 <literal>.bz2</literal>, with bzip2. If the path ends in
793 neither, the file is left uncompressed. If the second argument
794 is missing, the image is written to standard output. The
e3bff60a
MP
795 compression may also be explicitly selected with the
796 <option>--format=</option> switch. This is in particular
797 useful if the second parameter is left unspecified.</para>
798
799 <para>Much like image downloads and imports, ongoing exports
800 may be listed with <command>list-transfers</command> and
801 aborted with
802 <command>cancel-transfer</command>.</para>
803
db2df898 804 <para>Note that, currently, only directory and subvolume images
e3bff60a
MP
805 may be exported as TAR images, and only raw disk images as RAW
806 images.</para></listitem>
807 </varlistentry>
808
e735f4d4
MP
809 <varlistentry>
810 <term><command>list-transfers</command></term>
811
812 <listitem><para>Shows a list of container or VM image
e3bff60a
MP
813 downloads, imports and exports that are currently in
814 progress.</para></listitem>
e735f4d4
MP
815 </varlistentry>
816
817 <varlistentry>
818 <term><command>cancel-transfers</command> <replaceable>ID</replaceable>...</term>
819
e3bff60a
MP
820 <listitem><para>Aborts a download, import or export of the
821 container or VM image with the specified ID. To list ongoing
822 transfers and their IDs, use
823 <command>list-transfers</command>. </para></listitem>
e735f4d4
MP
824 </varlistentry>
825
826 </variablelist></refsect2>
827
828 </refsect1>
829
13d276d0
MP
830 <refsect1>
831 <title>Machine and Image Names</title>
832
833 <para>The <command>machinectl</command> tool operates on machines
db2df898 834 and images whose names must be chosen following strict
13d276d0
MP
835 rules. Machine names must be suitable for use as host names
836 following a conservative subset of DNS and UNIX/Linux
837 semantics. Specifically, they must consist of one or more
838 non-empty label strings, separated by dots. No leading or trailing
839 dots are allowed. No sequences of multiple dots are allowed. The
db2df898 840 label strings may only consist of alphanumeric characters as well
13d276d0
MP
841 as the dash and underscore. The maximum length of a machine name
842 is 64 characters.</para>
843
844 <para>A special machine with the name <literal>.host</literal>
845 refers to the running host system itself. This is useful for execution
db2df898 846 operations or inspecting the host system as well. Note that
13d276d0
MP
847 <command>machinectl list</command> will not show this special
848 machine unless the <option>--all</option> switch is specified.</para>
849
db2df898 850 <para>Requirements on image names are less strict, however, they must be
13d276d0
MP
851 valid UTF-8, must be suitable as file names (hence not be the
852 single or double dot, and not include a slash), and may not
853 contain control characters. Since many operations search for an
db2df898 854 image by the name of a requested machine, it is recommended to name
13d276d0
MP
855 images in the same strict fashion as machines.</para>
856
857 <para>A special image with the name <literal>.host</literal>
db2df898 858 refers to the image of the running host system. It hence
13d276d0
MP
859 conceptually maps to the special <literal>.host</literal> machine
860 name described above. Note that <command>machinectl
db2df898 861 list-images</command> will not show this special image either, unless
13d276d0
MP
862 <option>--all</option> is specified.</para>
863 </refsect1>
864
e735f4d4
MP
865 <refsect1>
866 <title>Files and Directories</title>
867
868 <para>Machine images are preferably stored in
869 <filename>/var/lib/machines/</filename>, but are also searched for
870 in <filename>/usr/local/lib/machines/</filename> and
db2df898 871 <filename>/usr/lib/machines/</filename>. For compatibility reasons,
e735f4d4
MP
872 the directory <filename>/var/lib/container/</filename> is
873 searched, too. Note that images stored below
874 <filename>/usr</filename> are always considered read-only. It is
875 possible to symlink machines images from other directories into
876 <filename>/var/lib/machines/</filename> to make them available for
877 control with <command>machinectl</command>.</para>
878
e3bff60a
MP
879 <para>Note that many image operations are only supported,
880 efficient or atomic on btrfs file systems. Due to this, if the
881 <command>pull-tar</command>, <command>pull-raw</command>,
4c89c718
MP
882 <command>import-tar</command>, <command>import-raw</command> and
883 <command>set-limit</command> commands notice that
884 <filename>/var/lib/machines</filename> is empty and not located on
885 btrfs, they will implicitly set up a loopback file
886 <filename>/var/lib/machines.raw</filename> containing a btrfs file
887 system that is mounted to
e3bff60a
MP
888 <filename>/var/lib/machines</filename>. The size of this loopback
889 file may be controlled dynamically with
890 <command>set-limit</command>.</para>
891
e735f4d4
MP
892 <para>Disk images are understood by
893 <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
894 and <command>machinectl</command> in three formats:</para>
895
896 <itemizedlist>
897 <listitem><para>A simple directory tree, containing the files
898 and directories of the container to boot.</para></listitem>
899
db2df898 900 <listitem><para>Subvolumes (on btrfs file systems), which are
e735f4d4
MP
901 similar to the simple directories, described above. However,
902 they have additional benefits, such as efficient cloning and
903 quota reporting.</para></listitem>
904
905 <listitem><para>"Raw" disk images, i.e. binary images of disks
906 with a GPT or MBR partition table. Images of this type are
907 regular files with the suffix
908 <literal>.raw</literal>.</para></listitem>
909 </itemizedlist>
910
911 <para>See
912 <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
db2df898 913 for more information on image formats, in particular its
e735f4d4
MP
914 <option>--directory=</option> and <option>--image=</option>
915 options.</para>
916 </refsect1>
917
918 <refsect1>
919 <title>Examples</title>
920 <example>
921 <title>Download an Ubuntu image and open a shell in it</title>
922
923 <programlisting># machinectl pull-tar https://cloud-images.ubuntu.com/trusty/current/trusty-server-cloudimg-amd64-root.tar.gz
924# systemd-nspawn -M trusty-server-cloudimg-amd64-root</programlisting>
925
926 <para>This downloads and verifies the specified
927 <filename>.tar</filename> image, and then uses
928 <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
929 to open a shell in it.</para>
930 </example>
931
932 <example>
933 <title>Download a Fedora image, set a root password in it, start
934 it as service</title>
935
e3bff60a
MP
936 <programlisting># machinectl pull-raw --verify=no http://ftp.halifax.rwth-aachen.de/fedora/linux/releases/21/Cloud/Images/x86_64/Fedora-Cloud-Base-20141203-21.x86_64.raw.xz
937# systemd-nspawn -M Fedora-Cloud-Base-20141203-21
938# passwd
939# exit
940# machinectl start Fedora-Cloud-Base-20141203-21
941# machinectl login Fedora-Cloud-Base-20141203-21</programlisting>
e735f4d4
MP
942
943 <para>This downloads the specified <filename>.raw</filename>
db2df898 944 image with verification disabled. Then, a shell is opened in it
e735f4d4
MP
945 and a root password is set. Afterwards the shell is left, and
946 the machine started as system service. With the last command a
947 login prompt into the container is requested.</para>
948 </example>
949
e3bff60a
MP
950 <example>
951 <title>Exports a container image as tar file</title>
952
953 <programlisting># machinectl export-tar fedora myfedora.tar.xz</programlisting>
954
db2df898
MP
955 <para>Exports the container <literal>fedora</literal> as an
956 xz-compressed tar file <filename>myfedora.tar.xz</filename> into the
e3bff60a
MP
957 current directory.</para>
958 </example>
959
13d276d0
MP
960 <example>
961 <title>Create a new shell session</title>
962
963 <programlisting># machinectl shell --uid=lennart</programlisting>
964
db2df898 965 <para>This creates a new shell session on the local host for
13d276d0
MP
966 the user ID <literal>lennart</literal>, in a <citerefentry
967 project='die-net'><refentrytitle>su</refentrytitle><manvolnum>1</manvolnum></citerefentry>-like
968 fashion.</para>
969 </example>
970
e735f4d4
MP
971 </refsect1>
972
973 <refsect1>
974 <title>Exit status</title>
975
976 <para>On success, 0 is returned, a non-zero failure code
977 otherwise.</para>
978 </refsect1>
979
980 <xi:include href="less-variables.xml" />
981
982 <refsect1>
983 <title>See Also</title>
984 <para>
985 <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
986 <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
e3bff60a
MP
987 <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
988 <citerefentry project='die-net'><refentrytitle>tar</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
989 <citerefentry project='die-net'><refentrytitle>xz</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
990 <citerefentry project='die-net'><refentrytitle>gzip</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
991 <citerefentry project='die-net'><refentrytitle>bzip2</refentrytitle><manvolnum>1</manvolnum></citerefentry>
e735f4d4
MP
992 </para>
993 </refsect1>
14228c0d
MB
994
995</refentry>