Table of contents
Boot config files
A user has the option to make persistent modifications to the non-Qubes boot process by creating one or more of the following files:
file | description |
---|---|
kexec_menu.txt | contains multiple options for parameters to the kexec command |
kexec_hashes.txt | a sha256sum file from within the respective boot directory |
kexec_iso_add.txt | a sh variable to override the standard ISO kernel argument additions |
kexec_iso_remove.txt | a sh variable to override the standard ISO kernel argument removals |
kexec_default.$N.txt | specifies the default kexec parameters corresponding to the Nth menu option |
kexec_default_hashes.txt | a sha256sum file for the default entry kexec file parameters |
kexec_rollback.txt | a sha256sum of the TPM counter contents in the tmp directory |
kexec_key_devices.txt | contains a list of “device uuid” combos for all LUKS devices to unlock |
kexec_key_lvm.txt | contains the name of an LVM group to activate on boot |
These can be placed in any of the following locations:
location | description |
---|---|
/boot/ | used during internal HD boot |
/media/ | used during standard USB boot |
/media/kexec_iso/$ISO_FILENAME/ | used during USB boot from a particular ISO file |
These files are only used if there is an appropriate signature for them in kexec.sig
covering all kexec*.txt
in that location. This can be generated from the user interface from the Update checksums and sign all files
in /boot menu option, or manually from the recovery shell by running kexec-sign-config -p /boot/
, etc. These files are only copied by kexec-check-config
to /tmp/kexec/
if there is a valid signature. From there the boot routines reference only the configs in /tmp/kexec
.
Dynamic vs Persistent Boot Options
There are two ways for heads to boot Operating systems from /boot.
- Dynamic (no kexec_menu.txt)
- Persistent
kexec_menu.txt
is generated from GUI menu option Default boot
while /boot contents detached signed digest is verified as valid. If there is no persistent kexec_menu.txt
the boot directory will be searched for grub/syslinux-like configurations and it will be generated dynamically (for any of the HD/USB/USB-ISO locations). Creating a persistent kexec_menu.txt
can be useful to limit the options displayed or to make persistent alterations to xen or kernel params.
Persistent Boot Options
To customize the boot options and ignore the default OS boot configurations you may create a kexec_menu.txt
which has a simple layout of a single line per boot option:
description 1|elf|kernel /vmlinuz... |initrd /initramfs... |append ...
description 2|multiboot|kernel ... |module ... |module ...
description 3|xen|kernel /xen... |module /vmlinuz... | module /initramfs...
Here is a sample kexec_menu.txt
derived from grub.cfg:
Ubuntu|elf|kernel /vmlinuz-4.8.0-58-generic|initrd /initrd.img-4.8.0-58-generic|append root=/dev/mapper/ubuntu--vg-root ro quiet splash crashkernel=384M-:128M crashkernel=384M-:128M
Memory test (memtest86+, serial console 115200)|elf|kernel /memtest86+.bin|append console=ttyS0,115200n8
Qubes, with Xen hypervisor|multiboot|kernel /xen-4.6.5.gz placeholder |module /vmlinuz-4.4.67-13.pvops.qubes.x86_64 placeholder root=/dev/mapper/luks-UUID ro rd.qubes.hide_all_usb|module /initramfs-4.4.67-13.pvops.qubes.x86_64.img
Securing Persistent Boot Options
By default, no file hash checks are made for default boot since this was done during configuration. A non-default boot will fail when the file hashes don’t match the expected values.
require hash checks
If a user wishes to require that file hashes be checked for a succesful non-recovery boot, they may set the CONFIG_BOOT_REQ_HASH=y
in their respective Heads config file (/etc/config.user).
default boot
As as convenience mechanism, a user may select a boot option to always be used in the future, assuming that the boot parameters and file hashes have not changed. This can be done by running kexec-save-default
manually or directly from the boot menu. This works for any boot location (HD/USB/USB ISO) but does modify the respective /boot/
or /media/
filesystems.
In the case of dynamicly derived boot options from grub.cfg
(i.e. no persistent kexec_menu.txt) an entry index is cached so that the boot will fail when there is a change to the underlying grub parameters. This will require the user to resign/revalidate the settings. This is useful to detect changes to the primary kernel/initramfs (for example in the Qubes case when the primary entry is first).
multiboot
Note that currently, any multiboot entry is interpreted as a Xen-variant and kexec-boot
overrides the arguments to the multiboot kernel with custom arguments. A user can manually specify multiboot
entries to override the default behavior by creating a custom kexec_menu.txt
.
rollback counter
If a user wishes to require that a TPM counter be set for rollback prevention, they may set the CONFIG_BOOT_REQ_ROLLBACK=y
in their respective Heads config file. When this is true, standard boot will only succeed in these two cases:
- Booting from an verified ISO
- Booting from a mount point that has a valid
kexec_rollback.txt
in its parameter directory
The simplest way to achieve this is to set a default boot option as this updates the rollback counter by default.