shaba/systemd
1
0
Fork 0
mirror of https://github.com/systemd/systemd.git synced 2024-12-23 21:35:11 +03:00
Code
80d62d4f1a
systemd/docs/BOOT_LOADER_INTERFACE.md

154 lines
8.4 KiB
Markdown
Raw Normal View History

docs: add a "front matter" snippet to our markdown pages It turns out Jekyll (the engine behind GitHub Pages) requires that pages include a "Front Matter" snippet of YAML at the top for proper rendering. Omitting it will still render the pages, but including it opens up new possibilities, such as using a {% for %} loop to generate index.md instead of requiring a separate script. I'm hoping this will also fix the issue with some of the pages (notably CODE_OF_CONDUCT.html) not being available under systemd.io Tested locally by rendering the website with Jekyll. Before this change, the *.md files were kept unchanged (so not sure how that even works?!), after this commit, proper *.html files were generated from it.
2019-01-03 01:16:34 +03:00
---
docs: drop "The" in categorization titles of Markdown documentation I think it makes sense to keep the "The" in place for the actual page's title, but let's drop it from the categorization header, to make it easier to find stuff, as the "The" isn't helpful to that. In particular as we sometimes do it this and sometimes the other way so far, hence let's stick to one common rule.
2020-01-14 12:11:19 +03:00
title: Boot Loader Interface
docs: place all our markdown docs in rough categories
2019-12-11 12:49:28 +03:00
category: Booting
docs: make it pretty Add custom Jekyll theme, logo, webfont and .gitignore FIXME: the markdown files have some H1 headers which need to be replaced with H2
2019-12-11 19:01:46 +03:00
layout: default
docs: add spdx tags to all .md files I have no idea if this is going to cause rendering problems, and it is fairly hard to check. So let's just merge this, and if it github markdown processor doesn't like it, revert.
2021-09-14 17:05:21 +03:00
SPDX-License-Identifier: LGPL-2.1-or-later
docs: add a "front matter" snippet to our markdown pages It turns out Jekyll (the engine behind GitHub Pages) requires that pages include a "Front Matter" snippet of YAML at the top for proper rendering. Omitting it will still render the pages, but including it opens up new possibilities, such as using a {% for %} loop to generate index.md instead of requiring a separate script. I'm hoping this will also fix the issue with some of the pages (notably CODE_OF_CONDUCT.html) not being available under systemd.io Tested locally by rendering the website with Jekyll. Before this change, the *.md files were kept unchanged (so not sure how that even works?!), after this commit, proper *.html files were generated from it.
2019-01-03 01:16:34 +03:00
---
docs: migrate boot loader interface from fdo wiki to git This imports https://www.freedesktop.org/wiki/Software/systemd/BootLoaderInterface/ into our sources, and extends it substantially with various variables now supported.
2018-10-23 17:28:30 +03:00
# The Boot Loader Interface
systemd can interface with the boot loader to receive performance data and
other information, and pass control information. This is only supported on EFI
systems. Data is transferred between the boot loader and systemd in EFI
variables. All EFI variables use the vendor UUID
`4a67b082-0a4c-41cf-b6c7-440b29bb8c4f`.
* The EFI Variable `LoaderTimeInitUSec` contains the timestamp in microseconds
when the loader was initialized. This value is the time spent in the firmware
for initialization, it is formatted as numeric, NUL-terminated, decimal
string, in UTF-16.
* The EFI Variable `LoaderTimeExecUSec` contains the timestamp in microseconds
when the loader finished its work and is about to execute the kernel. The
time spent in the loader is the difference between `LoaderTimeExecUSec` and
`LoaderTimeInitUSec`. This value is formatted the same way as
`LoaderTimeInitUSec`.
* The EFI variable `LoaderDevicePartUUID` contains the partition GUID of the
ESP the boot loader was run from formatted as NUL-terminated UTF16 string, in
normal GUID syntax.
tree-wide: s/time-out/timeout/g From WordNet (r) 3.0 (2006) [wn]: time-out n 1: a brief suspension of play; "each team has two time-outs left" From The Free On-line Dictionary of Computing (18 March 2015) [foldoc]: timeout A period of time after which an error condition is raised if some event has not occured. A common example is sending a message. If the receiver does not acknowledge the message within some preset timeout period, a transmission error is assumed to have occured.
2018-12-14 10:26:46 +03:00
* The EFI variable `LoaderConfigTimeout` contains the boot menu timeout
docs: migrate boot loader interface from fdo wiki to git This imports https://www.freedesktop.org/wiki/Software/systemd/BootLoaderInterface/ into our sources, and extends it substantially with various variables now supported.
2018-10-23 17:28:30 +03:00
currently in use. It may be modified both by the boot loader and by the
host. The value should be formatted as numeric, NUL-terminated, decimal
string, in UTF-16. The time is specified in µs.
* Similarly, the EFI variable `LoaderConfigTimeoutOneShot` contains a boot menu
tree-wide: s/time-out/timeout/g From WordNet (r) 3.0 (2006) [wn]: time-out n 1: a brief suspension of play; "each team has two time-outs left" From The Free On-line Dictionary of Computing (18 March 2015) [foldoc]: timeout A period of time after which an error condition is raised if some event has not occured. A common example is sending a message. If the receiver does not acknowledge the message within some preset timeout period, a transmission error is assumed to have occured.
2018-12-14 10:26:46 +03:00
timeout for a single following boot. It is set by the OS in order to request
docs: migrate boot loader interface from fdo wiki to git This imports https://www.freedesktop.org/wiki/Software/systemd/BootLoaderInterface/ into our sources, and extends it substantially with various variables now supported.
2018-10-23 17:28:30 +03:00
display of the boot menu on the following boot. When set overrides
`LoaderConfigTimeout`. It is removed automatically after being read by the
boot loader, to ensure it only takes effect a single time. This value is
formatted the same way as `LoaderConfigTimeout`. If set to `0` the boot menu
tree-wide: s/time-out/timeout/g From WordNet (r) 3.0 (2006) [wn]: time-out n 1: a brief suspension of play; "each team has two time-outs left" From The Free On-line Dictionary of Computing (18 March 2015) [foldoc]: timeout A period of time after which an error condition is raised if some event has not occured. A common example is sending a message. If the receiver does not acknowledge the message within some preset timeout period, a transmission error is assumed to have occured.
2018-12-14 10:26:46 +03:00
timeout is turned off, and the menu is shown indefinitely.
docs: migrate boot loader interface from fdo wiki to git This imports https://www.freedesktop.org/wiki/Software/systemd/BootLoaderInterface/ into our sources, and extends it substantially with various variables now supported.
2018-10-23 17:28:30 +03:00
* The EFI variable `LoaderEntries` may contain a series of boot loader entry
identifiers, one after the other, each individually NUL terminated. This may
be used to let the OS know which boot menu entries were discovered by the
boot loader. A boot loader entry identifier should be a short, non-empty
alphanumeric string (possibly containing `-`, too). The list should be in the
order the entries are shown on screen during boot. See below regarding a
recommended vocabulary for boot loader entry identifiers.
* The EFI variable `LoaderEntryDefault` contains the default boot loader entry
to use. It contains a NUL-terminated boot loader entry identifier.
* Similarly, the EFI variable `LoaderEntryOneShot` contains the default boot
loader entry to use for a single following boot. It is set by the OS in order
to request booting into a specific menu entry on the following boot. When set
overrides `LoaderEntryDefault`. It is removed automatically after being read
by the boot loader, to ensure it only takes effect a single time. This value
is formatted the same way as `LoaderEntryDefault`.
* The EFI variable `LoaderEntrySelected` contains the boot loader entry
identifier that was booted. It is set by the boot loader and read by
the OS in order to identify which entry has been used for the current boot.
* The EFI variable `LoaderFeatures` contains a 64bit unsigned integer with a
number of flags bits that are set by the boot loader and passed to the OS and
indicate the features the boot loader supports. Specifically, the following
bits are defined:
* `1 << 0` → The boot loader honours `LoaderConfigTimeout` when set.
* `1 << 1` → The boot loader honours `LoaderConfigTimeoutOneShot` when set.
* `1 << 2` → The boot loader honours `LoaderEntryDefault` when set.
* `1 << 3` → The boot loader honours `LoaderEntryOneShot` when set.
* `1 << 4` → The boot loader supports boot counting as described in [Automatic Boot Assessment](https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT).
docs: document new random seed EFI vars as part of the boot loader interface
2019-07-22 15:00:25 +03:00
* `1 << 5` → The boot loader supports looking for boot menu entries in the Extended Boot Loader Partition.
docs: fix typo in boot loader doc
2019-09-04 19:21:14 +03:00
* `1 << 6` → The boot loader supports passing a random seed to the OS.
docs: document new random seed EFI vars as part of the boot loader interface
2019-07-22 15:00:25 +03:00
* The EFI variable `LoaderRandomSeed` contains a binary random seed if set. It
docs: improve wording when mentioning the acronym "ESP" "ESP" is "EFI system partition", so "ESP partition" is redundant.
2021-07-09 12:56:54 +03:00
is set by the boot loader to pass an entropy seed read from the ESP to the OS.
The system manager then credits this seed to the kernel's entropy pool. It is
the responsibility of the boot loader to ensure the quality and integrity of
the random seed.
docs: document new random seed EFI vars as part of the boot loader interface
2019-07-22 15:00:25 +03:00
* The EFI variable `LoaderSystemToken` contains binary random data,
persistently set by the OS installer. Boot loaders that support passing
random seeds to the OS should use this data and combine it with the random
seed file read from the ESP. By combining this random data with the random
seed read off the disk before generating a seed to pass to the OS and a new
seed to store in the ESP the boot loader can protect itself from situations
where "golden" OS images that include a random seed are replicated and used
on multiple systems. Since the EFI variable storage is usually independent
(i.e. in physical NVRAM) of the ESP file system storage, and only the latter
is part of "golden" OS images, this ensures that different systems still come
up with different random seeds. Note that the `LoaderSystemToken` is
generally only written once, by the OS installer, and is usually not touched
after that.
docs: migrate boot loader interface from fdo wiki to git This imports https://www.freedesktop.org/wiki/Software/systemd/BootLoaderInterface/ into our sources, and extends it substantially with various variables now supported.
2018-10-23 17:28:30 +03:00
If `LoaderTimeInitUSec` and `LoaderTimeExecUSec` are set, `systemd-analyze`
will include them in its boot-time analysis. If `LoaderDevicePartUUID` is set,
systemd will mount the ESP that was used for the boot to `/boot`, but only if
that directory is empty, and only if no other file systems are mounted
there. The `systemctl reboot --boot-loader-entry=…` and `systemctl reboot
--boot-loader-menu=…` commands rely on the `LoaderFeatures` ,
docs: document new random seed EFI vars as part of the boot loader interface
2019-07-22 15:00:25 +03:00
`LoaderConfigTimeoutOneShot`, `LoaderEntries`, `LoaderEntryOneShot`
variables. `LoaderRandomSeed` is read by PID during early boot and credited to
the kernel's random pool.
doc: document the boot menu entry identifier vocabulary The existing text already said "See below regarding a recommended vocabulary for boot loader entry identifiers.", but the section for it was still missing. Let's fill in the missing bits, and describe basic suggested rules for the boot menu entry identifier vocabulary, in particular how to identify Windows and MacOS X installations, and how to name automatic entries vs. explicitly configured ones. This basically follows the logic implemented in sd-boot these days.
2018-11-19 16:33:03 +03:00
## Boot Loader Entry Identifiers
While boot loader entries may be named relatively freely, it's highly
recommended to follow the following rules when picking identifiers for the
entries, so that programs (and users) can derive basic context and meaning from
the identifiers as passed in `LoaderEntries`, `LoaderEntryDefault`,
`LoaderEntryOneShot`, `LoaderEntrySelected`, and possibly show nicely localized
names for them in UIs.
1. When boot loader entries are defined through [Boot Loader
Specification](https://systemd.io/BOOT_LOADER_SPECIFICATION) drop-in files
the identifier should be derived directly from the drop-in snippet name, but
with the `.conf` (or `.efi` in case of Type #2 entries) suffix removed.
2. Entries automatically discovered by the boot loader (as opposed to being
configured in configuration files) should generally have an identifier
prefixed with `auto-`.
3. Boot menu entries referring to Microsoft Windows installations should either
use the identifier `windows` or use the `windows-` prefix for the
identifier. If a menu entry is automatically discovered, it should be
prefixed with `auto-`, see above (Example: this means an automatically
discovered Windows installation might have the identifier `auto-windows` or
`auto-windows-10` or so.).
docs: use current spelling "macOS" not "OS X" etc.
2021-04-02 11:03:02 +03:00
4. Similar, boot menu entries referring to Apple macOS installations should
doc: document the boot menu entry identifier vocabulary The existing text already said "See below regarding a recommended vocabulary for boot loader entry identifiers.", but the section for it was still missing. Let's fill in the missing bits, and describe basic suggested rules for the boot menu entry identifier vocabulary, in particular how to identify Windows and MacOS X installations, and how to name automatic entries vs. explicitly configured ones. This basically follows the logic implemented in sd-boot these days.
2018-11-19 16:33:03 +03:00
use the identifier `osx` or one that is prefixed with `osx-`. If such an
entry is automatically discovered by the boot loader use `auto-osx` as
identifier, or `auto-osx-` as prefix for the identifier, see above.
5. If a boot menu entry encapsulates the EFI shell program, it should use the
identifier `efi-shell` (or when automatically discovered: `auto-efi-shell`,
see above).
6. If a boot menu entry encapsulates a reboot into EFI firmware setup feature,
it should use the identifier `reboot-to-firmware-setup` (or
`auto-reboot-to-firmware-setup` in case it is automatically discovered).
docs: interlink the docs to make it easier to navigate
2020-02-28 13:47:03 +03:00
## Links
docs: fix the link to boot loader specification The boot loader specification link points to the boot loader interface documentation. This fixes the link to point to BOOT_LOADER_SPECIFICATION instead of BOOTLOADER_INTERFACE which is itself.
2020-12-30 17:29:36 +03:00
[Boot Loader Specification](https://systemd.io/BOOT_LOADER_SPECIFICATION)<br>
docs: interlink the docs to make it easier to navigate
2020-02-28 13:47:03 +03:00
[Discoverable Partitions Specification](https://systemd.io/DISCOVERABLE_PARTITIONS)<br>
[systemd-boot(7)](https://www.freedesktop.org/software/systemd/man/systemd-boot.html)<br>
[bootctl(1)](https://www.freedesktop.org/software/systemd/man/bootctl.html)<br>
[systemd-gpt-auto-generator(8)](https://www.freedesktop.org/software/systemd/man/systemd-gpt-auto-generator.html)
Copy Permalink