system/systemd
system/systemd
1
0
Fork 0
mirror of https://github.com/systemd/systemd synced 2024-07-21 18:24:38 +00:00
Code Issues Actions 5 Packages Projects Releases Wiki Activity

Merge pull request #32251 from CodethinkLabs/vmspawn/docs_improvements

Browse source 
vmspawn docs improvements
This commit is contained in:
Luca Boccassi 2024-04-19 20:33:05 +02:00 committed by GitHub
parent ef40ad963a 2068ef6804
commit f5054c2e37
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 85 additions and 33 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
man/custom-entities.ent.in
View file

@ -19,3 +19,4 @@
<!ENTITY DEFAULT_USER_TIMEOUT "{{DEFAULT_USER_TIMEOUT_SEC}} s">
<!ENTITY DEFAULT_KEYMAP "{{SYSTEMD_DEFAULT_KEYMAP}}">
<!ENTITY fedora_latest_version "40">
<!ENTITY fedora_cloud_release "1.10">

117
man/systemd-vmspawn.xml
View file

@ -1,6 +1,9 @@
<?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">
"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"
@ -77,10 +80,12 @@
<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.</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.</para>
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>
@ -106,7 +111,7 @@
<varlistentry>
<term><option>--cpus=<replaceable>CPUS</replaceable></option></term>
<listitem><para>Configures the number of CPUs to start the virtual machine with.
<listitem><para>The number of CPUs to start the virtual machine with.
Defaults to 1.</para>
<xi:include href="version-info.xml" xpointer="v255"/>
@ -116,7 +121,7 @@
<varlistentry>
<term><option>--ram=<replaceable>BYTES</replaceable></option></term>
<listitem><para>Configures the amount of memory to start the virtual machine with.
<listitem><para>The amount of memory to start the virtual machine with.
Defaults to 2G.</para>
<xi:include href="version-info.xml" xpointer="v255"/>
@ -126,7 +131,7 @@
<varlistentry>
<term><option>--kvm=<replaceable>BOOL</replaceable></option></term>
<listitem><para>Configures whether to use KVM. If the option is not specified KVM support will be
<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>
@ -135,25 +140,20 @@
<varlistentry>
<term><option>--vsock=<replaceable>BOOL</replaceable></option></term>
<listitem>
<para>Configure whether to use VSOCK networking.</para>
<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>
<para>If the option is not specified VSOCK support will be detected automatically. If yes is
specified VSOCK is always used, and vice versa if no is set VSOCK are never used.</para>
<xi:include href="version-info.xml" xpointer="v255"/>
</listitem>
<xi:include href="version-info.xml" xpointer="v255"/></listitem>
</varlistentry>
<varlistentry>
<term><option>--vsock-cid=<replaceable>CID</replaceable></option></term>
<listitem>
<para>Configure vmspawn to use a specific CID for the guest.</para>
<para>If the option is not specified or an empty argument is supplied the guest will be assigned a random CID.</para>
<para>Valid CIDs are in the range <constant>3</constant> to <constant>4294967294</constant> (<constant>0xFFFF_FFFE</constant>).
CIDs outside of this range are reserved.</para>
<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>
@ -163,12 +163,10 @@
<term><option>--tpm=<replaceable>BOOL</replaceable></option></term>
<listitem>
<para>Configure whether to use VM with a virtual TPM or not.</para>
<para>If the option is not specified vmspawn will detect the presence of <citerefentry project='debian'>
<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 vice versa if no is set <citerefentry project='debian'><refentrytitle>swtpm</refentrytitle>
is always used, and if no is set <citerefentry project='debian'><refentrytitle>swtpm</refentrytitle>
<manvolnum>8</manvolnum></citerefentry> is never used.</para>
<para>Note: the virtual TPM used may change in future.</para>
@ -181,9 +179,12 @@
<term><option>--linux=<replaceable>PATH</replaceable></option></term>
<listitem>
<para>Set the linux kernel image to use for direct kernel boot.</para>
<para>If no kernel was installed into the image then the image will fail to boot.</para>
<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">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>
@ -193,13 +194,13 @@
<term><option>--initrd=<replaceable>PATH</replaceable></option></term>
<listitem>
<para>Set the initrd to use for direct kernel boot.</para>
<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">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>If the linux kernel supplied is a UKI then this argument is not required.</para>
<para>If the option is specified multiple times vmspawn will merge the initrds together.</para>
<para>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>
@ -330,7 +331,9 @@
<term><option>--private-users=<replaceable>UID_SHIFT[:UID_RANGE]</replaceable></option></term>
<listitem><para>Controls user namespacing under <option>--directory=</option>.
If enabled, <command>virtiofsd</command> is instructed to map user and group ids (UIDs and GIDs).
If enabled,
<citerefentry><refentrytitle>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>
@ -417,7 +420,7 @@
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 <command>sshd</command></para>.
may also be useful if the VM has a particularly old version of <command>sshd</command>.</para>
<xi:include href="version-info.xml" xpointer="v256"/>
</listitem>
@ -507,6 +510,53 @@ $ 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 39 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 isn't 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>
@ -524,6 +574,7 @@ $ systemd-vmspawn --image=image.raw
<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">Boot Loader Specification</ulink></member>
</simplelist></para>
</refsect1>
</refentry>