From 1a0b17df32c7f8de692f7d30a753b7753f8eb0f8 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Wed, 20 May 2026 15:45:57 +0200 Subject: [PATCH 1/5] vmspawn: move image related knobs close to --image= (Also, arrange the order if the image options group in the man page to the same as in the --help text) --- man/systemd-vmspawn.xml | 56 ++++++++++++++++++++--------------------- src/vmspawn/vmspawn.c | 34 ++++++++++++------------- 2 files changed, 45 insertions(+), 45 deletions(-) diff --git a/man/systemd-vmspawn.xml b/man/systemd-vmspawn.xml index 20be0c099b..2c07bad93c 100644 --- a/man/systemd-vmspawn.xml +++ b/man/systemd-vmspawn.xml @@ -104,6 +104,18 @@ + + + + + If specified, the VM is run with a temporary snapshot of its file system that is removed + immediately when the VM terminates. Only works with currently. + + Note that will not work with . + + + + @@ -139,15 +151,25 @@ - - + - If specified, the VM is run with a temporary snapshot of its file system that is removed - immediately when the VM terminates. Only works with currently. + Controls whether qemu processes discard requests from the VM. + This prevents long running VMs from using more disk space than required. + This is enabled by default. - Note that will not work with . + + - + + + + + Grows the image file specified by to the specified size + in bytes if it is smaller. Executes no operation if no image file is used or the image file is + already as large or larger than requested. The specified size accepts the usual K, M, G suffixes + (to the base of 1024). Specified values are rounded up to multiples of 4096. + + @@ -363,16 +385,6 @@ - - - - Controls whether qemu processes discard requests from the VM. - This prevents long running VMs from using more disk space than required. - This is enabled by default. - - - - @@ -409,18 +421,6 @@ - - - - - Grows the image file specified by to the specified size - in bytes if it is smaller. Executes no operation if no image file is used or the image file is - already as large or larger than requested. The specified size accepts the usual K, M, G suffixes - (to the base of 1024). Specified values are rounded up to multiples of 4096. - - - - diff --git a/src/vmspawn/vmspawn.c b/src/vmspawn/vmspawn.c index 6cb77dfadd..4ced5d6896 100644 --- a/src/vmspawn/vmspawn.c +++ b/src/vmspawn/vmspawn.c @@ -394,6 +394,23 @@ static int parse_argv(int argc, char *argv[]) { "Invalid image disk type: %s", opts.arg); break; + OPTION_LONG("discard-disk", "BOOL", "Control processing of discard requests"): + r = parse_boolean_argument("--discard-disk=", opts.arg, &arg_discard_disk); + if (r < 0) + return r; + break; + + OPTION('G', "grow-image", "BYTES", "Grow image file to specified size in bytes"): + if (isempty(opts.arg)) { + arg_grow_image = 0; + break; + } + + r = parse_size(opts.arg, 1024, &arg_grow_image); + if (r < 0) + return log_error_errno(r, "Failed to parse --grow-image= parameter: %s", opts.arg); + break; + OPTION_GROUP("Host Configuration"): {} OPTION_LONG("cpus", "CPUS", "Configure number of CPUs in guest"): {} @@ -646,23 +663,6 @@ static int parse_argv(int argc, char *argv[]) { break; } - OPTION_LONG("discard-disk", "BOOL", "Control processing of discard requests"): - r = parse_boolean_argument("--discard-disk=", opts.arg, &arg_discard_disk); - if (r < 0) - return r; - break; - - OPTION('G', "grow-image", "BYTES", "Grow image file to specified size in bytes"): - if (isempty(opts.arg)) { - arg_grow_image = 0; - break; - } - - r = parse_size(opts.arg, 1024, &arg_grow_image); - if (r < 0) - return log_error_errno(r, "Failed to parse --grow-image= parameter: %s", opts.arg); - break; - OPTION_GROUP("Execution"): {} OPTION('s', "smbios11", "STRING", "Pass an arbitrary SMBIOS Type #11 string to the VM"): From f9a40f7aa310ac974831560d5c8e3e54a2785ed4 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Wed, 20 May 2026 15:48:44 +0200 Subject: [PATCH 2/5] vmspawn: split 'Integration' section into 'Logging' and 'SSH' Each of the two has multiple options, hence let's split them out. --- man/systemd-vmspawn.xml | 9 ++++++++- src/vmspawn/vmspawn.c | 13 +++++++++---- 2 files changed, 17 insertions(+), 5 deletions(-) diff --git a/man/systemd-vmspawn.xml b/man/systemd-vmspawn.xml index 2c07bad93c..f31d1a3df2 100644 --- a/man/systemd-vmspawn.xml +++ b/man/systemd-vmspawn.xml @@ -708,7 +708,7 @@ - Integration Options + Logging Options @@ -740,6 +740,13 @@ + + + + + SSH Options + + diff --git a/src/vmspawn/vmspawn.c b/src/vmspawn/vmspawn.c index 4ced5d6896..0c3c6a8109 100644 --- a/src/vmspawn/vmspawn.c +++ b/src/vmspawn/vmspawn.c @@ -237,7 +237,8 @@ static int help(void) { "Properties", "User Namespacing", "Mounts", - "Integration", + "Logging", + "SSH", "Input/Output", "Credentials", }; @@ -251,8 +252,10 @@ static int help(void) { return r; } - (void) table_sync_column_widths(0, tables[0], tables[1], tables[2], tables[3], tables[4], - tables[5], tables[6], tables[7], tables[8], tables[9], tables[10]); + (void) table_sync_column_widths( + 0, tables[0], tables[1], tables[2], tables[3], tables[4], + tables[5], tables[6], tables[7], tables[8], tables[9], tables[10], + tables[11]); help_cmdline("[OPTIONS...] [ARGUMENTS...]"); help_abstract("Spawn a command or OS in a virtual machine."); @@ -839,7 +842,7 @@ static int parse_argv(int argc, char *argv[]) { return log_oom(); break; - OPTION_GROUP("Integration"): {} + OPTION_GROUP("Logging"): {} OPTION_LONG("forward-journal", "FILE|DIR", "Forward the VM's journal to the host"): r = parse_path_argument(opts.arg, /* suppress_root= */ false, &arg_forward_journal); @@ -871,6 +874,8 @@ static int parse_argv(int argc, char *argv[]) { return log_error_errno(r, "Failed to parse --forward-journal-max-files= value: %s", opts.arg); break; + OPTION_GROUP("SSH"): {} + OPTION_LONG("pass-ssh-key", "BOOL", "Create an SSH key to access the VM"): r = parse_boolean_argument("--pass-ssh-key=", opts.arg, &arg_pass_ssh_key); if (r < 0) From 183ec272eff1b86aa76948f83dacc8e0cd32386b Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Wed, 20 May 2026 15:50:32 +0200 Subject: [PATCH 3/5] vmspawn: split out networking related options into its own "Networking" section in --help --- man/systemd-vmspawn.xml | 60 ++++++++++++++++++++++------------------- src/vmspawn/vmspawn.c | 21 ++++++++------- 2 files changed, 45 insertions(+), 36 deletions(-) diff --git a/man/systemd-vmspawn.xml b/man/systemd-vmspawn.xml index f31d1a3df2..c70b76c498 100644 --- a/man/systemd-vmspawn.xml +++ b/man/systemd-vmspawn.xml @@ -322,33 +322,6 @@ - - - - - - Create a TAP device to network with the virtual machine. - - Note: root privileges are required to use TAP networking. - Additionally, - systemd-networkd8 - must be running and correctly set up on the host to provision the host interface. The relevant - .network file can be found at - /usr/lib/systemd/network/80-vm-vt.network. - - - - - - - - - - Use user mode networking. - - - - @@ -454,6 +427,39 @@ + + Networking Options + + + + + + + + Create a TAP device to network with the virtual machine. + + Note: root privileges are required to use TAP networking. + Additionally, + systemd-networkd8 + must be running and correctly set up on the host to provision the host interface. The relevant + .network file can be found at + /usr/lib/systemd/network/80-vm-vt.network. + + + + + + + + + + Use user mode networking. + + + + + + System Identity Options diff --git a/src/vmspawn/vmspawn.c b/src/vmspawn/vmspawn.c index 0c3c6a8109..cc26309317 100644 --- a/src/vmspawn/vmspawn.c +++ b/src/vmspawn/vmspawn.c @@ -232,6 +232,7 @@ static int help(void) { NULL, "Image", "Host Configuration", + "Networking", "Execution", "System Identity", "Properties", @@ -255,7 +256,7 @@ static int help(void) { (void) table_sync_column_widths( 0, tables[0], tables[1], tables[2], tables[3], tables[4], tables[5], tables[6], tables[7], tables[8], tables[9], tables[10], - tables[11]); + tables[11], tables[12]); help_cmdline("[OPTIONS...] [ARGUMENTS...]"); help_abstract("Spawn a command or OS in a virtual machine."); @@ -540,14 +541,6 @@ static int parse_argv(int argc, char *argv[]) { break; } - OPTION('n', "network-tap", NULL, "Create a TAP device for networking"): - arg_network_stack = NETWORK_STACK_TAP; - break; - - OPTION_LONG("network-user-mode", NULL, "Use user mode networking"): - arg_network_stack = NETWORK_STACK_USER; - break; - OPTION_LONG("secure-boot", "BOOL|auto", "Enable searching for firmware supporting SecureBoot"): { int b; @@ -666,6 +659,16 @@ static int parse_argv(int argc, char *argv[]) { break; } + OPTION_GROUP("Networking"): {} + + OPTION('n', "network-tap", NULL, "Create a TAP device for networking"): + arg_network_stack = NETWORK_STACK_TAP; + break; + + OPTION_LONG("network-user-mode", NULL, "Use user mode networking"): + arg_network_stack = NETWORK_STACK_USER; + break; + OPTION_GROUP("Execution"): {} OPTION('s', "smbios11", "STRING", "Pass an arbitrary SMBIOS Type #11 string to the VM"): From b12a3658663e7d6642b6c227e41bb6377ec1a498 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Wed, 20 May 2026 15:52:57 +0200 Subject: [PATCH 4/5] vmspawn: move --kernel=/--initrd= under the "Execution" section This has little to do with host configuration (where it was so far), and a lot with what being executed, let's move it over. Note that --help and man page so far differed here quite a bit: the former had the "Execution" section, the latter didn't. This creates it in the man page, to bring the two back in sync. --- man/systemd-vmspawn.xml | 130 +++++++++++++++++++++------------------- src/vmspawn/vmspawn.c | 36 +++++------ 2 files changed, 86 insertions(+), 80 deletions(-) diff --git a/man/systemd-vmspawn.xml b/man/systemd-vmspawn.xml index c70b76c498..74feca4050 100644 --- a/man/systemd-vmspawn.xml +++ b/man/systemd-vmspawn.xml @@ -291,37 +291,6 @@ - - - - - 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 - UAPI.1 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. - - - - - - - - - - Set the initrd to use for direct kernel boot. - If the supplied is a - UAPI.1 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. - - can be specified multiple times and vmspawn will merge them together. - - - - - @@ -393,37 +362,6 @@ - - - - - - Passes the specified string into the VM as an SMBIOS Type #11 vendor string. This - is useful to parameterize the invoked VM in various ways. See - smbios-type-117 - for details. - - - - - - - - Configures support for notifications from the VM's init process to - systemd-vmspawn. If true, systemd-vmspawn will consider the - machine as ready only when it has received a READY=1 message from the init - process in the VM. If false, systemd-vmspawn will consider the machine as ready - immediately after creation. In either case, systemd-vmspawn sends its own - readiness notification to its manager after the spawned VM is ready. For more details about - notifications see - sd_notify3. - - Defaults to true. (Note that this is unlike the option of the same name to - systemd-nspawn1 - that defaults to false.) - - - @@ -460,6 +398,74 @@ + + Execution Options + + + + + + + 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 + UAPI.1 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. + + + + + + + + + + Set the initrd to use for direct kernel boot. + If the supplied is a + UAPI.1 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. + + can be specified multiple times and vmspawn will merge them together. + + + + + + + + + + Passes the specified string into the VM as an SMBIOS Type #11 vendor string. This + is useful to parameterize the invoked VM in various ways. See + smbios-type-117 + for details. + + + + + + + + Configures support for notifications from the VM's init process to + systemd-vmspawn. If true, systemd-vmspawn will consider the + machine as ready only when it has received a READY=1 message from the init + process in the VM. If false, systemd-vmspawn will consider the machine as ready + immediately after creation. In either case, systemd-vmspawn sends its own + readiness notification to its manager after the spawned VM is ready. For more details about + notifications see + sd_notify3. + + Defaults to true. (Note that this is unlike the option of the same name to + systemd-nspawn1 + that defaults to false.) + + + + + + System Identity Options diff --git a/src/vmspawn/vmspawn.c b/src/vmspawn/vmspawn.c index cc26309317..0797676bf9 100644 --- a/src/vmspawn/vmspawn.c +++ b/src/vmspawn/vmspawn.c @@ -523,24 +523,6 @@ static int parse_argv(int argc, char *argv[]) { arg_efi_nvram_state_mode = STATE_PATH; break; - OPTION_LONG("linux", "PATH", "Specify the linux kernel for direct kernel boot"): - r = parse_path_argument(opts.arg, /* suppress_root= */ false, &arg_linux); - if (r < 0) - return r; - break; - - OPTION_LONG("initrd", "PATH", "Specify the initrd for direct kernel boot"): { - _cleanup_free_ char *initrd_path = NULL; - r = parse_path_argument(opts.arg, /* suppress_root= */ false, &initrd_path); - if (r < 0) - return r; - - r = strv_consume(&arg_initrds, TAKE_PTR(initrd_path)); - if (r < 0) - return log_oom(); - break; - } - OPTION_LONG("secure-boot", "BOOL|auto", "Enable searching for firmware supporting SecureBoot"): { int b; @@ -671,6 +653,24 @@ static int parse_argv(int argc, char *argv[]) { OPTION_GROUP("Execution"): {} + OPTION_LONG("linux", "PATH", "Specify the linux kernel for direct kernel boot"): + r = parse_path_argument(opts.arg, /* suppress_root= */ false, &arg_linux); + if (r < 0) + return r; + break; + + OPTION_LONG("initrd", "PATH", "Specify the initrd for direct kernel boot"): { + _cleanup_free_ char *initrd_path = NULL; + r = parse_path_argument(opts.arg, /* suppress_root= */ false, &initrd_path); + if (r < 0) + return r; + + r = strv_consume(&arg_initrds, TAKE_PTR(initrd_path)); + if (r < 0) + return log_oom(); + break; + } + OPTION('s', "smbios11", "STRING", "Pass an arbitrary SMBIOS Type #11 string to the VM"): if (isempty(opts.arg)) { arg_smbios11 = strv_free(arg_smbios11); From 95fe2d07ed9e080e63f7e9d10531ac21429b8315 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Wed, 20 May 2026 16:23:36 +0200 Subject: [PATCH 5/5] man: order --secure-boot= to the same location in man page as in --help for vmspawn --- man/systemd-vmspawn.xml | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/man/systemd-vmspawn.xml b/man/systemd-vmspawn.xml index 74feca4050..3a84196b62 100644 --- a/man/systemd-vmspawn.xml +++ b/man/systemd-vmspawn.xml @@ -291,6 +291,18 @@ + + + + Configure whether to search for firmware which supports Secure Boot. Takes a + boolean or auto. Setting this to yes is equivalent to + and setting this to no is equivalent to + . Setting this to auto + removes secure-boot from both the included and excluded feature lists. + + + + @@ -327,18 +339,6 @@ - - - - Configure whether to search for firmware which supports Secure Boot. Takes a - boolean or auto. Setting this to yes is equivalent to - and setting this to no is equivalent to - . Setting this to auto - removes secure-boot from both the included and excluded feature lists. - - - -