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>--mkdir</option></term>
156 <listitem><para>When used with
157 <command>bind</command> creates the
158 destination directory before applying
159 the bind mount.</para></listitem>
164 <term><option>--read-only</option></term>
166 <listitem><para>When used with
167 <command>bind</command> applies a
169 mount.</para></listitem>
174 <term><option>-n</option></term>
175 <term><option>--lines=</option></term>
177 <listitem><para>When used with
178 <command>status</command>, controls
179 the number of journal lines to show,
180 counting from the most recent
181 ones. Takes a positive integer
182 argument. Defaults to 10.</para>
187 <term><option>-o</option></term>
188 <term><option>--output=</option></term>
190 <listitem><para>When used with
191 <command>status</command>, controls
192 the formatting of the journal entries
193 that are shown. For the available
195 <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
197 <literal>short</literal>.</para></listitem>
200 <xi:include href="user-system-options.xml" xpointer="host" />
201 <xi:include href="user-system-options.xml" xpointer="machine" />
203 <xi:include href="standard-options.xml" xpointer="no-pager" />
204 <xi:include href="standard-options.xml" xpointer="no-legend" />
205 <xi:include href="standard-options.xml" xpointer="help" />
206 <xi:include href="standard-options.xml" xpointer="version" />
211 <title>Commands</title>
213 <para>The following commands are understood:</para>
215 <refsect2><title>Machine Commands</title><variablelist>
218 <term><command>list</command></term>
220 <listitem><para>List currently running
221 (online) virtual machines and
222 containers. To enumerate container
223 images that can be started,
224 use <command>list-images</command>
225 (see below).</para></listitem>
229 <term><command>status</command> <replaceable>NAME</replaceable>...</term>
231 <listitem><para>Show terse runtime
232 status information about one or more
233 virtual machines and containers,
234 followed by the most recent log data
235 from the journal. This function is
236 intended to generate human-readable
237 output. If you are looking for
238 computer-parsable output, use
239 <command>show</command> instead. Note
240 that the log data shown is reported by
241 the virtual machine or container
242 manager, and frequently contains
243 console output of the machine, but not
244 necessarily journal contents of the
245 machine itself.</para></listitem>
249 <term><command>show</command> <replaceable>NAME</replaceable>...</term>
251 <listitem><para>Show properties of one
252 or more registered virtual machines or
253 containers or the manager itself. If
254 no argument is specified, properties
255 of the manager will be shown. If an
256 NAME is specified, properties of this
257 virtual machine or container are
258 shown. By default, empty properties
260 <option>--all</option> to show those
261 too. To select specific properties to
263 <option>--property=</option>. This
264 command is intended to be used
265 whenever computer-parsable output is
267 <command>status</command> if you are
268 looking for formatted human-readable
269 output.</para></listitem>
273 <term><command>start</command> <replaceable>NAME</replaceable>...</term>
275 <listitem><para>Start a container as a
276 system service, using
277 <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
279 <filename>systemd-nspawn@.service</filename>,
280 instantiated for the specified machine
281 name, similar to the effect of
282 <command>systemctl start</command> on
284 name. <command>systemd-nspawn</command>
285 looks for a container image by the
287 <filename>/var/lib/machines/</filename>
288 (and other search paths, see below) and runs
289 it. Use <command>list-images</command>
290 (see below), for listing available
291 container images to start.</para>
294 <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
295 also interfaces with a variety of
296 other container and VM managers,
297 <command>systemd-nspawn</command> is
298 just one implementation of it. Most of
299 the commands available in
300 <command>machinectl</command> may be
301 used on containers or VMs controlled
302 by other managers, not just
303 <command>systemd-nspawn</command>. Starting
304 VMs and container images on those
305 managers requires manager-specific
308 <para>To interactively start a
309 container on the command line with
310 full access to the container's
311 console, please invoke
312 <command>systemd-nspawn</command>
313 directly. To stop a running container
314 use <command>machinectl
315 poweroff</command>, see
316 below.</para></listitem>
320 <term><command>login</command> <replaceable>NAME</replaceable></term>
322 <listitem><para>Open an interactive terminal login
323 session to a container. This will
324 create a TTY connection to a specific
325 container and asks for the execution of a
326 getty on it. Note that this is only
327 supported for containers running
328 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
329 as init system.</para>
331 <para>This command will open a full
332 login prompt on the container, which
333 then asks for username and
335 <citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry>
336 with the <option>--machine=</option>
337 switch to invoke a single command,
338 either interactively or in the
339 background within a local
340 container.</para></listitem>
344 <term><command>enable</command> <replaceable>NAME</replaceable>...</term>
345 <term><command>disable</command> <replaceable>NAME</replaceable>...</term>
347 <listitem><para>Enable or disable a
348 container as a system service to start
349 at system boot, using
350 <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
351 This enables or disables
352 <filename>systemd-nspawn@.service</filename>,
353 instantiated for the specified machine
354 name, similar to the effect of
355 <command>systemctl enable</command> or
356 <command>systemctl disable</command>
357 on the service name.</para></listitem>
361 <term><command>poweroff</command> <replaceable>NAME</replaceable>...</term>
363 <listitem><para>Power off one or more
364 containers. This will trigger a reboot
365 by sending SIGRTMIN+4 to the
366 container's init process, which causes
367 systemd-compatible init systems to
368 shut down cleanly. This operation does
369 not work on containers that do not run
371 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>-compatible
372 init system, such as sysvinit. Use
373 <command>terminate</command> (see
374 below) to immediately terminate a
375 container or VM, without cleanly
376 shutting it down.</para></listitem>
380 <term><command>reboot</command> <replaceable>NAME</replaceable>...</term>
382 <listitem><para>Reboot one or more
383 containers. This will trigger a reboot
384 by sending SIGINT to the container's
385 init process, which is roughly
386 equivalent to pressing Ctrl+Alt+Del on
387 a non-containerized system, and is
388 compatible with containers running any
389 system manager.</para></listitem>
393 <term><command>terminate</command> <replaceable>NAME</replaceable>...</term>
395 <listitem><para>Immediately terminates
396 a virtual machine or container,
397 without cleanly shutting it down. This
398 kills all processes of the virtual
399 machine or container and deallocates
400 all resources attached to that
402 <command>poweroff</command> to issue a
403 clean shutdown request.</para></listitem>
407 <term><command>kill</command> <replaceable>NAME</replaceable>...</term>
409 <listitem><para>Send a signal to one
410 or more processes of the virtual
411 machine or container. This means
412 processes as seen by the host, not the
413 processes inside the virtual machine
415 Use <option>--kill-who=</option> to
416 select which process to kill. Use
417 <option>--signal=</option> to select
418 the signal to send.</para></listitem>
422 <term><command>bind</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term>
424 <listitem><para>Bind mounts a
425 directory from the host into the
426 specified container. The first
427 directory argument is the source
428 directory on the host, the second
429 directory argument the source
430 directory on the host. When the latter
431 is omitted the destination path in the
432 container is the same as the source
433 path on the host. When combined with
434 the <option>--read-only</option>
435 switch a ready-only bind mount is
436 created. When combined with the
437 <option>--mkdir</option> switch the
438 destination path is first created
439 before the mount is applied. Note that
440 this option is currently only
442 <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
443 containers.</para></listitem>
447 <term><command>copy-to</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term>
449 <listitem><para>Copies files or
450 directories from the host system into
451 a running container. Takes a container
452 name, followed by the source path on
453 the host and the destination path in
454 the container. If the destination path
455 is omitted the same as the source path
456 is used.</para></listitem>
461 <term><command>copy-from</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term>
463 <listitem><para>Copies files or
464 directories from a container into the
465 host system. Takes a container name,
466 followed by the source path in the
467 container the destination path on the
468 host. If the destination path is
469 omitted the same as the source path is
470 used.</para></listitem>
472 </variablelist></refsect2>
474 <refsect2><title>Image Commands</title><variablelist>
477 <term><command>list-images</command></term>
479 <listitem><para>Show a list of locally
480 installed container and VM
481 images. This enumerates all raw disk
482 images and container directories and
484 <filename>/var/lib/machines/</filename> (and other search paths, see below). Use
485 <command>start</command> (see above)
486 to run a container off one of the
487 listed images. Note that by default
488 containers whose name begins with a
489 dot (<literal>.</literal>) are not
490 shown. To show these too, specify
491 <option>--all</option>. Note that a
492 special image <literal>.host</literal>
493 always implicitly exists and refers to
494 the image the host itself is booted
495 from.</para></listitem>
499 <term><command>image-status</command> <replaceable>NAME</replaceable>...</term>
501 <listitem><para>Show terse status
502 information about one or more
503 container or VM images. This function
504 is intended to generate human-readable
506 <command>show-image</command> (see
507 below) to generate computer-parsable
508 output instead.</para></listitem>
512 <term><command>show-image</command> <replaceable>NAME</replaceable>...</term>
514 <listitem><para>Show properties of one
515 or more registered virtual machine or
516 container images, or the manager
517 itself. If no argument is specified,
518 properties of the manager will be
519 shown. If an NAME is specified,
520 properties of this virtual machine or
521 container image are shown. By default,
522 empty properties are suppressed. Use
523 <option>--all</option> to show those
524 too. To select specific properties to
526 <option>--property=</option>. This
527 command is intended to be used
528 whenever computer-parsable output is
530 <command>image-status</command> if you
531 are looking for formatted
533 output.</para></listitem>
537 <term><command>clone</command> <replaceable>NAME</replaceable> <replaceable>NAME</replaceable></term>
539 <listitem><para>Clones a container or
540 disk image. The arguments specify the
541 name of the image to clone and the
542 name of the newly cloned image. Note
543 that plain directory container images
544 are cloned into subvolume images with
545 this command. Note that cloning a
546 container or VM image is optimized for
547 btrfs file systems, and might not be
548 efficient on others, due to file
549 system limitations.</para></listitem>
553 <term><command>rename</command> <replaceable>NAME</replaceable> <replaceable>NAME</replaceable></term>
555 <listitem><para>Renames a container or
556 disk image. The arguments specify the
557 name of the image to rename and the
559 image.</para></listitem>
563 <term><command>read-only</command> <replaceable>NAME</replaceable> [<replaceable>BOOL</replaceable>]</term>
565 <listitem><para>Marks or (unmarks) a
566 container or disk image
567 read-only. Takes a VM or container
568 image name, followed by a boolean as
569 arguments. If the boolean is omitted,
570 positive is implied, i.e. the image is
571 marked read-only.</para></listitem>
576 <term><command>remove</command> <replaceable>NAME</replaceable>...</term>
578 <listitem><para>Removes one or more
579 container or disk images. The special
580 image <literal>.host</literal>, which
581 refers to the host's own directory
583 removed.</para></listitem>
587 </variablelist></refsect2>
592 <title>Files and Directories</title>
594 <para>Machine images are preferably stored in
595 <filename>/var/lib/machines/</filename>, but are also
597 <filename>/usr/local/lib/machines/</filename> and
598 <filename>/usr/lib/machines/</filename>. For
599 compatibility reasons the directory
600 <filename>/var/lib/container/</filename> is searched,
601 too. Note that images stored below
602 <filename>/usr</filename> are always considered
603 read-only. It is possible to symlink machines images
604 from other directories into
605 <filename>/var/lib/machines/</filename> to make them
606 available for control with
607 <command>machinectl</command>.</para>
609 <para>Disk images are understood in three formats:</para>
612 <listitem><para>A simple directory tree,
613 containing the files and directories of the
614 container to boot.</para></listitem>
616 <listitem><para>A subvolume (on btrfs file
617 systems), which are similar to the simple
618 directories, described above. However, they
619 have additional benefits, such as efficient
620 cloning and quota reporting.</para></listitem>
622 <listitem><para>"Raw" disk images, i.e. binary
623 images of disks with a GPT or MBR partition
624 table. Images of this type are regular
625 files with the suffix
626 <literal>.raw</literal>.</para></listitem>
630 <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
631 for more information on image formats, in particular
632 it's <option>--directory=</option> and
633 <option>--image=</option> options.</para>
637 <title>Exit status</title>
639 <para>On success, 0 is returned, a non-zero failure
640 code otherwise.</para>
643 <xi:include href="less-variables.xml" />
646 <title>See Also</title>
648 <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
649 <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
650 <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>