1MACHINECTL(1)                     machinectl                     MACHINECTL(1)
2
3
4

NAME

6       machinectl - Control the systemd machine manager
7

SYNOPSIS

9       machinectl [OPTIONS...] {COMMAND} [NAME...]
10

DESCRIPTION

12       machinectl may be used to introspect and control the state of the
13       systemd(1) virtual machine and container registration manager systemd-
14       machined.service(8).
15
16       machinectl may be used to execute operations on machines and images.
17       Machines in this sense are considered running instances of:
18
19       ·   Virtual Machines (VMs) that virtualize hardware to run full
20           operating system (OS) instances (including their kernels) in a
21           virtualized environment on top of the host OS.
22
23       ·   Containers that share the hardware and OS kernel with the host OS,
24           in order to run OS userspace instances on top the host OS.
25
26       ·   The host system itself.
27
28       Machines are identified by names that follow the same rules as UNIX and
29       DNS host names. For details, see below.
30
31       Machines are instantiated from disk or file system images that
32       frequently — but not necessarily — carry the same name as machines
33       running from them. Images in this sense may be:
34
35       ·   Directory trees containing an OS, including the top-level
36           directories /usr, /etc, and so on.
37
38       ·   btrfs subvolumes containing OS trees, similar to normal directory
39           trees.
40
41       ·   Binary "raw" disk images containing MBR or GPT partition tables and
42           Linux file system partitions.
43
44       ·   The file system tree of the host OS itself.
45

OPTIONS

47       The following options are understood:
48
49       -p, --property=
50           When showing machine or image properties, limit the output to
51           certain properties as specified by the argument. If not specified,
52           all set properties are shown. The argument should be a property
53           name, such as "Name". If specified more than once, all properties
54           with the specified names are shown.
55
56       -a, --all
57           When showing machine or image properties, show all properties
58           regardless of whether they are set or not.
59
60           When listing VM or container images, do not suppress images
61           beginning in a dot character (".").
62
63           When cleaning VM or container images, remove all images, not just
64           hidden ones.
65
66       --value
67           When printing properties with show, only print the value, and skip
68           the property name and "=".
69
70       -l, --full
71           Do not ellipsize process tree entries.
72
73       --kill-who=
74           When used with kill, choose which processes to kill. Must be one of
75           leader, or all to select whether to kill only the leader process of
76           the machine or all processes of the machine. If omitted, defaults
77           to all.
78
79       -s, --signal=
80           When used with kill, choose which signal to send to selected
81           processes. Must be one of the well-known signal specifiers, such as
82           SIGTERM, SIGINT or SIGSTOP. If omitted, defaults to SIGTERM.
83
84       --uid=
85           When used with the shell command, chooses the user ID to open the
86           interactive shell session as. If the argument to the shell command
87           also specifies a user name, this option is ignored. If the name is
88           not specified in either way, "root" will be used by default. Note
89           that this switch is not supported for the login command (see
90           below).
91
92       -E NAME=VALUE, --setenv=NAME=VALUE
93           When used with the shell command, sets an environment variable to
94           pass to the executed shell. Takes an environment variable name and
95           value, separated by "=". This switch may be used multiple times to
96           set multiple environment variables. Note that this switch is not
97           supported for the login command (see below).
98
99       --mkdir
100           When used with bind, creates the destination file or directory
101           before applying the bind mount. Note that even though the name of
102           this option suggests that it is suitable only for directories, this
103           option also creates the destination file node to mount over if the
104           object to mount is not a directory, but a regular file, device
105           node, socket or FIFO.
106
107       --read-only
108           When used with bind, creates a read-only bind mount.
109
110           When used with clone, import-raw or import-tar a read-only
111           container or VM image is created.
112
113       -n, --lines=
114           When used with status, controls the number of journal lines to
115           show, counting from the most recent ones. Takes a positive integer
116           argument. Defaults to 10.
117
118       -o, --output=
119           When used with status, controls the formatting of the journal
120           entries that are shown. For the available choices, see
121           journalctl(1). Defaults to "short".
122
123       --verify=
124           When downloading a container or VM image, specify whether the image
125           shall be verified before it is made available. Takes one of "no",
126           "checksum" and "signature". If "no", no verification is done. If
127           "checksum" is specified, the download is checked for integrity
128           after the transfer is complete, but no signatures are verified. If
129           "signature" is specified, the checksum is verified and the image's
130           signature is checked against a local keyring of trustable vendors.
131           It is strongly recommended to set this option to "signature" if the
132           server and protocol support this. Defaults to "signature".
133
134       --force
135           When downloading a container or VM image, and a local copy by the
136           specified local machine name already exists, delete it first and
137           replace it by the newly downloaded image.
138
139       --format=
140           When used with the export-tar or export-raw commands, specifies the
141           compression format to use for the resulting file. Takes one of
142           "uncompressed", "xz", "gzip", "bzip2". By default, the format is
143           determined automatically from the image file name passed.
144
145       --max-addresses=
146           When used with the list-machines command, limits the number of ip
147           addresses output for every machine. Defaults to 1. All addresses
148           can be requested with "all" as argument to --max-addresses . If the
149           argument to --max-addresses is less than the actual number of
150           addresses, "..."follows the last address. If multiple addresses are
151           to be written for a given machine, every address except the first
152           one is on a new line and is followed by "," if another address will
153           be output afterwards.
154
155       -q, --quiet
156           Suppresses additional informational output while running.
157
158       -H, --host=
159           Execute the operation remotely. Specify a hostname, or a username
160           and hostname separated by "@", to connect to. The hostname may
161           optionally be suffixed by a container name, separated by ":", which
162           connects directly to a specific container on the specified host.
163           This will use SSH to talk to the remote machine manager instance.
164           Container names may be enumerated with machinectl -H HOST.
165
166       -M, --machine=
167           Connect to systemd-machined.service(8) running in a local
168           container, to perform the specified operation within the container.
169
170       --no-pager
171           Do not pipe output into a pager.
172
173       --no-legend
174           Do not print the legend, i.e. column headers and the footer with
175           hints.
176
177       --no-ask-password
178           Do not query the user for authentication for privileged operations.
179
180       -h, --help
181           Print a short help text and exit.
182
183       --version
184           Print a short version string and exit.
185

