shaba/systemd
1
0
Fork 0
mirror of https://github.com/systemd/systemd.git synced 2024-12-22 17:35:35 +03:00
Code
48d67957d5
systemd/man/bootctl.xml

649 lines
32 KiB
XML
Raw Normal View History

man: add bootctl(8) https://bugzilla.redhat.com/show_bug.cgi?id=1014303
2013-11-13 13:06:13 +04:00
<?xml version='1.0'?> <!--*-nxml-*-->
man: use same header for all files The "include" files had type "book" for some raeason. I don't think this is meaningful. Let's just use the same everywhere. $ perl -i -0pe 's^..DOCTYPE (book|refentry) PUBLIC "-//OASIS//DTD DocBook XML V4.[25]//EN"\s+"http^<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"\n "http^gms' man/*.xml
2019-03-14 16:40:58 +03:00
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
man: use same version in public and system ident.
2023-12-25 17:48:33 +03:00
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
license: LGPL-2.1+ -> LGPL-2.1-or-later
2020-11-09 07:23:58 +03:00
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
man: add bootctl(8) https://bugzilla.redhat.com/show_bug.cgi?id=1014303
2013-11-13 13:06:13 +04:00
tree-wide: Drop gnu-efi This drops all mentions of gnu-efi and its manual build machinery. A future commit will bring bootloader builds back. A new bootloader meson option is now used to control whether to build sd-boot and its userspace tooling.
2023-02-26 16:09:44 +03:00
<refentry id="bootctl" conditional='ENABLE_BOOTLOADER'
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>bootctl</title>
<productname>systemd</productname>
</refentryinfo>
<refmeta>
<refentrytitle>bootctl</refentrytitle>
<manvolnum>1</manvolnum>
</refmeta>
<refnamediv>
<refname>bootctl</refname>
bootctl: separate boot loader specific commands in man and --help bootctl implements three types of operation: those that work with an EFI boot loader, those which work with any EFI boot loader that implements the boot loader spec + interface, and finally those specific to sd-boot. Previously the --help text and the man page mixed them all up. Let's put them clearly in three separate sections however, to communicate clearly what is supposed to work everywhere, and what is specific to systemd-boot or boot loaders implementing the two specs. This adjusts wording here and there, but is mostly just about re-ordering existing docs, and putting them under new sections.
2020-10-13 14:40:21 +03:00
<refpurpose>Control EFI firmware boot settings and manage boot loader</refpurpose>
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
man: re-format man page for bootctl
2018-06-15 09:40:12 +03:00
<command>bootctl</command>
<arg choice="opt" rep="repeat">OPTIONS</arg>
<arg choice="req">COMMAND</arg>
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
bootctl: separate boot loader specific commands in man and --help bootctl implements three types of operation: those that work with an EFI boot loader, those which work with any EFI boot loader that implements the boot loader spec + interface, and finally those specific to sd-boot. Previously the --help text and the man page mixed them all up. Let's put them clearly in three separate sections however, to communicate clearly what is supposed to work everywhere, and what is specific to systemd-boot or boot loaders implementing the two specs. This adjusts wording here and there, but is mostly just about re-ordering existing docs, and putting them under new sections.
2020-10-13 14:40:21 +03:00
<para><command>bootctl</command> can check the EFI firmware and boot loader status, list and manage
available boot loaders and boot loader entries, and install, update, or remove the
<citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry> boot
loader on the current system.</para>
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
</refsect1>
man: re-format man page for bootctl
2018-06-15 09:40:12 +03:00
<refsect1>
bootctl: separate boot loader specific commands in man and --help bootctl implements three types of operation: those that work with an EFI boot loader, those which work with any EFI boot loader that implements the boot loader spec + interface, and finally those specific to sd-boot. Previously the --help text and the man page mixed them all up. Let's put them clearly in three separate sections however, to communicate clearly what is supposed to work everywhere, and what is specific to systemd-boot or boot loaders implementing the two specs. This adjusts wording here and there, but is mostly just about re-ordering existing docs, and putting them under new sections.
2020-10-13 14:40:21 +03:00
<title>Generic EFI Firmware/Boot Loader Commands</title>
<para>These commands are available on any EFI system, regardless of the boot loader used.</para>
man: re-format man page for bootctl
2018-06-15 09:40:12 +03:00
bootctl: separate boot loader specific commands in man and --help bootctl implements three types of operation: those that work with an EFI boot loader, those which work with any EFI boot loader that implements the boot loader spec + interface, and finally those specific to sd-boot. Previously the --help text and the man page mixed them all up. Let's put them clearly in three separate sections however, to communicate clearly what is supposed to work everywhere, and what is specific to systemd-boot or boot loaders implementing the two specs. This adjusts wording here and there, but is mostly just about re-ordering existing docs, and putting them under new sections.
2020-10-13 14:40:21 +03:00
<variablelist>
man: re-format man page for bootctl
2018-06-15 09:40:12 +03:00
<varlistentry>
<term><option>status</option></term>
man: fix tag syntax Strangely enough, having <varlistenetry>s outside of <variablelist> wasn't causing visual problems. But having two <listitem>s in one <varlistentry> resulted in the paragraphs running together in the rendered man page.
2022-04-04 11:13:16 +03:00
<listitem><para>Shows brief information about the system firmware, the boot loader that was used to
boot the system, the boot loaders currently available in the ESP, the boot loaders listed in the
firmware's list of boot loaders and the current default boot loader entry. If no command is
man: add annotated example for bootctl status & list This is based on the output on my laptop, with various manual adjustments. If people have other types of entries, it'd be useful to add them here. In particular, some dual-boot entries would be nice.
2022-04-04 11:45:47 +03:00
specified, this is the implied default.</para>
<para>See the example below for details of the output.</para>
man: update version information As I noticed a lot of missing information when trying to implement checking for missing info. I reimplemented the version information script to be more robust, and here is the result. Follow up to ec07c3c80b2b1bfa6788500202006ff85f5ae4f4
2023-09-18 18:03:38 +03:00
<xi:include href="version-info.xml" xpointer="v239"/>
man: add annotated example for bootctl status & list This is based on the output on my laptop, with various manual adjustments. If people have other types of entries, it'd be useful to add them here. In particular, some dual-boot entries would be nice.
2022-04-04 11:45:47 +03:00
</listitem>
man: re-format man page for bootctl
2018-06-15 09:40:12 +03:00
</varlistentry>
bootctl: separate boot loader specific commands in man and --help bootctl implements three types of operation: those that work with an EFI boot loader, those which work with any EFI boot loader that implements the boot loader spec + interface, and finally those specific to sd-boot. Previously the --help text and the man page mixed them all up. Let's put them clearly in three separate sections however, to communicate clearly what is supposed to work everywhere, and what is specific to systemd-boot or boot loaders implementing the two specs. This adjusts wording here and there, but is mostly just about re-ordering existing docs, and putting them under new sections.
2020-10-13 14:40:21 +03:00
man: fix tag syntax Strangely enough, having <varlistenetry>s outside of <variablelist> wasn't causing visual problems. But having two <listitem>s in one <varlistentry> resulted in the paragraphs running together in the rendered man page.
2022-04-04 11:13:16 +03:00
<varlistentry>
<term><option>reboot-to-firmware</option> <optional><replaceable>BOOL</replaceable></optional></term>
<listitem><para>Query or set the "Reboot-Into-Firmware-Setup" flag of the EFI firmware. Takes a
boolean argument which controls whether to show the firmware setup on next system reboot. If the
argument is omitted shows the current status of the flag, or whether the flag is supported. This
controls the same flag as <command>systemctl reboot --firmware-setup</command>, but is more low-level
man: cross-advertize bootctl and systemctl boot loader support
2022-04-28 17:44:40 +03:00
and allows setting the flag independently from actually requesting a reboot.</para>
<para>Hint: use <command>systemctl reboot --firmware-setup</command> to reboot into firmware setup
once. See
<citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-22 19:52:36 +03:00
for details.</para>
<xi:include href="version-info.xml" xpointer="v251"/></listitem>
man: fix tag syntax Strangely enough, having <varlistenetry>s outside of <variablelist> wasn't causing visual problems. But having two <listitem>s in one <varlistentry> resulted in the paragraphs running together in the rendered man page.
2022-04-04 11:13:16 +03:00
</varlistentry>
</variablelist>
bootctl: separate boot loader specific commands in man and --help bootctl implements three types of operation: those that work with an EFI boot loader, those which work with any EFI boot loader that implements the boot loader spec + interface, and finally those specific to sd-boot. Previously the --help text and the man page mixed them all up. Let's put them clearly in three separate sections however, to communicate clearly what is supposed to work everywhere, and what is specific to systemd-boot or boot loaders implementing the two specs. This adjusts wording here and there, but is mostly just about re-ordering existing docs, and putting them under new sections.
2020-10-13 14:40:21 +03:00
</refsect1>
<refsect1>
<title>Boot Loader Specification Commands</title>
bootctl: split out boot loader spec + boot loader interface commands in --help text grub (at least on fedora) nowadays implements the boot loader spec, but not the boot loader interface. Hence let's split out the commands specific to each in two groups in the --help text. This way the first group just covers boot lodaer spec stuff (i.e. stuff on disk in the ESP/XBOOTLDR partition). And the other covers talking to the boot loader via EFI var.
2023-01-20 20:36:31 +03:00
<para>These commands are available for all boot loaders that
implement the <ulink
url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot
Loader Specification</ulink>, such as
bootctl: separate boot loader specific commands in man and --help bootctl implements three types of operation: those that work with an EFI boot loader, those which work with any EFI boot loader that implements the boot loader spec + interface, and finally those specific to sd-boot. Previously the --help text and the man page mixed them all up. Let's put them clearly in three separate sections however, to communicate clearly what is supposed to work everywhere, and what is specific to systemd-boot or boot loaders implementing the two specs. This adjusts wording here and there, but is mostly just about re-ordering existing docs, and putting them under new sections.
2020-10-13 14:40:21 +03:00
<command>systemd-boot</command>.</para>
<variablelist>
<varlistentry>
<term><option>list</option></term>
<listitem><para>Shows all available boot loader entries implementing the <ulink
tree-wide: BLS and DPS are now on uapi-group website
2022-11-14 11:44:39 +03:00
url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader Specification</ulink>, as well as any
bootctl: separate boot loader specific commands in man and --help bootctl implements three types of operation: those that work with an EFI boot loader, those which work with any EFI boot loader that implements the boot loader spec + interface, and finally those specific to sd-boot. Previously the --help text and the man page mixed them all up. Let's put them clearly in three separate sections however, to communicate clearly what is supposed to work everywhere, and what is specific to systemd-boot or boot loaders implementing the two specs. This adjusts wording here and there, but is mostly just about re-ordering existing docs, and putting them under new sections.
2020-10-13 14:40:21 +03:00
other entries discovered or automatically generated by a boot loader implementing the <ulink
man: add annotated example for bootctl status & list This is based on the output on my laptop, with various manual adjustments. If people have other types of entries, it'd be useful to add them here. In particular, some dual-boot entries would be nice.
2022-04-04 11:45:47 +03:00
url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink>.
JSON output may be requested with <option>--json=</option>.</para>
bootctl: optionally, output entries in JSON format Replaces: #18387 Fixes: #18094
2022-03-23 18:08:36 +03:00
man: add annotated example for bootctl status & list This is based on the output on my laptop, with various manual adjustments. If people have other types of entries, it'd be useful to add them here. In particular, some dual-boot entries would be nice.
2022-04-04 11:45:47 +03:00
<para>See the example below for details of the output.</para>
man: update version information As I noticed a lot of missing information when trying to implement checking for missing info. I reimplemented the version information script to be more robust, and here is the result. Follow up to ec07c3c80b2b1bfa6788500202006ff85f5ae4f4
2023-09-18 18:03:38 +03:00
<xi:include href="version-info.xml" xpointer="v239"/>
bootctl: optionally, output entries in JSON format Replaces: #18387 Fixes: #18094
2022-03-23 18:08:36 +03:00
</listitem>
bootctl: separate boot loader specific commands in man and --help bootctl implements three types of operation: those that work with an EFI boot loader, those which work with any EFI boot loader that implements the boot loader spec + interface, and finally those specific to sd-boot. Previously the --help text and the man page mixed them all up. Let's put them clearly in three separate sections however, to communicate clearly what is supposed to work everywhere, and what is specific to systemd-boot or boot loaders implementing the two specs. This adjusts wording here and there, but is mostly just about re-ordering existing docs, and putting them under new sections.
2020-10-13 14:40:21 +03:00
</varlistentry>
bootctl: split out boot loader spec + boot loader interface commands in --help text grub (at least on fedora) nowadays implements the boot loader spec, but not the boot loader interface. Hence let's split out the commands specific to each in two groups in the --help text. This way the first group just covers boot lodaer spec stuff (i.e. stuff on disk in the ESP/XBOOTLDR partition). And the other covers talking to the boot loader via EFI var.
2023-01-20 20:36:31 +03:00
<varlistentry>
<term><option>unlink</option> <replaceable>ID</replaceable></term>
<listitem><para>Removes a boot loader entry including the files it refers to. Takes a single boot
loader entry ID string or a glob pattern as argument. Referenced files such as kernel or initrd are
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-22 19:52:36 +03:00
only removed if no other entry refers to them.</para>
<xi:include href="version-info.xml" xpointer="v253"/></listitem>
bootctl: split out boot loader spec + boot loader interface commands in --help text grub (at least on fedora) nowadays implements the boot loader spec, but not the boot loader interface. Hence let's split out the commands specific to each in two groups in the --help text. This way the first group just covers boot lodaer spec stuff (i.e. stuff on disk in the ESP/XBOOTLDR partition). And the other covers talking to the boot loader via EFI var.
2023-01-20 20:36:31 +03:00
</varlistentry>
<varlistentry>
<term><option>cleanup</option></term>
<listitem><para>Removes files from the ESP and XBOOTLDR partitions that belong to the entry token but
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-22 19:52:36 +03:00
are not referenced in any boot loader entries.</para>
<xi:include href="version-info.xml" xpointer="v253"/></listitem>
bootctl: split out boot loader spec + boot loader interface commands in --help text grub (at least on fedora) nowadays implements the boot loader spec, but not the boot loader interface. Hence let's split out the commands specific to each in two groups in the --help text. This way the first group just covers boot lodaer spec stuff (i.e. stuff on disk in the ESP/XBOOTLDR partition). And the other covers talking to the boot loader via EFI var.
2023-01-20 20:36:31 +03:00
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Boot Loader Interface Commands</title>
<para>These commands are available for all boot loaders that implement the <ulink
url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader Specification</ulink> and the <ulink
url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink>, such as
<command>systemd-boot</command>.</para>
<variablelist>
bootctl: separate boot loader specific commands in man and --help bootctl implements three types of operation: those that work with an EFI boot loader, those which work with any EFI boot loader that implements the boot loader spec + interface, and finally those specific to sd-boot. Previously the --help text and the man page mixed them all up. Let's put them clearly in three separate sections however, to communicate clearly what is supposed to work everywhere, and what is specific to systemd-boot or boot loaders implementing the two specs. This adjusts wording here and there, but is mostly just about re-ordering existing docs, and putting them under new sections.
2020-10-13 14:40:21 +03:00
<varlistentry>
<term><option>set-default</option> <replaceable>ID</replaceable></term>
<term><option>set-oneshot</option> <replaceable>ID</replaceable></term>
sd-boot: Allow glob patterns for default and oneshot EFI vars too
2021-10-28 13:15:33 +03:00
<listitem><para>Sets the default boot loader entry. Takes a single boot loader entry ID string or a glob
pattern as argument. The <option>set-oneshot</option> command will set the default entry only for the next boot,
man: fix tag syntax Strangely enough, having <varlistenetry>s outside of <variablelist> wasn't causing visual problems. But having two <listitem>s in one <varlistentry> resulted in the paragraphs running together in the rendered man page.
2022-04-04 11:13:16 +03:00
the <option>set-default</option> will set it persistently for all future boots.</para>
bootctl: add @current/@oneshot/@default targets to set-default/set-oneshot Using `bootctl set-default @current` will set the default loader entry to the currently booted entry as read from the `LoaderEntrySelected` EFI variable. Also `bootctl set-oneshot @current` will set the oneshot loader entry to the current booted entry. Correspondingly `@default` and `@oneshot` can be used to read from the LoaderEntryDefault and LoaderEntryOneshot EFI variables.
2020-10-13 13:25:59 +03:00
man: cross-advertize bootctl and systemctl boot loader support
2022-04-28 17:44:40 +03:00
<para><command>bootctl list</command> can be used to list available boot loader entries and their
IDs.</para>
<para>In addition, the boot loader entry ID may be specified as one of: <option>@default</option>,
bootctl: add @current/@oneshot/@default targets to set-default/set-oneshot Using `bootctl set-default @current` will set the default loader entry to the currently booted entry as read from the `LoaderEntrySelected` EFI variable. Also `bootctl set-oneshot @current` will set the oneshot loader entry to the current booted entry. Correspondingly `@default` and `@oneshot` can be used to read from the LoaderEntryDefault and LoaderEntryOneshot EFI variables.
2020-10-13 13:25:59 +03:00
<option>@oneshot</option> or <option>@current</option>, which correspond to the current default boot loader
entry for all future boots, the current default boot loader entry for the next boot, and the currently booted
boot loader entry. These special IDs are resolved to the current values of the EFI variables
<varname>LoaderEntryDefault</varname>, <varname>LoaderEntryOneShot</varname> and <varname>LoaderEntrySelected</varname>,
tree-wide: BLS and DPS are now on uapi-group website
2022-11-14 11:44:39 +03:00
see <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader Specification</ulink> for details.
bootctl: add @current/@oneshot/@default targets to set-default/set-oneshot Using `bootctl set-default @current` will set the default loader entry to the currently booted entry as read from the `LoaderEntrySelected` EFI variable. Also `bootctl set-oneshot @current` will set the oneshot loader entry to the current booted entry. Correspondingly `@default` and `@oneshot` can be used to read from the LoaderEntryDefault and LoaderEntryOneshot EFI variables.
2020-10-13 13:25:59 +03:00
These special IDs are primarily useful as a quick way to persistently make the currently booted boot loader
entry the default choice, or to upgrade the default boot loader entry for the next boot to the default boot
sd-boot: Add support to boot last selected entry Fixes: #18994
2021-10-28 14:00:13 +03:00
loader entry for all future boots, but may be used for other operations too.</para>
<para>If set to <option>@saved</option> the chosen entry will be saved as an EFI variable
on every boot and automatically selected the next time the boot loader starts.</para>
man: cross-advertize bootctl and systemctl boot loader support
2022-04-28 17:44:40 +03:00
<para>When an empty string ("") is specified as the ID, then the corresponding EFI variable will be
unset.</para>
<para>Hint: use <command>systemctl reboot --boot-loader-entry=<replaceable>ID</replaceable></command>
to reboot into a specific boot entry and
<command>systemctl reboot --boot-loader-menu=<replaceable>timeout</replaceable></command>
to reboot into the boot loader menu once. See
<citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
man: update version information As I noticed a lot of missing information when trying to implement checking for missing info. I reimplemented the version information script to be more robust, and here is the result. Follow up to ec07c3c80b2b1bfa6788500202006ff85f5ae4f4
2023-09-18 18:03:38 +03:00
for details.</para>
<xi:include href="version-info.xml" xpointer="v240"/></listitem>
bootctl: separate boot loader specific commands in man and --help bootctl implements three types of operation: those that work with an EFI boot loader, those which work with any EFI boot loader that implements the boot loader spec + interface, and finally those specific to sd-boot. Previously the --help text and the man page mixed them all up. Let's put them clearly in three separate sections however, to communicate clearly what is supposed to work everywhere, and what is specific to systemd-boot or boot loaders implementing the two specs. This adjusts wording here and there, but is mostly just about re-ordering existing docs, and putting them under new sections.
2020-10-13 14:40:21 +03:00
</varlistentry>
bootctl: Add set-timeout verb Fixes: #18766
2021-10-04 12:25:50 +03:00
<varlistentry>
<term><option>set-timeout</option> <replaceable>TIMEOUT</replaceable></term>
<term><option>set-timeout-oneshot</option> <replaceable>TIMEOUT</replaceable></term>
<listitem><para>Sets the boot loader menu timeout in seconds. The <option>set-timeout-oneshot</option>
command will set the timeout only for the next boot. See
<citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>
for details about the syntax of time spans.</para>
sd-boot: add way to disable the 100ms delay when timeout=0 Currently we have a 100ms delay which allows for people to enter/show the boot menu even when timeout is set to zero. In a handful of cases, that may not be needed - both in terms of access policy, as well as latency. For example: the option to provide the boot menu may be hidden behind an "expert only" UX in the OS, to avoid end users from accidentally entering it. In addition, the current 100ms input polling may cause unexpected additional delays in the boot. Some example numbers from my SteamDeck: - boot counting/rename/flush doubles 300us -> 600us - seed/hash setup doubles 900us -> 1800us - kernel/image load gets ~40% slower 107ms -> 167ms It's not entirely clear why the UEFI calls gets slower, nevertheless the information in itself proves useful. This commit introduces a new option "menu-disabled", which omits the 100ms delay. The option is documented throughout the manual pages as well as the Boot Loader Specification. v2: - use STR_IN_SET v3: - drop erroneous whitespace v4: - add a new LoaderFeature bit, - don't change ABI keep TIMEOUT_* tokens the same - move new token in the 64bit range, update API and storage for it - change inc/dec behaviour to TIMEOUT_MIN : TIMEOUT_MENU_FORCE - user cannot opt-in from sd-boot itself, add assert_not_reached() v5: - s/Menu disablement control/Menu can be disabled/ - rewrap comments to 109 - use SYNTHETIC_ERRNO(EOPNOTSUPP) Signed-off-by: Emil Velikov <emil.velikov@collabora.com>
2023-10-04 14:55:52 +03:00
<para>If this is set to <option>menu-disabled</option> or <option>menu-hidden</option> or
<option>0</option>, no menu is shown and the default entry will be booted immediately, while
setting this to <option>menu-force</option> disables the timeout while always showing the menu.
When an empty string ("") is specified the bootloader will revert to its default menu timeout.</para>
man: update version information As I noticed a lot of missing information when trying to implement checking for missing info. I reimplemented the version information script to be more robust, and here is the result. Follow up to ec07c3c80b2b1bfa6788500202006ff85f5ae4f4
2023-09-18 18:03:38 +03:00
<xi:include href="version-info.xml" xpointer="v250"/></listitem>
bootctl: Add set-timeout verb Fixes: #18766
2021-10-04 12:25:50 +03:00
</varlistentry>
bootctl: separate boot loader specific commands in man and --help bootctl implements three types of operation: those that work with an EFI boot loader, those which work with any EFI boot loader that implements the boot loader spec + interface, and finally those specific to sd-boot. Previously the --help text and the man page mixed them all up. Let's put them clearly in three separate sections however, to communicate clearly what is supposed to work everywhere, and what is specific to systemd-boot or boot loaders implementing the two specs. This adjusts wording here and there, but is mostly just about re-ordering existing docs, and putting them under new sections.
2020-10-13 14:40:21 +03:00
</variablelist>
</refsect1>
<refsect1>
<title><command>systemd-boot</command> Commands</title>
<para>These commands manage the <command>systemd-boot</command> EFI boot loader, and do not work in
conjunction with other boot loaders.</para>
<variablelist>
man: re-format man page for bootctl
2018-06-15 09:40:12 +03:00
<varlistentry>
man: various updates to the bootctl man page
2018-06-22 21:19:27 +03:00
<term><option>install</option></term>
man: re-format man page for bootctl
2018-06-15 09:40:12 +03:00
man: document XBOOTLDR partition logic in bootctl's man page
2019-02-12 18:22:31 +03:00
<listitem><para>Installs <command>systemd-boot</command> into the EFI system partition. A copy of
<command>systemd-boot</command> will be stored as the EFI default/fallback loader at
<filename><replaceable>ESP</replaceable>/EFI/BOOT/BOOT*.EFI</filename>. The boot loader is then added
man: update version information As I noticed a lot of missing information when trying to implement checking for missing info. I reimplemented the version information script to be more robust, and here is the result. Follow up to ec07c3c80b2b1bfa6788500202006ff85f5ae4f4
2023-09-18 18:03:38 +03:00
to the top of the firmware's boot loader list.</para>
<xi:include href="version-info.xml" xpointer="v239"/></listitem>
man: re-format man page for bootctl
2018-06-15 09:40:12 +03:00
</varlistentry>
<varlistentry>
man: various updates to the bootctl man page
2018-06-22 21:19:27 +03:00
<term><option>update</option></term>
man: re-format man page for bootctl
2018-06-15 09:40:12 +03:00
man: various updates to the bootctl man page
2018-06-22 21:19:27 +03:00
<listitem><para>Updates all installed versions of
<citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>, if the
available version is newer than the version installed in the EFI system partition. This also includes the EFI
default/fallback loader at <filename><replaceable>ESP</replaceable>/EFI/BOOT/BOOT*.EFI</filename>. The boot
man: update version information As I noticed a lot of missing information when trying to implement checking for missing info. I reimplemented the version information script to be more robust, and here is the result. Follow up to ec07c3c80b2b1bfa6788500202006ff85f5ae4f4
2023-09-18 18:03:38 +03:00
loader is then added to end of the firmware's boot loader list if missing.</para>
<xi:include href="version-info.xml" xpointer="v239"/></listitem>
man: re-format man page for bootctl
2018-06-15 09:40:12 +03:00
</varlistentry>
<varlistentry>
<term><option>remove</option></term>
man: various updates to the bootctl man page
2018-06-22 21:19:27 +03:00
<listitem><para>Removes all installed versions of <command>systemd-boot</command> from the EFI system partition
man: update version information As I noticed a lot of missing information when trying to implement checking for missing info. I reimplemented the version information script to be more robust, and here is the result. Follow up to ec07c3c80b2b1bfa6788500202006ff85f5ae4f4
2023-09-18 18:03:38 +03:00
and the firmware's boot loader list.</para>
<xi:include href="version-info.xml" xpointer="v239"/></listitem>
man: re-format man page for bootctl
2018-06-15 09:40:12 +03:00
</varlistentry>
bootctl: add "system-options" verb
2019-08-01 18:15:59 +03:00
<varlistentry>
<term><option>is-installed</option></term>
<listitem><para>Checks whether <command>systemd-boot</command> is installed in the ESP. Note that a
single ESP might host multiple boot loaders; this hence checks whether
<command>systemd-boot</command> is one (of possibly many) installed boot loaders — and neither
man: update version information As I noticed a lot of missing information when trying to implement checking for missing info. I reimplemented the version information script to be more robust, and here is the result. Follow up to ec07c3c80b2b1bfa6788500202006ff85f5ae4f4
2023-09-18 18:03:38 +03:00
whether it is the default nor whether it is registered in any EFI variables.</para>
<xi:include href="version-info.xml" xpointer="v243"/></listitem>
bootctl: add "system-options" verb
2019-08-01 18:15:59 +03:00
</varlistentry>
man: document the systemd-random-seed rework
2019-07-22 15:19:33 +03:00
<varlistentry>
<term><option>random-seed</option></term>
bootctl: fix docs/--help to say that "bootctl random-seed" not just initializes but also refreshes ESP random seeds
2023-06-13 17:47:36 +03:00
<listitem><para>Generates a random seed and stores it in the EFI System Partition (ESP), for use by
the <command>systemd-boot</command> boot loader. If a random seed already exists in the ESP it is
refreshed. Also generates a random 'system token' and stores it persistently as an EFI variable, if
one has not been set before. If the boot loader finds the random seed in the ESP and the system token
in the EFI variable it will derive a random seed to pass to the OS and a new seed to store in the ESP
from the combination of both. The random seed passed to the OS is credited to the kernel's entropy
pool by the system manager during early boot, and permits userspace to boot up with an entropy pool
fully initialized very early on. Also see
units: rename/rework systemd-boot-system-token.service → systemd-boot-random-seed.service This renames systemd-boot-system-token.service to systemd-boot-random-seed.service and conditions it less strictly. Previously, the job of the service was to write a "system token" EFI variable if it was missing. It called "bootctl --graceful random-seed" for that. With this change we condition it more liberally: instead of calling it only when the "system token" EFI variable isn't set, we call it whenever a boot loader interface compatible boot loader is used. This means, previously it was invoked on the first boot only: now it is invoked at every boot. This doesn#t change the command that is invoked. That's because previously already the "bootctl --graceful random-seed" did two things: set the system token if not set yet *and* refresh the random seed in the ESP. Previousy we put the focus on the former, now we shift the focus to the latter. With this simple change we can replace the logic f913c784ad4c93894fd6cb2590738113dff5a694 added, but from a service that can run much later and doesn't keep the ESP pinned.
2022-12-20 19:16:47 +03:00
<citerefentry><refentrytitle>systemd-boot-random-seed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
docs: add longer document about systemd and random number seeds
2019-07-22 19:13:26 +03:00
<para>See <ulink url="https://systemd.io/RANDOM_SEEDS">Random Seeds</ulink> for further
man: update version information As I noticed a lot of missing information when trying to implement checking for missing info. I reimplemented the version information script to be more robust, and here is the result. Follow up to ec07c3c80b2b1bfa6788500202006ff85f5ae4f4
2023-09-18 18:03:38 +03:00
information.</para>
<xi:include href="version-info.xml" xpointer="v243"/></listitem>
man: document the systemd-random-seed rework
2019-07-22 15:19:33 +03:00
</varlistentry>
man: re-format man page for bootctl
2018-06-15 09:40:12 +03:00
</variablelist>
</refsect1>
Move the Commands section above Options section For executables which take a verb, we should list the verbs first, and then options which modify those verbs second. The general layout of the man page is from general description to specific details, usually Overview, Commands, Options, Return Value, Examples, References.
2019-10-08 18:58:44 +03:00
<refsect1>
bootctl: change section title for kernel image commands Let's call them kernel *images*, not just *kernels*.
2023-01-20 20:30:06 +03:00
<title>Kernel Image Commands</title>
bootctl: add kernel-identity command The command takes a kernel as argument and checks what kind of kernel the image is. Returns one of uki, pe or unknown.
2023-01-16 20:58:21 +03:00
<variablelist>
<varlistentry>
<term><option>kernel-identify</option> <replaceable>kernel</replaceable></term>
man/bootctl: add missing markup Fixup for 53c368d71ba43da7414ac86c58291a11da05ba84.
2023-01-22 20:40:50 +03:00
<listitem><para>Takes a kernel image as argument. Checks what kind of kernel the image is. Returns
one of <literal>uki</literal>, <literal>pe</literal>, and <literal>unknown</literal>.
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-22 19:52:36 +03:00
</para>
<xi:include href="version-info.xml" xpointer="v253"/></listitem>
bootctl: add kernel-identity command The command takes a kernel as argument and checks what kind of kernel the image is. Returns one of uki, pe or unknown.
2023-01-16 20:58:21 +03:00
</varlistentry>
bootctl: add kernel-inspect command Takes a kernel image as argument. Prints details about the kernel. Signed-off-by: Gerd Hoffmann <kraxel@redhat.com>
2023-01-18 00:06:06 +03:00
<varlistentry>
<term><option>kernel-inspect</option> <replaceable>kernel</replaceable></term>
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-22 19:52:36 +03:00
<listitem><para>Takes a kernel image as argument. Prints details about the image.</para>
<xi:include href="version-info.xml" xpointer="v253"/></listitem>
bootctl: add kernel-inspect command Takes a kernel image as argument. Prints details about the kernel. Signed-off-by: Gerd Hoffmann <kraxel@redhat.com>
2023-01-18 00:06:06 +03:00
</varlistentry>
bootctl: add kernel-identity command The command takes a kernel as argument and checks what kind of kernel the image is. Returns one of uki, pe or unknown.
2023-01-16 20:58:21 +03:00
</variablelist>
</refsect1>
<refsect1>
Move the Commands section above Options section For executables which take a verb, we should list the verbs first, and then options which modify those verbs second. The general layout of the man page is from general description to specific details, usually Overview, Commands, Options, Return Value, Examples, References.
2019-10-08 18:58:44 +03:00
<title>Options</title>
<para>The following options are understood:</para>
<variablelist>
kernel-install: add --esp-path= and --boot-path= options Then, kernel-install takes one more step for compatibility with bootctl.
2023-03-19 20:55:56 +03:00
<xi:include href="standard-options.xml" xpointer="esp-path"/>
<xi:include href="standard-options.xml" xpointer="boot-path"/>
Move the Commands section above Options section For executables which take a verb, we should list the verbs first, and then options which modify those verbs second. The general layout of the man page is from general description to specific details, usually Overview, Commands, Options, Return Value, Examples, References.
2019-10-08 18:58:44 +03:00
bootctl: add --root and --image Operate on image/directory, and also take files to install from it
2022-06-13 02:01:02 +03:00
<varlistentry>
<term><option>--root=<replaceable>root</replaceable></option></term>
<listitem><para>Takes a directory path as an argument. All
paths will be prefixed with the given alternate
<replaceable>root</replaceable> path, including config search
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-22 19:52:36 +03:00
paths. </para>
<xi:include href="version-info.xml" xpointer="v252"/></listitem>
bootctl: add --root and --image Operate on image/directory, and also take files to install from it
2022-06-13 02:01:02 +03:00
</varlistentry>
<varlistentry>
<term><option>--image=<replaceable>image</replaceable></option></term>
man: similar → similarly Something *is* similar Something *works* similarly Something does something, similarly to how something else does something See https://sites.ulethbridge.ca/roussel/2017/11/29/similar-and-similarly-are-they-similar/ for a clear explanation.
2022-08-23 13:12:28 +03:00
<listitem><para>Takes a path to a disk image file or block device node. If specified, all operations
are applied to file system in the indicated disk image. This option is similar to
<option>--root=</option>, but operates on file systems stored in disk images or block devices. The
disk image should either contain just a file system or a set of file systems within a GPT partition
tree-wide: BLS and DPS are now on uapi-group website
2022-11-14 11:44:39 +03:00
table, following the <ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable Partitions
bootctl: add --root and --image Operate on image/directory, and also take files to install from it
2022-06-13 02:01:02 +03:00
Specification</ulink>. For further information on supported disk images, see
<citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-22 19:52:36 +03:00
switch of the same name.</para>
<xi:include href="version-info.xml" xpointer="v252"/></listitem>
bootctl: add --root and --image Operate on image/directory, and also take files to install from it
2022-06-13 02:01:02 +03:00
</varlistentry>
man: document image policy syntax and semantics, and the hooks in the various components
2022-12-02 00:41:47 +03:00
<xi:include href="standard-options.xml" xpointer="image-policy-open" />
bootctl: add --install-source=auto|image|host When using --root=/--image= the binaries to install/update will be picked from the directory/image. Add an option to let the caller choose. By default (auto) the image is tried first, and if nothing is found then the host. The other options allow to strictly try the image or host and ignore the other.
2022-06-13 02:21:41 +03:00
<varlistentry>
<term><option>--install-source=</option></term>
<listitem><para>When installing binaries with <option>--root=</option> or
<option>--image=</option>, selects where to source them from. Takes one of <literal>auto</literal>
(the default), <literal>image</literal> or <literal>host</literal>. With <literal>auto</literal>
binaries will be picked from the specified directory or image, and if not found they will be picked
from the host. With <literal>image</literal> or <literal>host</literal> no fallback search will be
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-22 19:52:36 +03:00
performed if the binaries are not found in the selected source.</para>
<xi:include href="version-info.xml" xpointer="v252"/></listitem>
bootctl: add --install-source=auto|image|host When using --root=/--image= the binaries to install/update will be picked from the directory/image. Add an option to let the caller choose. By default (auto) the image is tried first, and if nothing is found then the host. The other options allow to strictly try the image or host and ignore the other.
2022-06-13 02:21:41 +03:00
</varlistentry>
Move the Commands section above Options section For executables which take a verb, we should list the verbs first, and then options which modify those verbs second. The general layout of the man page is from general description to specific details, usually Overview, Commands, Options, Return Value, Examples, References.
2019-10-08 18:58:44 +03:00
<varlistentry>
<term><option>-p</option></term>
<term><option>--print-esp-path</option></term>
<listitem><para>This option modifies the behaviour of <command>status</command>. Only prints the path
man: update version information As I noticed a lot of missing information when trying to implement checking for missing info. I reimplemented the version information script to be more robust, and here is the result. Follow up to ec07c3c80b2b1bfa6788500202006ff85f5ae4f4
2023-09-18 18:03:38 +03:00
to the EFI System Partition (ESP) to standard output and exits.</para>
<xi:include href="version-info.xml" xpointer="v236"/></listitem>
Move the Commands section above Options section For executables which take a verb, we should list the verbs first, and then options which modify those verbs second. The general layout of the man page is from general description to specific details, usually Overview, Commands, Options, Return Value, Examples, References.
2019-10-08 18:58:44 +03:00
</varlistentry>
<varlistentry>
<term><option>-x</option></term>
<term><option>--print-boot-path</option></term>
<listitem><para>This option modifies the behaviour of <command>status</command>. Only prints the path
to the Extended Boot Loader partition if it exists, and the path to the ESP otherwise to standard
output and exit. This command is useful to determine where to place boot loader entries, as they are
preferably placed in the Extended Boot Loader partition if it exists and in the ESP otherwise.</para>
<para>Boot Loader Specification Type #1 entries should generally be placed in the directory
<literal>$(bootctl -x)/loader/entries/</literal>. Existence of that directory may also be used as
indication that boot loader entry support is available on the system. Similarly, Boot Loader
Specification Type #2 entries should be placed in the directory <literal>$(bootctl
-x)/EFI/Linux/</literal>.</para>
man/bootctl: typo in `--print-boot-path` description
2024-01-23 12:33:26 +03:00
<para>Note that this option (similarly to the <option>--print-esp-path</option> option mentioned
Move the Commands section above Options section For executables which take a verb, we should list the verbs first, and then options which modify those verbs second. The general layout of the man page is from general description to specific details, usually Overview, Commands, Options, Return Value, Examples, References.
2019-10-08 18:58:44 +03:00
above), is available independently from the boot loader used, i.e. also without
man: update version information As I noticed a lot of missing information when trying to implement checking for missing info. I reimplemented the version information script to be more robust, and here is the result. Follow up to ec07c3c80b2b1bfa6788500202006ff85f5ae4f4
2023-09-18 18:03:38 +03:00
<command>systemd-boot</command> being installed.</para>
<xi:include href="version-info.xml" xpointer="v242"/></listitem>
Move the Commands section above Options section For executables which take a verb, we should list the verbs first, and then options which modify those verbs second. The general layout of the man page is from general description to specific details, usually Overview, Commands, Options, Return Value, Examples, References.
2019-10-08 18:58:44 +03:00
</varlistentry>
bootctl: add new --print-root-device option We already have this nice code in system that determines the block device backing the root file system, but it's only used internally in systemd-gpt-generator. Let's make this more accessible and expose it directly in bootctl. It doesn't fit immediately into the topic of bootctl, but I think it's close enough and behaves very similar to the existing "bootctl --print-boot-path" and "--print-esp-path" tools. If --print-root-device (or -R) is specified once, will show the block device backing the root fs, and if specified twice (probably easier: -RR) it will show the whole block device that block device belongs to in case it is a partition block device. Suggested use: # cfdisk `bootctl -RR` To get access to the partition table, behind the OS install, for whatever it might be.
2023-02-20 19:25:14 +03:00
<varlistentry>
<term><option>-R</option></term>
<term><option>--print-root-device</option></term>
<listitem><para>Print the path to the block device node backing the root file system of the local
OS. This prints a path such as <filename>/dev/nvme0n1p5</filename>. If the root file system is backed
by dm-crypt/LUKS or dm-verity the underlying block device is returned. If the root file system is
backed by multiple block devices (as supported by btrfs) the operation will fail. If the switch is
specified twice (i.e. <option>-RR</option>) and the discovered block device is a partition device the
"whole" block device it belongs to is determined and printed
(e.g. <filename>/dev/nvme0n1</filename>). If the root file system is <literal>tmpfs</literal> (or a
similar in-memory file system), the block device backing <filename>/usr/</filename> is returned if
applicable. If the root file system is a network file system (e.g. NFS, CIFS) the operation will
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-22 19:52:36 +03:00
fail.</para>
<xi:include href="version-info.xml" xpointer="v254"/></listitem>
bootctl: add new --print-root-device option We already have this nice code in system that determines the block device backing the root file system, but it's only used internally in systemd-gpt-generator. Let's make this more accessible and expose it directly in bootctl. It doesn't fit immediately into the topic of bootctl, but I think it's close enough and behaves very similar to the existing "bootctl --print-boot-path" and "--print-esp-path" tools. If --print-root-device (or -R) is specified once, will show the block device backing the root fs, and if specified twice (probably easier: -RR) it will show the whole block device that block device belongs to in case it is a partition block device. Suggested use: # cfdisk `bootctl -RR` To get access to the partition table, behind the OS install, for whatever it might be.
2023-02-20 19:25:14 +03:00
</varlistentry>
Move the Commands section above Options section For executables which take a verb, we should list the verbs first, and then options which modify those verbs second. The general layout of the man page is from general description to specific details, usually Overview, Commands, Options, Return Value, Examples, References.
2019-10-08 18:58:44 +03:00
<varlistentry>
<term><option>--no-variables</option></term>
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-22 19:52:36 +03:00
<listitem><para>Do not touch the firmware's boot loader list stored in EFI variables.</para>
<xi:include href="version-info.xml" xpointer="v220"/></listitem>
Move the Commands section above Options section For executables which take a verb, we should list the verbs first, and then options which modify those verbs second. The general layout of the man page is from general description to specific details, usually Overview, Commands, Options, Return Value, Examples, References.
2019-10-08 18:58:44 +03:00
</varlistentry>
bootctl: make 'random-seed' handle inability to write system token EFI variable gracefully Apparently some firmwares don't allow us to write this token, and refuse it with EINVAL. We should normally consider that a fatal error, but not really in the case of "bootctl random-seed" when called from the systemd-boot-system-token.service since it's called as "best effort" service after boot on various systems, and hence we shouldn't fail loudly. Similar, when we cannot find the ESP don't fail either, since there are systems (arch install ISOs) that carry a boot loader capable of the random seed logic but don't mount it after boot. Fixes: #13603
2019-11-19 18:33:22 +03:00
<varlistentry>
<term><option>--graceful</option></term>
bootctl: tweak "bootctl update" to be a NOP when boot loader is already current and --graceful is given Previously, the "bootctl update" logic would refrain from downrgading a boot loader, but if the boot loader that is installed already matched the version we could install we'd install it anyway, under the assumption this was effectively without effect. This behaviour was handy while developing boot loaders, since installing a modified boot loader didn't require a version bump. However, outside of the systems of boot loader developers I don't think this behaviour makes much sense: we should always emphasize doing minimal changes to the ESP, hence when an update is supposedly not necessary, then don't do it. Only update if it really makes sense, to minimize writes to the ESP. Updating the boot loader is a good thing after all, but doing so redundantly is not. Also, downgrade the message about this to LOG_NOTICE, given this shouldn't be a reason to log. Finally, exit cleanly in this cases (or if another boot loader is detected)
2021-07-02 16:16:52 +03:00
<listitem><para>Ignore failure when the EFI System Partition cannot be found, when EFI variables
cannot be written, or a different or newer boot loader is already installed. Currently only applies
bootctl: support --graceful in is-installed
2022-05-05 13:15:46 +03:00
to <command>is-installed</command>, <command>update</command>, and <command>random-seed</command>
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-22 19:52:36 +03:00
verbs.</para>
<xi:include href="version-info.xml" xpointer="v244"/></listitem>
bootctl: make 'random-seed' handle inability to write system token EFI variable gracefully Apparently some firmwares don't allow us to write this token, and refuse it with EINVAL. We should normally consider that a fatal error, but not really in the case of "bootctl random-seed" when called from the systemd-boot-system-token.service since it's called as "best effort" service after boot on various systems, and hence we shouldn't fail loudly. Similar, when we cannot find the ESP don't fail either, since there are systems (arch install ISOs) that carry a boot loader capable of the random seed logic but don't mount it after boot. Fixes: #13603
2019-11-19 18:33:22 +03:00
</varlistentry>
bootctl: add --quiet It's useful for installation scripts and suchlike. Raised in https://bugzilla.redhat.com/show_bug.cgi?id=2079784#c9.
2022-05-05 13:28:32 +03:00
<varlistentry>
<term><option>-q</option></term>
<term><option>--quiet</option></term>
<listitem><para>Suppress printing of the results of various commands and also the hints about ESP
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-22 19:52:36 +03:00
being unavailable.</para>
<xi:include href="version-info.xml" xpointer="v251"/></listitem>
bootctl: add --quiet It's useful for installation scripts and suchlike. Raised in https://bugzilla.redhat.com/show_bug.cgi?id=2079784#c9.
2022-05-05 13:28:32 +03:00
</varlistentry>
bootctl: take --make-machine-id-directory=yes|no|auto and make/remove \$MACHINE_ID accordingly auto resolves to yes if /etc/machine-id resides on non-tmpfs This effectively reverts commit 31e57550b552e113bd3d44355b237c41e42beb58
2021-03-17 20:58:07 +03:00
<varlistentry>
bootctl: update to new kernel-install semantics This makes a bunch of closely related changes: 1. The "entry-token" concept already introduced in kernel-install is now made use of. i.e. specifically there's a new option --entry-token= that can be used to explicitly select by which ID to identify boot loader entries: the machine ID, or some OS ID (ID= or IMAGE_ID= from /etc/os-release, or even some completely different string. The selected string is then persisted to /etc/kernel/entry-token, so that kernel-install can find it there. 2. The --make-machine-id-directory= switch is renamed to --make-entry-directory= since after all it's not necessarily the machine ID the dir is named after, but can be any other string as selected by the entry token. 3. This drops all code to make automatic changes to /etc/machine-info. Specifically, the KERNEL_INSTALL_MACHINE_ID= field is now more generically implemented in /etc/kernel/entry-token described above, hence no need to place it at two locations. And the KERNEL_INSTALL_LAYOUT= field is not configurable by user switch or similar anyway in bootctl, but only read from /etc/kernel/install.conf, and hence copying it from one configuration file to another appears unnecessary, the second copy is fully redundant. Note that this just drops writing these fields, they'll still be honoured when already set.
2022-02-10 20:01:36 +03:00
<term><option>--make-entry-directory=yes|no</option></term>
<listitem><para>Controls creation and deletion of the <ulink
tree-wide: BLS and DPS are now on uapi-group website
2022-11-14 11:44:39 +03:00
url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader Specification</ulink> Type #1 entry
man: "the initial RAM disk" → "the initrd" In many places we spelled out the phrase behind "initrd" in full, but this isn't terribly useful. In fact, no "RAM disk" is used, so emphasizing this is just confusing to the reader. Let's just say "initrd" everywhere, people understand what this refers to, and that it's in fact an initramfs image. Also, s/i.e./e.g./ where appropriate. Also, don't say "in RAM", when in fact it's virtual memory, whose pages may or may not be loaded in page frames in RAM, and we have no control over this. Also, add <filename></filename> and other minor cleanups.
2022-09-15 15:43:59 +03:00
directory on the file system containing resources such as kernel and initrd images during
<option>install</option> and <option>remove</option>, respectively. The directory is named after the
entry token, as specified with <option>--entry-token=</option> parameter described below, and is
placed immediately below the <varname>$BOOT</varname> root directory (i.e. beneath the file system
returned by the <option>--print-boot-path</option> option, see above). Defaults to
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-22 19:52:36 +03:00
<literal>no</literal>.</para>
<xi:include href="version-info.xml" xpointer="v251"/></listitem>
bootctl: update to new kernel-install semantics This makes a bunch of closely related changes: 1. The "entry-token" concept already introduced in kernel-install is now made use of. i.e. specifically there's a new option --entry-token= that can be used to explicitly select by which ID to identify boot loader entries: the machine ID, or some OS ID (ID= or IMAGE_ID= from /etc/os-release, or even some completely different string. The selected string is then persisted to /etc/kernel/entry-token, so that kernel-install can find it there. 2. The --make-machine-id-directory= switch is renamed to --make-entry-directory= since after all it's not necessarily the machine ID the dir is named after, but can be any other string as selected by the entry token. 3. This drops all code to make automatic changes to /etc/machine-info. Specifically, the KERNEL_INSTALL_MACHINE_ID= field is now more generically implemented in /etc/kernel/entry-token described above, hence no need to place it at two locations. And the KERNEL_INSTALL_LAYOUT= field is not configurable by user switch or similar anyway in bootctl, but only read from /etc/kernel/install.conf, and hence copying it from one configuration file to another appears unnecessary, the second copy is fully redundant. Note that this just drops writing these fields, they'll still be honoured when already set.
2022-02-10 20:01:36 +03:00
</varlistentry>
<varlistentry>
<term><option>--entry-token=</option></term>
<listitem><para>Controls how to name and identify boot loader entries for this OS
installation. Accepted during <option>install</option>, and takes one of <literal>auto</literal>,
<literal>machine-id</literal>, <literal>os-id</literal>, <literal>os-image-id</literal> or an
arbitrary string prefixed by <literal>literal:</literal> as argument.</para>
<para>If set to <option>machine-id</option> the entries are named after the machine ID of the running
system (e.g. <literal>b0e793a9baf14b5fa13ecbe84ff637ac</literal>). See
bootctl: extend --make-machine-id-directory= documentation a bit The directory might not be created in the ESP but in the extended boot loader partition, hence don#t claim otherwise. Also, give a brief reason why the concept exists at all. Link up machine-id man page. Follow-up for: 6a3fff75baad94d9ebff1a6c7d1fb35448c44a81
2021-05-10 20:03:49 +03:00
<citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
details about the machine ID concept and file.</para>
bootctl: update to new kernel-install semantics This makes a bunch of closely related changes: 1. The "entry-token" concept already introduced in kernel-install is now made use of. i.e. specifically there's a new option --entry-token= that can be used to explicitly select by which ID to identify boot loader entries: the machine ID, or some OS ID (ID= or IMAGE_ID= from /etc/os-release, or even some completely different string. The selected string is then persisted to /etc/kernel/entry-token, so that kernel-install can find it there. 2. The --make-machine-id-directory= switch is renamed to --make-entry-directory= since after all it's not necessarily the machine ID the dir is named after, but can be any other string as selected by the entry token. 3. This drops all code to make automatic changes to /etc/machine-info. Specifically, the KERNEL_INSTALL_MACHINE_ID= field is now more generically implemented in /etc/kernel/entry-token described above, hence no need to place it at two locations. And the KERNEL_INSTALL_LAYOUT= field is not configurable by user switch or similar anyway in bootctl, but only read from /etc/kernel/install.conf, and hence copying it from one configuration file to another appears unnecessary, the second copy is fully redundant. Note that this just drops writing these fields, they'll still be honoured when already set.
2022-02-10 20:01:36 +03:00
<para>If set to <option>os-id</option> the entries are named after the OS ID of the running system,
i.e. the <varname>ID=</varname> field of
man: similar → similarly Something *is* similar Something *works* similarly Something does something, similarly to how something else does something See https://sites.ulethbridge.ca/roussel/2017/11/29/similar-and-similarly-are-they-similar/ for a clear explanation.
2022-08-23 13:12:28 +03:00
<citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry> (e.g.
<literal>fedora</literal>). Similarly, if set to <option>os-image-id</option> the entries are named
after the OS image ID of the running system, i.e. the <varname>IMAGE_ID=</varname> field of
bootctl: update to new kernel-install semantics This makes a bunch of closely related changes: 1. The "entry-token" concept already introduced in kernel-install is now made use of. i.e. specifically there's a new option --entry-token= that can be used to explicitly select by which ID to identify boot loader entries: the machine ID, or some OS ID (ID= or IMAGE_ID= from /etc/os-release, or even some completely different string. The selected string is then persisted to /etc/kernel/entry-token, so that kernel-install can find it there. 2. The --make-machine-id-directory= switch is renamed to --make-entry-directory= since after all it's not necessarily the machine ID the dir is named after, but can be any other string as selected by the entry token. 3. This drops all code to make automatic changes to /etc/machine-info. Specifically, the KERNEL_INSTALL_MACHINE_ID= field is now more generically implemented in /etc/kernel/entry-token described above, hence no need to place it at two locations. And the KERNEL_INSTALL_LAYOUT= field is not configurable by user switch or similar anyway in bootctl, but only read from /etc/kernel/install.conf, and hence copying it from one configuration file to another appears unnecessary, the second copy is fully redundant. Note that this just drops writing these fields, they'll still be honoured when already set.
2022-02-10 20:01:36 +03:00
<filename>os-release</filename> (e.g. <literal>vendorx-cashier-system</literal>).</para>
<para>If set to <option>auto</option> (the default), the <filename>/etc/kernel/entry-token</filename>
file will be read if it exists, and the stored value used. Otherwise if the local machine ID is
initialized it is used. Otherwise <varname>IMAGE_ID=</varname> from <filename>os-release</filename>
will be used, if set. Otherwise, <varname>ID=</varname> from <filename>os-release</filename> will be
used, if set.</para>
<para>Unless set to <literal>machine-id</literal>, or when
<option>--make-entry-directory=yes</option> is used the selected token string is written to a file
<filename>/etc/kernel/entry-token</filename>, to ensure it will be used for future entries. This file
is also read by
<citerefentry><refentrytitle>kernel-install</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
in order to identify under which name to generate boot loader entries for newly installed kernels, or
to determine the entry names for removing old ones.</para>
<para>Using the machine ID for naming the entries is generally preferable, however there are cases
where using the other identifiers is a good option. Specifically: if the identification data that the
machine ID entails shall not be stored on the (unencrypted) <varname>$BOOT</varname> partition, or if
the ID shall be generated on first boot and is not known when the entries are prepared. Note that
using the machine ID has the benefit that multiple parallel installations of the same OS can coexist
on the same medium, and they can update their boot loader entries independently. When using another
identifier (such as the OS ID or the OS image ID), parallel installations of the same OS would try to
use the same entry name. To support parallel installations, the installer must use a different entry
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-22 19:52:36 +03:00
token when adding a second installation.</para>
<xi:include href="version-info.xml" xpointer="v251"/></listitem>
bootctl: take --make-machine-id-directory=yes|no|auto and make/remove \$MACHINE_ID accordingly auto resolves to yes if /etc/machine-id resides on non-tmpfs This effectively reverts commit 31e57550b552e113bd3d44355b237c41e42beb58
2021-03-17 20:58:07 +03:00
</varlistentry>
bootctl: Add EFI arch detection support
2022-02-17 15:40:25 +03:00
<varlistentry>
<term><option>--all-architectures</option></term>
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-22 19:52:36 +03:00
<listitem><para>Install binaries for all supported EFI architectures (this implies <option>--no-variables</option>).</para>
<xi:include href="version-info.xml" xpointer="v252"/></listitem>
bootctl: Add EFI arch detection support
2022-02-17 15:40:25 +03:00
</varlistentry>
Add --efi-boot-option-description argument to bootctl to control the name of the boot entry. By default an entry named "Linux Boot Manager" is created (which is the previous behavior). With the flag the name of the entry can be controlled, which is useful when installing systemd-boot to multiple ESP partitions and having uniquely named entries. Fixes #17044.
2022-08-13 22:38:02 +03:00
<varlistentry>
<term><option>--efi-boot-option-description=</option></term>
<listitem><para>Description of the entry added to the firmware's boot option list. Defaults to <literal>Linux
Boot Manager</literal>.</para>
<para>Using the default entry name <literal>Linux Boot Manager</literal> is generally preferable as only
one bootloader installed to a single ESP partition should be used to boot any number of OS installations
found on the various disks installed in the system. Specifically distributions should not use this flag
to install a branded entry in the boot option list. However in situations with multiple disks, each with
their own ESP partition, it can be beneficial to make it easier to identify the bootloader being used in
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-22 19:52:36 +03:00
the firmware's boot option menu.</para>
<xi:include href="version-info.xml" xpointer="v252"/></listitem>
Add --efi-boot-option-description argument to bootctl to control the name of the boot entry. By default an entry named "Linux Boot Manager" is created (which is the previous behavior). With the flag the name of the entry can be controlled, which is useful when installing systemd-boot to multiple ESP partitions and having uniquely named entries. Fixes #17044.
2022-08-13 22:38:02 +03:00
</varlistentry>
bootctl: unlink and cleanup functions The unlink command removes an entry from the ESP including referenced files that are not referenced in other entries. That is useful eg to have multiple entries that use the same kernel with different options. The cleanup command removes all files that are not referenced by any entry.
2022-12-08 18:27:31 +03:00
<varlistentry>
<term><option>--dry-run</option></term>
man/bootctl: fix --dry-run entry Fixes 8702496bfb0205764569782a9a2ebd11fd80e5e8
2023-11-06 18:32:49 +03:00
<listitem><para>Dry run for <option>unlink</option> and <option>cleanup</option>.</para>
bootctl: unlink and cleanup functions The unlink command removes an entry from the ESP including referenced files that are not referenced in other entries. That is useful eg to have multiple entries that use the same kernel with different options. The cleanup command removes all files that are not referenced by any entry.
2022-12-08 18:27:31 +03:00
<para>In dry run mode, the unlink and cleanup operations only print the files that would get deleted
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-22 19:52:36 +03:00
without actually deleting them.</para>
<xi:include href="version-info.xml" xpointer="v253"/></listitem>
bootctl: unlink and cleanup functions The unlink command removes an entry from the ESP including referenced files that are not referenced in other entries. That is useful eg to have multiple entries that use the same kernel with different options. The cleanup command removes all files that are not referenced by any entry.
2022-12-08 18:27:31 +03:00
</varlistentry>
Move the Commands section above Options section For executables which take a verb, we should list the verbs first, and then options which modify those verbs second. The general layout of the man page is from general description to specific details, usually Overview, Commands, Options, Return Value, Examples, References.
2019-10-08 18:58:44 +03:00
<xi:include href="standard-options.xml" xpointer="no-pager"/>
bootctl: optionally, output entries in JSON format Replaces: #18387 Fixes: #18094
2022-03-23 18:08:36 +03:00
<xi:include href="standard-options.xml" xpointer="json" />
Move the Commands section above Options section For executables which take a verb, we should list the verbs first, and then options which modify those verbs second. The general layout of the man page is from general description to specific details, usually Overview, Commands, Options, Return Value, Examples, References.
2019-10-08 18:58:44 +03:00
<xi:include href="standard-options.xml" xpointer="help"/>
<xi:include href="standard-options.xml" xpointer="version"/>
</variablelist>
</refsect1>
bootctl: optionally install .signed efi file if /usr/lib/systemd/boot/efi/systemd-bootx64.efi.signed exists install that instead of /usr/lib/systemd/boot/efi/systemd-bootx64.efi the idea is that SecureBoot tooling can create the efi.signed file whenever /usr/lib/systemd/boot/efi/systemd-bootx64.efi from the package is updated.
2021-11-30 00:44:01 +03:00
<refsect1>
<title>Signed .efi files</title>
<para><command>bootctl</command> <option>install</option> and <option>update</option> will look for a
<command>systemd-boot</command> file ending with the <literal>.efi.signed</literal> suffix first, and copy
that instead of the normal <literal>.efi</literal> file. This allows distributions or end-users to provide
signed images for UEFI SecureBoot.</para>
</refsect1>
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
<refsect1>
<title>Exit status</title>
bootctl: add new --print-root-device option We already have this nice code in system that determines the block device backing the root file system, but it's only used internally in systemd-gpt-generator. Let's make this more accessible and expose it directly in bootctl. It doesn't fit immediately into the topic of bootctl, but I think it's close enough and behaves very similar to the existing "bootctl --print-boot-path" and "--print-esp-path" tools. If --print-root-device (or -R) is specified once, will show the block device backing the root fs, and if specified twice (probably easier: -RR) it will show the whole block device that block device belongs to in case it is a partition block device. Suggested use: # cfdisk `bootctl -RR` To get access to the partition table, behind the OS install, for whatever it might be.
2023-02-20 19:25:14 +03:00
<para>On success, 0 is returned, a non-zero failure code otherwise. <command>bootctl
--print-root-device</command> returns exit status 80 in case the root file system is not backed by single
tree-wide: fix typo
2023-02-22 08:46:19 +03:00
block device, and other non-zero exit statuses on other errors.</para>
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
</refsect1>
efi: allow ESP validity checks to be turned off let's add an env var for this, as this really shouldn't be a top-level feature, as it turning off the validity checks certainly isn't advisable. Fixes: #4925
2018-06-25 16:08:24 +03:00
<refsect1>
<title>Environment</title>
man: document XBOOTLDR partition logic in bootctl's man page
2019-02-12 18:22:31 +03:00
<para>If <varname>$SYSTEMD_RELAX_ESP_CHECKS=1</varname> is set the validation checks for the ESP are
relaxed, and the path specified with <option>--esp-path=</option> may refer to any kind of file system on
any kind of partition.</para>
<para>Similarly, <varname>$SYSTEMD_RELAX_XBOOTLDR_CHECKS=1</varname> turns off some validation checks for
the Extended Boot Loader partition.</para>
efi: allow ESP validity checks to be turned off let's add an env var for this, as this really shouldn't be a top-level feature, as it turning off the validity checks certainly isn't advisable. Fixes: #4925
2018-06-25 16:08:24 +03:00
</refsect1>
man: add annotated example for bootctl status & list This is based on the output on my laptop, with various manual adjustments. If people have other types of entries, it'd be useful to add them here. In particular, some dual-boot entries would be nice.
2022-04-04 11:45:47 +03:00
<refsect1>
<title>Examples</title>
<example>
<title>Output from <command>status</command> and <command>list</command></title>
<programlisting>$ <command>bootctl status</command>
System:
Firmware: UEFI 2.40 (<replaceable>firmware-version</replaceable>) ← firmware vendor and version
man: fix issues reported by the manpage-l10n project Fixes #25780. > Man page: crypttab.5 > Issue 1: Missing fullstop > Issue 2: I<cipher=>, I<hash=>, I<size=> → B<cipher=>, B<hash=>, B<size=> > > "Force LUKS mode\\&. When this mode is used, the following options are " > "ignored since they are provided by the LUKS header on the device: " > "I<cipher=>, I<hash=>, I<size=>" Seems OK to me. The full stop is there and has been for at least a few years. And we use <option> for the markup, which is appropriate here. > Man page: crypttab.5 > Issue 1: Missing fullstop > Issue 2: I<cipher=>, I<hash=>, I<keyfile-offset=>, I<keyfile-size=>, I<size=> → B<cipher=>, B<hash=>, B<keyfile-offset=>, B<keyfile-size=>, B<size=> > > "Use TrueCrypt encryption mode\\&. When this mode is used, the following " > "options are ignored since they are provided by the TrueCrypt header on the " > "device or do not apply: I<cipher=>, I<hash=>, I<keyfile-offset=>, I<keyfile-" > "size=>, I<size=>" Same. > Man page: journalctl.1 > Issue 1: make be → may be Fixed. > Issue 2: below\\&. → below: Fixed. > Man page: journalctl.1 > Issue: Colon at the end? > > "The following commands are understood\\&. If none is specified the default " > "is to display journal records\\&." > msgstr "" > "Die folgenden Befehle werden verstanden\\&. Falls keiner festgelegt ist, ist " > "die Anzeige von Journal-Datensätzen die Vorgabe\\&." This is a bit awkward, but I'm not sure how to fix it. > Man page: kernel-install.8 > Issue: methods a fallback → methods fallback It was correct, but I added a comma to make the sense clearer. > Man page: loader.conf.5 > Issue 1: secure boot variables → Secure Boot variables > Issue 2: one → one for (multiple times) > > "Supported secure boot variables are one database for authorized images, one " > "key exchange key (KEK) and one platform key (PK)\\&. For more information, " > "refer to the \\m[blue]B<UEFI specification>\\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]B<EDK2 " > "documentation>\\m[]\\&\\s-2\\u[3]\\d\\s+2\\&." "one of" would sound strange. "One this and one that" is OK. > Man page: loader.conf.5 > Issue: systemd-boot → B<systemd-boot>(7) Fixed. > Man page: logind.conf.5 > Issue: systemd-logind → B<systemd-logind>(8) We use <filename>systemd-logind</> on subsequent references… I think that's good enough. > Man page: nss-myhostname.8 > Issue: B<getent> → B<getent>(1) Fixed. > Man page: nss-resolve.8 > Issue: B<systemd-resolved> → B<systemd-resolved>(8) The first reference does this, subsequent are shorter. > Man page: os-release.5 > Issue: Portable Services → Portable Services Documentation? Updated. > Man page: pam_systemd_home.8 > Issue: auth and account use "reason", while session and password do not? Reworded. > Man page: portablectl.1 > Issue: In systemd-portabled.service(8): Portable Services Documentation Updated. > Man page: repart.d.5 > Issue: The partition → the partition Fixed. > Man page: repart.d.5 > Issue: B<systemd-repart> → B<systemd-repart>(8) The first reference does this. I also change this one, because it's pretty far down in the text. > Man page: systemd.1 > Issue: kernel command line twice? > > "Takes a boolean argument\\&. If false disables importing credentials from " > "the kernel command line, qemu_fw_cfg subsystem or the kernel command line\\&." Apparently this was fixed already. > Man page: systemd-boot.7 > Issue: enrollement → enrollment Fixed. > Man page: systemd-cryptenroll.1 > Issue: multiple cases: any specified → the specified Reworded. > Man page: systemd-cryptenroll.1 > Issue: If this this → If this Fixed tree-wide. > Man page: systemd-cryptsetup-generator.8 > Issue: and the initrd → and in the initrd "Is honoured by the initrd" is OK, because we often speak about the initrd as a single unit. But in the same paragraph we also used "in the initrd", which makes the other use look sloppy. I changed it to "in the initrd" everywhere in that file. > Man page: systemd.directives.7 > Issue: Why are these two quoted (but not others)? > > "B<\\*(Aqh\\*(Aq>" > > B<\\*(Aqs\\*(Aq>" > > "B<\\*(Aqy\\*(Aq>" This is autogenerated from files… We use slightly different markup in different files, and it's just too hard to make it consistent. We gave up on this. > Man page: systemd.exec.5 > Issue 1: B<at>(1p) → B<at>(1) > Issue 2: B<crontab>(1p) → B<crontab>(1) Fixed. > Man page: systemd.exec.5 > Issue: B<select()> → B<select>(2) Fixed. > Man page: systemd.exec.5 > Issue: qemu → B<qemu>(1) The man page doesn't seem to be in any of the canonical places on the web. I added a link to online docs. > Man page: systemd.exec.5 > Issue: variable → variables Seems to be fixed already. > Man page: systemd-integritysetup-generator.8 > Issue: systemd-integritysetup-generator → B<systemd-integritysetup-generator> I changed <filename> to <command>. > Man page: systemd-integritysetup-generator.8 > Issue: superfluous comma at the end Already fixed. > Man page: systemd-measure.1 > Issue: (see B<--pcr-bank=>) below → (see B<--pcr-bank=> below) Reworded. > Man page: systemd-measure.1 > Issue: =PATH> → =>I<PATH> Fixed. > Man page: systemd-measure.1.po > Issue: B<--bank=DIGEST> → B<--bank=>I<DIGEST> Fixed. > Man page: systemd.netdev.5 > Issue: os the → on the Appears to have been fixed already. > Man page: systemd.netdev.5 > Issue: Onboard → On-board (as in previous string) Updated. > Man page: systemd.network.5 > Issue: B<systemd-networkd> -> B<systemd-networkd>(8) First reference does this, subsequent do not. > Man page: systemd.network.5 > Issue: B<netlabelctl> → B<netlabelctl>(8) First reference does this, subsequent do not. > Man page: systemd.network.5 > Issue: Missing verb (aquired? configured?) in the half sentence starting with "or by a " I dropped the comma. > Man page: systemd-nspawn.1 > Issue: All host users outside of that range → All other host users Reworded. > # FIXME no effect → no effect\\&. > #. type: Plain text > #: archlinux debian-unstable fedora-rawhide mageia-cauldron opensuse-tumbleweed > msgid "" > "Whichever ID mapping option is used, the same mapping will be used for users " > "and groups IDs\\&. If B<rootidmap> is used, the group owning the bind " > "mounted directory will have no effect" A period is added. Not sure if there's some other issue. > Man page: systemd-oomd.service.8 > Issue: B<systemd> → B<systemd>(1) Done. > Man page: systemd.path.5 > Issue 1: B<systemd.exec>(1) → B<systemd.exec>(5) > Issue 2: This section does not (yet?) exist Fixed. > Man page: systemd-pcrphase.service.8 > Issue 1: indicate phases into TPM2 PCR 11 ?? > Issue 2: Colon at the end of the paragraph? Fixed. > Man page: systemd-pcrphase.service.8 > Issue: final boot phase → final shutdown phase? Updated. > Man page: systemd-pcrphase.service.8 > Issue: for the the → for the Fixed tree-wide. > Man page: systemd-portabled.service.8 > Issue: In systemd-portabled.service(8): Portable Services Documentation Updated. > Man page: systemd-pstore.service.8 > Issue: Here and the following paragraphs: . → \\&. // Upstream: What does this comment mean? // You normally write \\&. for a full dot (full stop etc.); here you write only "." (i.e. a plain dot). > > "and we look up \"localhost\", nss-dns will send the following queries to " > "systemd-resolved listening on 127.0.0.53:53: first \"localhost.foobar.com\", " > "then \"localhost.barbar.com\", and finally \"localhost\". If (hopefully) the " > "first two queries fail, systemd-resolved will synthesize an answer for the " > "third query." Looks all OK to me. > Man page: systemd.resource-control.5 > Issue: Missing closing bracket after link to Control Groups version 1 Fixed. > Man page: systemd-sysext.8 > Issue: In systemd-portabled.service(8): Portable Services Documentation Updated. > Man page: systemd.timer.5 > Issue 1: B<systemd.exec>(1) → B<systemd.exec>(5) > Issue 2: This section does not (yet?) exist Fixed. > Man page: systemd.unit.5 > Issue: that is → that are Fixed. > Man page: systemd-veritysetup-generator.8 > Issue: systemd-veritysetup-generator → B<systemd-veritysetup-generator> > > "systemd-veritysetup-generator implements B<systemd.generator>(7)\\&." > > "systemd-veritysetup-generator understands the following kernel command line " > "parameters:" Updated. > Man page: systemd-volatile-root.service.8 > Issue: initrdyes → Initrd Fixed. > Man page: sysupdate.d.5 > Issue: : → \\&. (As above in TRANSFER) Updated. > Man page: sysupdate.d.5 > Issue: some → certain Updated. > Man page: sysupdate.d.5 > Issue 1: i\\&.e\\& → I\\&.e\\& Fixed. > Issue 2: the image → the system "image" seems correct. > Man page: tmpfiles.d.5 > Issue: systemd-tmpfiles → B<systemd-tmpfiles>(8) Updated.
2023-01-11 18:45:59 +03:00
Secure Boot: disabled (setup) ← Secure Boot status
man: add annotated example for bootctl status & list This is based on the output on my laptop, with various manual adjustments. If people have other types of entries, it'd be useful to add them here. In particular, some dual-boot entries would be nice.
2022-04-04 11:45:47 +03:00
TPM2 Support: yes
Boot into FW: supported ← does the firmware support booting into itself
Current Boot Loader: ← details about sd-boot or another boot loader
Product: systemd-boot <replaceable>version</replaceable> implementing the <ulink
url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink>
Features: ✓ Boot counting
✓ Menu timeout control
✓ One-shot menu timeout control
✓ Default entry control
✓ One-shot entry control
✓ Support for XBOOTLDR partition
✓ Support for passing random seed to OS
✓ Load drop-in drivers
✓ Boot loader sets ESP information
sd-boot: add way to disable the 100ms delay when timeout=0 Currently we have a 100ms delay which allows for people to enter/show the boot menu even when timeout is set to zero. In a handful of cases, that may not be needed - both in terms of access policy, as well as latency. For example: the option to provide the boot menu may be hidden behind an "expert only" UX in the OS, to avoid end users from accidentally entering it. In addition, the current 100ms input polling may cause unexpected additional delays in the boot. Some example numbers from my SteamDeck: - boot counting/rename/flush doubles 300us -> 600us - seed/hash setup doubles 900us -> 1800us - kernel/image load gets ~40% slower 107ms -> 167ms It's not entirely clear why the UEFI calls gets slower, nevertheless the information in itself proves useful. This commit introduces a new option "menu-disabled", which omits the 100ms delay. The option is documented throughout the manual pages as well as the Boot Loader Specification. v2: - use STR_IN_SET v3: - drop erroneous whitespace v4: - add a new LoaderFeature bit, - don't change ABI keep TIMEOUT_* tokens the same - move new token in the 64bit range, update API and storage for it - change inc/dec behaviour to TIMEOUT_MIN : TIMEOUT_MENU_FORCE - user cannot opt-in from sd-boot itself, add assert_not_reached() v5: - s/Menu disablement control/Menu can be disabled/ - rewrap comments to 109 - use SYNTHETIC_ERRNO(EOPNOTSUPP) Signed-off-by: Emil Velikov <emil.velikov@collabora.com>
2023-10-04 14:55:52 +03:00
✓ Menu can be disabled
man: add annotated example for bootctl status & list This is based on the output on my laptop, with various manual adjustments. If people have other types of entries, it'd be useful to add them here. In particular, some dual-boot entries would be nice.
2022-04-04 11:45:47 +03:00
ESP: /dev/disk/by-partuuid/01234567-89ab-cdef-dead-beef00000000
File: └─/EFI/systemd/systemd-bootx64.efi
Random Seed: ← random seed used for entropy in early boot
Passed to OS: yes
System Token: set
Exists: yes
Available Boot Loaders on ESP:
ESP: /boot/efi (/dev/disk/by-partuuid/01234567-89ab-cdef-dead-beef00000000)
File: └─/EFI/systemd/systemd-bootx64.efi (systemd-boot 251
File: └─/EFI/BOOT/BOOTX64.EFI (systemd-boot 251
Boot Loaders Listed in EFI Variables:
Title: Linux Boot Manager
ID: 0x0001
Status: active, boot-order
Partition: /dev/disk/by-partuuid/…
File: └─/EFI/systemd/systemd-bootx64.efi
Title: Fedora
ID: 0x0000
Status: active, boot-order
Partition: /dev/disk/by-partuuid/…
File: └─/EFI/fedora/shimx64.efi
Title: Linux-Firmware-Updater
ID: 0x0002
Status: active, boot-order
Partition: /dev/disk/by-partuuid/…
File: └─/EFI/fedora/fwupdx64.efi
Boot Loader Entries:
$BOOT: /boot/efi (/dev/disk/by-partuuid/01234567-89ab-cdef-dead-beef00000000)
Default Boot Loader Entry:
type: Boot Loader Specification Type #1 (.conf)
title: Fedora Linux 36 (Workstation Edition)
id: …
source: /boot/efi/loader/entries/<replaceable>entry-token</replaceable>-<replaceable>kernel-version</replaceable>.conf
version: <replaceable>kernel-version</replaceable>
machine-id: …
linux: /<replaceable>entry-token</replaceable>/<replaceable>kernel-version</replaceable>/linux
initrd: /<replaceable>entry-token</replaceable>/<replaceable>kernel-version</replaceable>/initrd
options: root=…
</programlisting>
<programlisting>$ <command>bootctl list</command>
Boot Loader Entries:
type: Boot Loader Specification Type #1 (.conf)
title: Fedora Linux 36 (Workstation Edition) (default) (selected)
id: …
source: /boot/efi/loader/entries/<replaceable>entry-token</replaceable>-<replaceable>kernel-version</replaceable>.conf
version: <replaceable>kernel-version</replaceable>
machine-id: …
linux: /<replaceable>entry-token</replaceable>/<replaceable>kernel-version</replaceable>/linux
initrd: /<replaceable>entry-token</replaceable>/<replaceable>kernel-version</replaceable>/initrd
options: root=…
type: Boot Loader Specification Type #2 (.efi)
title: Fedora Linux 35 (Workstation Edition)
id: …
source: /boot/efi/EFI/Linux/fedora-<replaceable>kernel-version</replaceable>.efi
version: <replaceable>kernel-version</replaceable>
machine-id: …
linux: /EFI/Linux/fedora-<replaceable>kernel-version</replaceable>.efi
options: root=…
type: Automatic
title: Reboot Into Firmware Interface
id: auto-reboot-to-firmware-setup
source: /sys/firmware/efi/efivars/LoaderEntries-4a67b082-0a4c-41cf-b6c7-440b29bb8c4f
</programlisting>
<para>In the listing, <literal>(default)</literal> specifies the entry that will be
used by default, and <literal>(selected)</literal> specifies the entry that was
selected the last time (i.e. is currently running).</para>
</example>
</refsect1>
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
<refsect1>
<title>See Also</title>
man: use <simplelist> for 'See also' sections This is just a slight markup improvement; there should be no difference in rendering.
2023-12-22 21:09:32 +03:00
<para><simplelist type="inline">
<member><citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
<member><ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader Specification</ulink></member>
<member><ulink url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink></member>
<member><citerefentry><refentrytitle>systemd-boot-random-seed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
</simplelist></para>
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
</refsect1>
man: add bootctl(8) https://bugzilla.redhat.com/show_bug.cgi?id=1014303
2013-11-13 13:06:13 +04:00
</refentry>
Copy Permalink