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 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   5
   6 <refentry id="systemd-vmspawn" conditional="ENABLE_VMSPAWN"
   7     xmlns:xi="http://www.w3.org/2001/XInclude">
   8
   9   <refentryinfo>
  10     <title>systemd-vmspawn</title>
  11     <productname>systemd</productname>
  12   </refentryinfo>
  13
  14   <refmeta>
  15     <refentrytitle>systemd-vmspawn</refentrytitle>
  16     <manvolnum>1</manvolnum>
  17   </refmeta>
  18
  19   <refnamediv>
  20     <refname>systemd-vmspawn</refname>
  21     <refpurpose>Spawn an OS in a virtual machine.</refpurpose>
  22   </refnamediv>
  23
  24   <refsynopsisdiv>
  25     <cmdsynopsis>
  26       <command>systemd-vmspawn</command>
  27       <arg choice="opt" rep="repeat">OPTIONS</arg>
  28       <arg choice="opt" rep="repeat">ARGS</arg>
  29     </cmdsynopsis>
  30   </refsynopsisdiv>
  31
  32   <refsect1>
  33     <title>Description</title>
  34     <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
  35     project='man-pages'><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>, but it
  36     launches a full virtual machine instead of using namespaces.</para>
  37
  38     <para>File descriptors for <filename>/dev/kvm</filename> and <filename>/dev/vhost-vsock</filename> can be
  39     passed to <command>systemd-vmspawn</command> via systemd's native socket passing interface (see
  40     <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry> for
  41     details about the precise protocol used and the order in which the file descriptors are passed), these
  42     fds must be passed with the names <literal>kvm</literal> and <literal>vhost-vsock</literal> respectively.</para>
  43
  44     <para>Note: on Ubuntu/Debian derivatives systemd-vmspawn requires the user to be in the <literal>kvm</literal> group to use the VSock options.</para>
  45   </refsect1>
  46
  47   <refsect1>
  48     <title>Options</title>
  49
  50     <para>The excess arguments are passed as extra kernel command line arguments using SMBIOS.</para>
  51
  52     <para>The following options are understood:</para>
  53
  54     <variablelist>
  55
  56       <varlistentry>
  57         <term><option>-q</option></term>
  58         <term><option>--quiet</option></term>
  59
  60         <listitem><para>Turns off any status output by the tool
  61         itself. When this switch is used, the only output from vmspawn
  62         will be the console output of the Virtual Machine OS itself.</para>
  63
  64         <xi:include href="version-info.xml" xpointer="v256"/></listitem>
  65       </varlistentry>
  66
  67     </variablelist>
  68
  69     <refsect2>
  70       <title>Image Options</title>
  71
  72       <variablelist>
  73         <varlistentry>
  74           <term><option>-i</option></term>
  75           <term><option>--image=</option></term>
  76
  77           <listitem><para>Root file system disk image (or device node) for the virtual machine.</para>
  78
  79           <xi:include href="version-info.xml" xpointer="v255"/>
  80           </listitem>
  81         </varlistentry>
  82       </variablelist>
  83     </refsect2>
  84
  85     <refsect2>
  86       <title>Host Configuration</title>
  87
  88       <variablelist>
  89         <varlistentry>
  90           <term><option>--qemu-smp=</option><replaceable>SMP</replaceable></term>
  91
  92           <listitem><para>Configures the number of CPUs to start the virtual machine with.
  93           Defaults to 1.</para>
  94
  95           <xi:include href="version-info.xml" xpointer="v255"/>
  96           </listitem>
  97         </varlistentry>
  98
  99         <varlistentry>
 100           <term><option>--qemu-mem=</option><replaceable>MEM</replaceable></term>
 101
 102           <listitem><para>Configures the amount of memory to start the virtual machine with.
 103           Defaults to 2G.</para>
 104
 105           <xi:include href="version-info.xml" xpointer="v255"/>
 106           </listitem>
 107         </varlistentry>
 108
 109       <varlistentry>
 110         <term><option>--qemu-kvm=</option><replaceable>BOOL</replaceable></term>
 111
 112         <listitem><para>Configures whether to use KVM. If the option is not specified KVM support will be
 113         detected automatically. If true, KVM is always used, and if false, KVM is never used.</para>
 114
 115         <xi:include href="version-info.xml" xpointer="v255"/></listitem>
 116       </varlistentry>
 117
 118       <varlistentry>
 119         <term><option>--qemu-vsock=</option><replaceable>BOOL</replaceable></term>
 120
 121         <listitem>
 122           <para>Configure whether to use VSock networking.</para>
 123           <para>If the option is not specified VSock support will be detected automatically.
 124           If yes is specified VSocks are always used, and vice versa if no is set VSocks are never used.</para>
 125           <xi:include href="version-info.xml" xpointer="v255"/>
 126         </listitem>
 127       </varlistentry>
 128
 129       <varlistentry>
 130         <term><option>--vsock-cid=</option><replaceable>CID</replaceable></term>
 131
 132         <listitem>
 133           <para>Configure vmspawn to use a specific CID for the guest.</para>
 134           <para>If the option is not specified or an empty argument is supplied the guest will be assigned a random CID.</para>
 135           <para>Valid CIDs are in the range <constant>3</constant> to <constant>4294967294</constant> (<constant>0xFFFF_FFFE</constant>).
 136           CIDs outside of this range are reserved.</para>
 137           <xi:include href="version-info.xml" xpointer="v255"/>
 138         </listitem>
 139       </varlistentry>
 140
 141       <varlistentry>
 142         <term><option>--tpm=</option><replaceable>BOOL</replaceable></term>
 143
 144         <listitem>
 145           <para>Configure whether to use qemu with a virtual TPM or not.</para>
 146           <para>If the option is not specified vmspawn will detect the presence of <citerefentry project='man-pages'>
 147           <refentrytitle>swtpm</refentrytitle><manvolnum>8</manvolnum></citerefentry> and use it if available.
 148           If yes is specified <citerefentry project='man-pages'><refentrytitle>swtpm</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 149           is always used, and vice versa if no is set <citerefentry project='man-pages'><refentrytitle>swtpm</refentrytitle>
 150           <manvolnum>8</manvolnum></citerefentry> is never used.</para>
 151           <para>Note: the virtual TPM used may change in future.</para>
 152           <xi:include href="version-info.xml" xpointer="v256"/>
 153         </listitem>
 154       </varlistentry>
 155
 156       <varlistentry>
 157         <term><option>--linux=</option><replaceable>PATH</replaceable></term>
 158
 159         <listitem>
 160           <para>Set the linux kernel image to use for direct kernel boot.</para>
 161           <para>If no kernel was installed into the image then the image will fail to boot.</para>
 162           <xi:include href="version-info.xml" xpointer="v256"/>
 163         </listitem>
 164       </varlistentry>
 165
 166       <varlistentry>
 167         <term><option>--initrd=</option><replaceable>PATH</replaceable></term>
 168
 169         <listitem>
 170           <para>Set the initrd to use for direct kernel boot.</para>
 171           <para>If the linux kernel supplied is a UKI then this argument is not required.</para>
 172           <para>If no initrd was installed into the image then the image will fail to boot.</para>
 173           <xi:include href="version-info.xml" xpointer="v256"/>
 174         </listitem>
 175       </varlistentry>
 176
 177       <varlistentry>
 178         <term><option>--qemu-gui</option></term>
 179
 180         <listitem><para>Start QEMU in graphical mode.</para>
 181
 182         <xi:include href="version-info.xml" xpointer="v255"/></listitem>
 183       </varlistentry>
 184
 185       <varlistentry>
 186         <term><option>-n</option></term>
 187         <term><option>--network-tap</option></term>
 188
 189         <listitem>
 190           <para>Create a TAP device to network with the virtual machine.</para>
 191           <para>
 192             Note: root privileges are required to use TAP networking.
 193             Additionally requires a correctly setup
 194             <citerefentry><refentrytitle>systemd-networkd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 195             to be running on the host to ensure the host interface is correctly configured.
 196             The relevant <literal>.network</literal> file can be found at <filename>/usr/lib/systemd/network/80-vm-vt.network</filename>.
 197           </para>
 198           <xi:include href="version-info.xml" xpointer="v255"/>
 199         </listitem>
 200       </varlistentry>
 201
 202       <varlistentry>
 203         <term><option>--network-user-mode</option></term>
 204
 205         <listitem><para>Use user mode networking with QEMU.</para>
 206
 207         <xi:include href="version-info.xml" xpointer="v255"/></listitem>
 208       </varlistentry>
 209
 210       <varlistentry>
 211         <term><option>--firmware=</option><replaceable>PATH</replaceable></term>
 212
 213         <listitem><para>Takes an absolute path, or a relative path beginning with
 214         <filename>./</filename>. Specifies a JSON firmware definition file, which allows selecting the
 215         firmware to boot in the VM. If not specified a suitable firmware is automatically discovered. If the
 216         special string <literal>list</literal> is specified lists all discovered firmwares.</para>
 217
 218         <xi:include href="version-info.xml" xpointer="v256"/></listitem>
 219       </varlistentry>
 220
 221       <varlistentry>
 222         <term><option>--secure-boot=</option><replaceable>BOOL</replaceable></term>
 223
 224         <listitem><para>Configure whether to search for firmware which supports Secure Boot.</para>
 225         <para>If the option is not specified the first firmware which is detected will be used.
 226         If the option is set to yes then the first firmware with Secure Boot support will be selected.
 227         If no is specified then the first firmware without Secure Boot will be selected.</para>
 228
 229         <xi:include href="version-info.xml" xpointer="v255"/></listitem>
 230       </varlistentry>
 231       </variablelist>
 232     </refsect2>
 233
 234     <refsect2>
 235       <title>System Identity Options</title>
 236
 237       <variablelist>
 238         <varlistentry>
 239           <term><option>-M</option></term>
 240           <term><option>--machine=</option></term>
 241
 242           <listitem><para>Sets the machine name for this virtual machine. This
 243           name may be used to identify this virtual machine during its runtime
 244           (for example in tools like
 245           <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 246           and similar).</para>
 247           <xi:include href="version-info.xml" xpointer="v255"/>
 248           </listitem>
 249         </varlistentry>
 250       </variablelist>
 251
 252     </refsect2><refsect2>
 253       <title>Credentials</title>
 254
 255       <variablelist>
 256         <varlistentry>
 257           <term><option>--load-credential=</option><replaceable>ID</replaceable>:<replaceable>PATH</replaceable></term>
 258           <term><option>--set-credential=</option><replaceable>ID</replaceable>:<replaceable>VALUE</replaceable></term>
 259
 260           <listitem><para>Pass a credential to the virtual machine. These two options correspond to the
 261           <varname>LoadCredential=</varname> and <varname>SetCredential=</varname> settings in unit files. See
 262           <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
 263           details about these concepts, as well as the syntax of the option's arguments.</para>
 264
 265           <para>In order to embed binary data into the credential data for <option>--set-credential=</option>,
 266           use C-style escaping (i.e. <literal>\n</literal> to embed a newline, or <literal>\x00</literal> to
 267           embed a <constant>NUL</constant> byte). Note that the invoking shell might already apply unescaping
 268           once, hence this might require double escaping!.</para>
 269
 270           <xi:include href="version-info.xml" xpointer="v255"/></listitem>
 271         </varlistentry>
 272       </variablelist>
 273
 274     </refsect2><refsect2>
 275       <title>Other</title>
 276
 277       <variablelist>
 278         <xi:include href="standard-options.xml" xpointer="no-pager" />
 279         <xi:include href="standard-options.xml" xpointer="help" />
 280         <xi:include href="standard-options.xml" xpointer="version" />
 281       </variablelist>
 282     </refsect2>
 283   </refsect1>
 284
 285   <xi:include href="common-variables.xml" />
 286
 287   <refsect1>
 288     <title>Examples</title>
 289
 290     <example>
 291       <title>Run an Arch Linux VM image generated by mkosi</title>
 292
 293       <programlisting>
 294 $ mkosi -d arch -p systemd -p linux --autologin -o image.raw -f build
 295 $ systemd-vmspawn --image=image.raw
 296       </programlisting>
 297     </example>
 298   </refsect1>
 299
 300   <refsect1>
 301     <title>Exit status</title>
 302
 303     <para>If an error occurred the value errno is propagated to the return code.
 304     If EXIT_STATUS is supplied by the running image that is returned.
 305     Otherwise EXIT_SUCCESS is returned.</para>
 306   </refsect1>
 307
 308   <refsect1>
 309     <title>See Also</title>
 310     <para><simplelist type="inline">
 311       <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 312       <member><citerefentry><refentrytitle>mkosi</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 313     </simplelist></para>
 314   </refsect1>
 315 </refentry>