From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp2.migadu.com ([2001:41d0:403:58f0::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms13.migadu.com with LMTPS id iH4kOXi8smayigAAe85BDQ:P1 (envelope-from ) for ; Wed, 07 Aug 2024 00:14:49 +0000 Received: from aspmx1.migadu.com ([2001:41d0:403:58f0::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp2.migadu.com with LMTPS id iH4kOXi8smayigAAe85BDQ (envelope-from ) for ; Wed, 07 Aug 2024 02:14:49 +0200 X-Envelope-To: larch@yhetil.org Authentication-Results: aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=debbugs.gnu.org header.s=debbugs-gnu-org header.b=BFEhbLY3; dkim=fail ("headers rsa verify failed") header.d=lunabee.space header.s=purelymail3 header.b=ol2BUBYZ; dkim=fail ("headers rsa verify failed") header.d=purelymail.com header.s=purelymail3 header.b=bJc5k+5X; dmarc=pass (policy=none) header.from=gnu.org; spf=pass (aspmx1.migadu.com: domain of "guix-patches-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="guix-patches-bounces+larch=yhetil.org@gnu.org" ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1722989688; h=from:from:sender:sender:reply-to:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding:resent-cc: resent-from:resent-sender:resent-message-id:in-reply-to:in-reply-to: references:references:list-id:list-help:list-unsubscribe: list-subscribe:list-post:dkim-signature; bh=pTiVFh7LkZ1e6QZiXQTxzJu7n+GO0SadsqeMz+y0c5o=; b=PDHmRdNMm93rTa4a1cgatL9rVKwSNFeKiirqQ/2rNbGWbR+UHS6wriRjm4D0Ncuxhxi3hT MdEm8k2VjPsnC+fDaRu0/yjx3VXIyoH51IL4bzfT0PJMahRjGiHoPPp8EWkREMWsgzWk1Q UwDhWalGiDAKfOERc+zH1SmCzflFziEAHtq6Loo764ZuK3vzMll+xYqm0XyjDnG10VT4/O ORCtUSgj6HKKbuVbOF8qiGff76UQxOx7jo3xzNYQ2fceh9Ybt/bjaG4o/mOBLMes9UIEDR sTZZNw+okrz+5jUQvf3TAsRObrNezt4XG6YSh+cTF7WTSzIAW8NclgtnOcqXIg== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1722989688; a=rsa-sha256; cv=none; b=irJOJIfL6NHpq6iTtBZHMje+XY1nGJSwxa7iqO5DC8cRvmSrTBKgUOaC0LlCzQNPGC6txi v6akoXw330R+8IyABJ69Hpn3yk9+qM8cbr5hIrVyFpPMPo/sBXXvbntoNcAU4VQ13VgH1G +R/zcR3+WAmlKYTOE9k35IkyrHHTIVph/yPsm/lA8o90EGc1wfAfvBfg4rDdCn70Oltjxf /t6Dn6tVj7D0aFnUtAMj7qxrks02zl6/E51HPp9VZBVw03ruexkU+nCn/a3z8QXTiA3txk 0Ko9sI8sss5pVIbA5Hc0XOaqGTCVt97gsFZxgHNlWbDxUtZ9keXdE2U7ivjZsw== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=debbugs.gnu.org header.s=debbugs-gnu-org header.b=BFEhbLY3; dkim=fail ("headers rsa verify failed") header.d=lunabee.space header.s=purelymail3 header.b=ol2BUBYZ; dkim=fail ("headers rsa verify failed") header.d=purelymail.com header.s=purelymail3 header.b=bJc5k+5X; dmarc=pass (policy=none) header.from=gnu.org; spf=pass (aspmx1.migadu.com: domain of "guix-patches-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="guix-patches-bounces+larch=yhetil.org@gnu.org" Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id 7AF1964EF5 for ; Wed, 07 Aug 2024 02:14:48 +0200 (CEST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1sbUKC-0000Ds-EJ; Tue, 06 Aug 2024 20:14:44 -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 1sbUKB-000085-1n for guix-patches@gnu.org; Tue, 06 Aug 2024 20:14:43 -0400 Received: from debbugs.gnu.org ([2001:470:142:5::43]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1sbUKA-0002dO-NU; Tue, 06 Aug 2024 20:14:42 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=debbugs.gnu.org; s=debbugs-gnu-org; h=MIME-Version:References:In-Reply-To:Date:From:To:Subject; bh=pTiVFh7LkZ1e6QZiXQTxzJu7n+GO0SadsqeMz+y0c5o=; b=BFEhbLY3hQQmD5V4o43gRJ4yyWXEhOyNSFKXA1W83/PhAXdyW0YJ1brDaBFxL8I/aUETf6pMdpCWI1I8SNhejj2EeITvwarrRWFKjZzyMASRy1qxYLkb8wSQ7HCSJhgYEPEAAE3A7d6toEZuliUYpyVuY/0b+sC24tn0GpvPZtT1FTjSEDKJGCzD8svoUnymoSiPMv8GryG/A94b+4HLmXzoJ6TMjyowW5S4uqXzbIIyCAFXfVLROd1dlWBWKAW0TLJVt0Ey23X8qVTyPD/v7MrC++JhS179MvAa1PO8Fqb0PsE6wpvrXwQnGDIxckNQbuRXf3YxpE6rlHpELtSE9A==; Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1sbUKV-000721-Q2; Tue, 06 Aug 2024 20:15:03 -0400 X-Loop: help-debbugs@gnu.org Subject: [bug#72457] [PATCH v5 13/15] doc: Update bootloader documentation. Resent-From: Lilah Tascheter Original-Sender: "Debbugs-submit" Resent-CC: pelzflorian@pelzflorian.de, ludo@gnu.org, matt@excalamus.com, maxim.cournoyer@gmail.com, guix-patches@gnu.org Resent-Date: Wed, 07 Aug 2024 00:15:03 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 72457 X-GNU-PR-Package: guix-patches X-GNU-PR-Keywords: patch To: 72457@debbugs.gnu.org Cc: Lilah Tascheter , Sergey Trofimov , Florian Pelz , Ludovic Court??s , Matthew Trzcinski , Maxim Cournoyer X-Debbugs-Original-Xcc: Florian Pelz , Ludovic Court??s , Matthew Trzcinski , Maxim Cournoyer Received: via spool by 72457-submit@debbugs.gnu.org id=B72457.172298965726923 (code B ref 72457); Wed, 07 Aug 2024 00:15:03 +0000 Received: (at 72457) by debbugs.gnu.org; 7 Aug 2024 00:14:17 +0000 Received: from localhost ([127.0.0.1]:33326 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1sbUJj-000709-Ef for submit@debbugs.gnu.org; Tue, 06 Aug 2024 20:14:17 -0400 Received: from sendmail.purelymail.com ([34.202.193.197]:33168) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1sbUJe-0006xu-CZ for 72457@debbugs.gnu.org; Tue, 06 Aug 2024 20:14:12 -0400 DKIM-Signature: a=rsa-sha256; b=ol2BUBYZ+gckYqbwh4YF+5gYfcAbtlI4DKomc9/vHdVPuFKPooBa/kfr5qYRtSHtSr0E82lMTxDtDy4CTh5AYyh36xJ54Exm06sLtCpeserancvompb0YYmJ/GGLnTnZEYYMebdIoYcxaUm3IDluCAwatsJF2r7pX/bPewJ6BL7wNx3fcPCax9AJdhwvgQfTrNjgOx6n89kzrqO3d7a7cPWwDy0s9apP67E5lD56BC6CUmpixONUNEVqF2sb1z4WFXQnHXbXxcA/M78pncEkZGbgzacqVFEyjL+QjikdIEpnehFMK6EHycxXm12f18uN/owTJ+U9E5e0iMn+6f5C6A==; s=purelymail3; d=lunabee.space; v=1; bh=8cuo/wLuBQuczHqcZIJtJE5nDbUz5VdusWJm1flzwkM=; h=Received:From:To:Subject:Date; DKIM-Signature: a=rsa-sha256; b=bJc5k+5Xl7HX4FYgMxm1JzcoFR0OUx/GNQP4JDYua7coEiXglAgQlJb2DZt1nvwyALhAUZVhDLqt6K/M3FhmUg5nfvbu7xfjOPmqax7Y7qZJwhwU7GqaKH10C5HZOEflQ7FvK0JnnI5CgfuQ3DGsRIG7IAiSq2KygDnkaS2DSChE7gPZiAm7j1VHx9L5+l+2yaMZnTHrL1Ld2Uuzr88NkAqtFCvNhhtYc/OVyPnC9ak/pcnEKLCptmVisqgPLsFNwc2fLsMvDSSeKUlGihtTjEmMVbUT2jzzDm5SvFLiUDJYNrYdO2mI2lOjOSSVdhWSqGQN5EQO91D5LVDpjczbow==; s=purelymail3; d=purelymail.com; v=1; bh=8cuo/wLuBQuczHqcZIJtJE5nDbUz5VdusWJm1flzwkM=; h=Feedback-ID:Received:From:To:Subject:Date; Feedback-ID: 8937:2070:null:purelymail X-Pm-Original-To: 72457@debbugs.gnu.org Received: by smtp.purelymail.com (Purelymail SMTP) with ESMTPSA id -1661201426; (version=TLSv1.3 cipher=TLS_AES_256_GCM_SHA384); Wed, 07 Aug 2024 00:13:18 +0000 (UTC) Date: Tue, 6 Aug 2024 19:11:26 -0500 Message-ID: <55dcff0096a7a1ee3587af3b112e56fe669a7be4.1722989488.git.lilah@lunabee.space> In-Reply-To: References: MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable X-MIME-Autoconverted: from 8bit to quoted-printable by Purelymail X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: guix-patches@gnu.org List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , From: Lilah Tascheter via Guix-patches Reply-To: Lilah Tascheter Errors-To: guix-patches-bounces+larch=yhetil.org@gnu.org Sender: guix-patches-bounces+larch=yhetil.org@gnu.org X-Migadu-Flow: FLOW_IN X-Migadu-Country: US X-Migadu-Spam-Score: -2.44 X-Spam-Score: -2.44 X-Migadu-Queue-Id: 7AF1964EF5 X-Migadu-Scanner: mx11.migadu.com X-TUID: /JWhWwfFk3wb * doc/guix.texi (Manual Installation)[Proceeding with the Installation]: Offload target reference. (System Installation)[Building the Installation Image]: Use beaglebone as the example, and don't reference deleted variables. (System Configuration)[Using the Configuration System]: Update example. [operating-system Reference]: Can use multiple bootloaders. [Keyboard Layout]: Update example. [Bootloader Configuration]: Update documentation for all bootloaders, and add new ones. Document new fields efi-removable?, 32bit?, and keypair. Update terminal-outputs and terminal-outputs to not be GRUB-specific. : New record. : Remove now-unsupported GRUB specifics in linux. Move device documentation and add some for device-mount-point and device-subvol. Fix typo in multiboot-arguments. Document chain-loader for arbitrary bootloaders. [Invoking guix system]: Bootloaders are now reinstalled. Other bootloaders may be used. [Invoking guix deploy]: Update template. (Creating System Images)[image Reference]: Add target field. [Instantiate an Image]: Update examples and update formatting. : Delete. [image-type Reference]: Reword slightly. Change-Id: I45ac9d5ad3cb491c693e9a4b2f0b44b527478ee7 --- doc/guix.texi | 458 +++++++++++++++++++++++++++++--------------------- 1 file changed, 262 insertions(+), 196 deletions(-) diff --git a/doc/guix.texi b/doc/guix.texi index 41814042f5..b5f35a9066 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -2516,12 +2516,9 @@ Proceeding with the Installation Make sure the @code{bootloader-configuration} form refers to the targets you want to install GRUB on. It should mention @code{grub-bootloader} if you are installing GRUB in the legacy way, or -@code{grub-efi-bootloader} for newer UEFI systems. For legacy systems, -the @code{targets} field contain the names of the devices, like -@code{(list "/dev/sda")}; for UEFI systems it names the paths to mounted -EFI partitions, like @code{(list "/boot/efi")}; do make sure the paths -are currently mounted and a @code{file-system} entry is specified in -your configuration. +@code{grub-efi-bootloader} for newer UEFI systems. +@xref{Bootloader Configuration} for information on how to format the +@code{targets} field. =20 @item Be sure that your file system labels match the value of their respective @@ -2653,11 +2650,13 @@ Building the Installation Image includes the bootloader, specifically: =20 @example -guix system image --system=3Darmhf-linux -e '((@@ (gnu system install) os-= with-u-boot) (@@ (gnu system install) installation-os) "A20-OLinuXino-Lime2= ")' +guix system image --system=3Darmhf-linux -e '(@ (gnu system install) beagl= ebone-black-installation-os)' @end example =20 -@code{A20-OLinuXino-Lime2} is the name of the board. If you specify an in= valid -board, a list of possible boards will be printed. +@code{beaglebone-black} is the name of the board. Similar +@code{installation-os} variables exist for most other supported boards. +Otherwise, you can use @code{embedded-installation-os}, passing it a u-boo= t +bootloader and the desired console tty. =20 =20 @c ********************************************************************* @@ -17229,7 +17228,9 @@ Using the Configuration System @lisp (bootloader-configuration (bootloader grub-efi-bootloader) - (targets '("/boot/efi"))) + (targets (list (bootloader-target + (type 'esp) + (path "/boot/efi"))))) @end lisp =20 @xref{Bootloader Configuration}, for more information on the available @@ -17535,8 +17536,10 @@ operating-system Reference List of strings or gexps representing additional arguments to pass on the command-line of the kernel---e.g., @code{("console=3DttyS0")}. =20 -@item @code{bootloader} -The system bootloader configuration object. @xref{Bootloader Configuratio= n}. +@item @code{bootloader} (default: '()) +The system bootloader configuration object. Can either be a single +@code{bootloader-configuration} or a list of them, to install multiple or = no +bootloaders. @xref{Bootloader Configuration}. =20 @item @code{label} This is the label (a string) as it appears in the bootloader's menu entry. @@ -18731,7 +18734,9 @@ Keyboard Layout (keyboard-layout (keyboard-layout "tr")) ;for the console (bootloader (bootloader-configuration (bootloader grub-efi-bootloader) - (targets '("/boot/efi")) + (targets (list (bootloader-target + (type 'esp) + (path "/boot/efi")))) (keyboard-layout keyboard-layout))) ;for GRUB (services (cons (set-xorg-configuration (xorg-configuration ;for Xorg @@ -42119,132 +42124,124 @@ Bootloader Configuration @cindex EFI, bootloader @cindex UEFI, bootloader @cindex BIOS, bootloader -The bootloader to use, as a @code{bootloader} object. For now -@code{grub-bootloader}, @code{grub-efi-bootloader}, -@code{grub-efi-removable-bootloader}, @code{grub-efi-netboot-bootloader}, -@code{grub-efi-netboot-removable-bootloader}, @code{extlinux-bootloader} -and @code{u-boot-bootloader} are supported. +The bootloader to use, as a @code{bootloader} object. Available bootloade= rs, in +addition to what target types they require, are as follows: =20 -@cindex ARM, bootloaders -@cindex AArch64, bootloaders -Available bootloaders are described in @code{(gnu bootloader @dots{})} -modules. In particular, @code{(gnu bootloader u-boot)} contains definitio= ns -of bootloaders for a wide range of ARM and AArch64 systems, using the -@uref{https://www.denx.de/wiki/U-Boot/, U-Boot bootloader}. +@itemize +@vindex depthcharge-veyron-speedy-bootloader +@item @code{depthcharge-veyron-speedy-bootloader} +For the Asus C201. Requires a @code{'part} target, denoting the partition= to +install the kernel blob as a @code{device}, @code{label}, or @code{uuid}. =20 @vindex grub-bootloader -@code{grub-bootloader} allows you to boot in particular Intel-based machin= es -in ``legacy'' BIOS mode. +@item @code{grub-bootloader} +GRUB2 for BIOS systems. Requires a @code{'disk} target providing either a +@code{device}, @code{label}, or @code{uuid}. If root is mounted over NFS,= it +will load its files and the Guix System over +@acronym{PXE, Preboot eXecution Environment}. + +@vindex grub-minimal-bootloader +@item @code{grub-minimal-bootloader} +As above, but using a minimal build of GRUB. =20 @vindex grub-efi-bootloader -@code{grub-efi-bootloader} allows to boot on modern systems using the -@dfn{Unified Extensible Firmware Interface} (UEFI). This is what you shou= ld -use if the installation image contains a @file{/sys/firmware/efi} director= y -when you boot it on your system. - -@vindex grub-efi-removable-bootloader -@code{grub-efi-removable-bootloader} allows you to boot your system from -removable media by writing the GRUB file to the UEFI-specification locatio= n of -@file{/EFI/BOOT/BOOTX64.efi} of the boot directory, usually @file{/boot/ef= i}. -This is also useful for some UEFI firmwares that ``forget'' their configur= ation -from their non-volatile storage. Like @code{grub-efi-bootloader}, this can= only -be used if the @file{/sys/firmware/efi} directory is available. +@item @code{grub-efi-bootloader} +GRUB2 for "modern" systems using the @dfn{Unified Extensible Firmware Inte= rface} +(UEFI). Requires an @code{'esp} target providing a @code{path} to the mou= nt +point of the EFI System Partition. If root is mounted over NFS, it will l= oad +its files and the Guix System over a +@acronym{TFTP, Trivial File Transfer Protocol} server as configured over +@acronym{DHCP, Dynamic Host Configuration Protocol} as per PXE. + +@vindex extlinux-bootloader +@item @code{extlinux-bootloader} +Extlinux for "legacy" BIOS systems. Requires a @code{'disk} target provid= ing +either a @code{device}, @code{label}, or @code{uuid}. + +@vindex extlinux-gpt-bootloader +@item @code{extlinux-gpt-bootloader} +As above, but for systems using the GPT instead of MBR partition table. + +@cindex Secure Boot, UEFI +@vindex uki-efi-bootloader +@item @code{uki-efi-bootloader} +Makes and installs UKI images for UEFI systems. Requires an @code{'esp} t= arget +providing a @code{path} to the mount point of the EFI System Partition. N= ot all +system generations may be available with this option, as UKI images contai= n the +entire kernel and initramfs, and ESPs tend to be small. + +Full disk encryption with @code{uki-efi-bootloader} only requires a single +password entry with fast decryption, in contrast to GRUB2 requiring a seco= nd +password entry with slow, LUKS1-only decryption. + +This is the only bootloader to currently support UEFI secure boot, when +configured as below. =20 -@quotation Note -This @emph{will} overwrite the GRUB file from any other operating systems = that -also place their GRUB file in the UEFI-specification location; making them -unbootable. -@end quotation +@cindex ARM, bootloaders +@cindex AArch64, bootloaders +@vindex u-boot-a20-olinuxino-lime-bootloader +@vindex u-boot-a20-olinuxino-lime2-bootloader +@vindex u-boot-a20-olinuxino-micro-bootloader +@vindex u-boot-bananapi-m2-ultra-bootloader +@vindex u-boot-beaglebone-black-bootloader +@vindex u-boot-cubietruck-bootloader +@vindex u-boot-firefly-rk3399-bootloader +@vindex u-boot-mx6cuboxi-bootloader +@vindex u-boot-nintendo-nes-classic-edition-bootloader +@vindex u-boot-novena-bootloader +@vindex u-boot-orangepi-r1-plus-lts-rk3328-bootloader +@vindex u-boot-pine64-plus-bootloader +@vindex u-boot-pine64-lts-bootloader +@vindex u-boot-pinebook-bootloader +@vindex u-boot-pinebook-pro-rk3399-bootloader +@vindex u-boot-puma-rk3399-bootloader +@vindex u-boot-rock64-rk3328-bootloader +@vindex u-boot-rockpro64-rk3399-bootloader +@vindex u-boot-sifive-unmatched-bootloader +@vindex u-boot-qemu-riscv64-bootloader +@vindex u-boot-starfive-visionfive2-bootloader +@vindex u-boot-ts7970-q-2g-1000mhz-c-bootloader +@vindex u-boot-wandboard-bootloader +@vindex u-boot-rpi-2-bootloader +@vindex u-boot-rpi-3-bootloader +@vindex u-boot-rpi-4-bootloader +@vindex u-boot-rpi-bootloader +@item U-Boot +U-Boot has individual bootloaders @code{u-boot-board-bootloader} for each +of the following @code{board}s: @code{a20-olinuxino-lime}, +@code{a20-olinuxino-lime2}, @code{a20-olinuxino-micro}, +@code{bananapi-m2-ultra}, @code{beaglebone-black}, @code{cubietruck}, +@code{firefly-rk3399}, @code{mx6cuboxi}, @code{nintendo-nes-classic-editio= n}, +@code{novena}, @code{orangepi-r1-plus-lts-rk3328}, @code{pine64-plus}, +@code{pine64-lts}, @code{pinebook}, @code{pinebook-pro-rk3399}, +@code{puma-rk3399}, @code{rock64-rk3328}, @code{rockpro64-rk3399}, +@code{rpi-2}, @code{rpi-3}, @code{rpi-4}, @code{rpi}, @code{sifive-unmatch= ed}, +@code{ts7970-q-2g-1000mhz-c}, @code{qemu-riscv64}, and @code{wandboard}. + +Each of these requires a @code{'disk} target providing either a @code{devi= ce}, +@code{label}, or @code{uuid}, except for @code{ts7970-q-2g-1000mhz-c} and +@code{qemu-riscv64}, in which the bootloader just copies U-Boot to +@file{/boot/u-boot.imx} or @file{/boot/u-boot.bin}, respectively. You sho= uld +then manually flash it to the SPI flash at the U-Boot prompt. + +By default Guix configures U-Boot to boot using a generated extlinux confi= g, but +U-Boot does support loading UEFI bootloaders, if you want to combine it wi= th +another. +@end itemize =20 -@vindex grub-efi-netboot-bootloader -@code{grub-efi-netboot-bootloader} allows you to boot your system over net= work -through TFTP@. In combination with an NFS root file system this allows yo= u to -build a diskless Guix system. - -The installation of the @code{grub-efi-netboot-bootloader} generates the -content of the TFTP root directory at @code{targets} (@pxref{Bootloader -Configuration, @code{targets}}) below the sub-directory @file{efi/Guix}, t= o be -served by a TFTP server. You may want to mount your TFTP server directori= es -onto the @code{targets} to move the required files to the TFTP server -automatically during installation. - -If you plan to use an NFS root file system as well (actually if you mount = the -store from an NFS share), then the TFTP server needs to serve the file -@file{/boot/grub/grub.cfg} and other files from the store (like GRUBs back= ground -image, the kernel (@pxref{operating-system Reference, @code{kernel}}) and = the -initrd (@pxref{operating-system Reference, @code{initrd}})), too. All the= se -files from the store will be accessed by GRUB through TFTP with their norm= al -store path, for example as -@file{tftp://tftp-server/gnu/store/=E2=80=A6-initrd/initrd.cpio.gz}. - -Two symlinks are created to make this possible. For each target in the -@code{targets} field, the first symlink is -@samp{target}@file{/efi/Guix/boot/grub/grub.cfg} pointing to -@file{../../../boot/grub/grub.cfg}, where @samp{target} may be -@file{/boot}. In this case the link is not leaving the served TFTP root -directory, but otherwise it does. The second link is -@samp{target}@file{/gnu/store} and points to @file{../gnu/store}. This -link is leaving the served TFTP root directory. - -The assumption behind all this is that you have an NFS server exporting -the root file system for your Guix system, and additionally a TFTP -server exporting your @code{targets} directories=E2=80=94usually a single -@file{/boot}=E2=80=94from that same root file system for your Guix system.= In -this constellation the symlinks will work. - -For other constellations you will have to program your own bootloader -installer, which then takes care to make necessary files from the store -accessible through TFTP, for example by copying them into the TFTP root -directory for your @code{targets}. - -It is important to note that symlinks pointing outside the TFTP root direc= tory -may need to be allowed in the configuration of your TFTP server. Further = the -store link exposes the whole store through TFTP@. Both points need to be -considered carefully for security aspects. It is advised to disable any T= FTP -write access! - -Please note, that this bootloader will not modify the =E2=80=98UEFI Boot M= anager=E2=80=99 of -the system. - -Beside the @code{grub-efi-netboot-bootloader}, the already mentioned TFTP = and -NFS servers, you also need a properly configured DHCP server to make the b= ooting -over netboot possible. For all this we can currently only recommend you t= o look -for instructions about @acronym{PXE, Preboot eXecution Environment}. - -If a local EFI System Partition (ESP) or a similar partition with a FAT -file system is mounted in @code{targets}, then symlinks cannot be -created. In this case everything will be prepared for booting from -local storage, matching the behavior of @code{grub-efi-bootloader}, with -the difference that all GRUB binaries are copied to @code{targets}, -necessary for booting over the network. - -@vindex grub-efi-netboot-removable-bootloader -@code{grub-efi-netboot-removable-bootloader} is identical to -@code{grub-efi-netboot-bootloader} with the exception that the -sub-directory @file{efi/boot} will be used instead of @file{efi/Guix} to -comply with the UEFI specification for removable media. +@item @code{targets} +This is a list of @code{bootloader-target} (see below) structures denoting +where the bootloader should install itself. Interpretation of specific ta= rget +types and target requirements depend on the specific @code{bootloader} use= d. =20 @quotation Note -This @emph{will} overwrite the GRUB file from any other operating systems = that -also place their GRUB file in the UEFI-specification location; making them -unbootable. +Bootloaders have a set of default targets, that can interact with user-spe= cified +targets. For UEFI bootloaders using the @code{'esp} target, this typicall= y +includes a @code{'vendir} target. If you configure multiple UEFI bootload= ers, +you should set different @code{'vendir} target @code{path}s for each, each +@code{offset} from @code{'esp}. @end quotation =20 -@item @code{targets} -This is a list of strings denoting the targets onto which to install the -bootloader. - -The interpretation of targets depends on the bootloader in question. -For @code{grub-bootloader}, for example, they should be device names -understood by the bootloader @command{installer} command, such as -@code{/dev/sda} or @code{(hd0)} (@pxref{Invoking grub-install,,, grub, -GNU GRUB Manual}). For @code{grub-efi-bootloader} and -@code{grub-efi-removable-bootloader} they should be mount -points of the EFI file system, usually @file{/boot/efi}. For -@code{grub-efi-netboot-bootloader}, @code{targets} should be the mount -points corresponding to TFTP root directories served by your TFTP -server. - @item @code{menu-entries} (default: @code{'()}) A possibly empty list of @code{menu-entry} objects (see below), denoting entries to appear in the bootloader menu, in addition to the current @@ -42254,6 +42251,29 @@ Bootloader Configuration The index of the default boot menu entry. Index 0 is for the entry of the current system. =20 +@item @code{efi-removable?} (default: @var{#f}) +Used by all UEFI bootloaders to determine whether they should be installed= to +the UEFI standard fallback bootloader path (on x86_64, +@file{/EFI/BOOT/BOOTX64.EFI}). This allows it to be booted from removable= media +or otherwise in cases where the system has not been booted from UEFI alrea= dy. + +@quotation Warning +This will override any other bootloaders installed to the same path! +@end quotation + +@item @code{32bit?} (default: @var{#f}) +Some 64-bit systems require their bootloaders to be 32-bit, including some= early +UEFI systems and some Raspberry Pis. If that is the case, and the bootloa= der +supports it, setting this option will force the bootloader to install as i= f it +were on a 32-bit system. + +@item @code{keypair} (default: @var{#f}) +Designates a keypair to be used by bootloaders that support some kind of +cryptographic signature, such as UEFI Secure Boot. This must be a pair +@code{'(cert . priv)} of paths to the public key (@code{cert}) and private= key +(@code{priv}). The keys these paths point to should be owned by root with= 600 +permissions for security purposes. + @item @code{timeout} (default: @code{5}) The number of seconds to wait for keyboard input before booting. Set to 0 to boot immediately, and to -1 to wait indefinitely. @@ -42276,19 +42296,20 @@ Bootloader Configuration is provided, some bootloaders might use a default theme, that's true for GRUB. =20 -@item @code{terminal-outputs} (default: @code{'(gfxterm)}) +@item @code{terminal-outputs} (default: @var{#f}) The output terminals used for the bootloader boot menu, as a list of -symbols. GRUB accepts the values: @code{console}, @code{serial}, -@code{serial_@{0-3@}}, @code{gfxterm}, @code{vga_text}, -@code{mda_text}, @code{morse}, and @code{pkmodem}. This field -corresponds to the GRUB variable @code{GRUB_TERMINAL_OUTPUT} (@pxref{Simpl= e -configuration,,, grub,GNU GRUB manual}). - -@item @code{terminal-inputs} (default: @code{'()}) +symbols. When @var{#f}, the default is used. For GRUB this is @code{gfxt= erm}. +GRUB accepts the values: @code{console}, @code{serial}, @code{serial_@{0-3= @}}, +@code{gfxterm}, @code{vga_text}, @code{mda_text}, @code{morse}, and +@code{pkmodem}. This field corresponds to the GRUB variable +@code{GRUB_TERMINAL_OUTPUT} +(@pxref{Simple configuration,,, grub,GNU GRUB manual}). + +@item @code{terminal-inputs} (default: @var{#f}) The input terminals used for the bootloader boot menu, as a list of -symbols. For GRUB, the default is the native platform terminal as -determined at run-time. GRUB accepts the values: @code{console}, -@code{serial}, @code{serial_@{0-3@}}, @code{at_keyboard}, and +symbols. When @var{#f}, the default is used. For GRUB, this is the native +platform terminal as determined at run-time. GRUB accepts the values: +@code{console}, @code{serial}, @code{serial_@{0-3@}}, @code{at_keyboard}, = and @code{usb_keyboard}. This field corresponds to the GRUB variable @code{GRUB_TERMINAL_INPUT} (@pxref{Simple configuration,,, grub,GNU GRUB manual}). @@ -42364,6 +42385,53 @@ Bootloader Configuration =20 @end deftp =20 +@vindex bootloader-target +Configuring bootloader targets uses a specialized record designed for clar= ity +and to abstract the varying user-supplied paths bootloaders may need. Onl= y the +@code{type} field is required; Guix will attempt to extrapolate as needed = from +what information you provide, though at least one of @code{path}, @code{de= vice}, +@code{label}, or @code{uuid} is required to do so. + +@deftp {Data Type} bootloader-target +The type of a target as used in @code{bootloader-configuration}. + +@table @asis + +@item @code{type} +What target this record is describing. Must be a symbol, for example @code= {'esp} +or @code{'disk}. + +@item @code{path} (default: @var{#f}) +@code{path} denotes a string path, usually interpreted by the bootloader t= o +signify a mount point (such as in the case of @code{'esp}). This value is +automatically offset from the target denoted by @code{offset}, even if the= path +given is absolute. This allows for bootloaders to know what device or par= tition +a @code{path} is actually stored on, and how to locate it. + +@item @code{offset} (default: @code{'root} when @code{path}, otherwise @va= r{#f}) +All @code{path} values, even if absolute, are automatically offset from an= other. +@code{offset} is a symbol denoting which target type the path should be of= fset +from. This allows for bootloaders to know what device or partition a +@code{path} is actually stored on, and how to locate it. + +For most setups, you don't need to deal with this. + +@item @code{device} (default: @var{#f}) +@itemx @code{label} (default: @var{#f}) +@itemx @code{uuid} (default: @var{#f}) +These all work as a way of defining some kind of physical device or partit= ion. +@code{uuid} (taking a @code{uuid} record) and @code{label} (taking a strin= g) are +vastly preferred over device (a string denoting a filesystem path to a blo= ck +device), as block device names are inconsistant and unrecognized at boot-t= ime. + +@item @code{file-system} (default: @var{#f}) +A string denoting a file system type, as used in @ref{File Systems}. Unle= ss +your filesystem isn't being detected properly, or is unmounted at bootload= er +install-time, you shouldn't need to specify this. + +@end table +@end deftp + @cindex dual boot @cindex boot menu Should you want to list additional boot menu entries @i{via} the @@ -42375,6 +42443,8 @@ Bootloader Configuration @lisp (menu-entry (label "The Other Distro") + (device (file-system-label "boot")) + (device-mount-point "/boot") (linux "/boot/old/vmlinux-2.6.32") (linux-arguments '("root=3D/dev/sda2")) (initrd "/boot/old/initrd")) @@ -42390,6 +42460,28 @@ Bootloader Configuration @item @code{label} The label to show in the menu---e.g., @code{"GNU"}. =20 +@item @code{device} (default: @var{#f}) +The device where any files specified below are to be found--eg, for GRUB, +@dfn{root} for this menu entry (@pxref{root,,, grub, GNU GRUB manual}). + +This may be a file system label (a string), a file system UUID (a +bytevector, @pxref{File Systems}), or @code{#f}, in which case +the bootloader will search the device containing the file specified by +the @code{linux} field (@pxref{search,,, grub, GNU GRUB manual}). It +must @emph{not} be an OS device name such as @file{/dev/sda1}. + +@item @code{device-mount-point} (default: @var{#f}) +This is where @code{device} is mounted onto your file system. If provided= , it +allows for you to specify full paths for provided files, which will be +automatically realized into paths local to their device. + +This is not necessary if specified files are already referring to files lo= cal to +@code{device}, including if they're on your root filesystem. + +@item @code{device-subvol} (default: @var{#f}) +This is a btrfs subvolume name, useful in case you wish to access files fr= om a +btrfs subvolume on a device. @xref{Btrfs file system}. + @item @code{linux} (default: @code{#f}) The Linux kernel image to boot, for example: =20 @@ -42397,17 +42489,6 @@ Bootloader Configuration (file-append linux-libre "/bzImage") @end lisp =20 -For GRUB, it is also possible to specify a device explicitly in the -file path using GRUB's device naming convention (@pxref{Naming -convention,,, grub, GNU GRUB manual}), for example: - -@example -"(hd0,msdos1)/boot/vmlinuz" -@end example - -If the device is specified explicitly as above, then the @code{device} -field is ignored entirely. - @item @code{linux-arguments} (default: @code{'()}) The list of extra Linux kernel command-line arguments---e.g., @code{'("console=3DttyS0")}. @@ -42416,16 +42497,6 @@ Bootloader Configuration A G-Expression or string denoting the file name of the initial RAM disk to use (@pxref{G-Expressions}). =20 -@item @code{device} (default: @code{#f}) -The device where the kernel and initrd are to be found---i.e., for GRUB, -@dfn{root} for this menu entry (@pxref{root,,, grub, GNU GRUB manual}). - -This may be a file system label (a string), a file system UUID (a -bytevector, @pxref{File Systems}), or @code{#f}, in which case -the bootloader will search the device containing the file specified by -the @code{linux} field (@pxref{search,,, grub, GNU GRUB manual}). It -must @emph{not} be an OS device name such as @file{/dev/sda1}. - @item @code{multiboot-kernel} (default: @code{#f}) The kernel to boot in Multiboot-mode (@pxref{multiboot,,, grub, GNU GRUB manual}). When this field is set, a Multiboot menu-entry is generated. @@ -42448,7 +42519,7 @@ Bootloader Configuration To use the new and still experimental @uref{https://darnassus.sceen.net/~hurd-web/rump_kernel/, rumpdisk user-level disk driver} instead of GNU@tie{}Mach's in-kernel IDE driver, -set @code{kernel-arguments} to: +set @code{multiboot-arguments} to: =20 @lisp '("noide") @@ -42471,10 +42542,11 @@ Bootloader Configuration @end lisp =20 @item @code{chain-loader} (default: @code{#f}) -A string that can be accepted by @code{grub}'s @code{chainloader} -directive. This has no effect if either @code{linux} or -@code{multiboot-kernel} fields are specified. The following is an -example of chainloading a different GNU/Linux system. +Varies slightly depending on bootloader. For @code{grub}, this is anythin= g that +the @code{chainloader} directive can accept +(@pxref{Chain-loading,,, grub, GNU GRUB manual}). For @code{uki-efi}, this= is +any efi binary to be installed alongside the system. The following is an e= xample +of chainloading a different GNU/Linux system. =20 @lisp (bootloader @@ -42682,10 +42754,6 @@ Invoking guix system supported by the bootloader being used. The next time the system boots, it will use the specified system generation. =20 -The bootloader itself is not being reinstalled when using this -command. Thus, the installed bootloader is used with an updated -configuration file. - The target generation can be specified explicitly by its generation number. For example, the following invocation would switch to system generation 7: @@ -42706,11 +42774,10 @@ Invoking guix system @end example =20 Currently, the effect of invoking this action is @emph{only} to switch -the system profile to an existing generation and rearrange the -bootloader menu entries. To actually start using the target system -generation, you must reboot after running this action. In the future, -it will be updated to do the same things as @command{reconfigure}, -like activating and deactivating services. +the system profile to an existing generation and reinstall the bootloader.= To +actually start using the target system generation, you must reboot after +running this action. In the future, it will be updated to do the same thi= ngs +as @command{reconfigure}, like activating and deactivating services. =20 This action will fail if the specified generation does not exist. =20 @@ -42886,11 +42953,9 @@ Invoking guix system When using the @code{qcow2} image type, the returned image is in qcow2 format, which the QEMU emulator can efficiently use. @xref{Running Guix in a VM}, for more information on how to run the image in a virtual -machine. The @code{grub-bootloader} bootloader is always used -independently of what is declared in the @code{operating-system} file -passed as argument. This is to make it easier to work with QEMU, which -uses the SeaBIOS BIOS by default, expecting a bootloader to be installed -in the Master Boot Record (MBR). +machine. Currently, QEMU as packaged in Guix does not have UEFI support, +so you should select a bootloader for BIOS systems in your +@code{operating-system} configuration. =20 @cindex docker-image, creating docker images When using the @code{docker} image type, a Docker image is produced. @@ -43208,7 +43273,6 @@ Invoking guix deploy ;; forwarded to the host's loopback interface. =20 (use-service-modules networking ssh) -(use-package-modules bootloaders) =20 (define %system (operating-system @@ -43216,7 +43280,9 @@ Invoking guix deploy (timezone "Etc/UTC") (bootloader (bootloader-configuration (bootloader grub-bootloader) - (targets '("/dev/vda")) + (targets (list (bootloader-target + (type 'disk) + (device "/dev/sda")))) (terminal-outputs '(console)))) (file-systems (cons (file-system (mount-point "/") @@ -47800,6 +47866,12 @@ partition Reference this flag set, usually the root one. The @code{'esp} flag identifies a UEFI System Partition. =20 +@item @code{target} (default: @var{#f}) +If provided, this partition provides itself as a bootloader target +(@pxref{Bootloader Configuration}). Most commonly, this is used to provid= e the +@code{'root} and @code{'esp} targets, with the root partition and EFI Syst= em +Partition, respectively, though this can provide any target necessary. + @item @code{initializer} (default: @code{#false}) The partition initializer procedure as a gexp. This procedure is called to populate a partition. If no initializer is passed, the @@ -47848,6 +47920,7 @@ Instantiate an Image (label "GNU-ESP") (file-system "vfat") (flags '(esp)) + (target 'esp) (initializer (gexp initialize-efi-partition))) (partition (size (* 50 MiB)) @@ -47864,14 +47937,15 @@ Instantiate an Image (label root-label) (file-system "ext4") (flags '(boot)) + (target 'root) (initializer (gexp initialize-root-partition)))))) @end lisp =20 -Note that the first and third partitions use generic initializers -procedures, initialize-efi-partition and initialize-root-partition -respectively. The initialize-efi-partition installs a GRUB EFI loader -that is loading the GRUB bootloader located in the root partition. The -initialize-root-partition instantiates a complete system as defined by +Note that the first and third partitions use generic initializer +procedures, @code{initialize-efi-partition} and @code{initialize-root-part= ition} +respectively. @code{initialize-efi-partition} simply creates the director= y +structure for an EFI bootloader to install itself to. +@code{initialize-root-partition} instantiates a complete system as defined= by the @code{%simple-os} operating-system. =20 You can now run: @@ -47929,10 +48003,6 @@ Instantiate an Image @code{i686} machines, supporting BIOS or UEFI booting. @end defvar =20 -@defvar efi32-disk-image -Same as @code{efi-disk-image} but with a 32 bits EFI partition. -@end defvar - @defvar iso9660-image An ISO-9660 image composed of a single bootable partition. This image can also be used on most @code{x86_64} and @code{i686} machines. @@ -48023,10 +48093,6 @@ image-type Reference Build an image based on the @code{efi-disk-image} image. @end defvar =20 -@defvar efi32-raw-image-type -Build an image based on the @code{efi32-disk-image} image. -@end defvar - @defvar qcow2-image-type Build an image based on the @code{mbr-disk-image} image but with the @code{compressed-qcow2} image format. @@ -48054,14 +48120,14 @@ image-type Reference @defvar pinebook-pro-image-type Build an image that is targeting the Pinebook Pro machine. The MBR image contains a single partition starting at a @code{9MiB} offset. The -@code{u-boot-pinebook-pro-rk3399-bootloader} bootloader will be +@code{u-boot-pinebook-pro-rk3399-bootloader} bootloader can be installed in this gap. @end defvar =20 @defvar rock64-image-type Build an image that is targeting the Rock64 machine. The MBR image contains a single partition starting at a @code{16MiB} offset. The -@code{u-boot-rock64-rk3328-bootloader} bootloader will be installed in +@code{u-boot-rock64-rk3328-bootloader} bootloader can be installed in this gap. @end defvar =20 --=20 2.45.2