Skip to content

Commit 398c594

Browse files
Leo3418Leo3418
committed
gentoo-config-luks2-grub-systemd: Update for GRUB 2.14
1 parent 23b2c5e commit 398c594

7 files changed

Lines changed: 153 additions & 153 deletions

File tree

‎content/en/collections/gentoo-config-luks2-grub-systemd/_index.md‎

Lines changed: 0 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,6 @@ cascade:
1212
- date: 2022-08-21
1313
- show_date: true
1414
- toc: true
15-
lastmod: 2022-08-21
1615
---
1716

1817
This collection is a tutorial which provides instructions to set up LUKS2-based
@@ -29,14 +28,6 @@ articles in this collection.
2928

3029
## Caveats and Disclaimers
3130

32-
- This tutorial depends on **unofficial modification** to GRUB. The patch for
33-
the modification is from the [grub-devel mailing list][grub-devel-archive].
34-
Although the patch has been tested by myself and has not exhibited any issues
35-
so far, and it presumably has also been tested by their original authors,
36-
reviewers, testers, and some other users too, there is **no guarantee** on
37-
the modification's functionality, stability, compatibility, security, or
38-
performance whatsoever.
39-
4031
- This tutorial gives **no professional advice on computer security**.
4132
Although I endeavor to make responsible recommendations on security practices
4233
which *should* help make a system reasonably secure, there is **no

‎content/en/collections/gentoo-config-luks2-grub-systemd/background.md‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -42,11 +42,10 @@ is more resilient to header corruption and still provides modest protection
4242
when a weak passphrase is used. These enhancements are realized by use of a
4343
second copy of the LUKS header and Argon2id.
4444

45-
However, LUKS2 full disk encryption is not necessarily easy to set up:
45+
However, LUKS2 full disk encryption is not necessarily straightforward to set
46+
up:
4647
- On Gentoo, where many software packages' features can be customized via USE
4748
flags, the USE flags related to LUKS must be enabled.
48-
- Configuring the GRUB bootloader for LUKS2 with Argon2id is tricky because as
49-
of version 2.12, GRUB still does not support Argon2id.
5049
- The boot process might prompt for the passphrase twice: GRUB asks for it
5150
first, and the init system will ask for it again because GRUB cannot pass
5251
the passphrase or the unlocked state to the init system.