COMMANDS

187       The following commands are understood:
188
189   Machine Commands
190       list
191           List currently running (online) virtual machines and containers. To
192           enumerate machine images that can be started, use list-images (see
193           below). Note that this command hides the special ".host" machine by
194           default. Use the --all switch to show it.
195
196       status NAME...
197           Show runtime status information about one or more virtual machines
198           and containers, followed by the most recent log data from the
199           journal. This function is intended to generate human-readable
200           output. If you are looking for computer-parsable output, use show
201           instead. Note that the log data shown is reported by the virtual
202           machine or container manager, and frequently contains console
203           output of the machine, but not necessarily journal contents of the
204           machine itself.
205
206       show [NAME...]
207           Show properties of one or more registered virtual machines or
208           containers or the manager itself. If no argument is specified,
209           properties of the manager will be shown. If a NAME is specified,
210           properties of this virtual machine or container are shown. By
211           default, empty properties are suppressed. Use --all to show those
212           too. To select specific properties to show, use --property=. This
213           command is intended to be used whenever computer-parsable output is
214           required, and does not print the control group tree or journal
215           entries. Use status if you are looking for formatted human-readable
216           output.
217
218       start NAME...
219           Start a container as a system service, using systemd-nspawn(1).
220           This starts systemd-nspawn@.service, instantiated for the specified
221           machine name, similar to the effect of systemctl start on the
222           service name.  systemd-nspawn looks for a container image by the
223           specified name in /var/lib/machines/ (and other search paths, see
224           below) and runs it. Use list-images (see below) for listing
225           available container images to start.
226
227           Note that systemd-machined.service(8) also interfaces with a
228           variety of other container and VM managers, systemd-nspawn is just
229           one implementation of it. Most of the commands available in
230           machinectl may be used on containers or VMs controlled by other
231           managers, not just systemd-nspawn. Starting VMs and container
232           images on those managers requires manager-specific tools.
233
234           To interactively start a container on the command line with full
235           access to the container's console, please invoke systemd-nspawn
236           directly. To stop a running container use machinectl poweroff.
237
238       login [NAME]
239           Open an interactive terminal login session in a container or on the
240           local host. If an argument is supplied, it refers to the container
241           machine to connect to. If none is specified, or the container name
242           is specified as the empty string, or the special machine name
243           ".host" (see below) is specified, the connection is made to the
244           local host instead. This will create a TTY connection to a specific
245           container or the local host and asks for the execution of a getty
246           on it. Note that this is only supported for containers running
247           systemd(1) as init system.
248
249           This command will open a full login prompt on the container or the
250           local host, which then asks for username and password. Use shell
251           (see below) or systemd-run(1) with the --machine= switch to
252           directly invoke a single command, either interactively or in the
253           background.
254
255       shell [[NAME@]NAME [PATH [ARGUMENTS...]]]
256           Open an interactive shell session in a container or on the local
257           host. The first argument refers to the container machine to connect
258           to. If none is specified, or the machine name is specified as the
259           empty string, or the special machine name ".host" (see below) is
260           specified, the connection is made to the local host instead. This
261           works similar to login but immediately invokes a user process. This
262           command runs the specified executable with the specified arguments,
263           or the default shell for the user if none is specified, or /bin/sh
264           if no default shell is found. By default, --uid=, or by prefixing
265           the machine name with a username and an "@" character, a different
266           user may be selected. Use --setenv= to set environment variables
267           for the executed process.
268
269           Note that machinectl shell does not propagate the exit code/status
270           of the invoked shell process. Use systemd-run instead if that
271           information is required (see below).
272
273           When using the shell command without arguments, (thus invoking the
274           executed shell or command on the local host), it is in many ways
275           similar to a su(1) session, but, unlike su, completely isolates the
276           new session from the originating session, so that it shares no
277           process or session properties, and is in a clean and well-defined
278           state. It will be tracked in a new utmp, login, audit, security and
279           keyring session, and will not inherit any environment variables or
280           resource limits, among other properties.
281
282           Note that systemd-run(1) with its --machine= switch may be used in
283           place of the machinectl shell command, and allows non-interactive
284           operation, more detailed and low-level configuration of the invoked
285           unit, as well as access to runtime and exit code/status information
286           of the invoked shell process. In particular, use systemd-run's
287           --wait switch to propagate exit status information of the invoked
288           process. Use systemd-run's --pty switch for acquiring an
289           interactive shell, similar to machinectl shell. In general,
290           systemd-run is preferable for scripting purposes. However, note
291           that systemd-run might require higher privileges than machinectl
292           shell.
293
294       enable NAME..., disable NAME...
295           Enable or disable a container as a system service to start at
296           system boot, using systemd-nspawn(1). This enables or disables
297           systemd-nspawn@.service, instantiated for the specified machine
298           name, similar to the effect of systemctl enable or systemctl
299           disable on the service name.
300
301       poweroff NAME...
302           Power off one or more containers. This will trigger a reboot by
303           sending SIGRTMIN+4 to the container's init process, which causes
304           systemd-compatible init systems to shut down cleanly. Use stop as
305           alias for poweroff. This operation does not work on containers that
306           do not run a systemd(1)-compatible init system, such as sysvinit.
307           Use terminate (see below) to immediately terminate a container or
308           VM, without cleanly shutting it down.
309
310       reboot NAME...
311           Reboot one or more containers. This will trigger a reboot by
312           sending SIGINT to the container's init process, which is roughly
313           equivalent to pressing Ctrl+Alt+Del on a non-containerized system,
314           and is compatible with containers running any system manager.
315
316       terminate NAME...
317           Immediately terminates a virtual machine or container, without
318           cleanly shutting it down. This kills all processes of the virtual
319           machine or container and deallocates all resources attached to that
320           instance. Use poweroff to issue a clean shutdown request.
321
322       kill NAME...
323           Send a signal to one or more processes of the virtual machine or
324           container. This means processes as seen by the host, not the
325           processes inside the virtual machine or container. Use --kill-who=
326           to select which process to kill. Use --signal= to select the signal
327           to send.
328
329       bind NAME PATH [PATH]
330           Bind mounts a file or directory from the host into the specified
331           container. The first path argument is the source file or directory
332           on the host, the second path argument is the destination file or
333           directory in the container. When the latter is omitted, the
334           destination path in the container is the same as the source path on
335           the host. When combined with the --read-only switch, a ready-only
336           bind mount is created. When combined with the --mkdir switch, the
337           destination path is first created before the mount is applied. Note
338           that this option is currently only supported for systemd-nspawn(1)
339           containers, and only if user namespacing (--private-users) is not
340           used. This command supports bind mounting directories, regular
341           files, device nodes, AF_UNIX socket nodes, as well as FIFOs.
342
343       copy-to NAME PATH [PATH]
344           Copies files or directories from the host system into a running
345           container. Takes a container name, followed by the source path on
346           the host and the destination path in the container. If the
347           destination path is omitted, the same as the source path is used.
348
349           If host and container share the same user and group namespace, file
350           ownership by numeric user ID and group ID is preserved for the
351           copy, otherwise all files and directories in the copy will be owned
352           by the root user and group (UID/GID 0).
353
354       copy-from NAME PATH [PATH]
355           Copies files or directories from a container into the host system.
356           Takes a container name, followed by the source path in the
357           container the destination path on the host. If the destination path
358           is omitted, the same as the source path is used.
359
360           If host and container share the same user and group namespace, file
361           ownership by numeric user ID and group ID is preserved for the
362           copy, otherwise all files and directories in the copy will be owned
363           by the root user and group (UID/GID 0).
364
365   Image Commands
366       list-images
367           Show a list of locally installed container and VM images. This
368           enumerates all raw disk images and container directories and
369           subvolumes in /var/lib/machines/ (and other search paths, see
370           below). Use start (see above) to run a container off one of the
371           listed images. Note that, by default, containers whose name begins
372           with a dot (".") are not shown. To show these too, specify --all.
373           Note that a special image ".host" always implicitly exists and
374           refers to the image the host itself is booted from.
375
376       image-status [NAME...]
377           Show terse status information about one or more container or VM
378           images. This function is intended to generate human-readable
379           output. Use show-image (see below) to generate computer-parsable
380           output instead.
381
382       show-image [NAME...]
383           Show properties of one or more registered virtual machine or
384           container images, or the manager itself. If no argument is
385           specified, properties of the manager will be shown. If a NAME is
386           specified, properties of this virtual machine or container image
387           are shown. By default, empty properties are suppressed. Use --all
388           to show those too. To select specific properties to show, use
389           --property=. This command is intended to be used whenever
390           computer-parsable output is required. Use image-status if you are
391           looking for formatted human-readable output.
392
393       clone NAME NAME
394           Clones a container or VM image. The arguments specify the name of
395           the image to clone and the name of the newly cloned image. Note
396           that plain directory container images are cloned into btrfs
397           subvolume images with this command, if the underlying file system
398           supports this. Note that cloning a container or VM image is
399           optimized for file systems that support copy-on-write, and might
400           not be efficient on others, due to file system limitations.
401
402           Note that this command leaves host name, machine ID and all other
403           settings that could identify the instance unmodified. The original
404           image and the cloned copy will hence share these credentials, and
405           it might be necessary to manually change them in the copy.
406
407           If combined with the --read-only switch a read-only cloned image is
408           created.
409
410       rename NAME NAME
411           Renames a container or VM image. The arguments specify the name of
412           the image to rename and the new name of the image.
413
414       read-only NAME [BOOL]
415           Marks or (unmarks) a container or VM image read-only. Takes a VM or
416           container image name, followed by a boolean as arguments. If the
417           boolean is omitted, positive is implied, i.e. the image is marked
418           read-only.
419
420       remove NAME...
421           Removes one or more container or VM images. The special image
422           ".host", which refers to the host's own directory tree, may not be
423           removed.
424
425       set-limit [NAME] BYTES
426           Sets the maximum size in bytes that a specific container or VM
427           image, or all images, may grow up to on disk (disk quota). Takes
428           either one or two parameters. The first, optional parameter refers
429           to a container or VM image name. If specified, the size limit of
430           the specified image is changed. If omitted, the overall size limit
431           of the sum of all images stored locally is changed. The final
432           argument specifies the size limit in bytes, possibly suffixed by
433           the usual K, M, G, T units. If the size limit shall be disabled,
434           specify "-" as size.
435
436           Note that per-container size limits are only supported on btrfs
437           file systems. Also note that, if set-limit is invoked without an
438           image parameter, and /var/lib/machines is empty, and the directory
439           is not located on btrfs, a btrfs loopback file is implicitly
440           created as /var/lib/machines.raw with the given size, and mounted
441           to /var/lib/machines. The size of the loopback may later be
442           readjusted with set-limit, as well. If such a loopback-mounted
443           /var/lib/machines directory is used, set-limit without an image
444           name alters both the quota setting within the file system as well
445           as the loopback file and file system size itself.
446
447       clean
448           Remove hidden VM or container images (or all). This command removes
449           all hidden machine images from /var/lib/machines, i.e. those whose
450           name begins with a dot. Use machinectl list-images --all to see a
451           list of all machine images, including the hidden ones.
452
453           When combined with the --all switch removes all images, not just
454           hidden ones. This command effectively empties /var/lib/machines.
455
456           Note that commands such as machinectl pull-tar or machinectl
457           pull-raw usually create hidden, read-only, unmodified machine
458           images from the downloaded image first, before cloning a writable
459           working copy of it, in order to avoid duplicate downloads in case
460           of images that are reused multiple times. Use machinectl clean to
461           remove old, hidden images created this way.
462
463   Image Transfer Commands
464       pull-tar URL [NAME]
465           Downloads a .tar container image from the specified URL, and makes
466           it available under the specified local machine name. The URL must
467           be of type "http://" or "https://", and must refer to a .tar,
468           .tar.gz, .tar.xz or .tar.bz2 archive file. If the local machine
469           name is omitted, it is automatically derived from the last
470           component of the URL, with its suffix removed.
471
472           The image is verified before it is made available, unless
473           --verify=no is specified. Verification is done either via an inline
474           signed file with the name of the image and the suffix .sha256 or
475           via separate SHA256SUMS and SHA256SUMS.gpg files. The signature
476           files need to be made available on the same web server, under the
477           same URL as the .tar file. With --verify=checksum, only the SHA256
478           checksum for the file is verified, based on the .sha256 suffixed
479           file or theSHA256SUMS file. With --verify=signature, the sha
480           checksum file is first verified with the inline signature in the
481           .sha256 file or the detached GPG signature file SHA256SUMS.gpg. The
482           public key for this verification step needs to be available in
483           /usr/lib/systemd/import-pubring.gpg or
484           /etc/systemd/import-pubring.gpg.
485
486           The container image will be downloaded and stored in a read-only
487           subvolume in /var/lib/machines/ that is named after the specified
488           URL and its HTTP etag. A writable snapshot is then taken from this
489           subvolume, and named after the specified local name. This behavior
490           ensures that creating multiple container instances of the same URL
491           is efficient, as multiple downloads are not necessary. In order to
492           create only the read-only image, and avoid creating its writable
493           snapshot, specify "-" as local machine name.
494
495           Note that the read-only subvolume is prefixed with .tar-, and is
496           thus not shown by list-images, unless --all is passed.
497
498           Note that pressing C-c during execution of this command will not
499           abort the download. Use cancel-transfer, described below.
500
501       pull-raw URL [NAME]
502           Downloads a .raw container or VM disk image from the specified URL,
503           and makes it available under the specified local machine name. The
504           URL must be of type "http://" or "https://". The container image
505           must either be a .qcow2 or raw disk image, optionally compressed as
506           .gz, .xz, or .bz2. If the local machine name is omitted, it is
507           automatically derived from the last component of the URL, with its
508           suffix removed.
509
510           Image verification is identical for raw and tar images (see above).
511
512           If the downloaded image is in .qcow2 format it is converted into a
513           raw image file before it is made available.
514
515           Downloaded images of this type will be placed as read-only .raw
516           file in /var/lib/machines/. A local, writable (reflinked) copy is
517           then made under the specified local machine name. To omit creation
518           of the local, writable copy pass "-" as local machine name.
519
520           Similar to the behavior of pull-tar, the read-only image is
521           prefixed with .raw-, and thus not shown by list-images, unless
522           --all is passed.
523
524           Note that pressing C-c during execution of this command will not
525           abort the download. Use cancel-transfer, described below.
526
527       import-tar FILE [NAME], import-raw FILE [NAME]
528           Imports a TAR or RAW container or VM image, and places it under the
529           specified name in /var/lib/machines/. When import-tar is used, the
530           file specified as the first argument should be a tar archive,
531           possibly compressed with xz, gzip or bzip2. It will then be
532           unpacked into its own subvolume in /var/lib/machines. When
533           import-raw is used, the file should be a qcow2 or raw disk image,
534           possibly compressed with xz, gzip or bzip2. If the second argument
535           (the resulting image name) is not specified, it is automatically
536           derived from the file name. If the filename is passed as "-", the
537           image is read from standard input, in which case the second
538           argument is mandatory.
539
540           Both pull-tar and pull-raw will resize /var/lib/machines.raw and
541           the filesystem therein as necessary. Optionally, the --read-only
542           switch may be used to create a read-only container or VM image. No
543           cryptographic validation is done when importing the images.
544
545           Much like image downloads, ongoing imports may be listed with
546           list-transfers and aborted with cancel-transfer.
547
548       export-tar NAME [FILE], export-raw NAME [FILE]
549           Exports a TAR or RAW container or VM image and stores it in the
550           specified file. The first parameter should be a VM or container
551           image name. The second parameter should be a file path the TAR or
552           RAW image is written to. If the path ends in ".gz", the file is
553           compressed with gzip, if it ends in ".xz", with xz, and if it ends
554           in ".bz2", with bzip2. If the path ends in neither, the file is
555           left uncompressed. If the second argument is missing, the image is
556           written to standard output. The compression may also be explicitly
557           selected with the --format= switch. This is in particular useful if
558           the second parameter is left unspecified.
559
560           Much like image downloads and imports, ongoing exports may be
561           listed with list-transfers and aborted with cancel-transfer.
562
563           Note that, currently, only directory and subvolume images may be
564           exported as TAR images, and only raw disk images as RAW images.
565
566       list-transfers
567           Shows a list of container or VM image downloads, imports and
568           exports that are currently in progress.
569
570       cancel-transfer ID...
571           Aborts a download, import or export of the container or VM image
572           with the specified ID. To list ongoing transfers and their IDs, use
573           list-transfers.
574

