Skip to contentSkip to conversation

docs: Improve initrd documentation

PATCH Superseded Glenn Washburn 4 participants 5 messages Jun 28, 2023 – Jul 29, 2023

v1 of 3 Superseded Latest is v3 →

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 docs: Improve initrd documentation

Remove reference to "initial ramdisk" and replace with "initrd". This then covers the case of ramdisk and ramfs, which is the usual method with kernels 2.6 and greater. Add sentence with URL to initrd documentation Linux kernel. Also, add a section documenting how to have the initrd command generate a new-style initrd via a specially crafted argument and include an example.

Update initrd16 to refer to the initrd section and make note that initrd16 is only on the pc platform.

---
 docs/grub.texi | 46 ++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 40 insertions(+), 6 deletions(-)
docs/grub.texi +40 -6
index b39b72230c6f..bea86669191b 100644
@@ -4076,10 +4076,43 @@ load a defective boot loader, such as SCO UnixWare 7.1.
 @subsection initrd
 
 @deffn Command initrd file [file @dots{}]
-Load, in order, all initial ramdisks for a Linux kernel image, and set
-the appropriate parameters in the Linux setup area in memory.  This may only
-be used after the @command{linux} command (@pxref{linux}) has been run.  See
-also @ref{GNU/Linux}.
+Load, in order, all initrds for a Linux kernel image, and set the
+appropriate parameters in the Linux setup area in memory.  This may only
+be used after the @command{linux} command (@pxref{linux}) has been run.
+See @ref{GNU/Linux} for more info on booting GNU/Linux.  For more
+information on initrds see the GNU/Linux kernel
+@uref{https://docs.kernel.org/filesystems/ramfs-rootfs-initramfs.html,
+documentation} on them.
+
+A new-style initrd (for kernels greater than 2.6) containing one file
+with leading path components can also be generated at run time. This
+can be done by prefixing an argument with @code{newc:} followed by the
+path of the file in the new initrd, a @code{:}, and then the GRUB file
+path to the file data to be be included.
+
+For example:
+@example
+initrd newc:/etc/ssh/config:(hd0,2)/home/user/.ssh/config \
+       newc:/etc/ssh/ssh_host_rsa_key:/etc/ssh/ssh_host_rsa_key \
+       /boot/initrd.gz \
+       newc:/init:/home/user/init.fixed
+@end example
+
+This command will generate two new-style initrds on the fly. The first
+contains the path @samp{/etc/ssh/config} with the contents of
+@samp{(hd0,2)/home/user/.ssh/config} and the path
+@samp{/etc/ssh/ssh_host_rsa_key} with the contents of
+@samp{/etc/ssh/ssh_host_rsa_key} on the @var{root} device. Parent directory
+paths will automatically be generated as needed. This first generated initrd
+will then have @samp{/boot/initrd.gz} concatenated after it. Next, another
+new-style archive will be generated with the contents of @samp{/home/user/init.fixed}
+in the path @samp{/init} and appended to the previous concatenation. Finally,
+the result will be sent to the kernel when booted.
+
+Keep in mind that paths that comes later will take precendence. So in the
+example above, the generated path @samp{/init} will overwrite any @samp{/init}
+in @samp{/boot/initrd.gz}. This can be useful when changing the main initrd
+is undesirable or difficult.
 @end deffn
 
 
@@ -4090,9 +4123,10 @@ also @ref{GNU/Linux}.
 Load, in order, all initial ramdisks for a Linux kernel image to be booted in
 16-bit mode, and set the appropriate parameters in the Linux setup area in
 memory.  This may only be used after the @command{linux16} command
-(@pxref{linux16}) has been run.  See also @ref{GNU/Linux}.
+(@pxref{linux16}) has been run.  See also @ref{GNU/Linux} and the @command{initrd}
+(@pxref{initrd}) for more details.
 
-This command is only available on x86 systems.
+This command is only available on the pc platform for x86 systems.
 @end deffn
 
 
