User:Timofonic/MyGentooInstall

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!

This detailed (and tested) tutorial shows how to set up just such a dual-boot system, where the Gentoo component:
 * is fully encrypted on disk (LVM over LUKS, with dual-factor protection);
 * uses UEFI secure boot;
 * runs systemd & GNOME 3.14+;
 * or OpenRC & GNOME 3.14+ (new!)
 * can properly suspend and hibernate;
 * has working drivers for touchscreen, webcam etc.;
 * and even has a graphical boot splash!

To keep things concrete, I'll be walking line-by-line through the setup of a particular machine, namely the Panasonic CF-AX3 Ultrabook; however, these instructions should be usable (with minor alterations) for many modern PCs (including desktops) which have a UEFI BIOS.

All commands that you'll need to type in are listed, and an overlay with some useful installation utilities is also provided.

While best read in tandem with the official Gentoo Handbook, this manual can also be used standalone.

These instructions may also be easily adapted for those wishing to use Gentoo Linux as their sole OS, rather than dual booting.

Introduction
The install described in this tutorial attempts to follow the 'stock' process from the Gentoo Handbook where possible, but differs in a number of important respects. Specifically:
 * The kernel will be configured to self-boot under UEFI; no separate bootloader is needed.
 * For security, we will 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.
 * Secure boot will be enabled. The kernel will be signed with our own, generated key (and the original Windows keys will be retained too).
 * Gentoo's root, swap and home partitions will reside on LVM logical volumes, which themselves will live on a single 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.
 * The LUKS partition will be unlocked by a keyfile at boot. The keyfile will be stored on the USB key together with the Gentoo kernel, and will itself be 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.)
 * We will create an 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 to use in this step).
 * For all you source-code paranoiacs, the 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 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!).
 * The latest (3.14+) stable version of GNOME will be installed, which will necessitate using systemd for init (the existing handbook is quite OpenRC-centric). Incidentally, this will not require an interim GNOME 2 deployment.
 * An alternative track is now also provided, for those wishing to install GNOME 3.14+ under OpenRC, via Dantrell B.'s patchset (this is, essentially, how Funtoo avoids having to use systemd for GNOME, and now his patchset is available for use with Gentoo too). 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.
 * Lastly, I'll provide simple scripts to automate the EFI kernel creation process and keep your system up-to-date. The first of these 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  automates the process of updating your system software via  and associated tools. The scripts are shipped in an overlay, for easy deployment.

As mentioned, although this tutorial follows the format of the 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.14+ machine when you're done.

Chapters
The chapters of this tutorial are listed below, together with a brief summary of each.

You need to work though the chapters sequentially, in order to complete the install successfully.


 * 1) Installation Prerequisites. First, we'll briefly review the things you'll need in order to carry out the install.
 * 2) 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.
 * 3) Creating and Booting the Minimal-Install Image on USB. Then, per 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 legacy /  mode).
 * 4) Setting Up Networking and Connecting via ssh. Next, per 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  (to ease installation).
 * 5) 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 Chapter 4 of the handbook).
 * 6) Installing the Gentoo Stage 3 Files. Then, per 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.
 * 7) Building the Gentoo Base System Minus Kernel. Next, per Chapter 6 of the handbook, we'll complete some final preparations, then  into the stage 3 filesystem, update our Portage tree, and set a base profile, timezone and locale. We'll setup the  overlay (which contains utilities to assist with the build), and install the first of these,  (a program to monitor parallel s). Then, we'll bootstrap the toolchain (simulating an old-school stage 1 install), rebuild everything in the  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 (users on the OpenRC track will first add Dantrell B.'s overlays here), and then update the  set to reflect this.
 * 8) Configuring and Building the Kernel. Next, (loosely following Chapter 7 of the handbook), we'll setup necessary licenses, then download the Linux kernel sources and firmware. We'll then install (from the overlay) the  utility, configure it, and then use this to automatically build our (EFI-stub) kernel ( ensures our kernel command line is filled out properly, the initramfs contains a static version of, that the kernel has all necessary  options set, etc.).
 * 9) Final Preparations and Reboot into EFI. Then, following Chapter 8 of the handbook, we'll set up, install a few other packages, set up a root password, then dismount the  and reboot (in EFI /  mode, or EFI /  mode, depending on the track) into our new system (secure boot will be off at this stage). Users on the OpenRC track will branch off at the conclusion of this chapter.
 * 10) Configuring systemd and Installing Necessary Tools. With the machine restarted, we'll re-establish networking and the  connection, then complete the setup of 's configuration. Per Chapter 9 of the Gentoo handbook, we'll then install some additional system tools (such as ). Next, we'll install (from the overlay) the  utility, and use it to perform a precautionary update of the  set. Then, we'll reboot to check our  configuration. If successful, we'll invoke  again, to enable the  graphical boot splash, and restart once more to test it.
 * 11) Configuring Secure Boot. 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  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).
 * 12) Setting up the GNOME 3 Desktop. Next, we'll setup your graphical desktop environment. We'll begin by creating a regular (non-root) user, per Chapter 11 of the handbook. Then, we'll install X11, and try running it with a simple window manager, to check if all necessary display drivers are present. If they aren't, we'll modify the kernel configuration accordingly, and rebuild using . Once working, we'll remove the temporary window manager, install GNOME 3 (and a few key applications), and configure and test it.
 * 13) Final Configuration Steps. 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 to remove bloat; get suspend and hibernate working properly; ensure that the correct  interpreter is set as the system default; and disable  (as the helper PC is no longer needed from this point).
 * 14) Using Your New Gentoo System. 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 ). 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). Finally, we'll briefly review how to tweak GNOME, and (per Chapter 11 of the handbook) where to go next (should you wish to install other applications, a firewall, etc.).

Let's Get Started!
Ready? Then click here to go to the first chapter, "Installation Prerequisites".

What You'll Need
To work through this install, you will need:
 * A target, UEFI PC with Windows-10 (or 8 or 8.1) pre-installed (for example, an 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 C: yet.
 * Two USB keys, one of at least 300MB, and the other of at least 128MB:
 * the larger one is for the initial Gentoo minimal-install disk image, which we'll use to get the ball rolling; and
 * 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).


 * A working subnet to which the install target machine can be connected. To be concrete, I'm going to assume a 192.168.1.0/24 subnet, but yours may of course be different, in which case modify the instructions accordingly. There must be a gateway on the network providing Internet access, and a DHCP server. Furthermore, your target PC must have either:
 * 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
 * a WiFi modem with driver support in the Gentoo minimal-install image (many do). The tutorial covers setting up such a connection over WPA/WPA2, since this is the most common modern use case.


 * A 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:
 * once the initial, minimal-install image has booted, you can in to it from this second box, and run ; 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
 * 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.

Commencing the Install
Got everything? Then click here to go to the next chapter, "Preparing Windows for Dual-Booting".

Shrinking Windows' Disk Footprint
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):


 * 1) Ensure you have backups of everything important. Last chance ^-^
 * 2) Done that? OK then, to begin with, we'll turn off system protection (restore points). Hit the, which will bring up the start menu in Windows 10 (or the "start screen" in Windows 8.1 and 8), and type  . 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, 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'.
 * 3) Next, we'll turn off the virtual memory paging file. Hit the, which will bring up the start menu in Windows 10 (or the "start screen" in Windows 8.1 and 8), and type  . 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, 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.
 * 4) Now to turn off hibernation. This is most easily done from the Windows command line. Hit the , which will bring up the start menu in Windows 10 (or the "start screen" in Windows 8.1 and 8), and type  . 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  . After this, hit , then click on the power icon at the bottom right of the screen, and choose 'Restart' from the pop-up menu.
 * 5) Allow the machine to reboot back into Windows, and log in again.
 * 6) Now we will defragment the drive. Hit the, which will bring up the start menu in Windows 10 (or the "start screen" in Windows 8.1 and 8), and type  . 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 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.
 * 7) Follow the process described earlier to reboot and log in again to Windows. (Without this reboot, the shrink step below may fail.)
 * 8) Finally, we are ready to shrink the Windows partition . Hit, which will bring up the start menu in Windows 10 (or the "start screen" in Windows 8.1 and 8), and type  . 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 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 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:Win8PartitionShrink.png 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 C: partition shrunk to 42.10GB from 237.96GB). YMMV.
 * 9) 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.
 * 10) 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 turn on hibernation again. Hit the , which will bring up the start menu in Windows 10 (or the "start screen" in Windows 8.1 and 8), and type  . 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  . 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.
 * 11) Next, let's activate the virtual memory paging file again. Hit the, which will bring up the start menu in Windows 10 (or the "start screen" in Windows 8.1 and 8), and type  . 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.
 * 12) Now we'll turn on system protection (restore points) again. Hit the, which will bring up the start menu in Windows 10 (or the "start screen" in Windows 8.1 and 8), and type  . 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, 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'.
 * 13) Follow the process described earlier to reboot and log in one last time to Windows. Check that everything still works as expected.
 * 14) The final step is to ensure that hibernation shows up on the Windows power menu.  Hit the, 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  , and click on the 'Power Options' item which appears; then, click 'Choose what the power button does' in the presented dialog box. In Windows 8.1 or 8, type  , 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), 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 , 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.

Next Steps
Although we're done with our Windows prep work for now, leave the target machine running Windows for the moment. Click here to go to the next chapter, "Creating and Booting the Minimal-Install Image on USB".

Downloading and Verifying the ISO Image
Firstly, identify the name of the current release of the minimal install ISO (we'll refer to it using the generic form 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.

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

This may take a little time to complete, depending on the speed of your Internet link.

We next need to check the integrity of the ISO, before using it. The file contains cryptographically signed digests (using various hash algorithms) for two other files you have downloaded.

As such, to verify the ISO we must:
 * 1) download the public key used for Gentoo automated weekly releases (if you don't already have this on your helper PC);
 * 2) check the signature of the  file using this key; and then
 * 3) check that the hashes (digests) contained in that file agree with values that we compute independently.

The fingerprint of the automated weekly release public key may be found on the 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, so to download it (step 1 in the above list), issue:

With that done, use the program to verify the digest file (step 2):

Assuming that worked (the output reports 'Good signature'), next check the digests themselves (step 3); we'll use the SHA512 variants here:

If this outputs:

then continue, all is well.

Copying the ISO Image to USB
Next, we need to copy the ISO onto a USB key (the image is already hybrid ).

Just before inserting the USB key (the larger one) into the helper pc, issue:

Note the output, then insert the USB key, and issue:

again. The change in output will show you the key's device path (note that the initial prefix is not shown in the  output). We will refer to this path in these instructions as , but in reality on your system it will be something like, etc.

Next, we will write the ISO image to the USB key. This will require root access, so issue:

Now you can write the ISO image to the USB key (note, we use a larger than default block size here, for efficiency). Issue:

Wait for the process to complete before continuing.

Booting the ISO Image
Although the minimal install image does include an EFI directory, the images within it are unusable for booting. As such, we'll proceed by first booting the USB key we just created using the UEFI's 'legacy' / CSM mode. (Of course, the kernel we'll ultimately create will (secure) boot under EFI.)

So, to proceed, take the USB key from the helper PC (where we just '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:
 * Either: Use Windows boot options menu.
 * This is the easier method (particularly if your target machine is using the 'fast boot' option with Windows). In Windows, hit, then click on the power icon at the bottom right of the screen, and then while holding down , 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.


 * Or: Use the BIOS hotkey.
 * This is a less reliable method, since you are racing the OS loading process. To use it, hit 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  during startup (you may need to press it repeatedly).

Once you have the BIOS configuration GUI up, you need to perform the following steps :
 * 1) disable EFI boot mode;
 * 2) enable legacy / CSM boot mode;
 * 3) set the machine to look first at any inserted USB keys, when searching for a bootloader.

The precise steps to achieve this will depend on your BIOS. On the CF-AX3, use the arrow keys to move to the 'Boot' tab, then, as shown below, navigate down to the 'UEFI Boot' item, and press. In the popup that appears, select 'Disabled' using the arrow keys, and press. This switches the system out of UEFI mode and into legacy / CSM boot (steps 1 and 2 in the list above).

Next, move down using the arrow keys to the 'Boot Option #1' item (as shown below). Press and select 'USB KEY' from the pop-up menu that appears, then press. This ensures that any inserted USB key will be searched for a bootable system before the internal hard drive (step 3). (If you don't do this, you'll simply be dumped back into Windows when you restart.)

Finally, instruct the BIOS to save these changes and restart (with the USB key still inserted). Again, the method varies from machine to machine; on the Panasonic CF-AX3, hit, and confirm when prompted.

Hopefully, you'll now see ISOLINUX boot prompt (and the machine will beep at you). Unless you want to enter custom boot options, simply press 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 to select the Japanese keymap.

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).

Make a note of the password, as you will require it shortly.

Setting the Date and Time
It's important to ensure that you have the correct time and date on your target machine. Check it with:

Per <span id="set_date_and_time">the handbook, you should stick with UTC for now (the real timezone specification will come later in the install). If necessary, set the date and time, in MMDDhhmmYYYY format (Month, Day, hour, minute, year):

<span id="next_steps">Next Steps
Next, we'll setup the network and get an SSH daemon running. Click here to go to the next chapter, "Setting Up Networking and Connecting via ".

<span id="setting_up_networking_and_ssh">Getting Networking Running
Decide whether you wish to perform the install using a wired Ethernet connection, or over WiFi (using WPA/WPA2), and follow the appropriate instructions below. In both cases, the presence of a DHCP server on the subnet will be assumed.

<span id="connecting_via_ethernet">Connecting via Wired Ethernet
This is the easier option, if your machine physically supports it. To proceed, <span id="get_ip_address">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:

Hopefully, it will have autoconfigured an interface, as above. In the old days, you'd be looking for eth0 in the output of this command, but things have now changed (to ensure device naming stability across reboots), so your wired ethernet interface name will probably be something a bit stranger-sounding, such as enp0s25 (as is the case here). You are looking for the 'inet' (assuming IPv4) entry; in this case 192.168.1.106 (yours will almost certainly differ).

If that was successful, then try:

If this works, it demonstrates that you have a functioning network connection, with working DNS name resolution.

When ready, click here to jump to the next section of the tutorial.

<span id="connecting_via_wifi">Connecting via WiFi (WPA/WPA2)
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:

Your <span id="note_wifi_if_name">results will differ from the above, but you're looking for a record starting with , as this is a wireless adaptor. In this example, the predictable network interface name of the WiFi adaptor is ; take a note of the particular name reported in your case.

Next, we'll need to <span id="create_wpa_config">create a configuration file, to allow the program to handle the encrypted network connection. You'll need to know your WiFi access point's Wikipedia:Service_set_(802.11_network) (the name you'd see when connecting to it via your phone etc.) and its WPA (or WPA2) passphrase. Issue:

Lock down the file's access permissions (to root only) and check that its contents look sane. Issue:

Assuming that looks OK, we can connect. Issue:

In this command:

Now wait a moment or two, then issue:

Hopefully, it will have connected successfully. You are looking for the 'inet' (assuming IPv4) entry; in this case 192.168.1.106 (yours will almost certainly differ).

If that was successful, then try:

If this works, it demonstrates that you have a functioning network connection, with working DNS name resolution.

<span id="setup_ssh_server">Connecting via and Using
Our next step is to setup so we can remotely connect and run the install from our helper PC. Still on the target machine console, enter:

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

Next, <span id="log_in_via_helper">move back onto the second, helper PC (on the same subnet), and enter:

(The command simply removes any record of fingerprints for previous connections to other  servers at that IP address, since  will refuse to connect if it finds a conflicting one.)

Check the reported key fingerprint and then, if it matches one you noted earlier, continue as below:

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).

Now, still via this remote login connection (i.e., at the helper PC's keyboard), <span id="start_screen">issue :

to start a new 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.

<span id="next_steps">Next Steps
Next, we'll prepare the storage on the target machine. Click here to go to the next chapter, "Preparing the LUKS-LVM Filesystem and Boot USB Key".

<span id="making_boot_usb_key">Formatting and Mounting the UEFI-Bootable USB Key
We are going to use our smaller (>= 128 MB) USB key as the boot device for Gentoo Linux. Since we want it to work under UEFI, we must format it using GPT with a single EFI system partition.

Issue (using of course the /  terminal we have just established):

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 <span id="determine_efi_dev">path in these instructions as, but in reality on your system it will be something like , etc. You can find what it is, by issuing  again, and noting what has changed:

(note that the initial prefix is not shown in the  output)

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).

Now, using parted, we will <span id="setup_system_partition">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 somewhat confusingly named 'boot' flag (i.e., mark the partition as a GPT system partition). Issue:

Next, we need to format the partition fat32:

Now we create a <span id="temp_mount_efi">temporary mountpoint and mount the partition:

<span id="create_gpg_luks_keyfile">Creating a Password-Protected Keyfile for LUKS
We will next create a (pseudo) random keyfile (for use with LUKS). This keyfile will be encrypted with GPG (using a typed-in passphrase) and then stored on the USB key.

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).

Note that we are going to create a (one byte short of) 8192KiB underlying (i.e., binary plaintext) keyfile, even though, for the symmetric LUKS cipher we'll be using (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 / uses the 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 system can support keyfiles up to and including 8192KiB (execute  to verify this); in practice, due to a off-by-one bug, it supports only keyfiles strictly less than 8MiB. We therefore create a keyfile of length (1024 * 8192) - 1 = 8388607 bytes.

Note that we'll use the /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:

What <span id="correct_horse_battery_staple">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 str1ng5 @f characters. Advantages include:
 * it's easier to hit a reasonable level of entropy;
 * you are less likely to forget the resulting passphrase; and
 * your passphrase will be more robust in the face of keymapping snafus at boot time.

<span id="create_partition_for_luks">Creating a New GPT Partition on the PC's Main Drive
Our next task is to create a new GPT partition on the target PC's hard drive (which we freed up space for earlier).

We will use the 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.

We must first find the device path of the main hard drive on the target machine. We will refer to this as in the following text, but it will be something like,  etc. on your machine. Check the actual path with:

If you are dual booting with Windows, you'll probably see that the desired drive has four existing partitions (note that the initial  prefix is not shown in the  output). None of these should be mounted (all should have blank mountpoints in the output of ).

Now we will create the partition:

Now check that the sector has been created correctly. We'll <span id="find_luks_partition">issue an command again:

Take note of the new sector device path (note that the initial  prefix is not shown in the  output). We will refer to this as in the below, but it will actually be something like,  etc. If you have a non-standard Windows setup, the number of the new partition may also be something other than 5, so do please double check.

<span id="fuzz_luks_partition">Overwriting the New Partition with Pseudo-Random Data (Optional Step)
You can skip this step if you like. The main reasons to perform an overwrite are:
 * to purge any old, unencrypted data that may still be present in the partition (from prior use); and
 * to make it somewhat harder for an attacker to determine how much data is on your drive if the machine is compromised.

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).

This command may take a number of hours to complete.

By itself, will not show any progress, however, if you are using, you can send it USR1 signals to make it print I/O statistics. Hit followed by  to start a new virtual console within  (do this from the console where you started the ). Then issue:

Now switch back to the original virtual console with followed by  and you will be able to see  slowly progressing.

Once the overwrite completes, switch to the second console again with followed by, and then use  to kill , and  to close the (second) console, which leaves you back with a single virtual console again.

<span id="format_luks_partition">Formatting the New Partition with LUKS
The next step is to format the partition using 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 further encrypted under between one and eight user keys (themselves first pre-processed by PBKDF2).

The target partition itself begins with a LUKS metadata header, followed by the 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).

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.

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.).

LUKS functions are accessed via the cryptsetup program, and use 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:

(You may have others available as kernel modules, which will be loaded when required).

What we need to do is tell :
 * 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),
 * the key length to use with this cipher,
 * 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),
 * what processing, if any, should be applied to the sector index number during IV computation, and
 * the hash algorithm used for key derivation (under the PBKDF2 algorithm within LUKS)

This isn't a cryptography primer (see this article for further reading), but here's a thumbnail justification for the choices made:
 * we will use Serpent as the block cipher; this came second in the AES competition 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 Rijndael algorithm that won the competition (and which, accordingly, is now commonly referred to as 'AES');
 * for security, we'll use the longest supported key length for Serpent, which is 256 bits (see the following point, however);
 * we will use 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 CBC / 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 shellcode ; 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 ;
 * 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);
 * we will use SHA-512 as the user key hashing function for LUKS' PBKDF2 processing; it is a robust 512 bit hash.

We decrypt our keyfile from the USB key (using ) and pipe it to, to avoid the unencrypted keyfile having to be saved to disk. The and  strings instruct  to use the settings just discussed.

Check that the formatting worked, with:

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 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 init scripts that we'll rely on later.).

<span id="add_fallback_luks_passphrase">Adding a Fallback Passphrase (Optional Step)
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.

Unfortunately, the necessary 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 (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 named pipe.

Assuming you're using, hit followed by  to start a new virtual console. Then type:

(The slightly odd approach of piping via 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 followed by, and enter:

Verify that this worked by issuing:

You should now see slot 1 is enabled, as well as slot 0. Now, remove the named pipe, since we no longer need it:

Lastly, switch back to the second virtual console with followed by, and then hit  to close it out and return to the original console again.

<span id="create_lvm_structure">Creating the LVM Structure (PV->VG<-LVs) on Top of LUKS
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 here, and a handy command cheatsheet here. It is a highly flexible virtual partition system. Some important LVM terminology is as follows:
 * A 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.
 * A physical extent (PE) is the smallest allocatable unit of a PV. We will use the default PE size of 4MiB in this tutorial.
 * A 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.
 * A 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.

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.

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:

Check that this worked:

You should see the device 'gentoo' in the device mapper list, as above. This is our unlocked LUKS partition.

Next, we'll create an LVM physical volume (PV) on this partition:

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 :

Now, we'll create three logical volumes (LVs) in this volume group. The first is for swap. To allow the use of suspend to disk (which we'll setup 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:

In the case of the CF-AX3, this shows just under 8GiB, 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.

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 files and so on. We'll allow 50GiB here - if you wish you can make this smaller or larger of course:

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 snapshot later, for example).

You should now be able to look at the status of the physical volume (PV), volume group (VG) and logical volumes (LVs), as follows:

The final task in this step is to <span id="activate_lvm">'activate' the new volume group (vg1) so that it's logical volumes become available as block devices via the device mapper. Issue:

This should inform you that three LVs in the vg1 volume group have been activated. Check that they are visible via the device mapper:

If your output looks similar to the above, then all is well. The new logical volumes (, and ) can be treated exactly like physical disk partitions (i.e., just like  etc.).

<span id="create_lvm_lvs">Formatting and Mounting the LVM Logical Volumes (LVs)
Now we have our virtual partitions, we need to <span id="create_lvs">set up their filesystems and then mount them.

First, create the swap:

Next, the root filesystem. We'll create this as ext4 (you can of course modify this if you wish):

Finally, the user home filesystem, also ext4. Note that we use the 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:

Now, we activate the swap:

And, per the handbook, mount the root directory at the pre-existing mountpoint:

Next, we create the mountpoint, a  directory, and a  mountpoint. The purpose of these is as follows:
 * will be the mountpoint for our home directory LV.
 * 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 utility, supplied as part of this tutorial, will be used to copy the final, signed and bootable kernel image onto the USB key (at ) as part of the kernel build process. For that reason, we've converted  from a mountpoint to a regular directory in this tutorial.
 * 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 and will need to unmount it.

Create the directories:

Now mount the "home" LVM logical volume from the "vg1" volume group on the mountpoint:

Next, we need to <span id="unmount_efi">unmount the USB boot key's EFI partition from its current temporary mountpoint (we'll remount it later, when we build the kernel):

Finally, <span id="finding_blkids">issue :

Take note of the PARTUUIDs (unique partition identifiers) for these two partitions; we'll make use of them later (in the and the kernel build script's configuration file), rather than relying on the  paths (which can change depending on which devices are plugged in, and the order in which they are recognized).

<span id="next_steps">Next Steps
We're now ready to fetch the additional installation files and setup the build options. Click here to go to the next chapter, "Installing the Gentoo Stage 3 Files".

<span id="double_check_date_time">Double-Checking the Date and Time
Before downloading anything, double-check that you have the correct time and date on the target machine (you should do, as you set it up earlier, but since having an incorrect date can cause problems later, it is best to make sure now). Check it with:

Per <span id="set_date_and_time">the handbook, you should stick with UTC for now (the real timezone specification will come later in the install). If necessary, set the date and time, in MMDDhhmmYYYY format (Month, Day, hour, minute, year):

<span id="download_stage_3_tarball">Downloading, Verifying and Unpacking the Gentoo Stage 3 Tarball
The 'Stage 3' file is a tarball containing a populated directory structure from a basic Gentoo system. Unlike the minimal installation image however, the stage 3 system contains no kernel, only binaries and libraries essential to bootstrapping. As such, we will have to host it within a chroot from our existing (minimal install image) system, until we have recompiled all system files and libraries, built a fresh kernel, and the new system becomes self-hosting.

The stage 3 tarball is generally released on the same date as the minimal install image, and may be found (together with the usual contents and digest files) in the same autobuilds directory. As the amount of data involved here is small, pace the handbook we'll skip using the slightly awkward browser / mirror selection process at this stage, and just grab the files directly with.

Change to the Gentoo filesystem root mountpoint:

Now <span id="download_stage_3">download the files. As before, substitute for YYYYMMDD in the below with the current release file date (open the link http://distfiles.gentoo.org/releases/amd64/autobuilds/latest-stage3-amd64.txt in a browser to determine the current name).

As before (when we downloaded the minimal install image), we have to go through a two-stage verification: first check the signature in the file, and then check the digests in that file themselves. As this is the target machine (not the helper), we don't yet have the necessary Gentoo automated weekly release public key, whose fingerprint may be found on the Gentoo release engineering page. So let's fetch it now. Issue:

Once you have the public key, verify the digest file:

And assuming that worked (output reports 'Good signature'), next check the digests themselves; we'll use the SHA512 variants here:

If this outputs:

then continue.

The last step in this stage is to unpack the tarball. Double check you are in the directory, then issue:

As per the handbook, the options to are to extract, provide verbose output, decompress with bzip2 (j), preserve permissions and extract from a file, not standard input.

Check that the base system has unpacked OK:

If you see a file structure similar to the above, then you can proceed. As we no longer need the stage files, they can be deleted now to save space:

This structure looks, as it should, a lot like a normal Linux root directory, but it is positioned at. Later, we'll in a few additional special directories from our running (minimal) system, and then  into this new base to continue with the installation.

Lastly, return back to root's home:

Before we continue, we'll take a brief detour to discuss some essential Gentoo / Portage background information and terminology. If you are an old hand with this, feel free to skip this material.

<span id="gentoo_overview">Gentoo, Portage, Ebuilds and (Background Reading)
Gentoo is a source-based distribution, the heart of which is a powerful package manager called Portage. Portage itself has two main components:
 * the ebuild system, which performs the work of fetching, configuring, building and installing packages, and
 * the Emerge tool, which provides a command line interface to control ebuilds, and also allows you to update the Portage tree (discussed below).

Package ebuilds are Bash shell scripts, or more accurately shell script fragments, that are sourced into a larger build system 'host' script. This host script provides a package management control flow that invokes a set of default 'hook' functions, which a particular package's ebuild may override if it needs to (these are covered in detail in the Gentoo Development Guide). The ebuild also must define a minimum set of variables to allow the whole process to operate successfully (for example, the URI from where a package's source tarball may be downloaded must be assigned to the variable).

Now, when you invoke an ebuild to install a particular (as yet uninstalled) package on your system (via, for example, as described below), it will typically carry out the following tasks (inter alia):
 * check that the specified package can be installed (that is, that it isn't masked, or has an incompatible license requirement);
 * download the package's tarball (or other format source archive) from an upstream repository (or Gentoo mirror);
 * unpack the tarball in a temporary working area;
 * patch (and otherwise modify) the unpacked source if need be;
 * configure the source to prepare it for compilation on your machine;
 * compile / build the source, as a non-privileged user in the temporary work area;
 * run tests (if provided and required);
 * install the built package to a dummy filesystem root; and
 * copy ('merge') the package installation files from the dummy filesystem root to the real filesystem root (keeping a record of what gets done).

Up until the final file copy-over step (the 'merge' in ), all operations (even where the package's is invoked, for example) take place in a temporary staging area. This enables Portage to keep track of all the files installed by a particular package, limit the damage caused by failed compiles or installs, and facilitate simple removal of installed packages. Furthermore, for most of these tasks, Portage operates in a 'sandbox' mode, where attempts to write directly to the real root filesystem (rather than the temporary work area) are detected, and cause an error to be thrown (NB this is not intended as a security system per se, but it does help prevent accidental filesystem corruption).

<span id="portage_tree">Portage stores ebuilds in a hierarchical folder structure - the Portage tree (or repository), which by default is located under. The first tree level is the package category, which is used to organize packages into groups which have broadly similar functionality. So, for example, non-core development utilities are typically placed in the category (in folder). The next tree level is the package name itself. To take a concrete example, the small utility (which, as its name suggests, displays a histogram of changes implied by a patch file, or other  output), is located in the folder. Within that subdirectory we have the actual per-package content, specifically:
 * The  files. Each supported version has a file of format . At the time of writing, there are two supported versions (1.58 and 1.59) of in the Portage tree, so the ebuilds are located at  and . Portage supports a complex version numbering taxonomy which, for the most part, reflects upstream versioning (discussed further below), and most packages, unlike, will have multiple ebuild versions available at any given time.
 * Package metadata. This is stored in an xml-format text file (one per package), named . Its contents are described here, and can contain detailed package descriptions, email addresses for upstream maintainers, documentation about USE flags etc. 's metadata file is at.
 * A change log for the package's ebuild(s). This is a text file documenting what changes have been checked in to source control over time. The filename is, so 's may be found at.
 * A manifest file, which contains digests (SHA256, SHA512 and Whirlpool) and file sizes for the contents of the package directory and any referenced tarballs (and patches, if present). It is used to detect corruption and possible tampering during package download / installation. This manifest, which may optionally be digitally signed, is stored in the file; 's therefore resides at.
 * An optional files directory. This is used to hold patches and other small files that are supplementary to the main source tarball but referenced by one or more of the package's ebuilds. The directory may be absent if unused. As (at the time of writing) does not require patches, it has no  subdirectory either.

<span id="diffstat_ebuild">A Simple ()
So what does an file actually look like, then? happens to be a good minimal example; here (at the time of writing) is what contains:

Not a lot to see, is there? That's because uses a standard 'Autotools'-style build, without patches, so the default  control flow (and invoked 'hook' functions) can do almost everything for us. Therefore, all that has to be done is:
 * to specify (via the variable) that the  makes use of the most modern package manager functionality, including built-in default behaviours (version, at the time of writing).
 * to specify a brief, (both self-explanatory) and most importantly, ; this last variable tells Portage the location from whence to download the package tarball, if it cannot find it in the Portage mirrors (the  expands out to be the package name and version);
 * to specify the (the relevant text may be found at );
 * to specify that SLOTTING is not used by this ebuild (this is an advanced feature; see below for a brief overview); and
 * finally to list the architectures for which this  applies. Here, we can see for example that it is stable (no tilde) for, but only in 'testing' (has a tilde) for.

That's all that is needed in this case, because the default functions will automatically pull down the tarball, unpack it, issue a, issue a , followed by a  (to a dummy root), after which, the program file (plus manpage etc.) will be copied over ('merged') to the real filesystem (and any prior version's files safely unmerged immediately thereafter).

There are then two main ways to invoke the ebuild. The <span id="use_emerge">first (and more common way) is via : typically, you would issue:

The second (lower level) way is invoke the directly; for example, you could issue:

which will clean Portage's temporary build directories, and then perform all the steps of the ebuild workflow, providing detailed output as it does so (you can also use the command to perform only certain steps, if you wish, and it can also create  files; see the manpage for details).

<span id="nwipe_ebuild">A More Complex ()
The example above is about as simple as a real-world ebuild gets!

However, one common additional requirement is the need to apply patches. To do this, an ebuild will typically override the ebuild 'hook' function (invoked by the standard  flow after the source tarball has been successfully unpacked), and then use the epatch utility function to apply patches held in the  directory.

For example, consider the package, which provides tools to securely wipe disks. It lives in the category. Looking in its corresponding directory we notice a number of interesting differences from :
 * there are quite a number of ebuilds (at the time of writing,, , and );
 * there is a subdirectory, containing a single patch.

Now let's look at the version 0.12-r1 of the :

Most of this should be familiar enough from the example, but there are some new elements too. Specifically:
 * the command is used to pull in two useful 'eclasses': eutils (which supplies the  function discussed shortly) and autotools (which supplies );
 * the makes use of the  variable, which expands out to the package name, without version (a full list of these convenience variables may be found here);
 * the blank definition specifies that there are no ebuild-specific USE flags (see below for a brief introduction to USE flags);
 * the variable specifies a set of runtime dependencies, and the  a set of build/install time dependencies, for the package. This is used by Portage to ensure that all prerequisites are also installed, when you ask to ;
 * the variable is used to notify the default  'hook' function of additional documentation files (in addition to those the  itself may copy over, such as manpages) which it should install;
 * the 'hook' function (which by default is a no-op) is overridden to perform two custom tasks:
 * to patch the source using the utility, using a patch file in  (the  expansion excludes revision tags). As described here,  intelligently attempts to apply patches using different  levels etc.
 * to invoke, which updates the 'Autotools' scripts after the patch has been applied.

Overlays
What if you want to modify an yourself, or add a new one? You could of course submit the to Gentoo using Bugzilla, but that only really applies to completed work you want to share. For work in progress, or private ebuilds, a different approach is required. You can't simply insert new entries into the tree, as they'll get overwritten next time you synchronize the Gentoo repository.

Portage supports the concept of overlays to address just this issue. An overlay is an additional repository, similar in layout to the main Portage tree, which Portage (by default, and as the name suggests) 'overlays' on the file structure. To illustrate, suppose you created an directory at, say,, created the subfolders and , then created an ebuild  (and manifest, ), and then set PORTDIR_OVERLAY="/tmp/myoverlay" (in ). Then, when referring to (or installing), Portage would use your version, rather than the 'official' (however, if you had created an ebuild with a lower version number, say 1.57, then by default Portage would still use the higher numbered version, from the official  'underlay').

Now, while overlays can be created and managed manually in this manner, it is generally easier to use Portage's plug-in sync system to do the job. We'll exploit this ability shortly, when we add the  overlay (which will contain a number of useful tools used in this installation walk-through).

<span id="portage_config_files">Portage's Configuration Files
Portage provides you, the user, with a great deal of flexibility. As such, it has many configuration options, specified via a set of files held in the directory (and subdirectories thereof). As our installation process is going to involve using Portage (via the command-line tool ) to download, then build and install up-to-date versions of all core system software, we first need to set up these configuration files appropriately.

The most important Portage configuration files you'll need to know about now are as follows (this is not complete - see this list for more information, and also the Portage manpage ):

<span id="atoms_and_friends">Atoms, Packages, Categories, Versions, Sets and SLOTs
Finally for this background overview, there are a few Portage <span id="atoms_etc">package mangement terms that are worth a brief recap: For more information on atom naming, see the (5) manpage.
 * As mentioned, a package refers to a homogeneous block of software managed by a single ebuild, whether third-party (e.g., ) or internal to Gentoo itself (e.g., ).
 * Packages are grouped (as leaves of a tree) into categories, which describe broad classes of functionality. For example, is in the  category (along with other network tools like  and );  is in the  category (along with other Portage applications, like  and ).
 * A package base atom simply refers to the name made up of the full category, followed by the package, without version information or other qualifiers. So for example, etc. You can find all the ebuilds in the currently sync'd tree for a given / base atom in the directory  (so, for example, ), and find more information about that base atom online at  (so, for example, https://packages.gentoo.org/package/app-portage/gentoolkit). While it is often possible to drop the category name and simply use the package itself, it's generally safer to use the base atom, since two different packages of the same name may exist in different categories (e.g.  could refer to either , an object database over SQLite, or , a computer algebra system).
 * It is generally possible to specify that a specific repository should be used to supply a package, by appending to its atom. For example,  would force Portage to install the  package from the  repository (and would fail if either that overlay was unknown, or if the  package was not present in it).
 * Any given package will normally be supported at multiple versions within Portage (one ebuild per version). Not all versions from the upstream tree may be present as ebuilds, only certain selected versions. The online package data referred to above will show what versions are available, on which architectures, and which are marked as 'stable', which are 'testing' (shown with a tilde ('~')), and which are masked (will not be installed by Portage, generally due to known problems or with the ebuild, or incompatibilities with other packages). You can fully qualify an atom by specifying its version as a suffix - generally, you take the base atom, then add a hyphen ('-'), then add a period-separated list of numbers (possibly finishing with a letter, and/or a revision suffix). So, for example, version 2.3.2 of would be written as ; version 1.14 (r1) of  as . Revisions are Gentoo  specific, they do not relate to upstream versioning.
 * When specifying atoms to Portage in certain places (such as configuration files, like ), you can either specify base atoms (meaning apply the action to all ebuild versions), or a <span id="qualified_version_atom">qualified version atom . You can qualify a versioned atom with:
 * A <span id="atom_prefix">prefix ('>', '>=', '=', '<=', '<'], to restrict the action to particular versions relative to the stated variant (for example, if you appended "" to, you'd be telling Portage to apply the use flag to any version of  at or above 2.3.1.
 * A extended prefix: there are a number of these but the most important is '~', which is used to specify any revision of the base version specified. So, for example, would refer to, ,  etc.
 * A wildcard suffix ('*'). This can be used to match any version with the same string prefix. So for example, would match, ,  etc.
 * A number of atoms may be <span id="about_sets">grouped together into a set, so that operations (e.g. reinstallation) can be easily targeted at the whole group. Sets are special names and are prefixed by '@': some of these are pre-defined in Portage (for example, the System set (Portage) set (containing vital system software packages, the contents of the stage 3 tarball plus other component dictated by your profile), or the dynamically populated Preserve-libs set (which holds a list of packages using libraries whose sonames have changed (during an upgrade or downgrade) but whose rebuild has not been triggered automatically). The World set (Portage) set refers to all packages you explicitly requested be installed (plus the set), and is contained in a file . You can even define your own sets if you like.
 * Portage <span id="slot_intro">also allows (subject to certain limitations) different versions of the same package to exist on a machine at the same time: we speak of them being installed in different SLOTs. We won't need to refer to the SLOT technology explicitly in this tutorial, but should you see a versioned atom with a colon ':' followed by some numbers and possibly other characters at the end, that's a SLOT reference. For example, with the library, it is possible to have version 2.24.24 and 3.10.7 installed in parallel, should you desire it (in SLOTs 2 and 3). You might then see a reference to, which would refer to any version of  in SLOT 3 (which would, for example, cover version 3.4.4 as well).

That's about it for this sidebar on atoms and versioning, apart from one last point: unlike other Linux distributions, you'll see no reference to 'releases' of Gentoo itself - there's nothing similar to Ubuntu's "Quantal Quetzal" or "Trusty Tahr", Debian's "squeeze" or "wheezy", Fedora's "Spherical Cow" or "Heisenbug" etc. That's because, once installed, Gentoo itself is essentially versionless - when you update your system (more on which later), all installed software updates to the latest supported versions (subject to restrictions imposed by the Gentoo developers and you yourself, through settings in, etc.).

The upside of this is that you can get access to the latest and (often) greatest versions of software as soon as new ebuilds get released into the tree. The downside is that (particularly on the 'testing' (rather than the 'stable') branch), that sometimes updates fail to complete successfully, something which is very rare indeed when using binary distributed, release-based distributions such as Ubuntu.

Time to get back to the install!

<span id="configure_compile_opts">Configuring
Our first Portage configuration task is to ensure that the download / unpack / compile / install cycle (aka 'emerging') - which you'll see rather a lot of when running Gentoo - is as <span id="parallel_emerge">efficient as possible. That primarily means taking advantage of whatever parallelism your system can offer.

There are two main dimensions to this - the maximum number of concurrent Portage jobs that will be run at any one time, and the maximum number of parallel threads executed by the process invoked by each ebuild itself.

As has been recommended, we'll set our number of concurrent jobs and parallel make threads to attempt, to be equal to the number of CPUs on the system, plus one. We'll also prevent new jobs or compilations starting when the system load average hits or exceeds the number of CPUs.

The two variables we'll need to set here are EMERGE_DEFAULT_OPTS (for Portage job control) and MAKEOPTS (to pass options on to ). These are often defined in the file, but we want to allow the values to be set programmatically. Since Portage doesn't support fancy bash features like command substitution, we'll set and export these variables in root's instead (these will then override any conflicting values in the  or profile, as explained earlier).

Start up your favourite editor: in this tutorial we'll be assuming :

is a pretty simple editor to use: move around using the arrow keys, type to edit as you would in any text processing program, and exit with when done: you'll be prompted whether to save changes if you have modified the file. At this point, enter and  to exit, saving changes, or  to exit without making changes. For some more information on the editor, see this Wiki entry.

Add the following text to the file:

Save and exit the editor.

Next, we need to make sure that the file is picked up by root's login shell, so copy across the default :

Next, <span id="setup_make_conf">on to the configuration file itself. The stage 3 tarball we extracted already contains a skeleton configuration. We'll open this file with (feel free to substitute your favourite alternative editor), delete the existing lines (in,  can be used to quickly cut the current line), and enter our alternative configuration instead (see after for a line-by-line explanation). Issue:

Edit the file so it reads:

Save the file and exit.

Here is a <span id="make_conf_summary">brief summary of the shipped ('stage 3') values are, and what our version achieves:

<span id="next_steps">Next Steps
Now we have these options configured, we're ready to into our 'stage 3' environment and start building! Click here to go to the next chapter, "Building the Gentoo Base System Minus Kernel".

<span id="prep_for_chroot">Final Preparations for the
We begin by setting up appropriate the server URIs, which portage will search when looking for source tarballs. To do this, we <span id="use_mirrorselect">use the tool (shipped as part of the minimal install system), which allows you to choose the appropriate mirror from a list, and then save the result to the  file (as an assignment to the  variable):

Next, setup a file (this specifies information about repositories in the system to Portage; see the earlier overview for a brief primer on the concepts involved). Issue:

and edit the file (removing any line, if present) so it reads:

Save and exit.

The above simply says that:
 * The main repository is set to be, for all other repositories (such as overlays) that do not specify masters;
 * The repository location is set to be (within the, that is);
 * The repository will be synced during and  runs;
 * The repository is set to synchronize using the protocol.

Next, we must specify the variable, which tells Portage where to look for the  server, when bringing your Portage tree of ebuilds up to date.

Issue:

Check that something appropriate was written to and :

Next up, we need to <span id="copy_dns_info">make sure our DNS information, which exists on our target machine's current host system at, is still available after we ; otherwise networking will stop working. Issue:

The option ensures we don't copy a symbolic link by mistake, since the host filesystem will become inaccessible once we.

Next, <span id="copy_wpa_conf">if you are performing this install over a WiFi network, copy the configuration file for  (which we setup earlier) into the  filesystem. Issue:

Then, we need to <span id="setup_bind_mounts">ensure that the kernel information in, and the special files in and  are still available from inside the. We therefore mount on, and then bind-mount  and :

Finally, we ensure that the 's and  are (recursive) slave mounts (meaning that mounts and unmounts in the 'outer' system's corresponding subtrees will propagate to them, but not vice-versa); issue:

<span id="enter_chroot">Entering the
We're now ready to change root, thereby entering our new system. After this is done, although we will still be running the minimal install kernel pro tem, commands issued from within the -ed shell will only be able to 'see' and use files (including, but not limited to, executables, libraries, and configuration files) that lie within the stage 3 file structure we just unpacked (except for the special, and  directories, of course).

Per the handbook, we'll perform the in three steps:
 * 1) Enter the, using bash as the shell;
 * 2) Reload some settings, using ; and
 * 3) Redefine the console prompt (to remind us we are in a ).

Issue:

<span id="chroot_prompt">then :

<span id="update_portage_tree">Installing an Up-to-Date Portage Tree
The next step is to install a Portage (repository tree) snapshot, a set of files that tells Portage what software is available to install, what profiles are available, and so on. These updates are produced on a daily basis. Issue:

The fetching may take some time to complete. Once done, the command may recommend some software be updated, and tell you there is news to read: if so, you can safely ignore these for now (we're about to do a ground-up rebuild anyway, and we'll get to the news items shortly).

Next, we'll bring the Portage tree bang up to date (this may also take a little time to complete):

Next, make sure that Portage itself is up-to-date:

The command, without special options, asks Portage to pull down (if necessary), build, and install the latest version of the package specified, in this case the Portage system itself. The option informs Portage not to add itself to the set of 'explicitly-user-requested' packages in the 'world' file  (Portage is already part of the @system set, via the  package, so it would be redundant to add it here). The flag set makes  ask you before making any changes to your system, and produce verbose output (generally useful, and may be abbreviated to ).

Now, if that worked OK, (you eventually see "Jobs: 1 of 1 complete" in the output after you pressed  and ), congratulations: your Portage system is functional, and you should be able to proceed.

Finally, <span id="reading_news">if you were prompted about news items being available, please take the time to read them now: these are important, short announcements from developers to users, pushed out via the Portage tree. To view the current news items issue:

You'll notice the items are numbered. To read a news item N, enter:

You can purge all read news items with:

If you like, you can read more about the Gentoo news system on its manual page (using ).

<span id="check_base_profile">Ensuring that the Base Profile is Set
As was mentioned earlier, Gentoo uses profiles to set important variables (such as, , etc.) relevant to your particular architecture and usage scenario (e.g., a machine running the GNOME desktop). Profiles also constrain the versions of packages that can be installed. This is all maintained on your behalf by the Gentoo developers.

At this point, we just need to check that we are running the baseline profile (we should be). We'll change this to the 'real' profile post-bootstrap. Issue:

And double-check that the first entry is marked with an asterisk, indicating that it is active. If not, issue:

to correct this.

You can see the various (cumulative) variables assignments (to etc.) associated with a profile by looking at its  file, and those of its parents. Specifically, the command creates a symbolic link in. If you follow this link, and then look at the files in that directory (and in any of the directories listed by the  text file therein (transitively)), you will see how it works. Note that flags accumulate, but a flag with a minus sign in front of it gets removed from the list.

You can also see the net effect of the profile, your, environment etc. by issuing (this is a useful sanity check):

Lastly, if you are unsure of the meaning of any use flag, you can look it up as follows:

<span id="set_timezone">Setting Up Timezone and Locale
We don't have a timezone or locale set yet. So let's fix that now.

First up is timezone. You can find the available timezone in (generally, you'll have to check the subdirectory too):

Choose an appropriate location, and place its relative path into. For example, to set <span id="set_europe_london">London, in the UK, you would use:

Now, we need to reconfigure the package; this will pick up the value from  and reflect the correct value in. The latter is necessary for the system C library.

Secondly, we must <span id="modify_locale_gen">set an appropriate locale. You must specify the locales you want to use in. Edit this file (using your favourite editor, such as ), and uncomment those that you want. If necessary, add additional locales to the end of the list. For example, as there are no UK locales on the list (UK = United Kingdom, approximately the same ^-^ as Great Britain = GB) use we would need to add those as follows:

Then append (for this example):

Save and exit the editor.

Next, we must run to create the locales, based on the information in the  file:

Assuming that completes successfully, you then must then specify the default locale to use. Find the system list with:

Choose the appropriate value from the list. At this stage, I recommend you stick with the 'C' (default) locale (other setups can cause issues with the indirect / remote connection); we'll switch to your actual locale later on. Issue:

Now, reload your environment:

<span id="set_post_boot_keymap">Setting Up (Post-Boot) Keymap
We also need to setup a keymap, both for use post-boot, so that you will be able to type commands correctly when typing directly at your machine's keyboard.

We begin by displaying a list of keymaps, and filtering out those of interest. The Panasonic CF-AX3 has a Japanese layout, but obviously your machine may differ. Issue:

Review the list, and choose a keymap file relevant to your location. In my case for example, there is one appropriate result,. Strip off the suffix to get the appropriate name: in my case  (yours will obviously vary, depending on your actual keyboard). Now we can setup the (virtual console) keymap. Issue:

and edit the  line, to cite the string you just found. For example, in my case:

Leave the rest of the file as-is (unless you know there are other changes you need to make here), and save and exit.

<span id="set_cpu_features">Informing Portage of Processor-Specific Features (Optional)
In the last chapter, we left the blank in  (you will recall that this variable is used to inform Portage about any processor-specific features (such as MMX, for example) available on your machine). Now, if you like, we will fill it out, using the tool to help us.

If you do want to set, first emerge the query tool (we'll use  here, to avoid adding it to your @world set):

Now, run the tool and note its output (yours may well differ from the below, which is taken from the Panasonic CF-AX3):

Issue:

then copy the line just output by in place of the existing  definition. Save and exit.

<span id="prep_for_parallel_emerge">Preparing to Run Parallel s
We have (intentionally) set our Portage system up to maximize parallelism when emerging. However, a side-effect of this is that, because multi-job support is active, does not show any console build output, just a summary progress display.

This is easily fixed, using a simple script, which will show us the latest lines from both the Portage background tarball download log and from the most recently updated build log (Portage builds its projects in  by default). I have provided this and some other necessary utilities for this tutorial in a GitHub overlay, which makes them straightforward to install and keep up to date within Portage (for details of overlays, see the background reading section earlier).

To begin with, we'll first install the Wikipedia:Git_(software) source code management software, as we'll need this to be able to synchronize the overlay from GitHub. Issue:

Next, we need to tell Portage about our overlay, by adding an entry into the directory. Issue:

and add the following content to that file:

Save, and exit.

The above simply specifies that:
 * The repository is called ;
 * It should be cloned to the directory;
 * It is a git archive, which may be synchronized via the URI https://github.com/sakaki-/sakaki-tools.git;
 * It has 'priority' 50 (ebuilds with higher priority override those of lower priority, in the event of a name clash; the default tree has priority -1000); and
 * It will be automatically synced during during or  runs.

Next, we'll pull in the overlay itself. Issue:

<span id="overlay_hygiene">Whenever using a third-party overlay such as this one, remember that it will (in general, due to the 'priority' setting) take precedence over your 'real' Portage tree (the one it 'overlays'), in case of conflicting ebuilds. For this reason, it is prudent in such cases to:
 * 1) mask (blacklist) all packages from the overlay, then
 * 2) unmask (whitelist) only those packages from the overlay you explicitly know you want, then
 * 3) read the contents of those remaining, unmasked overlay ebuilds before installing (emerging) them.