MACHINE AND IMAGE NAMES

576       The machinectl tool operates on machines and images whose names must be
577       chosen following strict rules. Machine names must be suitable for use
578       as host names following a conservative subset of DNS and UNIX/Linux
579       semantics. Specifically, they must consist of one or more non-empty
580       label strings, separated by dots. No leading or trailing dots are
581       allowed. No sequences of multiple dots are allowed. The label strings
582       may only consist of alphanumeric characters as well as the dash and
583       underscore. The maximum length of a machine name is 64 characters.
584
585       A special machine with the name ".host" refers to the running host
586       system itself. This is useful for execution operations or inspecting
587       the host system as well. Note that machinectl list will not show this
588       special machine unless the --all switch is specified.
589
590       Requirements on image names are less strict, however, they must be
591       valid UTF-8, must be suitable as file names (hence not be the single or
592       double dot, and not include a slash), and may not contain control
593       characters. Since many operations search for an image by the name of a
594       requested machine, it is recommended to name images in the same strict
595       fashion as machines.
596
597       A special image with the name ".host" refers to the image of the
598       running host system. It hence conceptually maps to the special ".host"
599       machine name described above. Note that machinectl list-images will not
600       show this special image either, unless --all is specified.
601

FILES AND DIRECTORIES

603       Machine images are preferably stored in /var/lib/machines/, but are
604       also searched for in /usr/local/lib/machines/ and /usr/lib/machines/.
605       For compatibility reasons, the directory /var/lib/container/ is
606       searched, too. Note that images stored below /usr are always considered
607       read-only. It is possible to symlink machines images from other
608       directories into /var/lib/machines/ to make them available for control
609       with machinectl.
610
611       Note that some image operations are only supported, efficient or atomic
612       on btrfs file systems. Due to this, if the pull-tar, pull-raw,
613       import-tar, import-raw and set-limit commands notice that
614       /var/lib/machines is empty and not located on btrfs, they will
615       implicitly set up a loopback file /var/lib/machines.raw containing a
616       btrfs file system that is mounted to /var/lib/machines. The size of
617       this loopback file may be controlled dynamically with set-limit.
618
619       Disk images are understood by systemd-nspawn(1) and machinectl in three
620       formats:
621
622       ·   A simple directory tree, containing the files and directories of
623           the container to boot.
624
625       ·   Subvolumes (on btrfs file systems), which are similar to the simple
626           directories, described above. However, they have additional
627           benefits, such as efficient cloning and quota reporting.
628
629       ·   "Raw" disk images, i.e. binary images of disks with a GPT or MBR
630           partition table. Images of this type are regular files with the
631           suffix ".raw".
632
633       See systemd-nspawn(1) for more information on image formats, in
634       particular its --directory= and --image= options.
635

