User talk:Sakaki/Sakaki's EFI Install Guide

From Gentoo Wiki
Jump to:navigation Jump to:search
Before creating a discussion or leaving a comment, please read about using talk pages. To create a new discussion, click here. Comments on an existing discussion should be signed using ~~~~:
A comment [[User:Larry|Larry]] 13:52, 13 May 2024 (UTC)
: A reply [[User:Sally|Sally]] 06:37, 19 June 2024 (UTC)
:: Your reply ~~~~


Talk status
This discussion is done.

Why are the EFI Gentoo End to End Install pages in so many categories? Most of the categories have no relation to this page or the others. This clutters the category pages like Category:Laptops. If there is no objection, I will clean this up. Chithanh (talk) 07:43, 5 September 2014 (UTC)

Hi Chithanh - happy in principle for it to be cleaned up, the guide is my first wiki contribution so I'll defer to your knowledge of the proper form! However, you said that "most of the categories have no relation to this page or the others", and I'm not sure I quite understand/agree. This is a 76,000 word manual (which took around 5 months to write) and as such, does cover a lot of ground, more so than the average 2,000 word wiki article. I do agree the 'laptops' tag should be dropped from all (but one of) the pages, but here's the rationale for the rest, with possible changes:
Happy to discuss! sakaki (sakaki) Fri 5 Sep 13:01:33 UTC 2014
Hi Chithanh, as the changes to the categories I proposed above are at least moving monotonically in the direction you want, I've gone ahead and implemented them. Hopefully this will save you some time, but please let me know if you think things should be trimmed back further. Best, sakaki (sakaki) Sat 6 Sep 08:52:55 UTC 2014

This is much more than just an EFI install guide

Talk status
This discussion is done.

This guide shouldn't be framed as a general "how to install gentoo in EFI mode" guide. This is just one person's favorite install method, favorite packages, favorite disk layout, etc. It should just be called "Sakaki's custom gentoo install". Lots of users are mistakenly using this as a general EFI install guide and getting much more than they bargained for. — Preceding unsigned comment added by Iamben (talkcontribs)

Hello Iamben, thanks for the feedback!
You state that "lots of users are mistakenly using this as a general EFI install guide" - is that really the case? I think I am reasonably explicit right from the first sentence of the top-level page what the goals of the install are, and (later on in the page), the steps the user is going to be performing.
However, to reflect your feedback, and for avoidance of doubt, I have added an additional rider in the "Let's Get Started" section. This contains some pointers to more 'generic' EFI and systemd pages on the Wiki. Hopefully that'll redirect anyone who ends up on the top-level page from a search engine, but who was looking for more concise info ^-^
Rationale for the Guide's Structure
My motivation for writing this guide (having been through the Gentoo install loop more times than I care to think about!) was to deal with the most complex, but still desirable (to many end users) use case, specifically, Gnome 3 on a secure boot, EFI machine with disk encryption, sharing the machine with Windows. This is a fairly common install configuration for, say, an Ubuntu system, where it can easily be achieved using the graphical installer. However, the interlocking steps make it quite difficult when doing a command-line driven install in Gentoo.
Also, I deliberately targeted a specific (but hopefully, not wilfully customized) configuration, because that way, all necessary commands could be listed. I think this 'Linux from scratch' approach is a useful complement to individual pages for standalone functions (which are useful too, don't get me wrong) as it doesn't leave magic gaps where people have to try to figure out what to do next. It is relatively easy to adapt the instructions to achieve a different configuration once you have the concrete steps in front of you, and I know from my feedback emails that many people have indeed done this (for a non-dual-boot install, for example).
As far as possible, I have tried to avoid pulling packages, parameters etc. out of the air, but tried to stick only to those necessary, keeping to the handbook flow as far as possible. Specifically:
  • I'm essentially targeting an install of Gnome 3 here, so systemd is mandated. But, the install images start from OpenRC, so we need to work through that.
  • I use a USB key for the EFI system partition as that allows an explicit 'first EFI boot' from nearly all BIOS guis, and provide a script in an overlay to ease the EFI stub kernel build (with initramfs, correct command line, systemd stuff turned on). But instructions are also provided to migrate the kernel to an EFI partition on the main drive if desired.
  • Disk encryption - it is sensible for users with laptops to encrypt their disk, but difficult to retrofit, so it needed to be part of the install. I use lvm over luks, as this is supported by genkernel. I've gone for a dual-factor approach for security, but instructions for relaxing this to 'passphrase only' (a la ubuntu) are provided. Also, although genkernel's init script will invoke gpg, the pinentry versions don't play nicely with plymouth - nor is gpg slotted - so I provided a static variant of v1 gpg as an ebuild in the overlay.
  • As for the disk layout in lvm, that is fairly standard Gentoo root/swap/home; the size of swap is set by the desire to enable suspend to disk; the size / format of home and root is suggested but I do point out that users can vary these if desired.
  • Other than that, there aren't a lot of 'custom' packages mandated - things like cron etc. per the handbook (and to run log rotation etc.), eix of course, and screen to make it possible to disconnect, and that's about it. I've provided a tool to do the @world update (genup) but its use is optional (and not all users install it)
Anyway, hopefully with the rider added fewer people will be confused ^-^ thanks again for taking the time to post your feedback, sakaki (sakaki) Thu 6 Nov 19:29:42 UTC 2014

"Health Warning" Required for this Guide?

Talk status
This discussion is done.

I have, pro tem, removed the 'health warning' recently added to top page of this guide by Grknight, which read:

This page was created by a user and displays their experience and expectations. Please visit the Offical (sic) Handbook for the recommended install instructions.

The reasons for removing this are as follows:

  • I believe it to be a little unfair - this is a wiki, so by definition based on user-submitted content - and similar warnings have not been applied to other pages, as far as I can see.
  • I do refer, in the initial lead-in text, to the official handbook, so it should be clear that this is "unofficial".
  • Per my earlier comments herein, I believe anyone who reads the top page will understand the process that is going to be outlined. Since this covers, in detail, a number of points that are not as fully discussed in the official handbook, the two are not really fungible (e.g. secure boot, dual boot, EFI command line, LVM over LUKS etc)
  • The tone of the 'health warning' might put users off reading the guide, which I don't think is helpful to Gentoo users in general.

@Grnight, if you do feel that more needs to be done on this page to ensure users are not misled, please comment below, and hopefully we can agree on some change that is mutually acceptable. Many thanks, sakaki (sakaki) Sun 28 Dec 13:28:38 UTC 2014

Nice guide you compiled there. However, I have to agree with the concerns others have made. You're describing your installation, adding your overlay, building kernels with packages from there. As such, I propose to move your articles to "Sakaki's EFI Installation" or something along these lines. This will not only clear up the confusion (and not require a warning box) but also give you appropriate attribution for your efforts. I'd like to remove the explicit 'Acknowledgements' section, as we don't list authors on the pages unless required by license on old imported pages.
So: What title including your nickname sounds best to you? —a3li 02:22, 2 January 2015 (UTC)
Hi a3li; if the general consensus amongst the wiki / documentation team is that the guide needs renaming, then of course I'm happy to do that. Just for the record, my intention has never been to mislead users or to pass this off as the "official" guide - but if that's the way it has come across, apologies.
Anyway, as to the mechanics: the guide has quite a few internal links of the form [[User:Sakaki/Sakaki's EFI Install Guide/foo#bar|squiggle]], but I guess they could be mapped to [[../foo#bar|squiggle]], and then only the top page moved, is that correct? If so, I'm happy to migrate the pages myself, as I have to go through and fix the deprecated Code, File etc. templates anyway (and change the links into the handbook, now it's been wikified).
As to title, how about "Sakaki's EFI Install Guide"?
Also - there are quite a few inbound links from google now (and over 150 downloads of the overlay), so would there be some way to redirect those at the webserver level, at least for a little while? Otherwise, there's a risk (if nothing else) of someone recreating some content under the "EFI Gentoo End to End Install" title on an inbound link from a search engine.
Finally; I can also of course remove the 'acknowledgements' section from each page if you like. However, since the whole guide is going to have my nick attached, it seems a bit odd not to have some feedback link on there somewhere, so would you have an issue with a 'feedback' section, with a mailto link, at the bottom the top, and final, pages?
I'll make no edits till I hear back from you. Best, sakaki (sakaki) Fri 2 Jan 12:17:15 UTC 2015
Relative links should work as per [1], I think moving the root page should do. Your suggested title is fine. As for a redirection, I'd create a new page under the old name with a link to the new guide and a quick description, so that people know what's up. Finally, the discussion pages are there for providing feedback, having it go to your private mailbox doesn't feel right for a guide on a community Wiki. —a3li 12:47, 2 January 2015 (UTC)
OK, will do. I'll start with the subpage edits now, then move the top page last; that way there'll be no content with broken links. I'll then create a short redirect page as you suggest. Should only take a few days to migrate everything. You can then retire the redirect page after a few months, if you like.
As to feedback, agreed in principle about the talk pages, I will put in a note referring people there, instead of to my mailbox directly. BTW, is there any plan to mimic Funtoo's DISQUS template in the talk pages? (Makes them a lot more user friendly imho). Best, sakaki (sakaki) Fri 2 Jan 13:00:39 UTC 2015
Great, thanks for your cooperation. On DISQUS: No, we don't rely on commercial third-party services as per our social guidelines. I agree the pages are not nice, thankfully the Wikimedia guys have noticed as well, so we'll be getting Flow when it's ready for sure. —a3li 13:09, 2 January 2015 (UTC)
Migration completed. Guide still seems to be intact, and the wiki system created all the necessary redirects. Please let me know if there are any subsequent problems. Best, sakaki (sakaki) Sat 3 Jan 00:54:56 UTC 2015

Setup with SSD + HDD / Multiple Disks

Talk status
This discussion is done.

Hi. You made a really great guide there, sakaki! I think it would be nice to extend the guide in order to cover systems with multiple disks, too. What do you guys think? — Preceding unsigned comment added by dr-peppa Fri, 9 Jan 2015 - UTC 11:30

Thanks for the feedback, dr-peppa!
I assume the use case you are interested in is one where the second (HDD) disk also contains a LUKS partition (& possibly LVM/LUKS), where you then want to unlock this (automatically) via a keyfile located in the (existing, SSD) protected root partition, then automatically mount it? If so, then this can be achieved using an appropriate /etc/crypttab (and sys-apps/systemd emerged with the cryptsetup USE flag, so you get the systemd-cryptsetup-generator), per this Arch Linux wiki article... I'll put together a note about this and add it to the guide, once I've had a chance to test it on my desktop machine.
Best, Sakaki (talk) 18:22, 10 January 2015 (UTC)
I have just added a short 'mini-guide' to the main text, covering this use case. Sakaki (talk) 20:00, 5 February 2015 (UTC)

Flawed whirlpool implementation on Gentoo-ISO from 04.12.2014

Talk status
This discussion is done.

After installation, if you upgrade dm-crypt, etc. it is not possible to open the luksDevice anymore. This is because of a flaw in the whirlpool implementation in gcrypt 1.5.4 which is used on the installation media, i.e. the Gentoo Minimal Installation ISO. Discussion here: [2] The output of cryptsetup luksDump <luksDevice> --debug | grep backend gives:

Crypto backend (gcrypt 1.5.4, flawed whirlpool) initialized.

That's not good, glad you spotted it. I'll change the text now to recommend using sha512 hashing instead, and release a news item in the sakaki-tools overlay (and possibly also add a mask for libgcrypt >= 1.6, to give people time to fix things).
Have you managed to use cryptsetup luksHeaderBackup followed by cryptsetup-reencrypt to change the hash? Sakaki (talk) 18:30, 13 January 2015 (UTC)
No. I didn't have any data on the system so I decided to restart installation. Second time is much faster. ;-) In fact, I have already had to re-install once because of this but thought that I must have made an error somewhere. The second time made me look closer. However I'm really impressed that you respond so fast on the issues brought up. Nice. dr-peppa - 20:39, 13.01.2015 (UTC)
I have created a short guide (and archived the necessary tools on a referenced GitHub repo) for those who need to migrate their LUKS header hash from Whirlpool, available here.Sakaki (talk) 20:08, 14 January 2015 (UTC)

Connecting and decrypting via SSH

Talk status
This discussion is done.


is there a way, that I can take the usb-key with me, connect via ssh to the secured machine and pipe the key-file to the system so I can access it over ssh.

I plan to do things like this:

  • Port Knocking on OpenWRT-Router --> Wake-On-Lan-Port and SSH-Port to SecurePC becomes active
  • Performing Wake-On-Lan on SecurePC
  • SSH into SecurePC
  • Decrypt(?)
  • use Secure PC

Could you give me an Idea on how to perform the "Decrypt" part?

Thanks in advance dr-peppa - 08:00 (UTC), 14.01.2015

Hi dr-peppa; from the above, do you mean that the PC already has its main root mounted, when you connect in via ssh, and then you are looking to unlock some secondary LUKS container (to be mounted on /home or whatever) with a key piped via ssh? Sakaki (talk) 21:57, 14 January 2015 (UTC)
No, mounting the main root is the problem. Following this forum post: [3], I have managed to insert dropbear binary into the initramfs by adding said commands to the user_modify_initramfs-hook in buildkernel.conf. But somehow I can not connect properly. The RSA-Key is refused by dropbear and I get an output like "connection from ... to nonexistent user account", despite having edited ${INITRAMFSDIR}/etc/{passwd,shadow} including the right permissions in the initramfs (via hook). I don't know whether it has something to do with missing libraries or if my editing of /usr/share/genkernel/default/linuxrc (in order to start udhcpcd and dropbear after initramfs start) is flawed. Could you edit your guide to contain this info, or could give a condensed Todo-List with some pointers so we can look up things? Would be really nice - and does not have to be instantaneous. Thanks in advance.dr-peppa (dr-peppa) Wed 14 Jan 23:56:33 UTC 2015
OK, this should definitely be possible. I haven't used dropbear much, but I've managed to get a simple proof-of-concept working for your question, on the VirtualBox EFI system I use for testing the install. The basic idea is to provide a 'shim' init that will be run before the main (genkernel-supplied init) on the initramsfs. This init will start an ftp server on the /mnt/key directory (genkernel's init treats this location specially) and wait for the upload of a (binary plaintext) luks-key file. When this file is received, it'll then exec the genkernel init, which will use your just-uploaded keyfile (saved temporarily in the initramfs) to unlock the LUKS. Obviously this is wildly insecure (as I send the keyfile with ftp!) - but this setup provides a known-good baseline, from where the only problem remains to transfer the keyfile securely (via dropbear, scp) - which can then be tackled as a 'step 2'.
Anyway, here's what I did. First, create some raw key material, and add this as a new slot (the following assumes your original EFI partition is on /dev/sda1 and main system LUKS on /dev/sda2, adjust as required):
root #cd /boot
root #mount /dev/sda1 /boot/efi
root #mkfifo /tmp/gpgpipe
root #gpg --decrypt /boot/efi/luks-key.gpg | cat - >/tmp/gpgpipe
  ... enter keyfile passphrase when prompted ...

Switch to another terminal in GNOME, or a new screen, then

root #cd /boot
root #dd if=/dev/urandom bs=512 count=1 of=/boot/luks-key
root #cryptsetup --key-file /tmp/gpgpipe luksAddKey /dev/sda2 /boot/luks-key
Check you have the new slot:
root #cryptsetup luksDump /dev/sda2
Then clean up:
root #rm /tmp/gpgpipe
root #umount /dev/sda1
and close the second terminal / screen. (Incidentally, the reason we create a short keyfile here is because we're going to be sending it across the network.)
OK, now create the following shim init file in /boot/shim-init:
FILE /boot/shim-initShim init
#!/bin/busybox sh
echo "Starting init!"
rescue_shell() {
    echo "Entering ash rescue shell..."
    exec /bin/sh
# Mount the /proc, /sys and /dev filesystems.
mount -t proc none /proc
mount -t sysfs none /sys
mount -t devtmpfs none /dev

# make sure we have all the functions going...
/bin/busybox --install -s
# Uncomment to explore the busybox environment...
# This is useful to find out what modules you need, play around
# with interfaces etc.

# Bring up Ethernet. Adjust module(s) as required.
modprobe e1000
sleep 2
# Establish an interface to listen on. Adjust as desired.
ifconfig eth1
# Start ftp server (wildly insecure! proof of concept only!)
# You should start dropbear and scp the file instead...
tcpsvd -vE 21 ftpd -w -v /mnt/key &
# Wait for the keyfile to arrive... (ftp upload luks-key in BINARY mode to boot)
echo "Waiting for keyfile..."
while [[ ! -s /mnt/key/luks-key ]]; do
   sleep 1
echo "Keyfile received - attempting boot!"

# OK, we have a keyfile - clean up...
umount /proc
umount /sys
umount /dev
# And hand off to the genkernel init.
exec /init-orig
Next, change your /etc/buildkernel.conf file, so that we use this shim init as the 'real' init, and also specify that we want to use an unencrypted binary keyfile. Add the following lines to the end of the file:
FILE /etc/buildkernel.confAppend the following lines to override keyfile and init
user_modify_initramfs() {
    show "Inserting our shim init..."
    mv -v "${INITRAMFSDIR}/init" "${INITRAMFSDIR}/init-orig"
    cp -v "${INITRAMFSDIR}/../shim-init" "${INITRAMFSDIR}/init"
    chmod +x "${INITRAMFSDIR}/init"
    show "Making keyfile directory..."
    mkdir -pv "${INITRAMFSDIR}/mnt/key"
Next, we need to change the busybox configuration, so that it has the necessary tcpsvd server in it; by default, it will not. Issue:
root #cp /usr/share/genkernel/defaults/busy-config /boot
Then edit that file, so that the following lines are uncommented:
FILE /boot/busy-configUncomment the following to enable TCP and UDP servers in busybox environment
Now we need to ensure that genkernel uses our busybox init; make the following changes to its config to do this:
FILE /etc/genkernel.confSpecify a custom busybox configuration (leave rest of config file as is)
We're done! Make a backup so you can get back in the old way if something goes wrong, and then create the new kernel:
root #buildkernel --snapshot-backup
root #buildkernel
Take a copy of luks-key off to your remote machine, and shut down the target. Then start it up again; it should run our new shim init on boot, and wait for a keyfile. You should now be able to ftp into the target (in our example, at address from the remote, and then (binary) upload the luks-key file to the target (using FileZilla or similar utility). Once the keyfile is received, the shim init will pass off control to the genkernel init, which will use it to unlock the LUKS partition, mount root, and then hand off control to systemd's init. Done.
Obviously, you'll need to adjust the interface (eth1), address ( and required modules (e1000) used in the shim init script.
So, would you mind trying the above and seeing if you can get it to work for you, so there's a known-good baseline using simple (insecure!) ftp? If so, then we can look at the correct configuration of dropbear as a next step. Best Sakaki (talk) 13:39, 21 January 2015 (UTC)

Disabling LUKS Password Prompt Without Reformatting

Talk status
This discussion is done.
If you currently use full disk encryption with a password entry on boot and would like to disable it, there is a pretty simple, albeit hacky, solution. The most obvious way to go about this is to backup your data, wipe your drive, and reformat to whatever filesystem was previously contained inside LUKS. This method certainly works, but it's a pain to do and can backfire very easily. Note: doing this will make your installation as insecure as an installation with no disk encryption whatsoever.
The solution I came up with is to create a new trivial passphrase for my LUKS partition and modify the initramfs to pipe the passphrase to the gpg decryption command. The only change is in the user_modify_initramfs() hook in /etc/buildkernel.conf:
FILE /etc/buildkernel.conf
# ...
user_modify_initramfs() {
    # Make sure tty_cmd takes input from stdin; affects line 211 of
    sed -i 's/--quiet --decrypt \$/--quiet --passphrase-fd 0 --batch --no-tty --decrypt $/g' \
    # Pass in the mock passphrase to the ply_cmd command; affects line 223 of
    sed -i "s/local ply_cmd=\"/local ply_cmd=\"echo -n ${MOCK_PW} | /g"
    # Pass in the mock passphrase to the tty_cmd command; affects line 224 of
    sed -i "s/local tty_cmd=\"/local tty_cmd=\"echo -n ${MOCK_PW} | /g" \
# ...
Now just run buildkernel and the new initramfs should be built and installed. Your boot sequence should now go right by the password prompt, since gpg is being provided with the password via a pipe on every boot. I hope this was helpful! Please feel free to add any comments or questions.
Thanks for posting this tip! For those who still have their original GPG encrypted LUKS keyfile (luks-key.gpg) around (on the boot USB key, for example), another way to achieve this might be to decrypt that file (in place) to yield the binary plaintext file luks-key (no .gpg suffix), and then set LUKSKEYFILE="luks-key" in /etc/buildkernel.conf. I think that this (per line 201 of should also cause the LUKS partition to be unlocked without prompting (but I haven't tested this). Best, Sakaki (talk) 20:14, 18 August 2015 (UTC)

Additional (backup) boot USB flash drive

Talk status
This discussion is done.

Hi Sakaki, brilliant guide, thank you! I'm using the option to boot my Gentoo using USB key -- after the install I'm just a little concerned what if the USB key gets lost or damaged. As it's a real-life scenario, a backup key, stored somewhere safe, would be great. If I followed the guide correctly, such additional (signed) EFI boot key can be done using buildkernel --easy-setup if I temporary re-set the partition id in settings + copy over the content of the original key. Still I am not sure if this is achievable the way I plan, since you did not mentioned this in the guide. Can you please provide some comments on this? Thank you! Lacimarsik (talk) 14:50, 21 April 2016 (UTC)

Hi Lacimarsik, thanks for the feedback! As to making a backup of your USB boot key, the easiest thing is just to get a second USB key of at least the same storage capacity (a bigger key is also fine), then:
  • insert the (original) boot key and find its path (using lsblk; I refer to this path as /dev/sdX below but it'll actually be something like /dev/sdb, /dev/sdc etc.),
  • leaving the boot key still inserted, insert the backup target key and find its path (again, using lsblk; I refer to this path as /dev/sdY below, but it'll actually be something like /dev/sdc, /dev/sdd etc.),
  • unmount any partitions of the original or target key that may have automounted (using umount).
Then issue:
root #cat /dev/sdX > /dev/sdY && sync

to actually make the backup.

Of course, substitute /dev/sdX with the actual path of your boot key (e.g. /dev/sdb) and /dev/sdY with actual path of your backup target key (e.g. /dev/sdc) in the above command.
The actual backup will take between 5-15 minutes depending on your system and the capacity of the original boot key.
Double check the paths before running the cat command, as the contents of the target drive will be overwritten irretrievably!
Once the process is complete, the backup drive will be a complete 'clone' of the original (same partition UUIDs etc.) and so may be used without having to rebuild the kernel etc. You can easily verify this (by trying to boot from it) and then, if successful, you can confidently lock it away in a safe place.
I'd also recommend you take a backup of your main drive's LUKS header, as described here, if you haven't already done so.
Sakaki (talk) 16:14, 22 April 2016 (UTC)
Thank you Sakaki! Works nicely! Lacimarsik (talk) 14:50, 21 April 2016 (UTC)

Why no detached LUKS header?

Talk status
This discussion is still ongoing.

Why not detach the LUKS header to the USB stick, as described in this ArchLinux guide?

It would have several advantages:

  • No need to separately backup the LUKS header / No risk of the LUKS header becoming damaged - Any backup of the USB stick (which one should have anyway) will also be a backup of the LUKS header
  • No need for a statically built GPG and generally an easier setup
  • It gives plausible deniability, since the headerless LUKS partition is indistinguishable from random data

Barbeq (talk) 17:24, 17 December 2017 (UTC)

Hi Barbeq, apologies for the very delayed reply, the page update email notification got spam filtered at my end, for some reason ><
Anyway, yes, I like the idea of using detached headers. I'm just waiting for genkernel-next (which the guide uses) to merge and stabilize this PR, and then I'll look at using it.
One quick question, does the device with the headers have to stay permanently plugged in, or is it only required at initial boot and if e.g., a slot-modifying operation is requested? Best, --Sakaki (talk) 13:55, 31 January 2018 (UTC)

Installation without encrypt and boot usb key

Talk status
This discussion is still ongoing.

Hello! I wanted to install gentoo on your guide but without encrypt and boot usb key, how can I do this? Agalq12 (talk) 03:14, 5 December 2018 (UTC)

Hi, there are instructions at the end of the guide (here for systemd, and here for OpenRC) to migrate boot off the boot USB key onto a system partition on your main drive. This allows you to unlock your system using just a passphrase, which can be very simple (or blank).
If you actually want the root, swap and home partitions to remain unencrypted at rest however, this isn't (straightforwardly) supported by buildkernel right now (although it'd be reasonably easy to do so - just needs root etc. to be set up correctly in the kernel command line). For such a case, the standard handbook flow should have what you need though. --Sakaki (talk) 16:44, 6 December 2018 (UTC)