User talk:Sakaki/Sakaki's EFI Install Guide

Categories?
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:
 * The top level page (approx 2,000 words) currently contains a superset of all the categories for the underlying pages. If it should belong to a single one only, then maybe 'Core System' (so at least people have a chance of finding it in the featured docs)? (suggestion: -> 'Core System' only?)
 * Preparing Windows 8 for Dual-Booting (approx 1,900 words) - currently in core system, laptops. Could drop 'laptops' here (and on most of the subsequent pages). (suggestion: -> 'Core System' only?)
 * Creating and Booting the Minimal-Install Image on USB (approx 1,900 words) - currently in core system, laptops. Ditto.
 * Setting Up Networking and Connecting via ssh (approx 1,500 words) - currently in core system, laptops. Ditto.
 * Preparing the LUKS-LVM Filesystem and Boot USB Key (approx 5,400 words) - currently core system, laptops, security. Has detail on setting up LUKS (including XTS etc), hence security. (suggestion: -> 'Core System', 'Security' only)
 * Installing the Gentoo Stage 3 Files (approx 7,500 words) - currently core system, laptops, portage. Contains a large background reading section Gentoo, Portage, Ebuilds and emerge, hence portage. (suggestion: -> 'Core System', 'Portage' only?)
 * Building the Gentoo Base System Minus Kernel (approx 8,900 words) - currently core system, laptops, localization, portage, security. Contains info about (openRC) timezone, locale etc, hence localization. Contains info about bootstrapping and troubleshooting a failed emerge, hence portage, security. (suggestion: -> 'Core System', 'Localization', 'Portage', 'Security' only?)
 * Configuring and Building the Kernel (approx 10,400 words) - currently bootloaders, core system, laptops, initramfs, kernel. Kernel category because has detailed discussion of necessary EFI kernel options and command line params. Initramfs because it discusses how to build one (to get LVM and LUKS going in early boot). Bootloaders, because we are building an EFI stub kernel here and the necessary kernel command line (and config) options are discussed in detail. (suggestion: -> 'Bootloaders', 'Core System', 'Initramfs', 'Kernel' only?)
 * Final Preparations and Reboot into EFI (approx 4,400 words) - currently bootloaders, core system, laptops. Bootloaders because discusses BIOS settings to load EFI stub with secure boot off. This is marginal and could be dropped. (suggestion: -> 'Core System' only?)
 * Configuring systemd and Installing Necessary Tools (approx 7,200 words) - currently bootloaders, core system, laptops, kernel, localization, ssh, security. Discusses setting up the plymouth boot splash (including kernel recompile), hence bootloaders, kernel. Quite a lot of detail about systemd configuration, hence localization. ssh because of discussion of re-establishing ssh, printing host key fingerprints etc. (could be dropped). Security because of the discussion of gpg unlocked LUKS (but is covered in more detail elsewhere, so that could be dropped). (suggestion: -> 'Bootloaders', 'Core System', 'Kernel', 'Localization' only?)
 * Configuring Secure Boot (approx 6,100 words) - currently bootloaders, core system, laptops, kernel, security. Detailed discussion of secure boot process (variables used etc.), hence bootloader, security. Generation of a signed kernel, hence kernel. (suggestion: -> 'Bootloaders', 'Core System', 'Kernel', 'Security' only?)
 * Setting up the GNOME 3 Desktop (approx 7,900 words) - core system, laptops, GNOME, localization, X.Org. Discusses the emerge and setup of GNOME 3, so GNOME. Makes use of an initial X11/twm setup (to check drivers etc), hence X.Org. Discusses keyboard settings etc. in G3, hence localization. (suggestion: -> 'Core System', 'GNOME', 'Localization', 'X.Org' only?)
 * Final Configuration Steps (approx 4,700 words) - currently core system, laptops, kernel, power management. Covers the Pansonic CF-AX3 as an example of setting system-specific kernel options (drivers etc), so laptops probably applies here, as does kernel. Discussion about suspend and hibernate, hence power management. (suggestion: -> retain existing categories?)
 * Using Your New Gentoo System (approx 7,000 words) - currently bootloaders, core system, laptops, GNOME, kernel, portage, power management, security. Contains a set of misc. topics, hence the large number of categories. Covers the dual boot process and migration of the EFI stub kernel onto the windows system partition (requires kernel recompilation), hence bootloaders, security, kernel. Discusses various final setup points for GNOME, hence GNOME. Discusses automating eix-syncs/@world updates and using signed portage tree snapshots for security, hence portage (and security). (suggestion: -> 'Bootloaders', 'Core System', 'GNOME', 'Kernel', 'Portage', Power Management', 'Security' only?)
 * Happy to discuss! 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 Sat 6 Sep 08:52:55 UTC 2014

This is much more than just an EFI install guide
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 (talk • contribs)


 * 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 Thu 6 Nov 19:29:42 UTC 2014

"Health Warning" Required for this Guide?
I have, pro tem, removed the 'health warning' recently added to top page of this guide by Grknight, which read:

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 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 squiggle, but I guess they could be mapped to 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 Fri 2 Jan 12:17:15 UTC 2015


 * Relative links should work as per, 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 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 Sat 3 Jan 00:54:56 UTC 2015

Setup with SSD + HDD / Multiple Disks
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 (and  emerged with the   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
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:  The output of 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
Hi,

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:, 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 Wed 14 Jan 23:56:33 UTC 2015


 * OK, this should definitely be possible. I haven't used  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   server on the  directory (genkernel's init treats this location specially) and wait for the upload of a (binary plaintext)   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 ,  ) - 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):

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


 * Check you have the new slot:


 * Then clean up:


 * 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 :


 * Next, change your 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:


 * Next, we need to change the busybox configuration, so that it has the necessary  server in it; by default, it will not. Issue:


 * Then edit that file, so that the following lines are uncommented:


 * Now we need to ensure that genkernel uses our  init; make the following changes to its config to do this:


 * 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:


 * Take a copy of  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   into the target (in our example, at address  ) from the remote, and then (binary) upload the   file to the target (using   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, address and required modules  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!) ? If so, then we can look at the correct configuration of   as a next step. Best Sakaki (talk) 13:39, 21 January 2015 (UTC)

Disabling LUKS Password Prompt Without Reformatting

 * 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  decryption command. The only change is in the   hook in :


 * Now just run  and the new initramfs should be built and installed. Your boot sequence should now go right by the password prompt, since   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 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  (no .gpg suffix), and then set   in . I think that this (per line 201 of 00-crypt.sh) 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
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  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 ; I refer to this path as below but it'll actually be something like,  etc.),
 * leaving the boot key still inserted, insert the backup target key and find its path (again, using ; I refer to this path as below, but it'll actually be something like,  etc.),
 * unmount any partitions of the original or target key that may have automounted (using ).


 * Then issue:

to actually make the backup.
 * Of course, substitute with the actual path of your boot key (e.g. ) and  with actual path of your backup target key (e.g. ) 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.
 * 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)
 * 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?
Why not detach the LUKS header to the USB stick, as described in this ArchLinux guide?

It would have several advantages: Barbeq (talk) 17:24, 17 December 2017 (UTC)
 * 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