EXAMPLES

637       Example 1. Download an Ubuntu image and open a shell in it
638
639           # machinectl pull-tar https://cloud-images.ubuntu.com/trusty/current/trusty-server-cloudimg-amd64-root.tar.gz
640           # systemd-nspawn -M trusty-server-cloudimg-amd64-root
641
642       This downloads and verifies the specified .tar image, and then uses
643       systemd-nspawn(1) to open a shell in it.
644
645       Example 2. Download a Fedora image, set a root password in it, start it
646       as service
647
648           # machinectl pull-raw --verify=no https://dl.fedoraproject.org/pub/fedora/linux/releases/27/CloudImages/x86_64/images/Fedora-Cloud-Base-27-1.6.x86_64.raw.xz
649           # systemd-nspawn -M Fedora-Cloud-Base-27-1.6.x86_64
650           # passwd
651           # exit
652           # machinectl start Fedora-Cloud-Base-27-1.6.x86_64
653           # machinectl login Fedora-Cloud-Base-27-1.6.x86_64
654
655       This downloads the specified .raw image with verification disabled.
656       Then, a shell is opened in it and a root password is set. Afterwards
657       the shell is left, and the machine started as system service. With the
658       last command a login prompt into the container is requested.
659
660       Example 3. Exports a container image as tar file
661
662           # machinectl export-tar fedora myfedora.tar.xz
663
664       Exports the container "fedora" as an xz-compressed tar file
665       myfedora.tar.xz into the current directory.
666
667       Example 4. Create a new shell session
668
669           # machinectl shell --uid=lennart
670
671       This creates a new shell session on the local host for the user ID
672       "lennart", in a su(1)-like fashion.
673

EXIT STATUS

675       On success, 0 is returned, a non-zero failure code otherwise.
676

ENVIRONMENT

678       $SYSTEMD_PAGER
679           Pager to use when --no-pager is not given; overrides $PAGER. If
680           neither $SYSTEMD_PAGER nor $PAGER are set, a set of well-known
681           pager implementations are tried in turn, including less(1) and
682           more(1), until one is found. If no pager implementation is
683           discovered no pager is invoked. Setting this environment variable
684           to an empty string or the value "cat" is equivalent to passing
685           --no-pager.
686
687       $SYSTEMD_LESS
688           Override the options passed to less (by default "FRSXMK").
689
690       $SYSTEMD_LESSCHARSET
691           Override the charset passed to less (by default "utf-8", if the
692           invoking terminal is determined to be UTF-8 compatible).
693

SEE ALSO

695       systemd(1), systemd-machined.service(8), systemd-nspawn(1),
696       systemd.special(7), tar(1), xz(1), gzip(1), bzip2(1)
697
698
699
700systemd 239                                                      MACHINECTL(1)
Impressum