1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
|
<?xml version='1.0'?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % entities SYSTEM "custom-entities.ent" >
%entities;
]>
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
<refentry id="systemd-vmspawn" conditional="ENABLE_VMSPAWN"
xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>systemd-vmspawn</title>
<productname>systemd</productname>
</refentryinfo>
<refmeta>
<refentrytitle>systemd-vmspawn</refentrytitle>
<manvolnum>1</manvolnum>
</refmeta>
<refnamediv>
<refname>systemd-vmspawn</refname>
<refpurpose>Spawn an OS in a virtual machine</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>systemd-vmspawn</command>
<arg choice="opt" rep="repeat">OPTIONS</arg>
<arg choice="opt" rep="repeat">ARGS</arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para><command>systemd-vmspawn</command> may be used to start a virtual machine from an OS image. In many ways it is similar to <citerefentry>
<refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>, but
launches a full virtual machine instead of using namespaces.</para>
<para>File descriptors for <filename>/dev/kvm</filename> and <filename>/dev/vhost-vsock</filename> can be
passed to <command>systemd-vmspawn</command> via systemd's native socket passing interface (see
<citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry> 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 <literal>kvm</literal> and <literal>vhost-vsock</literal>
respectively.</para>
<para>Note: on Ubuntu/Debian derivatives <command>systemd-vmspawn</command> requires the user to be in the
<literal>kvm</literal> group to use the VSOCK options.</para>
</refsect1>
<refsect1>
<title>Options</title>
<para>The excess arguments are passed as extra kernel command line arguments using SMBIOS.</para>
<para>The following options are understood:</para>
<variablelist>
<varlistentry>
<term><option>-q</option></term>
<term><option>--quiet</option></term>
<listitem><para>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.</para>
<xi:include href="version-info.xml" xpointer="v256"/></listitem>
</varlistentry>
</variablelist>
<refsect2>
<title>Image Options</title>
<variablelist>
<varlistentry>
<term><option>-D</option></term>
<term><option>--directory=</option></term>
<listitem><para>Directory to use as file system root for the virtual machine.</para>
<para>One of either <option>--directory=</option> or <option>--image=</option> must be specified.
If neither are specified <option>--directory=.</option> is assumed.</para>
<para>Note: If mounting a non-root owned directory you may require <option>--private-users=</option>
to map into the user's subuid namespace. An example of how to use <constant>/etc/subuid</constant>
for this is given later.</para>
<xi:include href="version-info.xml" xpointer="v256"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-i</option></term>
<term><option>--image=</option></term>
<listitem><para>Root file system disk image (or device node) for the virtual machine.</para>
<xi:include href="version-info.xml" xpointer="v255"/>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
<refsect2>
<title>Host Configuration</title>
<variablelist>
<varlistentry>
<term><option>--cpus=<replaceable>CPUS</replaceable></option></term>
<listitem><para>The number of CPUs to start the virtual machine with.
Defaults to 1.</para>
<xi:include href="version-info.xml" xpointer="v255"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--ram=<replaceable>BYTES</replaceable></option></term>
<listitem><para>The amount of memory to start the virtual machine with.
Defaults to 2G.</para>
<xi:include href="version-info.xml" xpointer="v255"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--kvm=<replaceable>BOOL</replaceable></option></term>
<listitem><para>If <option>--kvm=</option> is not specified, KVM support will be
detected automatically. If true, KVM is always used, and if false, KVM is never used.</para>
<xi:include href="version-info.xml" xpointer="v255"/></listitem>
</varlistentry>
<varlistentry>
<term><option>--vsock=<replaceable>BOOL</replaceable></option></term>
<listitem><para>If <option>--vsock=</option> is not specified, VSOCK networking support will be
detected automatically. If true, VSOCK networking is always used, and if false, VSOCK networking is never used.</para>
<xi:include href="version-info.xml" xpointer="v255"/></listitem>
</varlistentry>
<varlistentry>
<term><option>--vsock-cid=<replaceable>CID</replaceable></option></term>
<listitem>
<para>Sets the specific CID to use for the guest.
Valid CIDs are in the range <constant>3</constant> to <constant>4294967294</constant> (<constant>0xFFFF_FFFE</constant>).
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.</para>
<xi:include href="version-info.xml" xpointer="v255"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--tpm=<replaceable>BOOL</replaceable></option></term>
<listitem>
<para>If <option>--tpm=</option> is not specified, vmspawn will detect the presence of <citerefentry project='debian'>
<refentrytitle>swtpm</refentrytitle><manvolnum>8</manvolnum></citerefentry> and use it if
available. If yes is specified <citerefentry
project='debian'><refentrytitle>swtpm</refentrytitle><manvolnum>8</manvolnum></citerefentry> is
always used, and if no is set <citerefentry project='debian'><refentrytitle>swtpm</refentrytitle>
<manvolnum>8</manvolnum></citerefentry> is never used.</para>
<xi:include href="version-info.xml" xpointer="v256"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--tpm-state=<replaceable>PATH</replaceable>|auto|off</option></term>
<listitem><para>Configures where to place TPM state, in case TPM support is enabled (see
<option>--tpm=</option> 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 <literal>auto</literal> a persistent path is automatically derived from the VM image
path or directory path, with the <literal>.tpmstate</literal> suffix appended. If set to the
special string <literal>off</literal> 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 <literal>auto</literal>.</para>
<xi:include href="version-info.xml" xpointer="v258"/></listitem>
</varlistentry>
<varlistentry>
<term><option>--linux=<replaceable>PATH</replaceable></option></term>
<listitem>
<para>Set the linux kernel image to use for direct kernel boot.
If a directory type image is used and <option>--linux=</option> was omitted, vmspawn will search for boot loader entries
according to the
<ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">UAPI.1 Boot Loader Specification</ulink> 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.</para>
<xi:include href="version-info.xml" xpointer="v256"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--initrd=<replaceable>PATH</replaceable></option></term>
<listitem>
<para>Set the initrd to use for direct kernel boot.
If the <option>--linux=</option> supplied is a
<ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">UAPI.1 Boot Loader Specification</ulink>
Type #2 entry, then this argument is not required.
If no initrd was installed into the image then the image will fail to boot.</para>
<para><option>--initrd=</option> can be specified multiple times and vmspawn will merge them together.</para>
<xi:include href="version-info.xml" xpointer="v256"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-n</option></term>
<term><option>--network-tap</option></term>
<listitem>
<para>Create a TAP device to network with the virtual machine.</para>
<para>Note: root privileges are required to use TAP networking.
Additionally,
<citerefentry><refentrytitle>systemd-networkd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
must be running and correctly set up on the host to provision the host interface. The relevant
<literal>.network</literal> file can be found at
<filename>/usr/lib/systemd/network/80-vm-vt.network</filename>.
</para>
<xi:include href="version-info.xml" xpointer="v255"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--network-user-mode</option></term>
<listitem><para>Use user mode networking.</para>
<xi:include href="version-info.xml" xpointer="v255"/></listitem>
</varlistentry>
<varlistentry>
<term><option>--firmware=<replaceable>PATH</replaceable></option></term>
<listitem><para>Takes an absolute path, or a relative path beginning with
<filename>./</filename>. Specifies a JSON firmware definition file, which allows selecting the
firmware to boot in the VM. If not specified, a suitable firmware is automatically discovered. If the
special string <literal>list</literal> is specified lists all discovered firmwares.</para>
<xi:include href="version-info.xml" xpointer="v256"/></listitem>
</varlistentry>
<varlistentry>
<term><option>--discard-disk=<replaceable>BOOL</replaceable></option></term>
<listitem><para>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.</para>
<xi:include href="version-info.xml" xpointer="v256"/></listitem>
</varlistentry>
<varlistentry>
<term><option>--secure-boot=<replaceable>BOOL</replaceable></option></term>
<listitem><para>Configure whether to search for firmware which supports Secure Boot.</para>
<para>If the option is not specified, the first firmware which is detected will be used.
If the option is set to yes, then the first firmware with Secure Boot support will be selected.
If no is specified, then the first firmware without Secure Boot will be selected.</para>
<xi:include href="version-info.xml" xpointer="v255"/></listitem>
</varlistentry>
<varlistentry>
<term><option>--grow-image=<replaceable>BYTES</replaceable></option></term>
<term><option>-G <replaceable>BYTES</replaceable></option></term>
<listitem><para>Grows the image file specified by <option>--image=</option> 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.</para>
<xi:include href="version-info.xml" xpointer="v258"/></listitem>
</varlistentry>
<varlistentry>
<term><option>--smbios11=<replaceable>STRING</replaceable></option></term>
<term><option>-s <replaceable>STRING</replaceable></option></term>
<listitem><para>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
<citerefentry><refentrytitle>smbios-type-11</refentrytitle><manvolnum>7</manvolnum></citerefentry>
for details.</para>
<xi:include href="version-info.xml" xpointer="v258"/></listitem>
</varlistentry>
<varlistentry>
<term><option>--notify-ready=</option></term>
<listitem><para>Configures support for notifications from the VM's init process to
<command>systemd-vmspawn</command>. If true, <command>systemd-vmspawn</command> will consider the
machine as ready only when it has received a <literal>READY=1</literal> message from the init
process in the VM. If false, <command>systemd-vmspawn</command> will consider the machine as ready
immediately after creation. In either case, <command>systemd-vmspawn</command> sends its own
readiness notification to its manager after the spawned VM is ready. For more details about
notifications see
<citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
<para>Defaults to true. (Note that this is unlike the option of the same name to
<citerefentry><refentrytitle>systemd-vmspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
that defaults to false.)</para>
<xi:include href="version-info.xml" xpointer="v258"/></listitem>
</varlistentry>
</variablelist>
</refsect2>
<refsect2>
<title>System Identity Options</title>
<variablelist>
<varlistentry>
<term><option>-M</option></term>
<term><option>--machine=</option></term>
<listitem><para>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
<citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
and similar).</para>
<xi:include href="version-info.xml" xpointer="v255"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--uuid=</option></term>
<listitem><para>Set the specified UUID for the virtual machine. The
init system will initialize
<filename>/etc/machine-id</filename> from this if this file is
not set yet. Note that this option takes effect only if
<filename>/etc/machine-id</filename> in the virtual machine is
unpopulated.</para>
<xi:include href="version-info.xml" xpointer="v256"/></listitem>
</varlistentry>
</variablelist>
</refsect2>
<refsect2>
<title>Property Options</title>
<variablelist>
<varlistentry>
<term><option>-S</option></term>
<term><option>--slice=</option></term>
<listitem><para>Make the VM part of the specified slice, instead of the default
<filename>machine.slice</filename>. This applies only if the machine is run in its own scope unit,
i.e. if <option>--keep-unit</option> is not used.</para>
<xi:include href="version-info.xml" xpointer="v258"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--property=</option></term>
<listitem><para>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 <option>--keep-unit</option> is not
used. Takes unit property assignments in the same format as <command>systemctl
set-property</command>. This is useful to set memory limits and similar for the VM.</para>
<xi:include href="version-info.xml" xpointer="v258"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--register=</option></term>
<listitem><para>Controls whether the virtual machine is registered with
<citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>8</manvolnum></citerefentry>. Takes a
boolean argument, which defaults to <literal>yes</literal> when running as root, and <literal>no</literal> when
running as a regular user. This ensures that the virtual machine is accessible via
<citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
<para>Note: root privileges are required to use this option as registering with
<citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>8</manvolnum></citerefentry>
requires privileged D-Bus method calls.</para>
<xi:include href="version-info.xml" xpointer="v256"/></listitem>
</varlistentry>
</variablelist>
</refsect2>
<refsect2>
<title>User Namespacing Options</title>
<variablelist>
<varlistentry>
<term><option>--private-users=<replaceable>UID_SHIFT[:UID_RANGE]</replaceable></option></term>
<listitem><para>Controls user namespacing under <option>--directory=</option>.
If enabled,
<citerefentry project='url'><refentrytitle url='https://manpages.debian.org/unstable/qemu-system-common/virtiofsd.1.en.html'>virtiofsd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
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's
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's UID/GID 65536).</para>
<para>If one or two colon-separated numbers are specified, user namespacing is turned on. <replaceable>UID_SHIFT</replaceable>
specifies the first host UID/GID to map, <replaceable>UID_RANGE</replaceable> is optional and specifies number of host
UIDs/GIDs to assign to the virtual machine. If <replaceable>UID_RANGE</replaceable> is omitted, 65536 UIDs/GIDs are assigned.</para>
<para>When user namespaces are used, the GID range assigned to each virtual machine is always chosen identical to the
UID range.</para>
<xi:include href="version-info.xml" xpointer="v256"/></listitem>
</varlistentry>
</variablelist>
</refsect2>
<refsect2>
<title>Mount Options</title>
<variablelist>
<varlistentry>
<term><option>--bind=<replaceable>PATH</replaceable></option></term>
<term><option>--bind-ro=<replaceable>PATH</replaceable></option></term>
<listitem><para>Mount a directory from the host into the virtual machine. Takes one of: a path
argument — 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 — 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 <option>--bind-ro=</option> option creates read-only bind mounts.
Backslash escapes are interpreted, so <literal>\:</literal> may be used to embed colons in either path.
This option may be specified multiple times for creating multiple independent bind mount points.</para>
<xi:include href="version-info.xml" xpointer="v256"/></listitem>
</varlistentry>
<varlistentry>
<term><option>--extra-drive=<replaceable>PATH</replaceable></option></term>
<listitem><para>Takes a disk image or block device on the host and supplies it to the virtual machine as another drive.</para>
<xi:include href="version-info.xml" xpointer="v256"/></listitem>
</varlistentry>
<varlistentry>
<term><option>--bind-user=</option></term>
<listitem><para>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:</para>
<orderedlist>
<listitem><para>The user's home directory is made available from the host into
<filename>/run/vmhost/home/</filename> using virtiofs. virtiofsd id translation to map the host
user's UID/GID to its assigned UID/GID in the virtual machine.</para></listitem>
<listitem><para>JSON user and group records are generated in that describes the mapped user which
are passed into the virtual machine using <literal>userdb.transient.*</literal> credentials.
They contain a minimized representation of the host's user record, adjusted to the UID/GID and
home directory path assigned to the user in the virtual machine. The
<citerefentry><refentrytitle>nss-systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
glibc NSS module will pick up these records from there and make them available in the virtual
machine's user/group databases.</para></listitem>
</orderedlist>
<para>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 <option>--bind-user=</option> mapping), those files and directories will be accessible to
the "new" user.</para>
<para>The user/group record mapping only works if the virtual machine contains systemd 258 or
newer, with <command>nss-systemd</command> properly configured in
<filename>nsswitch.conf</filename>. See
<citerefentry><refentrytitle>nss-systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry> for
details.</para>
<para>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 <literal>$y$</literal> hash prefix).</para>
<xi:include href="version-info.xml" xpointer="v259"/></listitem>
</varlistentry>
<varlistentry>
<term><option>--bind-user-shell=</option></term>
<listitem><para>When used with <option>--bind-user=</option>, includes the specified shell in the
user records of users bound into the virtual machine. Takes either a boolean or an absolute path.</para>
<itemizedlist>
<listitem><para>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's default shell.</para></listitem>
<listitem><para>If true, the shells specified by the host user records are included in the user records of all users bound into the virtual machine.</para></listitem>
<listitem><para>If passed an absolute path, sets that path as the shell for user records of all users bound into the virtual machine.</para></listitem>
</itemizedlist>
<para>Note: This will not check whether the specified shells exist in the virtual machine.</para>
<para>This operation is only supported in combination with <option>--bind-user=</option>.</para>
<xi:include href="version-info.xml" xpointer="v259"/></listitem>
</varlistentry>
<varlistentry>
<term><option>--bind-user-group=<replaceable>NAME</replaceable></option></term>
<listitem><para>When used with <option>--bind-user=</option>, includes the specified group as an
auxiliary group in the user records of users bound into the virtual machine. Takes a group name.</para>
<para>Note: This will not check whether the specified groups exist in the virtual machine.</para>
<para>This operation is only supported in combination with <option>--bind-user=</option>.</para>
<xi:include href="version-info.xml" xpointer="v259"/></listitem>
</varlistentry>
</variablelist>
</refsect2>
<refsect2>
<title>Integration Options</title>
<variablelist>
<varlistentry>
<term><option>--forward-journal=<replaceable>FILE|DIR</replaceable></option></term>
<listitem><para>Forward the virtual machine's journal to the host.
<citerefentry><refentrytitle>systemd-journal-remote</refentrytitle><manvolnum>8</manvolnum></citerefentry>
is currently used to receive the guest VM's forwarded journal entries. This option determines where
this journal is saved on the host and has the same semantics as
<option>-o</option>/<option>--output</option> described in
<citerefentry><refentrytitle>systemd-journal-remote</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
<xi:include href="version-info.xml" xpointer="v256"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--pass-ssh-key=<replaceable>BOOL</replaceable></option></term>
<listitem><para>By default, an SSH key is generated to allow <command>systemd-vmspawn</command> to open
a D-Bus connection to the VM's systemd bus. Setting this to "no" will disable SSH key generation.</para>
<para>The generated keys are ephemeral. That is they are valid only for the current invocation of <command>systemd-vmspawn</command>,
and are typically not persisted.</para>
<xi:include href="version-info.xml" xpointer="v256"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--ssh-key-type=<replaceable>TYPE</replaceable></option></term>
<listitem><para>Configures the type of SSH key to generate, see
<citerefentry project="man-pages"><refentrytitle>ssh-keygen</refentrytitle><manvolnum>1</manvolnum></citerefentry>
for more information.</para>
<para>By default, <literal>ed25519</literal> keys are generated, however <literal>rsa</literal> keys
may also be useful if the VM has a particularly old version of
<citerefentry project='man-pages'><refentrytitle>sshd</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
<xi:include href="version-info.xml" xpointer="v256"/>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
<refsect2>
<title>Input/Output Options</title>
<variablelist>
<varlistentry>
<term><option>--console=<replaceable>MODE</replaceable></option></term>
<listitem><para>Configures how to set up the console of the VM. Takes one of
<literal>interactive</literal>, <literal>read-only</literal>, <literal>native</literal>,
<literal>gui</literal>. Defaults to <literal>interactive</literal>. <literal>interactive</literal>
provides an interactive terminal interface to the VM. <literal>read-only</literal> is similar, but
is strictly read-only, i.e. does not accept any input from the user. <literal>native</literal> also
provides a TTY-based interface, but uses qemu native implementation (which means the qemu monitor
is available). <literal>gui</literal> shows the qemu graphical UI.</para>
<xi:include href="version-info.xml" xpointer="v256"/></listitem>
</varlistentry>
<varlistentry>
<term><option>--background=<replaceable>COLOR</replaceable></option></term>
<listitem><para>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
<literal>40</literal>, <literal>41</literal>, …, <literal>47</literal>, <literal>48;2;…</literal>,
<literal>48;5;…</literal>. See <ulink
url="https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_(Select_Graphic_Rendition)_parameters">ANSI
Escape Code (Wikipedia)</ulink> for details. Assign an empty string to disable any coloring. This
only has an effect in <option>--console=interactive</option> and
<option>--console=read-only</option> modes.</para>
<xi:include href="version-info.xml" xpointer="v256"/>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
<refsect2>
<title>Credentials</title>
<variablelist>
<varlistentry>
<term><option>--load-credential=<replaceable>ID</replaceable>:<replaceable>PATH</replaceable></option></term>
<term><option>--set-credential=<replaceable>ID</replaceable>:<replaceable>VALUE</replaceable></option></term>
<listitem><para>Pass a credential to the virtual machine. These two options correspond to the
<varname>LoadCredential=</varname> and <varname>SetCredential=</varname> settings in unit files. See
<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
details about these concepts, as well as the syntax of the option's arguments.</para>
<para>In order to embed binary data into the credential data for <option>--set-credential=</option>,
use C-style escaping (i.e. <literal>\n</literal> to embed a newline, or <literal>\x00</literal> to
embed a <constant>NUL</constant> byte). Note that the invoking shell might already apply unescaping
once, hence this might require double escaping!</para>
<xi:include href="version-info.xml" xpointer="v255"/></listitem>
</varlistentry>
</variablelist>
</refsect2><refsect2>
<title>Other</title>
<variablelist>
<xi:include href="standard-options.xml" xpointer="no-pager" />
<xi:include href="standard-options.xml" xpointer="help" />
<xi:include href="standard-options.xml" xpointer="version" />
<xi:include href="standard-options.xml" xpointer="no-ask-password" />
</variablelist>
</refsect2>
</refsect1>
<xi:include href="common-variables.xml" />
<refsect1>
<title>Examples</title>
<example>
<title>Run an Arch Linux VM image generated by mkosi</title>
<programlisting>
$ mkosi -d arch -p systemd -p linux --autologin -o image.raw -f build
$ systemd-vmspawn --image=image.raw
</programlisting>
</example>
<example>
<title>Import and run a Fedora &fedora_latest_version; Cloud image using machinectl</title>
<programlisting>
$ curl -L \
-O 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 \
-O https://download.fedoraproject.org/pub/fedora/linux/releases/&fedora_latest_version;/Cloud/x86_64/images/Fedora-Cloud-&fedora_latest_version;-&fedora_cloud_release;-x86_64-CHECKSUM \
-O https://fedoraproject.org/fedora.gpg
$ gpgv --keyring ./fedora.gpg Fedora-Cloud-&fedora_latest_version;-&fedora_cloud_release;-x86_64-CHECKSUM
$ sha256sum -c Fedora-Cloud-&fedora_latest_version;-&fedora_cloud_release;-x86_64-CHECKSUM
# machinectl import-raw Fedora-Cloud-Base-&fedora_latest_version;-&fedora_cloud_release;.x86_64.raw.xz fedora-&fedora_latest_version;-cloud
# systemd-vmspawn -M fedora-&fedora_latest_version;-cloud
</programlisting>
</example>
<example>
<title>Build and run systemd's system image and forward the VM's journal to a local file</title>
<programlisting>
$ mkosi build
$ systemd-vmspawn \
-D mkosi.output/system \
--private-users $(grep $(whoami) /etc/subuid | cut -d: -f2) \
--linux mkosi.output/system.efi \
--forward-journal=vm.journal \
enforcing=0
</programlisting>
<para>Note: this example also uses a kernel command line argument to ensure SELinux is not started in
enforcing mode.</para>
</example>
<example>
<title>SSH into a running VM using <command>systemd-ssh-proxy</command></title>
<programlisting>
$ mkosi build
$ my_vsock_cid=3735928559
$ systemd-vmspawn \
-D mkosi.output/system \
--private-users $(grep $(whoami) /etc/subuid | cut -d: -f2) \
--linux mkosi.output/system.efi \
--vsock-cid $my_vsock_cid \
enforcing=0
$ ssh root@vsock/$my_vsock_cid -i /run/user/$UID/systemd/vmspawn/machine-*-system-ed25519
</programlisting>
</example>
</refsect1>
<refsect1>
<title>Exit status</title>
<para>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.</para>
</refsect1>
<refsect1>
<title>See Also</title>
<para><simplelist type="inline">
<member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
<member><citerefentry project='debian'><refentrytitle>mkosi</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>importctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
<member><ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">UAPI.1 Boot Loader Specification</ulink></member>
</simplelist></para>
</refsect1>
</refentry>
|
