Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 427 insertions, 0 deletions

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 <<END
+580a6f4cc4e4b669b9ebdc1b2b3e087b80d0678d  ms\-db\-2011\&.der
+31590bfd89c9d74ed087dfac66334b3931254b30  ms\-kek\-2011\&.der
+46def63b5ce61cf8ba0de2e6639c1019d0ed14f3  ms\-uefi\-db\-2011\&.der
+45a0fa32604773c82433c3b7d59e7466b3ac0c67  ms\-db\-2023\&.der
+459ab6fb5e284d272d5e3e6abc8ed663829d632b  ms\-kek\-2023\&.der
+b5eeb4a6706048073f0ed296e7f580a790b59eaa  ms\-uefi\-db\-2023\&.der
+END
+for key in ms\-*\&.der; do
+  sbsiglist \-\-owner 77fa9abd\-0359\-4d32\-bd60\-28f4e78f784b \-\-type x509 \-\-output "${key%der}esl" "${key}"
+done
+
+# Optionally add Microsoft Windows certificates (needed to boot into Windows)\&.
+cat ms\-db\-*\&.esl >>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