We'll begin by wildcard-masking everything from. As described earlier, we'll use a file in the directory for this. Issue:

Now we can unmask what we explicitly need (using, as described earlier, files in the directory). Issue:

Here is a brief summary of what the above (whitelisted) ebuilds are, and what they do:

Next, note that all user overlay ebuilds (by stipulation) must specify that they are on the 'unstable' branch (since not yet fully tested). However, we are allowing (by default) only stable packages (see above), we have to specify that for the above packages, the unstable/testing ('tilde') branch is acceptable. We use a file in the directory for this, as described earlier. Issue:

Next, if you like, take a look through the files in the overlay (and any patches), read the underlying sources, and satisfy yourself that everything is benign. It is good hygiene to do this, particularly prior to using a third-party overlay for the first time.

Now, with that setup done, <span id="install_showem">we can now install the tool using the standard  command. Issue:

And that's installed! We're about to do quite a lot of building, so it'll be useful to <span id="second_virtual_console">set up a second virtual console, from which we can view the progress of using our new script. Assuming you are running (as discussed earlier), press  then  to start a new console. Then in that new console (which is back outside the, to begin with) enter:

followed by

Now hit then  to get back to the original console, and continue.

<span id="bootstrapping_base_system">Bootstrapping the Base System (Optional but Recommended)
We are about to perform the bootstrap proper! In the below, we will follow the Gentoo FAQ's advice on how to recreate a 'stage 1' bootstrap in the modern age ^-^. (However, if you are content to rely on the shipped binaries, click here to skip this step.)

Note that here, bootstrapping refers to the process of:
 * 1) building (from source) the standard toolchain (GCC compiler, linker, assembler, C library and a number of other items), i.e., the components necessary to build the other software and libraries that make up Gentoo's World set (Portage) package set; and then
 * 2) using that newly constructed toolchain to rebuild everything in the World set (Portage) package set, from source.

And the point of this whole exercise? Simply put, it is to ensure the integrity of the end binaries, as far as we can. To reiterate: we will first build the core tools from source, using (by necessity) the existing toolchain binaries that are shipped as part of the minimal 'stage 3' filesystem (which we're currently -ed inside of). We then use this newly built toolchain to rebuild (from source) all the shipped software in the stage 3 tarball (plus that which we've explicitly emerged, such as ). Once this has been done, we verify that all libraries and binaries (apart from the kernel, which we haven't built yet) have indeed been regenerated, and that no old binaries or libraries are still lying around.

In Gentoo parlance, people speak of three 'stages' of bootstrapping (and their corresponding file system tarballs):
 * 1) Stage 1: When starting from a stage 1 tarball, the base toolchain (GCC, standard C libary etc.) must be built using the existing (binary) host system toolchain, under direction of the  script. This yields a:
 * 2) Stage 2 system. Here, we still need to  (build) the core World set (Portage) package set, using our new toolchain. This yields a:
 * 3) Stage 3 system, in which the toolchain has been bootstrapped, and the important system binaries and libraries have been compiled using it. A tarball of such a stage 3 system's directories is now provided as a default part of the Gentoo distribution (stage 1 and stage 2 tarballs are not available to end-users anymore).

Although we have already downloaded a stage 3 tarball, we're going to pretend we haven't, and instead build up from stage 1.

<span id="bootstrap_from_1_to_2">Gentoo Bootstrap Remix: Progressing from Stage 1 to Stage 2
Right, let's get going. First, we'll need to build ourselves a toolchain! We'll switch to the correct directory, and then do a dummy run to see what the supplied script wants to do:

then

Start the build for real this time:

This will take a while! You can <span id=use_showem>now switch to the second console we prepared earlier, and see what is going on (as the files download, build etc.). Hit then  to switch to the second console (you can do this while the bootstrap is running), and issue:

You can now switch back and forward between the two windows as you like (using then  to cycle forwards, and  then  to cycle backwards - identical in function here where we only have two windows active), which should give you a good overview of the bootstrap process as it progresses.

Assuming the script completes successfully, you next need to check your GCC configuration (since we just rebuilt the compiler, and possibly upgraded it too). Switch back to the first console (hit then ), and issue:

(That's an 'ell' by the way, not a one!) If the output tells you your current config is invalid, enter:

(That's a one this time, not an 'ell'!)

Next, we'll run the script again, to ensure that everything in the toolchain (including early dependencies, such as  and ) have been rebuilt using the new compiler, and are then themselves used in a rebuild of that compiler:

Now, just as above, you can switch back and forth between the two consoles, to review the progress.

Once the toolchain bootstrap has completed (for the second time), we're ready to rebuild all the other binaries using it. You shouldn't need to reset the GCC profile this time around, but just to be on the safe side, double-check it is valid:

And finally, revert back to the root directory:

<span id="bootstrap_from_2_to_3">Gentoo Bootstrap Remix: Progressing from Stage 2 to Stage 3
We now need to build everything in the World set (Portage) package set, using our shiny new toolchain.

Before we start, we need to <span id="create_build_timestamp">write a null 'timestamp' file, which we'll use as a marker when checking later that all our executables and libraries have indeed been rebuilt. Issue:

Right, with that done, we are ready to build everything in the World set (Portage) package set, including all the libraries upon which they depend, as follows:

Here's what those parameters mean (see also the emerge manpage):

After some time, the build will hopefully complete successfully (if it does not, please see the troubleshooting section, below).

Assuming you modified your file and/or  file earlier (see here and here), then Portage will probably prompt you with:

in the output from the full run. This is <span id="using_dispatch_conf">easily dealt with, using the Handbook:AMD64/Portage/Tools tool (and it's good hygiene to run this anyway, after a large build session). This utility exploits the fact that Portage does not install packages directly to the filesystem, but rather uses a sandbox approach. As a result, it will not directly overwrite files in directories protected by the variable (includes most files under  in a standard setup, you can use  to see the full details). Instead, it writes the new configs to .cfg0000_ files. lets you step through each of these conflicting files in turn, shows you a Wikipedia:Diff between your current version and what the install wanted to write, and asks you what you want to do.

Enter:

Then follow the prompts to review each proposed change. Assuming only the and/or  need modifying (should be the case at this stage), then you simply need to press  for each file when prompted. This means (rather non-obviously) 'zap-new' - or in other words keep the version of the file that was there before the was initiated. Once this has been done, should exit automatically.

If everything worked fine, then you can skip ahead to the next section; otherwise, here are a few tips on how to rectify any problems that may have occurred.

<span id="troubleshooting_failed_build">Troubleshooting a Failed Build
Generally, s, even of the full World set (Portage) set, go without a hitch. However, if you elected earlier to use the '~amd64' (aka 'testing') phase ebuilds, issues will sometimes pop up. For example, here's a problem that happened during the writing of this guide, when attempting the stage 2 -> stage 3 (I was using the testing branch then, since GNOME 3 had not been stabilized at the time - nevertheless, it's an instructive example):



In this case, a build failure occurred while emerging the package. Here are some steps you can take if this kind of thing happens to you (this is not an in-depth guide - for that see this section from the Gentoo handbook):


 * If you are building on a system with little RAM (e.g. an old computer or a virtual machine), you might be running out of memory. On a VM, consider shutting it down, giving it more RAM, starting it again, and chrooting back into your installation if you still don't have a bootable system; you will be able to resume your build with emerge --resume. Alternatively, you might be running way too much build jobs and too much concurrent compilations; in this case, go to /etc/portage/make.conf and crank down the -jX parameter on MAKEOPTS, then go to /root/.bashrc and crank down the --load=Y and --jobs=Z parameters on your EMERGE_DEFAULT_OPTS. If your build still fails, try creating a paging file on your hard drive and enabling it to have at least some extra virtual memory as follows:
 * Sometimes, intermittent issues occur due to the very parallel build architecture we have specified. These issues will often resolve themselves if the build is recommenced. Fortunately, there's a flag for that. Issue and  will try to pick up where it left off, with all the same settings. Alternatively, you can try to resume the  with parallel  temporarily switched off; to do so, issue  If that works OK, great, you're done. If not, proceed to the next step.
 * Since you are (at the moment) running on a fairly 'vanilla' system, it's likely that others will have seen the build problem you're experiencing, and have already reported it. Gentoo has a pretty quick turnaround for fixes, which are posted to the Portage (ebuild) tree when signed off. Therefore, the next-lowest-overhead way to fix a build problem is simply to wait a little while (if it's a major issue, you shouldn't have to wait long), then resync Portage, and try the again (NB, but not using  here, since we've sync'd in between):  Hopefully, that fixed your problem. If not (or you don't want to wait), keep going...
 * Look at the full build log. As the build has failed, this will still be in somewhere - indeed, in this example, the actual file is at . Have a read. Having done so, try searching for any appropriate-sounding errors using Google (or, if you want to use an anyonymized wrapper around the Google search engine, Startpage). For example, here the text is quite specific and suggestive. A Google search for "" yields a relevant hit: a post on the Gentoo discussion forums: "mesa-9.2.5 fails, egl_gallium/llvm related". A quick perusal shows us we have found the correct problem, and that it is related to, a problem with the package . In short, it appears that there is a problem with the default-use-flag build of , it's just that it shows itself in the build of . You can now try to:
 * 1) Work around the problem, per the information you have found. For example, in this case, you could try appending  to the  file (see this earlier discussion of atoms and ../Installing_the_Gentoo_Stage_3_Files if you're unclear as to what this means) and issuing the full   again. Just don't forget that you have that you have made this change - and do try to come back and see if you can revert the fix later! (were a new ebuild for LLVM to be released, for example).
 * 2) Try using an earlier version of the affected package (this is, in fact, the approach I adopted at the time, although it was rendered moot by the stabilization of GNOME 3). You can do this using the  file (discussed earlier), which tells Portage the versions of software not to allow. Here, we could try preventing Portage from using the 3.4 version of, by adding  to  (forcing Portage to reject it), then re-emerging. In this case, from the online package information grid for LLVM, we can see this will drop us back to version 3.3-r3 (remember, I was on the testing branch). This approach generally works, but be warned - you may end up rolling back quite a lot of other packages when you mask in this way. Furthermore, if you adopt this approach, always be sure only to mask the specific version that has the problem (use '=' at the start of the  line, per our earlier discussion of atoms), as this means when a new (hopefully, fixed) ebuild is released (with a higher version number), Portage will automatically attempt to try to use that instead.


 * If you have switched your Portage profile and some toolchain-related packages like refuse to build, try building  first, as some profiles like hardened require rebuilding the toolchain with different USE variables. Depending on your attention to detail, you can just issue a simple  and then, or you can outright boostrap your system again. Refer to Hardened FAQ: How do I switch to the hardened profile for further info.

Finally, here are some miscellaneous hints that you may find useful:
 * 1) Check that your  configuration is set correctly, especially if you have recently upgraded your GCC installation - if it is invalid, builds will often fail in hard-to-debug ways. To do so, issue:  (That's an 'ell', not a 'one'!) If it returns  (or ), then specify an appropriate one from the list presented; for example, to select the first configuration in the list, issue:  (That's a 'one' this time!) If you do change your  profile in this way, be sure to issue:  to modify the settings in your current shell, before retrying any emerge.
 * 2) Check that your  libraries are up-to-date. This will not always be handled properly by Portage, but you can use  to bring things back in line. Issue:  If your system detects stale Perl libraries and they all fail to build, try rebuilding Perl itself:
 * 3) Ditto for . Issue:  and then re-attempt the failed.
 * 4) Ensure that  is set to the latest version, if it is present in your system (if the following  command returns an error, you do not). Certain things like  require an up-to-date version. Issue:  to see a list of available versions, and then:  to choose one.

Then re-attempt the failed.

<span id="verifying_bootstrap">Verifying the Bootstrap (Optional but Recommended)
Congratulations - by this point you have performed a 'stage 1' bootstrap, and so all the (binary) applications and libraries within the current should have been recompiled. Just to make sure that nothing has sneaked through (i.e., an app or library somehow included in the stage 3 tarfile we downloaded earlier, but not present in the deep transitive closure of the World set (Portage) package set), we'll check the datestamps of all relevant components against the we wrote before commencing the. We aren't worried about any text executables (such as scripts) since, in principle, these can be audited to ensure they are not malicious.

First, remove any installed packages that are not part of the dependency tree, so that the following test is not confused. Issue:

Let this process run through to completion (it may take a little while). Then issue:

This command finds all executable files (except beneath the EFI mountpoint at ; which will host a FAT filesystem - in which all files appear executable - when mounted (it currently shouldn't be mounted though, assuming you've been following the tutorial flow, but the is there for robustness)), which aren't newer than the checkpoint file, then tests their file type using, and prints them if they are not recognized as some form of text file (script, source code etc.). It should produce no output (as all files of this type should have been recreated, if our bootstrap was complete).

So much for executable binaries - what about libraries (shared or static)? On Gentoo, we'll have already checked most shared ('.so') libraries, since they have their execute bits set. However, this is not true for all flavours of Linux, and furthermore, static ('.a') libraries (and '.o' object files) do not have the execute bits set. Therefore, to be double-sure, we'll run another test (this may take some time to complete):

This looks for any files which aren't newer than our checkpoint file, and which are recognized by as ELF or ar archives; it may take some time to complete (as there are a lot of files to check). Again, it should produce no output. If so, and the previous check also worked, then congratulations, you have fully rebuilt all executable binaries and libraries on your machine!

<span id="choose_systemd_or_openrc">Choosing between systemd or OpenRC Init
At this point, you need to choose which init system you want to use on your target machine: systemd or OpenRC.

is the default choice, since a 'vanilla' (unpatched) GNOME 3.8+ system requires it to run properly. It is currently the most widely adopted init system amongst Linux distributions.

However, please be aware that there is now an alternative, for those who would rather not use. This involves installing a patchset provided by Dantrell B., which enables Gentoo users to enjoy the full GNOME experience (including session tracking and power management) under Gentoo's own init system (OpenRC).

If you choose to go the route, and so use Dantrell's patchset for GNOME (full instructions for which are provided in this guide), please be aware that, as with any third-party overlay:
 * you may find it more difficult to get support via the normal Gentoo channels (the forums etc.) when using an 'unofficial' patchset such as this one;
 * security fixes etc. may take longer to be released, and the overlays may themselves contain security holes;
 * the patchset's author (Dantrell B.) may cease support for this patchset in the future.

Having said that:
 * the vast majority of the GNOME code is unaffected by the patches;
 * the patchset code itself is largely shared with Funtoo, who use it in their mainline distribution, so you will not be alone;
 * Dantrell B. has stated his intention to support this patchset for Gentoo (at least until either a proper answer for the GNOME/systemd issue is arrived at, he ceases to use GNOME, or the complexity gets out of control).

Ultimately, as with all things Gentoo, the choice is yours ^-^

When you have decided, continue as below:
 * For, follow the "Option 1" text below, and then read the rest of this guide following the 'default' flow. Do not follow "Option 2" or read any of the 'alternative track' chapters (they are clearly marked). Be sure also to follow any specific instructions in chapters 8 and 9 that are marked for the attention of users; or
 * For, follow the "Option 2" text below, and then read the rest of this guide, following the 'alternative track' for Chapters 10 onwards (you will see the branch point clearly marked at the end of Chapter 9). Be sure also to follow any specific instructions in chapters 8 and 9 that are marked for the attention of users.

<span id="choose_systemd_profile">Option 1: Setting a systemd Profile
OK, so let's <span id="set_systemd_profile">set our Portage profile to the version we actually want to use going forward (we avoided doing so earlier, to minimize the scope of the bootstrap).

Issue:

The current (default) profile is shown marked with an asterisk. However, the most correct profile for our purposes is the 'desktop' variant that cites GNOME and. In the above list, this is number 5 (but your output may differ, so be sure to check).

To switch, issue:

Now, continue reading at "Updating @world to Reflect the New Profile", below (i.e., please skip the "Option 2" text below, as it does not apply).

<span id="choose_openrc_profile">Option 2: Adding Overlays and Setting an OpenRC Profile
To use GNOME with OpenRC, you will first need to install a few custom overlays, to apply Dantrell B.'s patchset for GNOME (see the background reading section earlier for a brief overview of overlays).

At the time of writing there are five overlays to install: a 'common' one, and one for each of GNOME 3.14, 3.16, 3.18 and 3.20. We'll create configuration files in for each of these.

Begin with the 'common' overlay; issue:

and enter the following text:

Save, and exit.

The above simply specifies that:
 * The (common GNOME) repository is called ;
 * It should be cloned to the directory;
 * It is a Wikipedia:Git_(software) archive, which may be synchronized via the URI https://github.com/dantrell/gentoo-overlay-dantrell-gnome.git;
 * It has 'priority' 150 (ebuilds with higher priority override those of lower priority, in the event of a name clash; the default tree has priority -1000); and
 * It will be automatically synced during during or  runs.

Next, the 3.14 overlay. Issue:

and enter the following text:

Save, and exit. (The contents should be self-explanatory).

Then, the 3.16 overlay (it is fine to have multiple versions installed, the profile, which we will select shortly, will decide which takes precedence). Issue:

and enter the following text:

Save, and exit. (Again, the contents should be self-explanatory).

Then, the 3.18 overlay. Issue:

and enter the following text:

Save, and exit.

Then, the 3.20 overlay. Issue:

and enter the following text:

Save, and exit.

Now, pull in the overlays:

The Dantrell overlays we just installed provide (inter alia) a bundled set of Portage profiles; these allow you to conveniently set flags, masks etc. and thereby ensure that subsequent installation of GNOME proceeds smoothly.

Accordingly, we next <span id="set_openrc_profile">set our profile to the version we actually want to use going forward (we avoided doing so earlier, to minimize the scope of the bootstrap).

Issue:

(Your output may vary.)

The current (default) profile is shown marked with an asterisk. However, the most correct profile for our purposes is the 'extended' variant whose version matches the current 'stable' version of GNOME in mainline Gentoo. To find out what version this is (actually, any of 3.14 through 3.18 inclusive, at the time of writing), consult the table in, and look for the green box with a plus sign in it, under the heading.

Having found the stable version of GNOME, select the appropriate profile; for example, to use GNOME 3.14 (one of the 'stable' versions at the time of writing), issue:

Check that the new profile is now active:

The output you see may differ from the above, but should reflect the profile choice you just made.

Having now successfully set up the appropriate custom profile, continue reading below.

<span id="update_world">Updating @world to Reflect the New Profile
Having chosen a target init system ( or ), and selected the appropriate profile, we must update set, to pull in (and build from source) any new packages required, and to reflect any USE flag changes to existing packages (by rebuilding them as necessary).

Issue:

Here's <span id="world_update_params">what those parameters mean (see also the emerge manpage):

Whether or not warns you that you have configuration files that need updating as a result of the above update, it is good hygiene to run:

Then follow the prompts to review each proposed change, if any.

<span id="next_steps">Next Steps
Having successfully built the set for our new profile, we can now turn our attention to the heart of the system: the Linux kernel itself. Click here to go to the next chapter, "Configuring and Building the Kernel".

Introduction
So what is the Linux kernel anyway? In essence, it's a privileged, pre-emptive, multitasking resource manager. As such, it's the core element of the operating system, because all 'normal' software (including operating system programs like and )  must go via the kernel to access system hardware (such as disks, screen and keyboard), to request or release system resources (such as memory), or to communicate with other 'userland' software (as the kernel maintains user processes in distinct virtual memory 'silos').

The kernel is not built using the normal procedure -  will fetch the necessary source files for us, but configuration, compilation and installation is separate. Configuration here refers to the process of setting (or in come cases, commenting out) key-value pairs in a special file. This file sets vital kernel parameters (such as the kernel command line, in the case of a UEFI-bootable system), and instructs the build system which kernel components (including drivers) to omit, which to build as loadable modules ('.ko' files), and which to build in to the kernel itself.

Before continuing, it's worth saying a little bit about the EFI boot process here. When your PC boots up (in EFI mode), the UEFI BIOS loads from ROM and runs. Once it has performed initial hardware configuration, this BIOS then looks for any runnable EFI software, proceeding through a list of possible locations (which must be EFI system partitions, if they are storage devices) as specified by you via the BIOS setup screens (or the EFI boot list variable). If it finds such an executable (on 64-bit x86 machines, normally, the filename is not (usually!) path sensitive), it will load this and run it.

Traditionally, this program would be a bootloader, whose job it would be to load and run the operating system proper. However, modern Linux kernels can be configured to appear as runnable EFI programs, obviating the need for any separate bootloader, and this is the approach we're going to take.

However, there is one wrinkle to overcome. When our EFI kernel is started, it needs to invoke various userland software (such as, and various LVM programs) to activate and access the encrypted volumes we created earlier: but those programs are themselves stored... within the very encrypted volumes we wish to unlock!

This is <span id="initramfs_intro">worked around by using an initial RAM filing system, or initramfs, which is a simple archive (like a Wikipedia:Tar_(file_format) archive, but using an older format, known as Wikipedia:Cpio) of a minimal Linux root filesystem. This initramfs contains only those userland programs (and the libraries and other files on which they depend) which are needed to boot the system (including a special init program, which we'll get to shortly). Although the use of an initramfs is reasonably commonplace with Linux systems (to start up LVM for example), we elect to include the archive within the kernel file itself, so it will be protected by the secure boot signature (once we add it).

So, the actual boot process we'll be aiming to utilize is as follows:
 * 1) The UEFI BIOS starts up, and initializes the hardware. It looks for, and finds, an executable .efi program (our stub-loadable kernel) on the USB key, so it loads this and passes off control to it. (If secure boot is on, it will also check that the kernel image contains a valid cryptographic signature, but we'll get to that in a later section ( track,  track).)
 * 2) The kernel starts up and initializes. It unpacks its bundled initramfs into memory, and activates it, which provides a root directory containing a skeleton set of system files (a bit like the contents of our stage 3 archive, but much sparser).
 * 3) The kernel then looks for a special 'init' program in the initramfs and starts it (as the first userspace process).
 * 4) This initscript, which is actually provided by a Gentoo utility called  (more of which shortly), prompts the user to enter a password, unlocks the .gpg keyfile (also on the USB key), and uses the resulting binary plaintext to unlock the LUKS partition. It next activates the LVM volume group on that partition ( in our case), and mounts any logical volumes (LVs) within it, as dictated by the file . This mounts the swap, root and home LVs.
 * 5) At this point the 'real' filing system is in place, and the initramfs (apart from,  and ) is discarded, using . The init script ends by invoking the 'proper' init system on this newly mounted root - which, depending on your earlier decision, will be either the  daemon, or the  init process. In either case, this 'real' init handles the boot from that point onwards.

Getting all of this to work correctly out of the box is complex, so I've provided a simple script which automates the process, and which should enable you to create a bootable EFI kernel with minimal fuss, which we'll install from the  overlay shortly.

So, let's go build ourselves a kernel!

<span id="downloading_kernel_source">Allowing Necessary Licenses and Downloading Kernel Sources and Firmware
Our default allowed license group, which we set earlier, does not by default enable the 'freely distributable' requirement of the kernel sources (or that of ), so we'll need to add that to our permitted license overrides (by creating an appropriate file in the directory).

Assuming that you are not intending to deblob your kernel (please see following note; most users will not wish to deblob), also issue:

Right, let's fetch the kernel sources:

<span id="install_firmware">And the firmware (assuming you are following our default options, and not deblobbing):

Now we need to quickly double-check that the symbolic link in is pointing to the correct place. Issue:

and check that the output of this refers to the same kernel version as following:

(the current default will have an asterisk marking it).

<span id="emerging_buildkernel">Emerging, and Additional Required Packages
We now have the necessary sources downloaded but, in order to proceed, there are two additional packages we should first. These are:


 * This is the master build script, supplied from the overlay (as described earlier). It pulls in a number of additional packages through its dependencies.
 * This contains a number of tools for working with UEFI, including commands to manipulate UEFI secure variables, which we will need when setting up secure boot.

Prior to emerging these, there are a number of package-specific use flags we'll need to set (some of these are in anticipation of dependencies). Issue:

Here are what those flags do:

Next, we can the packages themselves. <span id="install_buildkernel">Issue:

and wait for the build to complete.

