doc: Adapt to multiple bootloader support.
* doc/guix.texi (GRUB configuration): Rename to "Bootloader configuration". Remove device-mount-point field from menu-entry description. Adapt occurences of "GRUB" in other sections.
This commit is contained in:
parent
8b22107e5d
commit
74e6472451
177
doc/guix.texi
177
doc/guix.texi
|
@ -199,7 +199,7 @@ System Configuration
|
||||||
* X.509 Certificates:: Authenticating HTTPS servers.
|
* X.509 Certificates:: Authenticating HTTPS servers.
|
||||||
* Name Service Switch:: Configuring libc's name service switch.
|
* Name Service Switch:: Configuring libc's name service switch.
|
||||||
* Initial RAM Disk:: Linux-Libre bootstrapping.
|
* Initial RAM Disk:: Linux-Libre bootstrapping.
|
||||||
* GRUB Configuration:: Configuring the boot loader.
|
* Bootloader Configuration:: Configuring the boot loader.
|
||||||
* Invoking guix system:: Instantiating a system configuration.
|
* Invoking guix system:: Instantiating a system configuration.
|
||||||
* Running GuixSD in a VM:: How to run GuixSD in a virtual machine.
|
* Running GuixSD in a VM:: How to run GuixSD in a virtual machine.
|
||||||
* Defining Services:: Adding new service definitions.
|
* Defining Services:: Adding new service definitions.
|
||||||
|
@ -7797,7 +7797,7 @@ instance to support new system services.
|
||||||
* X.509 Certificates:: Authenticating HTTPS servers.
|
* X.509 Certificates:: Authenticating HTTPS servers.
|
||||||
* Name Service Switch:: Configuring libc's name service switch.
|
* Name Service Switch:: Configuring libc's name service switch.
|
||||||
* Initial RAM Disk:: Linux-Libre bootstrapping.
|
* Initial RAM Disk:: Linux-Libre bootstrapping.
|
||||||
* GRUB Configuration:: Configuring the boot loader.
|
* Bootloader Configuration:: Configuring the boot loader.
|
||||||
* Invoking guix system:: Instantiating a system configuration.
|
* Invoking guix system:: Instantiating a system configuration.
|
||||||
* Running GuixSD in a VM:: How to run GuixSD in a virtual machine.
|
* Running GuixSD in a VM:: How to run GuixSD in a virtual machine.
|
||||||
* Defining Services:: Adding new service definitions.
|
* Defining Services:: Adding new service definitions.
|
||||||
|
@ -7980,7 +7980,7 @@ system, should you ever need to.
|
||||||
Speaking of roll-back, each time you run @command{guix system
|
Speaking of roll-back, each time you run @command{guix system
|
||||||
reconfigure}, a new @dfn{generation} of the system is created---without
|
reconfigure}, a new @dfn{generation} of the system is created---without
|
||||||
modifying or deleting previous generations. Old system generations get
|
modifying or deleting previous generations. Old system generations get
|
||||||
an entry in the GRUB boot menu, allowing you to boot them in case
|
an entry in the bootloader boot menu, allowing you to boot them in case
|
||||||
something went wrong with the latest generation. Reassuring, no? The
|
something went wrong with the latest generation. Reassuring, no? The
|
||||||
@command{guix system list-generations} command lists the system
|
@command{guix system list-generations} command lists the system
|
||||||
generations available on disk. It is also possible to roll back the
|
generations available on disk. It is also possible to roll back the
|
||||||
|
@ -8036,7 +8036,7 @@ List of strings or gexps representing additional arguments to pass on
|
||||||
the command-line of the kernel---e.g., @code{("console=ttyS0")}.
|
the command-line of the kernel---e.g., @code{("console=ttyS0")}.
|
||||||
|
|
||||||
@item @code{bootloader}
|
@item @code{bootloader}
|
||||||
The system bootloader configuration object. @xref{GRUB Configuration}.
|
The system bootloader configuration object. @xref{Bootloader Configuration}.
|
||||||
|
|
||||||
@item @code{initrd} (default: @code{base-initrd})
|
@item @code{initrd} (default: @code{base-initrd})
|
||||||
@cindex initrd
|
@cindex initrd
|
||||||
|
@ -15711,32 +15711,52 @@ upon booting. All the derivations referenced by @var{exp} are
|
||||||
automatically copied to the initrd.
|
automatically copied to the initrd.
|
||||||
@end deffn
|
@end deffn
|
||||||
|
|
||||||
@node GRUB Configuration
|
@node Bootloader Configuration
|
||||||
@subsection GRUB Configuration
|
@subsection Bootloader Configuration
|
||||||
|
|
||||||
@cindex GRUB
|
@cindex bootloader
|
||||||
@cindex boot loader
|
@cindex boot loader
|
||||||
|
|
||||||
The operating system uses GNU@tie{}GRUB as its boot loader
|
The operating system supports multiple bootloaders. The bootloader is
|
||||||
(@pxref{Overview, overview of GRUB,, grub, GNU GRUB Manual}). It is
|
configured using @code{bootloader-configuration} declaration. All the
|
||||||
configured using a @code{grub-configuration} declaration. This data type
|
fields of this structure are bootloader agnostic except for one field,
|
||||||
is exported by the @code{(gnu system grub)} module and described below.
|
@code{bootloader} that indicates the bootloader to be configured and
|
||||||
|
installed.
|
||||||
|
|
||||||
@deftp {Data Type} grub-configuration
|
Some of the bootloaders do not honor every field of
|
||||||
The type of a GRUB configuration declaration.
|
@code{bootloader-configuration}. For instance, the extlinux
|
||||||
|
bootloader does not support themes and thus ignores the @code{theme}
|
||||||
|
field.
|
||||||
|
|
||||||
|
@deftp {Data Type} bootloader-configuration
|
||||||
|
The type of a bootloader configuration declaration.
|
||||||
|
|
||||||
@table @asis
|
@table @asis
|
||||||
|
|
||||||
|
@item @code{bootloader}
|
||||||
|
@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} and
|
||||||
|
@code{extlinux-bootloader} are supported. @code{grub-efi-bootloader},
|
||||||
|
allows to boot on modern systems using the @dfn{Unified Extensible
|
||||||
|
Firmware Interface} (UEFI).
|
||||||
|
|
||||||
|
Available bootloaders are described in @code{(gnu bootloader @dots{})}
|
||||||
|
modules.
|
||||||
|
|
||||||
@item @code{device}
|
@item @code{device}
|
||||||
This is a string denoting the boot device. It must be a device name
|
This is a string denoting the boot device. It must be a device name
|
||||||
understood by the @command{grub-install} command, such as
|
understood by the bootloader @command{installer} command, such as
|
||||||
@code{/dev/sda} or @code{(hd0)} (@pxref{Invoking grub-install,,, grub,
|
@code{/dev/sda} or @code{(hd0)} (for GRUB, @pxref{Invoking grub-install,,, grub,
|
||||||
GNU GRUB Manual}).
|
GNU GRUB Manual}).
|
||||||
|
|
||||||
@item @code{menu-entries} (default: @code{()})
|
@item @code{menu-entries} (default: @code{()})
|
||||||
A possibly empty list of @code{menu-entry} objects (see below), denoting
|
A possibly empty list of @code{menu-entry} objects (see below), denoting
|
||||||
entries to appear in the GRUB boot menu, in addition to the current
|
entries to appear in the bootloader menu, in addition to the current
|
||||||
system entry and the entry pointing to previous system generations.
|
system entry and the entry pointing to previous system generations.
|
||||||
|
generations.
|
||||||
|
|
||||||
@item @code{default-entry} (default: @code{0})
|
@item @code{default-entry} (default: @code{0})
|
||||||
The index of the default boot menu entry. Index 0 is for the entry of the
|
The index of the default boot menu entry. Index 0 is for the entry of the
|
||||||
|
@ -15746,42 +15766,37 @@ current system.
|
||||||
The number of seconds to wait for keyboard input before booting. Set to
|
The number of seconds to wait for keyboard input before booting. Set to
|
||||||
0 to boot immediately, and to -1 to wait indefinitely.
|
0 to boot immediately, and to -1 to wait indefinitely.
|
||||||
|
|
||||||
@item @code{theme} (default: @var{%default-theme})
|
@item @code{theme} (default: @var{#f})
|
||||||
The @code{grub-theme} object describing the theme to use.
|
The bootloader theme object describing the theme to use. If no theme
|
||||||
|
is provided, some bootloaders might use a default theme, that's true
|
||||||
@item @code{grub} (default: @code{grub})
|
for GRUB.
|
||||||
@cindex EFI, bootloader
|
|
||||||
@cindex UEFI, bootloader
|
|
||||||
@cindex BIOS, bootloader
|
|
||||||
The GRUB package to use. Currently either @code{grub}, for ``legacy''
|
|
||||||
x86 BIOS systems, or @code{grub-efi}, for modern systems using the
|
|
||||||
@dfn{Unified Extensible Firmware Interface} (UEFI).
|
|
||||||
|
|
||||||
@item @code{terminal-outputs} (default: @code{'gfxterm})
|
@item @code{terminal-outputs} (default: @code{'gfxterm})
|
||||||
The output terminals used for the GRUB boot menu, as a list of symbols.
|
The output terminals used for the bootloader boot menu, as a list of
|
||||||
These values are accepted: @code{console}, @code{serial},
|
symbols. GRUB accepts the values: @code{console}, @code{serial},
|
||||||
@code{serial_@{0-3@}}, @code{gfxterm}, @code{vga_text}, @code{mda_text},
|
@code{serial_@{0-3@}}, @code{gfxterm}, @code{vga_text},
|
||||||
@code{morse}, and @code{pkmodem}. This field corresponds to the GRUB
|
@code{mda_text}, @code{morse}, and @code{pkmodem}. This field
|
||||||
variable GRUB_TERMINAL_OUTPUT (@pxref{Simple configuration,,, grub,GNU
|
corresponds to the GRUB variable GRUB_TERMINAL_OUTPUT (@pxref{Simple
|
||||||
GRUB manual}).
|
configuration,,, grub,GNU GRUB manual}).
|
||||||
|
|
||||||
@item @code{terminal-inputs} (default: @code{'()})
|
@item @code{terminal-inputs} (default: @code{'()})
|
||||||
The input terminals used for the GRUB boot menu, as a list of symbols.
|
The input terminals used for the bootloader boot menu, as a list of
|
||||||
The default is the native platform terminal as determined by GRUB at
|
symbols. For GRUB, the default is the native platform terminal as
|
||||||
run-time. These values are accepted: @code{console}, @code{serial},
|
determined at run-time. GRUB accepts the values: @code{console},
|
||||||
@code{serial_@{0-3@}}, @code{at_keyboard}, and @code{usb_keyboard}.
|
@code{serial}, @code{serial_@{0-3@}}, @code{at_keyboard}, and
|
||||||
This field corresponds to the GRUB variable GRUB_TERMINAL_INPUT
|
@code{usb_keyboard}. This field corresponds to the GRUB variable
|
||||||
(@pxref{Simple configuration,,, grub,GNU GRUB manual}).
|
GRUB_TERMINAL_INPUT (@pxref{Simple configuration,,, grub,GNU GRUB
|
||||||
|
manual}).
|
||||||
|
|
||||||
@item @code{serial-unit} (default: @code{#f})
|
@item @code{serial-unit} (default: @code{#f})
|
||||||
The serial unit used by GRUB, as an integer from 0 to 3. The default
|
The serial unit used by the bootloader, as an integer from 0 to 3.
|
||||||
value is chosen by GRUB at run-time; currently GRUB chooses 0, which
|
For GRUB it is choosen at run-time; currently GRUB chooses 0, which
|
||||||
corresponds to COM1 (@pxref{Serial terminal,,, grub,GNU GRUB manual}).
|
corresponds to COM1 (@pxref{Serial terminal,,, grub,GNU GRUB manual}).
|
||||||
|
|
||||||
@item @code{serial-speed} (default: @code{#f})
|
@item @code{serial-speed} (default: @code{#f})
|
||||||
The speed of the serial interface, as an integer. The default value is
|
The speed of the serial interface, as an integer. For GRUB, the
|
||||||
chosen by GRUB at run-time; currently GRUB chooses 9600@tie{}bps
|
default value is chosen at run-time; currently GRUB chooses
|
||||||
(@pxref{Serial terminal,,, grub,GNU GRUB manual}).
|
9600@tie{}bps (@pxref{Serial terminal,,, grub,GNU GRUB manual}).
|
||||||
@end table
|
@end table
|
||||||
|
|
||||||
@end deftp
|
@end deftp
|
||||||
|
@ -15805,7 +15820,7 @@ along these lines:
|
||||||
Details below.
|
Details below.
|
||||||
|
|
||||||
@deftp {Data Type} menu-entry
|
@deftp {Data Type} menu-entry
|
||||||
The type of an entry in the GRUB boot menu.
|
The type of an entry in the bootloader menu.
|
||||||
|
|
||||||
@table @asis
|
@table @asis
|
||||||
|
|
||||||
|
@ -15819,9 +15834,9 @@ The Linux kernel image to boot, for example:
|
||||||
(file-append linux-libre "/bzImage")
|
(file-append linux-libre "/bzImage")
|
||||||
@end example
|
@end example
|
||||||
|
|
||||||
It is also possible to specify a device explicitly in the file path
|
For GRUB, it is also possible to specify a device explicitly in the
|
||||||
using GRUB's device naming convention (@pxref{Naming convention,,, grub,
|
file path using GRUB's device naming convention (@pxref{Naming
|
||||||
GNU GRUB manual}), for example:
|
convention,,, grub, GNU GRUB manual}), for example:
|
||||||
|
|
||||||
@example
|
@example
|
||||||
"(hd0,msdos1)/boot/vmlinuz"
|
"(hd0,msdos1)/boot/vmlinuz"
|
||||||
|
@ -15837,33 +15852,30 @@ The list of extra Linux kernel command-line arguments---e.g.,
|
||||||
@item @code{initrd}
|
@item @code{initrd}
|
||||||
A G-Expression or string denoting the file name of the initial RAM disk
|
A G-Expression or string denoting the file name of the initial RAM disk
|
||||||
to use (@pxref{G-Expressions}).
|
to use (@pxref{G-Expressions}).
|
||||||
|
|
||||||
@item @code{device} (default: @code{#f})
|
@item @code{device} (default: @code{#f})
|
||||||
The device where the kernel and initrd are to be found---i.e., the GRUB
|
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}).
|
@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
|
This may be a file system label (a string), a file system UUID (a
|
||||||
bytevector, @pxref{File Systems}), or @code{#f}, in which case GRUB will
|
bytevector, @pxref{File Systems}), or @code{#f}, in which case
|
||||||
search the device containing the file specified by the @code{linux}
|
the bootloader will search the device containing the file specified by
|
||||||
field (@pxref{search,,, grub, GNU GRUB manual}). It must @emph{not} be
|
the @code{linux} field (@pxref{search,,, grub, GNU GRUB manual}). It
|
||||||
an OS device name such as @file{/dev/sda1}.
|
must @emph{not} be an OS device name such as @file{/dev/sda1}.
|
||||||
|
|
||||||
@item @code{device-mount-point} (default: @code{"/"})
|
|
||||||
The mount point of the above device on the system. You probably do not
|
|
||||||
need to change the default value. GuixSD uses it to strip the prefix of
|
|
||||||
store file names for systems where @file{/gnu} or @file{/gnu/store} is
|
|
||||||
on a separate partition.
|
|
||||||
|
|
||||||
@end table
|
@end table
|
||||||
@end deftp
|
@end deftp
|
||||||
|
|
||||||
@c FIXME: Write documentation once it's stable.
|
@c FIXME: Write documentation once it's stable.
|
||||||
Themes are created using the @code{grub-theme} form, which is not
|
Fow now only GRUB has theme support. GRUB themes are created using
|
||||||
documented yet.
|
the @code{grub-theme} form, which is not documented yet.
|
||||||
|
|
||||||
@defvr {Scheme Variable} %default-theme
|
@defvr {Scheme Variable} %default-theme
|
||||||
This is the default GRUB theme used by the operating system, with a
|
This is the default GRUB theme used by the operating system if no
|
||||||
fancy background image displaying the GNU and Guix logos.
|
@code{theme} field is specified in @code{bootloader-configuration}
|
||||||
|
record.
|
||||||
|
|
||||||
|
It comes with a fancy background image displaying the GNU and Guix
|
||||||
|
logos.
|
||||||
@end defvr
|
@end defvr
|
||||||
|
|
||||||
|
|
||||||
|
@ -15903,9 +15915,10 @@ list-generations}). If that generation already exists, it will be
|
||||||
overwritten. This behavior mirrors that of @command{guix package}
|
overwritten. This behavior mirrors that of @command{guix package}
|
||||||
(@pxref{Invoking guix package}).
|
(@pxref{Invoking guix package}).
|
||||||
|
|
||||||
It also adds a GRUB menu entry for the new OS configuration, and moves
|
It also adds a bootloader menu entry for the new OS configuration,
|
||||||
entries for older configurations to a submenu---unless
|
---unless @option{--no-bootloader} is passed. For GRUB, it moves
|
||||||
@option{--no-bootloader} is passed.
|
entries for older configurations to a submenu, allowing you to choose
|
||||||
|
an older system generation at boot time should you need it.
|
||||||
|
|
||||||
@quotation Note
|
@quotation Note
|
||||||
@c The paragraph below refers to the problem discussed at
|
@c The paragraph below refers to the problem discussed at
|
||||||
|
@ -15919,11 +15932,16 @@ once @command{reconfigure} has completed.
|
||||||
@item switch-generation
|
@item switch-generation
|
||||||
@cindex generations
|
@cindex generations
|
||||||
Switch to an existing system generation. This action atomically
|
Switch to an existing system generation. This action atomically
|
||||||
switches the system profile to the specified system generation. It also
|
switches the system profile to the specified system generation. It
|
||||||
rearranges the system's existing GRUB menu entries. It makes the menu
|
also rearranges the system's existing bootloader menu entries. It
|
||||||
entry for the specified system generation the default, and it moves the
|
makes the menu entry for the specified system generation the default,
|
||||||
entries for the other generations to a submenu. The next time the
|
and it moves the entries for the other generatiors to a submenu, if
|
||||||
system boots, it will use the specified system generation.
|
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
|
The target generation can be specified explicitly by its generation
|
||||||
number. For example, the following invocation would switch to system
|
number. For example, the following invocation would switch to system
|
||||||
|
@ -15945,11 +15963,11 @@ guix system switch-generation -- -1
|
||||||
@end example
|
@end example
|
||||||
|
|
||||||
Currently, the effect of invoking this action is @emph{only} to switch
|
Currently, the effect of invoking this action is @emph{only} to switch
|
||||||
the system profile to an existing generation and rearrange the GRUB menu
|
the system profile to an existing generation and rearrange the
|
||||||
entries. To actually start using the target system generation, you must
|
bootloader menu entries. To actually start using the target system
|
||||||
reboot after running this action. In the future, it will be updated to
|
generation, you must reboot after running this action. In the future,
|
||||||
do the same things as @command{reconfigure}, like activating and
|
it will be updated to do the same things as @command{reconfigure},
|
||||||
deactivating services.
|
like activating and deactivating services.
|
||||||
|
|
||||||
This action will fail if the specified generation does not exist.
|
This action will fail if the specified generation does not exist.
|
||||||
|
|
||||||
|
@ -15984,8 +16002,9 @@ files, packages, and so on. It also creates other essential files
|
||||||
needed for the system to operate correctly---e.g., the @file{/etc},
|
needed for the system to operate correctly---e.g., the @file{/etc},
|
||||||
@file{/var}, and @file{/run} directories, and the @file{/bin/sh} file.
|
@file{/var}, and @file{/run} directories, and the @file{/bin/sh} file.
|
||||||
|
|
||||||
This command also installs GRUB on the device specified in
|
This command also installs bootloader on the device specified in
|
||||||
@file{my-os-config}, unless the @option{--no-bootloader} option was passed.
|
@file{my-os-config}, unless the @option{--no-bootloader} option was
|
||||||
|
passed.
|
||||||
|
|
||||||
@item vm
|
@item vm
|
||||||
@cindex virtual machine
|
@cindex virtual machine
|
||||||
|
@ -16125,7 +16144,7 @@ build users of the daemon (@pxref{Build Environment Setup}).
|
||||||
Once you have built, configured, re-configured, and re-re-configured
|
Once you have built, configured, re-configured, and re-re-configured
|
||||||
your GuixSD installation, you may find it useful to list the operating
|
your GuixSD installation, you may find it useful to list the operating
|
||||||
system generations available on disk---and that you can choose from the
|
system generations available on disk---and that you can choose from the
|
||||||
GRUB boot menu:
|
bootloader boot menu:
|
||||||
|
|
||||||
@table @code
|
@table @code
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue