SymbX/systemd
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

vmspawn: rearrange --help and man page a bit (#42200)

Browse Source 
This does not change man page or --help contents at all, but it does
introduce new sections, and moves some knobs between sections. It also
reorders things in the man page so that man page and --help show items
in the same order again.
This commit is contained in:
Yu Watanabe
2026-05-21 09:07:34 +09:00
committed by GitHub
parent 20ab4a8b15 95fe2d07ed
commit 6cb65dacd1
2 changed files with 157 additions and 130 deletions
Download Patch File Download Diff File Expand all files Collapse all files
man/systemd-vmspawn.xml
+107 -88
View File
@@ -104,6 +104,18 @@
</listitem>
</varlistentry>
<varlistentry>
<term><option>-x</option></term>
<term><option>--ephemeral</option></term>
<listitem><para>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 <option>--image=</option> currently.
Note that <option>--ephemeral</option> will not work with <option>--extra-drive=</option>.</para>
<xi:include href="version-info.xml" xpointer="v260"/></listitem>
</varlistentry>
<varlistentry>
<term><option>-i</option></term>
<term><option>--image=</option></term>
@@ -139,15 +151,25 @@
</varlistentry>
<varlistentry>
<term><option>-x</option></term>
<term><option>--ephemeral</option></term>
<term><option>--discard-disk=<replaceable>BOOL</replaceable></option></term>
<listitem><para>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 <option>--image=</option> currently.
<listitem><para>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.</para>
Note that <option>--ephemeral</option> will not work with <option>--extra-drive=</option>.</para>
<xi:include href="version-info.xml" xpointer="v256"/></listitem>
</varlistentry>
<xi:include href="version-info.xml" xpointer="v260"/></listitem>
<varlistentry>
<term><option>--grow-image=<replaceable>BYTES</replaceable></option></term>
<term><option>-G <replaceable>BYTES</replaceable></option></term>
<listitem><para>Grows the image file specified by <option>--image=</option> 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.</para>
<xi:include href="version-info.xml" xpointer="v258"/></listitem>
</varlistentry>
</variablelist>
</refsect2>
@@ -270,59 +292,13 @@
</varlistentry>
<varlistentry>
<term><option>--linux=<replaceable>PATH</replaceable></option></term>
<term><option>--secure-boot=<replaceable>BOOL</replaceable></option></term>
<listitem>
<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">UAPI.1 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>
</varlistentry>
<varlistentry>
<term><option>--initrd=<replaceable>PATH</replaceable></option></term>
<listitem>
<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">UAPI.1 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><option>--initrd=</option> can be specified multiple times and vmspawn will merge them together.</para>
<xi:include href="version-info.xml" xpointer="v256"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-n</option></term>
<term><option>--network-tap</option></term>
<listitem>
<para>Create a TAP device to network with the virtual machine.</para>
<para>Note: root privileges are required to use TAP networking.
Additionally,
<citerefentry><refentrytitle>systemd-networkd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
must be running and correctly set up on the host to provision the host interface. The relevant
<literal>.network</literal> file can be found at
<filename>/usr/lib/systemd/network/80-vm-vt.network</filename>.
</para>
<xi:include href="version-info.xml" xpointer="v255"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--network-user-mode</option></term>
<listitem><para>Use user mode networking.</para>
<listitem><para>Configure whether to search for firmware which supports Secure Boot. Takes a
boolean or <literal>auto</literal>. Setting this to yes is equivalent to
<option>--firmware-features=secure-boot</option> and setting this to no is equivalent to
<option>--firmware-features=~secure-boot</option>. Setting this to <literal>auto</literal>
removes <literal>secure-boot</literal> from both the included and excluded feature lists.</para>
<xi:include href="version-info.xml" xpointer="v255"/></listitem>
</varlistentry>
@@ -363,28 +339,6 @@
<xi:include href="version-info.xml" xpointer="v261"/></listitem>
</varlistentry>
<varlistentry>
<term><option>--discard-disk=<replaceable>BOOL</replaceable></option></term>
<listitem><para>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.</para>
<xi:include href="version-info.xml" xpointer="v256"/></listitem>
</varlistentry>
<varlistentry>
<term><option>--secure-boot=<replaceable>BOOL</replaceable></option></term>
<listitem><para>Configure whether to search for firmware which supports Secure Boot. Takes a
boolean or <literal>auto</literal>. Setting this to yes is equivalent to
<option>--firmware-features=secure-boot</option> and setting this to no is equivalent to
<option>--firmware-features=~secure-boot</option>. Setting this to <literal>auto</literal>
removes <literal>secure-boot</literal> from both the included and excluded feature lists.</para>
<xi:include href="version-info.xml" xpointer="v255"/></listitem>
</varlistentry>
<varlistentry>
<term><option>--coco=</option></term>
@@ -408,17 +362,75 @@
<xi:include href="version-info.xml" xpointer="v261"/></listitem>
</varlistentry>
</variablelist>
</refsect2>
<refsect2>
<title>Networking Options</title>
<variablelist>
<varlistentry>
<term><option>-n</option></term>
<term><option>--network-tap</option></term>
<listitem>
<para>Create a TAP device to network with the virtual machine.</para>
<para>Note: root privileges are required to use TAP networking.
Additionally,
<citerefentry><refentrytitle>systemd-networkd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
must be running and correctly set up on the host to provision the host interface. The relevant
<literal>.network</literal> file can be found at
<filename>/usr/lib/systemd/network/80-vm-vt.network</filename>.
</para>
<xi:include href="version-info.xml" xpointer="v255"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--grow-image=<replaceable>BYTES</replaceable></option></term>
<term><option>-G <replaceable>BYTES</replaceable></option></term>
<term><option>--network-user-mode</option></term>
<listitem><para>Grows the image file specified by <option>--image=</option> 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.</para>
<listitem><para>Use user mode networking.</para>
<xi:include href="version-info.xml" xpointer="v258"/></listitem>
<xi:include href="version-info.xml" xpointer="v255"/></listitem>
</varlistentry>
</variablelist>
</refsect2>
<refsect2>
<title>Execution Options</title>
<variablelist>
<varlistentry>
<term><option>--linux=<replaceable>PATH</replaceable></option></term>
<listitem>
<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">UAPI.1 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>
</varlistentry>
<varlistentry>
<term><option>--initrd=<replaceable>PATH</replaceable></option></term>
<listitem>
<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">UAPI.1 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><option>--initrd=</option> can be specified multiple times and vmspawn will merge them together.</para>
<xi:include href="version-info.xml" xpointer="v256"/>
</listitem>
</varlistentry>
<varlistentry>
@@ -708,7 +720,7 @@
</refsect2>
<refsect2>
<title>Integration Options</title>
<title>Logging Options</title>
<variablelist>
<varlistentry>
@@ -740,6 +752,13 @@
<xi:include href="version-info.xml" xpointer="v261"/></listitem>
</varlistentry>
</variablelist>
</refsect2>
<refsect2>
<title>SSH Options</title>
<variablelist>
<varlistentry>
<term><option>--pass-ssh-key=<replaceable>BOOL</replaceable></option></term>
src/vmspawn/vmspawn.c
+50 -42
View File
@@ -232,12 +232,14 @@ static int help(void) {
NULL,
"Image",
"Host Configuration",
"Networking",
"Execution",
"System Identity",
"Properties",
"User Namespacing",
"Mounts",
"Integration",
"Logging",
"SSH",
"Input/Output",
"Credentials",
};
@@ -251,8 +253,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], tables[12]);
help_cmdline("[OPTIONS...] [ARGUMENTS...]");
help_abstract("Spawn a command or OS in a virtual machine.");
@@ -394,6 +398,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"): {}
@@ -502,32 +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('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;
@@ -646,24 +641,35 @@ 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);
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_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('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);
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 log_error_errno(r, "Failed to parse --grow-image= parameter: %s", opts.arg);
break;
return r;
OPTION_GROUP("Execution"): {}
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)) {
@@ -839,7 +845,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 +877,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)