<span id="ensure_static_gpg">Checking we have a Minimal, Static (Without )
The <span id="staticgpg_intro">installation of (which you have just performed), should have caused a special, static version of  version 1.4.16 - called  - to have been installed on your system. The original (standard, v2.x) should be present as well (since it's part of the @system set for this profile).

As both versions are important to the proper functioning of your system, we need to check they are present and correct. Issue:

and verify that, per the messages produced, you do indeed have a v2.x and v1.x installed.

You can also verify that the binary is statically linked:

<span id="setup_buildkernel_conf">Setting Up 's Configuration File
Finally, before we can use the utility, we have to set up its configuration file. An initial version has already been copied to when you emerged, earlier. However, you must at least <span id="important_conf_vars">specify the following shell variables:
 * - the UUID of the first (EFI system) partition on your USB boot key.
 * - the UUID of the LUKS partition which you created on your target machine's main drive.
 * - the keymap to be used by the console early in the boot process. This is important for the passphrase protecting your LUKS keyfile to be recognized correctly. If you leave it commented out, the keymap will be used.

You made a note of these UUIDs earlier in this tutorial (where we referred to them as the partition UUIDs of and, respectively). If the  was able to identify them unambiguously (i.e., for, only one EFI system partition on a USB device could be found, and for , only one LUKS partition could be found), then these will already have been set for you, when you emerged , above. In any event, you must check to make sure, because if these values are wrong, you may not be able to boot your new Gentoo installation successfully.

There are two ways to check (and, if necessary, fix) your setup: manually, or via 's built-in menu-driven tool:

<span id="manual_buildkernel_conf">Option 1: Editing Manually
You can always modify the configuration manually. To do so, issue:

And then:
 * uncomment (if 's was able to identify only one such matching partition on a USB device, this will already have been set for you and uncommented, but you should check) the line setting, and make sure that it refers to the partition UUID of ;
 * uncomment (again, 's may already have set and uncommented this for you, but you must check) the line setting, and make sure that it refers to the partition UUID of ;
 * if not using the US keymap, uncomment the line setting, and make sure it refers to the correct keymap (in the case of the CF-AX3, for example, we'd set ).
 * if you chose to use (rather than ) init earlier, uncomment the line setting  (and make sure it reads  ). If you are on the default  install track, you should leave the variable commented out.

<span id="assisted_buildkernel_conf">Option 2: Editing Using
As it is important to get these settings correct, and easy to make a slip-up when manually editing a configuration file and copying UUIDs around, the program provides a menu-driven helper to conform.

To use it, simply issue buildkernel --easy-setup, and follow the prompts, making sure to save and exit when done. You can mix and match manual editing and using ; when you run, any conflicting changes in your file will simply be automatically commented out, and any new definitions will be written to a delineated block at the end of the file.

The below shows a typical configuration run; obviously your values (UUIDs etc) will differ, as may the menu selections you need to make:

Your configuration file should look something like the below, after running (obviously, your values will differ, depending on the choices you make, and the UUIDs etc. on your target machine):

Note how the changes made by have been added in a block at the end of the file. You can manually edit the file now if you like, but avoid making changes within the "" block, as definitions within it can be overwritten next time is run.

<span id="what_buildkernel_does">What the Script Does (Background Reading)
Right, so now we're ready to build the kernel, using the script to do all the heavy lifting for us.

The script carries out the following steps in order:
 * 1) Reads your  file;
 * 2) Mounts the EFI partition if not already mounted (to );
 * 3) Enters the  directory;
 * 4) Copies a  file from the currently running kernel (via ) if no config already exists in, and sanitizes/updates it with ;
 * 5) Conforms the, by setting various key parameters that are required for the kernel to boot successfully in EFI mode with  or  (we review these below), including the rather gnarly kernel command line (which contains directives targeted both at the kernel, and at the  script provided by );
 * 6) Calls your user hook function  if you have defined it in  (you'll only generally want to do this to override unwanted changes made by  in the above step; other changes should be made via the standard  route, per the step below; they will be persisted);
 * 7) If in interactive mode (set by the  option), allows you to <span id="make_menuconfig_step">modify the resulting configuration, if you choose, using the standard menuconfig tool (see this wiki entry for a brief set of usage instructions); (it's fine to elect not to, however, in which case the conformed  will be silently sanitized/upgraded with , as it will in non-interactive mode);
 * 8) Cleans the kernel tree (optionally, you can force this with the, and you will be asked in interactive mode);
 * 9) Builds the kernel, and its modules, with the specified configuration; in this first pass, an empty initramfs is used (since it must be incorporated in the kernel, to be protected by UEFI secure boot, but we don't have everything necessary to include in it, yet!);
 * 10) If required (via the  option) builds any external modules (such as those required for VirtualBox), using Kernel/Upgrade;
 * 11) Creates a first cut of the initramfs using genkernel (see below for more details); this will contain 's  script, compiled modules, any necessary firmware (if you haven't deblobbed), and a minimal set of binaries; it does not at this point contain a static copy of ;
 * 12) Unpacks the initramfs, to the  directory;
 * 13) <span id="copy_static_gpg">Modifies the initramfs by copying  directory contents across to it, and copies the  binary we discussed earlier, renaming it as  (if  does not exist,  will  it);
 * 14) Calls your user hook function  if you have defined it in  (you don't need it to make the boot work);
 * 15) Repacks the initramfs into  (the unpacked copy is left at  too, for reference, since it's useful to be able to see what is in this archive at a glance);
 * 16) <span id="initramfs_into_kernel">Builds the kernel a second time (to incorporate this 'real' initramfs); this is a quick process as most of the components are unchanged;
 * 17) If you have a secure boot key and certificate (we haven't, yet), signs the kernel so it will secure boot;
 * 18) Backs up the old kernel and config on the EFI system partition (on the USB key), if any are present;
 * 19) Copies the newly built kernel (which is configured so as to be an EFI executable), into  (the magic location expected by most UEFI BIOSes - you can change this path via ); and also copies the config to the same directory;
 * 20) If possible, ensures that there is an EFI boot entry for the new kernel, and that this entry is at the top of the EFI boot list (we aren't booted under EFI yet, so you will get a warning here instead);
 * 21) Performs a filesystem Wikipedia:Sync_(Unix) and then unmounts the EFI system partition (if you so specify).

The default behaviour of buildkernel is to run in an non-interactive mode, unless the option is passed. It is also possible to specify the option, in which case  will create a new kernel in the  staging area, but will not attempt to copy it to the USB key. This is useful in unattended contexts, when you may have the boot key removed, for security. You can then subsequently copy over the new kernel with the option. For more details, see the manpage. Issue:

<span id="kernel_opts_set_by_buildkernel">Kernel Configuration Options Conformed by
Here <span id="buildkernel_config_changes">are the values conformed by, what effect they have, and why they are set as they are (should you wish to find further information about any option, you can do this from within  (in the  directory), as instructed here):

<span id="kernel_cmd_line_set_by_buildkernel">Kernel Built-In Command Line Conformed by
At this initial stage, the built-in kernel command line will be conformed as follows (your specific values will be different, depending on what is set in,  ,  and ):

Note that the term 'kernel command line' can be a little misleading - some of these parameters are indeed consumed by the kernel (a reasonably complete list of which is provided by kernel.org ); however, others are really targeted at the script. The Linux kernel passes the script (or program) any parameters it has not already processed as arguments, and the  script can also read the full command line in any event, via.

The various parameters in the above are explained in the table below:

If you wish to override any of these, simply set the appropriate variable in (of course, per the earlier instructions, you must at least set  and, and possibly , to get a bootable kernel). You can also specify additional kernel command line options, in the variable. For example, one common additional option you may wish to set would be to <span id="enable_trim">enable passing TRIM commands down to the underlying LUKS partition (if using a solid state drive, to prevent performance degradation as the device fills up). To accomplish this, you would set in  (this is then passed on by 's  script to ). You can specify multiple additional options via this variable, if you need to; simply separate them with a space.

<span id="genkernel_opts_used_by_buildkernel"> Options Used by, When Creating initramfs
The script calls the Gentoo utility Genkernel (from package ) to create the initramfs. It does this because provides some very useful features, for instance:
 * a significantly evolved script, which deals with e.g., the set up of a root directory using LVM over LUKS, prior to handoff to the 'real' init system ( or ) on the unlocked root;
 * automatic inclusion in the initramfs archive of not only (the minimal set) of necessary binaries, but also the libraries upon which they depend (if dynamically linked);
 * dealing with the installation of firmware and kernel modules to the initramfs; and
 * managing the use of the boot splash manager, if specified.

is also capable of building the kernel itself, but since it does not provide the UEFI and secure-boot hooks yet, we do not use it for this, preferring our script instead.

When invokes, it does so using the following command:

These options override anything specified in, and have the following description and rationale for use:

That concludes our brief tour through some of the internals of. Now we can get on and use it!

<span id="build_using_buildkernel">Building the New Kernel (Using )
So, without further ado, let's <span id="first_buildkernel">build the kernel.

Make sure your boot USB key is plugged into the target machine, then issue:

This will take some time to complete during the first pass, since all kernel components must be built from scratch. Subsequent runs of should complete much more quickly, provided you answer  when prompted if you want to  (there's generally no need to, unless you experience some strange build problems, or are building a new version for the first time). Furthermore, the next time you run, it will use the configuration now saved in the file, rather than the currently running kernel's configuration (read from ).

<span id="next_steps">Next Steps
Assuming that completed successfully, congratulations, you have just built a UEFI-bootable kernel! Just a few more minor configuration steps to perform, and we'll be ready to try it out. Click here to go to the next chapter, "Final Preparations and Reboot into EFI".

<span id="setup_fstab">Setting up the Mountpoint Tables
Per the Gentoo handbook, we first need to setup, 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 earlier):
 * 1) the root partition, which holds the system software, configuration files, and the superuser's home directory (device file path );
 * 2) the swap partition, which is used to extend the system's available memory, and can also be used for hibernation (device file path ); and
 * 3) the home partition, which holds the home directories of normal users (device file path ).

We need to add entries for each of these to fstab; so issue:

and then edit the file, so that the only uncommented lines (those not starting with a symbol), are as follows:

If you have a cd-rom drive on your machine (the Panasonic CF-AX3 does not), you can also add the following additional line:

Save and exit.

In the file:
 * The first field describes the path to the partition's device file (NB - when this file is referenced, the initramfs-based 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).
 * The second field shows the mount point.
 * 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 for the optional cd-rom makes the operating system guess the filesystem type, which is useful with removable media.
 * The fourth field contains the mount options; these choices here are described in more detail below.
 * The fifth field is used by the command to denote which filesystems require dumping. It's generally fine to leave this as '0' (do not dump) in all cases.
 * The sixth field is used by to determine the order filesystems are integrity checked at boot time. A  indicates no check. The root filesystem should have (as here) a  to force it to be checked first, and then all other persistent filesystems can have  specified (so they are checked together, but after the root filesystem).

Here are the specific mount options selected above, and their meaning:

<span id="symlink_etc_mtab">Per the Gentoo wiki article on, the mounted file systems table  must be a symlink to  (this is now also required for  ), so issue:

<span id="concluding_prep">Some Concluding Preparations
It <span id="emerge_additionals">will be useful to have the DHCP daemon, Wikipedia:Wpa_supplicant and Wikipedia:GNU_Screen software available immediately upon reboot. They're not yet installed on the operating system, only on the 'outer' host, so let's emerge them now. Issue:

Next, <span id="note_if_name">take note of your current network interface name - this will be the same after a reboot, and knowing it will be useful during / configuration. Issue:

and look for a record name similar in format to (your system will most likely have a different name - in this particular case it refers to a ethernet card on PCI (p) bus 0, slot 25).

Next, we must <span id="setup_new_root_password">set up a root password. Yes, we did indeed set up a root password 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 -ed) one. As such, we need to set a fresh root password within the. Issue:

Similarly, we need to ensure that the setup inside the  will allow  to log-in (while we complete our set-up, at any rate). Issue:

<span id="setup_networking_openrc">Configure Networking for Post-Reboot Use (OpenRC Users Only)
To <span id="setup_dhcpcd_openrc">make sure you have your network interface available after restart, be sure to add to the default runlevel. Issue:

You should also <span id="setup_sshd_openrc">ensure that the service will automatically start on boot, so you can log in remotely; issue:

Next, <span id="start_wpa_supplicant">if you are performing this install over WiFi, we need to ensure that can be started by  (NB: if using wired Ethernet for the install, you should skip these commands). Issue:

Now, we also need to prepend one line to that configuration file, so that can invoke  directly. Issue:

and prepend the following line to the file:

Leave the rest of the file as-is. Save, and exit.

Also, as of version 6.10.0 of, you need to ensure that the appropriate 'hook' script is in place to start and stop on each wireless interface. So, to ensure that you have this file in place, issue:

<span id="networking_all_done">Assuming you want to use DHCP on your interface (wired or wireless), that's all you need to do: pace the Gentoo Handbook, there's no need to add symbolic links, edit  etc.

However, if you have more complex networking requirements (static IP, proxies etc.) should consult the relevant section of the Handbook. Also, if you have more complex WiFi configuration requirements, you may also find these notes useful.

<span id="exit_chroot_and_restart">Cleanly Dismounting the and Restarting
Almost there! Now we have to exit the in both our  virtual consoles, quit both of those consoles (thereby exiting ), unmount the various logical volumes, deactivate the LVM volume group, and close out the LUKS partition. Issue:

then:

The first exits the  in the first  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):

then:

Unmount everything (and turn off swap), deactivate LVM, and close LUKS:

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:

Your session will exit. Immediately your target machine starts to come back up again, enter the BIOS setup screen.

<span id="set_uefi_mode_in_bios">Selecting UEFI Boot Mode in the BIOS and Restarting!
As mentioned earlier, the exact method of entering the BIOS varies greatly from machine to machine (as does the BIOS user interface itself). On the Panasonic CF-AX3, press during startup (you may need to press it repeatedly, and you do this directly on the target machine's keyboard).

Once the BIOS setup screen comes up, remove the minimal install USB key, so that only the boot USB key (the smaller capacity one) remains inserted. Then, using the same navigation techniques as before, perform the following steps:
 * 1) disable legacy / CSM boot mode;
 * 2) enable EFI boot mode;
 * 3) 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);
 * 4) turn off secure boot (our kernel is currently unsigned, and we have not yet updated the machine's key database in any event);
 * 5) select the USB boot key as the highest priority UEFI boot device; and
 * 6) restart your machine (saving changes).

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 some idea, here's how you go about it on the Panasonic CF-AX3 (which has an AMT BIOS).

Using the arrow keys, navigate across to the 'Boot' tab. Then, navigate down to the 'UEFI Boot' item, and press. In the popup that appears, select 'Enabled' using the arrow keys, and press. This switches the system out of legacy / CSM boot and into standard UEFI mode (steps 1 and 2 in the list above):

Next (step 4), we'll <span id="turn_off_secure_boot">turn off secure boot, since we haven't yet signed our kernel (or installed our own keys into the BIOS). 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. This enters a 'Security' sub-page; navigate to the 'Secure Boot control' item, and press. In the popup that appears, select 'Disabled' using the arrow keys, and press :

Next, on the CF-AX3, 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). Press to restart, and confirm if prompted.

When the machine restarts, hit again, to re-enter BIOS setup. Now we can select a boot device (step 5). Using the arrow keys, navigate to the 'Boot' tab, and then down to the 'UEFI Priorities' item. Press, 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 to restart (confirming if prompted), and come back to this point). Navigate down to 'Boot Option #1' and press. In the pop-up menu that appears, select your (boot) USB key, and press to select it:

That's it! Now press to restart (step 6), and confirm if prompted.

If all that worked, your target system should restart, and boot the UEFI stub kernel off the boot USB key. After some initialization, you should be prompted for a passphrase to unlock the keyfile for your LUKS partition (this is the passphrase you set up earlier). Type this in (directly at the target machine keyboard), and press. Shortly after, assuming that your passphrase is correct, you'll be presented with a login prompt. <span id="login_directly_to_new_system">Enter 'root' as the user (again, directly at the keyboard, without quotes), and then type the root password you set up above.

If all goes well, 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 earlier) or. You can now click here to complete the configuration of your init system (and other) settings.

If however, for some reason you weren't able to boot, then read on.

<span id="if_things_go_wrong">How to Recover if Things Go Wrong
The following are short-form instructions to get you back into a 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.

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 re-activate legacy / CSM booting, and set (if it is not already) the USB key to be the top boot priority device (original instructions here). Save the BIOS settings and exit, thereby rebooting into the Gentoo minimal install system (original instructions here). As before, hit when it beeps at you, remember to select the correct keymap etc. Then, since the boot image itself has no persistence, issue (directly on the target machine's keyboard):

Remember (original instructions here), you are setting up a password for the 'outer', host system here - root's password inside the will be retained (and different), but we haven't remounted the  yet.

Next, ensure that your networking is up. Follow the appropriate instructions below.

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 (original instructions here):

Then click here to skip to the next step. If, instead, you are installing over WiFi, you need to re-create your configuration file (original instructions here). Issue:

Lock down the file's access permissions (to root only) and check that its contents look sane. Issue:

Assuming that looks OK, we can connect. Issue:

Then note your IP address:

<span id="restart_sshd">Now start (original instructions here):

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:

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 DHCP), then the helper will already have a note of its previous fingerprint, and will refuse to connect via (since a mismatched fingerprint might suggest a man-in-the-middle attack). Therefore, we need to remove the old fingerprint record for the IP from. Issue:

and issue (original instructions here):

Check the key fingerprint and then, if it matches, continue as below:

Once you are connected, we need to get running. Via the connection on the helper PC (which is how you should enter all subsequent commands, unless otherwise specified), issue (original instructions here):

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 here):

We will refer to this as in what follows, but of course on your machine it will be something like  or  (note that the initial  prefix is not shown in the  output).

Next, create a temporary mountpoint, and mount it. Issue (original instructions here):

Now, we can open the LUKS volume. You'll need the passphrase (for the keyfile) you set up earlier to do this:

Now we can bring up the LVM logical volumes, and mount them. Issue (original instructions here):

Next, unmount the USB boot key; issue (original instructions here):

Ensure the date and time is set correctly; issue (original instructions here):

Next, make sure that the DNS information will still be valid after we. Issue (original instructions here):

Now, ensure that the various special files in, and  are available after a. Issue (original instructions here):

Now we can actually enter the. Issue (original instructions here):

Remember to source our profile correctly and set a prompt hint. Issue (original instructions here):

Finally, we can setup a second virtual console inside (just as we did before), which will be useful to e.g., monitor the status of long s. Press  then  to start a new console. Then in that new console (which is back outside the, to begin with) enter:

followed by

Now hit then  to get back to the original console.

That's it! You can now proceed to edit your -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:
 * Incorrect kernel configuration. In this case, run, 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 config from the running minimal install system kernel - which is therefore to some extent 'known good' - as a basis).
 * Missing packages. For example, you may have forgotten to install e.g., prior to reboot, preventing you from accessing the network properly. If this is the case, simply  the required software within the chroot, and then try again. There is no need to re-run  in this case.
 * Password not set for root. If for any reason you forgot to set a root password for the new system (as instructed above, when you were -ed in originally), then your attempt to log in will have been rejected. This is easily fixed by using.
 * Wrong keymapping causing mangled passwords. If the system would not accept your keyfile passphrase on reboot, but you were able to successfully unlock it when re-entering the  above, or, if the system would not accept your root password after a restart, then you may have not setup the  variable in  correctly. See 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 previously.) Review, and if necessary, change your boot-time keymap by using, and then re-run.
 * Problems with UUIDs. The script tries to ensure that the UUIDs you have passed it (in  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 ) and then re-run.
 * 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? And that secure boot is disabled at this point? Run through the steps in the "Selecting UEFI Boot Mode in the BIOS and Restarting!" section once more, then try again. (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 ; see this discussion.) A very few EFI systems also do not look for a boot executable under the standard path, but instead will use . If that's the case for your target machine, change the EFI boot file path using, then re-run.

Once you have made your changes and are ready to have another go at rebooting, simply proceed from the section "Cleanly Dismounting the and Restarting" in the main text. Good luck!

<span id="next_steps">Next Steps (and Fork in the Road)
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 earlier choice of init system:
 * users targeting  (the default) should click here to go to the next chapter on the regular track, "Configuring and Installing Necessary Tools"; whereas
 * users targeting  should instead click here to go to the next chapter on the alternative track, "Completing Configuration and Installing Necessary Tools".

<span id="bring_back_ssh">Re-establishing Networking and
Our first order of business is to get back our network connection, then, so we can log in remotely, and use the facilities of the helper machine to complete the install.

To <span id="bring_up_if">bring up your network interface, issue (directly at the keyboard of the target PC):

Next, <span id="start_wpa_supplicant">if you are performing this install over WiFi, we need to ensure that can be started by  (NB: if using wired Ethernet for the install, you should skip the following commands). Issue:

Also, as of version 6.10.0 of, you need to ensure that the appropriate 'hook' script is in place to start and stop on each wireless interface. (NB: if using wired Ethernet for the install, you should skip the following command.) So, to ensure that you have this file in place, issue:

Now we <span id="start_dhcpcd">need to ensure that the DHCP service is started (by ), both immediately, and also automatically whenever the system starts up. We use the Systemd command to achieve this. Issue:

<span id="post_reboot_ip">Wait for a minute or so, and then check to see that you have been allocated an IP address:

Hopefully, it will have autoconfigured an interface, as above. You should of course look for the name corresponding to the interface brought up above, as opposed to (which is simply an example). If using WiFi for the install, the name will start with, not. You are looking for the 'inet' (assuming IPv4) entry; in this case 192.168.1.106 (yours will almost certainly differ). Make a note of this address, you will need it shortly.

Right, we can now <span id="start_sshd">start the daemon (and ensure it auto-starts on boot). Issue:

Now take <span id="note_new_fingerprints">note of the RSA, ED25519 and ECDSA fingerprints (which one is used when you try to connect, will depend upon the settings and recency of the system in your helper PC). These will have been generated automatically when you started for the first time, above (and of course will be different from those created by the  instance we started in the outer, 'host' system earlier):

Now switch back to your helper PC. Note that, if the target PC's IP address is the same as it was originally, then the helper will already have a note of its previous fingerprint (from the previous run), and will refuse to connect via  (since a mismatched fingerprint might suggest a man-in-the-middle attack). Therefore, we need to remove the old fingerprint record for the IP from. Issue:

Now we can connect via. From the helper, issue:

Check the (relevant) key fingerprint and then, if it matches, continue as below:

<span id="set_systemd_config_opts">Setting Up Configuration Options
Next, and before we invoke again, we'll want to set up our locale (and a number of other  options). Note that all subsequent commands should be issued via the connection on the helper PC, unless otherwise specified.

<span id="set_hostname_systemd">Hostname
We'll begin by <span id="set_hostname">setting our hostname. Choose whatever name you like; I'm going to use. Issue:

Check that it worked:

The name change will not immediately reflect in your prompt until you enter another login shell. So let's do that now:

<span id="set_locale_systemd">Locale, Keymap and Console Font
We set up some locale data earlier in the tutorial, but elected to use the default 'C' locale then, for simplicity. Now, we'll switch to use the 'real' locale.

Begin by listing the available locales. Issue:

The current LANG target is shown with a. Now choose a UTF-8 variant from the list (per the Gentoo handbook). For my particular case, that's option 5 in the list,, but yours will most likely vary. Issue:

Now we need to inform of our choice. Issue:

