From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from list by lists.gnu.org with archive (Exim 4.90_1) id 1qR0Ci-000815-Ug for mharc-grub-devel@gnu.org; Tue, 01 Aug 2023 20:59:08 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1qR0Ce-00080r-A5 for grub-devel@gnu.org; Tue, 01 Aug 2023 20:59:04 -0400 Received: from mail-oa1-x34.google.com ([2001:4860:4864:20::34]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1qR0Cb-0004TY-VF for grub-devel@gnu.org; Tue, 01 Aug 2023 20:59:04 -0400 Received: by mail-oa1-x34.google.com with SMTP id 586e51a60fabf-1bb5c259b44so4600388fac.1 for ; Tue, 01 Aug 2023 17:59:00 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=efficientek-com.20221208.gappssmtp.com; s=20221208; t=1690937939; x=1691542739; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:from:to:cc:subject:date:message-id:reply-to; bh=45tDQj2Z7rMYkGg4N18YmjV/N7ZRhTDKKJIQ38kX4wQ=; b=kiaX67iIOqJaDHddhPGIqDKOGXlT6FYzj3J92t2ZIUZJBT5TgOKbVjvZgygp4aMMJP Vh4kU7fGViSlfqIZgCEa9cxFspdU5gcH0qz6Y/xbzHO3OR0nSi7Ts/RGJlTu51SES4lM x83+WVy4S9fFhyDihBSBGe6UJBZSTXwgZTW6JTu93fc0nkWEJ1zGoGA/NSG9PenQJV6M lkJOBc/ZJWT3iFZIpdgdVA1WFUpgYhJK1BiJEgan1CpRQ5MpNVyIdfkGp0EyfCACnKIV ZEP4/VspEu6jCIiApZwahTdHaqojWCC3lU9O9cxnA7sT/YgQPQKZhJL4eqSeD8Vykkd+ UNJA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1690937939; x=1691542739; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=45tDQj2Z7rMYkGg4N18YmjV/N7ZRhTDKKJIQ38kX4wQ=; b=CjvwQNKeCjIAyDf4U+dDjA3uuSkz/ACCr9t+vHqp58h5wDs1MmNdQLFeqN6+JT9PbF FVlKF2gODBDXWtYVh6nyW3dKCBmw2VpQ6Sm7OoSOv/+ftkC3/63A6lFrF1+ycV0flrOI 0/8wd/h49ekIhYO+44qUyffDE3k4jsLQzdMlpTZMfQP0ao4nb3fwj87wz/AtCnv7HzGN +KVFehWhodCEeIQxyVyO6Mpwif10SFHFjCFFCHRhS9A/hRiqnJcM7Iti6OSCaemhMn4M oZkeH68nLHATIvtTHNXVTFQfUcvFlJ7M0L93MZJL8kqJmjc+y6Dms8A3BdlzHal0LC5/ SCkg== X-Gm-Message-State: ABy/qLbvAu43jkfcnBfnZXrHmyY/rHQxm4WdwhwrUSSTWXv+VJcR1uqW V7C2mZN1GLzL5WD4h5kAjP3Arp+8B3fycqCXJ88= X-Google-Smtp-Source: APBJJlGwcG450XAaebfeT6aIMbVSITE5pAErdp36kKYl1D75QSP/9YR3r+TmZYdy6zV1kMDRWMk9eQ== X-Received: by 2002:a05:6870:fb8f:b0:1b3:f1f7:999e with SMTP id kv15-20020a056870fb8f00b001b3f1f7999emr15884725oab.45.1690937939237; Tue, 01 Aug 2023 17:58:59 -0700 (PDT) Received: from localhost.localdomain ([37.218.244.249]) by smtp.gmail.com with ESMTPSA id g1-20020a056870340100b001bec2a8f4e3sm3481436oah.14.2023.08.01.17.58.56 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 01 Aug 2023 17:58:58 -0700 (PDT) From: Glenn Washburn To: grub-devel@gnu.org, Daniel Kiper Cc: Oskari Pirhonen , Paul Menzel , Glenn Washburn Subject: [PATCH v3] docs: Improve initrd documentation Date: Tue, 1 Aug 2023 19:58:51 -0500 Message-Id: <20230802005851.2256674-1-development@efficientek.com> X-Mailer: git-send-email 2.34.1 MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Received-SPF: pass client-ip=2001:4860:4864:20::34; envelope-from=development@efficientek.com; helo=mail-oa1-x34.google.com X-Spam_score_int: -18 X-Spam_score: -1.9 X-Spam_bar: - X-Spam_report: (-1.9 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: grub-devel@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: The development of GNU GRUB List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 02 Aug 2023 00:59:05 -0000 A list of improvements: * 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 newer. * Add sentence with URL to initrd documentation Linux kernel. * 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. Signed-off-by: Glenn Washburn Reviewed-by: Oskari Pirhonen Reviewed-by: Paul Menzel --- Range-diff against v2: 1: 28cda0c394d6 ! 1: d6ca60159b40 docs: Improve initrd documentation @@ Metadata ## Commit message ## 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. + A list of improvements: + * 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 newer. + * Add sentence with URL to initrd documentation Linux kernel. + * 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. - Update initrd16 to refer to the initrd section and make note that initrd16 - is only on the pc platform. + Signed-off-by: Glenn Washburn + Reviewed-by: Oskari Pirhonen + Reviewed-by: Paul Menzel ## docs/grub.texi ## @@ docs/grub.texi: load a defective boot loader, such as SCO UnixWare 7.1. @@ docs/grub.texi: load a defective boot loader, such as SCO UnixWare 7.1. +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. ++documentation}. + +A new-style initrd (for kernels newer than 2.6) containing one file +with leading path components can also be generated at run time. This @@ docs/grub.texi: load a defective boot loader, such as SCO UnixWare 7.1. +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 ++Keep in mind that paths that come later will take precedence. 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. docs/grub.texi | 48 +++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 41 insertions(+), 7 deletions(-) diff --git a/docs/grub.texi b/docs/grub.texi index 730e8c8d75a4..1d2f0a3d04fe 100644 --- a/docs/grub.texi +++ b/docs/grub.texi @@ -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}. + +A new-style initrd (for kernels newer 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 come later will take precedence. 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 @@ -4087,12 +4120,13 @@ also @ref{GNU/Linux}. @subsection initrd16 @deffn Command initrd16 file [file @dots{}] -Load, in order, all initial ramdisks for a Linux kernel image to be booted in +Load, in order, all initrds 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} +command (@pxref{initrd}) for more details on arguments. -This command is only available on x86 systems. +This command is only available on the pc platform for x86 systems. @end deffn -- 2.34.1