From 0f37ff38a8e4acd5962c2bd313a7e0c0a139d9da Mon Sep 17 00:00:00 2001 From: Sam Leonard Date: Fri, 12 Apr 2024 14:05:43 +0100 Subject: [PATCH 1/9] man: add machinectl import-raw example for vmspawn --- man/custom-entities.ent.in | 1 + man/systemd-vmspawn.xml | 20 +++++++++++++++++++- 2 files changed, 20 insertions(+), 1 deletion(-) 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..f9483f2d0e 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; +]> + + + 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 + + From b8db8e557b8c5e22a2e387bdd2436b15c99f6ab7 Mon Sep 17 00:00:00 2001 From: Sam Leonard Date: Fri, 12 Apr 2024 14:35:26 +0100 Subject: [PATCH 2/9] man: add example --forward-journal= example for vmspawn --- man/systemd-vmspawn.xml | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/man/systemd-vmspawn.xml b/man/systemd-vmspawn.xml index f9483f2d0e..e8d460ef4f 100644 --- a/man/systemd-vmspawn.xml +++ b/man/systemd-vmspawn.xml @@ -525,6 +525,22 @@ $ sha256sum -c Fedora-Cloud-&fedora_latest_version;-&fedora_cloud_release;-x86_6 # 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. + From 1490debd620e254e151761fcc30ffdc9ec63e5fe Mon Sep 17 00:00:00 2001 From: Sam Leonard Date: Fri, 12 Apr 2024 17:03:00 +0100 Subject: [PATCH 3/9] man: add ssh example for vmspawn --- man/systemd-vmspawn.xml | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/man/systemd-vmspawn.xml b/man/systemd-vmspawn.xml index e8d460ef4f..336ebe9f52 100644 --- a/man/systemd-vmspawn.xml +++ b/man/systemd-vmspawn.xml @@ -541,6 +541,22 @@ $ systemd-vmspawn \ 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 + + From e82d12a52f71974dd1b9246e4bf6f34b370d57a4 Mon Sep 17 00:00:00 2001 From: Sam Leonard Date: Fri, 12 Apr 2024 17:04:37 +0100 Subject: [PATCH 4/9] man: fix entry for vmspawn's --ssh-key-type --- man/systemd-vmspawn.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/man/systemd-vmspawn.xml b/man/systemd-vmspawn.xml index 336ebe9f52..59d7db96cf 100644 --- a/man/systemd-vmspawn.xml +++ b/man/systemd-vmspawn.xml @@ -420,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. From 45ec09ba4b577ce8cfd2f488598bd3eb772b004c Mon Sep 17 00:00:00 2001 From: Sam Leonard Date: Fri, 19 Apr 2024 14:51:09 +0100 Subject: [PATCH 5/9] man: clarify behaviour when omitting both -i/-D in vmspawn --- man/systemd-vmspawn.xml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/man/systemd-vmspawn.xml b/man/systemd-vmspawn.xml index 59d7db96cf..58b8268814 100644 --- a/man/systemd-vmspawn.xml +++ b/man/systemd-vmspawn.xml @@ -80,7 +80,8 @@ 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. From 900d283ae045322b7d936cdf954c5d6ec5a9a426 Mon Sep 17 00:00:00 2001 From: Sam Leonard Date: Fri, 19 Apr 2024 14:52:01 +0100 Subject: [PATCH 6/9] man: vmspawn - reference later example to show use of --private-users --- man/systemd-vmspawn.xml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/man/systemd-vmspawn.xml b/man/systemd-vmspawn.xml index 58b8268814..1177ce9143 100644 --- a/man/systemd-vmspawn.xml +++ b/man/systemd-vmspawn.xml @@ -84,7 +84,8 @@ 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. From dae32b1a2acf5a81ff8fdab4a23b7c11ac8d006a Mon Sep 17 00:00:00 2001 From: Sam Leonard Date: Fri, 19 Apr 2024 16:26:06 +0100 Subject: [PATCH 7/9] man: removely overly verbose wording from the vmspawn man page --- man/systemd-vmspawn.xml | 25 +++++++++++-------------- 1 file changed, 11 insertions(+), 14 deletions(-) diff --git a/man/systemd-vmspawn.xml b/man/systemd-vmspawn.xml index 1177ce9143..ae6a38d49e 100644 --- a/man/systemd-vmspawn.xml +++ b/man/systemd-vmspawn.xml @@ -111,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. @@ -121,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. @@ -131,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. @@ -140,13 +140,10 @@ - - 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. - - + @@ -168,12 +165,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. @@ -335,7 +330,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). From 9c50fd64b5155fdf0754f1d54ccae75436fdc938 Mon Sep 17 00:00:00 2001 From: Sam Leonard Date: Fri, 19 Apr 2024 16:30:56 +0100 Subject: [PATCH 8/9] man: vmspawn - clarify behaviour of omitting --vsock-cid= --- man/systemd-vmspawn.xml | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/man/systemd-vmspawn.xml b/man/systemd-vmspawn.xml index ae6a38d49e..4cf82454f8 100644 --- a/man/systemd-vmspawn.xml +++ b/man/systemd-vmspawn.xml @@ -150,12 +150,10 @@ - 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. From 2068ef6804478f4b0b752b85047043098b6cae0f Mon Sep 17 00:00:00 2001 From: Sam Leonard Date: Fri, 19 Apr 2024 16:31:33 +0100 Subject: [PATCH 9/9] man: vmspawn - clarify behaviour of omitting --linux=/--initrd= --- man/systemd-vmspawn.xml | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/man/systemd-vmspawn.xml b/man/systemd-vmspawn.xml index 4cf82454f8..8f196dd352 100644 --- a/man/systemd-vmspawn.xml +++ b/man/systemd-vmspawn.xml @@ -179,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. @@ -191,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. @@ -571,6 +574,7 @@ $ ssh root@vsock/$my_vsock_cid -i /run/user/$UID/systemd/vmspawn/machine-*-syste mkosi1 machinectl1 importctl1 + Boot Loader Specification