We also need to setup a keymap, both for the virtual consoles and for use with the X11 windowing system (which we haven't brought up yet, but will be using shortly).

Note that the virtual console keymap here is the one that will be used after has started - it does not replace that used in the initramfs (which is necessary to allow correct entry of the LUKS password); see this earlier comment.

We begin by displaying a list of keymaps, and filtering out those of interest. The Panasonic CF-AX3 has a Japanese layout, but obviously your machine may differ. Issue:

In my case, this shows one result, (yours will obviously vary, depending on your choice of  string). Now we can set the ( virtual console) keymap. Issue:

It's important that you double-check your layout will operate correctly, so issue:

Assuming that worked ( did not report an error), we now need to make sure our X11 setup is also correct. Confusingly, X Windows uses a different naming system for keyboard layouts from the virtual console. will try to infer the correct X11 layout for you, but you should check that it hasn't chosen anything bizarre. Issue:

and verify that all is well. For example, in the case above, the X11 Layout will have been guessed as, based on the keymap passed to. That happens to be fine, but in my case, I'd also like to add a second X11 keymap, for use with a plug-in keyboard (which happens to have a UK keymapping), so I issue:

We are nearly done - the last step is to ensure that the <span id="set_vconsole_font">virtual console font and font mapper are set up appropriately.

If the text output displayed directly on your target PC already looks OK, and you can press (directly at the target machine's keyboard) and delete characters successfully, then you need do nothing further here, the default settings are already appropriate for you, and you should click here to skip directly to the next step (regenerating your environment).

This involves setting the and  variables in the  file (which is read by the   service). See the manpage, and the discussions "Into the Mist: How Linux Console Fonts Work" and the "UTF-8 and Unicode FAQ for Unix/Linux" for more background on this. Issue:

And append the following lines to the file:

<span id="fix_strange_characters_on_backspace">

Save and exit the editor.

<span id="regenerate_env">Finally, whether or not you modified above, re-generate your environment, and check all looks good with the locale settings:

<span id="set_rc_local_systemd">Post-Boot Script
At this point, it's useful to setup an script (and invoking  service) that will be run each time the main boot process has concluded. We will use this to address three minor glitches:
 * 1) Often, the  service (which reads the  file that we set up above) can end up being run too early, meaning that these settings get applied, but are then overridden.
 * 2) The virtual console does not always fully clear the frame buffer properly (particularly, when taking over from ), meaning that you sometimes get grey lines at the top or bottom of the console screen.
 * 3) Depending on the version of  (which we'll set up shortly),  may remain running in the background (even though  has completed). This can consume CPU and cause screen glitches.

Whereas the first of these problems could be solved by changing the scheduling dependencies of the service, that's risky, since other services depend on it and we might cause a scheduling loop.

Instead, we'll create a new service, which we'll instruct to run as part of the  (boot synchronization point, similar to runlevel 3), and specify that it should run after the. Per the Gentoo wiki, we'll place the service file in.

Issue:

Then place the following text in the file:

Save and exit. Next, we need to set up the script itself. Issue:

and place the following text in the file:

Save and exit. Now make sure the script is executable, and writeable by root only:

Finally, we need to enable the service (so will invoke it). Issue:

You can of course add your own commands to the script, if you like.

<span id="set_time_date_systemd">Time and Date
Next, check that the date, time and timezone are OK (they should have been carried across successfully from when you set them earlier for OpenRC (here and here), but it is best to check). Issue:

If the time is not correct, issue:

to set it.

If the timezone reported in the output of is incorrect (or shows as ""), you can correct it now; to do so, issue:

We also <span id="systemd_utc">need to tell to save the time in UTC format to the system's real-time-clock (RTC). Issue:

This command should have forced the hardware RTC into sync. To check that this is the case, issue:

and check that the reported and  are in close agreement.

<span id="misc_networking_systemd">Networking
As this tutorial covers the setup of a non-server-configuration machine, most users will not need to set an explicit domain name or NIS domain (if you do, see this section of the Gentoo handbook).

However, their absence results in the appearance of an annoying ""-style message at console login. To fix this, enter:

and remove the string from that file, so it reads:

Save and exit.

Lastly, although networking will automatically start up on boot, we do need to setup some local hostname information. Issue:

And modify the and  lines in the 'localhost aliases' section, so they read:

Save and exit.

<span id="emerge_misc_system_tools">Emerging Additional System Tools
Next, we will some additional system tools that are not yet installed, but which are generally useful (many of these are covered in Chapter 9 of the Gentoo handbook).

However, before we start any heavy compilation, let's get our environment back. Issue:

As before, setup a second virtual console inside, which will be useful to e.g., monitor the status of long s. Press then  to start a new console. Then in that new console enter:

Now hit then  to get back to the original console.

We'll begin by installing as the logger, so that we can view and parse regular textual log files as well as 's somewhat controversial (and not entirely crash-resistant) binary log format. Issue:

As long as the use flag is set (which it will be, given your choice of profile earlier),  will automatically hook up to the correct socket.

Per, we need to make a minor configuration change to avoid binary zero characters getting written to the file (making it look like a binary file to tools like ). Issue:

Now start it up (and enable at boot):

Next, we need a daemon for scheduled commands. We'll choose, a fork of. Issue:

Enable and start it:

Next, we add file indexing, so that you can quickly search for files with the tool. Issue:

There is no service to explicitly enable for. It automatically adds an entry (for ) to  on installation.

Next, we add a program to manage log rotation (important to stop files like from growing to an unwieldy size). Issue:

Again, there is no need to activate any service here, as this creates a daily job (via ) upon installation.

We have already activated, and as I will assume you have no need for serial console access (as this tutorial is not aimed at configuring server machines); if you do, however, please see this section of the Gentoo handbook.

Next, as the handbook notes, we already have necessary file system utilities (for checking integrity, formatting etc.) installed to deal with ext2, ext3 and ext4 filesystems. If you need to support other file systems (e.g., XFS), you should, per the handbook, emerge the necessary package(s) now.

One set of filesystem tools we will definitely need, since we're forced to deal with fat32-formatted partitions for UEFI, is. Issue:

We have already installed and activated, and I will assume you do not require any additional networking tools installed at this point (if you do, please see the relevant section of the Gentoo handbook for more details).

Next, we'll add some useful utilities that let you discover information about the hardware in your system (this will come in handy when e.g., pruning kernel drivers). Issue:

As it's name suggests, provides similar facilities to the  package (present in the @system set), but for USB devices. In particular, the command it includes is very useful. The package provides (inter alia) the eponymous  tool, which can be used to generate a system overview log.

Check that these work. Issue:

and review the output, then:

and do the same (you can press and  to page through the output here, and  to quit).

Now we'll some useful Portage tools. Issue:

Here's what these packages provide:
 *  we've already used (in the minimal install image system) - it is a tool to simplify the selection of Gentoo mirror servers;
 *  is a set of utilities for searching, diffing and updating a binary cache of your local Portage tree (and overlays, if you have them); it is fast and convenient to use;
 *  is a set of miscellaneous administration scripts for Gentoo; these allow you to show package dependency graphs, find out which package installed a particular file, view package changelogs, show package use flags, and many other useful things;
 *  is a simple tool that allows you to query for use flag descriptions quickly.

<span id="ensure_system_up_to_date">Ensuring the System is Fully Up-to-Date
If you have been following these instructions, then it is very likely that you have a completely current system at this point. Nevertheless, let's make double-sure this is so. To do this, we'll make use of the utility script, from the  overlay. To install it, issue:

Next, execute the script to bring your system up to date (we'll avoid checking for kernel updates at this point). Issue:

You can read more about via its manpage. However, in summary, when invoked in non-interactive ('batch') mode (as here), and with the flag, it will:
 * update your Portage tree (including any active overlays, such as ) and the cache (using );
 * remove any prior resume history (using )
 * ensure Portage itself is up-to-date (using );
 * emerge any packages which have been updated, or whose use flags have changed (using );
 * rebuild any external modules if necessary (such as those for VirtualBox) (using )
 * rebuild any packages depending on stale libraries (using );
 * update old Perl and Python modules not caught by (using  and );
 * not attempt to rebuild the kernel, even if a new version of has become available (because we specified );
 * remove any unreferenced packages (using );
 * re-emerge any packages depending on libraries removed by the previous step (using );
 * rebuild any packages depending on stale libraries again (using );
 * remove any unused source tarballs (using ); and
 * update environment settings as a precautionary measure (using ); and
 * run any custom updaters in.

Assuming that completed successfully (you receive the message ""), look at the preceding few lines of output from. If you see:

then there's nothing more to do; however, if instead you see:

then (as instructed) you need to run (this is an inherently interactive process, and so is not called by  when running in batch mode, as here). To do so, issue:

and follow the prompts to accept, zap (ignore) or merge each proposed change.

<span id="reboot_sans_plymouth">Performing a Precautionary Reboot without
To be cautious, we will now reboot the system to check that our changes to the configuration have not caused any issues. This will then also ensure that we have a 'known good' version to fall back to, should any problems arise when we enable the boot splash manager in the next step.

Ensure that the boot USB key is still inserted in the target machine, then close out the two virtual terminals, and then the  connection itself. Issue:

which will close the first terminal, then:

to close the second one. Then exit the enclosing session itself:

Now, ensure your boot USB key is inserted, and then, directly on the target machine (i.e., at its keyboard), issue:

If all is OK, your target system should restart, and boot the UEFI stub kernel off the USB boot key as before. After some initialization, you should be prompted for a passphrase to unlock the keyfile for your LUKS partition (this is the passphrase you set up earlier). Type this in (directly at the target machine keyboard), and press. Shortly after, 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), and then type the root password you set up earlier.

Next, check that everything -related started up OK (do this directly at the target machine's keyboard, there's no need to re-establish / for this short interlude):

If this reports "" (or simply returns, printing nothing) then all is well.

<span id="reboot_with_plymouth">Enabling, Rebuilding the Kernel, and Restarting (Optional Step)
If you do not want to use a graphical boot splash manager, then you can safely skip this step, and stay with a textual boot. Otherwise, let's continue, and set up. We'll also <span id="change_bootfile_path">take this chance to migrate our bootfile from to the less generic.

Still directly at the target machine, use the tool to turn on Plymouth (the following is an example only; the values shown will vary for your machine). Issue:

Specifying a theme will have  automatically turn on the ../Configuring_and_Building_the_Kernel and ../Configuring_and_Building_the_Kernel kernel command line options, disable the 'penguin logo' display on boot (via ../Configuring_and_Building_the_Kernel) and instruct Genkernel to ensure that the necessary modules are installed into the initramfs. Of course, we need to run to make these changes take effect, so let's do that now. Ensure that the boot USB key is still inserted in your target machine, and then (directly at the keyboard) issue:

Wait for the process to complete (it will not do a by default, so it shouldn't take long).

When you get the message "", reboot. Issue:

When <span id="entering_plymouth_LUKS_password">the target system restarts, you should now see a graphical password entry screen, as shown below. Enter your LUKS keyfile passphrase (the one you created earlier), directly at the target machine keyboard, and you should then get a brief animation before the textual login console appears:

Once you receive the login prompt, enter 'root' as the user (again, directly at the keyboard, without quotes), and then type the root password you set up earlier.

<span id="if_plymouth_fails">If Doesn't Work Properly
If you encounter problems when using (for example, it failing to accept your -encrypted LUKS keyfile passphrase), you'll need to fall back to the textual boot manager (as debugging  is beyond the scope of this tutorial). Fortunately, because automatically preserves the prior kernel on the USB boot key, you should be able to do this easily, without having to remount the system using the minimal install image USB key /.

<span id="revert_to_previous_kernel">Simply remove the boot USB key, insert it into the helper PC, and then issue (I am assuming that you need to be the superuser to on your helper PC):

Enter the password (for the helper PC, that is), and then as, on the helper, mount the USB boot key's EFI system partition at :

Next, delete the old (failed) kernel and config (the one that tries to use during ) and replace it with the previous version. If you have only run once since changing the path of the bootfile (from  to ) in the last step, then issue:

otherwise, if you have run more than once since changing the path, issue:

Finally, ensure the data has been written, unmount the USB key, and remove the temporary mountpoint you created, then exit back to the normal user. Issue

Remove the boot USB key from the helper, and re-insert it into the target machine. Power cycle the target machine, and you should now be able to boot up successfully.

Once you have got your target machine environment back online, you will need to ensure that any subsequent kernels (created by ) will not attempt to use during. Issue (the details in the below will obviously differ on your machine):

Ensure that the boot USB key is still inserted in your target machine, and then issue:

Once the build completes, reboot:

and you should be back to a textual boot (where you of course need to enter the LUKS keyfile passphrase, then login as root, as before). You can then continue with the remainder of the tutorial (having a graphical boot splash is nice, but not necessary for what follows).

<span id="next_steps">Next Steps
Now that we have standard EFI boot operational, we will next set up secure boot, to ensure (as a safeguard) that the integrity of our bootable kernel will be checked by the system at startup. Click here to go to the next chapter, "Configuring Secure Boot".

<span id="secure_boot_intro">Introduction
We'll begin with a (very brief) primer on secure boot. (For a more in-depth review, please refer to James Bottomley's article "The Meaning of all the UEFI Keys", Greg Kroah-Hartman's article "Booting a Self-signed Linux Kernel" , and of course the UEFI specification itself .)

The UEFI specification defines four secure, non-volatile variables, which are used to control the secure boot subsystem. They are:
 * 1) The Platform Key (PK). The  variable contains a UEFI (small 's', small 'd') 'signature database' which has at most one entry in it. When PK is emptied (which the user can perform via a BIOS GUI action), the system enters setup mode (and secure boot is turned off). In setup mode, any of the four special variables can be updated without authentication checks. However, immediately a valid platform key is written into PK (in practice, this would be an X.509 public key, using a 2048-bit RSA scheme), the system (aka, 'platform') enters user mode. Once in user mode, updates to any of the four variables must be digitally signed with an acceptable key. The private key counterpart to the public key stored in PK may be used to sign user-mode updates to  or, but not db or dbx (nor can it be used to sign executables).
 * 2) The Key Exchange Key (KEK). This variable holds a signature database containing one (or more) X.509 / 2048-bit RSA public keys (other formats are possible). In user mode, any / (see below) updates must be signed by the private key counterpart of one of these keys (the  cannot be used for this). While  keys (or, more accurately, their private-key counterparts) may also be used to sign executables, it is uncommon to do so, since that's really what  is for (see below).
 * 3) The (caps 'S', caps 'D') Signature Database (db). As the name suggests, this variable holds a UEFI signature database which may contain (any mixture of) public keys, signatures and plain hashes. In practice, X.509 / RSA-2048 public keys are most common. It functions essentially as a boot executable whitelist (described in more detail shortly).
 * 4) The Forbidden Signatures Database (dbx). This variable holds a signature database of similar format to . It functions essentially as a boot executable blacklist.

Now, here's the key point (excuse the pun): when the system is in user mode, and secure boot is enabled, the machine will only boot EFI executables which:
 * are unsigned, but have a hash (message digest) in and not in ; or
 * are signed, where that signature appears in but not in ; or
 * are signed, where that signature is verifiable by a public key in, or a public key in , and where neither that key, not the signature itself, appears in.

When you buy a new Windows (10 or 8) machine, it will usually be set up as follows:
 * The PK variable will be loaded with a public key issued by the hardware vendor (for example, Panasonic).
 * The KEK variable will be loaded with a public key issued by Microsoft.
 * The db variable will be loaded with a set of public keys issued by various vendors authorized by Microsoft).
 * The dbx variable will generally contain some revoked signatures (although it may also be empty, it depends on the revision of Windows on your machine).

<span id="save_keystore_create_new_keys">Saving Current Keystore Values, and Creating New Keys
We begin by re-establishing an connection, as before (as it will make the work of entering commands etc. easier). From the helper PC, issue:

Now proceed as below, using the connection to enter all commands unless otherwise specified (incidentally, there is no need to use  at this point, since we'll be rebooting again shortly). Issue:

Ensure only the superuser can access this directory, using Filesystem/Security - issue:

Next, <span id="save_old_secure_vars">we'll use the tool (from the ) to store off the current values of, ,  and , in machine-readable signature list format. Issue:

Now we <span id="create_secure_boot_keys">can create a new platform keypair, key-exchange keypair and kernel-signing keypair. We'll use to do this. The requested keys will:
 * use X.509 certificate format for the public key (this allows various additional data fields to be passed with the key if desired, for subsequent identification);
 * utilise the RSA asymmetric cryptosystem, with a 2048 bit key length;
 * have 10 years (3650 days) to run until expiry;
 * use SHA-256 as the public key's message digest.

Issue:

This will have created three X.509 public-key certificate files (, and ), and three counterpart private key files (,  and ). We'll make the private keys readable only by root (an extra precaution, since they already in a directory readable only by root). Issue:

The tool (also from the ), which we'll use shortly, can use raw X.509 certificates and keys to update the,  and  secure variables. However, it is more picky (as of the time of writing) about the variable, and will only accept this in the 'signed signature list' ('') format. We can create this in a <span id="create_PK_auth">two step process (using two command line tools from ). First, we make a signature list (which requires a unique ID, the value of which is essentially unimportant), and then we use our own (private) platform key to sign it. Let's do both now - issue:

The file we need out of this is.

<span id="install_new_keys">Entering Setup Mode, and Installing New Keys
With the preparations completed, we're ready to enter setup mode. Reboot the machine:

Immediately your target PC starts to come back up again, enter the BIOS setup screen. As mentioned before, the exact method of entering the BIOS varies greatly from machine to machine (as does the BIOS user interface itself). On the Panasonic CF-AX3, press during startup (you may need to press it repeatedly, and you do this directly on the target machine's keyboard).

Once the BIOS setup screen comes up, using the same navigation techniques as before, perform the following steps:
 * 1) clear the UEFI secure boot variables, thereby entering setup mode; and
 * 2) restart your machine (saving changes).

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 some idea, here's how you go about it on the Panasonic CF-AX3 (which has an AMT BIOS).

To achieve step 1, use the arrow keys to navigate across to the 'Security' tab. Then, navigate down to the 'Secure Boot' item, and press. This enters a special 'Security' sub-page. Navigate down to the 'Clear Secure Boot Keys' item, and press. Confirm that you wish to proceed by selecting 'Yes' in the popup which appears, then press. If asked to reconfirm, select 'Yes' and press again:

Note that on some UEFI implementations it is required to set a supervisor password in order for the option to clear the Secure Boot keys to be available.

Next, ensure that your boot USB key is still inserted, then press to restart (step 2), and confirm if prompted.

The machine should restart, and, just as before, you will see the passphrase screen. Enter your LUKS keyfile passphrase (the one you created earlier), directly at the target machine keyboard, and wait for the text console login to appear.

Then, re-connect to the machine via. From the helper PC, issue:

Now proceed as below, using the connection to enter all commands unless otherwise specified (again, we will not need ). Issue:

You can verify that the secure variables have been cleared. To do so, enter:

and review the output.

<span id="set_new_values">Next, we'll reload the old contents of, and , which we saved off above, thereby ensuing that Windows will still be permitted to load under secure boot (if we don't do this, it will be blocked). Issue:

The option specifies that an EFI signature list file is to be loaded (and the  option precedes the filename itself). Because we are in setup mode, no private key is required for these operations (which it would be, if we were in user mode).

Assuming that completed successfully, we can now append our own key-exchange and kernel-signing public keys, which we created and stored into and  (respectively) earlier. Issue:

Note that here, we are using the option to append (rather than replace), and a slightly different format for the input file (since it is a X.509 certificate, rather than a signature list, we drop the, and use  rather than  to introduce the pathname). More details can be found in the manpage.

<span id="set_PK">Having made our changes, we can now write our own platform key into PK, using the signed signature list we created earlier. Issue:

If this succeeds, the target machine will have been switched back to user mode (although secure boot is not yet enabled).

Display the contents of all the secure variables now. Issue:

and verify that both your new keys, and Microsoft's original set, are present.

Now, let's make a backup (in machine readable signature list format) of the current state of the variables. Issue:

<span id="test_secure_boot">Testing Secure Boot with a Signed Kernel
Our next step is to create an appropriately signed kernel. The script will do this automatically for us, provided that the files  (the private kernel-signing key) and  (its public key counterpart) exist (which they now do). Ensure that the boot USB key is still inserted, then issue:

This should not take long to complete (as by default it does not ).

Assuming the kernel build completed successfully, we can now restart, turn on secure boot, and try it out! Issue:

Immediately your target PC starts to come back up again, enter the BIOS setup screen. As mentioned before, the exact method of entering the BIOS varies greatly from machine to machine (as does the BIOS user interface itself). On the Panasonic CF-AX3, press during startup (you may need to press it repeatedly, and you do this directly on the target machine's keyboard).

Once the BIOS setup screen comes up, using the same navigation techniques as before, perform the following steps:
 * 1) turn on secure boot; and
 * 2) restart your machine (saving changes).

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 some idea, here's how you go about it on the Panasonic CF-AX3 (which has an AMT BIOS).

To achieve step 1 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. This enters a 'Security' page; navigate to the 'Secure Boot control' item, and press. In the popup that appears, select 'Enabled' using the arrow keys, and press :

Next, ensure that your USB boot key is still inserted, then press to restart (step 2), and confirm if prompted.

The machine should restart, and, if all goes well, you should shortly be prompted with the passphrase screen. If so, then congratulations, you are running a self-signed kernel under secure boot! Enter your LUKS keyfile passphrase (the one you created earlier), directly at the target machine keyboard, and wait for the text console login to appear, as previously.

<span id="verify_win8_secure_boot">Verifying Secure Boot with Windows (and Fixing RTC)
Having successfully booted our own self-signed kernel, we next have to check that Windows still works. Remove the boot USB key from the target machine, then (while it is still running Gentoo) log in directly at the target machine's keyboard (at the login prompt, enter 'root' as the user (without quotes), and then type the root password you set up earlier). Then issue (directly at the machine's keyboard):

As the boot USB key is not inserted, Windows should start automatically. If it does boot, you have just verified that Windows also starts properly under your modified secure boot settings (and if it does not, follow the troubleshooting hints above).

Now, while Windows is running, let's take the chance to switch its clock to UTC, to match that used by (which we set earlier in the tutorial).

To achieve this, login to your Windows account (which must have administrator rights - the first user created on a new Windows install has these by default), as usual. Next, perform the following steps (I have noted where things differ between Windows 10, 8.1 and 8):


 * 1) First we'll check the Windows time, date and timezone is correct. Hit the, which will bring up the start menu in Windows 10 (or the "start screen" in Windows 8.1 and 8), and type  . Then click on the 'Date and Time' item which appears (in Windows 10 and 8.1; Windows 8 users will need to click the 'Settings' icon to see this result; note also that in Windows 8.1 and 8, the item you need to click is entitled 'Date and time settings'). A 'Date and time' dialog appears. Set appropriate values for your locale.
 * 2) Next, we'll instruct Windows to use UTC (this will require a registry edit). Hit the, which will bring up the start menu in Windows 10 (or the "start screen" in Windows 8.1 and 8), and type  . Then click on the 'regedit' item that appears. If prompted (via a dialog) whether to allow it to make changes to your computer, click 'Yes'. The  program now opens; using the navigation tree-view on the left, select  (you need to click on the little arrows to see the lower levels of the tree). Once this item has been selected, various time-zone related information will display on the right-hand pane. Right-click in the white area at the bottom of this pane, and choose  from the context menu that appears. A fresh DWORD entry is added to the end of the list with its name selected - overtype this with   then press . Now double-click on the name, and a dialog will appear, in which you can edit the key's value. Type in   (the number one) for the value, as shown below:Win8Regedit.png Close the dialog by clicking on 'OK'. Then exit the  application (using the menu item ).
 * 3) Now we'll disable the Windows Time Service. This is most easily done from the Windows command line. Hit the , which will bring up the start menu in Windows 10 (or the "start screen" in Windows 8.1 and 8), and type  . 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  . Hopefully, this should report . Close out the command window (by clicking on the 'x' in its title bar).
 * 4) Next, we'll force Windows to update the time. Hit the, which will bring up the start menu in Windows 10 (or the "start screen" in Windows 8.1 and 8), and type  . Then click on the 'Date and Time' item which appears (in Windows 10 and 8.1; Windows 8 users will need to click the 'Settings' icon to see this result; note also that in Windows 8.1 and 8, the item you need to click is entitled 'Date and time settings'). A 'Date and time' dialog (which we used above) appears again. Now, on Windows 10, select the 'Internet Time' tab, click on 'Change settings...' and click 'Update now', then press 'OK'. On Windows 8.1 and 8, instead move the 'Set time automatically' slider to 'Off', and then back to 'On' again. In either case, assuming you have a network connection, the time should immediately update when you do this (and, assuming your locale is set correctly, it should be accurate). Close out the dialog once complete.

<span id="set_bios_password">Setting BIOS Password (Optional), and Restarting Gentoo Linux
Next, we will <span id="reboot_from_win8_to_linux">reboot back into Gentoo. Re-insert the boot USB key into the target PC. Then, in Windows-8, hit, then click on the power icon at the bottom right of the screen, and choose 'Restart' from the pop-up menu.

Immediately your target PC starts to come back up again, enter the BIOS setup screen. As mentioned a number of times now, the exact method of entering the BIOS varies greatly from machine to machine (as does the BIOS user interface itself). On the Panasonic CF-AX3, press during startup (you may need to press it repeatedly, and you do this directly on the target machine's keyboard).

Once you have the BIOS configuration screen up, you need to perform the following steps:
 * 1) select the "" EFI boot item as top priority;
 * 2) (optionally) set a BIOS password; then
 * 3) restart your machine (saving changes).

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 some idea, here's how you go about it on the Panasonic CF-AX3 (which has an AMT BIOS).

To <span id="set_boot_order_gentoo">achieve step 1 on the CF-AX3, use the arrow keys the arrow keys to navigate to the 'Boot' tab, and then down to the 'UEFI Priorities' item. Press, 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 to restart, and come back to this point). Navigate down to 'Boot Option #1' and press. In the pop-up menu that appears, select the "" item (which was added to the boot list when we ran earlier):

Press to set this as the top boot option. Finally, press to exit the subpage.

<span id="set_bios_pw">The next step (#2, installing a BIOS password) is optional, but it is sensible to ensure that secure boot cannot be switched off by an attacker with temporary access to your machine (to permit a tampered kernel to run without your knowledge, for example). Most machines support some form of BIOS password, but the means of setting it varies widely. On the CF-AX3, use the arrow keys to navigate to the 'Security' tab, and then move down to the 'Set Supervisor Password' item, and press. Type your password into the pop-up that appears: When done, press. Then, when prompted, re-type the password to confirm and press.

It is then sensible (on the CF-AX3, at any rate) to disable the BIOS's boot password prompt (otherwise, you'll have to type in the BIOS (supervisor) password every time you boot from USB). On the CF-AX3, navigate up to the 'Password On Boot' item, and press. Then, in the pop-up that appears, use the arrow keys to select 'Disabled', and press to select:

That's it! Now ensure that the boot USB key is still inserted, then press to restart (step 3), and confirm if prompted.

The machine should restart, and, if all goes well, you should shortly be prompted with the (by now familiar) passphrase screen. Enter your LUKS keyfile passphrase (the one you created earlier), directly at the target machine keyboard, and wait for the text console login to appear, just as before.

Then, re-connect to the machine via. From the helper PC, issue:

