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)

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)