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.2/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>Note: on Ubuntu/Debian derivatives systemd-vmspawn requires the user to be in the <literal>kvm</literal> group to use the VSock options.</para>
  39   </refsect1>
  40
  41   <refsect1>
  42     <title>Options</title>
  43
  44     <para>The excess arguments are passed as extra kernel command line arguments using SMBIOS.</para>
  45
  46     <para>The following options are understood:</para>
  47
  48     <refsect2>
  49       <title>Image Options</title>
  50
  51       <variablelist>
  52         <varlistentry>
  53           <term><option>-D</option></term>
  54           <term><option>--directory=</option></term>
  55
  56           <listitem><para>Directory to use as file system root for the virtual machine.</para>
  57
  58           <para>One of either <option>--directory=</option> or <option>--image=</option> must be specified.
  59           If neither are specified <option>--directory=.</option> is assumed.</para>
  60
  61           <para>Note: If mounting a non-root owned directory you may require <option>--private-users=</option>
  62           to map into the user's subuid namespace. An example of how to use <constant>/etc/subuid</constant>
  63           for this is given later.</para>
  64
  65           <xi:include href="version-info.xml" xpointer="v256"/>
  66           </listitem>
  67         </varlistentry>
  68
  69         <varlistentry>
  70           <term><option>-i</option></term>
  71           <term><option>--image=</option></term>
  72
  73           <listitem><para>Root file system disk image (or device node) for the virtual machine.</para>
  74
  75           <xi:include href="version-info.xml" xpointer="v255"/>
  76           </listitem>
  77         </varlistentry>
  78       </variablelist>
  79     </refsect2>
  80
  81     <refsect2>
  82       <title>Host Configuration</title>
  83
  84       <variablelist>
  85         <varlistentry>
  86           <term><option>--qemu-smp=</option><replaceable>SMP</replaceable></term>
  87
  88           <listitem><para>Configures the number of CPUs to start the virtual machine with.
  89           Defaults to 1.</para>
  90
  91           <xi:include href="version-info.xml" xpointer="v255"/>
  92           </listitem>
  93         </varlistentry>
  94
  95         <varlistentry>
  96           <term><option>--qemu-mem=</option><replaceable>MEM</replaceable></term>
  97
  98           <listitem><para>Configures the amount of memory to start the virtual machine with.
  99           Defaults to 2G.</para>
 100
 101           <xi:include href="version-info.xml" xpointer="v255"/>
 102           </listitem>
 103         </varlistentry>
 104
 105       <varlistentry>
 106         <term><option>--qemu-kvm=</option><replaceable>BOOL</replaceable></term>
 107
 108         <listitem><para>Configures whether to use KVM. If the option is not specified KVM support will be
 109         detected automatically. If true, KVM is always used, and if false, KVM is never used.</para>
 110
 111         <xi:include href="version-info.xml" xpointer="v255"/></listitem>
 112       </varlistentry>
 113
 114       <varlistentry>
 115         <term><option>--qemu-vsock=</option><replaceable>BOOL</replaceable></term>
 116
 117         <listitem>
 118           <para>Configure whether to use VSock networking.</para>
 119           <para>If the option is not specified VSock support will be detected automatically.
 120           If yes is specified VSocks are always used, and vice versa if no is set VSocks are never used.</para>
 121           <xi:include href="version-info.xml" xpointer="v255"/>
 122         </listitem>
 123       </varlistentry>
 124
 125       <varlistentry>
 126         <term><option>--vsock-cid=</option><replaceable>CID</replaceable></term>
 127
 128         <listitem>
 129           <para>Configure vmspawn to use a specific CID for the guest.</para>
 130           <para>If the option is not specified or an empty argument is supplied the guest will be assigned a random CID.</para>
 131           <para>Valid CIDs are in the range <constant>3</constant> to <constant>4294967294</constant> (<constant>0xFFFF_FFFE</constant>).
 132           CIDs outside of this range are reserved.</para>
 133           <xi:include href="version-info.xml" xpointer="v255"/>
 134         </listitem>
 135       </varlistentry>
 136
 137       <varlistentry>
 138         <term><option>--qemu-gui</option></term>
 139
 140         <listitem><para>Start QEMU in graphical mode.</para>
 141
 142         <xi:include href="version-info.xml" xpointer="v255"/></listitem>
 143       </varlistentry>
 144
 145       <varlistentry>
 146         <term><option>--secure-boot=</option><replaceable>BOOL</replaceable></term>
 147
 148         <listitem><para>Configure whether to search for firmware which supports Secure Boot.</para>
 149         <para>If the option is not specified the first firmware which is detected will be used.
 150         If the option is set to yes then the first firmware with Secure Boot support will be selected.
 151         If no is specified then the first firmware without Secure Boot will be selected.</para>
 152
 153         <xi:include href="version-info.xml" xpointer="v255"/></listitem>
 154       </varlistentry>
 155     </variablelist>
 156
 157     </refsect2><refsect2>
 158       <title>System Identity Options</title>
 159
 160       <variablelist>
 161         <varlistentry>
 162           <term><option>-M</option></term>
 163           <term><option>--machine=</option></term>
 164
 165           <listitem><para>Sets the machine name for this container. This
 166           name may be used to identify this container during its runtime
 167           (for example in tools like
 168           <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 169           and similar).</para>
 170           <xi:include href="version-info.xml" xpointer="v255"/>
 171           </listitem>
 172         </varlistentry>
 173       </variablelist>
 174
 175     </refsect2><refsect2>
 176       <title>Credentials</title>
 177
 178       <variablelist>
 179         <varlistentry>
 180           <term><option>--load-credential=</option><replaceable>ID</replaceable>:<replaceable>PATH</replaceable></term>
 181           <term><option>--set-credential=</option><replaceable>ID</replaceable>:<replaceable>VALUE</replaceable></term>
 182
 183           <listitem><para>Pass a credential to the container. These two options correspond to the
 184           <varname>LoadCredential=</varname> and <varname>SetCredential=</varname> settings in unit files. See
 185           <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
 186           details about these concepts, as well as the syntax of the option's arguments.</para>
 187
 188           <para>In order to embed binary data into the credential data for <option>--set-credential=</option>,
 189           use C-style escaping (i.e. <literal>\n</literal> to embed a newline, or <literal>\x00</literal> to
 190           embed a <constant>NUL</constant> byte). Note that the invoking shell might already apply unescaping
 191           once, hence this might require double escaping!</para>
 192
 193           <xi:include href="version-info.xml" xpointer="v255"/></listitem>
 194         </varlistentry>
 195       </variablelist>
 196
 197     </refsect2><refsect2>
 198       <title>Other</title>
 199
 200       <variablelist>
 201         <xi:include href="standard-options.xml" xpointer="no-pager" />
 202         <xi:include href="standard-options.xml" xpointer="help" />
 203         <xi:include href="standard-options.xml" xpointer="version" />
 204       </variablelist>
 205     </refsect2>
 206   </refsect1>
 207
 208   <xi:include href="common-variables.xml" />
 209
 210   <refsect1>
 211     <title>Examples</title>
 212
 213     <example>
 214       <title>Run an Arch Linux VM image generated by mkosi</title>
 215
 216       <programlisting>
 217 $ mkosi -d arch -p systemd -p linux --autologin -o image.raw -f build
 218 $ systemd-vmspawn --image=image.raw
 219       </programlisting>
 220     </example>
 221   </refsect1>
 222
 223   <refsect1>
 224     <title>Exit status</title>
 225
 226     <para>If an error occurred the value errno is propagated to the return code.
 227     If EXIT_STATUS is supplied by the running image that is returned.
 228     Otherwise EXIT_SUCCESS is returned.</para>
 229   </refsect1>
 230
 231   <refsect1>
 232     <title>See Also</title>
 233     <para>
 234       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 235       <citerefentry><refentrytitle>mkosi</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 236     </para>
 237   </refsect1>
 238 </refentry>