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