man/systemd-vmspawn.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
   4 <!ENTITY % entities SYSTEM "custom-entities.ent" >
   5 %entities;
   6 ]>
   7 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   8
   9 <refentry id="systemd-vmspawn" conditional="ENABLE_VMSPAWN"
  10     xmlns:xi="http://www.w3.org/2001/XInclude">
  11
  12   <refentryinfo>
  13     <title>systemd-vmspawn</title>
  14     <productname>systemd</productname>
  15   </refentryinfo>
  16
  17   <refmeta>
  18     <refentrytitle>systemd-vmspawn</refentrytitle>
  19     <manvolnum>1</manvolnum>
  20   </refmeta>
  21
  22   <refnamediv>
  23     <refname>systemd-vmspawn</refname>
  24     <refpurpose>Spawn an OS in a virtual machine</refpurpose>
  25   </refnamediv>
  26
  27   <refsynopsisdiv>
  28     <cmdsynopsis>
  29       <command>systemd-vmspawn</command>
  30       <arg choice="opt" rep="repeat">OPTIONS</arg>
  31       <arg choice="opt" rep="repeat">ARGS</arg>
  32     </cmdsynopsis>
  33   </refsynopsisdiv>
  34
  35   <refsect1>
  36     <title>Description</title>
  37     <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>
  38     <refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>, but
  39     launches a full virtual machine instead of using namespaces.</para>
  40
  41     <para>File descriptors for <filename>/dev/kvm</filename> and <filename>/dev/vhost-vsock</filename> can be
  42     passed to <command>systemd-vmspawn</command> via systemd's native socket passing interface (see
  43     <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry> for
  44     details about the precise protocol used and the order in which the file descriptors are passed), these
  45     file descriptors must be passed with the names <literal>kvm</literal> and <literal>vhost-vsock</literal>
  46     respectively.</para>
  47
  48     <para>Note: on Ubuntu/Debian derivatives systemd-vmspawn requires the user to be in the
  49     <literal>kvm</literal> group to use the VSOCK options.</para>
  50   </refsect1>
  51
  52   <refsect1>
  53     <title>Options</title>
  54
  55     <para>The excess arguments are passed as extra kernel command line arguments using SMBIOS.</para>
  56
  57     <para>The following options are understood:</para>
  58
  59     <variablelist>
  60
  61       <varlistentry>
  62         <term><option>-q</option></term>
  63         <term><option>--quiet</option></term>
  64
  65         <listitem><para>Turns off any status output by the tool
  66         itself. When this switch is used, the only output from vmspawn
  67         will be the console output of the Virtual Machine OS itself.</para>
  68
  69         <xi:include href="version-info.xml" xpointer="v256"/></listitem>
  70       </varlistentry>
  71
  72     </variablelist>
  73
  74     <refsect2>
  75       <title>Image Options</title>
  76
  77       <variablelist>
  78         <varlistentry>
  79           <term><option>-D</option></term>
  80           <term><option>--directory=</option></term>
  81
  82           <listitem><para>Directory to use as file system root for the virtual machine.</para>
  83
  84           <para>One of either <option>--directory=</option> or <option>--image=</option> must be specified.
  85           If neither are specified <option>--directory=.</option> is assumed.</para>
  86
  87           <para>Note: If mounting a non-root owned directory you may require <option>--private-users=</option>
  88           to map into the user's subuid namespace. An example of how to use <constant>/etc/subuid</constant>
  89           for this is given later.</para>
  90
  91           <xi:include href="version-info.xml" xpointer="v256"/>
  92           </listitem>
  93         </varlistentry>
  94
  95         <varlistentry>
  96           <term><option>-i</option></term>
  97           <term><option>--image=</option></term>
  98
  99           <listitem><para>Root file system disk image (or device node) for the virtual machine.</para>
 100
 101           <xi:include href="version-info.xml" xpointer="v255"/>
 102           </listitem>
 103         </varlistentry>
 104       </variablelist>
 105     </refsect2>
 106
 107     <refsect2>
 108       <title>Host Configuration</title>
 109
 110       <variablelist>
 111         <varlistentry>
 112           <term><option>--cpus=<replaceable>CPUS</replaceable></option></term>
 113
 114           <listitem><para>The number of CPUs to start the virtual machine with.
 115           Defaults to 1.</para>
 116
 117           <xi:include href="version-info.xml" xpointer="v255"/>
 118           </listitem>
 119         </varlistentry>
 120
 121         <varlistentry>
 122           <term><option>--ram=<replaceable>BYTES</replaceable></option></term>
 123
 124           <listitem><para>The amount of memory to start the virtual machine with.
 125           Defaults to 2G.</para>
 126
 127           <xi:include href="version-info.xml" xpointer="v255"/>
 128           </listitem>
 129         </varlistentry>
 130
 131         <varlistentry>
 132           <term><option>--kvm=<replaceable>BOOL</replaceable></option></term>
 133
 134           <listitem><para>If <option>--kvm=</option> is not specified KVM support will be
 135           detected automatically. If true, KVM is always used, and if false, KVM is never used.</para>
 136
 137           <xi:include href="version-info.xml" xpointer="v255"/></listitem>
 138         </varlistentry>
 139
 140         <varlistentry>
 141           <term><option>--vsock=<replaceable>BOOL</replaceable></option></term>
 142
 143           <listitem><para>If <option>--vsock=</option> is not specified VSOCK networking support will be
 144           detected automatically. If true, VSOCK networking is always used, and if false, VSOCK networking is never used.</para>
 145
 146           <xi:include href="version-info.xml" xpointer="v255"/></listitem>
 147         </varlistentry>
 148
 149         <varlistentry>
 150           <term><option>--vsock-cid=<replaceable>CID</replaceable></option></term>
 151
 152           <listitem>
 153             <para>Sets the specific CID to use for the guest.
 154             Valid CIDs are in the range <constant>3</constant> to <constant>4294967294</constant> (<constant>0xFFFF_FFFE</constant>).
 155             CIDs outside of this range are reserved. By default vmspawn will attempt to derive a CID for the guest derived from the machine name,
 156             falling back to a random CID if this CID is taken.</para>
 157
 158             <xi:include href="version-info.xml" xpointer="v255"/>
 159           </listitem>
 160         </varlistentry>
 161
 162         <varlistentry>
 163           <term><option>--tpm=<replaceable>BOOL</replaceable></option></term>
 164
 165           <listitem>
 166             <para>If <option>--tpm=</option> is not specified vmspawn will detect the presence of <citerefentry project='debian'>
 167             <refentrytitle>swtpm</refentrytitle><manvolnum>8</manvolnum></citerefentry> and use it if available.
 168             If yes is specified <citerefentry project='debian'><refentrytitle>swtpm</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 169             is always used, and if no is set <citerefentry project='debian'><refentrytitle>swtpm</refentrytitle>
 170             <manvolnum>8</manvolnum></citerefentry> is never used.</para>
 171
 172             <para>Note: the virtual TPM used may change in future.</para>
 173
 174             <xi:include href="version-info.xml" xpointer="v256"/>
 175           </listitem>
 176         </varlistentry>
 177
 178         <varlistentry>
 179           <term><option>--linux=<replaceable>PATH</replaceable></option></term>
 180
 181           <listitem>
 182             <para>Set the linux kernel image to use for direct kernel boot.
 183             If a directory type image is used and <option>--linux=</option> was omitted, vmspawn will search for boot loader entries
 184             according to the
 185             <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader Specification</ulink> assuming
 186             XBOOTLDR to be located at /boot and ESP to be /efi respectively.
 187             If no kernel was installed into the image then the image will fail to boot.</para>
 188
 189             <xi:include href="version-info.xml" xpointer="v256"/>
 190           </listitem>
 191         </varlistentry>
 192
 193         <varlistentry>
 194           <term><option>--initrd=<replaceable>PATH</replaceable></option></term>
 195
 196           <listitem>
 197             <para>Set the initrd to use for direct kernel boot.
 198             If the <option>--linux=</option> supplied is a
 199             <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader Specification</ulink>
 200             Type #2 entry, then this argument is not required.
 201             If no initrd was installed into the image then the image will fail to boot.</para>
 202
 203             <para><option>--initrd=</option> can be specified multiple times and vmspawn will merge them together.</para>
 204
 205             <xi:include href="version-info.xml" xpointer="v256"/>
 206           </listitem>
 207         </varlistentry>
 208
 209         <varlistentry>
 210           <term><option>-n</option></term>
 211           <term><option>--network-tap</option></term>
 212
 213           <listitem>
 214             <para>Create a TAP device to network with the virtual machine.</para>
 215
 216             <para>Note: root privileges are required to use TAP networking.
 217             Additionally,
 218             <citerefentry><refentrytitle>systemd-networkd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 219             must be running and correctly set up on the host to provision the host interface. The relevant
 220             <literal>.network</literal> file can be found at
 221             <filename>/usr/lib/systemd/network/80-vm-vt.network</filename>.
 222             </para>
 223
 224             <xi:include href="version-info.xml" xpointer="v255"/>
 225           </listitem>
 226         </varlistentry>
 227
 228         <varlistentry>
 229           <term><option>--network-user-mode</option></term>
 230
 231           <listitem><para>Use user mode networking.</para>
 232
 233           <xi:include href="version-info.xml" xpointer="v255"/></listitem>
 234         </varlistentry>
 235
 236         <varlistentry>
 237           <term><option>--firmware=<replaceable>PATH</replaceable></option></term>
 238
 239           <listitem><para>Takes an absolute path, or a relative path beginning with
 240           <filename>./</filename>. Specifies a JSON firmware definition file, which allows selecting the
 241           firmware to boot in the VM. If not specified a suitable firmware is automatically discovered. If the
 242           special string <literal>list</literal> is specified lists all discovered firmwares.</para>
 243
 244           <xi:include href="version-info.xml" xpointer="v256"/></listitem>
 245         </varlistentry>
 246
 247         <varlistentry>
 248           <term><option>--discard-disk=<replaceable>BOOL</replaceable></option></term>
 249
 250           <listitem><para>Controls whether qemu processes discard requests from the VM.
 251           This prevents long running VMs from using more disk space than required.
 252           This is enabled by default.</para>
 253
 254           <xi:include href="version-info.xml" xpointer="v256"/></listitem>
 255         </varlistentry>
 256
 257         <varlistentry>
 258           <term><option>--secure-boot=<replaceable>BOOL</replaceable></option></term>
 259
 260           <listitem><para>Configure whether to search for firmware which supports Secure Boot.</para>
 261
 262           <para>If the option is not specified the first firmware which is detected will be used.
 263           If the option is set to yes then the first firmware with Secure Boot support will be selected.
 264           If no is specified then the first firmware without Secure Boot will be selected.</para>
 265
 266           <xi:include href="version-info.xml" xpointer="v255"/></listitem>
 267         </varlistentry>
 268       </variablelist>
 269     </refsect2>
 270
 271     <refsect2>
 272       <title>System Identity Options</title>
 273
 274       <variablelist>
 275         <varlistentry>
 276           <term><option>-M</option></term>
 277           <term><option>--machine=</option></term>
 278
 279           <listitem><para>Sets the machine name for this virtual machine. This
 280           name may be used to identify this virtual machine during its runtime
 281           (for example in tools like
 282           <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 283           and similar).</para>
 284
 285           <xi:include href="version-info.xml" xpointer="v255"/>
 286           </listitem>
 287         </varlistentry>
 288
 289         <varlistentry>
 290           <term><option>--uuid=</option></term>
 291
 292           <listitem><para>Set the specified UUID for the virtual machine. The
 293           init system will initialize
 294           <filename>/etc/machine-id</filename> from this if this file is
 295           not set yet. Note that this option takes effect only if
 296           <filename>/etc/machine-id</filename> in the virtual machine is
 297           unpopulated.</para>
 298
 299           <xi:include href="version-info.xml" xpointer="v256"/></listitem>
 300         </varlistentry>
 301       </variablelist>
 302     </refsect2>
 303
 304     <refsect2>
 305       <title>Property Options</title>
 306
 307       <variablelist>
 308         <varlistentry>
 309           <term><option>--register=</option></term>
 310
 311           <listitem><para>Controls whether the virtual machine is registered with
 312           <citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>8</manvolnum></citerefentry>.  Takes a
 313           boolean argument, which defaults to <literal>yes</literal> when running as root, and <literal>no</literal> when
 314           running as a regular user.  This ensures that the virtual machine is accessible via
 315           <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
 316
 317           <para>Note: root privileges are required to use this option as registering with
 318           <citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 319           requires privileged D-Bus method calls.</para>
 320
 321           <xi:include href="version-info.xml" xpointer="v256"/></listitem>
 322         </varlistentry>
 323       </variablelist>
 324     </refsect2>
 325
 326     <refsect2>
 327       <title>User Namespacing Options</title>
 328
 329       <variablelist>
 330         <varlistentry>
 331           <term><option>--private-users=<replaceable>UID_SHIFT[:UID_RANGE]</replaceable></option></term>
 332
 333           <listitem><para>Controls user namespacing under <option>--directory=</option>.
 334           If enabled,
 335           <citerefentry><refentrytitle>virtiofsd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 336           is instructed to map user and group ids (UIDs and GIDs).
 337           This involves mapping the private UIDs/GIDs used in the virtual machine (starting with the virtual machine's
 338           root user 0 and up) to a range of UIDs/GIDs on the host that are not used for other purposes (usually in the
 339           range beyond the host's UID/GID 65536).</para>
 340
 341           <para>If one or two colon-separated numbers are specified, user namespacing is turned on. <replaceable>UID_SHIFT</replaceable>
 342           specifies the first host UID/GID to map, <replaceable>UID_RANGE</replaceable> is optional and specifies number of host
 343           UIDs/GIDs to assign to the virtual machine. If <replaceable>UID_RANGE</replaceable> is omitted, 65536 UIDs/GIDs are assigned.</para>
 344
 345           <para>When user namespaces are used, the GID range assigned to each virtual machine is always chosen identical to the
 346           UID range.</para>
 347
 348           <xi:include href="version-info.xml" xpointer="v256"/></listitem>
 349         </varlistentry>
 350       </variablelist>
 351     </refsect2>
 352
 353     <refsect2>
 354       <title>Mount Options</title>
 355
 356       <variablelist>
 357
 358         <varlistentry>
 359           <term><option>--bind=<replaceable>PATH</replaceable></option></term>
 360           <term><option>--bind-ro=<replaceable>PATH</replaceable></option></term>
 361
 362           <listitem><para>Mount a directory from the host into the virtual machine. Takes one of: a path
 363           argument — in which case the specified path will be mounted from the host to the same path in the virtual machine, or
 364           a colon-separated pair of paths — in which case the first specified path is the source in the host, and the
 365           second path is the destination in the virtual machine. If the source path is not absolute, it is resolved
 366           relative to the current working directory. The <option>--bind-ro=</option> option creates read-only bind mounts.
 367           Backslash escapes are interpreted, so <literal>\:</literal> may be used to embed colons in either path.
 368           This option may be specified multiple times for creating multiple independent bind mount points.</para>
 369
 370           <xi:include href="version-info.xml" xpointer="v256"/></listitem>
 371         </varlistentry>
 372
 373         <varlistentry>
 374           <term><option>--extra-drive=<replaceable>PATH</replaceable></option></term>
 375
 376           <listitem><para>Takes a disk image or block device on the host and supplies it to the virtual machine as another drive.</para>
 377
 378           <xi:include href="version-info.xml" xpointer="v256"/></listitem>
 379         </varlistentry>
 380
 381       </variablelist>
 382     </refsect2>
 383
 384     <refsect2>
 385       <title>Integration Options</title>
 386
 387       <variablelist>
 388         <varlistentry>
 389           <term><option>--forward-journal=<replaceable>FILE|DIR</replaceable></option></term>
 390
 391           <listitem><para>Forward the virtual machine's journal to the host.
 392           <citerefentry><refentrytitle>systemd-journal-remote</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 393           is currently used to receive the guest VM's forwarded journal entries. This option determines where
 394           this journal is saved on the host and has the same semantics as
 395           <option>-o</option>/<option>--output</option> described in
 396           <citerefentry><refentrytitle>systemd-journal-remote</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
 397
 398           <xi:include href="version-info.xml" xpointer="v256"/>
 399           </listitem>
 400         </varlistentry>
 401
 402         <varlistentry>
 403           <term><option>--pass-ssh-key=<replaceable>BOOL</replaceable></option></term>
 404
 405           <listitem><para>By default an SSH key is generated to allow <command>systemd-vmspawn</command> to open
 406           a D-Bus connection to the VM's systemd bus. Setting this to "no" will disable SSH key generation.</para>
 407
 408           <para>The generated keys are ephemeral. That is they are valid only for the current invocation of <command>systemd-vmspawn</command>,
 409           and are typically not persisted.</para>
 410
 411           <xi:include href="version-info.xml" xpointer="v256"/>
 412           </listitem>
 413         </varlistentry>
 414
 415         <varlistentry>
 416           <term><option>--ssh-key-type=<replaceable>TYPE</replaceable></option></term>
 417
 418           <listitem><para>Configures the type of SSH key to generate, see
 419           <citerefentry project="man-pages"><refentrytitle>ssh-keygen</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 420           for more information.</para>
 421
 422           <para>By default <literal>ed25519</literal> keys are generated, however <literal>rsa</literal> keys
 423           may also be useful if the VM has a particularly old version of <command>sshd</command>.</para>
 424
 425           <xi:include href="version-info.xml" xpointer="v256"/>
 426           </listitem>
 427         </varlistentry>
 428       </variablelist>
 429     </refsect2>
 430
 431     <refsect2>
 432       <title>Input/Output Options</title>
 433
 434       <variablelist>
 435         <varlistentry>
 436           <term><option>--console=<replaceable>MODE</replaceable></option></term>
 437
 438           <listitem><para>Configures how to set up the console of the VM. Takes one of
 439           <literal>interactive</literal>, <literal>read-only</literal>, <literal>native</literal>,
 440           <literal>gui</literal>. Defaults to <literal>interactive</literal>. <literal>interactive</literal>
 441           provides an interactive terminal interface to the VM. <literal>read-only</literal> is similar, but
 442           is strictly read-only, i.e. does not accept any input from the user. <literal>native</literal> also
 443           provides a TTY-based interface, but uses qemu native implementation (which means the qemu monitor
 444           is available). <literal>gui</literal> shows the qemu graphical UI.</para>
 445
 446           <xi:include href="version-info.xml" xpointer="v256"/></listitem>
 447         </varlistentry>
 448
 449         <varlistentry>
 450           <term><option>--background=<replaceable>COLOR</replaceable></option></term>
 451
 452           <listitem><para>Change the terminal background color to the specified ANSI color as long as the VM
 453           runs. The color specified should be an ANSI X3.64 SGR background color, i.e. strings such as
 454           <literal>40</literal>, <literal>41</literal>, …, <literal>47</literal>, <literal>48;2;…</literal>,
 455           <literal>48;5;…</literal>. See <ulink
 456           url="https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_(Select_Graphic_Rendition)_parameters">ANSI
 457           Escape Code (Wikipedia)</ulink> for details. Assign an empty string to disable any coloring. This
 458           only has an effect in <option>--console=interactive</option> and
 459           <option>--console=read-only</option> modes.</para>
 460
 461           <xi:include href="version-info.xml" xpointer="v256"/>
 462           </listitem>
 463         </varlistentry>
 464       </variablelist>
 465     </refsect2>
 466
 467     <refsect2>
 468       <title>Credentials</title>
 469
 470       <variablelist>
 471         <varlistentry>
 472           <term><option>--load-credential=<replaceable>ID</replaceable>:<replaceable>PATH</replaceable></option></term>
 473           <term><option>--set-credential=<replaceable>ID</replaceable>:<replaceable>VALUE</replaceable></option></term>
 474
 475           <listitem><para>Pass a credential to the virtual machine. These two options correspond to the
 476           <varname>LoadCredential=</varname> and <varname>SetCredential=</varname> settings in unit files. See
 477           <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
 478           details about these concepts, as well as the syntax of the option's arguments.</para>
 479
 480           <para>In order to embed binary data into the credential data for <option>--set-credential=</option>,
 481           use C-style escaping (i.e. <literal>\n</literal> to embed a newline, or <literal>\x00</literal> to
 482           embed a <constant>NUL</constant> byte). Note that the invoking shell might already apply unescaping
 483           once, hence this might require double escaping!</para>
 484
 485           <xi:include href="version-info.xml" xpointer="v255"/></listitem>
 486         </varlistentry>
 487       </variablelist>
 488
 489     </refsect2><refsect2>
 490       <title>Other</title>
 491
 492       <variablelist>
 493         <xi:include href="standard-options.xml" xpointer="no-pager" />
 494         <xi:include href="standard-options.xml" xpointer="help" />
 495         <xi:include href="standard-options.xml" xpointer="version" />
 496       </variablelist>
 497     </refsect2>
 498   </refsect1>
 499
 500   <xi:include href="common-variables.xml" />
 501
 502   <refsect1>
 503     <title>Examples</title>
 504
 505     <example>
 506       <title>Run an Arch Linux VM image generated by mkosi</title>
 507
 508       <programlisting>
 509 $ mkosi -d arch -p systemd -p linux --autologin -o image.raw -f build
 510 $ systemd-vmspawn --image=image.raw
 511       </programlisting>
 512     </example>
 513
 514     <example>
 515       <title>Import and run a Fedora 39 Cloud image using machinectl</title>
 516
 517       <programlisting>
 518 $ curl -L \
 519        -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 \
 520        -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 \
 521        -O https://fedoraproject.org/fedora.gpg
 522 $ gpgv --keyring ./fedora.gpg Fedora-Cloud-&fedora_latest_version;-&fedora_cloud_release;-x86_64-CHECKSUM
 523 $ sha256sum -c Fedora-Cloud-&fedora_latest_version;-&fedora_cloud_release;-x86_64-CHECKSUM
 524 # machinectl import-raw Fedora-Cloud-Base-&fedora_latest_version;-&fedora_cloud_release;.x86_64.raw.xz fedora-&fedora_latest_version;-cloud
 525 # systemd-vmspawn -M fedora-&fedora_latest_version;-cloud
 526       </programlisting>
 527     </example>
 528
 529     <example>
 530       <title>Build and run systemd's system image and forward the VM's journal to a local file</title>
 531
 532       <programlisting>
 533 $ mkosi build
 534 $ systemd-vmspawn \
 535     -D mkosi.output/system \
 536     --private-users $(grep $(whoami) /etc/subuid | cut -d: -f2) \
 537     --linux mkosi.output/system.efi \
 538     --forward-journal=vm.journal \
 539     enforcing=0
 540       </programlisting>
 541
 542       <para>Note: this example also uses a kernel command line argument to ensure SELinux isn't started in enforcing mode.</para>
 543     </example>
 544
 545     <example>
 546       <title>SSH into a running VM using <command>systemd-ssh-proxy</command></title>
 547
 548       <programlisting>
 549 $ mkosi build
 550 $ my_vsock_cid=3735928559
 551 $ systemd-vmspawn \
 552     -D mkosi.output/system \
 553     --private-users $(grep $(whoami) /etc/subuid | cut -d: -f2) \
 554     --linux mkosi.output/system.efi \
 555     --vsock-cid $my_vsock_cid \
 556     enforcing=0
 557 $ ssh root@vsock/$my_vsock_cid -i /run/user/$UID/systemd/vmspawn/machine-*-system-ed25519
 558       </programlisting>
 559     </example>
 560   </refsect1>
 561
 562   <refsect1>
 563     <title>Exit status</title>
 564
 565     <para>If an error occurred the value errno is propagated to the return code.
 566     If EXIT_STATUS is supplied by the running image that is returned.
 567     Otherwise EXIT_SUCCESS is returned.</para>
 568   </refsect1>
 569
 570   <refsect1>
 571     <title>See Also</title>
 572     <para><simplelist type="inline">
 573       <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 574       <member><citerefentry project='debian'><refentrytitle>mkosi</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 575       <member><citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 576       <member><citerefentry><refentrytitle>importctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 577       <member><ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader Specification</ulink></member>
 578     </simplelist></para>
 579   </refsect1>
 580 </refentry>