Use the connection to enter all subsequent commands unless otherwise specified (do not start up  at this point, we'll do so again shortly).

The final thing thing we must do here is to check that our system time details have not been messed up by Windows (which, given the changes we have just made, they should not have been). Issue:

and make sure the time and date are still correct, and in particular that the "" field reports as.

<span id="next_steps">Next Steps
Congratulations, setup of secure boot is complete! Next, we can install the GNOME 3 graphical environment. Click here to go to the next chapter, "Setting up the GNOME 3 Desktop".

<span id="add_regular_user">Adding a User for Daily Use
Per the Gentoo Handbook, it is strongly recommended to set up a user for day-to-day use on your machine. Let's do that now. <span id="setup_regular_user">Issue (via the connection from the helper PC) :

The meaning of those options is as follows:

<span id="install_x11">Installing X11
As we'll be using X11 as the underlying graphical platform for GNOME, we'll install it next.

We need to set a few USE flags for (an OpenGL-like library which X pulls in as a dependency), and while we're at it, set a few others that we'll need shortly for GNOME, so issue:

Here are what those flags do (you may also find this Linux from Scratch page useful):

As before, since some of the next steps will involve lengthy emerges, we'll use, and <span id="another_second_console">setup a second virtual console , which will be let us monitor progress using. Issue:

to start. Then, press then  to start a new virtual console, and in that new console enter:

Now hit then  to get back to the original console.

Now, since you have already set up the necessary ../Installing_the_Gentoo_Stage_3_Files and ../Installing_the_Gentoo_Stage_3_Files variables in earlier, we can now proceed to install the X-server itself. Issue:

and the X11 server will be downloaded and installed. Note that we use here to avoid adding it to your @world set (this is slightly cleaner, as it will become a dependency of GNOME, once it is installed later).

<span id="temp_install_twm">Temporarily Installing an X11 Window Manager and Applications
To be <span id="install_x_test_apps">able to test out X11, we'll need to install a window manager, and a few X11 applications.

To keep things simple here, we'll use the (minimalist) Tab Window Manager (TWM), and the following apps:
 * : a background ('root') window parameter setting utility for X;
 * : a simple clock display for X; and
 * : the standard terminal emulator for X.

Issue:

These are small programs, and shouldn't take long to download, compile or install.

Next, reload your environment to avoid issues when starting the X server. Issue:

Press then  to switch to the second virtual console, and do the same there:

Then press then  to revert to the first virtual console again.

Next, we need to tell X11 what window manager and apps to use whenever it starts up. The file is used for this purpose. Also, as it's generally not a great idea to run an X server as root, we'll invoke it as the regular user we've just created. Still via / console, issue:

Next, edit the file in the regular user's home directory. Issue:

Put the following text in the :

Save and exit.

The above shell script simply instructs X to:
 * start the Tab Window Manager as a background process;
 * set the background colour to "CornflowerBlue" (also backgrounded, but will exit quickly);
 * show an analogue clock, of size 100x100 pixels, offset 1 pixel from the right side of the screen and 1 pixel from the top (as a background process);
 * show a terminal, of size 80x50 characters, offset 494 pixels from the left side of the screen and 51 pixels from the top (as a background process);
 * show a second terminal, of size 80x20 characters, offset 494 pixels from the left side of the screen and 0 pixels from the bottom; and
 * then execute a third terminal, of size 80x66 characters, offset 0 pixels from the left, top corner of the screen (replacing the calling process). This terminal has name 'login' and, when terminated, the X session will close.

<span id="first_try_startx">Now we are ready to try it out!

Still on the / console, issue:

If all goes well, the screen of your target PC should now be displaying something like the below: (If you get an error instead, see the following section "Troubleshooting a Failed X11 Startup". Any problems are most likely due to a missing kernel graphics driver, which is easy to fix, so don't panic!)

Check that you can move the cursor around (using the target machine's mouse or touchpad), and try typing some simple commands (e.g. "") into any of the three terminal windows. When done, move your cursor into the longest (leftmost) terminal, so that it receives the focus (its cursor will switch to a filled rectangle), and type (directly at the target machine's keyboard):

On the / console (at your helper PC), you should now see that the program has exited (and a lot of status output will have been written to the console too).

If you were able to carry out this test, then congratulations, GNOME 3 should be able to work fine on your system. Jump over the troubleshooting section and install it.

If, however, X failed to start up properly, continue reading.

<span id="if_x11_fails">Troubleshooting a Failed X11 Startup
By far the most likely problem you will encounter with X is a missing graphics driver. Actually, if you've been following this tutorial, and have a reasonably modern machine, then it'll likely have happened to you. That's because the Gentoo minimal install image kernel (on which your current kernel's configuration has been based) does not have many graphics device drivers configured (either built into the kernel, or as modules) - in order to keep the size of the image small.

Two drivers that are conspicuous by their absence from the minimal install kernel configuration are:
 * the driver; this is needed for the integrated "HD Graphics" on many Ultrabooks (such as the Panasonic CF-AX3);
 * the driver; this is an open-source driver that supports many nVidea graphics cards (which are popular on desktop machines).

The easiest way to see if you have had a problem like this is to look at the output from your attempt to run (the output in the / virtual terminal, that is, not on your target machine's display).

If you see output such as:

then you know that you have a driver problem. In this case, it is complaining about the driver module (dynamic library).

To rectify this, we need to <span id="make_menuconfig_intro">turn on the appropriate drivers and rebuild our kernel. Ensure that the USB boot key is inserted into the target machine, and issue (from the / virtual terminal):

to drop back to the user.

Then:

to start the kernel rebuild process going. Because you have not specified here, but you have specified, the process will run through by itself (assuming no errors) to the point where you can modify the kernel configuration using the standard -based editor GUI.

The configuration changes you need to make will vary depending on the driver(s) you need to enable. The following is a step-by-step guide for modern laptops (and other PCs) with Intel integrated HD graphics (following this wiki page). If you require a different driver, modify these instructions accordingly.

The system is a simple tool used to modify Linux kernel configurations (aka "" files) in a coherent manner. The tool will not let you make inconsistent choices, and has a useful search facility.

When starts up, it will present you with a display similar to the below (your version may vary depending on currently selected options and kernel version):

You can navigate the interface as follows:
 * Use the up and down arrow keys to move your selection (highlighted in blue) in the top pane;
 * Use the left and right arrow keys to traverse the bottom (horizontal) menu, which defines what happens when you press, viz.:
 * <Select> enters a sub-menu, for items (in the top pane) ending with, or brings up a text entry box for items which start with round brackets "";
 * <Exit> exits a sub-menu; if at the top level already, asks you whether to save changes (if you have made any) and exits the program; you can also press then  to perform this action;
 * <Help> shows a help screen that is relevant to the (top pane) selection; you can also press for this;
 * <Save> saves the current configuration; and
 * <Load> allows you to load a new configuration.

Items starting with non-round brackets represent features which can be enabled, as follows:
 * , : Square brackets indicate features that are deactivated (blank) or activated (asterisk). Press  to toggle status, or  to activate,  to deactivate. Activated items are built directly into the kernel; deactivated items are omitted from it entirely.
 * ,, : Angle bracketed items can similarly be deactivated (blank) or activated (asterisk), but can additionally be built as modules (""). In addition to ,  and , you can use  with such items to specify that they should be modularized.
 * , : Curly brackets indicate items which cannot be deactivated (due to another item's dependency). However, they may be activated or modularized (using,  or , as before).
 * , : Similarly, hyphens indicate items whose status cannot be changed (their selection having been forced as the result of another item choice).

To search, press and then type your search term. This is a very useful facility when looking for missing drivers etc. For example, since we are here looking for the missing module, press  then type in, then press  to see the search results:

You can scroll through the results using the arrow keys. Doing so in this case, we discover that (inter alia):
 * Four items are returned, of which the first and third (, and ) are relevant;
 * The output shows that (e.g.) the item (which will appear in the  file as ) is to be found under the  menu, by following down into the  submenu. We also see that its prompt in the upper-pane menu will (as is common with this software!) will be distinct from the  name (it will actually appear as "").
 * The dependencies of this driver are also shown (you can drag the terminal window on your helper machine wider to see any that may have been clipped off). Generally, for an item to be available for selection or modularization, all its dependencies must be satisfied: either selected (, the same as an asterisk) or modularized . In some cases, items whose dependencies are unsatisfied will not be visible other than through a search like this.

This last point bears repeating, since it confuses many first-time users: an item will often not even appear in 's top pane until its dependencies have been satisfied. It would be nice if would allow us to activate/modularize "an item and all its dependencies, transitively" from the search results screen, but it currently cannot, so we must perform this depth-first recursion manually.

OK, so let's work through the case as a concrete example. From the search just performed we can see that, of the requirements for, only the item is currently deselected. Well then, let's investigate : we hit to exit current search, then  to search again, and type in  and press. The item we want here is the first result term. All its dependencies appear satisfied in the current configuration, and we note also that it appears under "", and that its prompt is "":



Now we know there are no further unsatisfied dependencies for, we can activate , and then itself.

Begin by pressing to exit the current search, then use the arrow keys to navigate to the "" item (if not visible to begin with, the top pane will scroll as you arrow down), then press  to enter the submenu. Next, repeat the process to select the "" item, and press :

Now, move to the "" item. This is the symbol we want (as just mentioned, you can verify using  if you like). Press to enable it (this causes a number of subitems to appear, and also enables this entry itself as a submenu heading (not obvious unless you drag your window wider than the default 80 columns, so you can see the  suffix that appears post-selection):



So, now that we have set, we can proceed to enable itself. Navigate down the menu, through the new items that appeared when you selected, until you reach the  item (if you think this feels rather like a 70's era adventure game, you're not alone!):

You can verify that this is indeed the item, by using using  if you like; then, press  to enable it:

And that's it, you're done. Hit then  to come back out to the "" menu. Hit then  again to come back out to the top-level menu. Finally, hit then  again, to exit the program. When prompted, ensure is selected, and press  to save the new configuration and quit :

Once you have exited, will automatically create a kernel with the newly created configuration, sign it, and copy it over to the boot USB key. Wait for the process to complete (you get the message ""). Then issue:

which will close the first terminal, then:

to close the second one. Then, ensure the boot USB key is still inserted in the target machine and restart it, by issuing:

When the machine restarts, as before, you will need to enter your LUKS keyfile passphrase (the one you created earlier), directly at the target machine keyboard.

Once this has been completed successfully, and the target machine is restarted, from the helper PC, log back in again via :

Then, re-establish (enter all commands via the  console from the helper PC, unless otherwise stated). Issue:

to start. Then, press then  to start a new virtual console, and in that new console enter:

Now hit then  to get back to the original console. Log back in as your regular user:

And now rejoin the tutorial from the point where you attempted to run, above. Hopefully, all should be well this time. Good luck!

<span id="install_gnome3">Installing GNOME 3
Now that we know X works, we can install GNOME! Let's begin by removing the temporary X window manager and applications (which we installed, for testing purposes only, earlier).

Issue (from the helper PC / terminal):

to get back to the user, then:

Now for GNOME itself. There are two additional USE flags we'll need here, to turn on UPnP audio/video streaming support for the package, and to ensure that the  web server works in a non-threaded fashion. To enable these, issue:

Now we are ready to install GNOME! Issue:

The will take quite some time to complete! Note that the option instructs  to build as much as possible, even if some errors are encountered. This is useful here because, due to the size of the build, it is possible that you may come across one or two failed packages.

Most often, any failures will be caused by the high level of paralleism we are using. Accordingly, if, at the conclusion of the above, near the end of the output you see a message that:

then issue the following command, to re-attempt to build the failed packages, this time without parallelism:

(Of course, if the original completed successfully, there is no need to issue the above, but, as  is a meta-package, it is still safe to do so, and won't cause all the dependencies to be rebuilt.) You may need to repeat this step multiple times to get GNOME emerged successfully (I have found three or four iterations may be necessary). As long as the 'packages to be installed' count keeps falling, keep trying ^-^

Once the process has completed, ensure you are back in the virtual terminal from where you issued the command (i.e., not the  terminal), and then issue the following to ensure your environment is up-to-date post-install:

Hit then  to go to the second  console, and do the same there. Issue:

Then press then  to switch back to the original console again.

Make sure any regular users are members of the group (if it exists on your target machine). Issue:

If you wish your regular user to be able to play the GNOME games (assuming you have chosen to install them), then issue (this is optional):

Next, we need to log back in as our regular user, and try out our new desktop! Issue:

Next, edit the file in the regular user's home directory. Issue:

Delete the current contents of (you can use  inside  to delete a line at a time), and replace with the following text:

Save and exit.

OK, time to try it out! Issue:

And hopefully you should be greeted with a (rather startlingly empty!) GNOME 3 desktop, somewhat similar to the below, on the target machine:

You can try playing around with it briefly if you like (some simple instructions may be found here - or just get started by moving your mouse pointer up to the top left corner of the screen (and optionally, clicking on 'Activities'), or by pressing ), using the target machine keyboard and mouse / touchpad directly. Note, however, that this isn't a properly logged-in instance, so certain of the standard features will not function as you expect. You should be able to start a terminal etc. however. When you're done, kill the test instance, by issuing at the helper PC / terminal (the one where you just issued ).

<span id="testing_gnome3">Testing GNOME 3 (and Refining Settings)
Congratulations, GNOME 3 is now basically functional; we only need a few more steps to get it fully operational on your machine! So, let's continue. Come back out to be again:

Next, we must enable the Wikipedia:NetworkManager service (which will handle all network interaction under GNOME), and disable the service, which we started earlier (and whose functionality  supplants). First, issue:

Next, if you are using WiFi for the install, you'll also have explicitly set up a configuration file earlier in the tutorial, and so you need to remove this again now (however, skip this step if installing over a wired Ethernet connection):

<span id="start_nm">Now we can ensure comes up on boot (however, do not start it yet, since you may lose network connectivity when you do). Issue:

That having being done, we need to make sure that the GNOME Display Manager is configured to run on boot (and also, we'll start up an instance now, together with ). Issue:

Assuming that worked, <span id="login_to_gnome">you should now be able to see a GNOME login screen on the target machine, similar to the below:

Directly at the target machine, click on the (regular) user name then, when prompted, type in the (regular user) password you set up earlier.

You should arrive back at the GNOME desktop (only this time, with a little more functionality, since this is a normal login session).

Before our final reboot (at which point, we will no longer require the helper PC, but will be using the target machine natively), there are three additional tasks we need to carry out:
 * 1) ensuring that network settings are correct;
 * 2) setting up keyboard settings are correct within GNOME (if required); and
 * 3) ensuring that our the system remembers our volume preferences between reboots.

<span id="gnome_network_settings">GNOME Network Settings
You should now make sure that your network settings are correct under GNOME. Any wired connection should have been picked up fine, but if you have been installing using WiFi, you'll need to select an access point, and enter your wireless passphrase, to regain network connectivity.

To do that, simply click on the 'downwards pointing triangle' in very top right of the screen. This will show a drop-down menu, from which you can turn on WiFi, and select an access point (you'll be prompted for the passphrase). (Alternatively, you can press the, then type "" (and press ), then click on the item titled 'Network' in the panel that appears.) It's a fairly self-explanatory interface, but if you need assistance, simply press.

Once you have the network set up, you should be able to browse the web etc. Try this now: directly at the target machine's keyboard, press the and type 'Web', then press  to start the first item shown. GNOME's default web browser will start up, initially full-screen. You can drag it down by the top bar to make it a normal-sized window, type in a URL etc.:

<span id="gnome_keyboard_settings">GNOME Keyboard Settings
If you have a non-US keyboard (as in the case of the Panasonic CF-AX3), you will need to set this in GNOME. Press the, then type "" (and press ) and click on the item in the list. This opens a control panel. Make sure the 'Language' and 'Formats' in the top pane are correct for your locale. Then, add the appropriate 'input source' in the bottom pane. Click on the 'plus' sign icon, and an "Add an Input Source" panel will appear. Click on the tile showing three stacked dots, and drag the panel slightly larger vertically (as otherwise the output will be hidden). You should now be able to click on the 'Other' tile that appears, and then select the required source from the full list, and then click on 'Add' (in my case, I actually added three: "English (UK)" (for my plug-in keyboard), "Japanese" for the machine's built-in keyboard, and "Japanese (Anthy)" for kanji and kana input - obviously, your requirements will probably differ). When done, close out the "" dialog.

Once an item <span id="input_source_menu">has been added, it can be activated via a drop down in the top bar of the screen. In the case of the CF-AX3, you'd want to select 'Japanese' from this list, so that the keyboard mapping is correct (even if you are typing everything in English!) Be sure to check this, if you have problems having your password accepted at the GNOME login screen.

<span id="gnome_volume_control">GNOME Volume Control
You may find that although you can set sound levels using the 'speaker icon' menu in the GNOME top bar, these settings are lost on a reboot (and sound is muted each time). If this occurs on your system (it affects the CF-AX3), take the following steps. First, emerge (you can do this via the / terminal on the helper PC):

Once that completes, set the volume levels as you like them, then issue:

The settings should now be preserved across a reboot.

<span id="restart_to_gnome">Restarting into GNOME!
We are now ready to bid farewell to the services of the helper PC, as all further steps can now be done on the target machine directly. Close out the / terminal. Issue:

which will close the first terminal, then:

to close the second one, then:

which will close out the session itself.

Now, ensure that the USB boot key is inserted in the target PC, and reboot it, by clicking on the 'power' icon (in the top right of the screen), clicking on the 'power' button in the dropdown menu that then appears, and then clicking on the 'Restart' button in the dialog.

The machine should then power cycle (you will be cleanly logged out of GNOME first). When the machine restarts, as before, you will need to enter your LUKS keyfile passphrase (the one you created earlier), directly at the target machine keyboard to unlock the LUKS partition. You should then be presented directly with a GNOME login page (as above). Directly at the target machine, click on your (regular) user name then, when prompted, type in the (regular user) password you set up earlier (ensure you have the correct keyboard settings, if relevant, as discussed above).

Once logged in to GNOME, bring up a web browser: directly at the target machine's keyboard, press the and type 'Web', then press  to start the first item shown. GNOME's default web browser will start up, initially full-screen. You can drag it down by the top bar to make it a normal-sized window. Do so, and type in the URL for this tutorial, so that you can continue to follow it there.

Now, <span id="open_gnome_terminal">bring up a terminal window in GNOME. Press the again, and type 'terminal', then press. A standard-issue terminal window should open. As we have some final installation work to do, become root:

The password required here is the one you set up earlier in the tutorial (and have used when -ing in).

<span id="next_steps">Next Steps
Congratulations - if you have followed through to this stage, you have a basically functioning system! There is some final driver configuration left still to do, so let's address that now. Click here to go to the next chapter, "Final Configuration Steps".

<span id="general_approach">General Approach
<span id="resume_after_menuconfig_tutorial">The general approach when looking to enable a feature which is physically supported on your machine (for example, Bluetooth), is as follows:
 * Obviously, check whether the feature already works (it's always possible that your current kernel already has the necessary options enabled or modularized). If it does, great, you're done!
 * Ensure your boot USB key is inserted, then invoke (as ) in a terminal (which will run the  tool).
 * Collect as much information as possible about the physical device (vendor name, model name etc.), using tools such as, and  (in a separate terminal window).
 * If the device description should match one given in the specific CF-AX3 instructions below, implement the given kernel configuration shorthand fragment (using the interface).
 * Otherwise, search (still via the interface; see the tutorial earlier) for a suitable option, and then enable (or modularize) it (and any dependencies). If you can't find anything suitable this way, do a web search based on the information collected. (Unfortunately, there is no automated tool to do this for you).
 * Once you have made all desired changes, exit and save, thereby allowing to continue and create a new kernel; and then reboot. With luck, your desired feature should now be operational.
 * If all else fails, invoke again, try modularizing all options under the appropriate sub-menu in the  interface, then save and exit, to create a new kernel as before. If, after a reboot, the desired feature is operational, you should then be able to locate its driver using  (after which you can rerun  if you like, to turn off all other unneeded items and recompile). This approach (i.e., turn on pretty much everything so that something will work ^-^) is actually the one taken by many Linux distributions (such as Ubuntu) for their 'generic' kernels, so don't feel shy to try it if need be.

Tweaking your kernel configuration to enable machine features is one of the more frustrating tasks you have to do when bringing up a system under Linux. In this tutorial, I've deliberately postponed it till near the end - when you already have all the other elements of a functioning system in place.

To make the process concrete, I'll now lay out the changes necessary to enable the main features of the Panasonic CF-AX3 laptop. You will obviously need to adapt what follows depending on your particular target machine.

<span id="specific_config_recipes">Specific Configuration Recipes (Using CF-AX3 as an Example)
In what follows, we will cover the following (common) features, using the Panasonic CF-AX3 as a (fairly typical) example (it is a reasonably feature-rich Ultrabook, so some of these may apply directly to your system too):
 * 1) WiFi;
 * 2) Bluetooth;
 * 3) Integrated touchscreen;
 * 4) Integrated webcam;
 * 5) Audio;
 * 6) Integrated (SD etc.) card reader;
 * 7) LCD screen backlight.

To reiterate, what follows is simply an example, for a particular PC (the CF-AX3). Where necessary, follow the steps above to set the necessary options for your particular choice of target machine.

<span id="config_prelims">Preliminaries
Ensure your boot USB key is inserted in the target machine, and then (at the terminal within the GNOME session that we opened earlier), issue:

to create a 'last known good' backup of the current kernel (and configuration) on the boot USB key. Although does create a backup of the previous version when it is run, that backup is not persistent, and will be overwritten the next time buildkernel is executed. Keeping a (timestamped) backup via ensures that there's no risk we run  twice between reboots, thereby losing our reference point.

Next, issue:

Because you have not specified here, but you have specified, the process will run through by itself (assuming no errors) to the point where you can modify the kernel configuration using the standard -based  editor GUI. You can now use that interface to enable specific features as specified in the kernel configuration shorthand 'recipes' given below.