Signature · 1 line
2.34.1
Reviewed-by on v1 1/1
#1 lore raw
Quoted 10 lines · Glenn Washburn

Remove reference to "initial ramdisk" and replace with "initrd". This then covers the case of ramdisk and ramfs, which is the usual method with kernels 2.6 and greater. Add sentence with URL to initrd documentation Linux kernel. Also, add a section documenting how to have the initrd command generate a new-style initrd via a specially crafted argument and include an example.

Update initrd16 to refer to the initrd section and make note that initrd16 is only on the pc platform.

Daniel

#2 lore raw
In reply to Glenn Washburn
Quoted 25 lines · Glenn Washburn

Remove reference to "initial ramdisk" and replace with "initrd". This then covers the case of ramdisk and ramfs, which is the usual method with kernels 2.6 and greater. Add sentence with URL to initrd documentation Linux kernel. Also, add a section documenting how to have the initrd command generate a new-style initrd via a specially crafted argument and include an example.

Update initrd16 to refer to the initrd section and make note that initrd16 is only on the pc platform.

---
 docs/grub.texi | 46 ++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 40 insertions(+), 6 deletions(-)
docs/grub.texi +0 -3
index b39b72230c6f..bea86669191b 100644
@@ -4076,10 +4076,43 @@ load a defective boot loader, such as SCO UnixWare 7.1.
 @subsection initrd
 
 @deffn Command initrd file [file @dots{}]
-Load, in order, all initial ramdisks for a Linux kernel image, and set
-the appropriate parameters in the Linux setup area in memory.  This may only
-be used after the @command{linux} command (@pxref{linux}) has been run.  See

docs/grub.texi load a defective boot loader, such as SCO UnixWare 7.1. · line 4087

Quoted 10 lines
docs/grub.texi +9 -1
-also @ref{GNU/Linux}.
+Load, in order, all initrds for a Linux kernel image, and set the
+appropriate parameters in the Linux setup area in memory.  This may only
+be used after the @command{linux} command (@pxref{linux}) has been run.
+See @ref{GNU/Linux} for more info on booting GNU/Linux.  For more
+information on initrds see the GNU/Linux kernel
+@uref{https://docs.kernel.org/filesystems/ramfs-rootfs-initramfs.html,
+documentation} on them.
+
+A new-style initrd (for kernels greater than 2.6) containing one file

I'd personally say "newer than 2.6", but "greater than 2.6" is still easy enough to understand.

Quoted 32 lines
docs/grub.texi +28 -0
+with leading path components can also be generated at run time. This
+can be done by prefixing an argument with @code{newc:} followed by the
+path of the file in the new initrd, a @code{:}, and then the GRUB file
+path to the file data to be be included.
+
+For example:
+@example
+initrd newc:/etc/ssh/config:(hd0,2)/home/user/.ssh/config \
+       newc:/etc/ssh/ssh_host_rsa_key:/etc/ssh/ssh_host_rsa_key \
+       /boot/initrd.gz \
+       newc:/init:/home/user/init.fixed
+@end example
+
+This command will generate two new-style initrds on the fly. The first
+contains the path @samp{/etc/ssh/config} with the contents of
+@samp{(hd0,2)/home/user/.ssh/config} and the path
+@samp{/etc/ssh/ssh_host_rsa_key} with the contents of
+@samp{/etc/ssh/ssh_host_rsa_key} on the @var{root} device. Parent directory
+paths will automatically be generated as needed. This first generated initrd
+will then have @samp{/boot/initrd.gz} concatenated after it. Next, another
+new-style archive will be generated with the contents of @samp{/home/user/init.fixed}
+in the path @samp{/init} and appended to the previous concatenation. Finally,
+the result will be sent to the kernel when booted.
+
+Keep in mind that paths that comes later will take precendence. So in the
+example above, the generated path @samp{/init} will overwrite any @samp{/init}
+in @samp{/boot/initrd.gz}. This can be useful when changing the main initrd
+is undesirable or difficult.
 @end deffn
 
 

