From fc22b3d6507c6745911b9dfcc68f1e665ae13dbc Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Mon, 15 Apr 2024 21:43:11 +0200 Subject: Adding upstream version 4.22.0. Signed-off-by: Daniel Baumann --- upstream/archlinux/man5/loader.conf.5 | 427 ++++++++++++++++++++++++++++++++++ 1 file changed, 427 insertions(+) create mode 100644 upstream/archlinux/man5/loader.conf.5 (limited to 'upstream/archlinux/man5/loader.conf.5') diff --git a/upstream/archlinux/man5/loader.conf.5 b/upstream/archlinux/man5/loader.conf.5 new file mode 100644 index 00000000..7272f7c5 --- /dev/null +++ b/upstream/archlinux/man5/loader.conf.5 @@ -0,0 +1,427 @@ +'\" t +.TH "LOADER\&.CONF" "5" "" "systemd 255" "loader.conf" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +loader.conf \- Configuration file for systemd\-boot +.SH "SYNOPSIS" +.PP +\fIESP\fR/loader/loader\&.conf, +\fIESP\fR/loader/entries/*\&.conf +\fIXBOOTLDR\fR/loader/entries/*\&.conf +.SH "DESCRIPTION" +.PP +\fBsystemd-boot\fR(7) +will read +\fIESP\fR/loader/loader\&.conf, and any files with the +"\&.conf" +extension under +\fIESP\fR/loader/entries/ +on the EFI system partition (ESP), and +\fIXBOOTLDR\fR/loader/entries/ +on the extended boot loader partition (XBOOTLDR) as defined by +\m[blue]\fBBoot Loader Specification\fR\m[]\&\s-2\u[1]\d\s+2\&. +.PP +Each of these configuration files must consist of series of newline (i\&.e\&. ASCII code 10) separated lines, each consisting of an option name, followed by whitespace, and the option value\&. +"#" +may be used to start a comment line\&. Empty and comment lines are ignored\&. The files use UTF\-8 encoding\&. +.PP +Boolean arguments may be written as +"yes"/"y"/"true"/"t"/"on"/"1" +or +"no"/"n"/"false"/"f"/"off"/"0"\&. +.SH "OPTIONS" +.PP +The configuration options supported by +\fIESP\fR/loader/entries/*\&.conf +and +\fIXBOOTLDR\fR/loader/entries/*\&.conf +files are defined as part of the +\m[blue]\fBBoot Loader Specification\fR\m[]\&\s-2\u[1]\d\s+2\&. +.PP +The following configuration are supported by the +loader\&.conf +configuration file: +.PP +default +.RS 4 +A glob pattern to select the default entry\&. The default entry may be changed in the boot menu itself, in which case the name of the selected entry will be stored as an EFI variable, overriding this option\&. +.sp +If set to +"@saved" +the chosen entry will be saved as an EFI variable on every boot and automatically selected the next time the boot loader starts\&. +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.B Table\ \&1.\ \&Automatically detected entries will use the following names: +.TS +allbox tab(:); +lB lB. +T{ +Name +T}:T{ +Description +T} +.T& +l l +l l +l l +l l +l l +l l +l l. +T{ +auto\-efi\-default +T}:T{ +EFI Default Loader +T} +T{ +auto\-efi\-shell +T}:T{ +EFI Shell +T} +T{ +auto\-osx +T}:T{ +macOS +T} +T{ +auto\-poweroff +T}:T{ +Power Off The System +T} +T{ +auto\-reboot +T}:T{ +Reboot The System +T} +T{ +auto\-reboot\-to\-firmware\-setup +T}:T{ +Reboot Into Firmware Interface +T} +T{ +auto\-windows +T}:T{ +Windows Boot Manager +T} +.TE +.sp 1 +Supported glob wildcard patterns are +"?", +"*", and +"[\&...]" +(including ranges)\&. Note that these patterns use the same syntax as +\fBglob\fR(7), but do not support all features\&. In particular, set negation and named character classes are not supported\&. The matching is done case\-insensitively on the entry ID (as shown by +\fBbootctl list\fR)\&. +.sp +Added in version 239\&. +.RE +.PP +timeout +.RS 4 +How long the boot menu should be shown before the default entry is booted, in seconds\&. This may be changed in the boot menu itself and will be stored as an EFI variable in that case, overriding this option\&. +.sp +If set to +"menu\-disabled" +or +"menu\-hidden" +or +"0" +(the default), no menu is shown and the default entry will be booted immediately\&. Unless +"menu\-disabled" +is used, the menu can be shown by pressing and holding a key before systemd\-boot is launched\&. Setting this to +"menu\-force" +disables the timeout while always showing the menu\&. +.sp +Added in version 239\&. +.RE +.PP +console\-mode +.RS 4 +This option configures the resolution of the console\&. This may be changed in the boot menu itself and will be stored as an EFI variable in that case, overriding this option\&. +.sp +Takes a number or one of the special values listed below\&. The following values may be used: +.PP +0 +.RS 4 +Standard UEFI 80x25 mode +.sp +Added in version 239\&. +.RE +.PP +1 +.RS 4 +80x50 mode, not supported by all devices +.sp +Added in version 239\&. +.RE +.PP +2 +.RS 4 +the first non\-standard mode provided by the device firmware, if any +.sp +Added in version 239\&. +.RE +.PP +auto +.RS 4 +Pick a suitable mode automatically using heuristics +.sp +Added in version 239\&. +.RE +.PP +max +.RS 4 +Pick the highest\-numbered available mode +.sp +Added in version 239\&. +.RE +.PP +keep +.RS 4 +Keep the mode selected by firmware (the default) +.sp +Added in version 239\&. +.RE +.sp +Added in version 239\&. +.RE +.PP +editor +.RS 4 +Takes a boolean argument\&. Enable (the default) or disable the editor\&. The editor should be disabled if the machine can be accessed by unauthorized persons\&. +.sp +Added in version 239\&. +.RE +.PP +auto\-entries +.RS 4 +Takes a boolean argument\&. Enable (the default) or disable entries for other boot entries found on the boot partition\&. In particular, this may be useful when loader entries are created to show replacement descriptions for those entries\&. +.sp +Added in version 239\&. +.RE +.PP +auto\-firmware +.RS 4 +A boolean controlling the presence of the +"Reboot Into Firmware Interface" +entry (enabled by default)\&. If this is disabled, the firmware interface may still be reached by using the +f +key\&. +.sp +Added in version 239\&. +.RE +.PP +beep +.RS 4 +Takes a boolean argument\&. If timeout enabled beep every second, otherwise beep n times when n\-th entry in boot menu is selected (default disabled)\&. Currently, only x86 is supported, where it uses the PC speaker\&. +.sp +Added in version 251\&. +.RE +.PP +secure\-boot\-enroll +.RS 4 +Danger: this feature might soft\-brick your device if used improperly\&. +.sp +Controls enrollment of secure boot keys found on the ESP if the system is in setup mode: +.PP +\fBoff\fR +.RS 4 +No action is taken\&. +.sp +Added in version 253\&. +.RE +.PP +\fBmanual\fR +.RS 4 +Boot entries for found secure boot keys are created that allow manual enrollment\&. +.sp +Added in version 253\&. +.RE +.PP +\fBif\-safe\fR +.RS 4 +Same behavior as +\fBmanual\fR, but will try to automatically enroll the key +"auto" +if it is considered to be safe\&. Currently, this is only the case if the system is running inside a virtual machine\&. +.sp +Added in version 253\&. +.RE +.PP +\fBforce\fR +.RS 4 +Always enroll the +"auto" +key if found\&. Note that a warning message with a timeout will still be shown if this operation is unknown to be safe\&. +.sp +Added in version 253\&. +.RE +.sp +The different sets of variables can be set up under +/loader/keys/\fINAME\fR +where +\fINAME\fR +is the name that is going to be used as the name of the entry\&. This allows one to ship multiple sets of Secure Boot variables and choose which one to enroll at runtime\&. +.sp +Supported Secure Boot variables are one database for authorized images, one for the key exchange key (KEK) and one for the platform key (PK)\&. For more information, refer to the +\m[blue]\fBUEFI specification\fR\m[]\&\s-2\u[2]\d\s+2, under Secure Boot and Driver Signing\&. Another resource that describe the interplay of the different variables is the +\m[blue]\fBEDK2 documentation\fR\m[]\&\s-2\u[3]\d\s+2\&. +.sp +A complete set of UEFI variable includes +db\&.auth, +KEK\&.auth +and +PK\&.auth\&. Note that these files need to be authenticated UEFI variables\&. See below for an example of how to generate them from regular X\&.509 keys\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +uuid=$(systemd\-id128 new \-\-uuid) +for key in PK KEK db; do + openssl req \-new \-x509 \-subj "/CN=${key}/" \-keyout "${key}\&.key" \-out "${key}\&.pem" + openssl x509 \-outform DER \-in "${key}\&.pem" \-out "${key}\&.der" + sbsiglist \-\-owner "${uuid}" \-\-type x509 \-\-output "${key}\&.esl" "${key}\&.der" +done + +# See also: \m[blue]\fBWindows Secure Boot Key Creation and Management Guidance\fR\m[]\&\s-2\u[4]\d\s+2 +curl \-\-location \e + "https://go\&.microsoft\&.com/fwlink/p/?linkid=321192" \-o ms\-db\-2011\&.der \e + "https://go\&.microsoft\&.com/fwlink/p/?linkid=321185" \-o ms\-kek\-2011\&.der \e + "https://go\&.microsoft\&.com/fwlink/p/?linkid=321194" \-o ms\-uefi\-db\-2011\&.der \e + "https://go\&.microsoft\&.com/fwlink/p/?linkid=2239776" \-o ms\-db\-2023\&.der \e + "https://go\&.microsoft\&.com/fwlink/p/?linkid=2239775" \-o ms\-kek\-2023\&.der \e + "https://go\&.microsoft\&.com/fwlink/p/?linkid=2239872" \-o ms\-uefi\-db\-2023\&.der +sha1sum \-c <>db\&.esl + +# Optionally add Microsoft UEFI certificates for firmware drivers / option ROMs and third\-party +# boot loaders (including shim)\&. This is highly recommended on real hardware as not including this +# may soft\-brick your device (see next paragraph)\&. +cat ms\-uefi\-*\&.esl >>db\&.esl + +# Optionally add Microsoft KEK certificates\&. Recommended if either of the Microsoft keys is used as +# the official UEFI revocation database is signed with this key\&. The revocation database can be +# updated with \fBfwupdmgr\fR(1)\&. +cat ms\-kek\-*\&.esl >>KEK\&.esl + +attr=NON_VOLATILE,RUNTIME_ACCESS,BOOTSERVICE_ACCESS,TIME_BASED_AUTHENTICATED_WRITE_ACCESS +sbvarsign \-\-attr "${attr}" \-\-key PK\&.key \-\-cert PK\&.pem \-\-output PK\&.auth PK PK\&.esl +sbvarsign \-\-attr "${attr}" \-\-key PK\&.key \-\-cert PK\&.pem \-\-output KEK\&.auth KEK KEK\&.esl +sbvarsign \-\-attr "${attr}" \-\-key KEK\&.key \-\-cert KEK\&.pem \-\-output db\&.auth db db\&.esl + +.fi +.if n \{\ +.RE +.\} +.sp +This feature is considered dangerous because even if all the required files are signed with the keys being loaded, some files necessary for the system to function properly still won\*(Aqt be\&. This is especially the case with Option ROMs (e\&.g\&. for storage controllers or graphics cards)\&. See +\m[blue]\fBSecure Boot and Option ROMs\fR\m[]\&\s-2\u[5]\d\s+2 +for more details\&. +.sp +Added in version 252\&. +.RE +.PP +reboot\-for\-bitlocker +.RS 4 +Caveat: This feature is experimental, and is likely to be changed (or removed in its current form) in a future version of systemd\&. +.sp +Work around BitLocker requiring a recovery key when the boot loader was updated (disabled by default)\&. +.sp +Try to detect BitLocker encrypted drives along with an active TPM\&. If both are found and Windows Boot Manager is selected in the boot menu, set the +"BootNext" +EFI variable and restart the system\&. The firmware will then start Windows Boot Manager directly, leaving the TPM PCRs in expected states so that Windows can unseal the encryption key\&. This allows +\fBsystemd-boot\fR(7) +to be updated without having to provide the recovery key for BitLocker drive unlocking\&. +.sp +Note that the PCRs that Windows uses can be configured with the +"Configure TPM platform validation profile for native UEFI firmware configurations" +group policy under +"Computer Configuration\eAdministrative Templates\eWindows Components\eBitLocker Drive Encryption"\&. When Secure Boot is enabled, changing this to PCRs +"0,2,7,11" +should be safe\&. The TPM key protector needs to be removed and then added back for the PCRs on an already encrypted drive to change\&. If PCR 4 is not measured, this setting can be disabled to speed up booting into Windows\&. +.sp +Added in version 251\&. +.RE +.SH "EXAMPLE" +.sp +.if n \{\ +.RS 4 +.\} +.nf +# /boot/efi/loader/loader\&.conf +timeout 0 +default 01234567890abcdef1234567890abdf0\-* +editor no + +.fi +.if n \{\ +.RE +.\} +.PP +The menu will not be shown by default (the menu can still be shown by pressing and holding a key during boot)\&. One of the entries with files with a name starting with +"01234567890abcdef1234567890abdf0\-" +will be selected by default\&. If more than one entry matches, the one with the highest priority will be selected (generally the one with the highest version number)\&. The editor will be disabled, so it is not possible to alter the kernel command line\&. +.SH "SEE ALSO" +.PP +\fBsystemd-boot\fR(7), +\fBbootctl\fR(1) +.SH "NOTES" +.IP " 1." 4 +Boot Loader Specification +.RS 4 +\%https://uapi-group.org/specifications/specs/boot_loader_specification +.RE +.IP " 2." 4 +UEFI specification +.RS 4 +\%https://uefi.org/specifications +.RE +.IP " 3." 4 +EDK2 documentation +.RS 4 +\%https://edk2-docs.gitbook.io/understanding-the-uefi-secure-boot-chain/secure_boot_chain_in_uefi/uefi_secure_boot +.RE +.IP " 4." 4 +Windows Secure Boot Key Creation and Management Guidance +.RS 4 +\%https://learn.microsoft.com/en-us/windows-hardware/manufacture/desktop/windows-secure-boot-key-creation-and-management-guidance +.RE +.IP " 5." 4 +Secure Boot and Option ROMs +.RS 4 +\%https://github.com/Foxboron/sbctl/wiki/FAQ#option-rom +.RE -- cgit v1.2.3