Now, because it will be useful to have a second terminal available (for work etc.), open one now within GNOME. Click in the current terminal window (the one showing the interface, then press  to spawn a new one. In this fresh window, log in as root:

The password required here is the one you set up earlier in the tutorial (and have used when -ing in previously).

<span id="config_wifi">WiFi
The CF-AX3 has integrated WiFi, based on an Intel 7260 device. To find out which network controllers you have on your machine, issue the following in the second terminal (the one not displaying the interface):

and observe the output.

In the case of the CF-AX3, this returns:

(your machine will most likely differ).

On the CF-AX3, the built-in Ethernet adaptor is (obviously!) already working under the current kernel configuration, but the Intel 7260 wireless card is not.

Now, while the firmware for this 7260 is already included in (which we installed earlier), using it requires MVM firmware support (which, at the time of writing, the minimal-install kernel configuration has disabled).

Set the following options (within ) to rectify this, and thereby activate WiFi:

Incidentally, the 7260 device also supports WiMAX, but as of the time of writing, the ebuilds for do not, so I have not detailed its activation here.

<span id="config_bluetooth">Bluetooth
Like many modern notebooks, the CF-AX3 has an integrated Bluetooth modem. To see information about your system's Bluetooth hardware, issue in the second terminal (the one not displaying the interface):

To enable it on the CF-AX3, set the following options (this will work for many other machines too):

You must now ensure that the Bluetooth service will start on boot. To do so, issue:

<span id="config_touchscreen">Touchscreen
As is increasingly common, the CF-AX3 has a touchscreen (an eGalaxTouch device in this case). You can generally find out more information about your touchscreen (and touchpad, if present, although this is likely already supported at this point in the install), by issuing in the second terminal (the one not displaying the interface):

To enable the eGalaxTouch device (this will also work for many other touchscreen panels), set the following options:

<span id="config_webcam">Webcam
The CF-AX3 has an integrated webcam (a common feature on many laptops and netbooks). You can find out more information about your machine's webcam by issuing in the second terminal (the one not displaying the interface):

To enable the webcam on the CF-AX3 (this will work for many modern machines, as many webcams are UVC devices), set the following options:

<span id="config_audio">Audio
The CF-AX3 has an integrated Intel HD audio device, accessed on the PCI bus. You can find out more information about your machine's soundcard by issuing in the second terminal (the one not displaying the interface):

As configured, sound works 'out of the box' for the CF-AX3, but the Wikipedia:PulseAudio sound server complains about lack of high resolution timer support, and insufficiently large buffers. To address these problems on the CF-AX3, set the following options

<span id="config_card_reader">Card Reader
The CF-AX3 has an integrated SD/MMC card reader. You can find out more information about your machine's reader by issuing in the second terminal (the one not displaying the interface):

Although the necessary kernel options ( and ) for this card are modularized in the minimal install kernel, there is a bug impacting the CF-AX3 (and many other machines) which prevents correct initialization when a card is inserted. To fix this, still in the second terminal, issue:

<span id="config_others">Others
There are a couple of other devices on the CF-AX3 which I have not dealt with here:
 * The CF-AX3 has an i7 processor with Intel's Management Engine; if you really want access to this scarily-out-of-band coprocessor, enable the setting in the kernel configuration.
 * It also has a number of integrated sensors (geomagnetic, gyroscopic, acceleration etc.); however, these are not generally supported by Linux applications at the moment, so I haven't detailed their setup here.

Of course, as mentioned earlier, your particular target platform will have its own set of devices that may well not have been mentioned here (for example, MemoryStick readers, digital TV receivers etc.), and you should obviously adapt your kernel configuration accordingly.

Lastly, if you find that your early boot splash is being interrupted with the error message "", then you should ensure that only the KVM option (Intel or AMD) appropriate to your processor is set in the configuration. The relevant options are and.

<span id="finishing_up_config">Finishing Up
When satisfied with your configuration, exit, saving changes. Once you have done so, will automatically create a new kernel with the newly created configuration, sign it, and copy it over to the boot USB key. Wait for the process to complete (you get the message ""). Then (leaving the boot USB key inserted) restart your target machine (you can do this from within GNOME, by clicking on the 'power' icon (in the top right of the screen), clicking on the 'power' button in the dropdown menu that then appears, and then clicking on the 'Restart' button in the dialog).

The machine should then power cycle (you will be cleanly logged out of GNOME first). When it restarts, as before, you will need to enter your LUKS keyfile passphrase (the one you created earlier), directly at the target machine keyboard to unlock the LUKS partition. You should then be presented with a GNOME login page (as previously). Directly at the target machine, click on your (regular) user name then, when prompted, type in the (regular user) password you set up earlier (ensure you have the correct keyboard settings, if relevant, as discussed above).

You should now be able to use all the features of your machine that you just enabled (such as WiFi etc.).

<span id="config_lcd_backlight">LCD Screen Backlight (Addressing the i915 Regression)
One final note. Like most laptops, the CF-AX3 has a dimmable backlight on its LCD screen. With modern kernels (3.17+) and the i915 graphics driver (as used by many Ultrabooks), you may find that you cannot change the display brightness using the standard GNOME controls. This is a regression; if it affects you, first use the process described in "Preliminaries", above to get a root terminal, then issue:

Locate the line specifying. If it is currently commented out (the line starts with a character), then uncomment and edit that line so it reads:

Save and exit the editor.

Now, ensure that you have the boot USB key inserted, and issue:

to rebuild the kernel. Wait for the process to finish (you receive the message ""). Then power cycle the machine as described in "Finishing Up", above.

When you log in again to GNOME, you should find that the screen brightness controls now operate correctly.

<span id="cleaning_kernel_config">Cleaning Up the Kernel Configuration (Optional Step)
As your current Linux kernel is largely derived from the minimal-install image configuration, it contains a lot of modularized and enabled features that are irrelevant to your machine (for example, all the specific x86 platform support drivers for vendors other than yours). While this bloat is mostly harmless, there are a few negative side effects of having features you don't need, for example:
 * the kernel image is larger (which makes boot time slightly longer); even even where most features are modularized, since all modules are copied into the initramfs, which is then integrated into the kernel itself. This can be an important consideration if you choose to migrate your kernel into the (often cramped) Windows EFI system partition (instructions for which are provided later);
 * more code must be (uselessly) compiled each time you upgrade your kernel, which costs time; and
 * more features = a larger attack surface exposed to malware.

Accordingly, you may wish to perform another run, disabling features that do not apply to you. If so, proceed carefully: deselect some features, complete the build, and reboot; then repeat. This always allows you to fall back to the previous version kernel if something goes wrong, and you find you have chopped out something vital by mistake.

<span id="using_localmodconfig">Several commentators have suggested using to automate this task,    but that can be dangerous (as any modules not currently loaded by the kernel will be purged from the configuration, which can result in filesystem drivers, crypto modules, codepages etc. being dropped). Furthermore, there are lots of 'false positive' loaded modules retained as well (e.g. ATA drivers) when you use this method. The best approach remains to work through manually, and do things methodically; nevertheless if you do wish to try out for yourself, proceed as follows:

First, if you don't have a root terminal open already in GNOME, do so now: press the, and type 'terminal', then press. A standard-issue terminal window should open. Become root:

The password required here is the one you set up earlier in the tutorial (and have used when -ing in).

Then in this terminal, issue:

to create a 'last known good' backup of the current kernel (and configuration) on the USB boot key (this ensures that there's no risk we lose our 'safe' version, which might otherwise happen were we to run twice in a row between test reboots).

Now switch to the kernel directory, ask to do its magic, then return:

Finally, ensure you have the boot USB key inserted, and create a new kernel based on the stripped-down configuration:

This will allow you to review the proposed configuration for sanity in the tool, and make any necessary changes.

When satisfied with your configuration, exit, saving any changes. Once you have done so, will automatically create a new kernel with the newly created configuration, sign it, and copy it over to the boot USB key, as before. Once the process completes (you get the message ""), leave the USB key inserted and reboot in the normal manner.

This is very much an optional task, so feel free to postpone it for a rainy day (or forever if you like ^-^ !).

<span id="suspend_hibernate">Suspend and Hibernate
At this point, let's take the time to properly configure power management (suspend and hibernate), as this is a useful feature to have operational on your machine.

The default power management works well for many systems out of the box. The file determines (inter alia) what behaviour will occur when certain buttons are pressed on the machine, specifically that the 'suspend' key ( on the CF-AX3) will invoke the 'suspend' action (aka 'sleep'), and and that the 'hibernate' key ( on the CF-AX3) will invoke the 'hibernate' action (aka 'suspend to disk').

For the CF-AX3, the 'stock' configuration works perfectly for suspend (simply press and the machine will enter sleep state, with its power button light flashing slowly; slide the power button, and it will resume). However, hibernate requires a little further tweaking (it does work, but the system doesn't fully shutdown after the memory image is written to disk). To get around this, we need to request that writes the string "" into, rather than "" (this may be the case on your system too, but try to see if it works without making any changes first).

To achieve this, we need to use the file (which does not exist by default). If you don't have a root terminal open already in GNOME, do so now: press the, and type 'terminal', then press. A standard-issue terminal window should open. Become root:

The password required here is the one you set up earlier in the tutorial (and have used when -ing in).

Then in this terminal, issue:

Put the following text in the file:

Save and exit the editor (you can also close out the terminal if you have no further use for it).

After this, hibernate should work properly (on the CF-AX3). Press and the machine will write its memory to the LVM swap partition on the LUKS encrypted volume ( conforms the kernel command line to specify this, as noted earlier), and then automatically power off. To resume, ensure that the boot USB key is inserted, and slide the power key. Enter your LUKS password when prompted, log in to GNOME, and you should find your desktop just as you left it. As this feature uses encrypted swap, it is relatively safe to travel with the laptop hibernated in this fashion (you should unplug and carry the boot USB key separately, of course).

<span id="set_default_python">Setting the System Default Interpreter
This is a bit of an odd one, but it does seem to catch people out. Python is a widely used dynamic language. There are two major versions (2.0 and 3.0), and a lot of python scripts that you find on the web use the older version. The problem is that these scripts also often start with a versionless shebang like:

On Gentoo, this will end up invoking Python 3.x (not 2.x), thereby (often) causing the script to break.

It's generally safe to set the default to refer to version 2.7 instead (since scripts that require version 3 will explicitly call it).

To do so, open a root terminal in GNOME (if you don't already have one open): press the, and type 'terminal', then press. A standard-issue terminal window should open. Become root:

The password required here is the one you set up earlier in the tutorial (and have used when -ing in).

Then in this terminal, issue:

Your output may very somewhat from the above, but you should see that one of the lines has a '2.7' version (it is in the above). Now set it as the default:

That's it! There's no need to run here as we've really just switched a symbolic link, not installed anything new on the machine.

<span id="disabling_sshd">Disabling
Up until now, you've been running (the secure shell daemon) on your target machine, to allow for simpler configuration via a helper PC. This is no longer required, and running such a service can present security risks. Unless you have good reason to keep it, stop now (and ensure it does not restart again on boot).

To do so, open a root terminal in GNOME (if you don't already have one open): press the, and type 'terminal', then press. A standard-issue terminal window should open. Become root:

The password required here is the one you set up earlier in the tutorial (and have used when -ing in).

Then in this terminal, issue:

<span id="next_steps">Next Steps
Once you have worked through the above points to your satisfaction, congratulations - you now have a fully functioning dual-boot machine! We'll now cover a few quick points about day-to-day maintenance, cleanup, and other software you might like to install. Click here to go to the next (and final) chapter, "Using Your New Gentoo System".

Introduction
Gentoo provides two ways for users to handle kernel configuration, installation, and upgrades: automatic (genkernel) and manual. Although the automatic method can be regarded as easier for most users, there are a number of reasons why a large proportion of Gentoo users choose to configure their kernels manually:


 * 1) Greater flexibility
 * 2) Smaller (kernel) sizes
 * 3) Shorter compilation times
 * 4) The learning experience
 * 5) Severe boredom
 * 6) Absolute knowledge of kernel configuration, and/or
 * 7) Complete control

This guide does not cover the automatic method (genkernel). If genkernel is preferred method of handling matters related to the kernel head over to the Genkernel article for details.

This guide does not attempt to document the manual configuration process from start to finish — the configuration process relies upon a large degree of common sense and a relatively high level of technical knowledge about the system being used. Instead it will introduce the concepts of manual configuration and detail the most common pitfalls which users face.

At this point, the user is presumed to have Linux kernel sources unpacked on the hard disk (usually somewhere under ), and is expected to know how to enter the configuration utility with knowledge to navigate through the ncursers-based menu system. If the user is not at this stage, other documentation is available to help. Read the following articles, then return to this guide:


 * The Kernel sources overview article contains information on the various kernel source packages available in the Portage tree.
 * The Kernel upgrade article explains how to upgrade a kernel or switch from one kernel to another.
 * The Gentoo Handbook's kernel configuration section covers some aspects of kernel installation. Select the appropriate architecture, then navigate to section titled "Configuring the Linux kernel".

The basics
The general process is actually rather simple: a series of options, categorized into individual menus and sub-menus, are presented and the desired hardware support and kernel features relevant to the system are selected.

The kernel includes a default configuration, which is presented the first time menuconfig is run on a particular set of sources. The defaults are generally broad and sensible, which means that the majority of users will only have to make a small number of changes to the base configuration. When deciding to disable an option that was enabled from kernel's default configuration, make sure a good understanding has been obtained of exactly what that option does, and the consequences of disabling it.

During a first time Linux kernel configuring, aim to be conservative; do not be too adventurous, and try make as few modifications to the default settings as possible. At the same time, keep in mind that there are certain parts to a system's setup that must be customized to actually allow for the system to boot.

Built-in vs modular
Most configuration options are tristate: they can be either not built at all, built directly into the kernel  , or built as a module. Modules are stored externally on the filesystem, whereas built-in items are built directly into the kernel image itself.

There is an important difference between built-in and modular: with a few exceptions, the kernel makes no attempt whatsoever to load any external modules when the system might need them; it is left up to the user to decide when, or when to not, load a module. While certain other parts of the system may have load-on-demand facilities, and there are some automatic module loading utilities available, it is recommended to build hardware support and kernel features directly into the kernel. The kernel can then ensure the functionality and hardware support is available whenever needed. This is done by setting each kernel feature to (Y). For this setup to be coherent it is also necessary to include firmware support in the kernel. This is done setting  and   in the kernel's  or by the following:

For other parts of the configuration, built-in is an absolute requirement. For example, if the root partition was an btrfs filesystem the system would not boot if btrfs was built as a module. The system would have to look on the root partition to find the btrfs module (since modules are stored in the root partition), but it cannot look on the root partition unless it already has btrfs support loaded! If btrfs has not been built-in then the init process will fail to find the root device.

Hardware support
Beyond detecting the architecture type of the system, the configuration utility makes no attempt to identify what hardware is actually present in the system. While there are default settings for some hardware support, users almost certainly need to find and select the configuration options relevant to each system's hardware configuration.

Selecting the proper configuration options requires a knowledge of the components inside and connected to the computer. Most of the time these components can be identified without taking the lid off the system. For most internal components, users need to identify the chipset used on each device, rather than the retailed product name. Many expansion cards are retailed with a certain brand name, but use another manufacturer's chipset.

There are some utilities available to help users determine what kernel configuration options to use. (part of the package) will identify PCI-based and AGP-based hardware, this includes components built onto the motherboard itself. (from the package) will identify various devices connected to the system's USB ports.

The situation is somewhat confused by varying degrees of standardization in the hardware world. Unless the user selects extreme deviation from the default configuration settings, the IDE hard disks should "just work", as will the PS/2 or USB keyboard and mouse. Basic VGA display support is also included. However, some devices such as Ethernet adapters are hardly standardized at all; for these devices users will have to identify the Ethernet chipset and select the appropriate hardware support for the specific card to get network access.

In addition, while some things just-about-work with the default settings, more specialized options may need to be selected to get the full potential from the system. For example, if support for the appropriate IDE chipset has not been enabled, the IDE hard disks will run very slowly.

Kernel features
In addition to hardware support, users need to consider the software features that will be required in the kernel. One important example of such a feature is filesystem support: users must select support for the filesystems in use on their hard disks, as well as any filesystems they might use on external storage devices (e.g. VFAT on USB drives).

Another common software feature example is advanced network functionality. In order to do some kind of routing or firewalling the relevant configuration items must be included in the kernel configuration.

Ready?
Now that the concepts have been introduced, it should be easy to start identifying the system hardware, browsing through the menuconfig interface, and selecting the required kernel options for the system.

The rest of this guide should clear up common areas of confusion, and provide advice for how to avoid common problems which users often run into. Best wishes!

SATA disks are SCSI
Most modern desktop systems ship with storage devices (hard disk and CD/DVD drives) on a Serial ATA bus, rather than the older IDE (ribbon cable) bus type.

SATA support in Linux is implemented in a layer referred to as libata, which sits below the SCSI subsystem. For this reason, SATA drivers are found in the SCSI driver section of the configuration. Additionally, the system's storage devices will be treated as SCSI devices, which means SCSI disk/cdrom support will also be required. The first SATA hard disk will be named and the first SATA CD/DVD drive will be named.

Although the majority of these drivers are for SATA controllers, libata was not designed to be SATA-specific. All common IDE drivers will also be ported to libata in the near future, and at this point, the above considerations will also apply for IDE users.

IDE chipsets and DMA
Despite the introduction of SATA, IDE devices are still very common and depended upon by many systems. IDE is a fairly generic technology, and as such, Linux supports almost all IDE controllers out-of-the-box without any controller-specific options selected.

However, IDE is an old technology, and in its original Programmed Input/Output incarnation, it is unable to provide the transfer rates required for speedy access to modern storage devices. The generic IDE driver is limited to these PIO transfer modes which result in slow data transfer rates and significantly high CPU usage while data is being transferred to and from disk.

Unless a user is dealing with a pre-1995 system, the IDE controller will also support an alternative transfer mode, known as Direct Memory Access (DMA). DMA is much much faster, and CPU utilization is barely affected while data transfers are taking place. If the system is suffering from really poor general system performance while it is using an IDE disk, chances are that DMA is not being used and should be enabled.

When not using libata for IDE disks check for DMA usage and enable it. The following command can be used to determine if DMA is being used:

To enable DMA for older IDE devices (which is a deprecated setting), enable the following kernel features.

USB host controllers
USB is a widely adopted bus for connecting external peripherals to a computer. One of the reasons behind the success of USB is that it is a standardized protocol, however the USB host controller devices (HCDs) implemented on the host computer do vary a little. There are 4 main types:


 * 1)   is the Universal Host Controller Interface. It supports USB 1.1, and is usually found on motherboards based on a VIA or Intel chipset.
 * 2)   is the Open Host Controller Interface. It supports USB 1.1 and is usually found on motherboards based on an Nvidia or SiS chipset.
 * 3)   is the Extended Host Controller Interface. It is the only common host controller to support USB 2.0, and can typically be found on any computer that supports USB 2.0.
 * 4)   is the eXtensible Host Controller Interface. It is the host controller for USB 3.0 and is compatible with USB 1.0, 1.1, 2.0, 3.0 and future speeds. Enable this feature when the board supports USB 3.0.

Most systems come with two of the above interface types: XHCI (USB 3.0) and EHCI (USB 2.0). To use USB devices, it is no longer necessary to select both options since XHCI is compatible with slower USB-controllers. Users can also enable EHCI to be "extra" safe; it does no harm if USB 2.0 controllers are unavailable.

If the relevant options corresponding to the USB HCD types present on the system are not selected, then 'dead' USB ports may be experienced. This case can be determined if a working USB device is plugged in, but it does not get power or respond in any way.

A neat trick (from the  package) makes it relatively easy to detect which HCDs are present on system. Ignoring the SATA controller which was also matched, it is easy to spot that this system requires EHCI and XHCI support:

Select the HCDs present on the system. In general select all three options for maximum support, or if the correct option is uncertain:

In Linux kernel 3.12.13 and later,   has to be enabled if the USB controller is OHCI and a USB keyboard or mouse is used.

Multiprocessor, Hyper-Threading and multi-core systems
Many computer systems are based on multiple processors, but not always in an immediately obvious way.


 * Many of Intel's CPUs support a technology which they call hyper-threading. This technology enables a single CPU to be viewed by the system as two logical processors.
 * Most Intel/AMD CPUs actually consist of multiple physical processors inside a single package, these processors are known as multi-core processors.
 * Some high-end computer systems actually have multiple physical processors installed on specialized motherboards to provide a significant performance increase over a uniprocessor system. System users will probably know if they have such a system, since they are not cheap.

In all of these cases, the appropriate kernel options must be selected to obtain optimum performance from these setups:

The next option not only enables power management features, but might also be a requirement for making all CPUs available to the system:

x86 High Memory support
Due to limitations in the 32-bit address space of the architecture, a kernel with default configuration can only support up to 896MB RAM. If a system has more memory, only the first 896MB will be visible, unless high memory support has been enabled.

High memory support is not enabled by default, because it introduces a small system overhead. Do not be distracted by this, the overhead is insignificant when compared to the performance increase of having more memory available!

Choose the 4GB option, unless your system has more than 4GB of RAM:

Compressed kernel modules
From kernel version 3.18.x (and up) compression of kernel modules has been possible. gzip and xz compression are available. It is important to emerge with the proper USE flags before compiling a kernel with compressed modules:

Re-emerge :

Enable module compression and select a preferred compression method:

Usually runs. If did not have the proper USE flags set (see the  step above) the first time it was run, then the dependency list will be empty. The system will therefore be unable to load any modules that were built compressed.

After kmod has been recompiled, re-run as a solution to this problem:

Introduction
When reading about kernel configuration, often times settings are described as CONFIG_. This short-hand notation is what the kernel configuration actually uses internally, and is what will be found in the kernel configuration file (be it or in the auto-generated  file). Of course, using short-hand notation would not do much good if this cannot translate this to the real location in the kernel configuration. The tool makes this possible.

Translating CONFIG_FOO to the real configuration location
Suppose the CONFIG_TMPFS_XATTR feature needs to be enabled. Launch the kernel configuration menu and press the  key. This will open a search box. In the search box, type CONFIG_TMPFS_XATTR.

The following is an output of the result of this search:

This output yields lots of interesting information.

With this information, it should be possible to translate any CONFIG_* requirements fairly easily. In short, it means a user must


 * 1) Enable the settings described in the Depends on field;
 * 2) Navigate where Location: points;
 * 3) Toggle the value referred to by Prompt:;

Other kernel configuration documentation
So far only general concepts and specific problems related to kernel configuration has been discussed; precise details have been left up to the user to discover. However, other parts of the Gentoo documentation collection provide specialized details for the topics at hand.

Such documents may be helpful while configuring specific areas of the kernel. Although this warning was mentioned previously in this guide, remember: users who are new to kernel configuration should not be adventurous when attempting to configure their kernels. Start by getting a basic system up and running, support for your audio, printing, etc., can always be added at a later date.

Getting the basics of a kernel operational will help users in later configuration steps because the user will know what is breaking their system and what is not. It is always wise to save the base (working) kernel configuration in a folder other than the kernel's sources folder before attempting to add new features or hardware.


 * The ALSA article details the configuration options required for sound card support. Note that ALSA is an exception to the suggested scheme of not building things as modules: ALSA is actually much easier to configure when the components are modular.


 * The Bluetooth article details the options needed in order to use Bluetooth devices.


 * The IPv6 router guide describes how to configure the kernel for routing using the next generation network addressing scheme.


 * If the closed-source nVidia graphics drivers will be used for improved 3D graphics performance, the nVidia Guide lists the options that should and should not be selected on such a system.


 * Amongst other things, the Power Management guide explains how to configure the kernel for CPU frequency scaling, and for suspend and hibernate functionality.


 * If running a PowerPC system, the PPC FAQ has a few sections about PPC kernel configuration.


 * The Printing guide lists the kernel options needed to support printing in Linux.


 * The USB Guide details the configuration settings required to use common USB devices such as keyboards, mice, storage devices, and USB printers.

Configuration changes do not take effect
It is very common for users to make a configuration change, but then make a small mistake in the process of actually booting to their newly configured kernel. They reboot into a kernel image that is not the one they just reconfigured, observe that whatever problem they were trying to solve is still present, and conclude that the configuration change does not solve the problem.

The process of compiling and installing kernels is outside the scope of this document; refer to the Kernel Upgrade Guide for general guidance. In short, the process to get a modified kernel is the following: 1) configure, 2) compile, 3) mount (if not already mounted), 4) copy new kernel image to, 5) Make sure the bootloader will reference the new kernel, 6) reboot. If one of those final stages has been missed, then the changes will not properly take effect.

It is possible to verify if the kernel that has booted matches the newly kernel compiled on the hard disk. This is performed by examining the date and time of the kernel's compilation. Assuming the system architecture is and the kernel sources are installed at, the following command can be used:

The above command will display the date and time the currently booted kernel was compiled.

The above command displays the date and time that the kernel image on the hard disk was last compiled.

If the time stamps from the above commands differ by more than 2 minutes, it indicates a mistake was made during kernel reinstallation and the system has not booted from the newly modified kernel image.

Modules do not get loaded automatically
As mentioned earlier in this document, the kernel configuration system hides a large behavioral change when selecting a kernel component as a module (M) rather than built-in (Y). It is worth repeating this again because so many users fall into this trap.

When selecting a component as built-in, the code is built into the kernel image (bzImage). When the kernel needs to use that component, it can initialize and load it automatically, without any user intervention.

When selecting a component as a module, the code is built into a kernel module file and installed on the filesystem. In general, when the kernel needs to use that component, it will not be able to find it. With some exceptions, the kernel makes no effort to actually load these modules — this task is left up to the user.

If building support for a network card as a module, and it is discovered the network is not accessible, it is probably because the module is not loaded — either this must be done manually or the system must be configured to autoload the module at boot time.

Unless a user has a reasons to do otherwise, some time can be saved by building these components directly into the kernel image, so that the kernel can automatically configure these small settings by itself.

Introduction
As with everything else in Gentoo Linux, the philosophy of the Gentoo Kernel team is to give the user as much freedom of choice as possible. When looking at the output of it is easy to see a large variety of kernels to choose from. This document will attempt to give a brief rundown of the goals of each of the patch sets that Gentoo provides and also explain other kernel sources that are available.

Genkernel
is a kernel toolset that can be used to automatically detect hardware and configure some options in the kernel automatically. This is usually recommended for users who do not feel comfortable about compiling a kernel manually.

For more information, please read the Genkernel article.

General purpose: gentoo-sources
For most users, the kernel is recommended. gentoo-sources is a kernel based on Linux 4.x, lightly patched to fix security problems, kernel bugs, and to increase compatibility with the more uncommon system architectures.

The package absorbs most of the resources of the Gentoo kernel team. They are brought to the user by a group of talented developers, which can count on the expertise of popular kernel hacker Greg Kroah-Hartman, maintainer of udev and responsible for the USB and PCI subsystems of the official Linux kernel.

For servers: hardened-sources
The kernel is based on the official Linux kernel and is targeted at users running Gentoo on server systems. It provides patches for the various sub-projects of Gentoo Hardened (such as support for SELinux and grsecurity), together with stability and security-enhancements. Check out the Hardened project here on the wiki for more information.

ck-sources
is Con Kolivas's kernel patch set. This patchset is primarily designed to improve system responsiveness and interactivity and is configurable for varying workloads (from servers to desktops). The patchset includes a different scheduler, BFS, designed to keep systems responsive and smooth even when under heavy load. Support and information is available at http://kernel.kolivas.org and in the  channel on irc.oftc.net.

git-sources
The package tracks daily snapshots of the upstream development kernel tree. These kernels are good for users interested in kernel development or testing. Bug reports should go to the Linux Kernel Bug Tracker or LKML (Linux Kernel Mailing List).

Architecture dependent kernels
and are, as their names suggest, patched to run best on specific architectures. They also contain some of the patches for hardware and features support from the other patch sets mentioned above and below.

Unsupported kernel packages
Now to briefly describe some of the other which scrolled by when the  command was run. Below we discuss each one of them individually. These kernels are provided as a courtesy only — the various patch sets are not supported by the Gentoo kernel team. There is no specific preference to one source or another, so we review the kernel sources in alphabetical order.

aufs-sources
The package contains full kernel sources including the official genpatchset (found in gentoo-sources) for the 3.1x kernel tree and aufs3 support. This kernel is useful when attempting to utilize the aufs3 filesystem. For more information see the aufs3 page on Sourceforge or the genpatches homepage.

pf-sources
The kernel brings together parts of several different kernel patches. It includes the BFS patchset from, the patches, LinuxIMQ, and the BFQ I/O scheduler.

openvz-sources
OpenVZ is a server virtualization solution built on Linux. OpenVZ creates isolated, secure virtual private servers (VPSs) or virtual environments on a single physical server enabling better server utilization and ensuring that applications do not conflict. For more information, see http://www.openvz.org.

tuxonice-sources
The (formerly ) are patched with both genpatches which includes the patches found in gentoo-sources, and the patches found in TuxOnIce which are an improved implementation of suspend-to-disk for the Linux kernel, formerly known as suspend2.

This kernel is recommended for laptop users who often rely on being able to suspend their laptop and resume work elsewhere.

usermode-sources
usermode-sources are the User Mode Linux kernel patches and can be found in the package. These kernel patches are designed to allow Linux to recursively run within Linux. User Mode Linux is intended for testing and virtual server support. For more information about this amazing tribute to the stability and scalability of Linux, see http://user-mode-linux.sourceforge.net.

