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