1 <?xml version='1.0'?> <!--*-nxml-*-->
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
6 This file is part of systemd.
8 Copyright 2013 Zbigniew Jędrzejewski-Szmek
10 systemd is free software; you can redistribute it and/or modify it
11 under the terms of the GNU Lesser General Public License as published by
12 the Free Software Foundation; either version 2.1 of the License, or
13 (at your option) any later version.
15 systemd is distributed in the hope that it will be useful, but
16 WITHOUT ANY WARRANTY; without even the implied warranty of
17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18 Lesser General Public License for more details.
20 You should have received a copy of the GNU Lesser General Public License
21 along with systemd; If not, see <http://www.gnu.org/licenses/>.
24 <refentry id="machinectl" conditional='ENABLE_MACHINED'
25 xmlns:xi="http://www.w3.org/2001/XInclude">
28 <title>machinectl</title>
29 <productname>systemd</productname>
33 <contrib>Developer</contrib>
34 <firstname>Lennart</firstname>
35 <surname>Poettering</surname>
36 <email>lennart@poettering.net</email>
42 <refentrytitle>machinectl</refentrytitle>
43 <manvolnum>1</manvolnum>
47 <refname>machinectl</refname>
48 <refpurpose>Control the systemd machine manager</refpurpose>
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>
61 <title>Description</title>
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>
70 <title>Options</title>
72 <para>The following options are understood:</para>
76 <term><option>-p</option></term>
77 <term><option>--property=</option></term>
79 <listitem><para>When showing machine
80 or image properties, limit the output
81 to certain properties as specified by
82 the argument. If not specified, all
83 set properties are shown. The argument
84 should be a property name, such as
85 <literal>Name</literal>. If specified
86 more than once, all properties with
87 the specified names are
88 shown.</para></listitem>
92 <term><option>-a</option></term>
93 <term><option>--all</option></term>
95 <listitem><para>When showing machine
96 or image properties, show all
97 properties regardless of whether they
98 are set or not.</para>
100 <para>When listing VM or container
101 images, do not suppress images
102 beginning in a dot character
103 (<literal>.</literal>).</para></listitem>
107 <term><option>-l</option></term>
108 <term><option>--full</option></term>
110 <listitem><para>Do not ellipsize
111 process tree entries.</para>
116 <term><option>--no-ask-password</option></term>
118 <listitem><para>Do not query the user
119 for authentication for privileged
120 operations.</para></listitem>
124 <term><option>--kill-who=</option></term>
126 <listitem><para>When used with
127 <command>kill</command>,
128 choose which processes to kill. Must
129 be one of <option>leader</option>, or
130 <option>all</option> to select whether
131 to kill only the leader process of the
132 machine or all processes of the
133 machine. If omitted, defaults to
134 <option>all</option>.</para></listitem>
138 <term><option>-s</option></term>
139 <term><option>--signal=</option></term>
141 <listitem><para>When used with
142 <command>kill</command>, choose
143 which signal to send to selected
144 processes. Must be one of the
145 well-known signal specifiers, such as
146 <constant>SIGTERM</constant>,
147 <constant>SIGINT</constant> or
148 <constant>SIGSTOP</constant>. If
150 <constant>SIGTERM</constant>.</para></listitem>
154 <term><option>--no-legend</option></term>
156 <listitem><para>Do not print the legend,
157 i.e. the column headers and the
158 footer.</para></listitem>
162 <term><option>--mkdir</option></term>
164 <listitem><para>When used with
165 <command>bind</command> creates the
166 destination directory before applying
167 the bind mount.</para></listitem>
172 <term><option>--read-only</option></term>
174 <listitem><para>When used with
175 <command>bind</command> applies a
177 mount.</para></listitem>
182 <term><option>-n</option></term>
183 <term><option>--lines=</option></term>
185 <listitem><para>When used with
186 <command>status</command>, controls
187 the number of journal lines to show,
188 counting from the most recent
189 ones. Takes a positive integer
190 argument. Defaults to 10.</para>
195 <term><option>-o</option></term>
196 <term><option>--output=</option></term>
198 <listitem><para>When used with
199 <command>status</command>, controls
200 the formatting of the journal entries
201 that are shown. For the available
203 <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
205 <literal>short</literal>.</para></listitem>
208 <xi:include href="user-system-options.xml" xpointer="host" />
209 <xi:include href="user-system-options.xml" xpointer="machine" />
211 <xi:include href="standard-options.xml" xpointer="help" />
212 <xi:include href="standard-options.xml" xpointer="version" />
213 <xi:include href="standard-options.xml" xpointer="no-pager" />
218 <title>Commands</title>
220 <para>The following commands are understood:</para>
222 <refsect2><title>Machine Commands</title><variablelist>
225 <term><command>list</command></term>
227 <listitem><para>List currently running
228 (online) virtual machines and
229 containers. To enumerate container
230 images that can be started,
231 use <command>list-images</command>
232 (see below).</para></listitem>
236 <term><command>status</command> <replaceable>NAME</replaceable>...</term>
238 <listitem><para>Show terse runtime
239 status information about one or more
240 virtual machines and containers,
241 followed by the most recent log data
242 from the journal. This function is
243 intended to generate human-readable
244 output. If you are looking for
245 computer-parsable output, use
246 <command>show</command> instead. Note
247 that the log data shown is reported by
248 the virtual machine or container
249 manager, and frequently contains
250 console output of the machine, but not
251 necessarily journal contents of the
252 machine itself.</para></listitem>
256 <term><command>show</command> <replaceable>NAME</replaceable>...</term>
258 <listitem><para>Show properties of one
259 or more registered virtual machines or
260 containers or the manager itself. If
261 no argument is specified, properties
262 of the manager will be shown. If an
263 NAME is specified, properties of this
264 virtual machine or container are
265 shown. By default, empty properties
267 <option>--all</option> to show those
268 too. To select specific properties to
270 <option>--property=</option>. This
271 command is intended to be used
272 whenever computer-parsable output is
274 <command>status</command> if you are
275 looking for formatted human-readable
276 output.</para></listitem>
280 <term><command>start</command> <replaceable>NAME</replaceable>...</term>
282 <listitem><para>Start a container as a
283 system service, using
284 <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
286 <filename>systemd-nspawn@.service</filename>,
287 instantiated for the specified machine
288 name, similar to the effect of
289 <command>systemctl start</command> on
291 name. <command>systemd-nspawn</command>
292 looks for a container image by the
294 <filename>/var/lib/machines/</filename>
295 (and other search paths, see below) and runs
296 it. Use <command>list-images</command>
297 (see below), for listing available
298 container images to start.</para>
301 <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
302 also interfaces with a variety of
303 other container and VM managers,
304 <command>systemd-nspawn</command> is
305 just one implementation of it. Most of
306 the commands available in
307 <command>machinectl</command> may be
308 used on containers or VMs controlled
309 by other managers, not just
310 <command>systemd-nspawn</command>. Starting
311 VMs and container images on those
312 managers requires manager-specific
315 <para>To interactively start a
316 container on the command line with
317 full access to the container's
318 console, please invoke
319 <command>systemd-nspawn</command>
320 directly. To stop a running container
321 use <command>machinectl
322 poweroff</command>, see
323 below.</para></listitem>
327 <term><command>login</command> <replaceable>NAME</replaceable></term>
329 <listitem><para>Open an interactive terminal login
330 session to a container. This will
331 create a TTY connection to a specific
332 container and asks for the execution of a
333 getty on it. Note that this is only
334 supported for containers running
335 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
336 as init system.</para>
338 <para>This command will open a full
339 login prompt on the container, which
340 then asks for username and
342 <citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry>
343 with the <option>--machine=</option>
344 switch to invoke a single command,
345 either interactively or in the
346 background within a local
347 container.</para></listitem>
351 <term><command>enable</command> <replaceable>NAME</replaceable>...</term>
352 <term><command>disable</command> <replaceable>NAME</replaceable>...</term>
354 <listitem><para>Enable or disable a
355 container as a system service to start
356 at system boot, using
357 <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
358 This enables or disables
359 <filename>systemd-nspawn@.service</filename>,
360 instantiated for the specified machine
361 name, similar to the effect of
362 <command>systemctl enable</command> or
363 <command>systemctl disable</command>
364 on the service name.</para></listitem>
368 <term><command>poweroff</command> <replaceable>NAME</replaceable>...</term>
370 <listitem><para>Power off one or more
371 containers. This will trigger a reboot
372 by sending SIGRTMIN+4 to the
373 container's init process, which causes
374 systemd-compatible init systems to
375 shut down cleanly. This operation does
376 not work on containers that do not run
378 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>-compatible
379 init system, such as sysvinit. Use
380 <command>terminate</command> (see
381 below) to immediately terminate a
382 container or VM, without cleanly
383 shutting it down.</para></listitem>
387 <term><command>reboot</command> <replaceable>NAME</replaceable>...</term>
389 <listitem><para>Reboot one or more
390 containers. This will trigger a reboot
391 by sending SIGINT to the container's
392 init process, which is roughly
393 equivalent to pressing Ctrl+Alt+Del on
394 a non-containerized system, and is
395 compatible with containers running any
396 system manager.</para></listitem>
400 <term><command>terminate</command> <replaceable>NAME</replaceable>...</term>
402 <listitem><para>Immediately terminates
403 a virtual machine or container,
404 without cleanly shutting it down. This
405 kills all processes of the virtual
406 machine or container and deallocates
407 all resources attached to that
409 <command>poweroff</command> to issue a
410 clean shutdown request.</para></listitem>
414 <term><command>kill</command> <replaceable>NAME</replaceable>...</term>
416 <listitem><para>Send a signal to one
417 or more processes of the virtual
418 machine or container. This means
419 processes as seen by the host, not the
420 processes inside the virtual machine
422 Use <option>--kill-who=</option> to
423 select which process to kill. Use
424 <option>--signal=</option> to select
425 the signal to send.</para></listitem>
429 <term><command>bind</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term>
431 <listitem><para>Bind mounts a
432 directory from the host into the
433 specified container. The first
434 directory argument is the source
435 directory on the host, the second
436 directory argument the source
437 directory on the host. When the latter
438 is omitted the destination path in the
439 container is the same as the source
440 path on the host. When combined with
441 the <option>--read-only</option>
442 switch a ready-only bind mount is
443 created. When combined with the
444 <option>--mkdir</option> switch the
445 destination path is first created
446 before the mount is applied. Note that
447 this option is currently only
449 <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
450 containers.</para></listitem>
454 <term><command>copy-to</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term>
456 <listitem><para>Copies files or
457 directories from the host system into
458 a running container. Takes a container
459 name, followed by the source path on
460 the host and the destination path in
461 the container. If the destination path
462 is omitted the same as the source path
463 is used.</para></listitem>
468 <term><command>copy-from</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term>
470 <listitem><para>Copies files or
471 directories from a container into the
472 host system. Takes a container name,
473 followed by the source path in the
474 container the destination path on the
475 host. If the destination path is
476 omitted the same as the source path is
477 used.</para></listitem>
479 </variablelist></refsect2>
481 <refsect2><title>Image Commands</title><variablelist>
484 <term><command>list-images</command></term>
486 <listitem><para>Show a list of locally
487 installed container and VM
488 images. This enumerates all raw disk
489 images and container directories and
491 <filename>/var/lib/machines/</filename> (and other search paths, see below). Use
492 <command>start</command> (see above)
493 to run a container off one of the
494 listed images. Note that by default
495 containers whose name begins with a
496 dot (<literal>.</literal>) are not
497 shown. To show these too, specify
498 <option>--all</option>. Note that a
499 special image <literal>.host</literal>
500 always implicitly exists and refers to
501 the image the host itself is booted
502 from.</para></listitem>
506 <term><command>image-status</command> <replaceable>NAME</replaceable>...</term>
508 <listitem><para>Show terse status
509 information about one or more
510 container or VM images. This function
511 is intended to generate human-readable
513 <command>show-image</command> (see
514 below) to generate computer-parsable
515 output instead.</para></listitem>
519 <term><command>show-image</command> <replaceable>NAME</replaceable>...</term>
521 <listitem><para>Show properties of one
522 or more registered virtual machine or
523 container images, or the manager
524 itself. If no argument is specified,
525 properties of the manager will be
526 shown. If an NAME is specified,
527 properties of this virtual machine or
528 container image are shown. By default,
529 empty properties are suppressed. Use
530 <option>--all</option> to show those
531 too. To select specific properties to
533 <option>--property=</option>. This
534 command is intended to be used
535 whenever computer-parsable output is
537 <command>image-status</command> if you
538 are looking for formatted
540 output.</para></listitem>
544 <term><command>clone</command> <replaceable>NAME</replaceable> <replaceable>NAME</replaceable></term>
546 <listitem><para>Clones a container or
547 disk image. The arguments specify the
548 name of the image to clone and the
549 name of the newly cloned image. Note
550 that plain directory container images
551 are cloned into subvolume images with
552 this command. Note that cloning a
553 container or VM image is optimized for
554 btrfs file systems, and might not be
555 efficient on others, due to file
556 system limitations.</para></listitem>
560 <term><command>rename</command> <replaceable>NAME</replaceable> <replaceable>NAME</replaceable></term>
562 <listitem><para>Renames a container or
563 disk image. The arguments specify the
564 name of the image to rename and the
566 image.</para></listitem>
570 <term><command>read-only</command> <replaceable>NAME</replaceable> [<replaceable>BOOL</replaceable>]</term>
572 <listitem><para>Marks or (unmarks) a
573 container or disk image
574 read-only. Takes a VM or container
575 image name, followed by a boolean as
576 arguments. If the boolean is omitted,
577 positive is implied, i.e. the image is
578 marked read-only.</para></listitem>
583 <term><command>remove</command> <replaceable>NAME</replaceable>...</term>
585 <listitem><para>Removes one or more
586 container or disk images. The special
587 image <literal>.host</literal>, which
588 refers to the host's own directory
590 removed.</para></listitem>
594 </variablelist></refsect2>
599 <title>Files and Directories</title>
601 <para>Machine images are preferably stored in
602 <filename>/var/lib/machines/</filename>, but are also
604 <filename>/usr/local/lib/machines/</filename> and
605 <filename>/usr/lib/machines/</filename>. For
606 compatibility reasons the directory
607 <filename>/var/lib/container/</filename> is searched,
608 too. Note that images stored below
609 <filename>/usr</filename> are always considered
610 read-only. It is possible to symlink machines images
611 from other directories into
612 <filename>/var/lib/machines/</filename> to make them
613 available for control with
614 <command>machinectl</command>.</para>
616 <para>Disk images are understood in three formats:</para>
619 <listitem><para>A simple directory tree,
620 containing the files and directories of the
621 container to boot.</para></listitem>
623 <listitem><para>A subvolume (on btrfs file
624 systems), which are similar to the simple
625 directories, described above. However, they
626 have additional benefits, such as efficient
627 cloning and quota reporting.</para></listitem>
629 <listitem><para>"Raw" disk images, i.e. binary
630 images of disks with a GPT or MBR partition
631 table. Images of this type are regular
632 files with the suffix
633 <literal>.raw</literal>.</para></listitem>
637 <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
638 for more information on image formats, in particular
639 it's <option>--directory=</option> and
640 <option>--image=</option> options.</para>
644 <title>Exit status</title>
646 <para>On success, 0 is returned, a non-zero failure
647 code otherwise.</para>
650 <xi:include href="less-variables.xml" />
653 <title>See Also</title>
655 <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
656 <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
657 <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>