ryan77627/guix
1
0
Fork 0
mirror of https://git.in.rschanz.org/ryan77627/guix.git synced 2024-11-07 07:26:13 -05:00
Code Issues Projects Releases Packages Wiki Activity Actions

doc: Update bootloader documentation.

Browse source 
* doc/guix.texi (Manual Installation)[Proceeding with the Installation]:
Offload target reference.

(System Installation)[Building the Installation Image]: Don't reference
deleted variables.

(System Configuration)[Using the Configuration System]: Update example.
[operating-system Reference]<bootloader>: Can use multiple bootloaders.
[Proceeding with the installation]: Refer to Bootloader Configuration.
[Building the Installation Image]: Update example.
[Bootloader Configuration]<bootloader>: Update documentation for all
bootloaders, and add new ones. Document new fields efi-removable?,
32bit?, and keypair.
<bootloader-target>: New record.
<menu-entry>: 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]<switch-generation>: Bootloaders are now
reinstalled.
<image> Other bootloaders may be used.
[Invoking guix deploy]: Update template.

Change-Id: I45ac9d5ad3cb491c693e9a4b2f0b44b527478ee7
This commit is contained in:
Lilah Tascheter 2024-08-06 19:11:26 -05:00 committed by Ryan Schanzenbacher
parent 40e19b3be0
commit fd4e074d61
Signed by: ryan77627
GPG key ID: 81B0E222A3E2308E
1 changed files with 209 additions and 165 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

374
doc/guix.texi
View file

@ -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 "/")