‎content/en/collections/gentoo-config-luks2-grub-systemd/patch-grub.md‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
---
2+
title: "Appendix: Patching GRUB 2.12/2.06 to Add LUKS2 and Argon2 Support"
3+
weight: 1001
4+
date: 2026-05-19
5+
vars:
6+
memregion_patch: "4500-grub-2.06-runtime-memregion-alloc.patch"
7+
argon2_patch_206: "5000-grub-2.06-luks2-argon2-v4.patch"
8+
argon2_patch_212: "grub-2.12-luks2-argon2-v4.patch"
9+
aur_patch: "9500-grub-AUR-improved-luks2.patch"
10+
---
11+
12+
At the time of writing, the latest release of GRUB, which is 2.14, has
13+
built-in LUKS2 and Argon2id support. Therefore, users who can use the latest
14+
GRUB release do not need to patch its source code to add LUKS2 and Argon2
15+
support, hence they can ignore the information on this page.
16+
17+
However, users of older GRUB releases, including 2.12 and 2.06, need to patch
18+
them. Neither GRUB 2.12 nor GRUB 2.06 has built-in support for Argon2id; GRUB
19+
2.06 even has more limitations on LUKS2 support. Therefore, both GRUB 2.12 and
20+
GRUB 2.06 need some patches for LUKS2 and Argon2 support.
21+
22+
## GRUB 2.12
23+
24+
GRUB 2.12 only needs one patch [`{{< param vars.argon2_patch_212 >}}`](
25+
{{< patchesBaseURL.inline >}}
26+
{{- partial "static-path.html" (dict
27+
"page" (index .Page.Ancestors.Reverse 2) "type" "res") -}}
28+
{{< /patchesBaseURL.inline >}}/{{< param vars.argon2_patch_212 >}}) to get
29+
support for LUKS2 with Argon2. This patch was originally [submitted to the
30+
grub-devel mailing list][grub-devel-argon2-v4] and targeted GRUB 2.06; I ported
31+
it to GRUB 2.12, and it still works.
32+
33+
To apply this patch to Gentoo's GRUB package -- `sys-boot/grub`, add it as a
34+
[Portage user patch][gentoo-wiki-etc-portage-patches] to
35+
`/etc/portage/patches/sys-boot/grub-2.12`. Patches at this location are
36+
applied to all Gentoo revisions of GRUB 2.12 (`-r1`, `-r2`, etc.). The
37+
following commands may be used to do this:
38+
39+
{{< commands.inline "2.12" "argon2_patch_212" >}}
40+
{{- $grubVer := .Get 0 }}
41+
{{- $patches := split (.Get 1) " " }}
42+
{{- $patches = apply $patches "printf" "vars.%s" "." }}
43+
{{- $patches = apply $patches "page.Param" "." }}
44+
45+
{{ $content := print
46+
"# mkdir -p /etc/portage/patches/sys-boot/grub-" $grubVer | println }}
47+
{{ $content := print $content
48+
"# cd /etc/portage/patches/sys-boot/grub-" $grubVer | println }}
49+
{{- $baseURL := partial "static-path.html" (dict
50+
"page" (index .Page.Ancestors.Reverse 2) "type" "res" "abs" true) }}
51+
{{- range $patches }}
52+
{{- $content = print $content "# curl -O " $baseURL "/" . | println }}
53+
{{- end }}
54+
{{- highlight $content "console" }}
55+
{{< /commands.inline >}}
56+
57+
Readers who are interested in learning more about Portage's user patch feature
58+
are welcome to read [another article on this website][portage-user-patches]
59+
that discusses it in depth.
60+
{.notice--success}
61+
62+
Because this patch modifies the file `grub-core/Makefile.core.def`, according
63+
to the [`sys-boot/grub` ebuild][ebuild-sys-boot:grub], the `GRUB_AUTOGEN` and
64+
`GRUB_AUTORECONF` environment variables must be set. **Otherwise, any builds
65+
of the package with the patch applied would fail.** The environment variable
66+
can be set exclusively for all Gentoo revisions of `sys-boot/grub-2.12` in file
67+
`/etc/portage/env/sys-boot/grub-2.12`:
68+
69+
```console
70+
# mkdir -p /etc/portage/env/sys-boot
71+
# echo -e 'GRUB_AUTOGEN=1\nGRUB_AUTORECONF=1' >> /etc/portage/env/sys-boot/grub-2.12
72+
```
73+
74+
[grub-devel-argon2-v4]: https://lists.gnu.org/archive/html/grub-devel/2021-08/msg00027.html
75+
[grub-2.12-argon2]: https://lists.gnu.org/archive/html/grub-devel/2022-11/msg00094.html
76+
[gentoo-wiki-etc-portage-patches]: https://wiki.gentoo.org/wiki//etc/portage/patches
77+
[portage-user-patches]: {{< relref "2021-03-01-portage-user-patches" >}}
78+
[ebuild-sys-boot:grub]: https://gitweb.gentoo.org/repo/gentoo.git/tree/sys-boot/grub/grub-2.12.ebuild?id=76418694270557b6feb75381912a39569ee28d45#n6
79+
80+
## GRUB 2.06
81+
82+
GRUB 2.06's support for LUKS2 is [more limited][arch-wiki-grub-luks2].
83+
Although code implementing partial LUKS2 support exists in this version, the
84+
bootloader files installed using the default procedure do not support LUKS2.
85+
86+
Luckily, after applying the following patches to GRUB 2.06, LUKS2 support can
87+
be added to the installed bootloader files automatically, and Argon2id is
88+
supported too.
89+
90+
- [`{{< param vars.memregion_patch >}}`]({{< patchesBaseURL.inline />}}/{{<
91+
param vars.memregion_patch >}}): A patch set that allows GRUB to allocate new
92+
consecutive and large memory chunks, which is a prerequisite for Argon2
93+
support in GRUB. Argon2 enhances the security of LUKS by increasing the size
94+
of memory required for unlocking computations, so GRUB must be able to
95+
allocate more memory when needed. This patch set was cherry-picked from
96+
[GRUB 2.12][grub-git-memregion-patch].
97+
98+
- [`{{< param vars.argon2_patch_206 >}}`]({{< patchesBaseURL.inline />}}/{{<
99+
param vars.argon2_patch_206 >}}): The patch set that adds Argon2 support
100+
itself to GRUB. This patch is equivalent to the only patch needed for GRUB
101+
2.12 mentioned above.
102+
103+
- [`{{< param vars.aur_patch >}}`]({{< patchesBaseURL.inline />}}/{{< param
104+
vars.aur_patch >}}): A patch [included][aur-git-grub-install-luks2-patch] in
105+
the [`grub-improved-luks2-git`][aur-grub-improved-luks2-git] package on the
106+
AUR, which is what the Arch Wiki's GRUB article recommends for users seeking
107+
great LUKS2 support in GRUB. This patch allows GRUB 2.06's `grub-install`
108+
command to automatically install bootloader files with LUKS2 support.
109+
110+
The numbers in front of the patches' file names are there only to control the
111+
order in which they are applied (patches with a smaller ordinal are applied
112+
first). As long as the order is maintained, these numbers' values are
113+
arbitrary.
114+
{.notice--info}
115+
116+
Similar to the case of GRUB 2.12, add these patches as Portage user patches to
117+
`/etc/portage/patches/sys-boot/grub-2.06`:
118+
119+
{{< commands.inline "2.06" "memregion_patch argon2_patch_206 aur_patch" />}}
120+
121+
Then, add the required environment variables to
122+
`/etc/portage/env/sys-boot/grub-2.06`:
123+
124+
```console
125+
# mkdir -p /etc/portage/env/sys-boot
126+
# echo -e 'GRUB_AUTOGEN=1\nGRUB_AUTORECONF=1' >> /etc/portage/env/sys-boot/grub-2.06
127+
```
128+
129+
[arch-wiki-grub-luks2]: https://wiki.archlinux.org/title/GRUB#LUKS2
130+
[grub-git-memregion-patch]: https://git.savannah.gnu.org/cgit/grub.git/log/?qt=range&q=8afa5ef45..1df293482
131+
[aur-grub-improved-luks2-git]: https://aur.archlinux.org/packages/grub-improved-luks2-git
132+
[aur-git-grub-install-luks2-patch]: https://aur.archlinux.org/cgit/aur.git/tree/grub-install_luks2.patch?h=grub-improved-luks2-git&id=27612416769e544d2c08d29932fff69129cb143a

