├── .gitignore ├── 00_EFI_Gentoo_End_to_End_Install ├── 01_Installation_Prerequisites ├── 02_Preparing_Windows_for_Dual-Booting ├── 03_Creating_and_Booting_the_Minimal-Install_Image_on_USB ├── 04_Setting_Up_Networking_and_Connecting_via_ssh ├── 05_Preparing_the_LUKS-LVM_Filesystem_and_Boot_USB_Key ├── 06_Installing_the_Gentoo_Stage_3_Files ├── 07_Building_the_Gentoo_Base_System_Minus_Kernel ├── 08_Configuring_and_Building_the_Kernel ├── 09_Final_Preparations_and_Reboot_into_EFI ├── 10_Configuring_systemd_and_Installing_Necessary_Tools ├── 10a_Completing_OpenRC_Configuration_and_Installing_Necessary_Tools ├── 11_Configuring_Secure_Boot ├── 11a_Configuring_Secure_Boot_under_OpenRC ├── 12_Setting_up_the_GNOME_3_Desktop ├── 12a_Setting_up_the_GNOME_3_Desktop_under_OpenRC ├── 13_Final_Configuration_Steps ├── 13a_Final_Configuration_Steps_under_OpenRC ├── 14_Using_Your_New_Gentoo_System ├── 14a_Using_Your_New_Gentoo_System_under_OpenRC ├── README.md ├── download_pages.sh ├── m01_Extending_LUKS_to_Protect_an_Additional_Drive ├── m02_Disabling_the_Intel_Management_Engine ├── m03_Sandboxing_the_Firefox_Browser_with_Firejail ├── m04_Booting_Legacy_Images_on_EFI_using_kexec └── pages.txt /.gitignore: -------------------------------------------------------------------------------- 1 | .#* 2 | WIP/ 3 | check_links2.py 4 | -------------------------------------------------------------------------------- /00_EFI_Gentoo_End_to_End_Install: -------------------------------------------------------------------------------- 1 | 2 | 3 | If you have a Windows 10 (or 8) machine that you'd like to dual-boot with Gentoo Linux and GNOME 3, you've come to the right place! 4 | [[File:Dual_boot_cfax3_2.jpg|thumb|right|400px|CF-AX3 Ultrabook, Running Windows 10 / Gentoo Linux]] 5 | 6 | {{Warning|31 Oct 2020: sadly, due to legal obligations arising from a recent change in my 'real world' job, I must announce I am '''standing down as maintainer of this guide with immediate effect''' (for more background, please see my post [https://forums.gentoo.org/viewtopic-p-8522963.html#8522963 here]). 7 | 8 | 9 | While I will be leaving this guide up for now (for historical interest, and because it may still be of use to others), I can no longer recommend that you install a new Gentoo system using it. Instead, please follow the standard [[Handbook:AMD64|Gentoo Handbook]] flow. 10 | 11 | 12 | Similarly, if you are already running a system installed via these instructions, while it ''should'' continue to work for some time, you should now take steps to migrate to a standard, Handbook-based approach, since the underlying {{c|sakaki-tools}} repo, and provided tools such as {{c|buildkernel}}, will also no longer be actively supported. 13 | 14 | 15 | With sincere apologies, sakaki ><}} 16 | 17 | This detailed (and tested) tutorial shows how to set up just such a dual-boot system, where the Gentoo component: 18 | * is fully encrypted on disk (LVM over LUKS, with dual-factor protection); 19 | * uses UEFI secure boot; 20 | * OpenRC & GNOME 3 (on Wayland); 21 | ** ''or'' runs systemd & GNOME 3 (ditto); 22 | * can properly suspend and hibernate; 23 | * has working drivers for touchscreen, webcam etc.; 24 | * has (where appropriate) the Intel Management Engine disabled;As the ME is disabled via an (optional) system firmware modification, it will remain inactive even when booted into Windows. 25 | * and even has a graphical boot splash! 26 | 27 | To keep things concrete, I'll be walking {{Highlight|line-by-line}} through the setup of a particular machine, namely the Panasonic CF-AX3 [[:Wikipedia:Ultrabook|Ultrabook]]; however, these instructions should be usable (with minor alterations) for many modern PCs (including desktops) which have a [[:Wikipedia:Unified_Extensible_Firmware_Interface|UEFI]] BIOS. 28 | 29 | {{Highlight|All}} commands that you'll need to type in are listed, and an ebuild repository (aka 'overlay') with some useful installation utilities is also provided. 30 | 31 | While best read in tandem with the official [[Handbook:Main_Page|Gentoo Handbook]], this manual can also be used standalone. 32 | 33 | These instructions may also be easily adapted for those wishing to use Gentoo Linux as their sole OS, rather than dual booting. 34 | 35 | == Introduction == 36 | 37 | The install described in this tutorial attempts to follow the 'stock' process from the [[Handbook:AMD64|Gentoo Handbook]] where possible, but differs in a number of important respects. Specifically: 38 | * The kernel will be configured to {{Highlight|self-boot}} under UEFI; no separate bootloader is needed. 39 | * For security, we will {{Highlight|boot the kernel off of an external USB key}} (which can be removed once the boot has completed). If the USB key is absent on power-up, Windows will start automatically instead. 40 | * {{Highlight|Secure boot}} will be enabled. The kernel will be signed with our own, generated key (and the original Windows keys will be retained too). 41 | * Gentoo's root, swap and home partitions will reside on {{Highlight|LVM}} logical volumes, which themselves will live on a single {{Highlight|LUKS}} (encrypted) partition on the GPT-formatted hard drive of the machine. We'll shrink the Windows C: NTFS partition to provide space for this. 42 | * The LUKS partition will be {{Highlight|unlocked by a keyfile}} at boot. The keyfile will be stored on the USB key together with the Gentoo kernel, and will ''itself'' be {{Highlight|GPG-encrypted}}, so that both the file ''and'' its passphrase will be needed to access the (Gentoo) data on the hard drive. This provides a degree of dual-factor security against e.g., having the machine stolen with the USB key still in it, or even the existence of a keylogger on the PC itself (although not both at the same time!). (Using a provided utility, you can subsequently migrate the kernel onto the Windows EFI system partition on the main drive if desired, and also relax the security to use just a typed-in passphrase, so once installed you won't need to use a USB key at all if you don't want to.) 43 | * We will create an {{Highlight|initramfs}} to allow the GPG / LUKS / LVM stuff to happen in early userspace, and this RAM disk will be stored inside the kernel itself, so it will work under EFI with secure boot (we'll also, for reasons that will become clear later, build a custom version of {{c|gpg}} to use in this step). 44 | * For all you source-code paranoiacs, the {{Highlight|Gentoo toolchain and core system will be bootstrapped}} during the install (simulating an old-school stage-1) and we'll validate that all binary executables and libraries have indeed been rebuilt from source when done. The {{Highlight|licence model will be set to accept free software only}} (and although I don't deblob the kernel, instructions for how to do so are provided - assuming your hardware will actually work without uploaded firmware!). 45 | * All Gentoo repository syncs (including the initial {{c|emerge-webrsync}}) will be performed with {{Highlight|{{c|gpg}} signature authentication}}. Unauthenticated protocols will ''not'' be used. 46 | * The {{Highlight|latest (3.30+) ''stable'' version of GNOME}} will be installed, using [[OpenRC]] for init (as GNOME is now officially supported under this init system, and no longer requires Dantrell B.'s patchset for this). 47 | ** An alternative track is also provided, for those wishing to install GNOME 3 under [[systemd]]. Most of this tutorial is common to both tracks, and a short guide is provided at the appropriate point in the text, to help you choose which route is better for you. 48 | ** GNOME will be deployed on the modern [[:Wikipedia:Wayland_(display_server_protocol)|Wayland]] platform (including [https://wayland.freedesktop.org/xserver.html XWayland] support for legacy applications) — this is [[/Sandboxing_the_Firefox_Browser_with_Firejail#x11_vulnerability|more secure]] than deploying over X11, as it enforces application isolation at the GUI level. 49 | * I'll provide {{Highlight|simple scripts to automate the EFI kernel creation process and keep your system up-to-date.}} The first of these ({{c|buildkernel}}) handles conforming the kernel config for EFI encrypted boot (including setting the kernel command line correctly), creating the initramfs, building and signing the kernel, and installing it on the EFI system partition. The second ({{c|genup}}) automates the process of updating your system software via {{c|emerge}} and associated tools. The scripts are shipped in an ebuild repository (aka 'overlay'), for easy deployment. 50 | * Lastly, detailed (optional) instructions for {{Highlight|disabling the Intel Management Engine}}For avoidance of doubt, in this guide 'disabled' has the same meaning as 'neutralized and disabled' in the Purism Inc. Blog: [https://puri.sm/posts/deep-dive-into-intel-me-disablement/ "Deep Dive into Intel Management Engine Disablement"] will be provided (for those with Intel-CPU-based PCs who find this out-of-band coprocessor an unacceptable security risk), as will instructions for {{Highlight|fully sandboxing the popular {{c|firefox}} web browser, using {{c|firejail}}}}. 51 | 52 | {{Note|Tutorials covering various elements of the above can be found in one or more places online, but it's difficult to get an end-to-end overview - hence the reason this guide was created.}} 53 | 54 | As mentioned, although this tutorial follows the format of the [[Handbook:AMD64|Gentoo Handbook]] in places (particularly at the beginning), it's structured so as to be self-contained - you should be able to walk though this process and, using only these instructions, end up with a fully functional, relatively secure dual-boot Windows 10 (or 8) + Gentoo / GNOME 3 machine when you're done. 55 | 56 | {{Warning|Backup '''all''' of your data before doing anything else, particularly if you have a lot of work stored on Windows already. The install process described here has been tested end-to-end, ''but'' is provided 'as is' and without warranty. Proceed at your own risk.}} 57 | {{Warning|Tools like {{c|parted}}, {{c|dd}} and {{c|cryptsetup}}, which we'll be using, can vaporize data easily if misused. Please always double check that you are ''applying operations to the correct device / partition''. We've all been there...}} 58 | {{Warning|We will be using strong cryptography to protect your system. If you lose the LUKS keyfile, or forget the passphrase to unlock it, '''all your data will be gone''', and even the NSA (probably!) won't be able to get it back.TechCrunch: [http://techcrunch.com/2013/06/17/encrypting-your-email-works-says-nsa-whistleblower-edward-snowden/ "Encrypting Your Email Works, Says NSA Whistleblower Edward Snowden"] So keep backups of these critical elements too (in a safe place, of course)!}} 59 | 60 | == Chapters == 61 | 62 | The chapters of this tutorial are listed below, together with a brief summary of each. 63 | 64 | {{Highlight|You need to work though the chapters sequentially, in order to complete the install successfully.}} 65 | 66 | {{Note| Don't worry if you don't immediately understand everything in the chapter summaries below: the concepts involved will be described in detail in the main body of the text.}} 67 | 68 | # '''[[/Installation_Prerequisites|Installation Prerequisites]]'''. First, we'll briefly review the things you'll need in order to carry out the install. 69 | # '''[[/Preparing_Windows_for_Dual-Booting|Preparing Windows for Dual-Booting]]'''. Next, we'll reduce the amount of space Windows takes up on the target machine's hard drive, so there is room for our Gentoo system (and user data). We'll use tools already present in Windows to do this. 70 | # '''[[/Creating_and_Booting_the_Minimal-Install_Image_on_USB|Creating and Booting the Minimal-Install Image on USB]]'''. Then, per [[Handbook:AMD64/Installation/Media|Chapter 2]] of the Gentoo handbook, we'll download a minimal Gentoo image onto a USB key, and boot into it on our target PC (in EFI / {{c|OpenRC}} mode, with secure boot temporarily turned off). 71 | # '''[[/Setting_Up_Networking_and_Connecting_via_ssh|Setting Up Networking and Connecting via ssh]]'''. Next, per [[Handbook:AMD64/Installation/Networking|Chapter 3]] of the handbook, we'll setup network access for our minimal system, and connect in to it from a second, 'helper' PC via {{c|ssh}} (to ease installation). 72 | # '''[[/Preparing_the_LUKS-LVM_Filesystem_and_Boot_USB_Key|Preparing the LUKS-LVM Filesystem and Boot USB Key]]'''. After that, we'll create a GPG-protected keyfile on a second USB key, create a LUKS (encrypted) partition on the machine's hard drive protected with this key, and then create an LVM structure (root, home and swap) on top of this (achieving the goals of [[Handbook:AMD64/Installation/Disks|Chapter 4]] of the handbook). 73 | # '''[[/Installing_the_Gentoo_Stage_3_Files|Installing the Gentoo Stage 3 Files]]'''. Then, per [[Handbook:AMD64/Installation/Stage|Chapter 5]] of the handbook, we'll download a Gentoo 'stage 3' minimal filesystem, and install it into the LVM root. We'll also set up your Portage build configuration. 74 | # '''[[/Building_the_Gentoo_Base_System_Minus_Kernel|Building the Gentoo Base System Minus Kernel]]'''. Next, per [[Handbook:AMD64/Installation/Base|Chapter 6]] of the handbook, we'll complete some final preparations, then {{c|chroot}} into the stage 3 filesystem, update our Portage tree, and set a base profile, timezone and locale. We'll setup the {{c|sakaki-tools}} ebuild repository (which contains utilities to assist with the build), and install the first of these, {{c|showem}} (a program to monitor parallel {{c|emerge}}s). Then, we'll bootstrap the toolchain (simulating an old-school stage 1 install), rebuild everything in the {{c|@world}} set, and verify that all libraries and executables have, in fact, been rebuilt. (Instructions are also provided for those who wish to skip bootstrapping). We'll then set the 'real' GNOME profile, and then update the {{c|@world}} set to reflect this. 75 | # '''[[/Configuring_and_Building_the_Kernel|Configuring and Building the Kernel]]'''. Next, (loosely following [[Handbook:AMD64/Installation/Kernel|Chapter 7]] of the handbook), we'll setup necessary licenses, then download the Linux kernel sources and firmware. We'll then install (from the {{c|sakaki-tools}} ebuild repository) the {{c|buildkernel}} utility, configure it, and then use ''this'' to automatically build our (EFI-stub) kernel ({{c|buildkernel}} ensures our kernel command line is filled out properly, the initramfs contains a static version of {{c|gpg}}, that the kernel has all necessary options set for {{c|systemd}}, etc.). 76 | # '''[[/Final_Preparations_and_Reboot_into_EFI|Final Preparations and Reboot into EFI]]'''. Then, following [[Handbook:AMD64/Installation/System|Chapter 8]] of the handbook, we'll set up {{Path|/etc/fstab}}, install a few other packages, set up a root password, then dismount the {{c|chroot}} and reboot (in EFI / {{c|OpenRC}} mode, or EFI / {{c|systemd}} mode, depending on the track) into our new system (secure boot will still be off at this stage). Users on the OpenRC track will [[#alternative_track|branch off]] at the conclusion of this chapter. 77 | # '''[[/Completing_OpenRC_Configuration_and_Installing_Necessary_Tools|Completing OpenRC Configuration and Installing Necessary Tools]]'''. With the machine restarted, we'll re-establish networking and the {{c|ssh}} connection, then complete the setup of {{c|systemd}}'s configuration. Per [[Handbook:AMD64/Installation/Tools|Chapter 9]] of the Gentoo handbook, we'll then install some additional system tools (such as {{c|cron}}). Next, we'll install (from the {{c|sakaki-tools}} ebuild repository) the {{c|genup}} utility, and use it to perform a precautionary update of the {{c|@world}} set. Then, we'll reboot to check our {{c|OpenRC}} configuration. If successful, we'll invoke {{c|buildkernel}} again, to enable the {{c|plymouth}} graphical boot splash, and restart once more to test it. 78 | # '''[[/Configuring_Secure_Boot_under_OpenRC|Configuring Secure Boot under OpenRC]]'''. Next, we'll set up secure boot. First, we'll save off the existing state of the secure boot variables (containing Microsoft's public key-exchange-key, etc.). Then, we'll create our own platform, key-exchange and kernel-signing keypairs, and then reboot, ''en route'' using the BIOS GUI to enter setup mode (thereby clearing the variables, and enabling us to write to them). We'll then re-upload the saved keys, append our own set, and finally lock the platform with our new platform key. We'll then run {{c|buildkernel}} again, which will now be able to automatically sign our kernel. We'll reboot, enable secure boot in the BIOS, and verify that our signed kernel is allowed to run. Then, we'll reboot into Windows, and check we haven't broken ''its'' secure boot operation! Finally, we'll reboot back to Linux again (optionally setting a BIOS password as we do so). 79 | # '''[[/Setting_up_the_GNOME_3_Desktop_under_OpenRC|Setting up the GNOME 3 Desktop under OpenRC]]'''. Next, we'll setup your graphical desktop environment. We'll begin by creating a regular (non-root) user, per [[Handbook:AMD64/Installation/Finalizing#Adding_a_user_for_daily_use|Chapter 11]] of the handbook. Then, we'll activate the {{c|wayland}} USE flag globally, and update your system to reflect this, after which we'll install X11 and a simple window manager ({{c|twm}}) (for test purposes). Using {{c|buildkernel}}, we'll then reconfigure and rebuild the kernel to include an appropriate [[:Wikipedia:Direct_Rendering_Manager|DRM]] graphics driver, and then reboot. Upon restart, we'll verify that the new DRM driver (which {{c|wayland}} requires) has been activated, and then test-run X11 (and a few trivial applicators) under {{c|twm}}. Once working, we'll remove the temporary window manager, install GNOME 3 (and a few key applications), and configure and test it under X11. Then, we'll test it again under {{c|wayland}}, refine a few settings (network, keyboard etc.), and then restart the machine and proceed with the install, working natively within GNOME thereafter. 80 | # '''[[/Final_Configuration_Steps_under_OpenRC|Final Configuration Steps under OpenRC]]'''. Next, we'll configure your kernel to properly handle all your target PC's devices. Although this setup will necessarily differ from machine to machine, a general methodology is provided, together with a concrete set of steps required for the Panasonic CF-AX3 (covering setup of its integrated WiFi, Bluetooth, touchscreen, audio and SD card reader). Thereafter, we'll cover some final setup points - namely, how to: prune your kernel configuration (and initramfs firmware) to remove bloat; get suspend and hibernate working properly; and disable {{c|sshd}} (as the helper PC is no longer needed from this point). 81 | # '''[[/Using_Your_New_Gentoo_System_under_OpenRC|Using Your New Gentoo System under OpenRC]]'''. Now your dual-boot system is up and running, in this last chapter we'll cover a few miscellaneous (but important) topics (and options) regarding day-to-day use. We'll first recap how to boot from Linux to Windows (and vice versa), then discuss how to ensure your machine is kept up to date (using {{c|genup}}). We'll also show how to migrate your kernel to the internal drive (Windows) EFI system partition if desired (and also, how to dispense with the USB key entirely, if single-factor passphrase security is sufficient). In addition, we'll briefly review how to tweak GNOME, and (per [[Handbook:AMD64/Installation/Finalizing#Where_to_go_from_here|Chapter 11]] of the handbook) where to go next (should you wish to install other applications, a firewall, etc.). Finally, a number of addendum "mini-guides" are provided, covering how to ''e.g.'', [[/Disabling_the_Intel_Management_Engine|disable the Intel Management Engine]] on your target PC, and [[/Sandboxing_the_Firefox_Browser_with_Firejail|fully sandbox the {{c|firefox}} web browser, using {{c|firejail}}]]. 82 | 83 | 84 | As mentioned, an 'alternative track' is also provided for chapters 10-14, for those users who wish to use GNOME with {{c|systemd}}, rather than {{c|OpenRC}}: 85 |
    86 |
  1. '''[[/Configuring_systemd_and_Installing_Necessary_Tools|Alternative Track: Configuring systemd and Installing Necessary Tools (under systemd)]]'''
    2. 87 |
  2. '''[[/Configuring_Secure_Boot|Alternative Track: Configuring Secure Boot (under systemd)]]'''
    3. 88 |
  3. '''[[/Setting_up_the_GNOME_3_Desktop|Alternative Track: Setting up the GNOME 3 Desktop (under systemd)]]'''
    4. 89 |
  4. '''[[/Final_Configuration_Steps|Alternative Track: Final Configuration Steps (under systemd)]]'''
    5. 90 |
  5. '''[[/Using_Your_New_Gentoo_System|Alternative Track: Using Your New Gentoo System (under systemd)]]'''
    6. 91 |
