Debian Codegraph @

upstream/debian-unstable/man1/systemd-vmspawn.1

raw
1 '\" t
2 .TH "SYSTEMD\-VMSPAWN" "1" "" "systemd 261~rc3" "systemd-vmspawn"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 systemd-vmspawn \- Spawn an OS in a virtual machine
24 .SH "SYNOPSIS"
25 .HP \w'\fBsystemd\-vmspawn\fR\ 'u
26 \fBsystemd\-vmspawn\fR [OPTIONS...] [ARGS...]
27 .SH "DESCRIPTION"
28 .PP
29 \fBsystemd\-vmspawn\fR
30 may be used to start a virtual machine from an OS image\&. In many ways it is similar to
31 \fBsystemd-nspawn\fR(1), but launches a full virtual machine instead of using namespaces\&.
32 .PP
33 File descriptors for
34 /dev/kvm
35 and
36 /dev/vhost\-vsock
37 can be passed to
38 \fBsystemd\-vmspawn\fR
39 via systemd\*(Aqs native socket passing interface (see
40 \fBsd_listen_fds\fR(3)
41 for details about the precise protocol used and the order in which the file descriptors are passed), these file descriptors must be passed with the names
42 "kvm"
43 and
44 "vhost\-vsock"
45 respectively\&.
46 .PP
47 Note: on Ubuntu/Debian derivatives
48 \fBsystemd\-vmspawn\fR
49 requires the user to be in the
50 "kvm"
51 group to use the VSOCK options\&.
52 .SH "OPTIONS"
53 .PP
54 The excess arguments are passed as extra kernel command line arguments using SMBIOS\&.
55 .PP
56 The following options are understood:
57 .PP
58 \fB\-q\fR, \fB\-\-quiet\fR
59 .RS 4
60 Turns off any status output by the tool itself\&. When this switch is used, the only output from vmspawn will be the console output of the Virtual Machine OS itself\&.
61 .sp
62 Added in version 256\&.
63 .RE
64 .PP
65 \fB\-\-system\fR, \fB\-\-user\fR
66 .RS 4
67 Specify whether to interact with the user manager or the system manager and whether to register with the user machined instance or the system machined instance\&. If unspecified, the system manager and machined instance will be used when running as root, otherwise the user manager and machined instance will be used\&.
68 .sp
69 Added in version 260\&.
70 .RE
71 .SS "Image Options"
72 .PP
73 \fB\-D\fR, \fB\-\-directory=\fR
74 .RS 4
75 Directory to use as file system root for the virtual machine\&.
76 .sp
77 One of either
78 \fB\-\-directory=\fR
79 or
80 \fB\-\-image=\fR
81 must be specified\&. If neither are specified
82 \fB\-\-directory=\&.\fR
83 is assumed\&.
84 .sp
85 Note: If mounting a non\-root owned directory you may require
86 \fB\-\-private\-users=\fR
87 to map into the user\*(Aqs subuid namespace\&. An example of how to use
88 \fB/etc/subuid\fR
89 for this is given later\&.
90 .sp
91 Added in version 256\&.
92 .RE
93 .PP
94 \fB\-x\fR, \fB\-\-ephemeral\fR
95 .RS 4
96 If specified, the VM is run with a temporary snapshot of its file system that is removed immediately when the VM terminates\&. Only works with
97 \fB\-\-image=\fR
98 currently\&. Note that
99 \fB\-\-ephemeral\fR
100 will not work with
101 \fB\-\-extra\-drive=\fR\&.
102 .sp
103 Added in version 260\&.
104 .RE
105 .PP
106 \fB\-i\fR, \fB\-\-image=\fR
107 .RS 4
108 Root file system disk image (or device node) for the virtual machine\&.
109 .sp
110 Added in version 255\&.
111 .RE
112 .PP
113 \fB\-\-image\-format=\fR\fB\fIFORMAT\fR\fR
114 .RS 4
115 Specifies the format of the disk image passed to
116 \fB\-\-image=\fR\&. Takes either
117 "raw"
118 or
119 "qcow2"\&. Defaults to
120 "raw"\&. Note that
121 "qcow2"
122 is only supported for regular files, not block devices\&.
123 .sp
124 Added in version 260\&.
125 .RE
126 .PP
127 \fB\-\-image\-disk\-type=\fR\fB\fITYPE\fR\fR
128 .RS 4
129 Specifies the disk type to use for the root disk passed to
130 \fB\-\-image=\fR\&. Extra drives added via
131 \fB\-\-extra\-drive=\fR
132 inherit this disk type unless overridden with an explicit disk type prefix\&. Takes one of
133 "virtio\-blk",
134 "virtio\-scsi",
135 "nvme", or
136 "scsi\-cd"\&. Defaults to
137 "virtio\-blk"\&. When
138 "scsi\-cd"
139 is specified, the disk is attached as a read\-only CD\-ROM drive\&.
140 .sp
141 Added in version 261\&.
142 .RE
143 .PP
144 \fB\-\-discard\-disk=\fR\fB\fIBOOL\fR\fR
145 .RS 4
146 Controls whether qemu processes discard requests from the VM\&. This prevents long running VMs from using more disk space than required\&. This is enabled by default\&.
147 .sp
148 Added in version 256\&.
149 .RE
150 .PP
151 \fB\-\-grow\-image=\fR\fB\fIBYTES\fR\fR, \fB\-G \fR\fB\fIBYTES\fR\fR
152 .RS 4
153 Grows the image file specified by
154 \fB\-\-image=\fR
155 to the specified size in bytes if it is smaller\&. Executes no operation if no image file is used or the image file is already as large or larger than requested\&. The specified size accepts the usual K, M, G suffixes (to the base of 1024)\&. Specified values are rounded up to multiples of 4096\&.
156 .sp
157 Added in version 258\&.
158 .RE
159 .SS "Host Configuration"
160 .PP
161 \fB\-\-cpus=\fR\fB\fICPUS\fR\fR
162 .RS 4
163 The number of CPUs to start the virtual machine with\&. Defaults to 1\&.
164 .sp
165 Added in version 255\&.
166 .RE
167 .PP
168 \fB\-\-ram=\fR\fB\fIBYTES\fR\fR\fB[:\fR\fB\fIMAXBYTES\fR\fR\fB[:\fR\fB\fISLOTS\fR\fR\fB]]\fR
169 .RS 4
170 The amount of memory to start the virtual machine with\&. Defaults to 2G\&. If a maximum size is specified after a colon, memory hotplug is enabled with the given upper limit\&. The number of hotplug slots can optionally be specified after a second colon and defaults to 1\&.
171 .sp
172 Added in version 255\&.
173 .RE
174 .PP
175 \fB\-\-kvm=\fR\fB\fIBOOL\fR\fR
176 .RS 4
177 Controls whether to enable KVM acceleration\&. If not specified or set to
178 \fBauto\fR, KVM support will be detected automatically\&. If true, KVM is insisted on\&. If false, disable KVM\&.
179 .sp
180 Added in version 255\&.
181 .RE
182 .PP
183 \fB\-\-vsock=\fR\fB\fIBOOL\fR\fR
184 .RS 4
185 Controls whether to allocate a VSOCK socket for guest\&. If not specified or set to
186 \fBauto\fR, VSOCK networking support will be detected automatically\&. If true, VSOCK is insisted on\&. If false, VSOCK networking is disabled\&.
187 .sp
188 Added in version 255\&.
189 .RE
190 .PP
191 \fB\-\-vsock\-cid=\fR\fB\fICID\fR\fR
192 .RS 4
193 Sets the specific CID to use for the guest\&. Valid CIDs are in the range
194 \fB3\fR
195 to
196 \fB4294967294\fR
197 (\fB0xFFFF_FFFE\fR)\&. CIDs outside of this range are reserved\&. By default, vmspawn will attempt to derive a CID for the guest derived from the machine name, falling back to a random CID if this CID is taken\&.
198 .sp
199 Added in version 255\&.
200 .RE
201 .PP
202 \fB\-\-tpm=\fR\fB\fIBOOL\fR\fR
203 .RS 4
204 Controls whether to serve a TPM device for guest, via
205 \fBswtpm\fR(8)\&. If not specified or set to
206 \fBauto\fR, vmspawn will detect the presence of swtpm binary automatically\&. If yes, swtpm support is insisted on\&. If no, TPM is disabled\&.
207 .sp
208 Added in version 256\&.
209 .RE
210 .PP
211 \fB\-\-tpm\-state=\fR\fB\fIPATH\fR\fR\fB|auto|off\fR
212 .RS 4
213 Configures where to place TPM state, in case TPM support is enabled (see
214 \fB\-\-tpm=\fR
215 above)\&. This takes an absolute file system path to a directory to persistently place the state in\&. If the directory is missing it is created as needed\&. If set to the special string
216 "auto"
217 a persistent path is automatically derived from the VM image path or directory path, with the
218 "\&.tpmstate"
219 suffix appended\&. If set to the special string
220 "off"
221 the TPM state is only maintained transiently and flushed out when the VM shuts down\&. This mode is not suitable for VMs which lock disk encryption keys to the TPM, as these keys will be lost on every reboot\&. Defaults to
222 "auto"\&.
223 .sp
224 If
225 \fB\-\-ephemeral\fR
226 is specified,
227 "auto"
228 behaves like
229 "off"\&.
230 .sp
231 Added in version 258\&.
232 .RE
233 .PP
234 \fB\-\-efi\-nvram\-template=\fR\fB\fIPATH\fR\fR
235 .RS 4
236 Takes an absolute path, or a relative path beginning with
237 \&./\&. Specifies the path to an EFI NVRAM template file to copy and use as the initial EFI variable NVRAM state\&. If not specified, the default NVRAM template from the firmware definition is copied and used\&.
238 .sp
239 Added in version 261\&.
240 .RE
241 .PP
242 \fB\-\-efi\-nvram\-state=\fR\fB\fIPATH\fR\fR\fB|auto|off\fR
243 .RS 4
244 Configures where to place the EFI variable NVRAM state\&. This takes an absolute file system path to a regular file to persistently place the state in\&. If the file is missing it is created as needed\&. If set to the special string
245 "auto"
246 a persistent path is automatically derived from the VM image path or directory path, with the
247 "\&.efinvramstate"
248 suffix appended\&. If set to the special string
249 "off"
250 the EFI variable NVRAM state is only maintained transiently and flushed out when the VM shuts down\&. Defaults to
251 "auto"\&.
252 .sp
253 If
254 \fB\-\-ephemeral\fR
255 is specified,
256 "auto"
257 behaves like
258 "off"\&.
259 .sp
260 Added in version 261\&.
261 .RE
262 .PP
263 \fB\-\-secure\-boot=\fR\fB\fIBOOL\fR\fR
264 .RS 4
265 Configure whether to search for firmware which supports Secure Boot\&. Takes a boolean or
266 "auto"\&. Setting this to yes is equivalent to
267 \fB\-\-firmware\-features=secure\-boot\fR
268 and setting this to no is equivalent to
269 \fB\-\-firmware\-features=~secure\-boot\fR\&. Setting this to
270 "auto"
271 removes
272 "secure\-boot"
273 from both the included and excluded feature lists\&.
274 .sp
275 Added in version 255\&.
276 .RE
277 .PP
278 \fB\-\-firmware=\fR\fB\fIPATH\fR\fR
279 .RS 4
280 Selects which firmware to use in the VM\&. Takes one of
281 "auto",
282 "uefi",
283 "bios",
284 "none", an absolute path, or a relative path beginning with
285 \&./\&. Defaults to
286 "auto", which selects UEFI firmware unless
287 \fB\-\-linux=\fR
288 specifies a non\-PE kernel image, in which case
289 "none"
290 is selected\&.
291 "uefi"
292 loads OVMF firmware (use a path to a JSON firmware definition file to select a specific one)\&.
293 "bios"
294 skips OVMF loading and lets QEMU use its built\-in BIOS (e\&.g\&. SeaBIOS on x86)\&.
295 "none"
296 disables firmware loading entirely and requires
297 \fB\-\-linux=\fR
298 to be specified for direct kernel boot\&. Booting a UKI requires
299 "uefi"\&. If the special string
300 "list"
301 is specified, all discovered firmware definition files are listed\&. If the special string
302 "describe"
303 is specified, the UEFI firmware that would be selected (taking
304 \fB\-\-firmware\-features=\fR
305 into account) is printed and the program exits\&. If an empty string is specified, the option is reset to its default\&.
306 .sp
307 Added in version 256\&.
308 .RE
309 .PP
310 \fB\-\-firmware\-features=\fR\fB\fIFEATURE\fR\fR\fB[,\fR\fB\fIFEATURE\fR\fR\fB\&.\&.\&.]\fR
311 .RS 4
312 Takes a comma\-delimited list of firmware feature strings\&. This option may be specified multiple times, in which case the feature lists are combined\&. When specified, only firmware definitions that have all the required features will be considered during automatic firmware discovery\&. Features prefixed with
313 "~"
314 are excluded: firmware that has such a feature will be skipped\&. If a feature appears in both the included and excluded lists, inclusion takes priority\&. By default, firmware with the
315 "enrolled\-keys"
316 feature is excluded\&. If an empty string is passed, both the included and excluded feature lists are reset\&. If the special string
317 "list"
318 is specified, lists all available firmware features\&.
319 .sp
320 Added in version 261\&.
321 .RE
322 .PP
323 \fB\-\-coco=\fR
324 .RS 4
325 Caveat: This feature is experimental, and is likely to be changed (or removed in its current form) in a future version of systemd\&.
326 .sp
327 Configures whether to run the guest as a confidential VM\&. Takes one of
328 "no"
329 or
330 "sev\-snp"\&. Defaults to
331 "no"\&.
332 .sp
333 "sev\-snp"
334 enables AMD SEV\-SNP\&. This requires KVM on an x86_64 host with SNP\-capable hardware and firmware\&.
335 \fB\-\-firmware=\fR
336 must point to a raw SNP\-built OVMF
337 \&.fd
338 image; the standard pflash + NVRAM split is not supported under SNP, so the firmware is loaded via QEMU\*(Aqs
339 \fB\-bios\fR
340 and Secure Boot is unavailable\&. SMBIOS credentials passed via
341 \fB\-\-set\-credential=\fR
342 or
343 \fB\-\-load\-credential=\fR
344 are rejected because they are outside the SNP launch measurement\&. Direct kernel boot via
345 \fB\-\-linux=\fR
346 is required so that the kernel, initrd and command line are hashed into the launch measurement ("kernel\-hashes=on"); booting the kernel off the disk image via the firmware would leave it outside the measurement\&. A vTPM, if attached via
347 \fB\-\-tpm=\fR, must be treated as untrusted by the guest\&.
348 .sp
349 Added in version 261\&.
350 .RE
351 .SS "Networking Options"
352 .PP
353 \fB\-n\fR, \fB\-\-network\-tap\fR
354 .RS 4
355 Create a TAP device to network with the virtual machine\&.
356 .sp
357 Note: root privileges are required to use TAP networking\&. Additionally,
358 \fBsystemd-networkd\fR(8)
359 must be running and correctly set up on the host to provision the host interface\&. The relevant
360 "\&.network"
361 file can be found at
362 /usr/lib/systemd/network/80\-vm\-vt\&.network\&.
363 .sp
364 Added in version 255\&.
365 .RE
366 .PP
367 \fB\-\-network\-user\-mode\fR
368 .RS 4
369 Use user mode networking\&.
370 .sp
371 Added in version 255\&.
372 .RE
373 .SS "Execution Options"
374 .PP
375 \fB\-\-linux=\fR\fB\fIPATH\fR\fR
376 .RS 4
377 Set the linux kernel image to use for direct kernel boot\&. If a directory type image is used and
378 \fB\-\-linux=\fR
379 was omitted, vmspawn will search for boot loader entries according to the
380 \m[blue]\fBUAPI\&.1 Boot Loader Specification\fR\m[]\&\s-2\u[1]\d\s+2
381 assuming XBOOTLDR to be located at /boot and ESP to be /efi respectively\&. If no kernel was installed into the image then the image will fail to boot\&.
382 .sp
383 Added in version 256\&.
384 .RE
385 .PP
386 \fB\-\-initrd=\fR\fB\fIPATH\fR\fR
387 .RS 4
388 Set the initrd to use for direct kernel boot\&. If the
389 \fB\-\-linux=\fR
390 supplied is a
391 \m[blue]\fBUAPI\&.1 Boot Loader Specification\fR\m[]\&\s-2\u[1]\d\s+2
392 Type #2 entry, then this argument is not required\&. If no initrd was installed into the image then the image will fail to boot\&.
393 .sp
394 \fB\-\-initrd=\fR
395 can be specified multiple times and vmspawn will merge them together\&.
396 .sp
397 Added in version 256\&.
398 .RE
399 .PP
400 \fB\-\-smbios11=\fR\fB\fISTRING\fR\fR, \fB\-s \fR\fB\fISTRING\fR\fR
401 .RS 4
402 Passes the specified string into the VM as an SMBIOS Type #11 vendor string\&. This is useful to parameterize the invoked VM in various ways\&. See
403 \fBsmbios-type-11\fR(7)
404 for details\&.
405 .sp
406 Added in version 258\&.
407 .RE
408 .PP
409 \fB\-\-notify\-ready=\fR
410 .RS 4
411 Configures support for notifications from the VM\*(Aqs init process to
412 \fBsystemd\-vmspawn\fR\&. If true,
413 \fBsystemd\-vmspawn\fR
414 will consider the machine as ready only when it has received a
415 "READY=1"
416 message from the init process in the VM\&. If false,
417 \fBsystemd\-vmspawn\fR
418 will consider the machine as ready immediately after creation\&. In either case,
419 \fBsystemd\-vmspawn\fR
420 sends its own readiness notification to its manager after the spawned VM is ready\&. For more details about notifications see
421 \fBsd_notify\fR(3)\&.
422 .sp
423 Defaults to true\&. (Note that this is unlike the option of the same name to
424 \fBsystemd-nspawn\fR(1)
425 that defaults to false\&.)
426 .sp
427 Added in version 258\&.
428 .RE
429 .SS "System Identity Options"
430 .PP
431 \fB\-M\fR, \fB\-\-machine=\fR
432 .RS 4
433 Sets the machine name for this virtual machine\&. This name may be used to identify this virtual machine during its runtime (for example in tools like
434 \fBmachinectl\fR(1)
435 and similar)\&.
436 .sp
437 Added in version 255\&.
438 .RE
439 .PP
440 \fB\-\-uuid=\fR
441 .RS 4
442 Set the specified UUID for the virtual machine\&. The init system will initialize
443 /etc/machine\-id
444 from this if this file is not set yet\&. Note that this option takes effect only if
445 /etc/machine\-id
446 in the virtual machine is unpopulated\&.
447 .sp
448 Added in version 256\&.
449 .RE
450 .SS "Property Options"
451 .PP
452 \fB\-S\fR, \fB\-\-slice=\fR
453 .RS 4
454 Make the VM part of the specified slice, instead of the default
455 machine\&.slice\&. This applies only if the machine is run in its own scope unit, i\&.e\&. if
456 \fB\-\-keep\-unit\fR
457 is not used\&.
458 .sp
459 Added in version 258\&.
460 .RE
461 .PP
462 \fB\-\-property=\fR
463 .RS 4
464 Set a unit property on the scope unit to register for the machine\&. This applies only if the machine is run in its own scope unit, i\&.e\&. if
465 \fB\-\-keep\-unit\fR
466 is not used\&. Takes unit property assignments in the same format as
467 \fBsystemctl set\-property\fR\&. This is useful to set memory limits and similar for the VM\&.
468 .sp
469 Added in version 258\&.
470 .RE
471 .PP
472 \fB\-\-register=\fR
473 .RS 4
474 Controls whether the virtual machine is registered with
475 \fBsystemd-machined\fR(8)\&. Takes a boolean argument or
476 "auto", and defaults to
477 "auto"\&. This ensures that the virtual machine is accessible via
478 \fBmachinectl\fR(1)\&. When set to
479 "auto", registration is attempted but failures are ignored\&.
480 .sp
481 Added in version 256\&.
482 .RE
483 .SS "User Namespacing Options"
484 .PP
485 \fB\-\-private\-users=\fR\fB\fIUID_SHIFT[:UID_RANGE]\fR\fR
486 .RS 4
487 Controls user namespacing under
488 \fB\-\-directory=\fR\&. If enabled,
489 \fBvirtiofsd\fR(1)
490 is instructed to map user and group ids (UIDs and GIDs)\&. This involves mapping the private UIDs/GIDs used in the virtual machine (starting with the virtual machine\*(Aqs root user 0 and up) to a range of UIDs/GIDs on the host that are not used for other purposes (usually in the range beyond the host\*(Aqs UID/GID 65536)\&.
491 .sp
492 If one or two colon\-separated numbers are specified, user namespacing is turned on\&.
493 \fIUID_SHIFT\fR
494 specifies the first host UID/GID to map,
495 \fIUID_RANGE\fR
496 is optional and specifies number of host UIDs/GIDs to assign to the virtual machine\&. If
497 \fIUID_RANGE\fR
498 is omitted, 65536 UIDs/GIDs are assigned\&.
499 .sp
500 When user namespaces are used, the GID range assigned to each virtual machine is always chosen identical to the UID range\&.
501 .sp
502 Added in version 256\&.
503 .RE
504 .SS "Mount Options"
505 .PP
506 \fB\-\-bind=\fR\fB\fIPATH\fR\fR, \fB\-\-bind\-ro=\fR\fB\fIPATH\fR\fR
507 .RS 4
508 Mount a directory from the host into the virtual machine\&. Takes one of: a path argument\ \&\(em in which case the specified path will be mounted from the host to the same path in the virtual machine, or a colon\-separated pair of paths\ \&\(em in which case the first specified path is the source in the host, and the second path is the destination in the virtual machine\&. If the source path is not absolute, it is resolved relative to the current working directory\&. The
509 \fB\-\-bind\-ro=\fR
510 option creates read\-only bind mounts\&. Backslash escapes are interpreted, so
511 "\e:"
512 may be used to embed colons in either path\&. This option may be specified multiple times for creating multiple independent bind mount points\&.
513 .sp
514 Added in version 256\&.
515 .RE
516 .PP
517 \fB\-\-extra\-drive=[\fR\fB\fIFORMAT\fR\fR\fB:][\fR\fB\fIDISKTYPE\fR\fR\fB:]\fR\fB\fIPATH\fR\fR
518 .RS 4
519 Takes a disk image or block device on the host and supplies it to the virtual machine as another drive\&. Optionally, the image format and/or disk type can be specified by prefixing the path with their values separated by colons\&. The format and disk type prefixes can appear in any order\&. The format defaults to
520 "raw"
521 and the disk type defaults to the value of
522 \fB\-\-image\-disk\-type=\fR
523 (which itself defaults to
524 "virtio\-blk")\&. Note that
525 "qcow2"
526 is only supported for regular files, not block devices\&.
527 .sp
528 Added in version 256\&.
529 .RE
530 .PP
531 \fB\-\-bind\-volume=\fR\fB\fIPROVIDER\fR\fR\fB:\fR\fB\fIVOLUME\fR\fR\fB[:\fR\fB\fICONFIG\fR\fR\fB][:\fR\fB\fIK=V\fR\fR\fB,\&...]\fR
532 .RS 4
533 Acquire a storage volume from a
534 \fBstoragectl\fR(1)
535 provider and attach it to the virtual machine\&.
536 \fIPROVIDER\fR
537 is the provider name (typically
538 "block"
539 or
540 "fs")\&.
541 \fIVOLUME\fR
542 is the volume name passed to the provider\*(Aqs
543 \fBAcquire()\fR
544 method\&.
545 \fICONFIG\fR
546 selects the guest device type and takes one of
547 "virtio\-blk",
548 "virtio\-scsi",
549 "nvme", or
550 "scsi\-cd"\&. If empty or omitted, defaults to
551 "virtio\-blk"\&.
552 .sp
553 The trailing comma\-separated
554 \fIK=V\fR
555 list passes parameters to
556 \fBio\&.systemd\&.StorageProvider\&.Acquire()\fR:
557 \fItemplate=\fR,
558 \fIcreate=\fR
559 (one of
560 "any",
561 "new",
562 "open"),
563 \fIread\-only=\fR
564 (or
565 \fIro=\fR; takes a boolean or
566 "auto"),
567 \fIsize=\fR
568 /
569 \fIcreate\-size=\fR
570 (size for created volumes),
571 \fIrequest\-as=\fR
572 (one of
573 "blk",
574 "reg",
575 "dir";
576 "dir"
577 is rejected by vmspawn)\&.
578 .sp
579 Each attached volume is identified by the name
580 "\fIPROVIDER\fR:\fIVOLUME\fR"\&. Volumes attached at startup via this option cannot be detached at runtime via
581 \fBmachinectl unbind\-volume\fR; only volumes added at runtime via
582 \fBmachinectl bind\-volume\fR
583 are removable\&.
584 .sp
585 The provider is looked up under
586 /run/systemd/io\&.systemd\&.StorageProvider/
587 for system mode (or
588 $XDG_RUNTIME_DIR/systemd/io\&.systemd\&.StorageProvider/
589 for user mode), matching the runtime scope chosen via
590 \fB\-\-user\fR
591 /
592 \fB\-\-system\fR\&.
593 .sp
594 Added in version 261\&.
595 .RE
596 .PP
597 \fB\-\-bind\-user=\fR
598 .RS 4
599 Binds the home directory of the specified user on the host into the virtual machine\&. Takes the name of an existing user on the host as argument\&. May be used multiple times to bind multiple users into the virtual machine\&. This does two things:
600 .sp
601 .RS 4
602 .ie n \{\
603 \h'-04' 1.\h'+01'\c
604 .\}
605 .el \{\
606 .sp -1
607 .IP " 1." 4.2
608 .\}
609 The user\*(Aqs home directory is made available from the host into
610 /run/vmhost/home/
611 using virtiofs\&. virtiofsd id translation to map the host user\*(Aqs UID/GID to its assigned UID/GID in the virtual machine\&.
612 .RE
613 .sp
614 .RS 4
615 .ie n \{\
616 \h'-04' 2.\h'+01'\c
617 .\}
618 .el \{\
619 .sp -1
620 .IP " 2." 4.2
621 .\}
622 JSON user and group records are generated in that describes the mapped user which are passed into the virtual machine using
623 "userdb\&.transient\&.*"
624 credentials\&. They contain a minimized representation of the host\*(Aqs user record, adjusted to the UID/GID and home directory path assigned to the user in the virtual machine\&. The
625 \fBnss-systemd\fR(8)
626 glibc NSS module will pick up these records from there and make them available in the virtual machine\*(Aqs user/group databases\&.
627 .RE
628 .sp
629 The combination of the two operations above ensures that it is possible to log into the virtual machine using the same account information as on the host\&. The user is only mapped transiently, while the virtual machine is running, and the mapping itself does not result in persistent changes to the virtual machine (except maybe for log messages generated at login time, and similar)\&. Note that in particular the UID/GID assignment in the virtual machine is not made persistently\&. If the user is mapped transiently, it is best to not allow the user to make persistent changes to the virtual machine\&. If the user leaves files or directories owned by the user, and those UIDs/GIDs are reused during later virtual machine invocations (possibly with a different
630 \fB\-\-bind\-user=\fR
631 mapping), those files and directories will be accessible to the "new" user\&.
632 .sp
633 The user/group record mapping only works if the virtual machine contains systemd 258 or newer, with
634 \fBnss\-systemd\fR
635 properly configured in
636 nsswitch\&.conf\&. See
637 \fBnss-systemd\fR(8)
638 for details\&.
639 .sp
640 Note that the user record propagated from the host into the virtual machine will contain the UNIX password hash of the user, so that seamless logins in the virtual machine are possible\&. If the virtual machine is less trusted than the host it is hence important to use a strong UNIX password hash function (e\&.g\&. yescrypt or similar, with the
641 "$y$"
642 hash prefix)\&.
643 .sp
644 Added in version 259\&.
645 .RE
646 .PP
647 \fB\-\-bind\-user\-shell=\fR
648 .RS 4
649 When used with
650 \fB\-\-bind\-user=\fR, includes the specified shell in the user records of users bound into the virtual machine\&. Takes either a boolean or an absolute path\&.
651 .sp
652 .RS 4
653 .ie n \{\
654 \h'-04'\(bu\h'+03'\c
655 .\}
656 .el \{\
657 .sp -1
658 .IP \(bu 2.3
659 .\}
660 If false (the default), no shell is passed in the user records for users bound into the virtual machine\&. This causes bound users to the use the virtual machine\*(Aqs default shell\&.
661 .RE
662 .sp
663 .RS 4
664 .ie n \{\
665 \h'-04'\(bu\h'+03'\c
666 .\}
667 .el \{\
668 .sp -1
669 .IP \(bu 2.3
670 .\}
671 If true, the shells specified by the host user records are included in the user records of all users bound into the virtual machine\&.
672 .RE
673 .sp
674 .RS 4
675 .ie n \{\
676 \h'-04'\(bu\h'+03'\c
677 .\}
678 .el \{\
679 .sp -1
680 .IP \(bu 2.3
681 .\}
682 If passed an absolute path, sets that path as the shell for user records of all users bound into the virtual machine\&.
683 .RE
684 .sp
685 Note: This will not check whether the specified shells exist in the virtual machine\&.
686 .sp
687 This operation is only supported in combination with
688 \fB\-\-bind\-user=\fR\&.
689 .sp
690 Added in version 259\&.
691 .RE
692 .PP
693 \fB\-\-bind\-user\-group=\fR\fB\fINAME\fR\fR
694 .RS 4
695 When used with
696 \fB\-\-bind\-user=\fR, includes the specified group as an auxiliary group in the user records of users bound into the virtual machine\&. Takes a group name\&.
697 .sp
698 Note: This will not check whether the specified groups exist in the virtual machine\&.
699 .sp
700 This operation is only supported in combination with
701 \fB\-\-bind\-user=\fR\&.
702 .sp
703 Added in version 259\&.
704 .RE
705 .SS "Logging Options"
706 .PP
707 \fB\-\-forward\-journal=\fR\fB\fIFILE|DIR\fR\fR
708 .RS 4
709 Forward the virtual machine\*(Aqs journal to the host\&.
710 \fBsystemd-journal-remote\fR(8)
711 is currently used to receive the guest VM\*(Aqs forwarded journal entries\&. This option determines where this journal is saved on the host and has the same semantics as
712 \fB\-o\fR/\fB\-\-output\fR
713 described in
714 \fBsystemd-journal-remote\fR(8)\&.
715 .sp
716 Added in version 256\&.
717 .RE
718 .PP
719 \fB\-\-forward\-journal\-max\-use=\fR\fB\fIBYTES\fR\fR, \fB\-\-forward\-journal\-keep\-free=\fR\fB\fIBYTES\fR\fR, \fB\-\-forward\-journal\-max\-file\-size=\fR\fB\fIBYTES\fR\fR, \fB\-\-forward\-journal\-max\-files=\fR\fB\fIN\fR\fR
720 .RS 4
721 These options configure the corresponding settings of
722 \fBsystemd-journal-remote\fR(8)
723 when forwarding journal entries from the VM\&. See
724 \fBjournal-remote.conf\fR(5)
725 for the descriptions of these settings\&.
726 .sp
727 Added in version 261\&.
728 .RE
729 .SS "SSH Options"
730 .PP
731 \fB\-\-pass\-ssh\-key=\fR\fB\fIBOOL\fR\fR
732 .RS 4
733 By default, an SSH key is generated to allow
734 \fBsystemd\-vmspawn\fR
735 to open a D\-Bus connection to the VM\*(Aqs systemd bus\&. Setting this to "no" will disable SSH key generation\&.
736 .sp
737 The generated keys are ephemeral\&. That is they are valid only for the current invocation of
738 \fBsystemd\-vmspawn\fR, and are typically not persisted\&.
739 .sp
740 Added in version 256\&.
741 .RE
742 .PP
743 \fB\-\-ssh\-key\-type=\fR\fB\fITYPE\fR\fR
744 .RS 4
745 Configures the type of SSH key to generate, see
746 \fBssh-keygen\fR(1)
747 for more information\&.
748 .sp
749 By default,
750 "ed25519"
751 keys are generated, however
752 "rsa"
753 keys may also be useful if the VM has a particularly old version of
754 \fBsshd\fR(8)\&.
755 .sp
756 Added in version 256\&.
757 .RE
758 .SS "Input/Output Options"
759 .PP
760 \fB\-\-console=\fR\fB\fIMODE\fR\fR
761 .RS 4
762 Configures how to set up the console of the VM\&. Takes one of
763 "interactive",
764 "read\-only",
765 "native",
766 "gui",
767 "headless"\&. Defaults to
768 "interactive"\&.
769 "interactive"
770 provides an interactive terminal interface to the VM\&.
771 "read\-only"
772 is similar, but is strictly read\-only, i\&.e\&. does not accept any input from the user\&.
773 "native"
774 also provides a TTY\-based interface, but uses qemu native implementation (which means the qemu monitor is available)\&.
775 "gui"
776 shows the qemu graphical UI\&.
777 "headless"
778 runs the VM without any console, which is useful for automated or scripted usage\&.
779 .sp
780 Added in version 256\&.
781 .RE
782 .PP
783 \fB\-\-console\-transport=\fR\fB\fITRANSPORT\fR\fR
784 .RS 4
785 Configures the transport to use for the VM console\&. Takes one of
786 "virtio"
787 or
788 "serial"\&. Defaults to
789 "virtio"\&.
790 "virtio"
791 uses a virtio\-serial device, which appears as
792 /dev/hvc0
793 in the VM\&.
794 "serial"
795 uses a regular serial port, which appears as
796 /dev/ttyS0
797 (or
798 /dev/ttyAMA0
799 on ARM) in the VM\&. This option only has an effect in
800 \fB\-\-console=interactive\fR,
801 \fB\-\-console=read\-only\fR, and
802 \fB\-\-console=native\fR
803 modes\&.
804 .sp
805 Added in version 261\&.
806 .RE
807 .PP
808 \fB\-\-background=\fR\fB\fICOLOR\fR\fR
809 .RS 4
810 Change the terminal background color to the specified ANSI color as long as the VM runs\&. The color specified should be an ANSI X3\&.64 SGR background color, i\&.e\&. strings such as
811 "40",
812 "41", \&...,
813 "47",
814 "48;2;\&...",
815 "48;5;\&..."\&. See
816 \m[blue]\fBANSI Escape Code (Wikipedia)\fR\m[]\&\s-2\u[2]\d\s+2
817 for details\&. Assign an empty string to disable any coloring\&. This only has an effect in
818 \fB\-\-console=interactive\fR
819 and
820 \fB\-\-console=read\-only\fR
821 modes\&.
822 .sp
823 Added in version 256\&.
824 .RE
825 .SS "Credentials"
826 .PP
827 \fB\-\-load\-credential=\fR\fB\fIID\fR\fR\fB:\fR\fB\fIPATH\fR\fR, \fB\-\-set\-credential=\fR\fB\fIID\fR\fR\fB:\fR\fB\fIVALUE\fR\fR
828 .RS 4
829 Pass a credential to the virtual machine\&. These two options correspond to the
830 \fILoadCredential=\fR
831 and
832 \fISetCredential=\fR
833 settings in unit files\&. See
834 \fBsystemd.exec\fR(5)
835 for details about these concepts, as well as the syntax of the option\*(Aqs arguments\&.
836 .sp
837 In order to embed binary data into the credential data for
838 \fB\-\-set\-credential=\fR, use C\-style escaping (i\&.e\&.
839 "\en"
840 to embed a newline, or
841 "\ex00"
842 to embed a
843 \fBNUL\fR
844 byte)\&. Note that the invoking shell might already apply unescaping once, hence this might require double escaping!
845 .sp
846 Credentials are preferably passed to the VM via SMBIOS Type 11 strings or QEMU fw_cfg files\&. If neither mechanism is available, credentials are passed on the kernel command line using
847 \fIsystemd\&.set_credential_binary=\fR
848 which is not a confidential channel\&. Do not use this for passing secrets to the VM in that case\&.
849 .sp
850 Added in version 255\&.
851 .RE
852 .SS "Other"
853 .PP
854 \fB\-\-no\-pager\fR
855 .RS 4
856 Do not pipe output into a pager\&.
857 .RE
858 .PP
859 \fB\-h\fR, \fB\-\-help\fR
860 .RS 4
861 Print a short help text and exit\&.
862 .RE
863 .PP
864 \fB\-\-version\fR
865 .RS 4
866 Print a short version string and exit\&.
867 .RE
868 .PP
869 \fB\-\-no\-ask\-password\fR
870 .RS 4
871 Do not query the user for authentication for privileged operations\&.
872 .RE
873 .SH "ENVIRONMENT"
874 .PP
875 \fI$SYSTEMD_LOG_LEVEL\fR
876 .RS 4
877 The maximum log level of emitted messages (messages with a higher log level, i\&.e\&. less important ones, will be suppressed)\&. Takes a comma\-separated list of values\&. A value may be either one of (in order of decreasing importance)
878 \fBemerg\fR,
879 \fBalert\fR,
880 \fBcrit\fR,
881 \fBerr\fR,
882 \fBwarning\fR,
883 \fBnotice\fR,
884 \fBinfo\fR,
885 \fBdebug\fR, or an integer in the range 0\&...7\&. See
886 \fBsyslog\fR(3)
887 for more information\&. Each value may optionally be prefixed with one of
888 \fBconsole\fR,
889 \fBsyslog\fR,
890 \fBkmsg\fR
891 or
892 \fBjournal\fR
893 followed by a colon to set the maximum log level for that specific log target (e\&.g\&.
894 \fBSYSTEMD_LOG_LEVEL=debug,console:info\fR
895 specifies to log at debug level except when logging to the console which should be at info level)\&. Note that the global maximum log level takes priority over any per target maximum log levels\&.
896 .RE
897 .PP
898 \fI$SYSTEMD_LOG_COLOR\fR
899 .RS 4
900 A boolean\&. If true, messages written to the tty will be colored according to priority\&.
901 .sp
902 This setting is only useful when messages are written directly to the terminal, because
903 \fBjournalctl\fR(1)
904 and other tools that display logs will color messages based on the log level on their own\&.
905 .RE
906 .PP
907 \fI$SYSTEMD_LOG_TIME\fR
908 .RS 4
909 A boolean\&. If true, console log messages will be prefixed with a timestamp\&.
910 .sp
911 This setting is only useful when messages are written directly to the terminal or a file, because
912 \fBjournalctl\fR(1)
913 and other tools that display logs will attach timestamps based on the entry metadata on their own\&.
914 .RE
915 .PP
916 \fI$SYSTEMD_LOG_LOCATION\fR
917 .RS 4
918 A boolean\&. If true, messages will be prefixed with a filename and line number in the source code where the message originates\&.
919 .sp
920 Note that the log location is often attached as metadata to journal entries anyway\&. Including it directly in the message text can nevertheless be convenient when debugging programs\&.
921 .RE
922 .PP
923 \fI$SYSTEMD_LOG_TID\fR
924 .RS 4
925 A boolean\&. If true, messages will be prefixed with the current numerical thread ID (TID)\&.
926 .sp
927 Note that the this information is attached as metadata to journal entries anyway\&. Including it directly in the message text can nevertheless be convenient when debugging programs\&.
928 .RE
929 .PP
930 \fI$SYSTEMD_LOG_TARGET\fR
931 .RS 4
932 The destination for log messages\&. One of
933 \fBconsole\fR
934 (log to the attached tty),
935 \fBconsole\-prefixed\fR
936 (log to the attached tty but with prefixes encoding the log level and "facility", see
937 \fBsyslog\fR(3),
938 \fBkmsg\fR
939 (log to the kernel circular log buffer),
940 \fBjournal\fR
941 (log to the journal),
942 \fBjournal\-or\-kmsg\fR
943 (log to the journal if available, and to kmsg otherwise),
944 \fBauto\fR
945 (determine the appropriate log target automatically, the default),
946 \fBnull\fR
947 (disable log output)\&.
948 .RE
949 .PP
950 \fI$SYSTEMD_LOG_RATELIMIT_KMSG\fR
951 .RS 4
952 Whether to ratelimit kmsg or not\&. Takes a boolean\&. Defaults to
953 "true"\&. If disabled, systemd will not ratelimit messages written to kmsg\&.
954 .RE
955 .PP
956 \fI$SYSTEMD_PAGER\fR, \fI$PAGER\fR
957 .RS 4
958 Pager to use when
959 \fB\-\-no\-pager\fR
960 is not given\&.
961 \fI$SYSTEMD_PAGER\fR
962 is used if set; otherwise
963 \fI$PAGER\fR
964 is used\&. If neither
965 \fI$SYSTEMD_PAGER\fR
966 nor
967 \fI$PAGER\fR
968 are set, a set of well\-known pager implementations is tried in turn, including
969 \fBless\fR(1)
970 and
971 \fBmore\fR(1), until one is found\&. If no pager implementation is discovered, no pager is invoked\&. Setting those environment variables to an empty string or the value
972 "cat"
973 is equivalent to passing
974 \fB\-\-no\-pager\fR\&.
975 .sp
976 Note: if
977 \fI$SYSTEMD_PAGERSECURE\fR
978 is not set,
979 \fI$SYSTEMD_PAGER\fR
980 and
981 \fI$PAGER\fR
982 can only be used to disable the pager (with
983 "cat"
984 or
985 ""), and are otherwise ignored\&.
986 .RE
987 .PP
988 \fI$SYSTEMD_LESS\fR
989 .RS 4
990 Override the options passed to
991 \fBless\fR
992 (by default
993 "FRSXMK")\&.
994 .sp
995 Users might want to change two options in particular:
996 .PP
997 \fBK\fR
998 .RS 4
999 This option instructs the pager to exit immediately when
1000 Ctrl+C
1001 is pressed\&. To allow
1002 \fBless\fR
1003 to handle
1004 Ctrl+C
1005 itself to switch back to the pager command prompt, unset this option\&.
1006 .sp
1007 If the value of
1008 \fI$SYSTEMD_LESS\fR
1009 does not include
1010 "K", and the pager that is invoked is
1011 \fBless\fR,
1012 Ctrl+C
1013 will be ignored by the executable, and needs to be handled by the pager\&.
1014 .RE
1015 .PP
1016 \fBX\fR
1017 .RS 4
1018 This option instructs the pager to not send termcap initialization and deinitialization strings to the terminal\&. It is set by default to allow command output to remain visible in the terminal even after the pager exits\&. Nevertheless, this prevents some pager functionality from working, in particular paged output cannot be scrolled with the mouse\&.
1019 .RE
1020 .sp
1021 Note that setting the regular
1022 \fI$LESS\fR
1023 environment variable has no effect for
1024 \fBless\fR
1025 invocations by systemd tools\&.
1026 .sp
1027 See
1028 \fBless\fR(1)
1029 for more discussion\&.
1030 .RE
1031 .PP
1032 \fI$SYSTEMD_LESSCHARSET\fR
1033 .RS 4
1034 Override the charset passed to
1035 \fBless\fR
1036 (by default
1037 "utf\-8", if the invoking terminal is determined to be UTF\-8 compatible)\&.
1038 .sp
1039 Note that setting the regular
1040 \fI$LESSCHARSET\fR
1041 environment variable has no effect for
1042 \fBless\fR
1043 invocations by systemd tools\&.
1044 .RE
1045 .PP
1046 \fI$SYSTEMD_PAGERSECURE\fR
1047 .RS 4
1048 Common pager commands like
1049 \fBless\fR(1), in addition to "paging", i\&.e\&. scrolling through the output, support opening of or writing to other files and running arbitrary shell commands\&. When commands are invoked with elevated privileges, for example under
1050 \fBsudo\fR(8)
1051 or
1052 \fBpkexec\fR(1), the pager becomes a security boundary\&. Care must be taken that only programs with strictly limited functionality are used as pagers, and unintended interactive features like opening or creation of new files or starting of subprocesses are not allowed\&. "Secure mode" for the pager may be enabled as described below,
1053 \fIif the pager supports that\fR
1054 (most pagers are not written in a way that takes this into consideration)\&. It is recommended to either explicitly enable "secure mode" or to completely disable the pager using
1055 \fB\-\-no\-pager\fR
1056 or
1057 \fIPAGER=cat\fR
1058 when allowing untrusted users to execute commands with elevated privileges\&.
1059 .sp
1060 This option takes a boolean argument\&. When set to true, the "secure mode" of the pager is enabled\&. In "secure mode",
1061 \fBLESSSECURE=1\fR
1062 will be set when invoking the pager, which instructs the pager to disable commands that open or create new files or start new subprocesses\&. Currently only
1063 \fBless\fR(1)
1064 is known to understand this variable and implement "secure mode"\&.
1065 .sp
1066 When set to false, no limitation is placed on the pager\&. Setting
1067 \fISYSTEMD_PAGERSECURE=0\fR
1068 or not removing it from the inherited environment may allow the user to invoke arbitrary commands\&.
1069 .sp
1070 When
1071 \fI$SYSTEMD_PAGERSECURE\fR
1072 is not set, systemd tools attempt to automatically figure out if "secure mode" should be enabled and whether the pager supports it\&. "Secure mode" is enabled if the effective UID is not the same as the owner of the login session, see
1073 \fBgeteuid\fR(2)
1074 and
1075 \fBsd_pid_get_owner_uid\fR(3), or when running under
1076 \fBsudo\fR(8)
1077 or similar tools (\fI$SUDO_UID\fR
1078 is set
1079 \&\s-2\u[3]\d\s+2)\&. In those cases,
1080 \fISYSTEMD_PAGERSECURE=1\fR
1081 will be set and pagers which are not known to implement "secure mode" will not be used at all\&. Note that this autodetection only covers the most common mechanisms to elevate privileges and is intended as convenience\&. It is recommended to explicitly set
1082 \fI$SYSTEMD_PAGERSECURE\fR
1083 or disable the pager\&.
1084 .sp
1085 Note that if the
1086 \fI$SYSTEMD_PAGER\fR
1087 or
1088 \fI$PAGER\fR
1089 variables are to be honoured, other than to disable the pager,
1090 \fI$SYSTEMD_PAGERSECURE\fR
1091 must be set too\&.
1092 .RE
1093 .PP
1094 \fI$SYSTEMD_COLORS\fR
1095 .RS 4
1096 Takes a boolean argument, or a special value\&. By default (unset),
1097 \fBsystemd\fR
1098 and related utilities will use colors in their output if possible\&. If
1099 \fI$COLORTERM\fR
1100 is set to
1101 "truecolor"
1102 or
1103 "24bit", 24\-bit colors will be enabled, 256 colors otherwise, unless
1104 \fI$NO_COLOR\fR
1105 or
1106 \fI$TERM\fR
1107 indicates colors are disabled\&.
1108 .PP
1109 \fBtrue\fR
1110 .RS 4
1111 Same as unset, except that
1112 \fI$NO_COLOR\fR
1113 is ignored\&.
1114 .RE
1115 .PP
1116 \fBfalse\fR
1117 .RS 4
1118 The output will be monochrome\&.
1119 .RE
1120 .PP
1121 "16", "256", "24bit"
1122 .RS 4
1123 Always use the base 16 ANSI colors, 256 colors, or 24 bit color, respectively\&.
1124 .RE
1125 .PP
1126 "auto\-16", "auto\-256", "auto\-24bit"
1127 .RS 4
1128 Use the given quantity of colours, subject to
1129 \fI$TERM\fR, and what the console is connected to\&.
1130 .RE
1131 .RE
1132 .PP
1133 \fI$SYSTEMD_URLIFY\fR
1134 .RS 4
1135 The value must be a boolean\&. Controls whether clickable links should be generated in the output for terminal emulators supporting this\&. This can be specified to override the decision that
1136 \fBsystemd\fR
1137 makes based on
1138 \fI$TERM\fR
1139 and other conditions\&.
1140 .RE
1141 .SH "EXAMPLES"
1142 .PP
1143 \fBExample\ \&1.\ \&Run an Arch Linux VM image generated by mkosi\fR
1144 .sp
1145 .if n \{\
1146 .RS 4
1147 .\}
1148 .nf
1149 $ mkosi \-d arch \-p systemd \-p linux \-\-autologin \-o image\&.raw \-f build
1150 $ systemd\-vmspawn \-\-image=image\&.raw
1151 .fi
1152 .if n \{\
1153 .RE
1154 .\}
1155 .PP
1156 \fBExample\ \&2.\ \&Import and run a Fedora 44 Cloud image using importctl\fR
1157 .sp
1158 .if n \{\
1159 .RS 4
1160 .\}
1161 .nf
1162 $ curl \-L \e
1163 \-O https://download\&.fedoraproject\&.org/pub/fedora/linux/releases/44/Cloud/x86_64/images/Fedora\-Cloud\-Base\-Generic\-44\-1\&.7\&.x86_64\&.qcow2 \e
1164 \-O https://download\&.fedoraproject\&.org/pub/fedora/linux/releases/44/Cloud/x86_64/images/Fedora\-Cloud\-44\-1\&.7\-x86_64\-CHECKSUM \e
1165 \-O https://fedoraproject\&.org/fedora\&.gpg
1166 $ gpgv \-\-keyring \&./fedora\&.gpg Fedora\-Cloud\-44\-1\&.7\-x86_64\-CHECKSUM
1167 $ sha256sum \-c Fedora\-Cloud\-44\-1\&.7\-x86_64\-CHECKSUM
1168 # importctl import\-raw \-m Fedora\-Cloud\-Base\-Generic\-44\-1\&.7\&.x86_64\&.qcow2 fedora\-44\-cloud
1169 # systemd\-vmspawn \-M fedora\-44\-cloud
1170 .fi
1171 .if n \{\
1172 .RE
1173 .\}
1174 .PP
1175 \fBExample\ \&3.\ \&Build and run systemd\*(Aqs system image and forward the VM\*(Aqs journal to a local file\fR
1176 .sp
1177 .if n \{\
1178 .RS 4
1179 .\}
1180 .nf
1181 $ mkosi build
1182 $ systemd\-vmspawn \e
1183 \-D mkosi\&.output/system \e
1184 \-\-private\-users $(grep $(whoami) /etc/subuid | cut \-d: \-f2) \e
1185 \-\-linux mkosi\&.output/system\&.efi \e
1186 \-\-forward\-journal=vm\&.journal \e
1187 enforcing=0
1188 .fi
1189 .if n \{\
1190 .RE
1191 .\}
1192 .PP
1193 Note: this example also uses a kernel command line argument to ensure SELinux is not started in enforcing mode\&.
1194 .PP
1195 \fBExample\ \&4.\ \&SSH into a running VM using systemd\-ssh\-proxy\fR
1196 .sp
1197 .if n \{\
1198 .RS 4
1199 .\}
1200 .nf
1201 $ mkosi build
1202 $ my_vsock_cid=3735928559
1203 $ systemd\-vmspawn \e
1204 \-D mkosi\&.output/system \e
1205 \-\-private\-users $(grep $(whoami) /etc/subuid | cut \-d: \-f2) \e
1206 \-\-linux mkosi\&.output/system\&.efi \e
1207 \-\-vsock\-cid $my_vsock_cid \e
1208 enforcing=0
1209 $ ssh root@vsock/$my_vsock_cid \-i /run/user/$UID/systemd/vmspawn/machine\-*\-system\-ed25519
1210 .fi
1211 .if n \{\
1212 .RE
1213 .\}
1214 .SH "EXIT STATUS"
1215 .PP
1216 If an error occurred the value errno is propagated to the return code\&. If EXIT_STATUS is supplied by the running image that is returned\&. Otherwise, EXIT_SUCCESS is returned\&.
1217 .SH "SEE ALSO"
1218 .PP
1219 \fBsystemd\fR(1), \fBmkosi\fR(1), \fBmachinectl\fR(1), \fBimportctl\fR(1), \m[blue]\fBUAPI\&.1 Boot Loader Specification\fR\m[]\&\s-2\u[1]\d\s+2
1220 .SH "NOTES"
1221 .IP " 1." 4
1222 UAPI.1 Boot Loader Specification
1223 .RS 4
1224 \%https://uapi-group.org/specifications/specs/boot_loader_specification
1225 .RE
1226 .IP " 2." 4
1227 ANSI Escape Code (Wikipedia)
1228 .RS 4
1229 \%https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_(Select_Graphic_Rendition)_parameters
1230 .RE
1231 .IP " 3." 4
1232 It is recommended for other tools to set and check
1233 \fI$SUDO_UID\fR
1234 as appropriate, treating it is a common interface.
1235