‎content/en/collections/gentoo-config-luks2-grub-systemd/setup-process/configure-gentoo/grub.md‎

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -3,16 +3,15 @@ title: "Configure GRUB for Better User Experience"
33
weight: 337
44
---
55

6-
Although GRUB now has out-of-box support for LUKS2 and Argon2id thanks to the
7-
patches applied previously, a few additional configuration steps can still be
8-
taken to improve the user experience of unlocking the LUKS partition from GRUB.
6+
A few additional configuration steps can be taken to improve the user
7+
experience of unlocking the LUKS partition from GRUB.
98

109
## Update GRUB Settings for LUKS
1110

12-
GRUB's default settings disregard operating systems in LUKS partitions and
13-
therefore does not generate menu entries for them. To let GRUB probe LUKS
14-
partitions and create corresponding menu entries, the following option needs to
15-
be added to `/etc/default/grub`:
11+
With the default configuration, GRUB disregards operating systems in LUKS
12+
partitions and therefore does not generate menu entries for them. To let GRUB
13+
probe LUKS partitions and create corresponding menu entries, the following
14+
option needs to be added to `/etc/default/grub`:
1615

1716
```bash
1817
# /etc/default/grub

‎content/en/collections/gentoo-config-luks2-grub-systemd/setup-process/configure-gentoo/packages.md‎

Lines changed: 10 additions & 131 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,6 @@
11
---
22
title: "Enable LUKS2 and Argon2 Support for Packages"
33
weight: 332
4-
vars:
5-
memregion_patch: "4500-grub-2.06-runtime-memregion-alloc.patch"
6-
argon2_patch_206: "5000-grub-2.06-luks2-argon2-v4.patch"
7-
argon2_patch_212: "grub-2.12-luks2-argon2-v4.patch"
8-
aur_patch: "9500-grub-AUR-improved-luks2.patch"
9-
lastmod: 2023-12-24
104
---
115

126
Because the LUKS partition uses LUKS2 and Argon2id, support for these LUKS
@@ -36,131 +30,16 @@ USE flag must be disabled so `cryptsetup` can be built into the initramfs by
3630
dracut, or else the LUKS partition could not be unlocked during boot.
3731
{.notice--success}
3832

39-
## Add Patches for GRUB
40-
41-
Neither GRUB 2.12 nor GRUB 2.06 supports the Argon2id PBKDF; GRUB 2.06 even has
42-
more limitations on LUKS2 support. Therefore, both GRUB 2.12 and GRUB 2.06
43-
need some patches for LUKS2 with Argon2id support.
44-
45-
### GRUB 2.12
46-
47-
GRUB 2.12 only needs one patch [`{{< param vars.argon2_patch_212 >}}`](
48-
{{< patchesBaseURL.inline >}}
49-
{{- partial "static-path.html" (dict
50-
"page" (index .Page.Ancestors.Reverse 2) "type" "res") -}}
51-
{{< /patchesBaseURL.inline >}}/{{< param vars.argon2_patch_212 >}}) to get
52-
support for LUKS2 with Argon2. This patch was originally [submitted to the
53-
grub-devel mailing list][grub-devel-argon2-v4] and targeted GRUB 2.06; I ported
54-
it to GRUB 2.12, and it still works.
55-
56-
This patch has not been merged into GRUB, nor is it likely to be merged in the
57-
future. The patch's author [commented][grub-2.12-argon2] that, after the patch
58-
had been created, one dependency of GRUB gained Argon2 support, so the best way
59-
to add Argon2 support to GRUB became upgrading that dependency in GRUB's source
60-
tree. What the patch does instead is adding the Argon2 reference
61-
implementation to GRUB, which has become redundant after the said dependency's
62-
new version would also add Argon2 support.
63-
64-
To apply this patch to Gentoo's GRUB package -- `sys-boot/grub`, add it as a
65-
[Portage user patch][gentoo-wiki-etc-portage-patches] to
66-
`/etc/portage/patches/sys-boot/grub-2.12`. Patches at this location are
67-
applied to all Gentoo revisions of GRUB 2.12 (`-r1`, `-r2`, etc.). The
68-
following commands may be used to do this:
69-
70-
{{< commands.inline "2.12" "argon2_patch_212" >}}
71-
{{- $grubVer := .Get 0 }}
72-
{{- $patches := split (.Get 1) " " }}
73-
{{- $patches = apply $patches "printf" "vars.%s" "." }}
74-
{{- $patches = apply $patches "page.Param" "." }}
75-
76-
{{ $content := print
77-
"# mkdir -p /etc/portage/patches/sys-boot/grub-" $grubVer | println }}
78-
{{ $content := print $content
79-
"# cd /etc/portage/patches/sys-boot/grub-" $grubVer | println }}
80-
{{- $baseURL := partial "static-path.html" (dict
81-
"page" (index .Page.Ancestors.Reverse 2) "type" "res" "abs" true) }}
82-
{{- range $patches }}
83-
{{- $content = print $content "# curl -O " $baseURL "/" . | println }}
84-
{{- end }}
85-
{{- highlight $content "console" }}
86-
{{< /commands.inline >}}
87-
88-
Readers who are interested in learning more about Portage's user patch feature
89-
are welcome to read [another article on this website][portage-user-patches]
90-
that discusses it in depth.
91-
{.notice--success}
92-
93-
Because this patch modifies the file `grub-core/Makefile.core.def`, according
94-
to the [`sys-boot/grub` ebuild][ebuild-sys-boot:grub], the `GRUB_AUTOGEN` and
95-
`GRUB_AUTORECONF` environment variables must be set. **Otherwise, any builds
96-
of the package with the patch applied would fail.** The environment variable
97-
can be set exclusively for all Gentoo revisions of `sys-boot/grub-2.12` in file
98-
`/etc/portage/env/sys-boot/grub-2.12`:
99-
100-
```console
101-
# mkdir -p /etc/portage/env/sys-boot
102-
# echo -e 'GRUB_AUTOGEN=1\nGRUB_AUTORECONF=1' >> /etc/portage/env/sys-boot/grub-2.12
103-
```
104-
105-
[grub-devel-argon2-v4]: https://lists.gnu.org/archive/html/grub-devel/2021-08/msg00027.html
106-
[grub-2.12-argon2]: https://lists.gnu.org/archive/html/grub-devel/2022-11/msg00094.html
107-
[gentoo-wiki-etc-portage-patches]: https://wiki.gentoo.org/wiki//etc/portage/patches
108-
[portage-user-patches]: {{< relref "2021-03-01-portage-user-patches" >}}
109-
[ebuild-sys-boot:grub]: https://gitweb.gentoo.org/repo/gentoo.git/tree/sys-boot/grub/grub-2.12.ebuild?id=76418694270557b6feb75381912a39569ee28d45#n6
110-
111-
### GRUB 2.06
112-
113-
GRUB 2.06's support for LUKS2 is [more limited][arch-wiki-grub-luks2].
114-
Although code implementing partial LUKS2 support exists in this version, the
115-
bootloader files installed using the default procedure do not support LUKS2.
116-
117-
Luckily, after applying the following patches to GRUB 2.06, LUKS2 support can
118-
be added to the installed bootloader files automatically, and Argon2id is
119-
supported too.
33+
## GRUB 2.12 and Lower Only: Add Patches for GRUB
12034

121-
- [`{{< param vars.memregion_patch >}}`]({{< patchesBaseURL.inline />}}/{{<
122-
param vars.memregion_patch >}}): A patch set that allows GRUB to allocate new
123-
consecutive and large memory chunks, which is a prerequisite for Argon2
124-
support in GRUB. Argon2 enhances the security of LUKS by increasing the size
125-
of memory required for unlocking computations, so GRUB must be able to
126-
allocate more memory when needed. This patch set was cherry-picked from
127-
[GRUB 2.12][grub-git-memregion-patch].
128-
129-
- [`{{< param vars.argon2_patch_206 >}}`]({{< patchesBaseURL.inline />}}/{{<
130-
param vars.argon2_patch_206 >}}): The patch set that adds Argon2 support
131-
itself to GRUB. This patch is equivalent to the only patch needed for GRUB
132-
2.12 mentioned above.
133-
134-
- [`{{< param vars.aur_patch >}}`]({{< patchesBaseURL.inline />}}/{{< param
135-
vars.aur_patch >}}): A patch [included][aur-git-grub-install-luks2-patch] in
136-
the [`grub-improved-luks2-git`][aur-grub-improved-luks2-git] package on the
137-
AUR, which is what the Arch Wiki's GRUB article recommends for users seeking
138-
great LUKS2 support in GRUB. This patch allows GRUB 2.06's `grub-install`
139-
command to automatically install bootloader files with LUKS2 support.
140-
141-
The numbers in front of the patches' file names are there only to control the
142-
order in which they are applied (patches with a smaller ordinal are applied
143-
first). As long as the order is maintained, these numbers' values are
144-
arbitrary.
145-
{.notice--info}
146-
147-
Similar to the case of GRUB 2.12, add these patches as Portage user patches to
148-
`/etc/portage/patches/sys-boot/grub-2.06`:
149-
150-
{{< commands.inline "2.06" "memregion_patch argon2_patch_206 aur_patch" />}}
151-
152-
Then, add the required environment variables to
153-
`/etc/portage/env/sys-boot/grub-2.06`:
154-
155-
```console
156-
# mkdir -p /etc/portage/env/sys-boot
157-
# echo -e 'GRUB_AUTOGEN=1\nGRUB_AUTORECONF=1' >> /etc/portage/env/sys-boot/grub-2.06
158-
```
35+
GRUB has gained built-in support for LUKS2 and Argon2id support since 2.14, so
36+
users of GRUB 2.14 do not need to manually patch its source code to manually
37+
add LUKS2 and Argon2id support. These users can skip this step and move on to
38+
the next one.
15939

160-
[arch-wiki-grub-luks2]: https://wiki.archlinux.org/title/GRUB#LUKS2
161-
[grub-git-memregion-patch]: https://git.savannah.gnu.org/cgit/grub.git/log/?qt=range&q=8afa5ef45..1df293482
162-
[aur-grub-improved-luks2-git]: https://aur.archlinux.org/packages/grub-improved-luks2-git
163-
[aur-git-grub-install-luks2-patch]: https://aur.archlinux.org/cgit/aur.git/tree/grub-install_luks2.patch?h=grub-improved-luks2-git&id=27612416769e544d2c08d29932fff69129cb143a
40+
Users who need to use an older GRUB release for any reason, including 2.12 and
41+
2.06, need to patch its source code to add LUKS2 and Argon2id support. See
42+
[the appendix]({{% relref "../../patch-grub" %}}) for instructions.
16443

16544
## New Installation Only: Initialize Portage
16645

@@ -174,8 +53,8 @@ chapter:
17453

17554
## Rebuild Packages
17655

177-
First, build `sys-boot/grub` with the patches applied. Before starting the
178-
build, please make sure that in the output of `emerge`,
56+
First, build `sys-boot/grub` (with any patches applied, if needed). Before
57+
starting the build, please make sure that in the output of `emerge`,
17958
`GRUB_PLATFORMS="efi-64"` is enabled for `sys-boot/grub`. In other words,
18059
please check that `efi-64` is listed *without* a minus sign (`-`) in front of
18160
it under `GRUB_PLATFORMS`. If this is not true, the Handbook has [related

‎content/en/posts/2025-06-22-custom-gentoo-binhost.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -124,7 +124,7 @@ must be set up.
124124
[cachyos-benchmark]: https://www.phoronix.com/review/cachyos-x86-64-v3-v4
125125
[gentoo-news-x86-64-v3]: https://www.gentoo.org/news/2024/02/04/x86-64-v3.html
126126
[portage-user-patches-fix-bugs]: {{< relref "2021-03-01-portage-user-patches" >}}
127-
[portage-user-patches-grub-argon2]: {{< relref "collections/gentoo-config-luks2-grub-systemd/setup-process/configure-gentoo/packages#add-patches-for-grub" >}}
127+
[portage-user-patches-grub-argon2]: {{< relref "collections/gentoo-config-luks2-grub-systemd/patch-grub" >}}
128128

129129
## Effects
130130

‎content/zh/posts/2025-06-22-custom-gentoo-binhost.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@ toc: true
5252
[cachyos-benchmark]: https://www.phoronix.com/review/cachyos-x86-64-v3-v4
5353
[gentoo-news-x86-64-v3]: https://www.gentoo.org/news/2024/02/04/x86-64-v3.html
5454
[portage-user-patches-fix-bugs]: {{< relref "2021-03-01-portage-user-patches" >}}
55-
[portage-user-patches-grub-argon2]: {{< relref path="collections/gentoo-config-luks2-grub-systemd/setup-process/configure-gentoo/packages#add-patches-for-grub" lang="en" >}}
55+
[portage-user-patches-grub-argon2]: {{< relref path="collections/gentoo-config-luks2-grub-systemd/patch-grub" lang="en" >}}
5656

5757
## 效果
5858

@@ -518,4 +518,4 @@ $ journalctl --all --unit binhost-update.service
518518

519519
[gentoo-wiki-binpkg-guide]: https://wiki.gentoo.org/wiki/Binary_package_guide
520520
[github-hartwork-binary-gentoo]: https://github.com/hartwork/binary-gentoo
521-
[github-hartwork-binary-gentoo-readme-flags]: https://github.com/hartwork/binary-gentoo?tab=readme-ov-file#determining-ideal-build-flags
521+
[github-hartwork-binary-gentoo-readme-flags]: https://github.com/hartwork/binary-gentoo?tab=readme-ov-file#determining-ideal-build-flags

0 commit comments

Comments
 (0)