92 | 93 | {{Note|The decision about which init system ({{c|OpenRC}} or {{c|systemd}}) to use does not need to be made until Chapter 7 (where a brief summary of the pros and cons of each will be provided, to help you decide).}} 94 | 95 | == Let's Get Started! == 96 | 97 | Ready? Then [[/Installation_Prerequisites|click here]] to go to the first chapter, "Installation Prerequisites". 98 | 99 | {{Note|As is hopefully clear from the above, this tutorial covers a detailed, end-to-end installation walkthrough.
If you are searching for more concise, topic-based {{c|EFI}}, {{c|systemd}} or {{c|GNOME}} installation information, the following Wiki pages may be of use to you instead: 100 | * [[UEFI_Gentoo_Quick_Install_Guide{{!}}UEFI Gentoo Quick Install Guide]] 101 | * [[EFI_stub_kernel|EFI stub kernel]] 102 | * [[systemd|systemd]] 103 | * [[systemd/Installing_Gnome3_from_scratch{{!}}systemd/Installing Gnome3 from scratch]] 104 | * [[GNOME/GNOME_without_systemd{{!}}GNOME/GNOME without systemd]]}} 105 | 106 | {{Note|If you have recently upgraded {{Package|dev-libs/libgcrypt}} to version >{{=}} 1.6, and found yourself thereby locked out of your (Whirlpool-hashed) LUKS partition, please see [[/Migrating_from_Whirlpool_Hash_on_LUKS|this short guide]] on how to recover.}} 107 | 108 | {{Note|Comments, suggestions and feedback about this guide are welcomed! You can use the "Discussion" tab (of whatever is the most relevant page) for this purpose. On most browsers, you can use {{Key|Shift}}{{Key|Alt}}{{Key|t}} as a shortcut to access this.}} 109 | 110 | {{Tip|While the [https://mediawiki.org/ MediaWiki] ''source'' for individual pages of this guide may most easily be edited or viewed on the Gentoo Wiki directly, for ease of download the full page set is also maintained on GitHub, [https://github.com/sakaki-/efi-install-guide-source here]. }} 111 | 112 | == Notes == 113 | {{reflist}} 114 | 115 | [[Category:Sakaki's EFI Install Guide]] 116 | 117 | -------------------------------------------------------------------------------- /01_Installation_Prerequisites: -------------------------------------------------------------------------------- 1 | 2 | 3 | The installation process described in this manual has a small number of prerequisites, which are listed below. 4 | 5 | {{Highlight|Make sure that you have everything before starting out!}} 6 | 7 | == What You'll Need == 8 | 9 | To work through this install, you will need: 10 | * A {{Highlight|target, UEFI PC}} with Windows-10 (or 8 or 8.1) pre-installed (for example, an [[:Wikipedia:Ultrabook|Ultrabook]]). I'm going to assume you have already set up Windows, that you have an admin account (the first user on the machine automatically has admin rights), and that you haven't used up all the disk space on {{Path|C:}} yet.{{Note|Obviously, you can adapt the following instructions to create a single-OS Gentoo system very easily, if you don't have Windows, or want to wipe it. However, I'm only going to deal with the dual-boot scenario in this tutorial, as it is the more complicated case.}}{{Important|At the time of writing, it appears that machines designated as "Designed for Windows 10" do ''not'' have to provide the option to turn off secure boot, as Windows 8 certified machines did.Ars Techica: [http://arstechnica.com/information-technology/2015/03/windows-10-to-make-the-secure-boot-alt-os-lock-out-a-reality/ "Windows 10 to make the Secure Boot alt-OS lock out a reality"]PCWorld: [http://www.pcworld.com/article/2901262/microsoft-tightens-windows-10s-secure-boot-screws-where-does-that-leave-linux.html "Microsoft tightens Windows 10's Secure Boot screws: Where does that leave Linux?"] It remains to be seen how this will pan out, and whether OEMs will continue to provide the option. However, this option '''is''' necessary to complete this tutorial (because, although we ''will'' use secure boot ultimately, to do so we will need to add our own custom keys into the keystore, a process which is done from an unsecured UEFI-booted session), so if you intend using a PC that has the "Designed for Windows 10" mark, please check before proceeding that its BIOS still affords you the option.}} 11 | * {{Highlight|Two USB keys}}, one of at least 500MB, and the other of at least 250MB: 12 | ** the larger one is for the initial Gentoo minimal-install disk image, which we'll use to get the ball rolling; and 13 | ** the smaller one is where we'll place our compiled, UEFI bootable Gentoo Linux kernel and keyfile (we'll refer to this as the '''boot USB key''' throughout the rest of the tutorial). 14 | : {{Note|It is of course possible to boot from a burned CD, DVD etc., but in the modern day USB keys tend to be ubiquitous (and many laptops have no optical drive), so that's the route I'll take here. By the way, it's no problem if your USB keys are bigger, even much bigger, than the minimum sizes stipulated above: and indeed it is probably a good idea for the boot USB key to be 500MB or greater in size, to allow for kernel backups and so on.}} 15 | * A {{Highlight|working subnet}} to which the install target machine can be connected. To be concrete, I'm going to assume a {{Highlight|192.168.1.0/24}} subnet, but yours may of course be different, in which case modify the instructions accordingly. There must be a {{Highlight|gateway}} on the network providing Internet access, and a [[:Wikipedia:Dynamic_Host_Configuration_Protocol|DHCP]] server. Furthermore, your target PC must have either: 16 | :# a wired Ethernet adapter with driver support in the Gentoo minimal-install image (most do). This is the simplest option from an installation perspective, even if you intend going wireless once the system is up and running. WiFi routers usually have ports on the back into which you can plug Ethernet cables directly; or 17 | :# a WiFi modem with driver support in the Gentoo minimal-install image (many do). The tutorial covers setting up such a connection over [[:Wikipedia:Wi-Fi_Protected_Access|WPA/WPA2]], since this is the most common modern use case. 18 | :: {{Note|It is of course still possible to perform an install in other network configurations (for example, where you wish to use an open WiFi network, static IP addresses, proxies etc.). Please refer to [[Handbook:AMD64/Installation/Networking#Manual_network_configuration|Chapter 3 of the Gentoo Handbook]] for more details, where necessary during the tutorial.}} 19 | :: {{Note|If your machine's WiFi is not operational under the minimal-install image, ''and'' it has no Ethernet port of its own, you could consider buying an inexpensive USB-to-Ethernet adaptor (for example, I have used [https://www.amazon.co.uk/dp/B00AQM8586 this one] successfully on a number of Gentoo netbook installs).}} 20 | * A {{Highlight|second, 'helper' PC, running Linux}}, on the same subnet. Of course, this is not ''strictly'' required - you ''can'' do everything on the target machine itself. However, having a second machine really helps, because: 21 | ** once the initial, minimal-install image has booted, you can {{c|ssh}} in to it from this second box, and run {{c|[[:Wikipedia:GNU_Screen{{!}}screen]]}}; this gives you the ability to copy and paste commands and scripts from this tutorial, and to disconnect when lengthy processes are running, reconnecting later; and 22 | ** creation of the initial USB images etc. is easier from Linux than from Windows; although you ''can'' create the setup disks using Windows, I won't be covering the necessary steps here. 23 | : {{Note|You don't have to run Gentoo Linux natively on this second box either. For example, if you are starting from an 'all Windows' configuration, you could create a bootable Ubuntu live USB keyUbuntu: [http://www.ubuntu.com/download/desktop/create-a-usb-stick-on-windows "How to create a bootable USB stick on Windows"] and boot your helper PC from that (it will allow you to work without damaging anything on the machine's hard drive).}} 24 | 25 | == Commencing the Install == 26 | 27 | Got everything? Then [[../Preparing_Windows_for_Dual-Booting|click here]] to go to the next chapter, "Preparing Windows for Dual-Booting". 28 | 29 | == Notes == 30 | {{reflist}} 31 | 32 | {| class="wikitable" style="margin: 1em auto 1em auto;" 33 | |- 34 | | < Previous 35 | | [[../|Home]] 36 | | [[../Preparing_Windows_for_Dual-Booting|Next >]] 37 | |} 38 | 39 | [[Category:Sakaki's EFI Install Guide]] 40 | 41 | -------------------------------------------------------------------------------- /02_Preparing_Windows_for_Dual-Booting: -------------------------------------------------------------------------------- 1 | 2 | 3 | As shipped, a typical Windows 10 (or Windows 8) installation spans its host machine's entire drive. 4 | 5 | Accordingly, our first order of business is to shrink the size of the Windows {{Path|C:}} partition, thereby freeing up some space on which to install our new Gentoo system. 6 | 7 | The good news is that Windows already contains the necessary tools to shrink partitions. The not-so-good news is that Windows also sprinkles various files around the drive (for hibernation, paging and system restore), such that even if you have just started using the machine, without some additional work you can only reclaim about half of your {{Path|C:}} drive for Linux. 8 | 9 | But, fear not: the instructions below will show you how to get around this restriction.Download 3K: [http://www.download3k.com/articles/How-to-shrink-a-disk-volume-beyond-the-point-where-any-unmovable-files-are-located-00432 "How to shrink a disk volume beyond the point where any unmovable files are located"] 10 | 11 | {{Note|A similar process may be used to free up space in a Windows 7 system too.SuperUser Forum: [http://superuser.com/questions/88131/how-to-shrink-windows-7-boot-partition-with-unmovable-files "How to shrink Windows 7 boot partition with unmovable files"]}} 12 | 13 | == Shrinking Windows' Disk Footprint == 14 | 15 | Boot your target machine into Windows as normal, and login to your account (which must have administrator rights - the first user created on a new Windows install has these by default). Next, perform the following steps (I have noted where things differ between Windows 10, 8.1 and 8): 16 | {{Note|For Windows 10 users, the following assumes you are logged in with a local account and have options like "Search online and include web results" and Cortana turned off.Gizmodo UK: [http://www.gizmodo.co.uk/2015/11/windows-10-privacy-settings-what-you-need-to-know/ "Windows 10 Privacy Settings: What You Need to Know"] If you are running Windows 10 with more permissive settings, be sure to choose the correct item from those returned when directed to perform a search in the following instructions. The correct items will generally be tagged as "Control panel" or "Desktop app".}} 17 | 18 | # Ensure you have '''backups''' of everything important. Last chance ^-^ 19 | # Done that? OK then, to begin with, we'll {{Highlight|turn off system protection (restore points)}}.Ubuntu Forums: [http://ubuntuforums.org/showthread.php?t=2087466#post_message_12372055 "shrinking Windows 8 partition for dual boot"] Hit the {{Key|Windows Key}}, which will bring up the start menu in Windows 10 (or the "start screen" in Windows 8.1 and 8), and type restore point. Then click on the 'Create a restore point' item which appears (in Windows 10 and 8.1; Windows 8 users will need to click the 'Settings' icon to see this result). You will now be presented with a dialog box with 'System Protection' as the selected tab. Choose the relevant drive (generally, {{Path|C:}}). Click the 'Configure...' button. Another dialog pops up - click on the 'Disable system protection' radio button, and click 'OK'. When asked if you are sure, click 'Yes'. (N.B., this will remove existing restore points from the drive, if any; if they are important to you, do not perform this step.) Close out the other dialogs by clicking on 'OK'. 20 | # Next, we'll {{Highlight|turn off the virtual memory paging file}}. Hit the {{Key|Windows Key}}, which will bring up the start menu in Windows 10 (or the "start screen" in Windows 8.1 and 8), and type adjust the appearance. Then click on the 'Adjust the appearance and performance of Windows' item that appears (in Windows 10 and 8.1; Windows 8 users will again need to click the 'Settings' icon to see this result). You will now be presented with a 'Performance Options' dialog; select the 'Advanced' tab in it. In the virtual memory area, click on 'Change...', and, in the dialog that next appears, untick 'Automatically manage paging file size for all drives', then choose the relevant drive (generally, {{Path|C:}}), select the 'No paging file' radio button and click 'Set'. You'll get warnings about the problems this can cause; if happy to proceed select 'Yes', then choose 'OK' again to close out the Virtual Memory dialog itself. If you get a warning about needing to reboot, accept this (but don't reboot yet). Then close out any remaining dialogs. 21 | # Now to {{Highlight|turn off hibernation}}. This is most easily done from the Windows command line. Hit the {{Key|Windows Key}} , which will bring up the start menu in Windows 10 (or the "start screen" in Windows 8.1 and 8), and type command. Now ''right-click'' on the 'Command Prompt' icon that appears, then click on 'Run as administrator' item in the context menu (in Windows 10 and 8.1; it appears at the bottom of the screen in Windows 8). If asked whether you wish to proceed, click 'Yes'. You will be presented with an open command window. Now enter powercfg /H off. After this, hit {{Key|Ctrl}}{{Key|Alt}}{{Key|Delete}}, then click on the power icon at the bottom right of the screen, and choose 'Restart' from the pop-up menu. 22 | # Allow the machine to reboot back into Windows, and log in again. 23 | # Now we will {{Highlight|defragment the drive}}. Hit the {{Key|Windows Key}}, which will bring up the start menu in Windows 10 (or the "start screen" in Windows 8.1 and 8), and type defragment. Then click on the 'Defragment and Optimize Drives' item that appears (in Windows 10; in Windows 8.1 and 8 the required item is named 'Defragment and optimize your drives'). Select the {{Path|C:}} drive in the dialog box that appears, and select 'Optimize' (this will defragment the drive). When it has completed, click the 'Close' button to dismiss the dialog. 24 | # Follow the process described earlier to reboot and log in again to Windows. (Without this reboot, the shrink step below may fail.) 25 | # Finally, we are ready to {{Highlight|shrink the Windows partition}}.Liberian Geek: [http://www.liberiangeek.net/2012/11/shrink-resize-partitions-in-windows-8/ "Shrink / Resize Partitions in Windows 8"] Hit {{Key|Windows Key}}, which will bring up the start menu in Windows 10 (or the "start screen" in Windows 8.1 and 8), and type partitions. Then click on the 'Create and format hard disk partitions' item that appears (in Windows 10 and 8.1; Windows 8 users will again need to click the 'Settings' icon to see this result). ''Right click'' on the {{Path|C:}} partition in the display for Disk0 at the bottom of the 'Disk Management' dialog that appears, and select 'Shrink Volume...' from the context menu. Another dialog entitled 'Shrink {{Path|C:}}' appears. If all has gone according to plan with the changes above, you should now be able to enter quite a large amount of shrink space: enter (as you wish) anything up to the maximum amount allowed as shown on the dialog:[[File:Win8PartitionShrink.png|thumb|none|400px|Shrinking the C: Partition in Windows]] To proceed, click on 'Shrink'. When the process completes, you should now see an additional 'Unallocated' partition at the end of Disk 0 on the 'Disk Management' dialog, and it should be a meaningful percentage of the drive (note that the partition graphical display is not proportional). Note: as an indication, I was able to create a 195.86GB unallocated partition using this method (on a 238.35GB drive, with the {{Path|C:}} partition shrunk to 42.10GB from 237.96GB). [https://en.wiktionary.org/wiki/your_mileage_may_vary YMMV]. {{Note|If you encounter a problem during the shrink operation, for example Windows informing you that there is not enough disk space available to complete the operation, then try performing a shrink of ''half'' of the claimed 'available shrink space', and then immediately repeating if successful.}}{{Note|With certain versions of Windows, you may find that the very end of the disk contains a recovery partition (and possibly a number of additional "OEM" partitions). That's nothing to worry about, just shrink the {{Path|C:}} partition as described — you'll still be able to install Gentoo onto the space you have freed up, even if it does not span completely to the end of the drive.}}{{Note|How much space to free up for Gentoo / leave for Windows will obviously depend upon your particular usage pattern. You should probably aim to free up a ''minimum'' of 20GB or so for Gentoo, however. If you are running Windows 8 or 8.1, and planning to upgrade to Windows 10 in the future, you should ensure that your Windows {{Path|C:}} partition has a ''minimum'' of 5GB free space after the shrink.WindowsCentral: [http://www.windowscentral.com/how-prepare-your-pc-windows-10-upgrade "How to prepare your PC for the Windows 10 upgrade"] (see section "Making space for the upgrade") (Incidentally, even once Gentoo is co-installed, you ''can'' safely upgrade to Windows 10 without harming the Linux side of things; in this author's experience anyhow.)}} 26 | # For safety, follow the process described earlier to reboot and log in ''again'' to Windows. This ensures that all system processes take note of the new partition boundaries. 27 | # Now we'll revert the changes we made to Windows (other than the partition shrink!), prior to installing Gentoo Linux on our newly reclaimed disk space. First, we'll {{Highlight|turn on hibernation again}}. Hit the {{Key|Windows Key}} , which will bring up the start menu in Windows 10 (or the "start screen" in Windows 8.1 and 8), and type command. Now ''right-click'' on the 'Command Prompt' icon that appears, then click on 'Run as administrator' item in the context menu (in Windows 10 and 8.1; it appears at the bottom of the screen in Windows 8). If asked whether you wish to proceed, click 'Yes'. You will be presented with an open command window. Now enter powercfg /H on. Note that although this enables hibernation, the option to trigger it may still be hidden in the power menu, even after you reboot. We'll fix this shortly. 28 | # Next, let's {{Highlight|activate the virtual memory paging file again}}. Hit the {{Key|Windows Key}}, which will bring up the start menu in Windows 10 (or the "start screen" in Windows 8.1 and 8), and type adjust the appearance. Then click on the 'Adjust the appearance and performance of Windows' item that appears (in Windows 10 and 8.1; Windows 8 users will again need to click the 'Settings' icon to see this result). You will now be presented with a 'Performance Options' dialog; select the 'Advanced' tab in it. In the virtual memory area, click on 'Change...', and, in the dialog that next appears, tick 'Automatically manage paging file size for all drives', then choose 'OK' to close out the Virtual Memory dialog. If you get a warning about needing to reboot, accept this (but don't reboot yet). Close out all the remaining dialogs. 29 | # Now we'll {{Highlight|turn on system protection (restore points) again}}. Hit the {{Key|Windows Key}}, which will bring up the start menu in Windows 10 (or the "start screen" in Windows 8.1 and 8), and type restore point. Then click on the 'Create a restore point' item which appears (in Windows 10 and 8.1; Windows 8 users will again need to click the 'Settings' icon to see this result). You will now be presented with a dialog box with 'System Protection' as the selected tab. Choose the relevant drive (generally, {{Path|C:}}). Click the 'Configure...' button. Another dialog pops up - click on the 'Turn on system protection' radio button, and click 'OK'. Close out the other dialogs by clicking on 'OK'. 30 | # Follow the process described earlier to reboot and log in one last time to Windows. Check that everything still works as expected. 31 | # The final step is to ensure that {{Highlight|hibernation shows up on the Windows power menu}}.AddictiveTips: [http://www.addictivetips.com/windows-tips/how-to-enable-windows-8-hibernate-option/ "How To Enable Windows 8 Hibernate Option"]Winaero: [http://winaero.com/blog/add-hibernate-to-the-start-menu-in-windows-10/ "Add Hibernate to the Start Menu in Windows 10"] Hit the {{Key|Windows Key}}, which will bring up the start menu in Windows 10 (or the "start screen" in Windows 8.1 and 8). What you need to do next depends on your Windows version. In Windows 10, type power options, and click on the 'Power Options' item which appears (in newer versions of Windows 10, the item has been renamed; you should click on 'Power & sleep settings' instead); then, click 'Choose what the power button does' in the presented dialog box (in newer versions of Windows 10 you will need to click on 'Additional power settings' to see this dialog; the item you want inside it has been renamed also, to 'Choose what the power buttons do'). In Windows 8.1 or 8, type power buttons, then click on the 'Change what the power buttons do' item that appears (Windows 8 users will again need to click the 'Settings' icon to see this result). For all version of Windows, next click on the 'Change settings that are currently unavailable' link in the 'System Settings' dialog. In response, the dialog will display some 'Shut-down settings' (Windows 10) or 'Power options settings' (Windows 8.1 and 8). Ensure 'Hibernate' (in Windows 10) or 'Show Hibernate' (in Windows 8.1 and 8) is checked. You should also ensure that the entry 'Turn on fast startup (recommended)' is ''unchecked'' (this entry might be called 'Hybrid Boot', depending on your system version),ArchLinux Wiki:[https://wiki.archlinux.org/index.php/Windows_and_Arch_Dual_Boot#Fast_Start-Up "Windows and Arch Dual Boot: Fast Start-Up"] and then click the 'Save Changes' button (if you had to make any modifications). Hibernation should now be an option on the power menu. Hit {{Key|Ctrl}}{{Key|Alt}}{{Key|Delete}}, then click on the power icon at the bottom right of the screen, to make sure. ''Don't'' actually hibernate the machine though, simply cancel back out to the main screen, once you've verified that the item is now present. 32 | 33 | == Next Steps == 34 | 35 | Although we're done with our Windows prep work for now, leave the target machine running Windows for the moment. [[../Creating_and_Booting_the_Minimal-Install_Image_on_USB|Click here]] to go to the next chapter, "Creating and Booting the Minimal-Install Image on USB". 36 | 37 | == Notes == 38 | {{reflist}} 39 | 40 | {| class="wikitable" style="margin: 1em auto 1em auto;" 41 | |- 42 | | [[../Installation_Prerequisites|< Previous]] 43 | | [[../|Home]] 44 | | [[../Creating_and_Booting_the_Minimal-Install_Image_on_USB|Next >]] 45 | |} 46 | 47 | [[Category:Sakaki's EFI Install Guide]] 48 | 49 | -------------------------------------------------------------------------------- /03_Creating_and_Booting_the_Minimal-Install_Image_on_USB: -------------------------------------------------------------------------------- 1 | 2 | 3 | We can now proceed to download, verify and use the {{Highlight|Gentoo minimal install image}}. This is a bootable, self-contained Linux system [[:Wikipedia:ISO_image|ISO disk image]], updated regularly by Gentoo Release Engineering. As the name suggests, you can boot your target PC with it and, assuming you have internet access, parlay from there to a full Gentoo installation. 4 | 5 | This section shadows [[Handbook:AMD64/Installation/Media|Chapter 2]] of the Gentoo handbook. 6 | 7 | {{Note|For simplicity, I'll assume you're doing this on your secondary, ''helper'' PC, which is running Linux. I'll denote that machine as {{Highlight|pc2}} in the command prompts.}} 8 | 9 | == Downloading and Verifying the ISO Image == 10 | 11 | Firstly, identify the name of the current release of the minimal install ISO (we'll refer to it using the generic form {{c|install-amd64-minimal-YYYYMMDDThhmmssZ.iso}} below). New versions come out multiple times per year. Open the link http://distfiles.gentoo.org/releases/amd64/autobuilds/latest-iso.txt in a browser to determine the current name. 12 | 13 | {{Important|Be sure to use an up-to-date version of this image: those issued ''prior'' to August 2018 only support booting in legacy, not EFI, mode,Gentoo Forums: [https://forums.gentoo.org/viewtopic-t-1041178.html "The Gentoo minimal installation CD doesn't boot in UEFI"]Gentoo Forums: [http://forums.gentoo.org/viewtopic-t-967098-start-0.html#7377910 "Gentoo Minimal ISO EFI Boot?"] and so are unsuitable for use with this tutorial.Advanced users: it ''is'' possible to ''adapt'' legacy images so they will boot on EFI, as I describe [[../Booting_Legacy_Images_on_EFI_using_kexec{{!}}here]].}} 14 | 15 | {{Note|The variant part of the name is a ''timestamp'' — the first component of which is a date, then a 'T' separator, then a time, then finally a 'Z' (to denote UTC, or 'zero hours offset'). So for example, a real filename might be {{c|install-amd64-minimal-20180107T214502Z.iso}}, indicating that it was written at 9:45pm (and 2 seconds), on the 7th of January 2018.}} 16 | 17 | {{Note|We'll be using the {{c|amd64}} architecture (processor family) in what follows. The reference to 'amd' is an [[AMD64/FAQ{{!}}historical artifact]]; ''all'' modern 64-bit x86 CPUs (including those from Intel) should use this architecture in Gentoo.}} 18 | 19 | Open a terminal window on the helper PC, and download the necessary files (the ISO, a contents list for that ISO, and a signed digest list): 20 | {{Cmd 21 | |cd /tmp 22 | |wget -c http://distfiles.gentoo.org/releases/amd64/autobuilds/YYYYMMDDThhmmssZ/install-amd64-minimal-YYYYMMDDThhmmssZ.iso 23 | |wget -c http://distfiles.gentoo.org/releases/amd64/autobuilds/YYYYMMDDThhmmssZ/install-amd64-minimal-YYYYMMDDThhmmssZ.iso.CONTENTS 24 | |wget -c http://distfiles.gentoo.org/releases/amd64/autobuilds/YYYYMMDDThhmmssZ/install-amd64-minimal-YYYYMMDDThhmmssZ.iso.DIGESTS.asc 25 | |prompt=user@pc2 $}} 26 | 27 | {{Note|Of course, substitute the correct release timestamp (which you just looked up) for YYYYMMDDThhmmssZ in the above commands.}} 28 | 29 | This may take a little time to complete, depending on the speed of your Internet link. 30 | 31 | We next need to check the integrity of the ISO, before using it. The {{c|install-amd64-minimal-YYYYMMDDThhmmssZ.iso.DIGESTS.asc}} file contains cryptographically signed digests (using various hash algorithms) for two other files you have downloaded. 32 | 33 | As such, to verify the ISO we must: 34 | # download the public key used for Gentoo automated weekly releases (if you don't already have this on your helper PC); 35 | # check the signature of the {{c|install-amd64-minimal-YYYYMMDDThhmmssZ.iso.DIGESTS.asc}} file using this key; and then 36 | # check that the hashes (digests) contained in that file agree with values that we compute independently. 37 | 38 | {{Note|For a brief primer on digital signatures, see the [[../Configuring_Secure_Boot#digital_signatures_primer{{!}}"Configuring Secure Boot"]] chapter of this tutorial.}} 39 | 40 | The fingerprint of the automated weekly release public key may be found on the [[Project:RelEng|Gentoo Release Engineering]] page. When requesting the key from a keyserver, you don't need to cite the whole fingerprint, just enough of it to be unambiguous. For example, at the time of writing, the automated release key fingerprint was {{c|13EB BDBE DE7A 1277 5DFD B1BA BB57 2E0E 2D18 2910}}, so to download it (step 1 in the above list), issue: 41 | 42 | {{Cmd 43 | |gpg --keyserver pool.sks-keyservers.net --recv-key 2D182910 44 | |prompt=user@pc2 $}} 45 | 46 | {{Note|If this command fails, ensure you have enabled outbound access on your firewall for port 11371/tcp to allow [[:Wikipedia:Key_server_(cryptographic)|HKP]] communication, along with the usual state-tracking input rule.
Alternatively, you can use the following command, to fetch the key over port 80 (which should be open on most firewalls):{{Cmd 47 | |gpg --keyserver hkp://pool.sks-keyservers.net:80 --recv-key 2D182910 48 | |prompt=user@pc2 $}}}} 49 | {{Note|If the above keyserver is unavailable for some reason, you should be able to use any other one, such as {{c|pgp.mit.edu}} for example.}} 50 | {{Note|If the fingerprint has changed, substitute the correct value for 2D182910 in the above.}} 51 | 52 | You should next verify that the key's ''full'' fingerprint matches that listed on the [[Project:RelEng#Keys|Release Engineering]] page: 53 | {{Cmd 54 | |gpg --fingerprint 2D182910 55 | |prompt=user@pc2 $ 56 | |output=
 57 | pub   rsa4096 2009-08-25 [SC] [expires: 2020-07-01]
 58 |       13EB BDBE DE7A 1277 5DFD  B1BA BB57 2E0E 2D18 2910
 59 | uid           [ unknown] Gentoo Linux Release Engineering (Automated Weekly Release Key) 
 60 | sub   rsa2048 2019-02-23 [S] [expires: 2020-07-01]
 61 |
62 | }} 63 | {{Note|Although correct at the time of writing, the key ID you need to enter in the above command may differ from 2D182910, as may the fingerprint data shown. Always use the [[Project:RelEng#Keys|Release Engineering]] page data as your primary reference.}} 64 | 65 | If all looks good, use the {{c|gpg}} program to verify the digest file (step 2): 66 | 67 | {{Cmd 68 | |gpg --verify install-amd64-minimal-YYYYMMDDThhmmssZ.iso.DIGESTS.asc 69 | |prompt=user@pc2 $}} 70 | {{Note|Substitute the correct release timestamp for YYYYMMDDThhmmssZ in the above command.}} 71 | {{Note|You can ignore {{c|gpg}} output such as:{{GenericCmd|
 72 | gpg: WARNING: This key is not certified with a trusted signature!
 73 | gpg:          There is no indication that the signature belongs to the owner.
 74 |
}} 75 | This is normal since you have just imported the public key, and not yet 'trusted' it.Information Security Stack Exchange: [http://security.stackexchange.com/questions/6841/ways-to-sign-gpg-public-key-so-it-is-trusted "Ways to sign gpg public key so it is trusted?"] 76 | }} 77 | Assuming that worked (the output reports 'Good signature'), next check the digests themselves (step 3); we'll use the SHA512 variants here: 78 | {{Cmd 79 | |awk '/SHA512 HASH/{getline;print}' install-amd64-minimal-YYYYMMDDThhmmssZ.iso.DIGESTS.asc {{!}} sha512sum --check 80 | |prompt=user@pc2 $}} 81 | {{Note|Substitute the correct release timestamp for YYYYMMDDThhmmssZ in the above command.}} 82 | 83 | If this outputs: 84 | {{GenericCmd|
 85 | install-amd64-minimal-YYYYMMDDThhmmssZ.iso: OK
 86 | install-amd64-minimal-YYYYMMDDThhmmssZ.iso.CONTENTS: OK
 87 |
}} 88 | then continue, all is well. 89 | 90 | == Copying the ISO Image to USB == 91 | 92 | Next, we need to copy the ISO onto a USB key (the image is already hybridSuperUser Forum: [http://superuser.com/questions/683210/how-do-i-determine-if-an-iso-is-a-hybrid#683232 "How do I determine if an ISO is a hybrid?"]). 93 | 94 | Just before inserting the USB key (the [[../Installation_Prerequisites#two_usb_keys|larger one]]) into the helper pc, issue: 95 | {{Cmd 96 | |lsblk 97 | |prompt=user@pc2 $}} 98 | Note the output, then insert the USB key, and issue: 99 | {{Cmd 100 | |lsblk 101 | |prompt=user@pc2 $}} 102 | again. The change in output will show you the key's device path (note that the initial {{Path|/dev/}} prefix is not shown in the {{c|lsblk}} output). We will refer to this path in these instructions as '''{{Path|/dev/sdX}}''', but in reality on your system it will be something like {{Path|/dev/sdb}}, {{Path|/dev/sdc}} etc. 103 | 104 | {{Important|If the device has automounted, and {{c|lsblk}} shows that the device has a non-blank mountpoint for one or more of its partitions, you must unmount these, using {{c|umount}}, before proceeding. 105 | 106 | For example, suppose the USB key showed up as {{Path|/dev/sdb}} on your system, and its first partition {{Path|/dev/sdb1}} automounted (at {{Path|/var/run/media/user/myusbkey}} or some similar path). Then you would issue: 107 | {{Cmd 108 | |umount --verbose /dev/sdb1 109 | |prompt=user@pc2 $ 110 | }} 111 | to unmount it. 112 | 113 | If you have problems, you may need to run the {{c|umount}} as the root user.}} 114 | 115 | Next, we will write the ISO image to the USB key. This will require root access, so issue: 116 | 117 | {{Cmd 118 | |su --login root 119 | |prompt=user@pc2 $ 120 | |output=
121 | Password: 
122 |
123 | }} 124 | 125 | Now you can write the ISO image to the USB key (note, we use a larger than default block size here, for efficiency). Issue: 126 | 127 | {{RootCmd 128 | |dd if{{=}}/tmp/install-amd64-minimal-YYYYMMDDThhmmssZ.iso of{{=}}/dev/sdX bs{{=}}8192k status{{=}}progress && sync 129 | |prompt=root@pc2 # 130 | }} 131 | Wait for the process to complete before continuing. 132 | 133 | {{Warning|This will wipe everything on the USB key. Double check that there is nothing on there you want before proceeding. Make '''sure''' you have the correct device path! Note also that we need to target the device itself, and not a partition within it, so for {{Path|/dev/sdX}} in the above command, use e.g. {{Path|/dev/sdb}} and ''not'' {{Path|/dev/sdb1}}; {{Path|/dev/sdc}} and ''not'' {{Path|/dev/sdc1}}, etc.}} 134 | {{Note|Substitute the correct release timestamp for YYYYMMDDThhmmssZ in the above command.}} 135 | {{Note|You can safely omit the status{{=}}progress option, if it not supported in your version of {{c|dd}}.}} 136 | 137 | == Booting the ISO Image == 138 | 139 | Modern Gentoo minimal install images ''can'' be booted under EFI (as well as 'legacy' / [[:Wikipedia:Unified_Extensible_Firmware_Interface#CSM_booting|CSM]] mode), but do ''not'' support secure boot. As such, we'll need to bring up your target PC — using the USB key you just set up — under UEFI but with secure boot temporarily disabled (of course, the kernel we'll ultimately create ''will'' secure boot under EFI). 140 | 141 | So, to proceed, take the USB key from the helper PC (where we just {{c|dd}}'d it) and insert it into the target PC. The latter is still running Windows, and you need to reboot it into the BIOS setup GUI. There are two ways to do this; choose the one that suits you: 142 | ; ''Either:'' Use Windows boot options menu. 143 | : This is the easier method (particularly if your target machine is using the 'fast boot' option with Windows).Hoffman, Chris. [http://www.makeuseof.com/tag/how-to-access-the-bios-on-a-windows-8-computer/ "How To Access The BIOS On A Windows 8 Computer"] In Windows, hit {{Key|Ctrl}}{{Key|Alt}}{{Key|Delete}}, then click on the power icon at the bottom right of the screen, and then ''while holding down'' {{Key|Shift}}, click 'Restart' from the pop-up menu. This will pass you into the Windows boot options menu. Once this comes up (and asks you to 'Choose an option'), click on the 'Troubleshoot' tile, which brings up the 'Advanced options' panel (in Windows 10, you have to click on the 'Advanced options' tile to show this): from this, click on 'UEFI Firmware Settings', and confirm if prompted. Your machine will then restart into the BIOS GUI directly (no hotkeys required) and you can proceed. 144 | ; ''Or:'' Use the BIOS hotkey. 145 | : This is a less reliable method, since you are racing the OS loading process. To use it, hit {{Key|Ctrl}}{{Key|Alt}}{{Key|Delete}} from within Windows, then click on the power icon at the bottom right of the screen, and choose 'Restart' from the pop-up menu to perform a regular restart. Then, ''immediately'' the target PC starts to come back up, press the appropriate hotkey to enter the BIOS setup GUI. Unfortunately, the required hotkey varies greatly from machine to machine (as does the BIOS user interface itself). On the Panasonic CF-AX3, press {{Key|F2}} during startup (you may need to press it repeatedly). 146 | 147 | Once you have the BIOS configuration GUI up, you need to perform the following steps: 148 | # disable legacy / CSM boot mode (if available and currently the active default); 149 | # enable EFI boot mode (if not already the active default); 150 | # ensure any 'fast boot' / 'ultra fast boot' options (if present) are disabled (as these may cause USB to be disabled until the operating system comes up); 151 | # turn off secure boot (for the reason noted [[#image_restrictions|above]]); 152 | # select the Gentoo minimal install USB key as the highest priority UEFI boot device; and 153 | # restart your machine (saving changes). 154 | 155 | It's impossible to be precise about the GUI actions required to achieve the above, as they will vary from BIOS to BIOS. However, to give you an idea, here's how you would go about it on the Panasonic CF-AX3 (which has an AMT BIOS). 156 | 157 | Use the arrow keys to move to the 'Boot' tab. Then, navigate down to the 'UEFI Boot' item, and press {{Key|Enter}}. In the popup that appears, select 'Enabled' using the arrow keys, and press {{Key|Enter}}. This switches the system out of legacy / CSM boot and into standard UEFI mode (steps 1 and 2 in the list above): 158 | {|style="background:transparent; color:black" 159 | |[[File:Bios_enable_uefi.jpg|thumb|none|400px|Ensuring UEFI Boot Mode Selected]] 160 | |} 161 | 162 | {{Note|If your target system was already ''in'' UEFI mode (quite likely for a modern system running Windows), then you will have nothing to do here. Similarly, some PCs (for example, ultra-compacts) do not support legacy boot at all (in which case you can, of course, safely skip the above step).}} 163 | 164 | Next, if you have a 'Fast Boot' / 'Ultra Fast Boot' option in your BIOS, you should turn it off at this point (step 3 in the list); as this ''may'' cause USB devices to be disabled at boot time. The Panasonic has the choice of 'Normal' (as here) or 'Compatible' boot modes; 'Normal' does allow boot from USB and works with the USB keys I used, but if you have problems (and the same BIOS), you could try switching this to 'Compatible' instead). 165 | 166 | Then (step 4), we'll turn off [[:Wikipedia:Unified_Extensible_Firmware_Interface#Secure_boot|secure boot]], since the Gentoo minimal install image isn't signed with a Microsoft-sanctioned key (don't worry, we'll set up our own secure-boot keystore later in the tutorial). On the CF-AX3, use the arrow keys to select the 'Security' tab, then navigate down to the 'Secure Boot' item, and select it by pressing {{Key|Enter}}. This enters a 'Security' sub-page; navigate to the 'Secure Boot control' item, and press {{Key|Enter}}. In the popup that appears, select 'Disabled' using the arrow keys, and press {{Key|Enter}}: 167 | {|style="background:transparent; color:black" 168 | |[[File:Bios_disable_secure_boot.jpg|thumb|none|400px|(Temporarily) Disabling Secure Boot]] 169 | |} 170 | 171 | Next, on the CF-AX3, ''if'' your machine was ''originally'' in CSM / legacy boot mode during step 1 above, it is necessary to restart the machine at this point (as it will not pick up valid UEFI boot devices immediately upon switching into UEFI boot mode). Again, the method to achieve this varies from machine to machine; on the Panasonic's BIOS, hit {{Key|F10}} to restart, and confirm if prompted. 172 | {{Note|If your machine was ''already'' in UEFI boot mode during step 1 (likely for modern Windows machines) you may safely skip the above restart.}} 173 | {{Tip|Many BIOSes behave in this manner, and must be restarted when changing from CSM/legacy to UEFI boot (and ''vice versa''), before all BIOS boot options relevant to that new mode can be specified.}} 174 | When the machine restarts, hit {{Key|F2}} again, to re-enter BIOS setup. 175 | 176 | Now we can select a boot device (step 5) — if you don't do this, you'll simply be dumped back into Windows when you restart. Using the arrow keys, navigate to the 'Boot' tab, and then down to the 'UEFI Priorities' item. Press {{Key|Enter}}, and a sub-page is displayed. Ensure the item 'UEFI Boot from USB' is enabled (if it isn't, enable it now, and then press {{Key|F10}} to restart (confirming if prompted), and come back to this point). Navigate down to 'Boot Option #1' and press {{Key|Enter}}. In the pop-up menu that appears, select your (Gentoo minimal install) USB key, and press {{Key|Enter}} to select it: 177 | {|style="background:transparent; color:black" 178 | |[[File:Bios_set_efi_boot_order.jpg|thumb|none|400px|Making Our Minimal Install USB Key the First Boot Option]] 179 | |} 180 | {{Note|The item that ''you'' need to select from this menu will of course depend the make and model of your minimal install USB key.}} 181 | {{Note|With ''some'' BIOSes you will also have to specify which ''file'' on the chosen USB device to boot - if so, you should enter (or select) {{Path|/EFI/Boot/bootx64.efi}} (most BIOSes however will ''not'' require this, as this path is the EFI default).}} 182 | 183 | That's it! Now press {{Key|F10}} to restart (step 6; the required method varies from BIOS to BIOS), and confirm if prompted. 184 | 185 | Hopefully, after a short delay you'll be presented with a [[:Wikipedia:GNU_GRUB|GRUB]] boot screen. Unless you want to enter custom options — which most users will not — simply press {{Key|Enter}} to proceed. After a few seconds (and before you are provided with a command prompt), you'll be asked to choose a keymap. It's important, particularly on a machine with non-standard keyboard layout such as the CF-AX3, to get this right, otherwise you may have problems with passwords and so forth. Again, the correct map to choose will obviously depend on your machine but, on the Panasonic CF-AX3, press {{Key|2}}{{Key|2}}{{Key|Enter}} to select the Japanese keymap. 186 | 187 | A few seconds later, you should have a Gentoo Linux root command prompt! Now, we'll set-up a root password (this is only for use during the install, it will not persist across into the final system). 188 | 189 | {{RootCmd 190 | |passwd root 191 | |prompt=livecd ~ # 192 | |output=
193 | New password: 
194 | Retype new password: 
195 | passwd: password updated successfully
196 |
197 | }} 198 | 199 | Make a note of the password, as you will require it shortly. 200 | 201 | == Setting the Date and Time == 202 | 203 | It's important to ensure that you have the correct time and date on your target machine. Check it with: 204 | {{RootCmd 205 | |date 206 | |prompt=livecd ~ # 207 | }} 208 | 209 | Per the handbook, you should stick with [[:Wikipedia:UTC|UTC]] for now (the real timezone specification will come later in the install). If necessary, set the date and time, in {{Highlight|MMDDhhmmYYYY}} format ('''M'''onth, '''D'''ay, '''h'''our, '''m'''inute, '''y'''ear): 210 | {{RootCmd 211 | |date MMDDhhmmYYYY 212 | |prompt=livecd ~ # 213 | }} 214 | {{Note|Substitute MMDDhhmmYYYY in the above with the correct date/time string. For example, to set the UTC date/time to 5:12pm on February 9th 2017, you would issue 215 | {{RootCmd 216 | |date 020917122017 217 | |prompt=livecd ~ # 218 | }} 219 | }} 220 | 221 | == Next Steps == 222 | 223 | Next, we'll setup the network and get an SSH daemon running. [[../Setting_Up_Networking_and_Connecting_via_ssh|Click here]] to go to the next chapter, "Setting Up Networking and Connecting via {{c|ssh}}". 224 | 225 | == Notes == 226 | {{reflist}} 227 | 228 | {| class="wikitable" style="margin: 1em auto 1em auto;" 229 | |- 230 | | [[../Preparing_Windows_for_Dual-Booting|< Previous]] 231 | | [[../|Home]] 232 | | [[../Setting_Up_Networking_and_Connecting_via_ssh|Next >]] 233 | |} 234 | 235 | [[Category:Sakaki's EFI Install Guide]] 236 | 237 | -------------------------------------------------------------------------------- /04_Setting_Up_Networking_and_Connecting_via_ssh: -------------------------------------------------------------------------------- 1 | 2 | 3 | Having successfully booted our target PC with the Gentoo minimal install image, our next task is to establish network connectivity for it. 4 | 5 | Once that is done, we'll connect in remotely to the target, from the helper PC, via {{c|ssh}}. This will make subsequent installation steps (such as the copy/paste of lengthy commands) much easier. 6 | 7 | This section shadows [[Handbook:AMD64/Installation/Networking|Chapter 3]] of the Gentoo handbook. 8 | 9 | == Getting Networking Running == 10 | 11 | Decide whether you wish to perform the install using a wired Ethernet connection, or over WiFi (using [[:Wikipedia:Wi-Fi_Protected_Access|WPA/WPA2]]), and follow the appropriate instructions below. In both cases, the presence of a [[:Wikipedia:Dynamic_Host_Configuration_Protocol|DHCP]] server on the subnet will be assumed. 12 | 13 | {{Note|If you need to use a fixed IP address, a proxy, IPv6, or an unencrypted WiFi connection, please see [[Handbook:AMD64/Installation/Networking|Chapter 3]] of the Gentoo handbook for more details. 14 | }} 15 | 16 | === Connecting via Wired Ethernet === 17 | 18 | This is the easier option, if your machine physically supports it. To proceed, plug an ethernet cable into the target machine now, and hook it up to your network (into the back of your cable or ADSL router etc.). Wait for a minute or so (for DHCP to allocate you an address), then (at the keyboard of your target PC) enter: 19 | 20 | {{RootCmd 21 | |ifconfig 22 | |prompt=livecd ~ # 23 | |output= 24 | 
 25 | enp0s25: flags=4163  mtu 1500
 26 |         inet 192.168.1.106  netmask 255.255.255.0  broadcast 192.168.1.255
 27 |         ... etc ...
 28 |
29 | }} 30 | 31 | Hopefully, it will have autoconfigured an interface, as above. In the old days, you'd be looking for {{Highlight|eth0}} in the output of this command, but things have now changed freedesktop.org: [http://www.freedesktop.org/wiki/Software/systemd/PredictableNetworkInterfaceNames Predictable Network Interface Names] (to ensure device naming stability across reboots), so your wired ethernet interface name will probably be something a bit stranger-sounding, such as {{Highlight|enp0s25}} (as is the case here). You are looking for the 'inet' (assuming IPv4) entry; in this case {{Highlight|192.168.1.106}} (yours will almost certainly differ). 32 | 33 | If that was successful, then try: 34 | 35 | {{RootCmd 36 | |ping -c 3 www.gentoo.org 37 | |prompt=livecd ~ # 38 | }} 39 | 40 | If this works, it demonstrates that you have a functioning network connection, with working DNS name resolution. 41 | 42 | When ready, [[#setup_ssh_server|click here]] to jump to the next section of the tutorial. 43 | 44 | === Connecting via WiFi (WPA/WPA2) === 45 | 46 | If your PC has no Ethernet port, you'll have to perform the installation over WiFi. First, check that your PC's adaptor has driver support in the minimal-install image. Issue: 47 | {{RootCmd 48 | |iwconfig 49 | |prompt=livecd ~ # 50 | |output= 51 | 
 52 | wlp2s0    IEEE 802.11abgn ESSID:off/any
 53 |           Mode:Managed  Access Point: Not-Associated Tx-Power=0 dBm
 54 |           Retry  long limit:7   RTS thr:off   Fragment thr:off
 55 |           Encryption key:off
 56 |           Power Management: on
 57 |           
 58 | lo        no wireless extensions.
 59 |
60 | }} 61 | Your results will differ from the above, but you're looking for a record starting with '''{{c|wl}}''', as this is a wireless adaptor. In this example, the predictable network interface name of the WiFi adaptor is {{c|wlp2s0}}; take a note of the particular name reported in your case. 62 | {{Note|If you see no records beginning with {{c|wl}}, then you will not be able to install the system wirelessly. Use a wired adaptor if your machine has one, or purchase a supported USB to Ethernet (or WiFi) adaptor, and use that.
Most machines do have driver support in the minimal install image, however.}} 63 | 64 | Next, we'll need to create a configuration file, to allow the {{c|wpa_supplicant}} program to handle the encrypted network connection. You'll need to know your WiFi access point's [[:Wikipedia:Service_set_(802.11_network)|{{c|ESSID}}]] (the name you'd see when connecting to it via your phone etc.) and its WPA (or WPA2) passphrase. Issue:Linux.icydog.net Blog: [http://linux.icydog.net/wpa.php "Command line WPA"] 65 | {{RootCmd 66 | |wpa_passphrase "ESSID" > /etc/wpa.conf 67 | |prompt=livecd ~ # 68 | |output= 69 | 
 70 | 
 71 |
72 | }} 73 | {{Note|Substitute the correct name for "ESSID" in the above ("MyWiFi", or whatever it happens to be in your case).}} 74 | 75 | Lock down the file's access permissions (to root only) and check that its contents look sane. Issue: 76 | {{RootCmd 77 | |chmod -v 600 /etc/wpa.conf 78 | |cat /etc/wpa.conf 79 | |prompt=livecd ~ # 80 | }} 81 | 82 | Assuming that looks OK, we can connect. Issue: 83 | {{RootCmd 84 | |wpa_supplicant -Dnl80211,wext -iwlp2s0 -c/etc/wpa.conf -B 85 | |prompt=livecd ~ # 86 | |output= 87 | 
 88 | Successfully initialized wpa_supplicant
 89 |
90 | }} 91 | {{Note|Substitute the wireless network interface name you wrote down [[#note_wifi_if_name{{!}}a minute ago]] for wlp2s0 in the above command.}} 92 | In this command: 93 | {| class="wikitable" 94 | |- 95 | ! Option !! Description 96 | |- 97 | | {{c|-D}} || Specifies the wireless driver name to use. {{c|wext}} is the 'catch all' and will work in most cases; {{c|nl80211}} is the more modern version that will ultimately replace it. It's fine to specify multiple drivers here, so we do. 98 | |- 99 | | {{c|-i}} || Specifies the interface name (from {{c|iwconfig}} [[#note_wifi_if_name{{!}}above]]). 100 | |- 101 | | {{c|-c}} || Specifies the configuration file path (as created by {{c|wpa_passphrase}} [[#create_wpa_config{{!}}above]]). 102 | |- 103 | | {{c|-B}} || Instructs {{c|wpa_supplicant}} to run in the background. 104 | |} 105 | 106 | Now wait a moment or two, then issue: 107 | 108 | {{RootCmd 109 | |ifconfig wlp2s0 110 | |prompt=livecd ~ # 111 | |output= 112 | 
113 | wlp2s0: flags=4163  mtu 1500
114 |         inet 192.168.1.106  netmask 255.255.255.0  broadcast 192.168.1.255
115 |         ... etc ...
116 |
117 | }} 118 | {{Note|Substitute the wireless network interface name you wrote down [[#note_wifi_if_name{{!}}a minute ago]] for wlp2s0 in the above command.}} 119 | 120 | Hopefully, it will have connected successfully. You are looking for the 'inet' (assuming IPv4) entry; in this case {{Highlight|192.168.1.106}} (yours will almost certainly differ). 121 | 122 | If that was successful, then try: 123 | 124 | {{RootCmd 125 | |ping -c 3 www.gentoo.org 126 | |prompt=livecd ~ # 127 | }} 128 | 129 | If this works, it demonstrates that you have a functioning network connection, with working DNS name resolution. 130 | 131 | == Connecting via {{c|ssh}} and Using {{c|screen}} == 132 | 133 | Our next step is to setup {{c|ssh}} so we can remotely connect and run the install from our helper PC. Still on the target machine console, enter: 134 | {{RootCmd 135 | |sed -i 's/^#PermitRootLogin.*$/PermitRootLogin yes/' /etc/ssh/sshd_config 136 | |/etc/init.d/sshd start 137 | |prompt=livecd ~ # 138 | }} 139 | 140 | {{Note|From release 7.0 of {{c|OpenSSH}}, the defaults have changed to prohibit password-based login as {{c|root}}, hence the reason we edit the {{Path|/etc/ssh/sshd_config}} file above.OpenSSH Unix Announce: [http://lists.mindrot.org/pipermail/openssh-unix-announce/2015-August/000122.html OpenSSH 7.0 released] (More recent versions of the minimal install image have fixed this issue, but it does not hurt to apply the edit even when using them.)}} 141 | 142 | Now take note of the RSA and ED25519 fingerprints for the host (which one is used when you try to connect, will depend upon the settings and recency of the system in your helper PC): 143 | {{RootCmd 144 | |for K in /etc/ssh/ssh_host_*key.pub; do ssh-keygen -l -f "${K}"; done 145 | |prompt=livecd ~ # 146 | }} 147 | {{Note|At the time of writing, {{c|sshd}} from the minimal install image does not set up {{c|ECDSA}} keys.}} 148 | {{Note|By default, the above command will now display [[:Wikipedia:SHA256{{!}}SHA-256]] fingerprints in [[:Wikipedia:Base64{{!}}Base64]] format (as used by more modern versions of the {{c|ssh}} client program); however, if your {{c|ssh}} client still uses [[:Wikipedia:MD5{{!}}MD5]] fingerprints, you can display these using the following command instead: 149 | {{RootCmd 150 | |for K in /etc/ssh/ssh_host_*key.pub; do ssh-keygen -l -E "md5" -f "${K}"; done 151 | |prompt=livecd ~ # 152 | }} 153 | }} 154 | 155 | Next, move back onto the second, helper PC (on the same subnet), and enter: 156 | {{Cmd 157 | |sed -i '/^[^[:digit:]]*192.168.1.106[^[:digit:]]/d' ~/.ssh/known_hosts 158 | |ssh root@192.168.1.106 159 | |prompt=user@pc2 $}} 160 | (The {{c|sed}} command simply removes any record of fingerprints for previous connections to other {{c|sshd}} servers at that IP address, since {{c|ssh}} will refuse to connect if it finds a conflicting one.) 161 | {{Note|Of course, substitute whatever IP address you got back from {{c|ifconfig}} for 192.168.1.106 in the above commands.}} 162 | {{Tip|If you have a large number of existing keys in your {{Path|~/.ssh}} directory, you may get a Too many authentication failures error when attempting to connect. In this case (which will not affect most users), simply add the -o PubkeyAuthentication{{=}}no option to your {{c|ssh}} command.Server Fault: [https://serverfault.com/questions/36291/how-to-recover-from-too-many-authentication-failures-for-user-root/540613#540613 "How to recover from 'Too many Authentication Failures for user root'"]}} 163 | Check the reported key fingerprint and then, if it matches one you noted earlier, continue as below: 164 | {{GenericCmd|
165 | ... additional output suppressed ...
166 | Are you sure you want to continue connecting (yes/no)? 
167 | ... additional output suppressed ...
168 | Password: 
169 | ... additional output suppressed ...
170 |
171 | }} 172 | 173 | You should find that you can continue configuring remotely, which is much more convenient (as you will have a full windowing environment with graphical web browser, copy and paste, and so on). 174 | 175 | {{Note|Assuming you are using DHCP, if you have to reboot your machine during the following process, bear in mind that it may not come back up with the same address (although with many DHCP setups, it will). 176 | }} 177 | 178 | Now, still via this remote login {{c|ssh}} connection (i.e., at the helper PC's keyboard), issue: 179 | 180 | {{RootCmd 181 | |screen 182 | |prompt=livecd ~ # 183 | }} 184 | to start a new [[:Wikipedia:GNU_Screen|screen]] session - this is useful as it allows you to multiplex several virtual consoles, disconnect while lengthy compiles are running and then reconnect later, and so on. 185 | 186 | {{Note|With some (helper-PC-side) terminals, you may get an error issued when trying to run {{c|screen}}, of the form Cannot find terminfo entry for 'xxx'.Stack Overflow: [http://stackoverflow.com/questions/10823994/unix-screen-utility-error-cannot-find-termcap-entry-for-xterm-256color "Unix screen utility error: Cannot find termcap entry for 'xterm-256color'"]
If this happens, simply try again with:{{RootCmd|TERM{{=}}xterm-color screen|prompt=livecd ~ #}}}} 187 | {{Note|See [https://library.linode.com/linux-tools/utilities/screen this brief discussion] of how to use screen. And here is an even briefer overview of some commands you may find useful to get you started: {{Key|Ctrl}}{{Key|a}} is the ''escape character'' for screen, which you type and then follow up with the rest of the command if necessary; so for example {{Key|Ctrl}}{{Key|a}} ''then'' {{Key|?}} to get help, {{Key|Ctrl}}{{Key|a}} ''then'' {{Key|d}} to detach the current session (disconnect from it from your ssh console, leaving any active commands to run in the background), {{Key|Ctrl}}{{Key|a}} ''then'' {{Key|c}} to create a new 'window', {{Key|Ctrl}}{{Key|a}} ''then'' {{Key|"}} (that's a double quote) to list the current windows, {{Key|Ctrl}}{{Key|a}} ''then'' {{Key|n}} to go to the next window and {{Key|Ctrl}}{{Key|a}} ''then'' {{Key|p}} to go to the previous window. If you disconnect, you can reconnect to your session from a console (either when logged in via {{c|ssh}}, or directly on the machine's console itself) using {{RootCmd|screen -D -R}}You can also use this command to reconnect to a {{c|screen}} session if e.g. your {{c|ssh}} connection gets dropped for some reason.}} 188 | 189 | == Next Steps == 190 | 191 | Next, we'll prepare the storage on the target machine. [[../Preparing_the_LUKS-LVM_Filesystem_and_Boot_USB_Key|Click here]] to go to the next chapter, "Preparing the LUKS-LVM Filesystem and Boot USB Key". 192 | 193 | == Notes == 194 | {{reflist}} 195 | 196 | {| class="wikitable" style="margin: 1em auto 1em auto;" 197 | |- 198 | | [[../Creating_and_Booting_the_Minimal-Install_Image_on_USB|< Previous]] 199 | | [[../|Home]] 200 | | [[../Preparing_the_LUKS-LVM_Filesystem_and_Boot_USB_Key|Next >]] 201 | |} 202 | 203 | [[Category:Sakaki's EFI Install Guide]] 204 | 205 | -------------------------------------------------------------------------------- /05_Preparing_the_LUKS-LVM_Filesystem_and_Boot_USB_Key: -------------------------------------------------------------------------------- 1 | 2 | 3 | In this section, we'll be shadowing [[Handbook:AMD64/Installation/Disks|Chapter 4]] of the Gentoo handbook (and, although we're going to start to diverge considerably, you may want to read that chapter before proceeding, as it has some useful background information). 4 | 5 | The process we'll be following here is: 6 | # First, we'll format the smaller USB key ([[../Installation_Prerequisites#two_usb_keys|discussed earlier]]) so that it can support booting under UEFI (although there'll be no bootable kernel on it, yet). We'll then mount it. 7 | # Next, we'll create a pseudo-random binary blob of key data that will be used to secure the main computer drive, encrypt this with a passphrase using GPG, and store the result on the USB key. 8 | # Then, we will create a new [[:Wikipedia:GUID_Partition_Table|GPT]] (GUID partition table) partition on the target machine's main drive, using the space we [[../Preparing_Windows_for_Dual-Booting#shrink_windows_partition|freed up from Windows]] earlier in the tutorial. 9 | # We'll then (optionally) overwrite that partition with pseudo-random data. 10 | # Next, we'll format the partition using LUKS (secured with the key data created in step 2). 11 | # We'll then (optionally) add a fallback passphrase to the LUKS container. 12 | # Then, we'll create an LVM physical volume (PV) on the LUKS partition, create an LVM volume group (VG) with just that one physical volume in it, and then create three logical volumes (LVs) (for the Gentoo root, swap and home partitions) utilizing that physical volume. 13 | # Finally, we'll format the logical volumes appropriately, and mount them so that they can be used in the rest of the installation. 14 | 15 | Let's go! 16 | 17 | == Formatting and Mounting the UEFI-Bootable USB Key == 18 | 19 | We are going to use our smaller (>= 250 MB) USB key as the boot device for Gentoo Linux. Since we want it to work under UEFI, we must format it using [[:Wikipedia:GUID_Partition_Table|GPT]] with a single {{c|fat32}} EFI system partition. 20 | 21 | {{Warning|This process will wipe everything on the USB key, so be sure to back it up if necessary.}} 22 | 23 | Issue (using of course the {{c|ssh}} / {{c|screen}} terminal we have just established): 24 | {{RootCmd 25 | |lsblk 26 | |prompt=livecd ~ # 27 | }} 28 | And note the output. Then, insert the smaller capacity USB key into one of the remaining free USB slots on the target machine, and determine its device path. We will refer to its path in these instructions as {{Path|/dev/sdY}}, but in reality on your system it will be something like {{Path|/dev/sdc}}, {{Path|/dev/sdd}} etc. You can find what it is, by issuing {{c|lsblk}} again, and noting what has changed: 29 | {{RootCmd 30 | |lsblk 31 | |prompt=livecd ~ # 32 | }} 33 | (note that the initial {{Path|/dev/}} prefix is not shown in the {{c|lsblk}} output) 34 | 35 | The minimal-install image shouldn't auto-mount the USB key, even if it has any existing partitions, but double-check to make sure (no mountpoints for the device should be shown in the output of the above command). 36 | 37 | Now, using {{Highlight|parted}}, we will create a single primary partition, sized so as to fill the USB key completely (you can of course use a more modest extent if your drive is much larger than the minimum required size), and set its [http://forums.fedoraforum.org/archive/index.php/t-271111.html somewhat confusingly named] 'boot' flag (i.e., mark the partition as a GPT system partition). Issue: 38 | 39 | {{RootCmd 40 | |parted -a optimal /dev/sdY 41 | |prompt=livecd ~ # 42 | |output=
 43 | GNU Parted 3.2
 44 | ... additional output suppressed ...
 45 | (parted) mklabel gpt
 46 | Warning: The existing disk label on /dev/sdY will be destroyed and all data on
 47 | this disk will be lost. Do you want to continue?
 48 | Yes/No? yes
 49 | (parted) mkpart primary fat32 0% 100%
 50 | (parted) set 1 BOOT on
 51 | (parted) quit
 52 |
53 | }} 54 | {{Note|Replace {{Path|/dev/sdY}} in the above command with the path of the USB key you found above, such as {{Path|/dev/sdc}} or {{Path|/dev/sdd}} etc.}} 55 | 56 | Next, we need to format the partition fat32: 57 | 58 | {{RootCmd 59 | |mkfs.vfat -F32 /dev/sdY1 60 | |prompt=livecd ~ # 61 | }} 62 | {{Note|Replace {{Path|/dev/sdY1}} in the above command with the path of first partition on the USB key, such as {{Path|/dev/sdc1}} or {{Path|/dev/sdd1}} etc.}} 63 | {{Tip|On some machines, a ''new'' drive letter will be assigned to the USB key after it has been edited by {{c|parted}} in this fashion. For example, if the drive was {{Path|/dev/sdc}} prior to editing, it may become {{Path|/dev/sdd}} afterwards. For avoidance of doubt, this issue will '''not''' affect most users; but, it is simple to check, by using {{c|lsblk}}.}} 64 | 65 | Now we create a temporary mountpoint and mount the partition: 66 | {{RootCmd 67 | |mkdir -v /tmp/efiboot 68 | |mount -v -t vfat /dev/sdY1 /tmp/efiboot 69 | |prompt=livecd ~ # 70 | }} 71 | {{Note|As before, remember to subsitute for {{Path|/dev/sdY1}} in the above.}} 72 | 73 | == Creating a Password-Protected Keyfile for LUKS == 74 | 75 | We will next create a (pseudo) random keyfile (for use with LUKS). This keyfile will be encrypted with [[:Wikipedia:Gnu_Privacy_Guard|GPG]] (using a typed-in passphrase) and then stored on the USB key. 76 | 77 | The point of this is to establish dual-factor security - both the (encrypted) keyfile, ''and'' your passphrase (to decrypt it) will be required to access the LUKS data stored on the target machine's hard drive. This means that even if a keylogger is present, should the machine be stolen - powered down but without the USB key - the LUKS data will still be safe (as the thief will not have your encrypted keyfile). Similarly, (assuming no keylogger!) if your machine were to be stolen powered down but with the USB key still in it, it will also not be possible to access your LUKS data (as in this case the thief will not know your passphrase). 78 | 79 | Note that we are going to create a (one byte short of) 8192[[:Wikipedia:Kibibyte|KiB]] underlying (i.e., binary plaintext) keyfile, even though, for the symmetric LUKS cipher we'll be using ([[:Wikipedia:Serpent_(cipher)|Serpent]]), the maximum supported key size is 256 bits (32 bytes) (or two 256 bit keys = 512 bits = 64 bytes in XTS mode, as explained later). This works because LUKS / {{c|cryptsetup}} uses the [[:Wikipedia:PBKDF2|PBKDF2]] key derivation function to map the keyfile into the actual (user) key material internally (which in turn is used to unlock the master key actually used for sector encryption / decryption), so we are free, within limits, to choose whatever size keyfile we want. As such, we elect to use the largest legal size, so as to make it (very slightly) harder for any data capture malware (in low-level drivers, for example) to intercept the file and squirrel it away, or transmit it over the network surreptitiously. In theory, the {{c|cryptsetup}} system can support keyfiles up to and including 8192KiB (execute cryptsetup --help to verify this); in practice, due to a off-by-one bug, it supports only keyfiles strictly less than 8[[:Wikipedia:Mebibyte|MiB]]. We therefore create a keyfile of length (1024 * 8192) - 1 = 8388607 bytes. 80 | 81 | Note that we'll use the [[:Wikipedia:/dev/random|/dev/urandom]] source to create the underlying (binary plaintext) pseudo-random keyfile, and then pipe it to gpg to encrypt (using a passphrase of your choosing). The resulting binary ciphertext is saved to the USB key. This avoids ever having the binary plaintext keyfile stored on disk anywhere (and indeed not even you need ever see the unencrypted contents). Enter: 82 | {{RootCmd 83 | |export GPG_TTY{{=}}$(tty) 84 | |dd if{{=}}/dev/urandom bs{{=}}8388607 count{{=}}1 {{!}} gpg --symmetric --cipher-algo AES256 --output /tmp/efiboot/luks-key.gpg 85 | |prompt=livecd ~ # 86 | |output=
 87 | Enter passphrase
 88 | Passphrase 
 89 | Please re-enter this passhprase
 90 | Passphrase 
 91 | ... further output suppressed ...
 92 |
93 | }} 94 | {{Note|We need to set the GPG_TTY variable here, otherwise gpg's pinentry password system may misbehave. If you are connecting over {{c|ssh}}, and your helper system has locale settings not available within the minimal install environment, you may get complaints about no LC_CTYPE known printed by {{c|pinentry}}; these can generally be ignored, and result from {{c|sshd}} on the target machine attempting to use the helper machine's environment.ServerFault Q&A Site: [http://serverfault.com/questions/304469/setting-locale-failed-force-certain-locale-when-connecting-through-ssh "Setting locale failed: force certain locale when connecting through ssh"]}} 95 | {{Note|We are using the symmetric [[:Wikipedia:Advanced_Encryption_Standard|AES]] cipher here with a 256 bit key (derived from your passphrase) to protect the ''keyfile''. We'll use a different cipher ([[:Wikipedia:Serpent_(cipher)|Serpent]]) in LUKS to protect the hard drive partition. Note also that the {{Path|/tmp/efiboot/luks_key.gpg}} file will be larger than 8388607 bytes, due to the GPG 'wrapper'.}} 96 | {{Warning|If you lose the (encrypted) keyfile, or forget the passphrase, it's game over for your LUKS data. Therefore, be sure to backup both keyfile and passphrase (to separate, secure locations).}} 97 | 98 | What passphrase you choose to protect your LUKS keyfile is, of course, entirely up to you, but do consider the approach of using a longer list of everyday words, rather than the more traditional cryptic {{Highlight|str1ng5 @f}} characters. Advantages include:Information Security Stack Exchange: [http://security.stackexchange.com/questions/6095/xkcd-936-short-complex-password-or-long-dictionary-passphrase "XKCD #936: Short complex password, or long dictionary passphrase?"] 99 | * it's easier to hit a reasonable level of entropy; 100 | * you are less likely to forget the resulting passphrase; and 101 | * your passphrase will be more robust in the face of keymapping snafus at boot time. 102 | 103 | == Creating a New GPT Partition on the PC's Main Drive == 104 | 105 | Our next task is to create a new GPT partition on the target PC's hard drive (which we [[../Preparing_Windows_for_Dual-Booting#shrink_windows_partition|freed up space for earlier]]). 106 | 107 | We will use the {{c|parted}} tool, instruct it to use sectors for units, and then display the free space on the current drive. We'll then create a new primary partition on that drive using all the available space indicated. 108 | 109 | {{Warning|Please take particular care with this step. {{c|parted}} can cause '''catastrophic data loss''' if misused and, unlike {{c|fdisk}}, writes changes immediately.}} 110 | 111 | We must first find the device path of the main hard drive on the target machine. We will refer to this as {{Path|/dev/sdZ}} in the following text, but it will be something like {{Path|/dev/sda}}, {{Path|/dev/sdb}} etc. on your machine. Check the actual path with: 112 | 113 | {{RootCmd 114 | |lsblk 115 | |prompt=livecd ~ # 116 | }} 117 | If you are dual booting with Windows, you'll probably see that the desired drive has between four and six existing partitions, depending on your version of Windows (note that the initial {{Path|/dev/}} prefix is not shown in the {{c|lsblk}} output). None of these should be mounted (all should have blank mountpoints in the output of {{c|lsblk}}). 118 | 119 | Now we will create the partition: 120 | {{RootCmd 121 | |parted -a optimal /dev/sdZ 122 | |prompt=livecd ~ # 123 | |output=
124 | GNU Parted 3.1
125 | ... additional output suppressed ...
126 | (parted) unit s
127 | (parted) print free
128 | ... additional output suppressed ...
129 | Number  Start      End         Size        File system  Name                          Flags
130 | ... additional output suppressed ...
131 |         AAAs       BBBs        CCCs        Free Space
132 | 
133 | (parted) mkpart primary AAAs BBBs
134 | (parted) quit
135 |
136 | }} 137 | {{Note|Replace {{Path|/dev/sdZ}} in the above command with the path of the target machine's main drive (the one on which Windows is installed), such as {{Path|/dev/sda}}. Note also that we need to target the device itself, and not a partition within it, so for {{Path|/dev/sdZ}} in the above command, use e.g. {{Path|/dev/sda}} and ''not'' {{Path|/dev/sda1}}; {{Path|/dev/sdb}} and ''not'' {{Path|/dev/sdb1}}, etc.}} 138 | {{Note|You should of course also substitute for AAA and BBB, whatever output is displayed for the boundaries of the free space when you issue the {{c|print free}}. For example, if you got back 
        89362432s  500118158s  410755727s  Free Space
you would issue 
(parted) mkpart primary 89362432s 500118158s
139 | You can make the partition smaller, if you do not wish to use all of the remaining space for the Gentoo install. It can be useful to reserve some space (<{{=}}1[[:Wikipedia:Gibibyte{{!}}GiB]], say) for e.g. an emergency recovery partition, but whether to do so is entirely up to you.}} 140 | {{Note|You may see multiple blocks of free space listed (particularly with modern versions of Windows 10; in this case, just use the largest one.}} 141 | {{Note|The suffix 's' in the dimensions passed above tells parted that you are using 'sector' units. Do not omit it!}} 142 | {{Note|If {{c|parted}} complains that your new partition is '''not properly aligned for best performance''', you may wish to cancel the {{c|mkpart}}, then try again with modified values: rounding the start address ''up'' to the nearest 2048, and the end address ''down'' to the nearest 2048 sectors. For example, if the largest free block prior to creation of the new partition was reported as 
224107278s  469868543s  245761266s  Free Space
you could do the following on your helper PC to calculate optimal values:{{Cmd 143 | |echo "$((((224107278 + 2047) / 2048) * 2048))s $((469868543 - (469868543 % 2048)))s" 144 | |output=
145 | 224108544s 469866496s
146 |
147 | |prompt=user@pc2 $}} 148 | so you would issue: 
(parted) mkpart primary 224108544s 469866496s
Obviously, adapt using the sector start and end addresses for the free space block on your drive! Incidentally, the 'magic number' 2048 is a safe choice for most drives; but you can easily calculate the actual optimal value for your own device, if desired.Rainbow Chard Blog: [http://rainbow.chard.org/2013/01/30/how-to-align-partitions-for-best-performance-using-parted/ ''How to align partitions for best performance using parted'']}} 149 | {{Note|If the drive you are using has ''not'' yet been partitioned, the {{c|print free}} command will not output data as above. In such a case, you will need to issue a mklabel gpt command within {{c|parted}} first. However, do '''not''' do this (i.e., issue mklabel gpt) on an already-partitioned drive; you will lose all the data on there if you do!
Users who are targeting a fresh disk in this way may also find it easier to create the partition itself with the {{c|parted}} command mkpart primary 0% 100%, as this will deal with all sector alignment issues etc. (Users with existing data on their drives should '''not''' do this however, but instead follow the commands given in the main text.)}} 150 | {{Note|Additionally, users who are ''not'' co-installing with Windows may find it useful to create two partitions on {{Path|/dev/sdZ}}: the main one as specified above, and a second EFI system partition. This will allow e.g. subsequent migration of the kernel from the boot USB key to the main drive later if desired. Users who ''do'' intend to dual-boot with Windows should ignore this point: your hard drive already contains an EFI system partition.}} 151 | 152 | Now check that the partition has been created correctly. We'll issue an {{c|lsblk}} command again: 153 | {{RootCmd 154 | |lsblk 155 | |prompt=livecd ~ # 156 | }} 157 | Take note of the new sector device path (note that the initial {{Path|/dev/}} prefix is not shown in the {{c|lsblk}} output). We will refer to this as {{Path|/dev/sdZn}} in the below, but it will actually be something like {{Path|/dev/sda7}}, {{Path|/dev/sdb7}} etc. If you have a non-standard Windows setup, the number of the new partition may also be something other than 7 (for example, on older Windows 10 and most Windows 8 systems it is more likely to be 5), so do please double check. 158 | 159 | == Overwriting the New Partition with Pseudo-Random Data (Optional Step) == 160 | 161 | You can [[#format_luks_partition|skip this step]] if you like. The main reasons to perform an overwrite are: 162 | * to purge any old, unencrypted data that may still be present in the partition (from prior use); and 163 | * to make it somewhat harder for an attacker to determine how much data is on your drive if the machine is compromised. 164 | 165 | However, it may make things slower on a solid-state drive, by forcing any new writes to first delete a sector (once any overcapacity has been exceeded), rather than simply writing to a fresh, unused one (and furthermore, it cannot completely be guaranteed that old data ''has'' been wiped, when using such devices). 166 | 167 | This command may take a number of hours to complete. 168 | 169 | {{Warning|The step below will '''destroy''' existing data on the partition; please double check to ensure you have the correct device path (e.g., {{Path|/dev/sda7}} etc.) before continuing.}} 170 | {{RootCmd 171 | |dd if{{=}}/dev/urandom of{{=}}/dev/sdZn bs{{=}}1M status{{=}}progress && sync 172 | |prompt=livecd ~ # 173 | }} 174 | {{Note|Replace {{Path|/dev/sdZn}} in the above command with the device path for the partition we just created, e.g., {{Path|/dev/sda7}}.}} 175 | 176 | You will be able to see {{c|dd}} slowly progressing. Wait for it to complete before proceeding to the next step. 177 | 178 | == Formatting the New Partition with LUKS == 179 | 180 | The next step is to format the partition using [[:Wikipedia:Linux_Unified_Key_Setup|LUKS]]. LUKS, which stands for Linux Unified Key Setup, is as the name suggests primarily a way to manage the encryption keys for whole-partition (or drive) encryption. It does this by first generating a high-entropy, secret, ''master key'', which is then encrypted using between one and eight ''user keys'' (themselves first pre-processed by [[:Wikipedia:PBKDF2|PBKDF2]]). 181 | 182 | The target partition itself begins with a LUKS metadata header, followed by the encrypted master key material corresponding to each of the 8 possible user 'slots', and finally the bulk, encrypted (payload) data itself (the encrypted sector data for the partition). 183 | 184 | The LUKS master key itself is ''never'' stored in unencrypted form on the partition, nor (unless you explicitly request it) even made visible to you, the user. 185 | 186 | LUKS uses a cryptographic splitting and chaining technique to artificially inflate the size of the key material for each slot into a number of interdependent 'stripes'. This is done to increase the likelihood that, when a slot is modified (a user key is revoked, or changed, for example), that the old key material is, indeed, irrecoverable (necessary, since under LUKS the partition master key is ''never'' changed once created). Be warned though, that with solid-state drives no guarantees can be given, if you change a user key, that the old key material is not retained on the drive somewhere (due to wear-levelling etc.).cryptsetup: [https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions "Frequently Asked Questions"]; section 5.19/ 187 | 188 | LUKS functions are accessed via the {{Highlight|cryptsetup}} program, and use [[Dm-crypt|dm-crypt]] for the back-end processing. Note that LUKS is agnostic as to the actual symmetric encryption method used, provided it is supported by dm-crypt. You can get a list of the (currently loaded) encryption and hash algorithms by issuing: 189 | {{RootCmd 190 | |cat /proc/crypto 191 | |prompt=livecd ~ # 192 | }} 193 | (You may have others available as kernel modules, which will be loaded when required). 194 | 195 | What we need to do is tell {{c|cryptsetup}}: 196 | * the underlying block cipher we want to use (block ciphers work on fixed-size units, or blocks, of data to encrypt or decrypt at a time), 197 | * the key length to use with this cipher, 198 | * the way we'll ''tweak'' it to en/decrypt amounts of data larger than one cipher block (many ciphers use a 16-byte block, and sectors, the indexing unit, are larger than this), 199 | * what processing, if any, should be applied to the sector index number during [[:Wikipedia:Initialization_vector|IV]] computation, and 200 | * the hash algorithm used for key derivation (under the [[:Wikipedia:PBKDF2|PBKDF2]] algorithm within LUKS) 201 | 202 | This isn't a cryptography primer ([[:Wikipedia:Disk_encryption_theory|see this article]] for further reading), but here's a thumbnail justification for the choices made: 203 | * we will use [[:Wikipedia:Serpent_(cipher)|Serpent]] as the block cipher; this came second in the AES competition [http://www.100tb.com/blog/2013/05/security-performance-serpent-cipher-rijndael/ mainly for reasons of speed], but has a more conservative design (32 rounds as opposed to 14) and scored a higher safety factor when compared to the [[:Wikipedia:Rijndael|Rijndael]] algorithm that won the competition (and which, accordingly, is now commonly referred to as 'AES'); 204 | * for security, we'll use the longest supported key length for Serpent, which is 256 bits (see the following point, however); 205 | * we will use [[:Wikipedia:XEX-TCB-CTS#XEX-based_tweaked-codebook_mode_with_ciphertext_stealing_.28XTS.29|XTS]] mode to both extend the cipher over multiple blocks within a sector, and perform the by-sector-index 'tweaking'; this approach overcomes the security weakness in the more conventional [[:Wikipedia:Cipher_block_chaining#Cipher-block_chaining_.28CBC.29|CBC]] / [[:Wikipedia:ESSIV|ESSIV]] methodology, whereby an attacker, although unable to read the encrypted material, can yet, if they know the cleartext for that sector (possible for some system files), arbitrarily modify alternating blocks to inject shellcodeLell, Jakob. [http://www.jakoblell.com/blog/2013/12/22/practical-malleability-attack-against-cbc-encrypted-luks-partitions/ "Practical malleability attack against CBC-encrypted LUKS partitions"]; this is a non-trivial concern for a dual-boot machine where the Windows side of things is untrusted (and has access to the encrypted contents of the LUKS partition when running). Note that since XTS mode actually requires ''two'' keys, we must pass an effective key length of 512 (= 2 x 256) bits to {{c|cryptsetup}}; 206 | * as XTS is a (modified) ''counter'' mode, we will simply pass the untransformed ("plain") 64-bit sector index to it (using a 64-bit index will allow for disks > 2TiB);dm-crypt Mailing List: [http://www.saout.de/pipermail/dm-crypt/2010-July/001039.html "Using plain64/plain IV (initialisation vector) in dm-crypt"] 207 | * we will use [[:Wikipedia:Whirlpool_(cryptography)|Whirlpool]] as the user key hashing function for LUKS' PBKDF2 processing; it is a 512 bit hash that has been recommended by the [[:Wikipedia:NESSIE|NESSIE]] project. Note that Whirlpool hash will appear in the output from {{Path|/proc/crypto}} as {{c|wp512}} (if loaded). 208 | 209 | We decrypt our keyfile from the USB key (using {{c|gpg}}) and pipe it to {{c|cryptsetup}}, to avoid the unencrypted keyfile having to be saved to disk. The --cipher and --hash strings instruct {{c|cryptsetup}} to use the settings just discussed. 210 | 211 | {{Warning|The step below will '''destroy''' existing data on the partition; please double check to ensure you have the correct device path (e.g., {{Path|/dev/sda7}} etc.) before continuing. When you pipe the keyfile in this way, {{c|cryptsetup}} will ''not'' ask you if you are sure prior to formatting.}} 212 | {{RootCmd 213 | |gpg --decrypt /tmp/efiboot/luks-key.gpg {{!}} cryptsetup --cipher serpent-xts-plain64 --key-size 512 --hash whirlpool --key-file - luksFormat /dev/sdZn 214 | |prompt=livecd ~ # 215 | |output=
216 | 
217 | ... additional output suppressed ...
218 |
219 | }} 220 | {{Note|Replace {{Path|/dev/sdZn}} in the above command with the device path for the partition we just created, e.g., {{Path|/dev/sda7}}.
Also, you ''may'' see some errors of the form device-mapper: remove ioctl on XXX failed: Device or resource busy; these can generally be ignored, provided the {{c|luksDump}} command (described below) works.}} 221 | {{Note|Depending on how soon after first creating the {{c|gpg}} keyfile you issue the above command, you may find that you are not prompted for a passphrase at all. That's because your passphrase has been (temporarily) cached behind the scenes, for convenience, by {{c|gpg-agent}}. If you ''want'' to force the passphrase prompt (for example to double-check you have the passphrase written down correctly!), you can do so by issuing the following prior to the {{c|luksFormat}} command above: 222 | {{RootCmd 223 | |echo RELOADAGENT {{!}} gpg-connect-agent 224 | |prompt=livecd ~ # 225 | }} 226 | }} 227 | {{Note|By default, {{c|cryptsetup}} uses {{Path|/dev/random}} as its random number generator (RNG); this ''may'' run out of entropy when formatting the partition and print a warning; if this happens, just run your finger over the touchpad of the target machine (or move its mouse, if attached) until the process completes.}} 228 | {{Note|If you use the Whirlpool hash (as we have done), be aware that you will not be able to open the LUKS container using {{Package|dev-libs/libgcrypt}} < v1.6.0, because of a bug in those earlier versions when writing data to the Whirlpool hash function in chunks.dm-crypt Mailing List: [http://www.saout.de/pipermail/dm-crypt/2014-January/003813.html "Whirlpool in gcrypt <= 1.5.3 broken (if writes in chunks)?"]}} 229 | {{Note|If you'd rather use a vanilla approach, omit the --cipher and --hash arguments; {{c|cryptsetup}} will then revert to its compiled-in defaults (which you can see using) 230 | {{RootCmd 231 | |cryptsetup --help 232 | |prompt=livecd ~ # 233 | }} 234 | At the time of writing, this implies aes-xts-plain64, so [[:Wikipedia:Rijndael|Rijndael]] (AES) rather than [[:Wikipedia:Serpent_(cipher)|Serpent]], with a 256bit key (which really means 2 x 128bit keys, given XTS mode, so less secure than our 512bit ({{=}} 2 x 256bit) variant), and SHA1 for the LUKS password hashing, which again is arguably less good than Whirlpool. Ultimately, the choice is yours of course.}} 235 | {{Note|Although you ''can'' specify an additional hash postfix in the --cipher string (e.g. serpent-xts-plain64:whirlpool rather than simply serpent-xts-plain64), it will be ''ignored'' by the kernel in plain64 mode.dm-crypt Mailing List: [http://www.spinics.net/lists/dm-crypt/msg05521.html "Re: Non-standard cipher mode"] As such, you should omit it (as we have done). Remember, this postfix is ''only'' used to specify the hash function for [[:Wikipedia:Initialization_vector|IV]] processing (if any), and so is relevant in [[:Wikipedia:ESSIV|ESSIV]] mode, for example. It has ''nothing'' to do with the hash used in the LUKS header, which is specified by the --hash argument, as above.}} 236 | 237 | Check that the formatting worked, with: 238 | {{RootCmd 239 | |cryptsetup luksDump /dev/sdZn 240 | |prompt=livecd ~ # 241 | }} 242 | {{Note|Replace {{Path|/dev/sdZn}} in the above command with the device path for the LUKS partition, e.g., {{Path|/dev/sda7}}.}} 243 | 244 | This should print out information about the LUKS setup on the sector, and show that one of the 8 keyslots (slot 0) is now in use (incidentally, pointing out that LUKS does not provide any plausible deniability about the use of encryption! You ''can'' [https://www.kernel.org/pub/linux/utils/cryptsetup/v1.4/v1.4.0-ReleaseNotes detach the header] and store it on a separate device, but we won't do that here as it isn't supported in the standard {{c|genkernel}} init scripts that we'll rely on later.). 245 | {{Important|If the LUKS header gets damaged, your encrypted data will be lost forever, even if you have a backup of the GPG key and passphrase. Therefore, you may wish to consider backing up this header to a separate device, and storing it securely. See the [https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions#6-backup-and-data-recovery LUKS FAQ] for more details on how to do this.
For example, to save a copy of the current LUKS header to your boot USB key (doing so is optional), you could now issue, per the FAQ: 246 | {{RootCmd 247 | |cryptsetup luksHeaderBackup /dev/sdZn --header-backup-file /tmp/efiboot/luks-header.img 248 | |prompt=livecd ~ # 249 | }} 250 | Replace {{Path|/dev/sdZn}} in the above command with the device path for the LUKS partition, e.g., {{Path|/dev/sda7}}.
'''Be aware''' that if you do keep a LUKS header backup in this fashion, and subsequently revoke any of the keyslots, that the old keys will ''still'' be usable to unlock the LUKS partition, to those with access to that header backup file. 251 | }} 252 | 253 | == Adding a Fallback Passphrase (Optional Step) == 254 | 255 | Since LUKS supports up to 8 user key 'slots', you can, if you wish, add an additional (traditional) passphrase to your LUKS container now. This is not intended for use day-to-day, but simply as a last-resort fallback, should you lose the USB key with the GPG keyfile on it, for example. 256 | 257 | {{Warning|If you are concerned that your machine might already contain a keylogger, '''do not''' perform this step; [[#create_lvm_structure{{!}}click here]] to jump to the next task instead.}} 258 | {{Important|If, at the conclusion of the tutorial, you wish to be able to switch to booting ''without'' using the GPG keyfile, then you ''should'' setup a fallback passphrase now.}} 259 | 260 | Unfortunately, the necessary {{c|cryptsetup}} command requires that we provide an existing valid user key in addition to the new one we want to add. If we pipe this in directly from {{c|gpg}} (as we did earlier), then cryptsetup will not prompt correctly for a new passphrase. To get around this issue, without writing the existing GPG key out in binary plaintext form to a disk file, we'll use a [http://www.linuxjournal.com/article/2156 named pipe]. 261 | 262 | Assuming you're using {{c|screen}}, hit {{Key|Ctrl}}{{Key|a}} followed by {{Key|c}} to start a new virtual console. Then type: 263 | {{RootCmd 264 | |mkfifo /tmp/gpgpipe 265 | |echo RELOADAGENT {{!}} gpg-connect-agent 266 | |gpg --decrypt /tmp/efiboot/luks-key.gpg {{!}} cat - >/tmp/gpgpipe 267 | |prompt=livecd ~ # 268 | |output=
269 | 
270 | ... additional output suppressed ...
271 |
272 | }} 273 | (The slightly odd approach of piping via {{c|cat}} is intentional.) This will block once you type in your passphrase, as nothing is connected to the other end our the named pipe (yet). Now switch back to the original virtual console with {{Key|Ctrl}}{{Key|a}} followed by {{Key|p}}, and enter: 274 | 275 | {{RootCmd 276 | |cryptsetup --key-file /tmp/gpgpipe luksAddKey /dev/sdZn 277 | |prompt=livecd ~ # 278 | |output=
279 | Enter new passphrase for key slot: 
280 | Verify passphrase: 
281 |
282 | }} 283 | {{Note|Replace {{Path|/dev/sdZn}} in the above command with the device path for the LUKS partition, e.g., {{Path|/dev/sda7}}.}} 284 | 285 | Verify that this worked by issuing: 286 | {{RootCmd 287 | |cryptsetup luksDump /dev/sdZn 288 | |prompt=livecd ~ # 289 | }} 290 | {{Note|Replace {{Path|/dev/sdZn}} in the above command with the device path for the LUKS partition, e.g., {{Path|/dev/sda7}}.}} 291 | 292 | You should now see slot 1 is enabled, as well as slot 0. Now, remove the named pipe, since we no longer need it: 293 | {{RootCmd 294 | |rm -vf /tmp/gpgpipe 295 | |prompt=livecd ~ # 296 | }} 297 | 298 | Lastly, switch back to the second virtual console with {{Key|Ctrl}}{{Key|a}} followed by {{Key|n}}, and then hit {{Key|Ctrl}}{{Key|d}} to close it out and return to the original console again. 299 | 300 | == Creating the LVM Structure (PV->VG<-LVs) on Top of LUKS == 301 | 302 | Our next step is to set up an LVM structure within the LUKS container we just created. LVM stands for Logical Volume Manager: a useful overview may be found [https://wiki.archlinux.org/index.php/LVM here], and a handy command cheatsheet [http://www.datadisk.co.uk/html_docs/redhat/rh_lvm.htm here]. It is a highly flexible virtual partition system. Some important LVM terminology is as follows: 303 | * A {{Highlight|physical volume (PV)}} is an underlying storage device (for example, an actual disk partition or loopback file), which is managed by LVM. PVs have a special header, and are divided into physical extents. 304 | * A {{Highlight|physical extent (PE)}} is the smallest allocatable unit of a PV. We will use the default PE size of 4MiB in this tutorial. 305 | * A {{Highlight|logical volume (LV)}} is LVM's equivalent of a partition. It contains ''logical extents'', which are mapped one-to-one onto the PEs of contributing physical volumes. Note - unlike a conventional partition, because of this architecture an LV can span multiple underlying physical volumes, and a physical volume can host multiple logical volumes, if desired. The LV appears as a standard block device, and so can be formatted with any normal Linux filesystem (e.g. [[ext4]]). We will create LVs for the root directory, the user home directory and swap in this tutorial. 306 | * A {{Highlight|volume group (VG)}} is an administrative unit gathering together a collection of LVs and PVs. We will create a single VG containing a single PV, and (as just mentioned) three LVs. 307 | 308 | The main reason we're using LVM here is to provide a simple way to get three 'logical' partitions on top of a single underlying LUKS container (partition). LVM also provides a number of additional advantages when resizing, backing up, or moving partitions, in exchange for a little initial configuration overhead.Arch Linux Wiki: [https://wiki.archlinux.org/index.php/LVM#Advantages "LVM: Advantages"] 309 | 310 | To proceed with LVM, the first thing we need to do is ''open'' the LUKS volume we just created, as it will host our single PV. Issue: 311 | 312 | {{RootCmd 313 | |gpg --decrypt /tmp/efiboot/luks-key.gpg {{!}} cryptsetup --key-file - luksOpen /dev/sdZn gentoo 314 | |prompt=livecd ~ # 315 | |output=
316 | Enter passphrase
317 | 
318 | ... additional output suppressed ...
319 |
320 | }} 321 | {{Note|Replace {{Path|/dev/sdZn}} in the above command with the device path for the LUKS partition, e.g., {{Path|/dev/sda7}}.}} 322 | {{Note|Depending on how soon after last decrypting the {{c|gpg}} keyfile you issue the above command, you may find that you are not prompted for a passphrase at all. That's because your passphrase has been (temporarily) cached behind the scenes, for convenience, by {{c|gpg-agent}}. If you ''want'' to force the passphrase prompt (for example to double-check you have the passphrase written down correctly!), you can do so by issuing the following prior to the {{c|luksOpen}} command above: 323 | {{RootCmd 324 | |echo RELOADAGENT {{!}} gpg-connect-agent 325 | |prompt=livecd ~ # 326 | }} 327 | }} 328 | 329 | Check that this worked: 330 | {{RootCmd 331 | |ls /dev/mapper 332 | |prompt=livecd ~ # 333 | |output=
334 | control  gentoo
335 |
336 | }} 337 | You should see the device 'gentoo' in the device mapper list, as above. This is our unlocked LUKS partition. 338 | 339 | Next, we'll create an LVM physical volume (PV) on this partition: 340 | 341 | {{RootCmd 342 | |pvcreate /dev/mapper/gentoo 343 | |prompt=livecd ~ # 344 | }} 345 | 346 | {{Note|If you see a warning such as:{{GenericCmd|
347 |   /run/lvm/lvmetad.socket: connect failed: No such file or directory
348 |   WARNING: Failed to connect to lvmetad. Falling back to internal scanning.
349 |
}} when running this or subsequent LVM commands, it may generally safely be ignored.}} 350 | 351 | Then, we create a volume group (VG) hosting this PV. We'll call the new VG "vg1". Note that since we're using lvm2 format here, there's no need to set a larger physical extent size - the default of 4MiB per PE will be fine Fedora Forum: [http://forums.fedoraforum.org/showthread.php?t=281745 "LVM PE size - is it important?"]: 352 | {{RootCmd 353 | |vgcreate vg1 /dev/mapper/gentoo 354 | |prompt=livecd ~ # 355 | }} 356 | 357 | {{Important|Please use the suggested VG name ({{c|vg1}}), since this is assumed by the {{c|buildkernel}} utility later. If you do need to change it, you'll need to override CMDLINE_REAL_ROOT and CMDLINE_REAL_RESUME variables appropriately in {{Path|/etc/buildkernel.conf}} [[../Configuring_and_Building_the_Kernel#deal_with_different_vg_name{{!}}later in the tutorial]].}} 358 | 359 | Now, we'll create three logical volumes (LVs) in this volume group. The first is for swap. To allow the use of {{Highlight|suspend to disk}} (which we'll setup [[../Final_Configuration_Steps#suspend_hibernate|later]]) we'll want a swap slightly larger than the size of our RAM. So first, find the size of RAM on your system with: 360 | 361 | {{RootCmd 362 | |grep MemTotal /proc/meminfo 363 | |prompt=livecd ~ # 364 | }} 365 | 366 | In the case of the CF-AX3, this shows just under 8[[:Wikipedia:Gibibyte|GiB]], hence we'll allocate 10GiB. Adjust this for your system and preferences. If you don't want to use suspend to disk, a much smaller swap would work just as well. 367 | 368 | {{RootCmd 369 | |lvcreate --size 10G --name swap vg1 370 | |prompt=livecd ~ # 371 | }} 372 | {{Note|LVM uses base-2 units, so this is 10GiB. Adjust the size to suit your system, as described above.}} 373 | {{Note|If {{c|lvcreate}} complains about not being able to wipe the start of the LV, try adding the -Z n parameter to the previous command. Supposedly it is dangerous to mount an LV whose first few kilobytes haven't been wiped, but then again, you'll be formatting your LV with a filesystem.}} 374 | 375 | Next, we'll create a relatively large LV to hold our root partition. This will eventually hold everything apart from the user home directories, and, since this is Gentoo, we'll need a fair amount of room for {{c|portage}} files and so on. We'll allow 50GiB here - if you wish you can make this smaller or larger of course: 376 | 377 | {{RootCmd 378 | |lvcreate --size 50G --name root vg1 379 | |prompt=livecd ~ # 380 | }} 381 | {{Note|LVM uses base-2 units, so this is 50GiB. Adjust the size to suit your needs, as described above.}} 382 | 383 | Finally, let's create a third LV to hold the user home directories. We'll instruct LVM to use almost all the remaining space on the LUKS container for this, leaving 5% of the (so far unused space) free (this additional room will come in useful if you want to take a snapshotArch Linux Wiki: [https://wiki.archlinux.org/index.php/Create_root_filesystem_snapshots_with_LVM "Create root filesystem snapshots with LVM"] later, for example). 384 | 385 | {{RootCmd 386 | |lvcreate --extents 95%FREE --name home vg1 387 | |prompt=livecd ~ # 388 | }} 389 | 390 | You should now be able to look at the status of the physical volume (PV), volume group (VG) and logical volumes (LVs), as follows: 391 | 392 | {{RootCmd 393 | |pvdisplay 394 | |vgdisplay 395 | |lvdisplay 396 | |prompt=livecd ~ # 397 | }} 398 | 399 | The final task in this step is to 'activate' the new volume group (vg1) so that it's logical volumes become available as block devices via the device mapper. Issue: 400 | 401 | {{RootCmd 402 | |vgchange --available y 403 | |prompt=livecd ~ # 404 | }} 405 | 406 | This should inform you that three LVs in the vg1 volume group have been activated. Check that they are visible via the device mapper: 407 | 408 | {{RootCmd 409 | |ls /dev/mapper 410 | |prompt=livecd ~ # 411 | |output=
412 | control  gentoo  vg1-home  vg1-root  vg1-swap
413 |
414 | }} 415 | 416 | If your output looks similar to the above, then all is well. The new logical volumes ({{Path|/dev/mapper/vg1-home}}, {{Path|/dev/mapper/vg1-root}} and {{Path|/dev/mapper/vg1-swap}}) can be treated exactly like physical disk partitions (i.e., just like {{Path|/dev/sda1}} etc.). 417 | 418 | == Formatting and Mounting the LVM Logical Volumes (LVs) == 419 | 420 | Now we have our virtual partitions, we need to set up their filesystems and then mount them. 421 | 422 | First, create the swap: 423 | {{RootCmd 424 | |mkswap -L "swap" /dev/mapper/vg1-swap 425 | |prompt=livecd ~ # 426 | }} 427 | 428 | Next, the root filesystem. We'll create this as [[ext4]] (you can of course modify this if you wish): 429 | 430 | {{RootCmd 431 | |mkfs.ext4 -L "root" /dev/mapper/vg1-root 432 | |prompt=livecd ~ # 433 | }} 434 | 435 | Finally, the user home filesystem, also ext4. Note that we use the {{c|-m 0}} option here, since ext4 will, by default, reserve 5% of the filesystem for the superuser, and we don't need that in this location, only on the root partition: 436 | {{RootCmd 437 | |mkfs.ext4 -m 0 -L "home" /dev/mapper/vg1-home 438 | |prompt=livecd ~ # 439 | }} 440 | 441 | Now, we activate the swap: 442 | {{RootCmd 443 | |swapon -v /dev/mapper/vg1-swap 444 | |prompt=livecd ~ # 445 | }} 446 | 447 | And, per the handbook, mount the root directory at the pre-existing {{Path|/mnt/gentoo}} mountpoint: 448 | {{RootCmd 449 | |mount -v -t ext4 /dev/mapper/vg1-root /mnt/gentoo 450 | |prompt=livecd ~ # 451 | }} 452 | 453 | Next, we create the {{Path|/mnt/gentoo/home}} mountpoint, a {{Path|/mnt/gentoo/boot}} directory, and a {{Path|/mnt/gentoo/boot/efi}} mountpoint. The purpose of these is as follows: 454 | * {{Path|/mnt/gentoo/home}} will be the mountpoint for our home directory LV. 455 | * {{Path|/mnt/gentoo/boot}} will be the equivalent of the /boot directory in the Gentoo handbook. We will build our [[kernel]] and [[initramfs]] targeting this directory as usual, although, since we are booting from an UEFI USB key, this directory will ''not'' be used when booting the system itself. Instead, the {{c|buildkernel}} utility, supplied as part of this tutorial, will be used to copy the final, signed and bootable kernel image onto the USB key (at {{Path|/mnt/gentoo/efiboot}}) as part of the kernel build process. For that reason, we've converted {{Path|/mnt/gentoo/boot}} from a mountpoint to a regular directory in this tutorial. 456 | * {{Path|/mnt/gentoo/boot/efi}} will be the mountpoint for our USB boot key when inserted in the machine (when installing a new kernel, etc.). We currently have the key mounted at {{Path|/tmp/efiboot}} and will need to unmount it. 457 | 458 | Create the directories: 459 | {{RootCmd 460 | |mkdir -v /mnt/gentoo/{home,boot,boot/efi} 461 | |prompt=livecd ~ # 462 | }} 463 | 464 | Now mount the "home" LVM logical volume from the "vg1" volume group on the {{Path|/mnt/gentoo/home}} mountpoint: 465 | {{RootCmd 466 | |mount -v -t ext4 /dev/mapper/vg1-home /mnt/gentoo/home 467 | |prompt=livecd ~ # 468 | }} 469 | 470 | Next, we need to unmount the USB boot key's EFI partition from its current temporary mountpoint (we'll remount it later, when we build the kernel): 471 | {{RootCmd 472 | |umount -v /tmp/efiboot 473 | |prompt=livecd ~ # 474 | }} 475 | 476 | Finally, issue: 477 | 478 | {{RootCmd 479 | |blkid /dev/sdY1 /dev/sdZn 480 | |prompt=livecd ~ # 481 | }} 482 | {{Note|Replace {{Path|/dev/sdY1}} in the above with the actual path of your USB boot key's first partition, which we found [[#making_boot_usb_key{{!}}earlier]] (e.g., {{Path|/dev/sdc1}} etc.), and {{Path|/dev/sdZn}} with the actual device path for the LUKS partition (e.g., {{Path|/dev/sda7}} etc.). }} 483 | 484 | Take note of the PARTUUIDs (unique partition identifiers) for these two partitions; we'll make use of them later (in the {{c|fstab}} and the kernel build script's configuration file), rather than relying on the {{Path|/dev/sd??}} paths (which can change depending on which devices are plugged in, and the order in which they are recognized). 485 | 486 | == Next Steps == 487 | 488 | We're now ready to fetch the additional installation files and setup the build options. [[../Installing_the_Gentoo_Stage_3_Files|Click here]] to go to the next chapter, "Installing the Gentoo Stage 3 Files". 489 | 490 | == Notes == 491 | {{reflist}} 492 | 493 | {| class="wikitable" style="margin: 1em auto 1em auto;" 494 | |- 495 | | [[../Setting_Up_Networking_and_Connecting_via_ssh|< Previous]] 496 | | [[../|Home]] 497 | | [[../Installing_the_Gentoo_Stage_3_Files|Next >]] 498 | |} 499 | 500 | [[Category:Sakaki's EFI Install Guide]] 501 | [[Category:Security]] 502 | 503 | -------------------------------------------------------------------------------- /09_Final_Preparations_and_Reboot_into_EFI: -------------------------------------------------------------------------------- 1 | 2 | 3 | In this section, we'll be following along with [[Handbook:AMD64/Installation/System|Chapter 8]] of the Gentoo handbook. However, we'll defer some of the configuration tasks mentioned there until the next chapter, when you have rebooted (mainly to help out those users who [[../Building_the_Gentoo_Base_System_Minus_Kernel#choose_systemd_or_openrc|have chosen]] {{c|systemd}} as their target init, since {{c|systemd}} configuration is most easily done from within a system actually running {{c|systemd}}). The steps we'll be undertaking are: 4 | # Setting up the mountpoint tables {{Path|/etc/fstab}} and {{Path|/etc/mtab}}; 5 | # Concluding preparations, viz.: 6 | ## Emerging some necessary packages (which it will be useful to have in place before a reboot); 7 | ## Taking note of networking information; 8 | ## Configuring networking for use post-reboot ({{c|OpenRC}} users only) 9 | ## Setting up a root password for the new system; then 10 | # Cleanly dismounting the {{c|chroot}}, and restarting; 11 | # Logging in to your new system as the root user, directly at the target machine's keyboard. 12 | 13 | Instructions are also provided at [[#if_things_go_wrong|the end of this chapter]] to recover back to a {{c|chroot}} environment, should things not go as planned. 14 | 15 | Please note that at the conclusion of this chapter there is a parting of the ways, depending on [[../Building_the_Gentoo_Base_System_Minus_Kernel#choose_systemd_or_openrc|your previous choice]] of init system: 16 | * users targeting {{c|OpenRC}} should continue following the regular guide Chapters 10-14; however 17 | * users targeting {{c|systemd}} should instead follow the 'alternative track' Chapters 10-14. 18 | The division point is [[#next_steps|clearly marked]]. 19 | 20 | So let's get started! 21 | 22 | == Setting up the Mountpoint Tables == 23 | 24 | Per the Gentoo handbook, we first need to setup {{Path|/etc/fstab}}, so that the system knows the location, mount point, filesystem type and mount options for the key system partitions. There are three such partitions (which we created [[../Preparing_the_LUKS-LVM_Filesystem_and_Boot_USB_Key#create_lvs|earlier]]): 25 | # the {{Highlight|root}} partition, which holds the system software, configuration files, and the superuser's home directory (device file path {{Path|/dev/mapper/vg1-root}}); 26 | # the {{Highlight|swap}} partition, which is used to extend the system's available memory, and can also be used for hibernation (device file path {{Path|/dev/mapper/vg1-swap}}); and 27 | # the {{Highlight|home}} partition, which holds the home directories of normal users (device file path {{Path|/dev/mapper/vg1-home}}). 28 | 29 | We need to add entries for each of these to [[fstab]]; so issue: 30 | {{RootCmd 31 | |nano -w /etc/fstab 32 | |prompt=(chroot) livecd / # 33 | }} 34 | and then edit the file, so that the only ''uncommented'' lines (those not starting with a {{c|#}} symbol), are as follows: 35 | {{FileBox|filename=/etc/fstab|title=Set the following as the only uncommented lines|1= 36 | /dev/mapper/vg1-root / ext4 defaults,noatime,errors=remount-ro,discard 0 1 37 | /dev/mapper/vg1-swap none swap defaults,noatime,discard 0 0 38 | /dev/mapper/vg1-home /home ext4 defaults,noatime,discard 0 2 39 | }} 40 | If you have a cd- or dvd-rom drive on your machine (the Panasonic CF-AX3 does not), you can also add the following additional line: 41 | {{FileBox|filename=/etc/fstab|title=Add the following additional line, if you have a cd-rom or dvd-rom drive|1= 42 | /dev/cdrom/ /mnt/cdrom auto noauto,user,ro 0 0 43 | }} 44 | Save and exit {{c|nano}}. 45 | 46 | In the {{Path|/etc/fstab}} file:[http://man7.org/linux/man-pages/man5/fstab.5.html {{c|fstab}} (7) manpage] 47 | * The first field describes the path to the partition's device file (NB - when this file is referenced, the [[initramfs]]-based {{c|init}} script will already have unlocked the LUKS partition and activated the LVM logical volumes, so we can safely use the device-mapper paths, as above). 48 | * The second field shows the mount point. 49 | * The third field shows the filesystem type. I have assumed (per the tutorial instructions) that you have used [[ext4]] for the root and home partitions; if you chose something different, make sure to reflect it here. The use of {{c|auto}} for the optional cd-rom makes the operating system guess the filesystem type, which is useful with removable media. 50 | * The fourth field contains the mount options; these choices here are described in more detail below. 51 | * The fifth field is used by the {{c|dump}} command to denote which filesystems require dumping. It's generally fine to leave this as 0 (do not dump) in all cases. 52 | * The sixth field is used by {{c|fsck}} to determine the order filesystems are integrity checked at boot time. A 0 indicates no check. The root filesystem should have (as here) a 1 to force it to be checked first, and then all other persistent filesystems can have 2 specified (so they are checked together, but after the root filesystem). 53 | 54 | {{Note|We ''don't'' need to mount {{Path|/boot}} here, since this is a UEFI system and our {{Path|/boot}} is simply a regular directory, used as a marshalling ground. Nor do we specify our {{Path|/boot/efi}} mountpoint, since that will be dealt with explicitly by {{c|buildkernel}} (and the UEFI boot sequence), and we'll generally want to be able to remove the USB key once the machine has booted anyway (for security).}} 55 | {{Note|There is no need to place entries for {{Path|/proc}} and {{Path|/dev}} into {{Path|/etc/fstab}}; these will be mounted automatically.}} 56 | 57 | Here are the specific mount options selected above, and their meaning: 58 | 59 | {| class="wikitable" 60 | |- 61 | ! Partition !! Mount Option !! Description 62 | |- 63 | | rowspan=4|{{Highlight|root}} || {{c|defaults}} || Specifies the baseline options: 64 | * {{c|rw}} (mount the filesystem read/write); 65 | * {{c|suid}} (allow set-user-identifier / set-group-identifier [[:Wikipedia:Setuid|bits]] to take effect); 66 | * {{c|dev}} (interpret character or block special [[:Wikipedia:Device_file|device files]] on the filesystem); 67 | * {{c|exec}} (permit execution of binaries); 68 | * {{c|auto}} (automatically mount at boot); 69 | * {{c|nouser}} (forbid non-root users to explicitly mount) and 70 | * {{c|async}} (perform I/O to the filesystem asynchronously). 71 | |- 72 | | {{c|noatime}} || This prevents file access times from being recorded; these are not generally needed, and this setting is particularly important for performance if you use a solid-state drive (SSD).Arch Linux Wiki: [https://wiki.archlinux.org/index.php/Solid_State_Drives#noatime_Mount_Flag "Solid State Drives: noatime Mount Flag"] Incidentially, {{c|noatime}} is a superset of {{c|nodiratime}}.LWN.net: [http://lwn.net/Articles/245002/ "Does noatime imply nodiratime?"] 73 | |- 74 | | {{c|errors{{=}}remount-ro}} || This causes the root system to be remounted read-only if errors are encountered, for safety. 75 | |- 76 | | {{c|discard}} || This allows the TRIM command to work, ''provided that'' you have also allowed this in LUKS via the {{c|root_trim{{=}}yes}} kernel command-line flag (actually passed through to the {{c|init}} script) in {{Path|/etc/buildkernel.conf}}, as described [[../Configuring_and_Building_the_Kernel#enable_trim|earlier]]. TRIM will improve performance on SSDs as they get full,Arch Linux Wiki: [https://wiki.archlinux.org/index.php/Solid_State_Drives#TRIM "Solid State Drives: TRIM"] but make sure you are comfortable with the possible security implications of turning it on. 77 | |- 78 | | rowspan=3|{{Highlight|swap}} || {{c|defaults}} || Sets baseline options as per the root partition, above. Note that you do ''not'' need {{c|sw}} or {{c|swap}} here, although they are commonly seen.SuperUser Forum: [http://superuser.com/questions/337410/what-is-the-difference-between-swap-entries-in-fstab "What is the difference between swap entries in fstab?"] 79 | |- 80 | | {{c|noatime}} || ''See above.'' 81 | |- 82 | | {{c|discard}} || ''See above.'' 83 | |- 84 | | rowspan=3|{{Highlight|home}} || {{c|defaults}} || Sets baseline options as per the root logical volume, above. 85 | |- 86 | | {{c|noatime}} || ''See above.'' 87 | |- 88 | | {{c|discard}} || ''See above.'' 89 | |- 90 | | rowspan=3|{{Highlight|cd-rom}} (optional)|| {{c|noauto}} || Do not attempt to mount automatically at boot. 91 | |- 92 | | {{c|user}} || Allow a non-root user to explicitly mount (desirable for removable media). Note that this implies: 93 | * {{c|noexec}} (prevent execution of binaries on this filesystem); 94 | * {{c|nosuid}} (prevent set-user-identifier / set-group-identifier [[:Wikipedia:Setuid|bits]] from taking effect) and 95 | * {{c|nodev}} (do ''not'' interpret character or block special [[:Wikipedia:Device_file|device files]] on the filesystem). 96 | If any of that bothers you, be sure to override with a subsequent option. 97 | |- 98 | | {{c|ro}} || Mount the filesystem read-only. 99 | |} 100 | 101 | Per the Gentoo [[Systemd#/etc/mtab|wiki article on {{c|systemd}}]], the mounted file systems table ({{Path|/etc/mtab}}) must be a symlink to {{Path|/proc/self/mounts}} (this is now also required for {{c|OpenRC}}Gentoo Linux GitWeb: [https://gitweb.gentoo.org/proj/openrc.git/commit/?id=a6391f44ee6c68d674ae8425983467b971710d5d "mtab: move toward requiring /etc/mtab to be a symbolic link" (commit a6391f44ee6c68d6)]), so issue: 102 | {{RootCmd 103 | |ln -vsf /proc/self/mounts /etc/mtab 104 | |prompt=(chroot) livecd / # 105 | }} 106 | 107 | {{Important|Please ensure you carry out the above step! Your system will not function correctly if you omit it.}} 108 | 109 | == Some Concluding Preparations == 110 | 111 | It will be useful to have the [[:Wikipedia:DHCPD|DHCP daemon]], [[:Wikipedia:Wpa_supplicant|{{c|wpa_supplicant}}]] and [[:Wikipedia:GNU_Screen|{{c|screen}}]] software available immediately upon reboot. They're not yet installed on the {{c|chroot}} operating system, only on the 'outer' host, so let's emerge them now. Issue: 112 | 113 | {{RootCmd 114 | |emerge --ask --verbose net-misc/dhcpcd net-wireless/wpa_supplicant app-misc/screen 115 | |prompt=(chroot) livecd / # 116 | |output=
117 | ... additional output suppressed ...
118 | Would you like to merge these packages? [Yes/No] 
119 | ... additional output suppressed ...
120 |
121 | }} 122 | 123 | Next, take note of your current network interface name - this will be the same after a reboot, and knowing it will be useful during {{c|systemd}}/{{c|OpenRC}} configuration. Issue: 124 | {{RootCmd 125 | |ifconfig 126 | |prompt=(chroot) livecd / # 127 | }} 128 | 129 | and look for a record name similar in format to {{c|enp0s25}} (your system will most likely have a different name - in this particular case it refers to a '''e'''ther'''n'''et card on PCI ('''p''') bus '''0''', '''s'''lot '''25''').freedesktop.org: [http://www.freedesktop.org/wiki/Software/systemd/PredictableNetworkInterfaceNames Predictable Network Interface Names] 130 | 131 | {{Note|If you are using a wireless adapter for the install, your identifier string will start with {{c|wl}}, not {{c|en}}. You will have made a note of the relevant name [[../Setting_Up_Networking_and_Connecting_via_ssh#note_wifi_if_name{{!}}earlier]].}} 132 | 133 | Next, we must set up a root password. Yes, we did indeed set up a root password [[../Creating_and_Booting_the_Minimal-Install_Image_on_USB#first_root_pw_setup|earlier]], but that was for the ''host'' operating system on the target machine, and we are about to discard that and boot directly into the ''new'' (currently {{c|chroot}}-ed) one. As such, we need to set a fresh root password within the {{c|chroot}}. Issue: 134 | {{RootCmd 135 | |passwd root 136 | |prompt=(chroot) livecd / # 137 | |output=
138 | New password: 
139 | Retype new password: 
140 | passwd: password updated successfully
141 |
142 | }} 143 | 144 | {{Important|Be sure to write this password down somewhere safe! You will require it to log in shortly.}} 145 | 146 | Similarly, we need to ensure that the {{c|sshd}} setup inside the {{c|chroot}} will allow {{c|root}} to log-in (while we complete our set-up, at any rate). Issue: 147 | {{RootCmd 148 | |sed -i 's/^#PermitRootLogin.*$/PermitRootLogin yes/' /etc/ssh/sshd_config 149 | |prompt=(chroot) livecd / # 150 | }} 151 | {{Note|As you may recall (from when we edited the outer host's {{Path|/etc/ssh/sshd_config}} file [[../Setting_Up_Networking_and_Connecting_via_ssh#setup_ssh_server{{!}}earlier]]), from release 7.0 of {{c|OpenSSH}}, the defaults have changed to prohibit password-based login as {{c|root}}, hence the reason for the above edit.OpenSSH Unix Announce: [http://lists.mindrot.org/pipermail/openssh-unix-announce/2015-August/000122.html OpenSSH 7.0 released]}} 152 | 153 | We also need to make sure that the {{Package|app-editors/nano}} editor does not accidentally get removed later in the installation (as it is only 'held in place' by a virtual — {{Package|virtual/editor}} — at the moment). Issue: 154 | {{RootCmd 155 | |emerge --noreplace app-editors/nano 156 | |prompt=(chroot) livecd / # 157 | }} 158 | {{Note|The --noreplace option ensures that the package is not rebuilt if already installed. In any case, it will be added to the @world set ({{Path|/var/lib/portage/world}}). It's a useful idiom to be aware of.}} 159 | 160 | === Configure Networking for Post-Reboot Use (OpenRC Users Only) === 161 | 162 | {{Note|If you selected {{c|systemd}} [[../Building_the_Gentoo_Base_System_Minus_Kernel#choose_systemd_or_openrc{{!}}earlier]] as your target init system (the default now being {{c|OpenRC}} in this guide), you should [[#exit_chroot_and_restart{{!}}click here]] to skip this section: the instructions contained herein are {{c|OpenRC}}-specific.}} 163 | 164 | To make sure you have your network interface available after restart, be sure to add {{Package|net-misc/dhcpcd}} to the default runlevel. Issue: 165 | 166 | {{RootCmd 167 | |rc-update add dhcpcd default 168 | |prompt=(chroot) livecd / # 169 | }} 170 | 171 | {{Note|We will disable this service later, when {{Package|net-misc/networkmanager}} takes over (with GNOME). However, we leave it enabled-on-boot for now for convenience.}} 172 | 173 | You should also ensure that the {{c|sshd}} service will automatically start on boot, so you can log in remotely; issue: 174 | {{RootCmd 175 | |rc-update add sshd default 176 | |prompt=(chroot) livecd / # 177 | }} 178 | {{Warning|As currently configured, {{c|sshd}} allows some rather insecure things, such as remote log-in as root. While this is useful at the moment (and relatively benign given the machine is on a subnet, presumably behind a firewall), do consider editing the {{Path|/etc/ssh/sshd_config}} file once all configuration is complete, to disallow this. You should also consider [http://www.thegeekstuff.com/2008/11/3-steps-to-perform-ssh-login-without-password-using-ssh-keygen-ssh-copy-id/ moving to public key authentication] for {{c|ssh}} login, once everything else is in place (at the end of the install).}} 179 | 180 | Next, if you are performing this install over '''WiFi''', we need to ensure that {{c|wpa_supplicant}} can be started by {{c|dhcpcd}}ArchLinux Wiki: [https://wiki.archlinux.org/index.php/Dhcpcd#10-wpa_supplicant "dhcpcd: Hooks: 10-wpa_supplicant"] (NB: if using '''wired Ethernet''' for the install, you should [[#networking_all_done|'''skip''']] these commands). Issue: 181 | {{RootCmd 182 | |mv -v /etc/wpa.conf /etc/wpa_supplicant/wpa_supplicant.conf 183 | |prompt=localhost ~ # 184 | }} 185 | {{Note|The {{Path|/etc/wpa.conf}} file was created [[../Building_the_Gentoo_Base_System_Minus_Kernel#copy_wpa_conf{{!}}earlier]].}} 186 | Now, we also need to prepend one line to that configuration file, so that {{c|dhcpcd}} can invoke {{c|wpa_supplicant}} directly. Issue: 187 | {{RootCmd 188 | |nano -w /etc/wpa_supplicant/wpa_supplicant.conf 189 | |prompt=(chroot) livecd / # 190 | }} 191 | and ''prepend'' the following line to the file: 192 | {{FileBox|filename=/etc/wpa_supplicant/wpa_supplicant.conf|title=Prepend the following line, to allow dhcpcd invocation|1= 193 | ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=wheel 194 | }} 195 | Leave the rest of the file as-is. Save, and exit {{c|nano}}. 196 | 197 | Also, as of version 6.10.0 of {{Package|net-misc/dhcpcd}}, you need to ensure that the appropriate 'hook' script is in place to start and stop {{Package|net-wireless/wpa_supplicant}} on each wireless interface.Gentoo News: [https://www.gentoo.org/support/news-items/2016-01-08-some-dhcpcd-hooks-are-now-examples.html "Some dhcpcd hooks are now examples"] So, to ensure that you have this file in place, issue: 198 | {{RootCmd 199 | |if ! [ -s /lib/dhcpcd/dhcpcd-hooks/10-wpa_supplicant ]; then cp -vf /usr/share/dhcpcd/hooks/10-wpa_supplicant /lib/dhcpcd/dhcpcd-hooks/; fi 200 | |prompt=(chroot) livecd / # 201 | }} 202 | 203 | {{Note|This is a deliberately minimal setup, as we'll only use it until {{Package|net-misc/networkmanager}} takes over (with GNOME); for more information on the {{c|ctrl_interface}} option, and others you may wish to set, see [https://wiki.archlinux.org/index.php/WPA_supplicant#Advanced_usage these notes].}} 204 | 205 | Assuming you want to use [[:Wikipedia:Dynamic_Host_Configuration_Protocol|DHCP]] on your interface (wired or wireless), that's all you need to do: ''pace'' the [[Handbook:AMD64/Installation/System#Configuring_the_network{{!}}Gentoo Handbook]], there's no need to add {{Path|/etc/init.d/net.}} symbolic links, edit {{Path|/etc/conf.d/net}} etc.Gentoo Wiki: [[Network_management_using_DHCPCD#Migration_from_Gentoo_net..2A_scripts|"Network management using DHCPCD": Migration from Gentoo net.* scripts]] 206 | 207 | However, if you have more complex networking requirements (static IP, proxies etc.) ''should'' consult the relevant section of the [[Handbook:AMD64/Installation/System#Configuring_the_network|Handbook]]. Also, if you have more complex WiFi configuration requirements, you may also find [[Handbook:AMD64/Networking/Wireless|these notes]] useful. 208 | 209 | == Cleanly Dismounting the {{c|chroot}} and Restarting == 210 | 211 | Almost there! Now we have to exit the {{c|chroot}} in both our {{c|screen}} virtual consoles, quit both of those consoles (thereby exiting {{c|screen}}), unmount the various logical volumes, deactivate the LVM volume group, and close out the LUKS partition. Issue: 212 | 213 | {{RootCmd 214 | |exit 215 | |prompt=(chroot) livecd / # 216 | }} 217 | then: 218 | {{RootCmd 219 | |exit 220 | |prompt=livecd ~ # 221 | }} 222 | The first {{c|exit}} exits the {{c|chroot}} in the first {{c|screen}} virtual console, the second exits that console itself. Now do the same for the second virtual console (which you'll automatically be dropped out to): 223 | {{RootCmd 224 | |exit 225 | |prompt=(chroot:2) livecd / # 226 | }} 227 | then: 228 | {{RootCmd 229 | |exit 230 | |prompt=livecd ~ # 231 | |output=
232 | [screen is terminating]
233 |
234 | }} 235 | 236 | Unmount everything (and turn off swap), deactivate LVM, and close LUKS: 237 | {{RootCmd 238 | |sync 239 | |swapoff -v /dev/mapper/vg1-swap 240 | |umount -lv /mnt/gentoo/home 241 | |umount -lv /mnt/gentoo/dev{/shm,/pts,} 242 | |umount -Rv /mnt/gentoo 243 | |vgchange --available n 244 | |cryptsetup luksClose gentoo 245 | |prompt=livecd ~ # 246 | }} 247 | 248 | {{Note|In the unlikely event you are unable to execute the vgchange --available n command, perhaps due to some components reported as being still mounted from within the LVM logical volume, simply proceed with the following {{c|reboot}} anyway. Your system should still be in a consistent state due to the {{c|sync}} command. For avoidance of doubt, this point will ''not'' affect most users, who should find their system dismounts cleanly.}} 249 | 250 | Now we're ready to restart. Ensure your boot USB key is still inserted into the target machine (as well as the minimal install USB key, at this point), and issue: 251 | {{RootCmd 252 | |reboot 253 | |prompt=livecd ~ # 254 | }} 255 | 256 | {{Note|If you have been using your system in ''legacy'' (non-UEFI) boot mode up to this point — and, for avoidance of doubt, this '''won't''' apply to the majority of users, who should therfore simply ignore this note — then you will need to ''remove'' the boot USB key after rebooting; then, as your system starts to come back up, enter into your system's BIOS, enable UEFI mode (''without'' secure boot enabled) and restart once more.}} 257 | 258 | Your {{c|ssh}} session will exit. If all is well, shortly after this your target machine will restart, and, because {{c|buildkernel}} [[../Configuring_and_Building_the_Kernel#add_to_boot_list|automatically placed]] 259 | your new, EFI-stub kernel at the top of the boot list, it should then proceed — without any further intervention required — to boot this kernel off of the boot USB key. 260 | 261 | == Logging in Directly to the New System == 262 | 263 | After some initialization, you should then be prompted for a passphrase to unlock the {{c|gpg}} keyfile for your LUKS partition (this is the passphrase you set up [[../Preparing_the_LUKS-LVM_Filesystem_and_Boot_USB_Key#create_gpg_luks_keyfile|earlier]]). Type this in (directly at the target machine keyboard), and press {{Key|Enter}}. 264 | 265 | Shortly after this, assuming that your passphrase is correct, you'll be presented with a login prompt. Enter 'root' as the user (again, directly at the keyboard, without quotes), press {{Key|Enter}}, and then type the root password you set up [[#setup_new_root_password|above]], and press {{Key|Enter}} again. 266 | 267 | {{Note|On certain versions of {{c|systemd}}, you may be notified that the {{c|plymouth-start.service}} unit failed during boot. As we have not yet enabled {{c|plymouth}} using {{c|buildkernel}}, this is to be expected, and the error may be ignored at this point.
For avoidance of doubt, this (minor) issue does not impact {{c|OpenRC}} users.}} 268 | 269 | With luck, you should now be logged in! If this is the case, congratulations, you have a encrypted system which boots from UEFI and uses (depending on your choice [[../Building_the_Gentoo_Base_System_Minus_Kernel#choose_systemd_or_openrc|earlier]]) {{c|OpenRC}} or {{c|systemd}}. You should now '''remove the minimal install USB key''', so that only the boot USB key (the smaller capacity one) remains inserted, then [[#next_steps|click here]] to complete the configuration of your init system (and other) settings. 270 | 271 | {{Note|If you ''were'' able to successfully boot, then please note that the minimal install image USB key is no longer required for the remaining steps in this tutorial — as such, you may, at your option, either keep it around for 'fallback recovery' purposes (in case anything should go wrong later — the process for command-line recovery is detailed [[#if_things_go_wrong|below]]), or, reformat it for other use.}} 272 | 273 | If however, for some reason you ''weren't'' able to boot, then read on. 274 | 275 | == How to Recover if Things Go Wrong == 276 | 277 | {{Note|If you managed to reboot your new system and log in successfully, then you should [[#next_steps{{!}}skip this step]], it is only necessary for those attempting to recover back to a {{c|chroot}} system after a failed boot.}} 278 | 279 | The following are short-form instructions to get you back into a {{c|chroot}} environment again, so that you can attempt to fix whatever problem prevented you from booting under UEFI. I have included backlinks throughout, so you can hop up to where these steps were first taken, and read in more detail about what is involved - the style of what follows is rather telegraphic. 280 | 281 | First, re-insert your minimal install USB key into the target machine (leaving the boot USB key inserted as well, since we'll need it to unlock the LUKS partition), and restart the system. As the machine comes up, re-enter the BIOS, and set (if it is not already) the (minimal install) USB key to be the top UEFI boot device (original instructions [[../Creating_and_Booting_the_Minimal-Install_Image_on_USB#set_mii_boot|here]]). Save the BIOS settings and exit, thereby rebooting into the Gentoo minimal install system (original instructions [[../Creating_and_Booting_the_Minimal-Install_Image_on_USB#boot_beep|here]]). As before, hit {{Key|Enter}} at the GRUB screen, remember to select the correct keymap etc. Then, since the boot image itself has no persistence, issue (directly on the target machine's keyboard): 282 | {{RootCmd 283 | |passwd root 284 | |prompt=livecd ~ # 285 | |output=
286 | New password: 
287 | Retype new password: 
288 | passwd: password updated successfully
289 |
290 | }} 291 | Remember (original instructions [[../Creating_and_Booting_the_Minimal-Install_Image_on_USB#first_root_pw_setup|here]]), you are setting up a password for the 'outer', host system here — root's password ''inside'' the {{c|chroot}} will be retained (and different), but we haven't remounted the {{c|chroot}} yet. 292 | 293 | Next, ensure that your networking is up. Follow the appropriate instructions below. 294 | 295 | If installing over '''wired Ethernet''', simply wait for a little while (if necessary for address allocation to complete), and then note your IP address, using {{c|ifconfig}} (original instructions [[../Setting_Up_Networking_and_Connecting_via_ssh#get_ip_address|here]]): 296 | {{RootCmd 297 | |ifconfig 298 | |prompt=livecd ~ # 299 | }} 300 | Then [[#restart_sshd|click here]] to skip to the next step. 301 | If, instead, you are installing over '''WiFi''', you need to re-create your configuration file (original instructions [[../Setting_Up_Networking_and_Connecting_via_ssh#connecting_via_wifi|here]]). Issue: 302 | {{RootCmd 303 | |wpa_passphrase "ESSID" > /etc/wpa.conf 304 | |prompt=livecd ~ # 305 | |output= 306 | 
307 | 
308 |
309 | }} 310 | {{Note|As before, substitute the correct name for "ESSID" in the above.}} 311 | Lock down the file's access permissions (to root only) and check that its contents look sane. Issue: 312 | {{RootCmd 313 | |chmod -v 600 /etc/wpa.conf 314 | |cat /etc/wpa.conf 315 | |prompt=livecd ~ # 316 | }} 317 | Assuming that looks OK, we can connect. Issue: 318 | {{RootCmd 319 | |wpa_supplicant -Dnl80211,wext -iwlp2s0 -c/etc/wpa.conf -B 320 | |prompt=livecd ~ # 321 | }} 322 | {{Note|Substitute the wireless network interface name you wrote down [[../Setting_Up_Networking_and_Connecting_via_ssh#note_wifi_if_name{{!}}previously]] for wlp2s0 in the above command.}} 323 | Then note your IP address: 324 | {{RootCmd 325 | |ifconfig wlp2s0 326 | |prompt=livecd ~ # 327 | }} 328 | {{Note|Again, substitute the wireless network interface name you wrote down [[../Setting_Up_Networking_and_Connecting_via_ssh#note_wifi_if_name{{!}}previously]] for wlp2s0 in the above command.}} 329 | 330 | {{Note|As before, if you need to use a fixed IP address, a proxy, IPv6, or an unencrypted WiFi connecction, please see [[Handbook:AMD64/Installation/Networking|Chapter 3]] of the Gentoo handbook for more details. 331 | }} 332 | Now start {{c|sshd}} (original instructions [[../Setting_Up_Networking_and_Connecting_via_ssh#setup_ssh_server|here]]): 333 | {{RootCmd 334 | |sed -i 's/^#PermitRootLogin.*$/PermitRootLogin yes/' /etc/ssh/sshd_config 335 | |/etc/init.d/sshd start 336 | |prompt=livecd ~ # 337 | }} 338 | 339 | This will generate a new set of keys, so take a note of the RSA and ED25519 fingerprints for the host key, as shown with: 340 | {{RootCmd 341 | |ssh-keygen -l -f /etc/ssh/ssh_host_rsa_key.pub 342 | |ssh-keygen -l -f /etc/ssh/ssh_host_ed25519_key.pub 343 | |prompt=livecd ~ # 344 | }} 345 | Now switch to your helper PC. Note that, if the target PC's IP address is the same as it was originally (quite likely, even with [[:Wikipedia:Dynamic_Host_Configuration_Protocol|DHCP]]), then the helper will already have a note of its previous fingerprint, and will refuse to connect via {{c|ssh}} (since a mismatched fingerprint might suggest a [[:Wikipedia:Man-in-the-middle_attack|man-in-the-middle attack]]). Therefore, we need to remove the old fingerprint record for the IP from {{Path|~/.ssh/known_hosts}}. Issue: 346 | {{Cmd 347 | |sed -i '/^[^[:digit:]]*192.168.1.106[^[:digit:]]/d' ~/.ssh/known_hosts 348 | |prompt=user@pc2 $}} 349 | {{Note|Substitute whatever IP address you got back from {{c|ifconfig}} for 192.168.1.106 in the above command.}} 350 | 351 | and issue (original instructions [[../Setting_Up_Networking_and_Connecting_via_ssh#log_in_via_helper|here]]): 352 | {{Cmd 353 | |ssh root@192.168.1.106 354 | |prompt=user@pc2 $}} 355 | Check the key fingerprint and then, if it matches, continue as below: 356 | {{GenericCmd|
357 | ... additional output suppressed ...
358 | Are you sure you want to continue connecting (yes/no)? 
359 | ... additional output suppressed ...
360 | Password: 
361 | ... additional output suppressed ...
362 |
363 | }} 364 | {{Note|Substitute whatever IP address you got back from {{c|ifconfig}} for 192.168.1.106 in the above command.}} 365 | Once you are connected, we need to get {{c|screen}} running. Via the {{c|ssh}} connection on the helper PC (which is how you should enter all subsequent commands, unless otherwise specified), issue (original instructions [[../Setting_Up_Networking_and_Connecting_via_ssh#start_screen|here]]): 366 | {{RootCmd 367 | |screen 368 | |prompt=livecd ~ # 369 | }} 370 | 371 | Next, we must mount the USB boot key's EFI system partition, so that we can use the keyfile on it to unlock the LUKS partition. Find out the device file name for the EFI partition on the USB boot key, by issuing (original instructions [[../Preparing_the_LUKS-LVM_Filesystem_and_Boot_USB_Key#determine_efi_dev|here]]): 372 | {{RootCmd 373 | |lsblk 374 | |prompt=livecd ~ # 375 | }} 376 | We will refer to this as {{Path|/dev/sdY1}} in what follows, but of course on your machine it will be something like {{Path|/dev/sdb1}} or {{Path|/dev/sdc1}} (note that the initial {{Path|/dev/}} prefix is not shown in the {{c|lsblk}} output). 377 | 378 | Next, create a temporary mountpoint, and mount it. Issue (original instructions [[../Preparing_the_LUKS-LVM_Filesystem_and_Boot_USB_Key#temp_mount_efi|here]]): 379 | {{RootCmd 380 | |mkdir -v /tmp/efiboot 381 | |mount -v -t vfat /dev/sdY1 /tmp/efiboot 382 | |prompt=livecd ~ # 383 | }} 384 | {{Note|Replace {{Path|/dev/sdY1}} in the above command with the path of first partition on the USB key, which you just located with {{c|lsblk}}, such as {{Path|/dev/sdb1}} or {{Path|/dev/sdc1}}.}} 385 | 386 | Now, we can open the [[:Wikipedia:Linux_Unified_Key_Setup|LUKS]] volume. You'll need the passphrase (for the {{c|gpg}} keyfile) you [[../Preparing_the_LUKS-LVM_Filesystem_and_Boot_USB_Key#create_gpg_luks_keyfile|set up earlier]] to do this: 387 | {{RootCmd 388 | |export GPG_TTY{{=}}$(tty) 389 | |gpg --decrypt /tmp/efiboot/luks-key.gpg {{!}} cryptsetup --key-file - luksOpen /dev/sdZn gentoo 390 | |prompt=livecd ~ # 391 | |output=
392 | Enter passphrase
393 | 
394 | ... additional output suppressed ...
395 |
396 | }} 397 | {{Note|Replace {{Path|/dev/sdZn}} in the above command with the device path for the LUKS partition, e.g., {{Path|/dev/sda7}}. You can check this with {{c|lsblk}} (original instructions [[../Preparing_the_LUKS-LVM_Filesystem_and_Boot_USB_Key#find_luks_partition|here]]).
Also, you ''may'' see some errors of the form device-mapper: remove ioctl on XXX failed: Device or resource busy; these can generally be ignored.}} 398 | {{Note|You may get complaints about no LC_CTYPE known printed by {{c|pinentry}}; these can generally be ignored. See explanation in the [[../Preparing_the_LUKS-LVM_Filesystem_and_Boot_USB_Key#lc_ctype_problem|original text]].}} 399 | {{Tip|Remember that if {{c|gpg}} gets stuck with a bad password in its cache for some reason, you can reset it by issuing: 400 | {{RootCmd 401 | |echo RELOADAGENT {{!}} gpg-connect-agent 402 | |prompt=livecd ~ # 403 | }}}} 404 | 405 | Now we can bring up the [[:Wikipedia:Logical_Volume_Manager_(Linux)|LVM]] logical volumes, and mount them. Issue (original instructions [[../Preparing_the_LUKS-LVM_Filesystem_and_Boot_USB_Key#activate_lvm|here]]): 406 | {{RootCmd 407 | |vgchange --available y 408 | |swapon -v /dev/mapper/vg1-swap 409 | |mount -v -t ext4 /dev/mapper/vg1-root /mnt/gentoo 410 | |mount -v -t ext4 /dev/mapper/vg1-home /mnt/gentoo/home 411 | |prompt=livecd ~ # 412 | }} 413 | 414 | Next, unmount the USB boot key; issue (original instructions [[../Preparing_the_LUKS-LVM_Filesystem_and_Boot_USB_Key#unmount_efi|here]]): 415 | {{RootCmd 416 | |umount -v /tmp/efiboot 417 | |prompt=livecd ~ # 418 | }} 419 | 420 | Ensure the date and time is set correctly. Issue: 421 | {{RootCmd 422 | |date 423 | |prompt=livecd ~ # 424 | }} 425 | 426 | If necessary fix it by issuing (original instructions [[../Creating_and_Booting_the_Minimal-Install_Image_on_USB#set_date_time|here]]): 427 | {{RootCmd 428 | |date MMDDhhmmYYYY 429 | |prompt=livecd ~ # 430 | }} 431 | {{Note|Substitute MMDDhhmmYYYY in the above with the correct date/time string. For example, to set the UTC date/time to 5:12pm on February 9th 2017, you would issue 432 | {{RootCmd 433 | |date 020917122017 434 | |prompt=livecd ~ # 435 | }} 436 | }} 437 | Next, make sure that the [[:Wikipedia:Domain_Name_System|DNS]] information will still be valid after we {{c|chroot}}. Issue (original instructions [[../Building_the_Gentoo_Base_System_Minus_Kernel#copy_dns_info|here]]): 438 | {{RootCmd 439 | |cp -L /etc/resolv.conf /mnt/gentoo/etc/ 440 | |prompt=livecd ~ # 441 | |output=
442 | cp: overwrite '/mnt/gentoo/etc/resolv.conf'? 
443 |
444 | }} 445 | 446 | Now, ensure that the various special files in {{Path|/proc}}, {{Path|/sys}} and {{Path|/dev}} are available after a {{c|chroot}}. Issue (original instructions [[../Building_the_Gentoo_Base_System_Minus_Kernel#setup_bind_mounts|here]]): 447 | {{RootCmd 448 | |mount -v -t proc none /mnt/gentoo/proc 449 | |mount -v --rbind /sys /mnt/gentoo/sys 450 | |mount -v --rbind /dev /mnt/gentoo/dev 451 | |mount -v --make-rslave /mnt/gentoo/sys 452 | |mount -v --make-rslave /mnt/gentoo/dev 453 | |prompt=livecd ~ # 454 | }} 455 | 456 | Now we can actually enter the {{c|chroot}}. Issue (original instructions [[../Building_the_Gentoo_Base_System_Minus_Kernel#enter_chroot|here]]): 457 | {{RootCmd 458 | |chroot /mnt/gentoo /bin/bash 459 | |prompt=livecd ~ # 460 | }} 461 | Remember to source our profile correctly and set a prompt hint. Issue (original instructions [[../Building_the_Gentoo_Base_System_Minus_Kernel#chroot_prompt|here]]): 462 | {{RootCmd 463 | |source /etc/profile 464 | |export PS1{{=}}"(chroot) $PS1" 465 | |prompt=livecd / # 466 | }} 467 | Finally, we can setup a second virtual console inside {{c|screen}} (just as we did [[../Building_the_Gentoo_Base_System_Minus_Kernel#second_virtual_console|before]]), which will be useful to e.g., monitor the status of long {{c|emerge}}s. Press {{Key|Ctrl}}{{Key|a}} then {{Key|c}} to start a new console. Then in that new console (which is back outside the {{c|chroot}}, to begin with) enter: 468 | {{RootCmd 469 | |chroot /mnt/gentoo /bin/bash 470 | |prompt=livecd ~ # 471 | }} 472 | followed by 473 | {{RootCmd 474 | |source /etc/profile 475 | |export PS1{{=}}"(chroot:2) $PS1" 476 | |prompt=livecd / # 477 | }} 478 | 479 | Now hit {{Key|Ctrl}}{{Key|a}} then {{Key|p}} to get back to the original console. 480 | 481 | That's it! You can now proceed to edit your {{c|chroot}}-ed system (and hopefully, to fix it). It is impossible to be specific as to what may have caused a problem, but some likely candidates include: 482 | * '''Incorrect kernel configuration.''' In this case, run buildkernel --ask --verbose, enter the graphical kernel configuration editor when prompted, change the appropriate kernel settings, and then save and exit the editor. The build will continue with your modified configuration. (A problem of this sort is most likely to occur if you have ''already'' started to dabble with the configuration, since the standard flow in this tutorial assumes you have used the {{Path|/proc/config.gz}} config from the running minimal install system kernel - which is therefore to some extent 'known good' - as a basis). 483 | ** In particular, if you elected to use {{c|OpenRC}} boot [[../Building_the_Gentoo_Base_System_Minus_Kernel#choose_systemd_or_openrc|earlier]] (and not the default {{c|systemd}}), and received an error similar to The filesystem /dev/mapper/vg1-root <...> does not contain a valid init=<...>/systemd after entering your LUKS passphrase, then you have not correctly set up the INITSYSTEM variable in {{Path|/etc/buildkernel.conf}}. Fix this (either by editing {{Path|/etc/buildkernel.conf}} or using buildkernel --easy-setup and choosing option "{{c|7) set init system}}", then run buildkernel --ask --verbose again. 484 | * '''Buggy version of {{c|buildkernel}}.''' Please note that {{c|buildkernel}} version 1.0.24 has a bug that affects booting and should not be used (earlier and later versions are not affected). Issue buildkernel --version to check, and if you ''do'' have the affected 1.0.24 version installed, update it (using emaint sync --repo sakaki-tools && emerge -av --update buildkernel), then rebuild your kernel and reboot. 485 | * '''Missing packages.''' For example, you may have forgotten to install e.g., {{Package|net-misc/dhcpcd}} prior to reboot, preventing you from accessing the network properly. If this is the case, simply {{c|emerge}} the [[#emerge_additionals|required software]] within the chroot, and then try again. There is no need to re-run {{c|buildkernel}} in this case. 486 | * '''Password not set for root.''' If for any reason you forgot to set a root password for the new system (as instructed [[#setup_new_root_password|above]], when you were {{c|chroot}}-ed in originally), then your attempt to log in will have been rejected. This is easily fixed by using passwd root. 487 | * '''Wrong keymapping causing mangled passwords.''' If the system would not accept your {{c|gpg}} keyfile passphrase on reboot, but you were able to successfully unlock it when re-entering the {{c|chroot}} above, or, if the system would not accept your root password after a restart, then you may have not setup the KEYMAP variable in {{Path|/etc/buildkernel.conf}} correctly. See [[../Configuring_and_Building_the_Kernel#important_conf_vars|this earlier discussion]] for further details. (These issues can also generally be ameliorated (for most locales) through the use of only standard English letters in your passphrases, as mentioned [[../Preparing_the_LUKS-LVM_Filesystem_and_Boot_USB_Key#correct_horse_battery_staple|previously]].) Review, and if necessary, change your boot-time keymap by using buildkernel --easy-setup, and then re-run buildkernel --ask --verbose. 488 | * '''Problems with UUIDs.''' The {{c|buildkernel}} script tries to ensure that the UUIDs you have passed it (in {{Path|/etc/genkernel.conf}} [[../Configuring_and_Building_the_Kernel#important_conf_vars|above]]) are valid, but it is still possible to make a mistake (e.g. if you have more than one LUKS partition on your system, for example). Double check these values, and, if necessary, change them (by using buildkernel --easy-setup) and then re-run buildkernel --ask --verbose. 489 | * '''BIOS configuration problems.''' A total failure of your new system to even try to start (or if you get Windows instead!) is likely to indicate some issue with your BIOS settings. Are you sure your USB '''boot''' key is at the top of the UEFI boot order (as it should be, if {{c|buildkernel}} has [[../Configuring_and_Building_the_Kernel#add_to_boot_list|done its job]])? And that secure boot is disabled at this point, and that fast boot is off? Double check these points, then try again — for hints about entering and modifying the UEFI BIOS settings, please refer to [[../Creating_and_Booting_the_Minimal-Install_Image_on_USB#boot_minimal_install_iso|these earlier notes]]. (You should also double-check that the first (and only) partition on your USB boot key is marked as an EFI system partition and is formatted {{c|fat32}}; see [[../Preparing_the_LUKS-LVM_Filesystem_and_Boot_USB_Key#setup_system_partition|this discussion]].) A very few EFI systems also do not look for a boot executable under the standard {{Path|/EFI/Boot/bootx64.efi}} path, but instead will use {{Path|/EFI/Microsoft/Boot/bootmgfw.efi}}.Smith, Roderick W. [http://www.rodsbooks.com/refind/installing.html#naming "The rEFInd Boot Manager: Installing rEFInd: Alternative Naming Options"] If that's the case for your target machine, change the EFI boot file path using buildkernel --easy-setup, then re-run buildkernel --ask --verbose. 490 | 491 | {{Note|If you try to fix things that involve using the graphical kernel configuration editor, and you are connected over {{c|ssh}} from your helper machine, be aware that you may get some pretty strange characters displayed. This can happen if your helper's locale is not present on the target (in the host operating system that is, not the {{c|chroot}}, since {{c|sshd}} is running in the former context).ServerFault Q&A Site: [http://serverfault.com/questions/304469/setting-locale-failed-force-certain-locale-when-connecting-through-ssh "Setting locale failed: force certain locale when connecting through ssh"] In this case, simply open up a chroot directly at the target's keyboard, and perform the {{c|buildkernel}} from there; i.e., directly at the machine, issue: 492 | {{RootCmd 493 | |chroot /mnt/gentoo /bin/bash 494 | |prompt=livecd ~ # 495 | }} 496 | followed by: 497 | {{RootCmd 498 | |source /etc/profile 499 | |export PS1{{=}}"(chroot:direct) $PS1" 500 | |prompt=livecd / # 501 | }} 502 | and then: 503 | {{RootCmd 504 | |buildkernel --ask --verbose 505 | |prompt=(chroot:direct) livecd / # 506 | }} 507 | }} 508 | 509 | Once you have made your changes and are ready to have another go at rebooting, simply proceed from the section [[#exit_chroot_and_restart|"Cleanly Dismounting the {{c|chroot}} and Restarting"]] in the main text. Good luck! 510 | 511 | == Next Steps (and Fork in the Road) == 512 | 513 | Now that you have successfully booted into Gentoo from UEFI, we can proceed to configure your system. At this point, you need to follow one of two tracks for the final set of chapters (10-14), depending on your [[../Building_the_Gentoo_Base_System_Minus_Kernel#choose_systemd_or_openrc|earlier choice of init system]]: 514 | * users targeting '''{{c|OpenRC}}''' (the default) should [[../Completing_OpenRC_Configuration_and_Installing_Necessary_Tools|click here]] to go to the next chapter on the regular track, "Completing {{c|OpenRC}} Configuration and Installing Necessary Tools"; whereas 515 | * users targeting '''{{c|systemd}}''' should instead [[../Configuring_systemd_and_Installing_Necessary_Tools|click here]] to go to the next chapter on the alternative track, "Configuring {{c|systemd}} and Installing Necessary Tools". 516 | 517 | 518 | == Notes == 519 | {{reflist}} 520 | 521 | {| class="wikitable" style="margin: 1em auto 1em auto;" 522 | |- 523 | | rowspan=2|[[../Configuring_and_Building_the_Kernel|< Previous]] 524 | | rowspan=2|[[../|Home]] 525 | | [[../Completing_OpenRC_Configuration_and_Installing_Necessary_Tools|Next ({{c|OpenRC}}) >]] 526 | |- 527 | | [[../Configuring_systemd_and_Installing_Necessary_Tools|Next ({{c|systemd}}) >]] 528 | |} 529 | 530 | [[Category:Sakaki's EFI Install Guide]] 531 | 532 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # efi-install-guide-source 2 | The ([MediaWiki](https://mediawiki.org)) source pages for "Sakaki's EFI Install Guide" (as hosted on the Gentoo wiki, [here](https://wiki.gentoo.org/wiki/Sakaki's_EFI_Install_Guide)). 3 | 4 | These pages _can_ be accessed individually via the Gentoo site, but they are gathered here in one place for convenience (and as a backup). 5 | 6 | If you want to update the pages manually to the most recent version, enter the directory and run: 7 | ```console 8 | ./download_pages.sh pages.txt 9 | ``` 10 | 11 | A weekly cronjob runs this (included) `download_pages.sh` script, and uploads any changes here automatically. 12 | 13 | All source pages are licensed (per the Gentoo wiki standards), under [CC-BY-SA-3.0](https://creativecommons.org/licenses/by-sa/3.0/). 14 | 15 | Currently, images used in the pages are not archived in this repository. 16 | -------------------------------------------------------------------------------- /download_pages.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | # 3 | # A trivial script to download the source for a list of wiki pages 4 | # from the Gentoo wiki, and save them in the specified files. 5 | # 6 | # Takes one argument, the filename of the page source file. This file 7 | # should contain one line per file to download. Each line should have 8 | # the page name from the wiki, followed by a space, followed by the 9 | # filename to save to. 10 | # 11 | # So you could run e.g. 12 | # ./download_pages.sh pages.txt 13 | # when in the repo directory, to manually update the pages. Once you 14 | # have done this, a "git diff" will show you what has changed. 15 | # 16 | # The script will remove unnecessary HTML from the fetched page, such 17 | # that if the resulting content were to be pasted back into the 'edit' 18 | # field on the Gentoo wiki for that page, no change would be detected. 19 | # 20 | # The Gentoo wiki could change at any time leaving the scraping 21 | # process used by this script invalid, so do not use it for any 22 | # critical production purpose! 23 | # 24 | # Copyright (c) 2018 sakaki 25 | # 26 | # License (GPL v3.0) 27 | # ------------------ 28 | # 29 | # This program is free software: you can redistribute it and/or modify 30 | # it under the terms of the GNU General Public License as published by 31 | # the Free Software Foundation, either version 3 of the License, or 32 | # (at your option) any later version. 33 | # 34 | # This program is distributed in the hope that it will be useful, 35 | # but WITHOUT ANY WARRANTY; without even the implied warranty of 36 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 37 | # GNU General Public License for more details. 38 | # 39 | # You should have received a copy of the GNU General Public License 40 | # along with this program. If not, see . 41 | # 42 | 43 | set -e 44 | set -u 45 | 46 | BASE_URL="https://wiki.gentoo.org/index.php?title=" 47 | URL_ACTION="&action=edit" 48 | 49 | while read -r LN; do 50 | # TODO - would be better not to use space as the separator! 51 | SUB_URL="$(cut <<<${LN} -d' ' -f1)" 52 | TO_FILENAME="$(cut <<<${LN} -d' ' -f2)" 53 | echo -n "${TO_FILENAME} ... " 54 | rm -f "${TO_FILENAME}" 55 | DATA="$(wget -q -O - "${BASE_URL}${SUB_URL}${URL_ACTION}")" 56 | # convert '<' chars 57 | DATA="${DATA//</<}" 58 | # convert '&' chars 59 | DATA="${DATA//&/&}" 60 | # drop trailing content from close of textarea 61 | DATA="${DATA%% "${TO_FILENAME}" 67 | echo "OK" 68 | done < "$1" 69 | 70 | -------------------------------------------------------------------------------- /m01_Extending_LUKS_to_Protect_an_Additional_Drive: -------------------------------------------------------------------------------- 1 | 2 | 3 | In this mini-guide, we'll show how to easily extend your LUKS protection to cover an additional drive (or drives) on your system. This is most useful with desktop machines, where you may have multiple hard drives installed. 4 | 5 | {{Note|If you simply wish to protect a removable drive (such as a USB key), it's easier to rely on the tools already in GNOME; you can use the {{c|Disks}} utility to format your drive with encryption (see [https://help.ubuntu.com/community/EncryptedFilesystemsOnRemovableStorage this guide], for example), and then have it unlocked automatically (assuming you are logged in) on insertion (to do so, just opt to allow GNOME to remember your passphrase for the drive, when first prompted).}} 6 | 7 | == Prerequisites == 8 | 9 | To carry this out, you will need: 10 | * to have an operational {{c|systemd}}/{{c|EFI}} {{c|Gentoo}} system, which you have set up per the text of the main guide (you don't need to have installed GNOME, however); and 11 | * a secondary drive (or partition) that you would like to protect with LUKS, and have automatically mounted on boot. 12 | 13 | == Preparing systemd == 14 | 15 | First, we'll need to ensure that {{c|systemd}} has the {{c|cryptsetup}} USE flag enabled (which it does not, by default); this turns on the unit generator for {{Path|/etc/crypttab}}, which we'll need. Open a terminal, get {{c|root}}, then issue: 16 | 17 | {{RootCmd 18 | |nano -w /etc/portage/package.use 19 | }} 20 | and append the following line: 21 | {{FileBox|filename=/etc/portage/package.use|title=Append this line to enable the crypttab unit generator|lang=bash|1= 22 | sys-apps/systemd cryptsetup 23 | }} 24 | Save and exit {{c|nano}}; then, rebuild {{c|systemd}}: 25 | {{RootCmd 26 | |emerge --ask --verbose --oneshot sys-apps/systemd 27 | |output=
 28 | ... additional output suppressed ...
 29 | Would you like to merge these packages? [Yes/No] 
 30 | ... additional output suppressed ...
 31 |
32 | }} 33 | 34 | == Preparing your New Drive == 35 | 36 | In the below, I'm going to assume you want to use [[../Preparing_the_LUKS-LVM_Filesystem_and_Boot_USB_Key#format_luks_partition|same cryptography settings]] as those recommended for the main system, earlier in the tutorial (obviously, adapt as appropriate). I will refer to the drive as {{Path|/dev/sdN}}; substitute your actual device path as appropriate ({{Path|/dev/sdc}}, {{Path|/dev/sdd}} etc.). Also, if you wish to encrypt only one partition within the drive, use the relevant value instead (e.g., {{Path|/dev/sdc1}}, {{Path|/dev/sdd1}} etc.) You can use the Disks utility in GNOME, or the {{c|lsblk}} command line utility, to find your device's path. 37 | 38 | First, we will create a keyfile, and place this in the {{c|root}} user's home directory, within the (already LUKS-protected) {{c|root}} partition. Issue: 39 | {{RootCmd 40 | |touch /root/crypt1.key 41 | |chmod 400 /root/crypt1.key 42 | |dd if{{=}}/dev/urandom of{{=}}/root/crypt1.key bs{{=}}512 count{{=}}1 43 | }} 44 | to create the key, and make it (read) accessible by the {{c|root}} user only. 45 | 46 | {{Note|We do '''not''' {{c|gpg}}-encrypt this keyfile, as we need it to be unlocked automatically. The key 'lives' in a LUKS-protected location already, so this is safe to do.}} 47 | 48 | Now, LUKS-format your new drive: 49 | {{Warning|This will '''destroy''' any existing data on the drive! Make sure you have the device path correct before proceeding.}} 50 | {{RootCmd 51 | |cryptsetup --cipher serpent-xts-plain64 --key-size 512 --hash whirlpool --key-file /root/crypt1.key luksFormat /dev/sdN 52 | |output=
 53 | 
 54 | WARNING!
 55 | ========
 56 | This will overwrite data on /dev/sdN irrevocably.
 57 | 
 58 | Are you sure? (Type uppercase yes): 
 59 |
60 | }} 61 | {{Note|Replace {{Path|/dev/sdN}} in the above command (and where used subsequently) with that of your new drive, or, if appropriate, the partition within it (e.g., {{Path|/dev/sdc}}, {{Path|/dev/sdd}} etc. for a drive; {{Path|/dev/sdc1}}, {{Path|/dev/sdd1}} etc. for a partition).}} 62 | 63 | Next, open the encrypted device, using the keyfile: 64 | {{RootCmd 65 | |cryptsetup luksOpen --key-file /root/crypt1.key /dev/sdN crypt1 66 | }} 67 | 68 | If that succeeded, the new device will be visible under {{Path|/dev/mapper}} (as {{Path|/dev/mapper/crypt1}}). 69 | 70 | Next, create a filesystem on your unlocked drive. 71 | 72 | {{Note|You can simply create an {{c|ext4}} or similar filesystem if you like; however, to illustrate the most complex (normal) case, in this example we're going to create an {{c|LVM}} setup, with (arbitrarily) two logical volumes {{c|foo}} and {{c|bar}} on top of {{Path|/dev/mapper/crypt1}}, each of 10GiB (and each of which will later be formatted {{c|ext4}}). Obviously, adapt the number of logical volumes, their sizes, and their names to your own requirements.}} 73 | 74 | Issue: 75 | {{RootCmd 76 | |pvcreate /dev/mapper/crypt1 77 | |vgcreate cr1 /dev/mapper/crypt1 78 | |lvcreate --size 10G --name foo cr1 79 | |lvcreate --size 10G --name bar cr1 80 | |vgchange --activate y cr1 81 | }} 82 | to create the physical volume (PV), volume group {{c|cr1}} (VG) and the {{c|foo}} and {{c|bar}} logical volumes (LVs). 83 | 84 | The LVs will be visible (in this case) as {{Path|/dev/mapper/cr1-foo}} and {{Path|/dev/mapper/cr1-bar}}. They may be treated as any other device - so let's do that now, and format them (adapt to your own requirements): 85 | {{RootCmd 86 | |mkfs.ext4 -m 0 -L "test" /dev/mapper/cr1-foo 87 | |mkfs.ext4 -m 0 -L "test" /dev/mapper/cr1-bar 88 | }} 89 | 90 | Close the drive again: 91 | {{RootCmd 92 | |cryptsetup luksClose crypt1 93 | }} 94 | 95 | Finally, find the UUID of the new LUKS disk (or partition); issue: 96 | {{RootCmd 97 | |blkid /dev/sdN 98 | |output=
 99 | /dev/sdN: UUID="45f1f1af-025b-4395-8a33-7ef0a4709329" TYPE="crypto_LUKS"
100 |
101 | }} 102 | Your output will differ from the above. Note down the UUID. 103 | {{Note|If you have your new LUKS set up on a partition, rather than a whole drive, ''ignore'' the PARTUUID, and note the UUID only.}} 104 | 105 | == Configuring /etc/crypttab and /etc/fstab == 106 | 107 | Next, we need to set up the file {{Path|/etc/crypttab}}. This file is processed by {{c|systemd}} ''before'' {{Path|/etc/fstab}} is read, and tells the system which cryptographically protected volumes it should unlock at boot. 108 | {{Note|For more information about the format of {{Path|/etc/crypttab}}, see man crypttab.}} 109 | 110 | Issue: 111 | {{RootCmd 112 | |nano -w /etc/crypttab 113 | }} 114 | 115 | and add the following text to the file (subsituting the UUID you just noted down for the one I have used, obviously): 116 | {{FileBox|filename=/etc/crypttab|title=Specifying a LUKS volume to automatically unlock at boot|1= 117 | crypt1 UUID=45f1f1af-025b-4395-8a33-7ef0a4709329 /root/crypt1.key luks 118 | }} 119 | Save and exit {{c|nano}}. 120 | 121 | That's it for the encryption side of things; with this in place, {{c|systemd}} will automatically unlock the LUKS container, call it {{Path|/dev/mapper/crypt1}}, and then activate any logical volumes within it, and make these available via the device mapper too. This will be done ''before'' {{Path|/etc/fstab}} is processed, so you are now free to cite these LVs within your {{Path|/etc/fstab}}. 122 | 123 | For example, let's suppose we wanted to mount the {{c|foo}} LV at {{Path|/mnt/foo}}, and {{c|bar}} at {{Path|/home/bar}} (these are just examples, obviously, adapt to your own requirements). 124 | 125 | We need to create mountpoints, as they don't exist yet, so issue: 126 | {{RootCmd 127 | |mkdir -pv /mnt/foo /home/bar 128 | }} 129 | 130 | Then add the entries to {{Path|/etc/fstab}} to have them mounted. Issue: 131 | {{RootCmd 132 | |nano -w /etc/fstab 133 | }} 134 | 135 | and then ''append'' (for our example, adapt to your own requirements): 136 | {{FileBox|filename=/etc/fstab|title=Append, to specify mountpoints for our newly created LVs|1= 137 | /dev/mapper/cr1-foo /mnt/foo ext4 defaults 0 2 138 | /dev/mapper/cr1-bar /home/bar ext4 defaults 0 2 139 | }} 140 | Save and exit {{c|nano}}. 141 | {{Note|For more information about the format of {{Path|/etc/fstab}}, see man fstab.}} 142 | 143 | That's it! Next time you reboot, you should have access to your new protected LVs! 144 | 145 | To rejoin the main guide, click [[../Using_Your_New_Gentoo_System#additional_mini_guides|here ({{c|systemd}})]] or [[../Using_Your_New_Gentoo_System_under_OpenRC#additional_mini_guides|here ({{c|OpenRC}})]]. 146 | 147 | -------------------------------------------------------------------------------- /m02_Disabling_the_Intel_Management_Engine: -------------------------------------------------------------------------------- 1 | 2 | 3 | The [[:Wikipedia:Intel_Active_Management_Technology|Intel Management Engine]] ('IME' or 'ME') is an '''out-of-band co-processor''' integrated in all post-2006 Intel-CPU-based PCs. It has '''full network and memory access and runs proprietary, signed, closed-source software at ring -3''',Skochinsky, Igor. [http://me.bios.io/images/c/ca/Rootkit_in_your_laptop.pdf ''Rootkit in your Laptop'']. Breakpoint 2012Skochinsky, Igor. [https://recon.cx/2014/slides/Recon%202014%20Skochinsky.pdf ''Intel ME Secrets'']. Recon 2014Positive Technologies [https://www.troopers.de/downloads/troopers17/TR17_ME11_Static.pdf ''Intel ME: The Way of the Static Analysis'']. TROOPERS17Ermolov, Alexander. [https://2016.zeronights.ru/wp-content/uploads/2017/03/Intel-BootGuard.pdf ''Safeguarding rootkits: Intel BootGuard'']. ZERONIGHTS 2016 independently of the BIOS, main CPU and platform operating systemlibreboot FAQ: [https://libreboot.org/faq.html#intelme "Intel Management Engine"]Purism Inc. Blog: [https://puri.sm/learn/intel-me/ "Intel's Management Engine"] — a fact which many regard as an unacceptable security risk (particularly given that at least one remotely exploitable security hole has already been reportedDemerjian, Charlie. [https://semiaccurate.com/2017/05/01/remote-security-exploit-2008-intel-platforms/ "Remote security exploit in all 2008+ Intel platforms "]The Register: [https://www.theregister.co.uk/2017/05/01/intel_amt_me_vulnerability/ "Red alert! Intel patches remote execution hole that's been hidden in chips since 2010"]The Register: [https://www.theregister.co.uk/2017/11/20/intel_flags_firmware_flaws/ "Intel Finds Critical Holes in Secret Management Engine Hidden in Tons of Desktop, Server Chipsets"]). 4 | 5 | In this mini-guide, I'll run through the process of '''disabling''' the IME on your target PC.For avoidance of doubt, in this guide 'disabled' has the same meaning as 'neutralized and disabled' in the Purism Inc. Blog: [https://puri.sm/posts/deep-dive-into-intel-me-disablement/ "Deep Dive into Intel Management Engine Disablement"] To do so, we will use Nicola Corna's [https://github.com/corna/me_cleaner {{c|me_cleaner}}]. This software operates on the firmware stored in your PC's BIOS chip (where the bulk of the ME's code resides), and does two things: 6 | * sets the 'High Assurance Program' bit, an ME 'kill switch' that the US government reportedlyPT Security Blog [http://blog.ptsecurity.com/2017/08/disabling-intel-me.html#more "Disabling Intel ME 11 via undocumented mode"] had incorporated for PCs used in sensitive applicationsCorna, Nicola, ''me_cleaner wiki'', [https://github.com/corna/me_cleaner/wiki/HAP-AltMeDisable-bit "HAP AltMeDisable bit"]The HAP bit is available for ME version 11 (Skylake) and following. Earlier versions include a similar-function {{c|AltMeDisable}} bit (discovered by Igor Skochinsky) which {{c|me_cleaner}} will automatically set instead, where appropriate; however, this {{c|AltMeDisable}} bit is technically unassociated with the High Assurance Program ''per se''.; 7 | * removes the vast majority of the ME's software modules (including network stack, RTOS and Java VM), leaving only the essential 'bring up' components (the latter being necessary because, on modern systems, if the IME fails to initialize, either the machine startup will be completely halted at that point, or startup will ''appear'' to complete, only for a watchdog timer to reset the whole PC 30 minutes laterBenchoff, Brian. [https://hackaday.com/2016/11/28/neutralizing-intels-management-engine/ "Neutralizing Intel's Management Engine"]). 8 | 9 | This combined 'belt-and-braces' approach means that the ME ''ought'' to cleanly enter a self-induced null state (after resetting the 30-minute watchdog timer) but, should that not work, it will nevertheless enter a failed state shortly thereafter (as the majority of its core software modules have been purged). 10 | 11 | {{Note|You may wonder how this can work at all, given that the ME's code is signed. The reason (fortunately for us) is that the ME's software is deployed as ''individually signed modules'' that are signature checked only when loaded — and they are lazy loaded.Corna, Nicola, ''me_cleaner wiki'', [https://github.com/corna/me_cleaner/wiki/How-does-it-work%3F "How does it work?"] The very first module, {{c|BUP}} (or 'Bring UP'), contains the watchdog timer reset, and is left alone by {{c|me_cleaner}}. Once {{c|BUP}} has completed, the ME will either enter a 'parked' state (if the HAP/AltMeDisable bit is respected), or try to load the remaining RTOS modules (if not). In the former case, the ME is cleanly disabled. In the latter case, the signature check fails and the ME effectively crashes. Either way, it is out of action from that point.}} 12 | 13 | {{Warning|The process involved will require re-flashing your system's BIOS-chip firmware image, and will almost certainly void your system warranty. It may result in your machine becoming 'bricked'. On some (though not many) PCs, the ME is used to initialize or manage certain system peripherals and/or provide silicon workarounds — if that is the case on your target machine, you may lose functionality by disabling it.
Remember: disabling the IME is a completely optional step: proceed entirely at your own risk.}} 14 | 15 | The process we will be following is as follows: 16 | * ensuring you have the necessary components available; 17 | * locating (and identifying) the BIOS flash chip on your target PC; 18 | * setting up a Raspberry Pi 3 Model B (or B+) ('RPi3') or Pi 4 Model B ('RPi4') as an in-system flash programmer; 19 | * reading the original firmware from the BIOS flash chip (and validating this), using the RPi3/4; 20 | * creating a modified copy of this firmware using {{c|me_cleaner}}; 21 | * writing the modified copy of the firmware back to your PC's BIOS flash chip, again using the RPi3/4; 22 | * restarting your PC, and verifying that the IME has been disabled. 23 | 24 | Although some systems ''do'' allow the full contents of the BIOS flash chip to be reprogrammed using software tools only (so called [https://github.com/corna/me_cleaner/wiki/Internal-flashing-with-OEM-firmware 'internal flashing']), on most PCs this facility is either completely unavailable, ''or'' can only write to the unprotected areas of the flash filesystem (''excluding'' the ME area), ''or'' will only write vendor-signed images. Accordingly, we will describe the approach of using 'external' flashing in this guide, as that is the most reliable. 25 | 26 | {{Warning|Although the most reliable method, external flashing ''does'' require you to open the case of your PC, an action that by itself is likely to void the warranty on non-desktop systems. Always observe [https://www.computerhope.com/esd.htm proper ESD protective measures] when working with exposed system boards, and ensure that you have all external power sources and batteries removed. Backup any important files before proceeding. Read all instructions carefully and proceed only if you are comfortable, and at your own risk.}} 27 | 28 | If you are ready, let's go! 29 | 30 | == Prerequisites == 31 | 32 | To proceed, you will require the following: 33 | 34 | * an Intel-CPU-based target PC — that does ''not'' have [https://github.com/corna/me_cleaner/wiki/Intel-Boot-Guard Boot Guard] enabled — on which you wish to disable the IME; 35 | ** the target PC may be running an OEM BIOS (such as AMI, Dell etc.), or [https://www.coreboot.org/ coreboot]; 36 | * a [[Raspberry_Pi|Raspberry Pi 3 Model B or B+, or Pi 4 Model B]] single board computer ('RPi3' or 'RPi4'), for use as an external flash programmer; 37 | * a spare >= 8GB microSD card (to hold the 64-bit Gentoo O/S image we will use for the RPi3/4); 38 | * an appropriate IC clip for your target PC's flash chip, e.g.: 39 | ** a Pomona 5250 for SOIC-8 chips; 40 | ** a Pomona 5208 for unsocketed DIP-8 chips, or 41 | ** a Pomona 5252 for SOIC-16 chips; 42 | * 8 female-female connector wires (to attach the appropriate clip to the RPi3/4's GPIO header); 43 | * a maintenance manual for your target PC, where available, to assist in safe disassembly / reassembly; and 44 | ** whatever tools are stipulated in the above. 45 | 46 | {{Note|AMD-CPU-based systems do not have the IME of course, but ''do'' have a broadly equivalent subsystem, the platform security processor (or 'PSP'),libreboot FAQ: [https://libreboot.org/faq.html#amd-platform-security-processor-psp "AMD Platform Security Processor (PSP)"] for which there is no equivalent workaround at the time of writing.}} 47 | {{Note|Intel systems that have Boot Guard enabled ''cannot'' be fully 'cleansed' — this technology stores a public verification key for the vendor's (signed) firmware images in one-time-programmable fuses in the CPU, and utilises the ME to verify these. It was introduced in the 4th generation (Haswell) architecture. By definition, Boot Guard ''cannot'' be active on systems where the motherboard and CPU are purchased separately, and at the time of writing only a minority of laptop systems have it active. Note however that you should be able to use {{c|me_cleaner}}'s -s/--soft-disable-only option ''even if'' Boot Guard is in use on your system.}} 48 | {{Note|Note that there are many other [[:Wikipedia:Single-board_computer|SBCs]] that may be used for in-system flash reprogramming, for example the BeagleBone. You can also use the RPi3/4 in 32-bit mode, and it is also possible to use earlier versions of the RPi. However, for the sake of concreteness, I will assume you are using the specified (RPi3 or RPi4) system in what follows.}} 49 | {{Note|Other brands of IC clip are available, but Pomona is arguably the best known, and their model numbers often quoted by 'compatibles'. If you are unsure which type you need, see the [[#locate_chip{{!}}next step]].}} 50 | {{Note|Desktop users whose motherboard contains a ''socketed'' DIP-8 chip, may use a [https://wiki.analog.com/university/courses/electronics/electronics-lab-breadboards solderless breadboard] to hold the flash chip while programming. In such a case, use female-male connecting wires, or use break-away male headers on the breadboard, and connect the female-female wires from the RPi3/4 to those.}} 51 | 52 | In the text, I will run through the process of reflashing the BIOS-chip firmware on a specific machine, namely the long-suffering '''Panasonic CF-AX3 Ultrabook''' used in the main body of this guide. This has a SOIC-8 BIOS flash chip, so we will be using a Pomona 5250 clip. Of course, you should adapt the following instructions to match your specific setup, flash chip type etc. 53 | 54 | == Locating (and Identifying) the Target PC's BIOS Flash Chip == 55 | 56 | To begin — always observing [https://www.computerhope.com/esd.htm good ESD practices], and following the instructions given in your target system's maintenance manual — ''disconnect'' any external power sources and removable batteries, and then expose your target PC's motherboard. 57 | 58 | For desktop machines, gaining access to the motherboard is generally easy, but for laptops the disassembly process is often quite fiddly. However, the Panasonic CF-AX3 is refreshingly straightforward in this regard — after removing the main battery and removing 19 small screws on the bottom-side, the rear panel of the laptop lifts off easily. With this done, a second (internal) li-ion battery must be disconnected, after which the mainboard is ready for inspection. Obviously, the approach required for your system will be different. 59 | 60 | {{Tip|In addition to your manufacturer's maintenance manual, you can also often find useful disassembly videos by searching on YouTube.}} 61 | {{Note|It is ''not'' generally necessary to remove the small CMOS button battery found on most boards, in order to reprogram the BIOS flash, but your system may differ. Be aware that if you ''do'' remove this battery, things like the BIOS password will probably be erased, if you set one earlier ([[../Configuring_Secure_Boot#set_bios_pw{{!}}{{c|systemd}} track]], [[../Configuring_Secure_Boot_under_OpenRC#set_bios_pw{{!}}{{c|OpenRC}} track)]].}} 62 | 63 | Once you have your target PC's motherboard exposed, locate its BIOS flash chip. On many machines, the BIOS chip will be marked with a sticker or paint dot. Laptops will generally have 8-pin or 16-pin [[:Wikipedia:Small_Outline_Integrated_Circuit|SOIC]] packages;on desktop machines, 8-pin socketed (and unsocketed) [[:Wikipedia:Dual_in-line_package|DIP]] packages are also common. 64 | 65 | {{Note|If your BIOS flash chip is in a [[:Wikipedia:Plastic_leaded_chip_carrier|PLCC]] or [[:Wikipedia:List_of_integrated_circuit_packaging_types#Small_outline_packages|WSON]] package, you will need specialized equipment to connect to the chip, the process for which is not currently covered in this guide.}} 66 | 67 | The CF-AX3 has a SOIC-8 flash IC, as shown: 68 | 69 | [[File:Flash_chip_location2.jpg|thumb|none|600px|Location of the SOIC-8 Flash Chip on a Panasonic CF-AX3 Laptop; Pin 1 on Bottom Left]] 70 | 71 | Once you have located the BIOS flash chip, with the help of a magnifying glass (good apps for this are available for IOS and Android phones) or digital camera, read off the maker's name and model number from the device. Then, use a search engine to locate the device's datasheet. 72 | 73 | For example, as the above photo shows, the CF-AX3 has a Winbond W25Q64FV IC; its datasheet may be found [http://www.winbond.com/resource-files/w25q64fv%20revs%2007182017.pdf here]. This part uses a very commonly seen pinout, as follows (note how the pins are numbered counter-clockwise): 74 | 75 | [[File:Flash_8_pinout.png|thumb|none|386px|Pinout of a Typical SOIC-8 / DIP-8 BIOS Flash Chip]] 76 | 77 | {{Warning|You must '''always''' check the pinout and voltage requirements of your particular device, and adapt the connections on the IC clip accordingly. While a large number of 8-pin devices use the layout shown above, not all do.}} 78 | 79 | Note that on DIP packages, the top of the chip will generally be marked by a semicircular indent; on SOIC packages, a small circle or indent will mark pin 1 (NB, do not confuse this with any paint blobs the manufacturer may have used to highlight the flash chip, as for example with the blue paint blob used on the CF-AX3.) 80 | 81 | Write down the pinout for your device, if it differs from that shown in the above diagram. 82 | 83 | {{Note|While, following common usage, this guide talks about the 'BIOS chip' and 'reflashing the BIOS firmware' etc., it is important to understand that the BIOS code proper is only ''one'' component of the firmware stored on the flash chip. It would be more accurate to talk about it as the 'system firmware flash memory' or similar, containing multiple regions (for the BIOS, IME, Gigabit Ethernet etc.) each of which can contain multiple modules. For more details, please see e.g., John Butterworth's [http://opensecuritytraining.info/IntroBIOS.html "Introduction to BIOS & SMM" slidesets].}} 84 | 85 | == Setting up the RPi3/4 as an External Flash Programmer == 86 | 87 | Next, we will set up a Raspberry Pi 3 Model B / B+ ('RPi3') or Pi 4 Model B ('RPi4') single board computer as an external flash programmer, running 64-bit Gentoo Linux as its operating system. For convenience we will use a pre-built image. 88 | 89 | === Software Configuration === 90 | 91 | Download, write and boot the Gentoo image provided [https://github.com/sakaki-/gentoo-on-rpi-64bit here] on your RPi3/4 (following the instructions given on that page). 92 | 93 | {{Tip|It is a good idea to write the Gentoo image to a different (spare) microSD card from your main Raspbian system; that way, you can easily revert to using Raspbian when done.}} 94 | {{Note|It is of course possible to carry out the flashing procedure described in this chapter using other RPi OSes; however, for concreteness (and since it has all the necessary components available) I will assume you ''are'' using the specified [https://github.com/sakaki-/gentoo-on-rpi-64bit gentoo-on-rpi-64bit] image, in what follows.}} 95 | 96 | The image starts up directly into an Xfce4 desktop, pre-logged in as the {{c|demouser}} account. When the boot has completed, open a terminal window on (or {{c|ssh}} in to) the RPi3/4 and become root: 97 | 98 | {{Cmd 99 | |sudo su --login root 100 | |prompt=demouser@pi64 ~ $ 101 | }} 102 | 103 | If you have not modified the default image settings, no password will be required for this step. 104 | 105 | Next, note that if you are using version >=1.2.0 of the {{c|gentoo-on-rpi3-64bit}} image, ''all'' the required software now comes pre-installed for convenience, so you can [[#setup_rpi3_hardware|skip directly to the "Hardware Configuration" section]] now. Otherwise, keep reading. 106 | 107 | Then, modify the {{Path|/boot/config.txt}} file so that the [[:Wikipedia:Serial_Peripheral_Interface_Bus|SPI interface]] (used to communicate with the flash chip) is available via the RPi's GPIO pins. As root, issue: 108 | 109 | {{RootCmd 110 | |nano -w /boot/config.txt 111 | |prompt=pi64 ~ # 112 | }} 113 | 114 | and modify that file, ''uncommenting'' the following line (if not already done): 115 | 116 | {{FileBox|filename=/boot/config.txt|title=Enable the SPI interface on your RPi|lang=ini|1= 117 | dtparam=spi=on 118 | }} 119 | Leave the rest of the file as-is. Save, and exit {{c|nano}}. 120 | 121 | {{Tip|If you are using the official 7" touchscreen with your RPi3/4, you can also add lcd_rotate{{=}}2 to {{Path|/boot/config.txt}}, to efficiently rotate the display (and touch region) to match the default orientation of the case. For avoidance of doubt, if you are using a monitor or {{c|ssh}} connection you should ''not'' add this stanza, however.}} 122 | 123 | Next, fetch up-to-date copies of the [https://github.com/sakaki-/sakaki-tools {{c|sakaki-tools}}] and [https://github.com/sakaki-/genpi64-overlay {{c|genpi64}}] ebuild repositories ('overlays') on the RPi3/4. Ensure your RPi has a valid network connection (you can easily setup a WiFi or Ethernet connection via the bundled {{c|NetworkManager}} applet, just click on the network icon in the status bar), then issue: 124 | {{RootCmd 125 | |emaint sync --repo sakaki-tools 126 | |emaint sync --repo genpi64 127 | |prompt=pi64 ~ # 128 | }} 129 | 130 | {{Note|If you have time, it is better to do a ''full'' software update of your RPi3/4 before proceeding (the process requires about 2 hours). To do this, ''instead'' of the above two commands, ensure your RPi has network connectivity, then issue:{{RootCmd 131 | |genup 132 | |prompt=pi64 ~ # 133 | }}and wait for this to finish with the message All done - your system is now up-to-date!, before proceeding.}} 134 | 135 | Next, we need to install the {{Package|sys-apps/flashrom}} software, which will allow us to read and write the flash chip over the SPI interface. Issue: 136 | 137 | {{RootCmd 138 | |emerge --ask --verbose sys-apps/flashrom 139 | |prompt=pi64 ~ # 140 | |output=
141 | ... additional output suppressed ...
142 | Would you like to merge these packages? [Yes/No] 
143 | ... additional output suppressed ...
144 |
}} 145 | 146 | Because it will fetch and then check the [https://github.com/sakaki-/gentoo-on-rpi-64bit#binhost binhost] packages metadata file, this command may take 3-4 minutes before prompting you whether to proceed, so please be patient. The actual package itself is available as a binary and will install quickly (with no local compilation required), once confirmed. 147 | 148 | {{Note|If you are ''not'' using the [https://github.com/sakaki-/gentoo-on-rpi-64bit specified 64-bit Gentoo image] on your RPi3/4, please note that the {{c|atapromise}} USE flag needs to be disabled on {{c|arm64}} (on the image, this is done via a [https://github.com/sakaki-/gentoo-on-rpi-64bit#profile custom profile]).}} 149 | 150 | Then, we need to emerge the {{c|coreboot-utils}} package, which provides {{c|ifdtool}} (a utility to parse and modify the structure of Intel firmware flash dumps). The package has an ebuild in the [https://github.com/sakaki-/sakaki-tools {{c|sakaki-tools}}] repository (aka 'overlay') used on the image, so issue: 151 | {{RootCmd 152 | |emerge --ask --verbose sys-apps/coreboot-utils 153 | |prompt=pi64 ~ # 154 | |output=
155 | ... additional output suppressed ...
156 | Would you like to merge these packages? [Yes/No] 
157 | ... additional output suppressed ...
158 |
}} 159 | 160 | {{Note|If you are ''not'' using the [https://github.com/sakaki-/gentoo-on-rpi-64bit specified 64-bit Gentoo image], follow the instructions given [https://github.com/corna/me_cleaner/wiki/How-to-apply-me_cleaner here] to clone and build the software directly.}} 161 | {{Note|For avoidance of doubt, we are ''not'' going to be overwriting your BIOS with [https://coreboot.org/ coreboot], we just need access to some of its bundled tools. As mentioned [[#prerequisites|earlier]], it is fine to use a target PC with an OEM BIOS (such as AMI, Dell etc.).
And, of course, if you ''are'' running coreboot, that's fine too ^-^}} 162 | 163 | The next step is to install Nicola Corna's {{c|me_cleaner}} software itself. This also has an ebuild in the [https://github.com/sakaki-/sakaki-tools {{c|sakaki-tools}}] repo, so issue: 164 | 165 | {{RootCmd 166 | |emerge --ask --verbose sys-apps/me_cleaner 167 | |prompt=pi64 ~ # 168 | |output=
169 | ... additional output suppressed ...
170 | Would you like to merge these packages? [Yes/No] 
171 | ... additional output suppressed ...
172 |
}} 173 | 174 | {{Note|If you are ''not'' using the [https://github.com/sakaki-/gentoo-on-rpi-64bit specified 64-bit Gentoo image], follow the instructions given [https://github.com/corna/me_cleaner/wiki/How-to-apply-me_cleaner here] to clone the software directly.}} 175 | 176 | {{c|me_cleaner}} is a reasonably straightforward Python script. Nevertheless, it is good hygiene to review scripts prior to running them (particularly when they impact such security-critical areas as the IME and BIOS), so do so now. Issue: 177 | 178 | {{RootCmd 179 | |less /usr/lib/python-exec/python3.6/me_cleaner 180 | |prompt=pi64 ~ # 181 | }} 182 | 183 | Use {{Key|Page Down}} and {{Key|Page Up}} to navigate within the file, and press {{Key|q}} to quit, when done. 184 | 185 | Lastly, we'll pull in the {{c|pigpio}} library (and accompanying {{c|pigs}} utility and {{c|pigpiod}} server), which will be used to set the GPIO pins on the header not directly controlled by {{c|flashrom}}). This has an ebuild in the [https://github.com/sakaki-/genpi64-overlay {{c|genpi64}}] repo used on the image, so issue: 186 | 187 | {{RootCmd 188 | |emerge --ask --verbose dev-libs/pigpio 189 | |prompt=pi64 ~ # 190 | |output=
191 | ... additional output suppressed ...
192 | Would you like to merge these packages? [Yes/No] 
193 | ... additional output suppressed ...
194 |
}} 195 | 196 | {{Note|If you are ''not'' using the [https://github.com/sakaki-/gentoo-on-rpi-64bit specified 64-bit Gentoo image], you can find links to the underlying source for {{c|pigpio}} [https://github.com/joan2937/pigpio here].}} 197 | 198 | {{Note|This tutorial originally used the {{c|wiringpi}} package for GPIO access, but as this has since been deprecated by its author,Henderson, Gordon, ''wiringPi Blog'', [http://wiringpi.com/wiringpi-deprecated/ "wiringPi – deprecated…"] I have switched to using {{c|pigpio}} instead.}} 199 | 200 | Once installed, start the {{c|pigpiod}} daemon, and ensure that this is automatically started each boot; issue: 201 | 202 | {{RootCmd 203 | |rc-service pigpiod start 204 | |rc-update add pigpiod default 205 | |prompt=pi64 ~ # 206 | }} 207 | 208 | === Hardware Configuration === 209 | 210 | With the necessary software prepared, we can proceed to attach the appropriate IC clip to the RPi's GPIO (general purpose input-output) header. 211 | 212 | Cleanly shutdown your RPi3/4: 213 | {{RootCmd 214 | |poweroff 215 | |prompt=pi64 ~ # 216 | }} 217 | 218 | Physically remove the RPi3/4's power connector once the shutdown sequence has completed. 219 | 220 | With your RPi powered off, locate its 40-pin GPIO header, and connect one end of each of the 8 female-female cables to the appropriate RPi GPIO pin as shown in (the inner, light green section of) the diagram below: 221 | 222 | {{Tip|This header mapping will also work for the Raspberry Pi 1 model B+ or later.}} 223 | 224 | [[File:Rpi_gpio_header_ic_flash.png|thumb|none|500px|Pin mapping from RPi3/4 GPIO Header to Typical 8-Pin Flash Chip]] 225 | 226 | Here is a photo showing these connections in place on an actual RPi3 (in an official 7" touchscreen enclosure; this is of course not necessary in order to use the board). Disregard the wires on the left-hand side, they are for the touchscreen. With the RPi oriented as it is in this picture, pin 1 is at the extreme left position on the nearer row, and pin 40 at the extreme right position on the farther row. The colours of the jumper wires used match those in the above [[#pin_mapping|pin mapping]] and [[#flash_8_pinout|flash chip pinout]]. 227 | 228 | [[File:Rpi3_wiring2.jpg|thumb|none|600px|An RPi3 with GPIO/SPI Connected for Flash Programming to a Pomona 5250 IC Clip (Click to Zoom)]] 229 | 230 | {{Warning|Be '''very careful''' not to connect pins 2 or 4 on the RPi's GPIO header to any pin of the IC clip - these are 5v (rather then 3.3v) and are likely to '''destroy''' your flash chip should you accidentally use them.}} 231 | 232 | The other end of the 8 wires you should connect to an appropriate IC test clip, per the outer (lilac) section of the [[#pin_mapping|above pin mapping diagram]]. The photo above shows a 5250 clip attached (as is appropriate for the SOIC-8 flash chip in the Panasonic CF-AX3); obviously, adapt as required. The important thing is to look at your flash IC's pin names / functions (as given by its datasheet), and ensure that these are connected to the appropriate header wire from the RPi3/4. For example, with the Winbond W25Q64FV chip in a SOIC-8 package, as here, we have: 233 | 234 | {| class="wikitable" 235 | |- 236 | ! IC Pin !! IC Name !! Wire Colour !! RPi3/4 Pin !! RPi3/4 Name !! Function 237 | |- 238 | | 1 || /CS || White || 24 || SPI_CE0_N || Chip select; drive low to enable device 239 | |- 240 | | 2 || DO || Grey || 21 || SPI_MISO || Standard SPI data output (from chip) 241 | |- 242 | | 3 || /WP || Blue || 16 || GPIO23 / GPIO_GEN4 || Write protect; drive high to enable status registers to be written 243 | |- 244 | | 4 || GND || Black || 25 || Ground || Ground 245 | |- 246 | | 5 || DI || Orange || 19 || SPI_MOSI || Standard SPI data input (to chip) 247 | |- 248 | | 6 || CLK || Yellow || 23 || SPI_CLK || SPI clock 249 | |- 250 | | 7 || /HOLD || Green || 18 || GPIO24 / GPI_GEN5 || Hold; drive low to pause device while actively selected 251 | |- 252 | | 8 || VCC || Red || 17 || 3.3v || Power supply (NB do ''not'' use 5v) 253 | |} 254 | {{Note|The '/' in front of some IC signal names implies that their logic is ''inverted''. So, for example, with {{c|/WP}} ("write protect"), we must drive the line ''low'' to write-protect the status registers on the flash chip, and high to write-enable them.}} 255 | 256 | With the test clip connected, hardware setup of your RPi as a in-circuit flash programmer is complete. 257 | 258 | == Reading and Verifying the Original Contents of your BIOS Flash Chip == 259 | 260 | Power the RPi back up, wait for Gentoo to boot, and then and open a terminal window (or, at your option, log in over {{c|ssh}}). As before, become root: 261 | 262 | {{Cmd 263 | |sudo su --login root 264 | |prompt=demouser@pi64 ~ $ 265 | }} 266 | 267 | Then, as root, ensure that {{c|/WP}} and {{c|/HOLD}} are both pulled high. Issue: 268 | 269 | {{RootCmd 270 | |pigs pud 23 u 271 | |pigs pud 24 u 272 | |prompt=pi64 ~ # 273 | }} 274 | 275 | These commands (using the {{c|pigs}} client from {{c|pigpio}}) activates the RPi3/4's internal pull-up resistors on {{c|GPIO23}} (RPi pin 16 → {{c|/WP}}) and {{c|GPIO24}} (RPi pin 18 → {{c|/HOLD}}) respectively. 276 | {{Note|These two lines are ''not'' part of the SPI interface managed by {{c|flashrom}}, so we must explicitly set them to appropriate values, as here.}} 277 | 278 | {{Note|If (and only if) these {{c|pigs}} commands ''fail'' with an error message (rather than returning silently), ensure you have an up-to-date version of {{c|pigpio}} installed, and have the {{c|pigpiod}} daemon running, by issing:{{RootCmd 279 | |emaint sync --repo genpi64 280 | |emerge --verbose dev-libs/pigpio 281 | |rc-service pigpiod start 282 | |rc-update add pigpiod default 283 | |prompt=pi64 ~ # 284 | }}Then retry the above {{c|pigs}} commands once done.
For avoidance of doubt, most users should ''not'' have to issue the commands in this note.}} 285 | 286 | Next, observing proper [https://www.computerhope.com/esd.htm proper ESD precautions] (and after double-checking that you have all external power supplies and batteries removed), '''attach the IC clip to your target PC's BIOS flash chip'''. 287 | 288 | For example, the photo below shows the same RPi3 as shown [[#wiring_photo|earlier]] attached to the BIOS chip of the CF-AX3 laptop, using a Pomona 5250 test clip: 289 | 290 | [[File:Flash_reprogramming2.jpg|thumb|none|600px|Using an RPi3 for In-Circuit BIOS Chip Reflashing of a CF-AX3 (Click to Zoom)]] 291 | 292 | {{Note|The wire colours used are the same as in the rest of this guide (but other than consistency, there is nothing 'magic' about them ^-^).
Pin 1 is on the bottom left of the flash chip in the above (and corresponds to the white wire on the Pomona 5250 IC clip).}} 293 | 294 | With the clip attached, request that {{c|flashrom}} 'probe' to see if it can identify your BIOS flash chip: 295 | 296 | {{RootCmd 297 | |flashrom -p linux_spi:dev{{=}}/dev/spidev0.0,spispeed{{=}}8000 298 | |prompt=pi64 ~ # 299 | |output=
300 | flashrom v0.9.9-r1955 on Linux 4.10.17-v8-9411792647f6+ (aarch64)
301 | flashrom is free software, get the source code at https://flashrom.org
302 | 
303 | Calibrating delay loop... OK.
304 | Found Winbond flash chip "W25Q64.V" (8192 kB, SPI) on linux_spi.
305 | No operations were specified.
306 |
}} 307 | 308 | Obviously the output will reflect your particular version of flashrom, kernel and flash chip, but if you see something like the above, you are good to proceed. 309 | 310 | {{Note|You can also specify the actual device using the {{c|-c }} parameter to {{c|flashrom}} if you like; for example, on the Panasonic CF-AX3 you would would use: 311 | {{RootCmd 312 | |flashrom -p linux_spi:dev{{=}}/dev/spidev0.0,spispeed{{=}}8000 -c W25Q64.V 313 | |prompt=pi64 ~ # 314 | }} 315 | With most devices this is unnecessary; however, if {{c|flashrom}} complains when you probe that "{{c|Multiple flash chip definitions match... [p]lease specify which chip definition to use}}", then you '''must''' use this option (with all {{c|flashrom}} commands in this guide) to disambiguate (obviously, use the appropriate {{c|chipname}} for your setup, if you do).}} 316 | 317 | However, if instead you got an output containing No EEPROM/flash device found, then you have a problem. Double-check the wiring to your RPi3/4 and the IC clip, and make sure your RPi's [https://www.raspberrypi.org/forums/viewtopic.php?f=63&t=138636 power supply is sufficient]. If that all looks good, re-seat the IC clip on your flash chip, and try again. The clips are tricky to get seated properly, so it is not unusual for a few tries to be required before {{c|flashrom}} can successfully connect. 318 | 319 | {{Warning|If {{c|flashrom}} reports that it has found a brand or make of chip that doesn't match what you expected, '''stop'''. Search online and only proceed if you are confident there is no ambiguity.}} 320 | 321 | {{Tip|You can see all {{c|flashrom}}'s supported devices with:{{RootCmd 322 | |flashrom --list-supported 323 | |prompt=pi64 ~ # 324 | }}If your device is not shown you may be unable to proceed ({{c|flashrom}} ''will'' work correctly with most encountered flash devices though).}} 325 | 326 | Once you have a successful probe, leaving the clip in place, dump a copy of your existing firmware: 327 | 328 | {{RootCmd 329 | |flashrom -p linux_spi:dev{{=}}/dev/spidev0.0,spispeed{{=}}8000 -r original.rom 330 | |prompt=pi64 ~ # 331 | |output=
332 | flashrom v0.9.9-r1955 on Linux 4.10.17-v8-9411792647f6+ (aarch64)
333 | flashrom is free software, get the source code at https://flashrom.org
334 | 
335 | Calibrating delay loop... OK.
336 | Found Winbond flash chip "W25Q64.V" (8192 kB, SPI) on linux_spi.
337 | Reading flash... done.
338 |
}} 339 | 340 | {{Note|Again, obviously the output you get will most likely differ, but it should follow the pattern above. Make sure you see the Reading flash... done. line in your own output, indicating that the operation has been successful.}} 341 | 342 | Make another copy of the original firmware: 343 | 344 | {{RootCmd 345 | |flashrom -p linux_spi:dev{{=}}/dev/spidev0.0,spispeed{{=}}8000 -r original2.rom 346 | |prompt=pi64 ~ #}} 347 | 348 | And check that both copies are identical (this is a useful check to ensure that neither image has been corrupted): 349 | 350 | {{RootCmd 351 | |diff original{,2}.rom 352 | |prompt=pi64 ~ # 353 | }} 354 | 355 | This should produce no output, indicating that the dumped images are identical. 356 | {{Warning|If {{c|diff}} reports that the two images differ, '''stop'''. Repeat the read process until you have two identical copies that pass the diff test. Try reducing the {{c|spispeed}} parameter, and check your clip is properly seated. It is essential that you have a 'known good' backup copy of your original firmware before proceeding, so take care with this step and do not skip it!}} 357 | 358 | Next, assuming the {{c|diff}} check passes, run {{c|ifdtool}} on one of the images, to ensure that it has a valid structure: 359 | {{RootCmd 360 | |ifdtool -d original.rom 361 | |prompt=pi64 ~ # 362 | }} 363 | 364 | Your output will obviously be system-specific, but should resemble something like that shown [https://gist.github.com/corna/66322fb938dedd93d2aaa1d59b27341d here] (at least in broad outline). 365 | 366 | {{Warning|If {{c|ifdtool -d}} reports an error, or states that No Flash Descriptor found in this image, '''stop'''. Repeat the read process until you have two identical copies that pass the diff test ''and'' this {{c|ifdtool -d}} check.}} 367 | 368 | Finally, check that the dumped image has a structure that the {{c|me_cleaner}} tool understands, and can work with. To do so, issue: 369 | {{RootCmd 370 | |me_cleaner --check original.rom 371 | |prompt=pi64 ~ # 372 | }} 373 | 374 | As before, your output will be system-specific, but should pass all checks as for example shown [https://gist.github.com/corna/92df16e65248c63a258fdbdac5cb0923 here]. 375 | 376 | {{Warning|If {{c|me_cleaner --check}} reports an error, or states that you have an Unknown image, '''stop'''. Given that the other tests passed, please [https://github.com/corna/me_cleaner/issues/new open an issue] with {{c|me_cleaner}}, and report your findings.}} 377 | 378 | == Modifying Firmware using {{c|me_cleaner}}, to Disable the IME == 379 | 380 | With all tests passed, you can now run {{c|me_cleaner}} on your firmware image. Issue: 381 | 382 | {{RootCmd 383 | |me_cleaner --soft-disable original.rom --output modified.rom 384 | |prompt=pi64 ~ # 385 | |output=
386 | Full image detected
387 | The ME/TXE region goes from 0x3000 to 0x280000
388 | Found FPT header at 0x3010
389 | Found 21 partition(s)
390 | Found FTPR header: FTPR partition spans from 0x4e000 to 0xd4000
391 | ME/TXE firmware version 9.5.3.1520
392 | Removing extra partitions...
393 | Removing extra partition entries in FPT...
394 | Removing EFFS presence flag...
395 | Correcting checksum (0xe3)...
396 | Reading FTPR modules list...
397 |  UPDATE           (LZMA   , 0x0b1e05 - 0x0b1f0f): removed
398 |  ROMP             (Huffman, fragmented data    ): NOT removed, essential
399 |  BUP              (Huffman, fragmented data    ): NOT removed, essential
400 |  KERNEL           (Huffman, fragmented data    ): removed
401 |  POLICY           (Huffman, fragmented data    ): removed
402 |  FTPM             (LZMA   , 0x0b1f0f - 0x0bfbe1): removed
403 |  HOSTCOMM         (LZMA   , 0x0bfbe1 - 0x0c81af): removed
404 |  TDT              (LZMA   , 0x0c81af - 0x0cd4ed): removed
405 |  FPF              (LZMA   , 0x0cd4ed - 0x0ceff8): removed
406 | The ME minimum size should be 430080 bytes (0x69000 bytes)
407 | The ME region can be reduced up to:
408 |  00003000:0006bfff me
409 | Setting the AltMeDisable bit in PCHSTRP10 to disable Intel ME...
410 | Checking the FTPR RSA signature... VALID
411 | Done! Good luck!
412 |
413 | }} 414 | 415 | Your output will obviously differ (and in particular, if you are using a more modern PC than the CF-AX3 you may see a larger number of modules listed (and on a server-class machine, many fewer); see the {{c|me_cleaner}} [https://github.com/corna/me_cleaner/issues/3 success reports], for examples of the sort of output that may be produced). 416 | 417 | {{Note|We have used the {{c|--soft-disable}} flag here to ''both'' purge unneeded ME firmware ''and'' set the AltMeDisable/HAP bit (requesting the ME to do a clean self-disable during the bring-up phase) as noted [[#me_cleaner_ops|earlier]].}} 418 | 419 | The resulting image is saved to the file {{c|modified.rom}}; the original firmware files are left untouched. 420 | 421 | == Writing Back the Modified Firmware == 422 | 423 | We can now write back ('reflash') the system firmware we have just modified. With the IC clip still in place, issue: 424 | 425 | {{RootCmd 426 | |flashrom -p linux_spi:dev{{=}}/dev/spidev0.0,spispeed{{=}}8000 -w modified.rom 427 | |prompt=pi64 ~ # 428 | |output=
429 | flashrom v0.9.9-r1955 on Linux 4.10.17-v8-9411792647f6+ (aarch64)
430 | flashrom is free software, get the source code at https://flashrom.org
431 | 
432 | Calibrating delay loop... OK.
433 | Found Winbond flash chip "W25Q64.V" (8192 kB, SPI) on linux_spi.
434 | Reading old flash chip contents... done.
435 | Erasing and writing flash chip... Erase/write done.
436 | Verifying flash... VERIFIED.
437 |
}} 438 | 439 | As before, your output will most likely differ somewhat, depending on the specifics of your setup. 440 | 441 | {{Warning|If {{c|flashrom}} reports an error here, or does not finish with the output Verifying flash... VERIFIED, '''stop'''. You almost surely have a corrupted flash. Try the write again, using a slower {{c|spispeed}} parameter, and if that also fails, try re-seating the IC clip. Ensure you have the {{c|/WP}} and {{c|/HOLD}} pullups active as was specified [[#pullup{{!}}earlier]]. You can also try specifying the exact model name to {{c|flashrom}} using the {{c|-c}} parameter, as was discussed [[#specify_rom{{!}}above]].}} 442 | 443 | Once the flash has been successfully programmed, disconnect the IC-clip (or, if you are using a socketed chip and have it e.g. mounted on a solderless breadboard, remove the flash chip and place it back carefully in its socket on your PC). 444 | 445 | == Restarting your PC and Verifying the IME is Disabled == 446 | 447 | Reassemble your target PC, following instructions given in your vendor's maintenance manual where available (and as always taking care to observe proper [https://www.computerhope.com/esd.htm proper ESD protective measures]). Ensure any batteries or power supplies are reconnected, and then try booting it up (into Gentoo) using your regular procedure. 448 | 449 | If you experience serious problems upon restart — for example, the machine will not [[:Wikipedia:Power-on_self-test|POST]], or you are unable to enter the BIOS setup GUI after boot — then jump [[#recovery|here]] for instructions on how to recover (by reflashing your original firmware again). 450 | 451 | However, in the more likely case that your machine appears to start up correctly into Linux (after you enter your {{c|LUKS}} passphrase etc.), you can run the {{c|intelmetool}} to check the status of the ME. This is available as part of the {{c|coreboot-utils}} package on the {{c|sakaki-tools}} ebuild repository (aka 'overlay') which we already set up [[../Building_the_Gentoo_Base_System_Minus_Kernel#prep_for_parallel_emerge|earlier in the guide]], so, to install it, open a terminal (on your target PC), become root, and issue: 452 | 453 | {{RootCmd 454 | |emaint sync --repo sakaki-tools 455 | |mkdir -p -v /etc/portage/package.unmask 456 | |echo "sys-apps/coreboot-utils::sakaki-tools" >> /etc/portage/package.unmask/coreboot-utils 457 | |emerge --ask --verbose sys-apps/coreboot-utils 458 | |prompt=koneko ~ # 459 | |output=
460 | ... additional output suppressed ...
461 | Would you like to merge these packages? [Yes/No] 
462 | ... additional output suppressed ...
463 |
}} 464 | 465 | {{Note|The host name you see when running these commands will obviously reflect the settings on your target PC.}} 466 | {{Note|If you have ''not'' installed the {{c|sakaki-tools}} ebuild repository (its use was specified [[../Building_the_Gentoo_Base_System_Minus_Kernel#prep_for_parallel_emerge|earlier]] in the guide), then please follow the instructions given [https://github.com/corna/me_cleaner/wiki/How-to-apply-me_cleaner here] to clone and build the software directly.}} 467 | {{Note|For avoidance of doubt, {{c|intelmetool}} is usable ''both'' on systems with an OEM (e.g. AMI, Dell etc.) BIOS and on those running [https://www.coreboot.org/ coreboot].}} 468 | 469 | Then issue: 470 | {{RootCmd 471 | |intelmetool --show 472 | |prompt=koneko ~ # 473 | |output= 474 | Bad news, you have a `8 Series LPC Controller` so you have ME hardware on board 475 | and you can't control or disable it, continuing... 476 | 
477 | MEI was hidden on PCI, now unlocked
478 | MEI found: [8086:9c3a] 8 Series HECI #0
479 | 
480 | ME Status   : 0x1e020191
481 | ME Status 2 : 0x104d0142
482 | 
483 | ME: FW Partition Table      : OK
484 | ME: Bringup Loader Failure  : NO
485 | ME: Firmware Init Complete  : NO
486 | ME: Manufacturing Mode      : YES
487 | ME: Boot Options Present    : NO
488 | ME: Update In Progress      : NO
489 | ME: Current Working State   : Initializing
490 | ME: Current Operation State : Bring up
491 | ME: Current Operation Mode  : Debug
492 | ME: Error Code              : No Error
493 | ME: Progress Phase          : BUP Phase
494 | ME: Power Management Event  : Clean Moff->Mx wake
495 | ME: Progress Phase State    : 0x4d
496 | 
497 | ME: Extend SHA-256: 
498 | 
499 | ME: failed to become ready
500 | ME: failed to become ready
501 | ME: GET FW VERSION message failed
502 | ME: failed to become ready
503 | ME: failed to become ready
504 | ME: GET FWCAPS message failed
505 | Re-hiding MEI device...done
506 |
}} 507 | 508 | Again, the output on your system will probably differ from this. You can safely ignore the ominous sounding Bad news... message, as that actually only indicates that the very low-level status registers of the ME are visible over PCI. The ''real'' indications that the ME is disabled are that you see (depending on your ME version) one or more of the below: 509 | * ME: Firmware Init Complete : NO (as in the above); 510 | * ME: Error Code : Image Failure; 511 | * ME: Current Working State : Initializing (as in the above); 512 | * ME: Current Operation Mode : (null); 513 | * ME: Current Operation State : Bring up (as in the above); 514 | * ME: Progress Phase : Uncategorized Failure; 515 | * ME: Progress Phase : BUP Phase (as in the above); 516 | * ME: Progress Phase State : Check to see if straps say ME DISABLED; 517 | * ME: Progress Phase State : 0x4d (as in the above); 518 | * ME: Progress Phase State : Unknown 0x40; 519 | * ME: has a broken implementation on your board with this BIOS; 520 | * ME: GET FW VERSION message failed (as in the above); or 521 | * ME: GET FWCAPS message failed (as in the above). 522 | 523 | 524 | {{Note|If {{c|intelmetool}} reports an error similar to Could not map MEI PCI device memory, please see [https://github.com/corna/me_cleaner/issues/30#issuecomment-301193328 these notes] for a solution.}} 525 | 526 | You can also browse through the {{c|me_cleaner}} [https://github.com/corna/me_cleaner/issues/3 success reports], to see the sort of output that may be produced on different platforms. 527 | 528 | Next, wait for 30 minutes of wall time to elapse, and ensure that your target PC does not reset itself (thereby proving that the watchdog timer has been properly cleared). 529 | 530 | {{Note|If you ''don't'' see ME: Current Working State : Platform Disable Wait in the output from {{c|intelmetool}}, you can confident that the watchdog ''has'' been successfully disabled (and can safely skip the 30 minute check).}} 531 | 532 | If all that worked, congratulations! You have disabled the ME on your PC — click [[#next_steps|here]] to skip to the next step. 533 | 534 | If however you experience a problem booting (and cannot e.g. start Windows either, assuming you are dual-booting), then continue reading [[#recovery|immediately below]], to restore the original firmware image again. 535 | 536 | === Recovery in Case of Error === 537 | 538 | The {{c|me_cleaner}} process just described does not work on all machines. Fortunately, since you [[#backup_firmware|saved a copy]] of your original firmware earlier, and have a functional flash reprogrammer (the RPi3/4) to hand, it is straightforward to roll things back. 539 | 540 | {{Note|However, ''before'' rolling back your firmware, is is worth noting that on some systems, the {{c|me_cleaner}} process will cause the BIOS' ''state'' to be erased. As such, you may find e.g., that your target PC has fallen back to legacy boot mode, that your custom secure boot keys have been deleted and so on, but that you '''can''' still enter the BIOS GUI on boot (by pressing the appropriate hotkey).

541 | If this happens to you, you can recover your Gentoo system straightforwardly (and will probably ''not'' require a rollback reflash). To do so, enter the BIOS GUI, make sure UEFI (not legacy) booting is selected, and turn off secure boot, if enabled. Then, temporarily rename the kernel file {{Path|/EFI/Boot/gentoo.efi}} on your boot USB key to {{Path|/EFI/Boot/bootx64.efi}} (this can be done on any PC, including a Windows box). Insert the boot USB key into your target PC, and restart, entering the BIOS GUI once more. In the BIOS, select the boot USB key as the highest priority boot device, and exit, saving changes (on a few BIOSes, you may also need to specify the full {{Path|/EFI/Boot/bootx64.efi}} path here). Your Linux system should now start up, with the familiar LUKS prompt etc. Once back in your Gentoo desktop again, leave the boot USB key inserted, open a terminal window, and run (without arguments, as root) buildkernel, which should reset your EFI boot order list (and put a fresh copy of {{Path|(/boot/efi)/EFI/Boot/gentoo.efi}} on your boot USB key. You can now delete the temporary file {{Path|(/boot/efi)/EFI/Boot/bootx64.efi}} if you like. Reboot, and you should find that this new kernel starts up correctly.

Having done this, follow the instructions given in the "Installing New Keys into the Keystore" section (''ff''.) of the "Configuring Secure Boot" chapter (which may be found [[../Configuring_Secure_Boot#install_new_keys{{!}}here]] for {{c|systemd}} users, and [[../Configuring_Secure_Boot_under_OpenRC#install_new_keys{{!}}here]] for those using {{c|OpenRC}}) to re-install your (existing) secure boot keys, and re-activate and test secure boot.

If the process just described works for you, congratulations, your system should be functioning normally again! Rejoin the tutorial [[#renga_janai{{!}}above]], and check that the IME has been successfully disabled on your machine. If, however, it did ''not'' work, continuing reading [[#restore_image|immediately below]], to roll back your firmware.}} 542 | 543 | To restore the original firmware image, simply follow the previous instructions to power down your PC, expose the system motherboard, and (re)connect the RPi flash programmer's IC clip. Then on the RPi, working as root, issue: 544 | 545 | {{RootCmd 546 | |pigs pud 23 u 547 | |pigs pud 24 u 548 | |flashrom -p linux_spi:dev{{=}}/dev/spidev0.0,spispeed{{=}}8000 -w original.rom 549 | |prompt=pi64 ~ # 550 | |output=
551 | ... additional output suppressed ...
552 | Verifying flash... VERIFIED.
553 |
}} 554 | to write the original firmware image back again. When done (make sure you see the Verifying flash... VERIFIED output), follow the earlier procedure to disconnect the IC clip, reassemble your target PC, and boot it up. 555 | 556 | In this case, unfortunately it appears that the IME cannot be disabled on your system at this time. 557 | 558 | == Next Steps == 559 | 560 | If you were '''successful''' restarting your system after running {{c|me_cleaner}} (and it passed the [[#imt_check|intelmetool --show test]]), please consider posting details of your system [https://github.com/corna/me_cleaner/issues/3 here], to assist others. 561 | 562 | However, if you '''experienced a problem''' during the process, please take the time to post an [https://github.com/corna/me_cleaner/issues/new new issue] here. 563 | 564 | Finally, to rejoin the main guide, please click [[../Using_Your_New_Gentoo_System#additional_mini_guides|here ({{c|systemd}})]] or [[../Using_Your_New_Gentoo_System_under_OpenRC#additional_mini_guides|here ({{c|OpenRC}})]]. 565 | 566 | == Notes == 567 | {{reflist}} 568 | 569 | [[Category:Security]] 570 | 571 | -------------------------------------------------------------------------------- /pages.txt: -------------------------------------------------------------------------------- 1 | User:Sakaki/Sakaki's_EFI_Install_Guide 00_EFI_Gentoo_End_to_End_Install 2 | User:Sakaki/Sakaki's_EFI_Install_Guide/Installation_Prerequisites 01_Installation_Prerequisites 3 | User:Sakaki/Sakaki's_EFI_Install_Guide/Preparing_Windows_for_Dual-Booting 02_Preparing_Windows_for_Dual-Booting 4 | User:Sakaki/Sakaki's_EFI_Install_Guide/Creating_and_Booting_the_Minimal-Install_Image_on_USB 03_Creating_and_Booting_the_Minimal-Install_Image_on_USB 5 | User:Sakaki/Sakaki's_EFI_Install_Guide/Setting_Up_Networking_and_Connecting_via_ssh 04_Setting_Up_Networking_and_Connecting_via_ssh 6 | User:Sakaki/Sakaki's_EFI_Install_Guide/Preparing_the_LUKS-LVM_Filesystem_and_Boot_USB_Key 05_Preparing_the_LUKS-LVM_Filesystem_and_Boot_USB_Key 7 | User:Sakaki/Sakaki's_EFI_Install_Guide/Installing_the_Gentoo_Stage_3_Files 06_Installing_the_Gentoo_Stage_3_Files 8 | User:Sakaki/Sakaki's_EFI_Install_Guide/Building_the_Gentoo_Base_System_Minus_Kernel 07_Building_the_Gentoo_Base_System_Minus_Kernel 9 | User:Sakaki/Sakaki's_EFI_Install_Guide/Configuring_and_Building_the_Kernel 08_Configuring_and_Building_the_Kernel 10 | User:Sakaki/Sakaki's_EFI_Install_Guide/Final_Preparations_and_Reboot_into_EFI 09_Final_Preparations_and_Reboot_into_EFI 11 | User:Sakaki/Sakaki's_EFI_Install_Guide/Configuring_systemd_and_Installing_Necessary_Tools 10_Configuring_systemd_and_Installing_Necessary_Tools 12 | User:Sakaki/Sakaki's_EFI_Install_Guide/Completing_OpenRC_Configuration_and_Installing_Necessary_Tools 10a_Completing_OpenRC_Configuration_and_Installing_Necessary_Tools 13 | User:Sakaki/Sakaki's_EFI_Install_Guide/Configuring_Secure_Boot 11_Configuring_Secure_Boot 14 | User:Sakaki/Sakaki's_EFI_Install_Guide/Configuring_Secure_Boot_under_OpenRC 11a_Configuring_Secure_Boot_under_OpenRC 15 | User:Sakaki/Sakaki's_EFI_Install_Guide/Setting_up_the_GNOME_3_Desktop 12_Setting_up_the_GNOME_3_Desktop 16 | User:Sakaki/Sakaki's_EFI_Install_Guide/Setting_up_the_GNOME_3_Desktop_under_OpenRC 12a_Setting_up_the_GNOME_3_Desktop_under_OpenRC 17 | User:Sakaki/Sakaki's_EFI_Install_Guide/Final_Configuration_Steps 13_Final_Configuration_Steps 18 | User:Sakaki/Sakaki's_EFI_Install_Guide/Final_Configuration_Steps_under_OpenRC 13a_Final_Configuration_Steps_under_OpenRC 19 | User:Sakaki/Sakaki's_EFI_Install_Guide/Using_Your_New_Gentoo_System 14_Using_Your_New_Gentoo_System 20 | User:Sakaki/Sakaki's_EFI_Install_Guide/Using_Your_New_Gentoo_System_under_OpenRC 14a_Using_Your_New_Gentoo_System_under_OpenRC 21 | User:Sakaki/Sakaki's_EFI_Install_Guide/Extending_LUKS_to_Protect_an_Additional_Drive m01_Extending_LUKS_to_Protect_an_Additional_Drive 22 | User:Sakaki/Sakaki's_EFI_Install_Guide/Disabling_the_Intel_Management_Engine m02_Disabling_the_Intel_Management_Engine 23 | User:Sakaki/Sakaki's_EFI_Install_Guide/Sandboxing_the_Firefox_Browser_with_Firejail m03_Sandboxing_the_Firefox_Browser_with_Firejail 24 | User:Sakaki/Sakaki's_EFI_Install_Guide/Booting_Legacy_Images_on_EFI_using_kexec m04_Booting_Legacy_Images_on_EFI_using_kexec 25 | --------------------------------------------------------------------------------