docs/grub.texi also @ref{GNU/Linux}. · line 4123

Quoted 1 line
docs/grub.texi +0 -0
@@ -4090,9 +4123,10 @@ also @ref{GNU/Linux}.
 Load, in order, all initial ramdisks for a Linux kernel image to be booted in

Your commit message mentions replacing references to "initial ramdisk" with "initrd" which you did above. Did you mean to do that here too?

docs/grub.texi also @ref{GNU/Linux}. · line 4128

Quoted 6 lines
docs/grub.texi +2 -1
 16-bit mode, and set the appropriate parameters in the Linux setup area in
 memory.  This may only be used after the @command{linux16} command
-(@pxref{linux16}) has been run.  See also @ref{GNU/Linux}.
+(@pxref{linux16}) has been run.  See also @ref{GNU/Linux} and the @command{initrd}
+(@pxref{initrd}) for more details.
 

I would add "command" after the "@command{initrd}" bit.

This is cool stuff. I was not aware of this feature in GRUB.

- Oskari

Quoted 8 lines
docs/grub.texi +1 -1
-This command is only available on x86 systems.
+This command is only available on the pc platform for x86 systems.
 @end deffn
 
 
Signature · 1 line
2.34.1
Reviewed-by on v1 1/1
#3 lore raw
In reply to Glenn Washburn

Dear Glenn,

Thank you for all your work on GRUB.

Am 28.06.23 um 12:12 schrieb Glenn Washburn:

Quoted 5 lines

Remove reference to "initial ramdisk" and replace with "initrd". This then covers the case of ramdisk and ramfs, which is the usual method with kernels 2.6 and greater. Add sentence with URL to initrd documentation Linux kernel. Also, add a section documenting how to have the initrd command generate a new-style initrd via a specially crafted argument and include an example.

(I’d format this as a list.)

Quoted 18 lines

Update initrd16 to refer to the initrd section and make note that initrd16 is only on the pc platform.

---
  docs/grub.texi | 46 ++++++++++++++++++++++++++++++++++++++++------
  1 file changed, 40 insertions(+), 6 deletions(-)
docs/grub.texi +0 -1
index b39b72230c6f..bea86669191b 100644
@@ -4076,10 +4076,43 @@ load a defective boot loader, such as SCO UnixWare 7.1.
  @subsection initrd
 
  @deffn Command initrd file [file @dots{}]
-Load, in order, all initial ramdisks for a Linux kernel image, and set

docs/grub.texi load a defective boot loader, such as SCO UnixWare 7.1. · line 4085

Quoted 10 lines
docs/grub.texi +7 -3
-the appropriate parameters in the Linux setup area in memory.  This may only
-be used after the @command{linux} command (@pxref{linux}) has been run.  See
-also @ref{GNU/Linux}.
+Load, in order, all initrds for a Linux kernel image, and set the
+appropriate parameters in the Linux setup area in memory.  This may only
+be used after the @command{linux} command (@pxref{linux}) has been run.
+See @ref{GNU/Linux} for more info on booting GNU/Linux.  For more
+information on initrds see the GNU/Linux kernel
+@uref{https://docs.kernel.org/filesystems/ramfs-rootfs-initramfs.html,
+documentation} on them.

The “on them” at the end sounds like a leftover. But I am no native speaker.

Quoted 17 lines
docs/grub.texi +17 -0
+
+A new-style initrd (for kernels greater than 2.6) containing one file
+with leading path components can also be generated at run time. This
+can be done by prefixing an argument with @code{newc:} followed by the
+path of the file in the new initrd, a @code{:}, and then the GRUB file
+path to the file data to be be included.
+
+For example:
+@example
+initrd newc:/etc/ssh/config:(hd0,2)/home/user/.ssh/config \
+       newc:/etc/ssh/ssh_host_rsa_key:/etc/ssh/ssh_host_rsa_key \
+       /boot/initrd.gz \
+       newc:/init:/home/user/init.fixed
+@end example
+
+This command will generate two new-style initrds on the fly. The first
+contains the path @samp{/etc/ssh/config} with the contents of

