diff --git a/doc/guix.texi b/doc/guix.texi index 388d601e61..969b722cc3 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -2529,12 +2529,9 @@ in particular: 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. @item Be sure that your file system labels match the value of their respective @@ -17276,7 +17273,9 @@ the @code{bootloader} field should contain something along these lines: @lisp (bootloader-configuration (bootloader grub-efi-bootloader) - (targets '("/boot/efi"))) + (targets (list (bootloader-target + (type 'esp) + (path "/boot/efi"))))) @end lisp @xref{Bootloader Configuration}, for more information on the available @@ -17582,8 +17581,10 @@ from--e.g. @code{(list ddcci-driver-linux)}. List of strings or gexps representing additional arguments to pass on the command-line of the kernel---e.g., @code{("console=ttyS0")}. -@item @code{bootloader} -The system bootloader configuration object. @xref{Bootloader Configuration}. +@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}. @item @code{label} This is the label (a string) as it appears in the bootloader's menu entry. @@ -18778,7 +18779,9 @@ configuration would look like: (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 @@ -42240,18 +42243,8 @@ The type of a bootloader configuration declaration. @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. - -@cindex ARM, bootloaders -@cindex AArch64, bootloaders -Available bootloaders are described in @code{(gnu bootloader @dots{})} -modules. In particular, @code{(gnu bootloader u-boot)} contains definitions -of bootloaders for a wide range of ARM and AArch64 systems, using the -@uref{https://www.denx.de/wiki/U-Boot/, U-Boot bootloader}. +The bootloader to use. Available bootloaders, in addition to what +target types they require, are as follows: @itemize @vindex depthcharge-veyron-speedy-bootloader @@ -42260,117 +42253,104 @@ 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}. @vindex grub-bootloader -@code{grub-bootloader} allows you to boot in particular Intel-based machines -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. @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 should -use if the installation image contains a @file{/sys/firmware/efi} directory -when you boot it on your system. +@item @code{grub-efi-bootloader} +GRUB2 for "modern" systems using the +@acronym{UEFI, Unified Extensible Firmware Interface}. It requires an +@code{'esp} target providing a mount point @code{path} for the EFI +System Partition. If root is mounted over NFS, a PXE client will load +the boot files and Guix System from a +@acronym{TFTP, Trivial File Transfer Protocol} server, discovered via +@acronym{DHCP, Dynamic Host Configuration Protocol}. -@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 location of -@file{/EFI/BOOT/BOOTX64.efi} of the boot directory, usually @file{/boot/efi}. -This is also useful for some UEFI firmwares that ``forget'' their configuration -from their non-volatile storage. Like @code{grub-efi-bootloader}, this can only -be used if the @file{/sys/firmware/efi} directory is available. +@vindex extlinux-bootloader +@item @code{extlinux-bootloader} +Extlinux for "legacy" BIOS systems which use an MBR partition table. +It requires a @code{'disk} target providing either a @code{device}, +@code{label}, or @code{uuid}. -@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 +@vindex extlinux-gpt-bootloader +@item @code{extlinux-gpt-bootloader} +This is the same as above, but for systems with a GPT partition table. -@vindex grub-efi-netboot-bootloader -@code{grub-efi-netboot-bootloader} allows you to boot your system over network -through TFTP@. In combination with an NFS root file system this allows you to -build a diskless Guix system. +@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-nanopi-r4s-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-orangepi-zero-2w-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-qemu-riscv64-bootloader +@vindex u-boot-rock64-rk3328-bootloader +@vindex u-boot-rockpro64-rk3399-bootloader +@vindex u-boot-rpi-2-bootloader +@vindex u-boot-rpi-3-bootloader +@vindex u-boot-rpi-4-bootloader +@vindex u-boot-rpi-bootloader +@vindex u-boot-sifive-unmatched-bootloader +@vindex u-boot-starfive-visionfive2-bootloader +@vindex u-boot-ts7970-q-2g-1000mhz-c-bootloader +@vindex u-boot-wandboard-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{nanopi-r4s}, +@code{nintendo-nes-classic-edition}, @code{novena}, +@code{orangepi-r1-plus-lts-rk3328}, @code{orangepi-zero-2w}, +@code{pine64-plus}, @code{pine64-lts}, @code{pinebook}, +@code{pinebook-pro-rk3399}, @code{puma-rk3399}, @code{qemu-riscv64}, +@code{rock64-rk3328}, @code{rockpro64-rk3399}, @code{rpi-2}, +@code{rpi-3}, @code{rpi-4}, @code{rpi}, @code{sifive-unmatched}, +@code{ts7970-q-2g-1000mhz-c}, and @code{wandboard}. -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}, to be -served by a TFTP server. You may want to mount your TFTP server directories -onto the @code{targets} to move the required files to the TFTP server -automatically during installation. +Each of these require a @code{'disk} target providing either a @code{device}, +@code{label}, or @code{uuid}, except the @code{ts7970-q-2g-1000mhz-c} +and @code{qemu-riscv64} boards. Here the bootloader just copies U-Boot +to @file{/boot/u-boot.imx} or @file{/boot/u-boot.bin}, respectively. +You should then manually flash it to the SPI flash at the U-Boot prompt. -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 background -image, the kernel (@pxref{operating-system Reference, @code{kernel}}) and the -initrd (@pxref{operating-system Reference, @code{initrd}})), too. All these -files from the store will be accessed by GRUB through TFTP with their normal -store path, for example as -@file{tftp://tftp-server/gnu/store/…-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—usually a single -@file{/boot}—from 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 directory -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 TFTP -write access! - -Please note, that this bootloader will not modify the ‘UEFI Boot Manager’ 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 booting -over netboot possible. For all this we can currently only recommend you to 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. - -@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 +By default Guix configures U-Boot to use a generated extlinux config. +However U-Boot can be configured to run a UEFI application, if you want +to chain load another bootloader. +@end itemize @item @code{targets} -This is a list of strings denoting the targets onto which to install the -bootloader. +This is a list of @code{bootloader-target} (see below) structures denoting +where the bootloader should install itself. Interpretation of specific target +types and target requirements depend on the specific @code{bootloader} used. -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. +@quotation Note +Bootloaders have a set of default targets, that can interact with user-specified +targets. For UEFI bootloaders using the @code{'esp} target, this typically +includes a @code{'vendir} target. If you configure multiple UEFI bootloaders, +you should set different @code{'vendir} target @code{path}s for each, each +@code{offset} from @code{'esp}. +@end quotation @item @code{menu-entries} (default: @code{'()}) A possibly empty list of @code{menu-entry} objects (see below), denoting @@ -42381,6 +42361,29 @@ system entry and the entry pointing to previous system generations. The index of the default boot menu entry. Index 0 is for the entry of the current system. +@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 already. + +@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 bootloader +supports it, setting this option will force the bootloader to install as if 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. @@ -42492,6 +42495,51 @@ Currently only supported by GRUB. @end deftp +@vindex bootloader-target +Configuring bootloader targets uses a specialized record designed for clarity +and to abstract over the varying user-supplied paths bootloaders. Only 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{device}, +@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 to +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 partition +a @code{path} is actually stored on, and how to locate it. + +@item @code{offset} (default: @code{'root} when @code{path}, otherwise @var{#f}) +All @code{path} values, even if absolute, are automatically offset from another. +@code{offset} is a symbol denoting which target type the path should be offset +from. This allows for bootloaders to know what device or partition a +@code{path} is actually stored on, and how to locate it. + +@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 partition. +Using @code{uuid} and @code{label} to refer to a filesystem's UUID or +label is vastly preferred over using @code{device} to refer to block +devices, as they can vary per boot and may not exist at boot-time. + +@item @code{file-system} (default: @var{#f}) +A string denoting a file system type, as used in @ref{File Systems}. Unless +your filesystem isn't being detected properly, or is unmounted at bootloader +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 @@ -42503,6 +42551,8 @@ along these lines: @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=/dev/sda2")) (initrd "/boot/old/initrd")) @@ -42518,6 +42568,29 @@ The type of an entry in the bootloader menu. @item @code{label} The label to show in the menu---e.g., @code{"GNU"}. +@item @code{device} (default: @var{#f}) +The device where any files specified below are to be found. For GRUB, +this is what @dfn{root} (@pxref{root,,, grub, GNU GRUB manual}) is set +to for this menu entry. + +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 local 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 from a +btrfs subvolume on a device. @xref{Btrfs file system}. + @item @code{linux} (default: @code{#f}) The Linux kernel image to boot, for example: @@ -42525,17 +42598,6 @@ The Linux kernel image to boot, for example: (file-append linux-libre "/bzImage") @end lisp -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=ttyS0")}. @@ -42544,16 +42606,6 @@ The list of extra Linux kernel command-line arguments---e.g., A G-Expression or string denoting the file name of the initial RAM disk to use (@pxref{G-Expressions}). -@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. @@ -42576,7 +42628,7 @@ console (use options @option{--nographic} @option{--serial mon:stdio}): 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: @lisp '("noide") @@ -42599,10 +42651,8 @@ The list of commands for loading Multiboot modules. For example: @end lisp @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 anything that +the @code{chainloader} directive can accept @lisp (bootloader @@ -42810,10 +42860,6 @@ and it moves the entries for the other generations to a submenu, if supported by the bootloader being used. The next time the system boots, it will use the specified system generation. -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: @@ -42834,11 +42880,10 @@ guix system switch-generation -- -1 @end example 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 things +as @command{reconfigure}, like activating and deactivating services. This action will fail if the specified generation does not exist. @@ -43014,11 +43059,9 @@ types. 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. @cindex docker-image, creating docker images When using the @code{docker} image type, a Docker image is produced. @@ -43336,7 +43379,6 @@ evaluates to. As an example, @var{file} might contain a definition like this: ;; forwarded to the host's loopback interface. (use-service-modules networking ssh) -(use-package-modules bootloaders) (define %system (operating-system @@ -43344,7 +43386,9 @@ evaluates to. As an example, @var{file} might contain a definition like this: (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 "/")