diff --git a/man/custom-entities.ent.in b/man/custom-entities.ent.in index c82e2b8d8f..8dfc1eb98c 100644 --- a/man/custom-entities.ent.in +++ b/man/custom-entities.ent.in @@ -19,3 +19,4 @@ + diff --git a/man/systemd-vmspawn.xml b/man/systemd-vmspawn.xml index f9649b2f30..8f196dd352 100644 --- a/man/systemd-vmspawn.xml +++ b/man/systemd-vmspawn.xml @@ -1,6 +1,9 @@ + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ + +%entities; +]> Directory to use as file system root for the virtual machine. - One of either or must be specified. + One of either or must be specified. + If neither are specified is assumed. Note: If mounting a non-root owned directory you may require - to map into the user's subuid namespace. + to map into the user's subuid namespace. An example of how to use /etc/subuid + for this is given later. @@ -106,7 +111,7 @@ - Configures the number of CPUs to start the virtual machine with. + The number of CPUs to start the virtual machine with. Defaults to 1. @@ -116,7 +121,7 @@ - Configures the amount of memory to start the virtual machine with. + The amount of memory to start the virtual machine with. Defaults to 2G. @@ -126,7 +131,7 @@ - Configures whether to use KVM. If the option is not specified KVM support will be + If is not specified KVM support will be detected automatically. If true, KVM is always used, and if false, KVM is never used. @@ -135,25 +140,20 @@ - - Configure whether to use VSOCK networking. + If 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. - 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. - - + - Configure vmspawn to use a specific CID for the guest. - - If the option is not specified or an empty argument is supplied the guest will be assigned a random CID. - - Valid CIDs are in the range 3 to 4294967294 (0xFFFF_FFFE). - CIDs outside of this range are reserved. + Sets the specific CID to use for the guest. + Valid CIDs are in the range 3 to 4294967294 (0xFFFF_FFFE). + 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. @@ -163,12 +163,10 @@ - Configure whether to use VM with a virtual TPM or not. - - If the option is not specified vmspawn will detect the presence of + If is not specified vmspawn will detect the presence of swtpm8 and use it if available. If yes is specified swtpm8 - is always used, and vice versa if no is set swtpm + is always used, and if no is set swtpm 8 is never used. Note: the virtual TPM used may change in future. @@ -181,9 +179,12 @@ - Set the linux kernel image to use for direct kernel boot. - - If no kernel was installed into the image then the image will fail to boot. + Set the linux kernel image to use for direct kernel boot. + If a directory type image is used and was omitted, vmspawn will search for boot loader entries + according to the + Boot Loader Specification 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. @@ -193,13 +194,13 @@ - Set the initrd to use for direct kernel boot. + Set the initrd to use for direct kernel boot. + If the supplied is a + Boot Loader Specification + Type #2 entry, then this argument is not required. + If no initrd was installed into the image then the image will fail to boot. - If the linux kernel supplied is a UKI then this argument is not required. - - If the option is specified multiple times vmspawn will merge the initrds together. - - If no initrd was installed into the image then the image will fail to boot. + can be specified multiple times and vmspawn will merge them together. @@ -330,7 +331,9 @@ Controls user namespacing under . - If enabled, virtiofsd is instructed to map user and group ids (UIDs and GIDs). + If enabled, + virtiofsd1 + 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). @@ -417,7 +420,7 @@ for more information. By default ed25519 keys are generated, however rsa keys - may also be useful if the VM has a particularly old version of sshd. + may also be useful if the VM has a particularly old version of sshd. @@ -507,6 +510,53 @@ $ mkosi -d arch -p systemd -p linux --autologin -o image.raw -f build $ systemd-vmspawn --image=image.raw + + + Import and run a Fedora 39 Cloud image using machinectl + + +$ 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 + + + + + Build and run systemd's system image and forward the VM's journal to a local file + + +$ 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 + + + Note: this example also uses a kernel command line argument to ensure SELinux isn't started in enforcing mode. + + + + SSH into a running VM using <command>systemd-ssh-proxy</command> + + +$ 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 + + @@ -524,6 +574,7 @@ $ systemd-vmspawn --image=image.raw mkosi1 machinectl1 importctl1 + Boot Loader Specification