docs/grub.texi load a defective boot loader, such as SCO UnixWare 7.1. · line 4112

Quoted 10 lines
docs/grub.texi +10 -0
+@samp{(hd0,2)/home/user/.ssh/config} and the path
+@samp{/etc/ssh/ssh_host_rsa_key} with the contents of
+@samp{/etc/ssh/ssh_host_rsa_key} on the @var{root} device. Parent directory
+paths will automatically be generated as needed. This first generated initrd
+will then have @samp{/boot/initrd.gz} concatenated after it. Next, another
+new-style archive will be generated with the contents of @samp{/home/user/init.fixed}
+in the path @samp{/init} and appended to the previous concatenation. Finally,
+the result will be sent to the kernel when booted.
+
+Keep in mind that paths that comes later will take precendence. So in the

1. come later
2. precedence

docs/grub.texi load a defective boot loader, such as SCO UnixWare 7.1. · line 4116

Quoted 4 lines
docs/grub.texi +3 -0
+example above, the generated path @samp{/init} will overwrite any @samp{/init}
+in @samp{/boot/initrd.gz}. This can be useful when changing the main initrd
+is undesirable or difficult.
  @end deffn

(Today I learned something new. Nice feature.)

docs/grub.texi also @ref{GNU/Linux}. · line 4130

Quoted 13 lines
docs/grub.texi +3 -2
@@ -4090,9 +4123,10 @@ also @ref{GNU/Linux}.
  Load, in order, all initial ramdisks for a Linux kernel image to be booted in
  16-bit mode, and set the appropriate parameters in the Linux setup area in
  memory.  This may only be used after the @command{linux16} command
-(@pxref{linux16}) has been run.  See also @ref{GNU/Linux}.
+(@pxref{linux16}) has been run.  See also @ref{GNU/Linux} and the @command{initrd}
+(@pxref{initrd}) for more details.
 
-This command is only available on x86 systems.
+This command is only available on the pc platform for x86 systems.
  @end deffn

Kind regards,

Paul

#4 lore raw
Quoted 30 lines · Paul Menzel

Dear Glenn,

Thank you for all your work on GRUB.

Am 28.06.23 um 12:12 schrieb Glenn Washburn:

Quoted 5 lines

Remove reference to "initial ramdisk" and replace with "initrd". This then covers the case of ramdisk and ramfs, which is the usual method with kernels 2.6 and greater. Add sentence with URL to initrd documentation Linux kernel. Also, add a section documenting how to have the initrd command generate a new-style initrd via a specially crafted argument and include an example.

(I’d format this as a list.)

Quoted 16 lines

Update initrd16 to refer to the initrd section and make note that initrd16 is only on the pc platform.

---
  docs/grub.texi | 46 ++++++++++++++++++++++++++++++++++++++++------
  1 file changed, 40 insertions(+), 6 deletions(-)
docs/grub.texi +0 -0
index b39b72230c6f..bea86669191b 100644
@@ -4076,10 +4076,43 @@ load a defective boot loader, such as SCO UnixWare 7.1.
  @subsection initrd
 
Quoted 15 lines

docs/grub.texi load a defective boot loader, such as SCO UnixWare 7.1. · line 4085

Quoted 12 lines
docs/grub.texi +7 -4
  @deffn Command initrd file [file @dots{}]
-Load, in order, all initial ramdisks for a Linux kernel image, and set
-the appropriate parameters in the Linux setup area in memory.  This may only
-be used after the @command{linux} command (@pxref{linux}) has been run.  See
-also @ref{GNU/Linux}.
+Load, in order, all initrds for a Linux kernel image, and set the
+appropriate parameters in the Linux setup area in memory.  This may only
+be used after the @command{linux} command (@pxref{linux}) has been run.
+See @ref{GNU/Linux} for more info on booting GNU/Linux.  For more
+information on initrds see the GNU/Linux kernel
+@uref{https://docs.kernel.org/filesystems/ramfs-rootfs-initramfs.html,
+documentation} on them.

