Add documentation for all GRUB modules contained in the source code tree.
When possible, cross-references to additional detail on commands was added
from their corresponding module documentation. In addition, documentation
for the file command was added.
Signed-off-by: Andrew Hamilton <adhamilt@gmail.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
The fdtdump command allows dumping arbitrary device tree properties
and saving them to a variable similar to the smbios command.
This is useful in scripts where further actions such as selecting
a kernel or loading another device tree depend on the compatible
or model values of the device tree provided by the firmware.
For now only the root level properties of the dtb are exposed.
Signed-off-by: Tobias Heider <tobias.heider@canonical.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
Add functionality to disable command line interface access and editing of GRUB
menu entries if GRUB image is built with --disable-cli.
Signed-off-by: Alec Brown <alec.r.brown@oracle.com>
Reviewed-by: Vladimir Serbinenko <phcoder@gmail.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
The EROFS [1] is a lightweight read-only filesystem designed for performance
which has already been shipped in most Linux distributions as well as widely
used in several scenarios, such as Android system partitions, container
images and rootfs for embedded devices.
This patch brings in the EROFS uncompressed support. Now, it's possible to
boot directly through GRUB with an EROFS rootfs.
Support for the EROFS compressed files will be added later.
[1] https://erofs.docs.kernel.org
Signed-off-by: Yifan Zhao <zhaoyifan@sjtu.edu.cn>
Tested-by: Daniel Axtens <dja@axtens.net>
Signed-off-by: Gao Xiang <hsiangkao@linux.alibaba.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
Give the user a chance to re-enter their cryptodisk passphrase after a typo,
rather than immediately failing (and likely dumping them into a GRUB shell).
By default, we allow 3 tries before giving up. A value in the
cryptodisk_passphrase_tries environment variable will override this default.
The user can give up early by entering an empty passphrase, just as they
could before this patch.
Signed-off-by: Forest <forestix@nom.one>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
Improve the documentation of the bli module and explain in more detail what
it does. Make clear that GPT formatted drives are expected and other
partition formats are ignored. Also reorder and reword this section a bit.
Signed-off-by: Oliver Steffen <osteffen@redhat.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
It has been reported that makeinfo version 4.13a complains and returns
error when menus for chapter structuring commands are not present. It
is also known that newer makeinfos, such as version 6.7, will create
default menus when needed. Since the menu will be created regardless,
explicitly create it to support older makeinfo versions. This also
enables building to be successful when an older makeinfo is installed
because in that case info files are attempted to be generated with the
"all" target.
Reported-by: Olaf Hering <olaf@aepfle.de>
Signed-off-by: Glenn Washburn <development@efficientek.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
Tested-by: Olaf Hering <olaf@aepfle.de>
The @xref command is meant to be used at the beginning of a sentence
because its expansion creates a "See " prefix on all output formats, and
on older makeinfo versions is strict about enforcing a "." or "," after
the command. The @ref command has no such restriction and is just the
link, which allows more control over output. This also fixes an issue
where there was a repeated "see" in the output.
Reported-by: Olaf Hering <olaf@aepfle.de>
Signed-off-by: Glenn Washburn <development@efficientek.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
Tested-by: Olaf Hering <olaf@aepfle.de>
A list of improvements:
* Remove reference to "initial ramdisk" and replace with "initrd". This
then covers the case of ramdisk and ramfs, which is the usual method
with kernels 2.6 and newer.
* Add sentence with URL to initrd documentation Linux kernel.
* Add a section documenting how to have the initrd command generate
a new-style initrd via a specially crafted argument and include an example.
* Update initrd16 to refer to the initrd section and make note that
initrd16 is only on the pc platform.
Signed-off-by: Glenn Washburn <development@efficientek.com>
Reviewed-by: Oskari Pirhonen <xxc3ncoredxx@gmail.com>
Reviewed-by: Paul Menzel <pmenzel@molgen.mpg.de>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
The cat command should not be used to print binary data because it can
show bytes not in the binary data and not show bytes that are in the data,
which can lead to confusion. This happens because cat does some processing
of the data stream, namely trying to decode substrings as UTF-8.
Signed-off-by: Glenn Washburn <development@efficientek.com>
Reviewed-by: Oskari Pirhonen <xxc3ncoredxx@gmail.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
Also reword a prior sentence to be more clear.
Fixes: 5a3d2b4742df (docs: Add debugging chapter to development documentation)
Signed-off-by: Glenn Washburn <development@efficientek.com>
Reviewed-by: Oskari Pirhonen <xxc3ncoredxx@gmail.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
When referring to initrd16 the link for initrd16 should be used, not a link
for initrd. Also, correct the spelling of additionally and add a comma after
it to correct its grammatical usage.
Signed-off-by: Glenn Washburn <development@efficientek.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
Small set of wording and grammatical edits which did not make it in time
for the original review of the chapter.
Signed-off-by: Oskari Pirhonen <xxc3ncoredxx@gmail.com>
Reviewed-by: Glenn Washburn <development@efficientek.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
Currently booting the system is prevented when call to EFI firmware
hash_log_extend_event() returns unknown error. Solve this by following
convention used in commit a4356538d (commands/tpm: Don't propagate
measurement failures to the verifiers layer).
Let the system to be bootable by default when unknown TPM error is
encountered. Check environment variable tpm_fail_fatal to fallback to
previous behaviour.
Signed-off-by: Michał Grzelak <mchl.grzlk@gmail.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
Debugging GRUB can be tricky and require arcane knowledge. This will
help those unfamiliar with the process to get started debugging GRUB
with less effort.
Signed-off-by: Glenn Washburn <development@efficientek.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
EFI firmware determines where to load the GRUB EFI at runtime, and so the
addresses of debug symbols are not known ahead of time. There is a command
defined in the gdb_grub script which will load the debug symbols at the
appropriate addresses, if given the application load address for GRUB.
So add a command named "gdbinfo" to allow the user to print this GDB command
string with the application load address on-demand. For the outputted GDB
command to have any effect when entered into a GDB session, GDB should have
been started with the script as an argument to the -x option or sourced into
an active GDB session before running the outputted command.
Documentation for the gdbinfo command is also added.
Co-developed-by: Peter Jones <pjones@redhat.com>
Signed-off-by: Peter Jones <pjones@redhat.com>
Signed-off-by: Glenn Washburn <development@efficientek.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
Extra arguments given to chainloader on EFI platforms will be sent to
the chainloaded application. Also, minor edit in the chainloading section
to note that chainloading can be a jump via the firmware and not
necessarily in real mode (which does not exist on some architectures).
Signed-off-by: Glenn Washburn <development@efficientek.com>
Reviewed-by: Ard Biesheuvel <ardb@kernel.org>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
Add a new module named bli. It implements a small but quite useful part
of the Boot Loader Interface [0]. This interface uses EFI variables for
communication between the boot loader and the operating system.
When loaded, this module sets two EFI variables under the vendor GUID
4a67b082-0a4c-41cf-b6c7-440b29bb8c4f:
- LoaderInfo: contains GRUB + <version number>.
This allows the running operating system to identify the boot loader
used during boot.
- LoaderDevicePartUUID: contains the partition UUID of the EFI System
Partition (ESP). This is used by systemd-gpt-auto-generator [1] to
find the root partitions (and others too), via partition type IDs [2].
This module is available on EFI platforms only. The bli module relies on
the part_gpt module which has to be loaded beforehand to make the GPT
partitions discoverable.
Update the documentation, add a new chapter "Modules" and describe the
bli module there.
[0] https://systemd.io/BOOT_LOADER_INTERFACE/
[1] https://www.freedesktop.org/software/systemd/man/systemd-gpt-auto-generator.html
[2] https://uapi-group.org/specifications/specs/discoverable_partitions_specification/
Signed-off-by: Oliver Steffen <osteffen@redhat.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
Reword some section headings, remove "The List of" from titles. While
grammatically correct, this phrase can be omitted to increase
readability, especially in the table of contents.
Signed-off-by: Oliver Steffen <osteffen@redhat.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
Loosely based on early_pci_serial_init() from Linux, allow GRUB to make
use of PCI serial devices.
Specifically, my Alderlake NUC exposes the Intel AMT SoL UART as a PCI
enumerated device but doesn't include it in the EFI tables.
Tested and confirmed working on a "Lenovo P360 Tiny" with Intel AMT
enabled. This specific machine has (from lspci -vv):
00:16.3 Serial controller: Intel Corporation Device 7aeb (rev 11) (prog-if 02 [16550])
DeviceName: Onboard - Other
Subsystem: Lenovo Device 330e
Control: I/O+ Mem+ BusMaster- SpecCycle- MemWINV- VGASnoop- ParErr- Stepping- SERR- FastB2B- DisINTx-
Status: Cap+ 66MHz+ UDF- FastB2B+ ParErr- DEVSEL=fast >TAbort- <TAbort- <MAbort- >SERR- <PERR- INTx-
Interrupt: pin D routed to IRQ 19
Region 0: I/O ports at 40a0 [size=8]
Region 1: Memory at b4224000 (32-bit, non-prefetchable) [size=4K]
Capabilities: [40] MSI: Enable- Count=1/1 Maskable- 64bit+
Address: 0000000000000000 Data: 0000
Capabilities: [50] Power Management version 3
Flags: PMEClk- DSI+ D1- D2- AuxCurrent=0mA PME(D0-,D1-,D2-,D3hot-,D3cold-)
Status: D0 NoSoftRst+ PME-Enable- DSel=0 DScale=0 PME-
Kernel driver in use: serial
From which the following config (/etc/default/grub) gets a working
serial setup:
GRUB_CMDLINE_LINUX="console=tty0 earlyprintk=pciserial,00:16.3,115200 console=ttyS0,115200"
GRUB_SERIAL_COMMAND="serial --port=0x40a0 --speed=115200"
GRUB_TERMINAL="serial console"
Documentation is added to note that serial devices found on the PCI bus will
be exposed as "pci,XX:XX.X" and how to find serial terminal logical names.
Also, some minor documentation improvements were added.
This can be tested in QEMU by adding a pci-serial device, e.g. using the option
"-device pci-serial".
Signed-off-by: Peter Zijlstra (Intel) <peterz@infradead.org>
Tested-by: Glenn Washburn <development@efficientek.com>
Signed-off-by: Glenn Washburn <development@efficientek.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
The menu entry commands now have their own section. Change the wording in
the section that they were in to reflect this.
Signed-off-by: Glenn Washburn <development@efficientek.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
Allow specifying port numbers for http and tftp paths and allow IPv6
addresses to be recognized with brackets around them, which is required
to specify a port number.
Co-authored-by: Aaron Miller <aaronmiller@fb.com>
Signed-off-by: Aaron Miller <aaronmiller@fb.com>
Co-authored-by: Peter Jones <pjones@redhat.com>
Signed-off-by: Peter Jones <pjones@redhat.com>
Signed-off-by: Robbie Harwood <rharwood@redhat.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
The notation introduced in ac8a37dda (net/http: Allow use of non-standard
TCP/IP ports) contradicts that used in downstream distributions including
Fedora, RHEL, Debian, Ubuntu, and others. Revert it and apply the downstream
notation which was originally proposed to the GRUB in 2016.
This reverts commit ac8a37dda (net/http: Allow use of non-standard TCP/IP ports).
Signed-off-by: Robbie Harwood <rharwood@redhat.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
Add support for trusted boot using a vTPM 2.0 on the IBM IEEE1275
PowerPC platform. With this patch grub now measures text and binary data
into the TPM's PCRs 8 and 9 in the same way as the x86_64 platform
does.
This patch requires Daniel Axtens's patches for claiming more memory.
Note: The tpm_init() function cannot be called from GRUB_MOD_INIT() since
it does not find the device nodes upon module initialization and
therefore the call to tpm_init() must be deferred to grub_tpm_measure().
For vTPM support to work on PowerVM, system driver levels 1010.30
or 1020.00 are required.
Note: Previous versions of firmware levels with the 2hash-ext-log
API call have a bug that, once this API call is invoked, has the
effect of disabling the vTPM driver under Linux causing an error
message to be displayed in the Linux kernel log. Those users will
have to update their machines to the firmware levels mentioned
above.
Cc: Eric Snowberg <eric.snowberg@oracle.com>
Signed-off-by: Stefan Berger <stefanb@linux.ibm.com>
Signed-off-by: Daniel Axtens <dja@axtens.net>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
Tested-by: Nageswara R Sastry <rnsastry@linux.ibm.com>
Reviewed-by: Robbie Harwood <rharwood@redhat.com>
On powerpc-ieee1275, we are running out of memory trying to verify
anything. This is because:
- we have to load an entire file into memory to verify it. This is
difficult to change with appended signatures.
- We only have 32MB of heap.
- Distro kernels are now often around 30MB.
So we want to be able to claim more memory from OpenFirmware for our heap
at runtime.
There are some complications:
- The grub mm code isn't the only thing that will make claims on
memory from OpenFirmware:
* PFW/SLOF will have claimed some for their own use.
* The ieee1275 loader will try to find other bits of memory that we
haven't claimed to place the kernel and initrd when we go to boot.
* Once we load Linux, it will also try to claim memory. It claims
memory without any reference to /memory/available, it just starts
at min(top of RMO, 768MB) and works down. So we need to avoid this
area. See arch/powerpc/kernel/prom_init.c as of v5.11.
- The smallest amount of memory a ppc64 KVM guest can have is 256MB.
It doesn't work with distro kernels but can work with custom kernels.
We should maintain support for that. (ppc32 can boot with even less,
and we shouldn't break that either.)
- Even if a VM has more memory, the memory OpenFirmware makes available
as Real Memory Area can be restricted. Even with our CAS work, an LPAR
on a PowerVM box is likely to have only 512MB available to OpenFirmware
even if it has many gigabytes of memory allocated.
What should we do?
We don't know in advance how big the kernel and initrd are going to be,
which makes figuring out how much memory we can take a bit tricky.
To figure out how much memory we should leave unused, I looked at:
- an Ubuntu 20.04.1 ppc64le pseries KVM guest:
vmlinux: ~30MB
initrd: ~50MB
- a RHEL8.2 ppc64le pseries KVM guest:
vmlinux: ~30MB
initrd: ~30MB
So to give us a little wriggle room, I think we want to leave at least
128MB for the loader to put vmlinux and initrd in memory and leave Linux
with space to satisfy its early allocations.
Allow other space to be allocated at runtime.
Tested-by: Stefan Berger <stefanb@linux.ibm.com>
Signed-off-by: Daniel Axtens <dja@axtens.net>
Tested-by: Nageswara R Sastry <rnsastry@linux.ibm.com>
Reviewed-by: Robbie Harwood <rharwood@redhat.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
This adds the ability to explicitly add an MMIO based serial port
via the "serial" command. The syntax is:
serial --port=mmio,<hex_address>{.b,.w,.l,.q}
Signed-off-by: Benjamin Herrenschmidt <benh@kernel.crashing.org>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
"serial auto" is now equivalent to just "serial" and will use the
SPCR to discover the port if present, otherwise defaults to "com0"
as before.
This allows to support MMIO ports specified by ACPI which is needed
on AWS EC2 "metal" instances, and will enable GRUB to pickup the
port configuration specified by ACPI in other cases.
Signed-off-by: Benjamin Herrenschmidt <benh@kernel.crashing.org>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
This allows the cmp command to be used in GRUB scripts to conditionally
run commands based on whether two files are the same.
The command is now quiet by default and the -v switch can be given to enable
verbose mode, the previous behavior.
Update documentation accordingly.
Suggested-by: Li Gen <ligenlive@gmail.com>
Signed-off-by: Glenn Washburn <development@efficientek.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
This was fixed here: 3cf2e848bc (disk/cryptodisk: Allows UUIDs to be compared
in a dash-insensitive manner).
Signed-off-by: Glenn Washburn <development@efficientek.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
This patch adds support for plain encryption mode, plain dm-crypt, via
new module/command named "plainmount".
Signed-off-by: Maxim Fomin <maxim@fomin.one>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
Reviewed-by: Glenn Washburn <development@efficientek.com>
Currently if an EFI firmware fails to do a TPM measurement for a file,
the error will be propagated to the verifiers framework which will
prevent it to be opened. This mean that buggy firmwares will lead to
the system not booting because files won't be allowed to be loaded. But
a failure to do a TPM measurement isn't expected to be a fatal error
that causes the system to be unbootable.
To avoid this, don't return errors from .write and .verify_string
callbacks and just print a debug message in the case of a TPM
measurement failure. Add an environment variable, tpm_fail_fatal, to
restore the previous behavior.
Also-authored-by: Javier Martinez Canillas <javierm@redhat.com>
Signed-off-by: Javier Martinez Canillas <javierm@redhat.com>
Signed-off-by: Robbie Harwood <rharwood@redhat.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
The GRUB emulator is used as a debugging utility but it could also be
used as a user-space bootloader if there is support to boot an operating
system.
The Linux kernel is already able to (re)boot another kernel via the
kexec boot mechanism. So the grub-emu tool could rely on this feature
and have linux and initrd commands that are used to pass a kernel,
initramfs image and command line parameters to kexec for booting
a selected menu entry.
By default the systemctl kexec option is used so systemd can shutdown
all of the running services before doing a reboot using kexec. But if
this is not present, it can fall back to executing the kexec user-space
tool directly. The ability to force a kexec-reboot when systemctl kexec
fails must only be used in controlled environments to avoid possible
filesystem corruption and data loss.
Signed-off-by: Raymund Will <rw@suse.com>
Signed-off-by: John Jolly <jjolly@suse.com>
Signed-off-by: Javier Martinez Canillas <javierm@redhat.com>
Signed-off-by: Robbie Harwood <rharwood@redhat.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
A user may wish to use an image that is not sorted as the "latest"
version as the top-level entry. For example, in Arch Linux, if a user
has the LTS and regular kernels installed, "/boot/vmlinuz-linux-lts"
gets sorted as the "latest" compared to "/boot/vmlinuz-linux", meaning
the LTS kernel becomes the top-level entry. However, a user may wish to
use the regular kernel as the top-level default with the LTS only
existing as a backup.
This need can be seen in Arch Linux's AUR with two user-submitted
packages[0][1] providing an update hook which patches /etc/grub.d/10_linux
to move the desired kernel to the top-level. This patch serves to solve
this in a more generic way.
Introduce the GRUB_TOP_LEVEL, GRUB_TOP_LEVEL_XEN and GRUB_TOP_LEVEL_OS_PROBER
variables to allow users to specify the top-level entry.
Create grub_move_to_front() as a helper function which moves entries to
the front of a list. This function does the heavy lifting of moving
the menu entry to the front in each script.
In 10_netbsd, since there isn't an explicit list variable, extract the
items that are being iterated through into a list so that we can
optionally apply grub_move_to_front() to the list before the loop.
[0]: https://aur.archlinux.org/packages/grub-linux-default-hook
[1]: https://aur.archlinux.org/packages/grub-linux-rt-default-hook
Signed-off-by: Denton Liu <liu.denton@gmail.com>
Reviewed-by: Oskari Pirhonen <xxc3ncoredxx@gmail.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
In grub-core/video/readers/jpeg.c, the height and width of a JPEG image don't
have an upper limit for how big the JPEG image can be. In Coverity, this is
getting flagged as an untrusted loop bound. This issue can also seen in PNG and
TGA format images as well but Coverity isn't flagging it. To prevent this, the
constant IMAGE_HW_MAX_PX is being added to include/grub/bitmap.h, which has
a value of 16384, to act as an artificial limit and restrict the height and
width of images. This value was picked as it is double the current max
resolution size, which is 8K.
Fixes: CID 292450
Signed-off-by: Alec Brown <alec.r.brown@oracle.com>
Reviewed-by: Darren Kenny <darren.kenny@oracle.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
This is useful on cloud instances with remote serial ports as it can be
difficult to connect "fast enough" to get the initial menu display
Signed-off-by: Benjamin Herrenschmidt <benh@kernel.crashing.org>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
A new option is added to the loopback command, -D or --decompress, which
when specified transparently decompresses the backing file. This allows
compressed images to be used as if they were uncompressed.
Add documentation to support this change.
Suggested-by: Li Gen <ligenlive@gmail.com>
Signed-off-by: Glenn Washburn <development@efficientek.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
This is trivial, but it might save some time to beginners.
Signed-off-by: Andrea G. Monaco <andrea.monaco@autistici.org>
Reviewed-by: Glenn Washburn <development@efficientek.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
This command is meant to behave similarly to the "mode" command of the EFI
Shell application. In addition to allowing mode selection by giving the
number of columns and rows as arguments, the command allows specifying the
mode number to select the mode. Also supported are the arguments "min" and
"max", which set the mode to the minimum and maximum mode respectively as
calculated by the columns * rows of that mode.
Signed-off-by: Glenn Washburn <development@efficientek.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
Document the variables net_<interface>_clientid, net_<interface>_clientuuid,
lockdown, and shim_lock in the list of special environment variables.
Signed-off-by: Glenn Washburn <development@efficientek.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
The section is an itemized list of commands that are not listed else where
in the command sections.
Signed-off-by: Glenn Washburn <development@efficientek.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
Move loader commands documented in the general commands list into the
loader command section.
Signed-off-by: Glenn Washburn <development@efficientek.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