For more information on UML and Gentoo, read the Gentoo User-mode Linux Guide

vanilla-sources
Many Linux users will probably be familiar with the package. These kernels are copies of the official kernel sources released on http://www.kernel.org/. Please note that the Gentoo kernel team does not patch vanilla-sources at all; they are for people who wish to run a completely unmodified Linux kernel. The Gentoo kernel team recommends instead.

Versions of the kernel can be found under this package: 3.x, 4.x.

aa-sources
was a heavily modified kernel with all kinds of patches. The upstream maintainer stopped releasing kernel patchsets and subsequently this package has been removed.

alpha-sources
was a 2.4 kernel with patches applied to improve hardware compatibility for the Alpha architecture. These patches have been developed and are now included in the mainline kernel. Alpha users can run any recent kernel with no need for extra patches.

Architecture dependent kernels
was a 2.6 kernel designed to run on the Sony PlayStation 3 game console.

development-sources
, the official 2.6 kernel from kernel.org, can now be found under the vanilla-sources package.

gentoo-dev-sources
, a 2.6 kernel patched with bug, security, and stability fixes, can now be found under the gentoo-sources package.

grsec-sources
The kernel source used to be patched with the latest grsecurity updates (grsecurity version 2.0 and up) which included, amongst other security-related patches, support for PaX. Grsecurity patches are included in the hardened-sources kernel, so this package is no longer available in Portage.

hardened-dev-sources
can now be found under the hardened-sources package.

hppa-sources
was a 2.6 kernel with patches applied to improve hardware compatibility for the HPPA architecture. These patches have been developed and included in the mainline kernel. HPPA users can now run any recent kernel with no need for extra patches.

mm-sources
The were based on vanilla-sources and contained Andrew Morton's patch set. They included the experimental and bleeding-edge features that were going to be included in the official kernel (or were going to be rejected because they set systems on fire!). They were known to be always moving at a fast pace and could change radically from one week to the other; kernel hackers often used as a testing ground for highly experimental stuff. They have since been removed from the Portage tree.

rsbac-dev-sources
The kernels can now be found under the  package.

rsbac-sources
Back in the days of 2.6-based kernels contained patches to use Rule Set Based Access Controls (RSBAC). It was removed due to lack of maintainers, but has has magically reappeared with the 3.10 kernel series. Use hardened-sources if additional security features are needed.

selinux-sources
, a 2.4 kernel including lots of security enhancements, has been obsoleted by security development in the 2.6 kernel tree. SELinux functionality can be found in the hardened-sources package.

sh-sources
was a 2.6 kernel with patches applied to improve hardware compatibility for the SuperH architecture. These patches have been developed and included in the mainline kernel. SuperH users can now run any recent kernel with no need for extra patches.

sparc-sources
was a 2.4 kernel with patches applied to improve hardware compatibility for the SPARC architecture. These patches have been developed and included in the mainline kernel. SPARC users can now run any recent kernel with no need for extra patches.

uclinux-sources
The are meant for CPUs without MMUs as well as embedded devices. For more information, see http://www.uclinux.org. Lack of security patches as well as hardware to test on were the reasons this package is no longer found in the Portage tree.

win4lin-sources
were patched to support the userland win4lin tools that allowed Linux users to run many Microsoft Windows (TM) applications at almost native speeds. These kernel sources were removed due to security issues.

xen-sources
was a 2.6-based kernel that allowed running multiple operating systems on a single physical system. A user could create virtual environments in which one or more guest operating systems could run on a Xen-powered host operating system.

The patches were incorporated into the mainline Linux kernel as of version 3.0.

For more information on working with Xen and Gentoo, read the Xen article here on the wiki.

zen-sources
The package is designed for desktop systems. It includes code not found in the mainline kernel. The Zen kernel has patches that add new features, support additional hardware, and contains various tweaks for desktops. The Zen 3.8 kernel series is currently masked in the Portage tree. For more information on the Zen kernel please visit Zen Kernel Live Sources website.

This article describes the steps to upgrade to a new kernel.

Installing and using a new kernel
A kernel upgrade may be a good idea when new kernel sources are installed. New kernel sources are sometimes installed while updating the system by running the following command:

Of course, they can be installed directly using the next command (replace gentoo-sources with hardened-sources when using a hardened profile):

Installing new kernel sources doesn't provide the user with a new kernel. It is necessary to make and install a new kernel from the new sources and then reboot the system to actually run the new kernel.

Making a new kernel from the new sources is basically the same process as making a kernel when installing the system. The difference is that one can use the configuration of the old kernel to create a configuration for the new kernel. Using the old configuration saves the user from going through all the kernel options (like ) again.

The configuration of the kernel is saved in a file named in the directory that holds the kernel sources. A new kernel may have options or features the old kernel does not have, or it might not have a feature or option anymore which the old kernel still has. The kernel configuration specifies whether the features and options of a kernel are to be enabled or not, perhaps built into the kernel, or perhaps built as modules which can be loaded into the running kernel on demand. Hence the configuration file of the new kernel may have new entries the configuration file of the old kernel doesn't have, and it might not have entries anymore which are present in the configuration file of the old kernel.

To deal with such changes of the configuration file, the configuration file of the old kernel needs to be converted to a configuration that can be used with the new kernel. This article shows how to make a new kernel from new kernel sources with converting the configuration file of the old kernel.

Make a backup of the current kernel configuration
It is wise to make a backup of the kernel configuration so that the previous configurations are not lost. After all, many users devote considerable time to figure out the best configuration for the system, and losing that information is definitely not wanted.

It is easy to make a backup of the current kernel configuration:

Provided that the symlink to the kernel sources has been set correctly, this copies the configuration of the currently used kernel to the home directory of root, renaming the configuration to followed by the version of the current running Linux kernel.

Set symlink to new kernel sources
The symlink should always point to the directory that holds the sources of the kernel which currently runs. This can be done in one of three ways:


 * 1) Installing the kernel sources with
 * 2) Setting the link with eselect
 * 3) Manually updating the symbolic link

Installing the kernel sources with the symlink USE flag
This will make the point to the newly installed kernel sources.

If necessary, it can still be modified later with one of the other two methods.

Setting the link with eselect
To set the symlink with :

This outputs the available kernel sources. The asterisk indicates the chosen sources.

To change the kernel sources, e.g. to the second entry, do:

Manually updating the symbolic link
To set the symbolic link manually:

Copy previous kernel configuration
The configuration of the old kernel needs to be copied to the new one. It can be found in several places:


 * In the procfs filesystem, if the kernel option Enable access to .config through /proc/config.gz was activated in the present kernel:


 * From the old kernel. This will only work when the old kernel was compiled with CONFIG_IKCONFIG:


 * In the directory, if the configuration was installed there:


 * In the kernel directory of the currently-running kernel:


 * In the directory, if   is set in  and  was previously used:

Configure the new kernel
To use the configuration of the old kernel with the new kernel, it needs to be converted. The conversion can be done by running either or. Use either, not both.

make silentoldconfig
The following configuration is like the text based configuration with. For new configuration options, the user is asked for a decision. For example:

The string (NEW) at the end of the line marks this option as new. Left to the string in square brackets are the possible answers: Yes, no, module or ? to show the help. The recommend (i.e. default) answer is capitalized (here Y). The help explains the option or driver.

Unfortunately doesn't show a lot more information for each option, such as the context, so it is sometimes difficult to give the right answer. In this case the best way to go is to remember the option name and revise it afterwards through one of the graphical kernel configuration tools.

make olddefconfig
If all new configuration options should be set to their recommended (i.e. default) values use :

make help
Use to see other conversion methods available:

Build
For this step, follow the steps in the manual configuration article.

Reinstalling external kernel modules
Any external kernel modules, such as binary kernel modules, need to be rebuilt for each new kernel. If the kernel has not been built yet, it has to first be prepared for the building of the external kernel modules:

Packages containing kernel modules can be rebuilt using the  set:

Solving build problems
When experiencing build problems while rebuilding the current kernel, it might help to sanitize the kernel sources. Make sure to backup the file first, as the operation will remove it. Make sure not to use a or  suffix as backup as  will clean those up as well.

Removing old kernels
See the kernel removal article.

External resources

 * kernel changelog with some explanations of new features

<span id="using_your_new_system">In this (final) section, we'll consider a number of miscellaneous (but important) topics regarding your new system. Although this final part of the tutorial has no precise analogue in the Gentoo manual, it logically relates to Chapter 11.

The topics we'll briefly cover are:
 * recapping how to boot to Linux from Windows (and vice versa);
 * keeping your machine up to date;
 * migrating your kernel to the internal hard drive (optional);
 * and how to dispense with the USB key entirely (also optional);
 * tweaking GNOME; and
 * installing a firewall, and other applications; plus
 * links to some additional 'mini-guides', that don't fit naturally within the rest of the tutorial.

Let's go!

<span id="dual_boot_procedure">Booting into Linux or Windows (Recap)
With the setup you have just carried out, you can easily boot your target PC into either Gentoo Linux or Windows, as desired. Here's a brief recap of how to go about it (with links back to the more detailed explanations in the body of the text, where relevant):
 * If you power up the machine without the boot USB key inserted, Windows will always load automatically. You can do this safely even if you hibernated your Linux session last time (assuming you had no Windows partitions mounted in Linux!).
 * All your Linux data is ultimately held within an encrypted LUKS partition, and so cannot be 'snooped' by malware running in Windows. Nor can Windows software read your keyfile or kernel, as the boot USB key is not physically present when Windows is running.
 * Windows updates etc. should leave the LUKS partition entirely unaffected (and cannot access the boot USB key either, assuming you don't insert it mid-session).
 * If you <span id="win8_to_linux">are running Windows, and wish to reboot into Linux instead, be sure to restart the machine from Windows (not shut it down - unless you have disabled hybrid shutdown as was recommended at the start of the tutorial). Insert the boot USB key while the system is closing down prior to the reboot. Then, immediately the machine commences restarting, enter the BIOS (the key combination needed to do this varies from machine to machine, it is on the CF-AX3). If you set one earlier, you'll need to enter your BIOS password at this point. Then, choose "" as the highest priority EFI boot entry, save changes and restart (if the BIOS does not immediately recognize the USB key, you may need to do the 'save changes and restart' cycle twice). A more detailed exposition of how to do this on the CF-AX3 was presented earlier in the text. The machine should then restart into Linux as usual.
 * Now, if you are running Linux, and then power down the machine, then power it back up with the USB key inserted, it should start up Linux again automatically (you'll have to enter your LUKS keyfile passphrase (the one you created earlier) to gain access of course). It is entirely safe to remove the boot USB key once you get to the GNOME login screen (and indeed, it is recommended that you do so, for security). You can do any work you like under Linux, power the machine down, suspend or hibernate it, without needing to re-insert the boot USB key. Then:
 * If you suspend (sleep) the machine from Linux, you can come back out of suspend without needing to re-insert the key (just slide the power button).
 * If you hibernate the machine from Linux, insert the boot USB key immediately before powering up again. Upon restart, you'll have to enter the GPG-encrypted LUKS keyfile passphrase, and should then be presented with a GNOME login prompt (as before, you can remove the boot USB key at this point). Log in, and you'll find your desktop the way you left it on hibernation.
 * If you power the machine off from Linux, simply remember to insert the USB key before sliding the power key again (otherwise you'll reboot into Windows, as above).
 * Similarly, if you have hibernated from Linux, and power back up without re-inserting the boot USB key, your machine will come up in Windows. This isn't a problem (unless you had any of the Windows partitions deliberately mounted in your Linux session!), because you can use Windows as necessary and then, when done, follow the process above to restart back into Linux again (it'll remember that you hibernated, and come back into your old session).

The whole process is easier to do in practice than it is to describe! It has the advantage of not requiring multiple EFI system partitions on the machine's main drive (something which Microsoft specifically cautions is unsupported under Windows ), nor a separate bootloader. Furthermore, Windows will sometimes overwrite the EFI boot list anyway, even when a bootloader is used, so taking that approach doesn't necessary buy you anything.

If you would like to use Windows' EFI system partition (the one on the internal drive) to store your kernel (or even dispense with the need for a USB key during boot altogether), instructions for doing so will be provided later in this chapter.

<span id="updating_software">Keeping Your Machine Up to Date
The tool makes it easy to keep your machine (kernel and packages) up to date. To perform a full update at any time, first open a root terminal in GNOME (if you don't already have one open): press the, and type 'terminal', then press. A standard-issue terminal window should open. Become root:

The password required here is the one you set up earlier in the tutorial (and have used when -ing in).

Ensure that your boot USB key is inserted (this will be required if there is a kernel upgrade). Then, in this terminal, issue:

and the update will proceed automatically (the option means that, although not running in interactive mode per se, you will be prompted to resolve clashing changes to configuration files, should any arise, and the  will copy over any new kernel to the boot USB key, once built). When the process completes (you get the message ""), remove the boot USB key again, and close out the terminal.

If the output of informed you that a new kernel has been built, you should reboot your machine at this point to start using it.

<span id="automating_genup">Automating (Optional)
To ensure you don't forget updates, you can schedule to run automatically (this is entirely optional, of course). One simple approach is to use to have it executed every night (at around 3am on most systems; check  for details ).

To set this up, first open a root terminal in GNOME (if you don't already have one available): press the, and type 'terminal', then press. A standard-issue terminal window should open. Become root:

The password required here is the one you set up earlier in the tutorial (and have used when -ing in).

Then issue:

Then <span id="genup_cron_file">put the following text in the file:

Save and exit the editor, and make the file executable:

(You can now close out the root terminal if you have no further use for it.)

<span id="overnight_genup">That's it! Your system will now attempt to update each night, without requiring any input from you. Also, because you have not specified here, there's no need to have your boot USB key inserted when the process runs (any new kernel will still be built, but then simply retained in the staging area at, until you issue , as described shortly).

Although this is automatic, you do need to do a bit of checking periodically that this worked OK (each morning, say). To do this, open a root terminal in GNOME (as just described), and issue:

If the tail of the log just printed contains text similar to the below:

then, as instructed, you need to run ; so do so now:

See the explanation earlier in this tutorial for how to use.

<span id="deploy_batch_kernel">Next, if the tail of the log contains text similar to the below:

then you need to copy it across (it has already been built in the staging area). Insert your boot USB key, then issue:

When this completes (it shouldn't take long), remove the boot USB key, and close out the root terminal if you have no further use for it (or, alternatively, leave the key inserted and reboot, to start using your new kernel immediately).

<span id="switching_to_webrsync">Switching to for Security (Optional)
This is an entirely optional step, but you may choose to update your local portage tree with only signed snapshots, as opposed to using. This is considerably less efficient in terms of bandwidth, but does provide protection against rogue mirrors adding or changing code or packages.

To make use of this feature, follow the instructions under "Pulling Validated Portage Tree Snapshots" in the Gentoo Handbook (summarized again below for convenience).

First, open a root terminal in GNOME (if you don't already have one available): press the, and type 'terminal', then press. A standard-issue terminal window should open. Become root:

The password required here is the one you set up earlier in the tutorial (and have used when -ing in).

Then make a directory to hold the necessary public keys:

Next, download and accept the Gentoo release engineering keys, as specified on the Release Engineering page. You need at least the fingerprint of the key described as "Gentoo Portage Snapshot Signing Key (Automated Signing Key)":

You can set the key's trust at this point if you like. However, it isn't necessary ( just looks at the exit value of ). Next, edit, and enable support for validating the signed Portage tree snapshots. Issue:

and append:

Save and exit the editor.

There is no need to disable conventional (pace the handbook), as it won't be used unless you explicitly call it (with ). Note however that you must take care to use the option with  (so that it calls, rather than , internally). If you are using to manage your updates, this is taken care of for you automatically (it will notice that the  feature has been set and act accordingly).

Try it out now, to make sure everything is still working:

Note that this will take quite a bit longer than before, as it has now to pull down the full Portage tree each time. However, if you have automated the process to run overnight, this shouldn't impact you too much.

When completed, close out the root terminal if you have no further use for it.

<span id="migrating_off_usb_key">Migrating Off the Boot USB Key (Optional)
Up until now, we have been using a boot USB key to hold your (stub EFI) kernel and GPG-encrypted LUKS keyfile. This approach has a number of advantages:
 * It let us get around the 'EFI chicken and egg' problem - namely that it is only possible to modify the EFI boot list when already booted under EFI - by exploiting the exception that most UEFI BIOSes will boot specially named EFI images on removable drives. Of course, now we have an EFI system running, this advantage is moot.
 * It provides dual factor security - you need both the keyfile and its passphrase to access the LUKS partition. This confers a degree of protection against hardware keyloggers etc., which a 'passphrase only' (or, indeed, 'keyfile only') LUKS approach would lack.
 * Similarly, if you physically destroy the USB key and all backups, your LUKS data will be gone forever. Even someone with your GPG passphrase would be unable to recover it. Of course, this is a double-edged sword!
 * If the system is booted without the key inserted, it will automatically come up in Windows.
 * When Windows is running, malware is unable to see your kernel image (assuming you leave the USB key unplugged) nor can it copy your GPG-encrypted keyfile.
 * Similarly, there is no risk of Windows accidentally (during an upgrade, for example) overwriting your kernel, or experiencing problems because your kernel has consumed too much space in the (internal hard drive) EFI system partition.
 * You can use a large-capacity USB key, with plenty of room for snapshot backups etc.

Nevertheless, some users may prefer to use their internal hard drive's EFI system partition to store the kernel (retaining the USB key for GPG-encrypted keyfile only, to preserve dual-factor security). Others may like to go even further, and remove the need for the USB key altogether on boot (relying on a passphrase only, Ubuntu-style ). While there are six logical possibilities here (and all are simple to achieve via ), not all make sense, as the table below demonstrates:

Accordingly, instructions are provided below for migration from option 1 (which you have now) to options 4 and 6, below.

<span id="option_4_migration">Using the Internal Drive EFI System Partition for the Kernel (Option 4)
This <span id="option_4_comments">is a somewhat attractive option. By using the (Windows) EFI system partition to store the kernel, boot times are reduced, and you can perform full upgrades (including any kernel deployment) without having to insert the USB key. However, you may experience issues due to the lack of space in the internal drive EFI system partition, particularly if you have not slimmed down your kernel configuration (as described earlier).

When using the internal drive EFI system partition, Windows malware can read your kernel (and configuration), although it is protected against tampering by its cryptographic signature (of course, malware with access to the Microsoft private keys could modify your kernel and resign it...).

A final point to bear in mind is that, whenever you wish to restart from Linux to Windows, you will have to change the EFI boot list explicitly, using the tool (the use of which was described previously). You can no longer simply restart the machine without the boot key present (as you can with 'option 1').

With all that in mind, if you still wish to migrate to an 'option 4' configuration, proceed as follows.

First, open a root terminal in GNOME (if you don't already have one available): press the, and type 'terminal', then press. A standard-issue terminal window should open. Become root:

The password required here is the one you set up earlier in the tutorial (and have used when -ing in).

Next, use the tool to make the necessary changes to.

Issue (the following session is an example only; the values output will obviously vary for your machine):

Now rebuild the kernel (it will attempt to save the result to the internal EFI system partition now, not to the boot USB key):

Once the build completes (make sure it works successfully, and that you get the prompt "" at the end), ensure your USB (boot) key is inserted, and restart your machine (you can do this from within GNOME, by clicking on the 'power' icon (in the top right of the screen), clicking on the 'power' button in the dropdown menu that then appears, and then clicking on the 'Restart' button in the dialog).

The machine should then power cycle (you will be cleanly logged out of GNOME first). When it restarts, as before, you will need to enter your LUKS keyfile passphrase (the one you created earlier), directly at the target machine keyboard to unlock the LUKS partition. You should then be able to log into GNOME as usual.

<span id="option_6_migration">Completely Removing the Need for a Boot USB Key (Option 6)
This is the most convenient option for everyday use, since no USB key is required at all: the backup LUKS passphrase is prompted for at boot time, and the kernel is contained on the internal drive (Windows) EFI system partition. However, dual-factor security is lost with this approach. It is otherwise similar to option 4 above, so please read through the comments there before continuing.

If you still wish to migrate to an 'option 6' configuration, proceed as follows.

First, open a root terminal in GNOME (if you don't already have one available): press the, and type 'terminal', then press. A standard-issue terminal window should open. Become root:

The password required here is the one you set up earlier in the tutorial (and have used when -ing in).

Next, use the tool to make the necessary changes to.

Issue (the following session is an example only; the values output will obviously vary for your machine):

Now rebuild the kernel (it will attempt to save the result to the internal EFI system partition now, not to the boot USB key):

Once the build completes (make sure it works successfully, and that you get the prompt "" at the end), remove your USB (boot) key (you won't need it any more!), and restart your machine (you can do this from within GNOME, by clicking on the 'power' icon (in the top right of the screen), clicking on the 'power' button in the dropdown menu that then appears, and then clicking on the 'Restart' button in the dialog).

The machine should then power cycle (you will be cleanly logged out of GNOME first). When it restarts, as before, you will need to enter your LUKS fallback passphrase (the one you created earlier), directly at the target machine keyboard to unlock the LUKS partition. You should then be able to log into GNOME as usual.

<span id="tweaking_gnome">Tweaking GNOME
One of the saving graces of the GNOME 3 shell interface (the desktop GUI) is its extensibility. By using JavaScript-based plug-ins known as shell extensions, you can modify the behaviour of your system considerably (changing the way window placement works, adding things like weather and system performance applets, changing app search options etc.).

The simplest way to get plugins is via the application. From within your GNOME desktop, press, then type and press. The tool that appears allows you to change many of the default GNOME behaviours that you may find annoying (such as attached modal dialogs!), add startup applications, etc., so its well worth browsing through the options.

To install extensions, however, click on the 'Extensions' tab on the left side of the app, and then navigate to the extension you want on the right (simply move the slider to "ON" for any you wish to enable). If you scroll to the bottom of this list, you'll see a link entitled "". Click on this, and a web page will open with a list of downloadable plug-ins. You can search the list for topics of interest. Again, if you want to use a plug-in, simply click on it to open its detail page, move its slider to "ON", and it should download and start running automatically:



<span id="misc_gnome">Miscellaneous GNOME Points
The following are a few GNOME setup questions that come up frequently by email (but which don't really fit into the main flow of this guide). For any other GNOME issues, your first point of call should be the gnome.org website (and failing that, the Gentoo Desktop Environments discussion forum).

<span id="use_printer_in_gnome">Using a Printer in GNOME
Depending on what version of GNOME you have, and which other applications you have installed, you may find that you are initially unable to print from GNOME, and cannot use the 'Printers' control panel.

To enable printing, you need to install the package, and then start the  service in.

To set this up, first open a root terminal in GNOME (if you don't already have one available): press the, and type 'terminal', then press. A standard-issue terminal window should open. Become root:

The password required here is the one you set up earlier in the tutorial (and have used when -ing in).

Then issue:

Next, enter:

after which you should be able to go to the 'Printers' control panel, click on the 'plus' icon, and setup your printer. You can also close out the terminal if you have no further need for it.

<span id="use_vpn_in_gnome">Using a VPN in GNOME
To be able to use a Virtual Private Network (VPN) with in GNOME, you have to install the package.

To do this, open a terminal (per the instructions above), and then issue:

Once this completes, you should now be able to go to the 'Network' control panel, click on the 'plus' icon, and add a new VPN connection. (As before, close out the terminal now, if you have no further need for it.)

<span id="play_mp4_in_gnome">Playing MP4 Videos (using ) in GNOME
If you find that you are unable to play MP4 videos using GNOME's default media player (and it complains about a missing H264 codec), then you'll need to install the  package.

To do this, open a terminal (per the instructions above), and then issue:

Once this completes, the problem should be fixed. (As before, close out the terminal now, if you have no further need for it.)

<span id="install_firewall_etc">Installing Other Applications, Including a Firewall etc.
As currently configured, your machine is not running a firewall - but I'd definitely recommend installing one! Configuring a firewall is beyond the scope of this tutorial, but a good place to start is Chapter 1 of Michael Rash's book Linux Firewalls. The ArchLinux wiki also has some useful information on using Iptables (the Linux kernel firewall based on ) under.

Other than that, what you install on your machine is now up to you! It's worth reading this introduction in the Gentoo handbook regarding searching for and installing software. The basic process, of course, is straightforward. Suppose, for example, that you'd like to install the Firefox web browser...

To do this, first, open a root terminal in GNOME (if you don't already have one available): press the, and type 'terminal', then press. A standard-issue terminal window should open. Become root:

The password required here is the one you set up earlier in the tutorial (and have used when -ing in).

Next, search for the application. You can use to do this: for example:

Reviewing 's output, you can see that the package you want is. To install it, use the familiar rubric:

If there are any USE flag problems or license issues reported, edit or  accordingly (see text earlier for a description of these), then try again.

<span id="additional_mini_guides">Additional Mini-Guides
Listed below is a short set of 'mini-guides', covering additional set-up topics that may be of interest to some users, but which do not fit within the main flow of the text (currently, there is just one such guide; this will be expanded in the future):
 * Extending LUKS to Protect an Additional Drive

Sayonara ^-^
Well, that's it! You now have a fully operational Gentoo dual-boot system, with and !

Enjoy!

(Click here to go back up to the top-level page.)