The “on them” at the end sounds like a leftover. But I am no native speaker.

The "on them" is fine IMO because it clarifies what part of the documentation is being referred to. In info(1), the sentence gets rendered as:

For more information on initrds see the GNU/Linux kernel documentation ($URL) on them.

But, according to the texinfo docs, for HTML it gets rendered without the inline URL.

It's just a matter of personal preference I guess. I have no strong opinion in either direction.

Quoted 22 lines
Quoted 22 lines
docs/grub.texi +22 -0
+
+A new-style initrd (for kernels greater than 2.6) containing one file
+with leading path components can also be generated at run time. This
+can be done by prefixing an argument with @code{newc:} followed by the
+path of the file in the new initrd, a @code{:}, and then the GRUB file
+path to the file data to be be included.
+
+For example:
+@example
+initrd newc:/etc/ssh/config:(hd0,2)/home/user/.ssh/config \
+       newc:/etc/ssh/ssh_host_rsa_key:/etc/ssh/ssh_host_rsa_key \
+       /boot/initrd.gz \
+       newc:/init:/home/user/init.fixed
+@end example
+
+This command will generate two new-style initrds on the fly. The first
+contains the path @samp{/etc/ssh/config} with the contents of
+@samp{(hd0,2)/home/user/.ssh/config} and the path
+@samp{/etc/ssh/ssh_host_rsa_key} with the contents of
+@samp{/etc/ssh/ssh_host_rsa_key} on the @var{root} device. Parent directory
+paths will automatically be generated as needed. This first generated initrd
+will then have @samp{/boot/initrd.gz} concatenated after it. Next, another
Quoted 9 lines

docs/grub.texi load a defective boot loader, such as SCO UnixWare 7.1. · line 4112

Quoted 5 lines
docs/grub.texi +5 -0
+new-style archive will be generated with the contents of @samp{/home/user/init.fixed}
+in the path @samp{/init} and appended to the previous concatenation. Finally,
+the result will be sent to the kernel when booted.
+
+Keep in mind that paths that comes later will take precendence. So in the

1. come later
2. precedence

Good catch.

Quoted 17 lines

docs/grub.texi load a defective boot loader, such as SCO UnixWare 7.1. · line 4116

Quoted 4 lines
docs/grub.texi +3 -0
+example above, the generated path @samp{/init} will overwrite any @samp{/init}
+in @samp{/boot/initrd.gz}. This can be useful when changing the main initrd
+is undesirable or difficult.
  @end deffn

(Today I learned something new. Nice feature.)

Quoted 10 lines
docs/grub.texi +2 -1
@@ -4090,9 +4123,10 @@ also @ref{GNU/Linux}.
  Load, in order, all initial ramdisks for a Linux kernel image to be booted in
  16-bit mode, and set the appropriate parameters in the Linux setup area in
  memory.  This may only be used after the @command{linux16} command
-(@pxref{linux16}) has been run.  See also @ref{GNU/Linux}.
+(@pxref{linux16}) has been run.  See also @ref{GNU/Linux} and the @command{initrd}
+(@pxref{initrd}) for more details.
 
Quoted 6 lines

docs/grub.texi also @ref{GNU/Linux}. · line 4130

Quoted 3 lines
docs/grub.texi +1 -1
-This command is only available on x86 systems.
+This command is only available on the pc platform for x86 systems.
  @end deffn

A v2 was posted July 3 [1], could you re-comment on there?

- Oskari

[1]: https://lists.gnu.org/archive/html/grub-devel/2023-07/msg00007.html

Quoted 4 lines

Kind regards,

Paul