09_Final_Preparations_and_Reboot_into_EFI

<!-- Page: Final_Preparations_and_Reboot_into_EFI -->

<span id="final_prep_and_reboot">In this section</span>, we'll be following along with [[Handbook:AMD64/Installation/System|Chapter 8]] of the Gentoo handbook. However, we'll defer some of the configuration tasks mentioned there until the next chapter, when you have rebooted (mainly to help out those users who [[../Building_the_Gentoo_Base_System_Minus_Kernel#choose_systemd_or_openrc|have chosen]] {{c|systemd}} as their target init, since {{c|systemd}} configuration is most easily done from within a system actually running {{c|systemd}}). The steps we'll be undertaking are:
# Setting up the mountpoint tables {{Path|/etc/fstab}} and {{Path|/etc/mtab}};
# Concluding preparations, viz.:
## Emerging some necessary packages (which it will be useful to have in place before a reboot);
## Taking note of networking information;
## Configuring networking for use post-reboot ({{c|OpenRC}} users only)
## Setting up a root password for the new system; then
# Cleanly dismounting the {{c|chroot}}, and restarting;
# Logging in to your new system as the root user, directly at the target machine's keyboard.

Instructions are also provided at [[#if_things_go_wrong|the end of this chapter]] to recover back to a {{c|chroot}} environment, should things not go as planned.

Please note that at the conclusion of this chapter there is a parting of the ways, depending on [[../Building_the_Gentoo_Base_System_Minus_Kernel#choose_systemd_or_openrc|your previous choice]] of init system:
* users targeting {{c|OpenRC}} should continue following the regular guide Chapters 10-14; however
* users targeting {{c|systemd}} should instead follow the 'alternative track' Chapters 10-14.
The division point is [[#next_steps|clearly marked]].

So let's get started!

== <span id="setup_fstab">Setting up the Mountpoint Tables</span> ==

Per the Gentoo handbook, we first need to setup {{Path|/etc/fstab}}, so that the system knows the location, mount point, filesystem type and mount options for the key system partitions. There are three such partitions (which we created [[../Preparing_the_LUKS-LVM_Filesystem_and_Boot_USB_Key#create_lvs|earlier]]):
# the {{Highlight|root}} partition, which holds the system software, configuration files, and the superuser's home directory (device file path {{Path|/dev/mapper/vg1-root}});
# the {{Highlight|swap}} partition, which is used to extend the system's available memory, and can also be used for hibernation (device file path {{Path|/dev/mapper/vg1-swap}}); and
# the {{Highlight|home}} partition, which holds the home directories of normal users (device file path {{Path|/dev/mapper/vg1-home}}).

We need to add entries for each of these to [[fstab]]; so issue:
{{RootCmd
|nano -w /etc/fstab
|prompt=<span style{{=}}"color:gray;">(chroot)</span> livecd <span style{{=}}"color:royalblue;">/ #</span>
}}
and then edit the file, so that the only ''uncommented'' lines (those not starting with a {{c|#}} symbol), are as follows:
{{FileBox|filename=/etc/fstab|title=Set the following as the only uncommented lines|1=
/dev/mapper/vg1-root    /           ext4    defaults,noatime,errors=remount-ro,discard   0 1
/dev/mapper/vg1-swap    none        swap    defaults,noatime,discard    0 0
/dev/mapper/vg1-home    /home       ext4    defaults,noatime,discard    0 2
}}
If you have a cd- or dvd-rom drive on your machine (the Panasonic CF-AX3 does not), you can also add the following additional line:
{{FileBox|filename=/etc/fstab|title=Add the following additional line, if you have a cd-rom or dvd-rom drive|1=
/dev/cdrom/             /mnt/cdrom  auto    noauto,user,ro 0 0
}}
Save and exit {{c|nano}}.

In the {{Path|/etc/fstab}} file:<ref>[http://man7.org/linux/man-pages/man5/fstab.5.html {{c|fstab}} (7) manpage]</ref>
* The first field describes the path to the partition's device file (NB - when this file is referenced, the [[initramfs]]-based {{c|init}} script will already have unlocked the LUKS partition and activated the LVM logical volumes, so we can safely use the device-mapper paths, as above).
* 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 {{c|auto}} 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 {{c|dump}} command to denote which filesystems require dumping. It's generally fine to leave this as <code>0</code> (do not dump) in all cases.
* The sixth field is used by {{c|fsck}} to determine the order filesystems are integrity checked at boot time. A <code>0</code> indicates no check. The root filesystem should have (as here) a <code>1</code> to force it to be checked first, and then all other persistent filesystems can have <code>2</code> specified (so they are checked together, but after the root filesystem).

{{Note|We ''don't'' need to mount {{Path|/boot}} here, since this is a UEFI system and our {{Path|/boot}} is simply a regular directory, used as a marshalling ground. Nor do we specify our {{Path|/boot/efi}} mountpoint, since that will be dealt with explicitly by {{c|buildkernel}} (and the UEFI boot sequence), and we'll generally want to be able to remove the USB key once the machine has booted anyway (for security).}}
{{Note|There is no need to place entries for {{Path|/proc}} and {{Path|/dev}} into {{Path|/etc/fstab}}; these will be mounted automatically.}}

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

{| class="wikitable"
|-
! Partition !! Mount Option !! Description
|-
| rowspan=4|{{Highlight|root}} || {{c|defaults}} || Specifies the baseline options: 
* {{c|rw}} (mount the filesystem read/write);
* {{c|suid}} (allow set-user-identifier / set-group-identifier [[:Wikipedia:Setuid|bits]] to take effect);
* {{c|dev}} (interpret character or block special [[:Wikipedia:Device_file|device files]] on the filesystem);
* {{c|exec}} (permit execution of binaries); 
* {{c|auto}} (automatically mount at boot);
* {{c|nouser}} (forbid non-root users to explicitly mount) and 
* {{c|async}} (perform I/O to the filesystem asynchronously).
|-
| {{c|noatime}} || This prevents file access times from being recorded; these are not generally needed, and this setting is particularly important for performance if you use a solid-state drive (SSD).<ref>Arch Linux Wiki: [https://wiki.archlinux.org/index.php/Solid_State_Drives#noatime_Mount_Flag "Solid State Drives: noatime Mount Flag"]</ref> Incidentially, {{c|noatime}} is a superset of {{c|nodiratime}}.<ref>LWN.net: [http://lwn.net/Articles/245002/ "Does noatime imply nodiratime?"]</ref>
|-
| {{c|errors{{=}}remount-ro}} || This causes the root system to be remounted read-only if errors are encountered, for safety.
|-
| {{c|discard}} || This allows the TRIM command to work, ''provided that'' you have also allowed this in LUKS via the {{c|root_trim{{=}}yes}} kernel command-line flag (actually passed through to the {{c|init}} script) in {{Path|/etc/buildkernel.conf}}, as described [[../Configuring_and_Building_the_Kernel#enable_trim|earlier]]. TRIM will improve performance on SSDs as they get full,<ref>Arch Linux Wiki: [https://wiki.archlinux.org/index.php/Solid_State_Drives#TRIM "Solid State Drives: TRIM"]</ref> but make sure you are comfortable with the possible security implications of turning it on.
|-
| rowspan=3|{{Highlight|swap}} || {{c|defaults}} || Sets baseline options as per the root partition, above. Note that you do ''not'' need {{c|sw}} or {{c|swap}} here, although they are commonly seen.<ref>SuperUser Forum: [http://superuser.com/questions/337410/what-is-the-difference-between-swap-entries-in-fstab "What is the difference between swap entries in fstab?"]</ref>
|-
| {{c|noatime}} || ''See above.''
|-
| {{c|discard}} || ''See above.''
|-
| rowspan=3|{{Highlight|home}} || {{c|defaults}} || Sets baseline options as per the root logical volume, above.
|-
| {{c|noatime}} || ''See above.''
|-
| {{c|discard}} || ''See above.''
|-
| rowspan=3|{{Highlight|cd-rom}} (optional)|| {{c|noauto}} || Do not attempt to mount automatically at boot.
|-
| {{c|user}} || Allow a non-root user to explicitly mount (desirable for removable media). Note that this implies:
* {{c|noexec}} (prevent execution of binaries on this filesystem);
* {{c|nosuid}} (prevent set-user-identifier / set-group-identifier [[:Wikipedia:Setuid|bits]] from taking effect) and 
* {{c|nodev}} (do ''not'' interpret character or block special [[:Wikipedia:Device_file|device files]] on the filesystem).
If any of that bothers you, be sure to override with a subsequent option.
|-
| {{c|ro}} || Mount the filesystem read-only.
|}

<span id="symlink_etc_mtab">Per the Gentoo [[Systemd#/etc/mtab|wiki article on {{c|systemd}}]]</span>, the mounted file systems table ({{Path|/etc/mtab}}) must be a symlink to {{Path|/proc/self/mounts}} (this is now also required for {{c|OpenRC}}<ref>Gentoo Linux GitWeb: [https://gitweb.gentoo.org/proj/openrc.git/commit/?id=a6391f44ee6c68d674ae8425983467b971710d5d "mtab: move toward requiring /etc/mtab to be a symbolic link" (commit 	a6391f44ee6c68d6)]</ref>), so issue:
{{RootCmd
|ln -vsf /proc/self/mounts /etc/mtab
|prompt=<span style{{=}}"color:gray;">(chroot)</span> livecd <span style{{=}}"color:royalblue;">/ #</span>
}}

{{Important|Please ensure you carry out the above step! Your system will not function correctly if you omit it.}}

== <span id="concluding_prep">Some Concluding Preparations</span> ==

It <span id="emerge_additionals">will</span> be useful to have the [[:Wikipedia:DHCPD|DHCP daemon]], [[:Wikipedia:Wpa_supplicant|{{c|wpa_supplicant}}]] and [[:Wikipedia:GNU_Screen|{{c|screen}}]] software available immediately upon reboot. They're not yet installed on the {{c|chroot}} operating system, only on the 'outer' host, so let's emerge them now. Issue:

{{RootCmd
|emerge --ask --verbose net-misc/dhcpcd net-wireless/wpa_supplicant app-misc/screen
|prompt=<span style{{=}}"color:gray;">(chroot)</span> livecd <span style{{=}}"color:royalblue;">/ #</span>
|output=<pre>
... additional output suppressed ...
Would you like to merge these packages? [Yes/No] <press y, then press Enter>
... additional output suppressed ...
</pre>
}}

Next, <span id="note_if_name">take note</span> of your current network interface name - this will be the same after a reboot, and knowing it will be useful during {{c|systemd}}/{{c|OpenRC}} configuration. Issue:
{{RootCmd
|ifconfig
|prompt=<span style{{=}}"color:gray;">(chroot)</span> livecd <span style{{=}}"color:royalblue;">/ #</span>
}}

and look for a record name similar in format to {{c|enp0s25}} (your system will most likely have a different name - in this particular case it refers to a '''e'''ther'''n'''et card on PCI ('''p''') bus '''0''', '''s'''lot '''25''').<ref name="predictable_names">freedesktop.org: [http://www.freedesktop.org/wiki/Software/systemd/PredictableNetworkInterfaceNames Predictable Network Interface Names]</ref> 

{{Note|If you are using a wireless adapter for the install, your identifier string will start with {{c|wl}}, not {{c|en}}. You will have made a note of the relevant name [[../Setting_Up_Networking_and_Connecting_via_ssh#note_wifi_if_name{{!}}earlier]].}} 

Next, we must <span id="setup_new_root_password">set up a root password</span>. Yes, we did indeed set up a root password [[../Creating_and_Booting_the_Minimal-Install_Image_on_USB#first_root_pw_setup|earlier]], but that was for the ''host'' operating system on the target machine, and we are about to discard that and boot directly into the ''new'' (currently {{c|chroot}}-ed) one. As such, we need to set a fresh root password within the {{c|chroot}}. Issue:
{{RootCmd
|passwd root
|prompt=<span style{{=}}"color:gray;">(chroot)</span> livecd <span style{{=}}"color:royalblue;">/ #</span>
|output=<pre>
New password: <enter your new password>
Retype new password: <enter your new password again>
passwd: password updated successfully
</pre>
}}

{{Important|Be sure to write this password down somewhere safe! You will require it to log in shortly.}}

Similarly, we need to ensure that the {{c|sshd}} setup inside the {{c|chroot}} will allow {{c|root}} to log-in (while we complete our set-up, at any rate). Issue:
{{RootCmd
|sed -i 's/^#PermitRootLogin.*$/PermitRootLogin yes/' /etc/ssh/sshd_config
|prompt=<span style{{=}}"color:gray;">(chroot)</span> livecd <span style{{=}}"color:royalblue;">/ #</span>
}}
{{Note|As you may recall (from when we edited the outer host's {{Path|/etc/ssh/sshd_config}} file [[../Setting_Up_Networking_and_Connecting_via_ssh#setup_ssh_server{{!}}earlier]]), from release 7.0 of {{c|OpenSSH}}, the defaults have changed to prohibit password-based login as {{c|root}}, hence the reason for the above edit.<ref name{{=}}"openssh_7_release_notes">OpenSSH Unix Announce: [http://lists.mindrot.org/pipermail/openssh-unix-announce/2015-August/000122.html OpenSSH 7.0 released]</ref>}}

We also need to make sure that the {{Package|app-editors/nano}} editor does not accidentally get removed later in the installation (as it is only 'held in place' by a virtual &mdash; {{Package|virtual/editor}} &mdash; at the moment). Issue:
{{RootCmd
|emerge --noreplace app-editors/nano
|prompt=<span style{{=}}"color:gray;">(chroot)</span> livecd <span style{{=}}"color:royalblue;">/ #</span>
}}
{{Note|The <code>--noreplace</code> option ensures that the package is not rebuilt if already installed. In any case, it will be added to the @world set ({{Path|/var/lib/portage/world}}). It's a useful idiom to be aware of.}}

=== <span id="setup_networking_openrc">Configure Networking for Post-Reboot Use (OpenRC Users Only)</span> ===

{{Note|If you selected {{c|systemd}} [[../Building_the_Gentoo_Base_System_Minus_Kernel#choose_systemd_or_openrc{{!}}earlier]] as your target init system (the default now being {{c|OpenRC}} in this guide), you should [[#exit_chroot_and_restart{{!}}click here]] to skip this section: the instructions contained herein are {{c|OpenRC}}-specific.}}

To <span id="setup_dhcpcd_openrc">make sure you have your network interface available</span> after restart, be sure to add {{Package|net-misc/dhcpcd}} to the default runlevel. Issue:

{{RootCmd
|rc-update add dhcpcd default
|prompt=<span style{{=}}"color:gray;">(chroot)</span> livecd <span style{{=}}"color:royalblue;">/ #</span>
}}

{{Note|We will disable this service later, when {{Package|net-misc/networkmanager}} takes over (with GNOME). However, we leave it enabled-on-boot for now for convenience.}}

You should also <span id="setup_sshd_openrc">ensure that the {{c|sshd}} service</span> will automatically start on boot, so you can log in remotely; issue:
{{RootCmd
|rc-update add sshd default
|prompt=<span style{{=}}"color:gray;">(chroot)</span> livecd <span style{{=}}"color:royalblue;">/ #</span>
}}
{{Warning|As currently configured, {{c|sshd}} allows some rather insecure things, such as remote log-in as root. While this is useful at the moment (and relatively benign given the machine is on a subnet, presumably behind a firewall), do consider editing the {{Path|/etc/ssh/sshd_config}} file once all configuration is complete, to disallow this. You should also consider [http://www.thegeekstuff.com/2008/11/3-steps-to-perform-ssh-login-without-password-using-ssh-keygen-ssh-copy-id/ moving to public key authentication] for {{c|ssh}} login, once everything else is in place (at the end of the install).}} 

Next, <span id="start_wpa_supplicant">if you are performing</span> this install over '''WiFi''', we need to ensure that {{c|wpa_supplicant}} can be started by {{c|dhcpcd}}<ref>ArchLinux Wiki: [https://wiki.archlinux.org/index.php/Dhcpcd#10-wpa_supplicant "dhcpcd: Hooks: 10-wpa_supplicant"]</ref> (NB: if using '''wired Ethernet''' for the install, you should [[#networking_all_done|'''skip''']] these commands). Issue:
{{RootCmd
|mv -v /etc/wpa.conf /etc/wpa_supplicant/wpa_supplicant.conf
|prompt=localhost <span style{{=}}"color:royalblue;">~ #</span>
}}
{{Note|The {{Path|/etc/wpa.conf}} file was created [[../Building_the_Gentoo_Base_System_Minus_Kernel#copy_wpa_conf{{!}}earlier]].}}
Now, we also need to prepend one line to that configuration file, so that {{c|dhcpcd}} can invoke {{c|wpa_supplicant}} directly. Issue:
{{RootCmd
|nano -w /etc/wpa_supplicant/wpa_supplicant.conf
|prompt=<span style{{=}}"color:gray;">(chroot)</span> livecd <span style{{=}}"color:royalblue;">/ #</span>
}}
and ''prepend'' the following line to the file:
{{FileBox|filename=/etc/wpa_supplicant/wpa_supplicant.conf|title=Prepend the following line, to allow dhcpcd invocation|1=
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=wheel
}}
Leave the rest of the file as-is. Save, and exit {{c|nano}}.

Also, as of version 6.10.0 of {{Package|net-misc/dhcpcd}}, you need to ensure that the appropriate 'hook' script is in place to start and stop {{Package|net-wireless/wpa_supplicant}} on each wireless interface.<ref>Gentoo News: [https://www.gentoo.org/support/news-items/2016-01-08-some-dhcpcd-hooks-are-now-examples.html "Some dhcpcd hooks are now examples"]</ref> So, to ensure that you have this file in place, issue:
{{RootCmd
|if ! [ -s /lib/dhcpcd/dhcpcd-hooks/10-wpa_supplicant ]; then cp -vf /usr/share/dhcpcd/hooks/10-wpa_supplicant /lib/dhcpcd/dhcpcd-hooks/; fi
|prompt=<span style{{=}}"color:gray;">(chroot)</span> livecd <span style{{=}}"color:royalblue;">/ #</span>
}}

{{Note|This is a deliberately minimal setup, as we'll only use it until {{Package|net-misc/networkmanager}} takes over (with GNOME); for more information on the {{c|ctrl_interface}} option, and others you may wish to set, see [https://wiki.archlinux.org/index.php/WPA_supplicant#Advanced_usage these notes].}}

<span id="networking_all_done">Assuming you want</span> to use [[:Wikipedia:Dynamic_Host_Configuration_Protocol|DHCP]] on your interface (wired or wireless), that's all you need to do: ''pace'' the [[Handbook:AMD64/Installation/System#Configuring_the_network{{!}}Gentoo Handbook]], there's no need to add {{Path|/etc/init.d/net.<ifname>}} symbolic links, edit {{Path|/etc/conf.d/net}} etc.<ref>Gentoo Wiki: [[Network_management_using_DHCPCD#Migration_from_Gentoo_net..2A_scripts|"Network management using DHCPCD": Migration from Gentoo net.* scripts]]</ref>

However, if you have more complex networking requirements (static IP, proxies etc.) ''should'' consult the relevant section of the [[Handbook:AMD64/Installation/System#Configuring_the_network|Handbook]]. Also, if you have more complex WiFi configuration requirements, you may also find [[Handbook:AMD64/Networking/Wireless|these notes]] useful.

== <span id="exit_chroot_and_restart">Cleanly Dismounting the {{c|chroot}} and Restarting</span> ==

Almost there! Now we have to exit the {{c|chroot}} in both our {{c|screen}} virtual consoles, quit both of those consoles (thereby exiting {{c|screen}}), unmount the various logical volumes, deactivate the LVM volume group, and close out the LUKS partition. Issue:

{{RootCmd
|exit
|prompt=<span style{{=}}"color:gray;">(chroot)</span> livecd <span style{{=}}"color:royalblue;">/ #</span>
}}
then:
{{RootCmd
|exit
|prompt=livecd <span style{{=}}"color:royalblue;">~ #</span>
}}
The first {{c|exit}} exits the {{c|chroot}} in the first {{c|screen}} virtual console, the second exits that console itself. Now do the same for the second virtual console (which you'll automatically be dropped out to):
{{RootCmd
|exit
|prompt=<span style{{=}}"color:gray;">(chroot:2)</span> livecd <span style{{=}}"color:royalblue;">/ #</span>
}}
then:
{{RootCmd
|exit
|prompt=livecd <span style{{=}}"color:royalblue;">~ #</span>
|output=<pre>
[screen is terminating]
</pre>
}}

Unmount everything (and turn off swap), deactivate LVM, and close LUKS:
{{RootCmd
|sync
|swapoff -v /dev/mapper/vg1-swap
|umount -lv /mnt/gentoo/home
|umount -lv /mnt/gentoo/dev{/shm,/pts,}
|umount -Rv /mnt/gentoo
|vgchange --available n
|cryptsetup luksClose gentoo
|prompt=livecd <span style{{=}}"color:royalblue;">~ #</span>
}}

{{Note|In the unlikely event you are unable to execute the <code>vgchange --available n</code> command, perhaps due to some components reported as being still mounted from within the LVM logical volume, simply proceed with the following {{c|reboot}} anyway. Your system should still be in a consistent state due to the {{c|sync}} command. For avoidance of doubt, this point will ''not'' affect most users, who should find their system dismounts cleanly.}}

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:
{{RootCmd
|reboot
|prompt=livecd <span style{{=}}"color:royalblue;">~ #</span>
}}

{{Note|If you have been using your system in ''legacy'' (non-UEFI) boot mode up to this point &mdash; and, for avoidance of doubt, this '''won't''' apply to the majority of users, who should therfore simply ignore this note &mdash; then you will need to ''remove'' the boot USB key after rebooting; then, as your system starts to come back up, enter into your system's BIOS, enable UEFI mode (''without'' secure boot enabled) and restart once more.}}

Your {{c|ssh}} session will exit. If all is well, shortly after this your target machine will restart, and, because {{c|buildkernel}} [[../Configuring_and_Building_the_Kernel#add_to_boot_list|automatically placed]]
your new, EFI-stub kernel at the top of the boot list, it should then proceed &mdash; without any further intervention required &mdash; to boot this kernel off of the boot USB key.

== <span id="login_directly_to_new_system">Logging in Directly to the New System</span> ==

After some initialization, you should then be prompted for a passphrase to unlock the {{c|gpg}} keyfile for your LUKS partition (this is the passphrase you set up [[../Preparing_the_LUKS-LVM_Filesystem_and_Boot_USB_Key#create_gpg_luks_keyfile|earlier]]). Type this in (directly at the target machine keyboard), and press {{Key|Enter}}.

Shortly after this, assuming that your passphrase is correct, you'll be presented with a login prompt. Enter 'root' as the user (again, directly at the keyboard, without quotes), press {{Key|Enter}}, and then type the root password you set up [[#setup_new_root_password|above]], and press {{Key|Enter}} again.

{{Note|On certain versions of {{c|systemd}}, you may be notified that the {{c|plymouth-start.service}} unit failed during boot. As we have not yet enabled {{c|plymouth}} using {{c|buildkernel}}, this is to be expected, and the error may be ignored at this point.<br>For avoidance of doubt, this (minor) issue does not impact {{c|OpenRC}} users.}}

With luck, you should now be logged in! If this is the case, congratulations, you have a encrypted system which boots from UEFI and uses (depending on your choice [[../Building_the_Gentoo_Base_System_Minus_Kernel#choose_systemd_or_openrc|earlier]]) {{c|OpenRC}} or {{c|systemd}}. You should now '''remove the minimal install USB key''', so that only the boot USB key (the smaller capacity one) remains inserted, then [[#next_steps|click here]] to complete the configuration of your init system (and other) settings.

{{Note|If you ''were'' able to successfully boot, then please note that the minimal install image USB key is no longer required for the remaining steps in this tutorial &mdash; as such, you may, at your option, either keep it around for 'fallback recovery' purposes (in case anything should go wrong later &mdash; the process for command-line recovery is detailed [[#if_things_go_wrong|below]]), or, reformat it for other use.}}

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</span> ==

{{Note|If you managed to reboot your new system and log in successfully, then you should [[#next_steps{{!}}skip this step]], it is only necessary for those attempting to recover back to a {{c|chroot}} system after a failed boot.}}

The following are short-form instructions to get you back into a {{c|chroot}} environment again, so that you can attempt to fix whatever problem prevented you from booting under UEFI. I have included backlinks throughout, so you can hop up to where these steps were first taken, and read in more detail about what is involved - the style of what follows is rather telegraphic.

First, re-insert your minimal install USB key into the target machine (leaving the boot USB key inserted as well, since we'll need it to unlock the LUKS partition), and restart the system. As the machine comes up, re-enter the BIOS, and set (if it is not already) the (minimal install) USB key to be the top UEFI boot device (original instructions [[../Creating_and_Booting_the_Minimal-Install_Image_on_USB#set_mii_boot|here]]). Save the BIOS settings and exit, thereby rebooting into the Gentoo minimal install system (original instructions [[../Creating_and_Booting_the_Minimal-Install_Image_on_USB#boot_beep|here]]). As before, hit {{Key|Enter}} at the GRUB screen, remember to select the correct keymap etc. Then, since the boot image itself has no persistence, issue (directly on the target machine's keyboard):
{{RootCmd
|passwd root
|prompt=livecd <span style{{=}}"color:royalblue;">~ #</span>
|output=<pre>
New password: <enter your (host system) root password>
Retype new password: <enter your (host system) root password again>
passwd: password updated successfully
</pre>
}}
Remember (original instructions [[../Creating_and_Booting_the_Minimal-Install_Image_on_USB#first_root_pw_setup|here]]), you are setting up a password for the 'outer', host system here &mdash; root's password ''inside'' the {{c|chroot}} will be retained (and different), but we haven't remounted the {{c|chroot}} 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 {{c|ifconfig}} (original instructions [[../Setting_Up_Networking_and_Connecting_via_ssh#get_ip_address|here]]):
{{RootCmd
|ifconfig
|prompt=livecd <span style{{=}}"color:royalblue;">~ #</span>
}}
Then [[#restart_sshd|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 [[../Setting_Up_Networking_and_Connecting_via_ssh#connecting_via_wifi|here]]). Issue:
{{RootCmd
|wpa_passphrase "ESSID" > /etc/wpa.conf
|prompt=livecd <span style{{=}}"color:royalblue;">~ #</span>
|output=
<pre>
<then type your WiFi access point passphrase (without quotes) and press Enter>
</pre>
}}
{{Note|As before, substitute the correct name for <code>"ESSID"</code> in the above.}}
Lock down the file's access permissions (to root only) and check that its contents look sane. Issue:
{{RootCmd
|chmod -v 600 /etc/wpa.conf
|cat /etc/wpa.conf
|prompt=livecd <span style{{=}}"color:royalblue;">~ #</span>
}}
Assuming that looks OK, we can connect. Issue:
{{RootCmd
|wpa_supplicant -Dnl80211,wext -iwlp2s0 -c/etc/wpa.conf -B
|prompt=livecd <span style{{=}}"color:royalblue;">~ #</span>
}}
{{Note|Substitute the wireless network interface name you wrote down [[../Setting_Up_Networking_and_Connecting_via_ssh#note_wifi_if_name{{!}}previously]] for <code>wlp2s0</code> in the above command.}}
Then note your IP address:
{{RootCmd
|ifconfig wlp2s0
|prompt=livecd <span style{{=}}"color:royalblue;">~ #</span>
}}
{{Note|Again, substitute the wireless network interface name you wrote down [[../Setting_Up_Networking_and_Connecting_via_ssh#note_wifi_if_name{{!}}previously]] for <code>wlp2s0</code> in the above command.}}

{{Note|As before, if you need to use a fixed IP address, a proxy, IPv6, or an unencrypted WiFi connecction, please see [[Handbook:AMD64/Installation/Networking|Chapter 3]] of the Gentoo handbook for more details.
}}
<span id="restart_sshd">Now start {{c|sshd}}</span> (original instructions [[../Setting_Up_Networking_and_Connecting_via_ssh#setup_ssh_server|here]]):
{{RootCmd
|sed -i 's/^#PermitRootLogin.*$/PermitRootLogin yes/' /etc/ssh/sshd_config
|/etc/init.d/sshd start
|prompt=livecd <span style{{=}}"color:royalblue;">~ #</span>
}}

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:
{{RootCmd
|ssh-keygen -l -f /etc/ssh/ssh_host_rsa_key.pub
|ssh-keygen -l -f /etc/ssh/ssh_host_ed25519_key.pub
|prompt=livecd <span style{{=}}"color:royalblue;">~ #</span>
}}
Now switch to your helper PC. Note that, if the target PC's IP address is the same as it was originally (quite likely, even with [[:Wikipedia:Dynamic_Host_Configuration_Protocol|DHCP]]), then the helper will already have a note of its previous fingerprint, and will refuse to connect via {{c|ssh}} (since a mismatched fingerprint might suggest a [[:Wikipedia:Man-in-the-middle_attack|man-in-the-middle attack]]). Therefore, we need to remove the old fingerprint record for the IP from {{Path|~/.ssh/known_hosts}}. Issue:
{{Cmd
|sed -i '/^[^[:digit:]]*192.168.1.106[^[:digit:]]/d' ~/.ssh/known_hosts
|prompt=user@pc2 $}}
{{Note|Substitute whatever IP address you got back from {{c|ifconfig}} for <code>192.168.1.106</code> in the above command.}}

and issue (original instructions [[../Setting_Up_Networking_and_Connecting_via_ssh#log_in_via_helper|here]]):
{{Cmd
|ssh root@192.168.1.106
|prompt=user@pc2 $}}
Check the key fingerprint and then, if it matches, continue as below:
{{GenericCmd|<pre>
... additional output suppressed ...
Are you sure you want to continue connecting (yes/no)? <type 'yes', then Enter>
... additional output suppressed ...
Password: <enter root password you just set>
... additional output suppressed ...
</pre>
}}
{{Note|Substitute whatever IP address you got back from {{c|ifconfig}} for <code>192.168.1.106</code> in the above command.}}
Once you are connected, we need to get {{c|screen}} running. Via the {{c|ssh}} connection on the helper PC (which is how you should enter all subsequent commands, unless otherwise specified), issue (original instructions [[../Setting_Up_Networking_and_Connecting_via_ssh#start_screen|here]]):
{{RootCmd
|screen
|prompt=livecd <span style{{=}}"color:royalblue;">~ #</span>
}}

Next, we must mount the USB boot key's EFI system partition, so that we can use the keyfile on it to unlock the LUKS partition. Find out the device file name for the EFI partition on the USB boot key, by issuing (original instructions [[../Preparing_the_LUKS-LVM_Filesystem_and_Boot_USB_Key#determine_efi_dev|here]]):
{{RootCmd
|lsblk
|prompt=livecd <span style{{=}}"color:royalblue;">~ #</span>
}}
We will refer to this as {{Path|/dev/sdY1}} in what follows, but of course on your machine it will be something like {{Path|/dev/sdb1}} or {{Path|/dev/sdc1}} (note that the initial {{Path|/dev/}} prefix is not shown in the {{c|lsblk}} output).

Next, create a temporary mountpoint, and mount it. Issue (original instructions [[../Preparing_the_LUKS-LVM_Filesystem_and_Boot_USB_Key#temp_mount_efi|here]]):
{{RootCmd
|mkdir -v /tmp/efiboot
|mount -v -t vfat /dev/sdY1 /tmp/efiboot
|prompt=livecd <span style{{=}}"color:royalblue;">~ #</span>
}}
{{Note|Replace {{Path|/dev/sdY1}} in the above command with the path of first partition on the USB key, which you just located with {{c|lsblk}}, such as {{Path|/dev/sdb1}} or {{Path|/dev/sdc1}}.}}

Now, we can open the [[:Wikipedia:Linux_Unified_Key_Setup|LUKS]] volume. You'll need the passphrase (for the {{c|gpg}} keyfile) you [[../Preparing_the_LUKS-LVM_Filesystem_and_Boot_USB_Key#create_gpg_luks_keyfile|set up earlier]] to do this:
{{RootCmd
|export GPG_TTY{{=}}$(tty)
|gpg --decrypt /tmp/efiboot/luks-key.gpg {{!}} cryptsetup --key-file - luksOpen /dev/sdZn gentoo
|prompt=livecd <span style{{=}}"color:royalblue;">~ #</span>
|output=<pre>
Enter passphrase
<type the passphrase for the gpg keyfile you setup earlier>
... additional output suppressed ...
</pre>
}}
{{Note|Replace {{Path|/dev/sdZn}} in the above command with the device path for the LUKS partition, e.g., {{Path|/dev/sda7}}. You can check this with {{c|lsblk}} (original instructions [[../Preparing_the_LUKS-LVM_Filesystem_and_Boot_USB_Key#find_luks_partition|here]]).<br>Also, you ''may'' see some errors of the form <code>device-mapper: remove ioctl on XXX failed: Device or resource busy</code>; these can generally be ignored.}}
{{Note|You may get complaints about <code>no LC_CTYPE known</code> printed by {{c|pinentry}}; these can generally be ignored. See explanation in the [[../Preparing_the_LUKS-LVM_Filesystem_and_Boot_USB_Key#lc_ctype_problem|original text]].}}
{{Tip|Remember that if {{c|gpg}} gets stuck with a bad password in its cache for some reason, you can reset it by issuing:
{{RootCmd
|echo RELOADAGENT {{!}} gpg-connect-agent
|prompt=livecd <span style{{=}}"color:royalblue;">~ #</span>
}}}}

Now we can bring up the [[:Wikipedia:Logical_Volume_Manager_(Linux)|LVM]] logical volumes, and mount them. Issue (original instructions [[../Preparing_the_LUKS-LVM_Filesystem_and_Boot_USB_Key#activate_lvm|here]]):
{{RootCmd
|vgchange --available y
|swapon -v /dev/mapper/vg1-swap
|mount -v -t ext4 /dev/mapper/vg1-root /mnt/gentoo
|mount -v -t ext4 /dev/mapper/vg1-home /mnt/gentoo/home
|prompt=livecd <span style{{=}}"color:royalblue;">~ #</span>
}}

Next, unmount the USB boot key; issue (original instructions [[../Preparing_the_LUKS-LVM_Filesystem_and_Boot_USB_Key#unmount_efi|here]]):
{{RootCmd
|umount -v /tmp/efiboot
|prompt=livecd <span style{{=}}"color:royalblue;">~ #</span>
}}

Ensure the date and time is set correctly. Issue:
{{RootCmd
|date
|prompt=livecd <span style{{=}}"color:royalblue;">~ #</span>
}}

If necessary fix it by issuing (original instructions [[../Creating_and_Booting_the_Minimal-Install_Image_on_USB#set_date_time|here]]):
{{RootCmd
|date MMDDhhmmYYYY
|prompt=livecd <span style{{=}}"color:royalblue;">~ #</span>
}}
{{Note|Substitute <code>MMDDhhmmYYYY</code> in the above with the correct date/time string. For example, to set the UTC date/time to 5:12pm on February 9th 2017, you would issue
{{RootCmd
|date 020917122017
|prompt=livecd <span style{{=}}"color:royalblue;">~ #</span>
}}
}}
Next, make sure that the [[:Wikipedia:Domain_Name_System|DNS]] information will still be valid after we {{c|chroot}}. Issue (original instructions [[../Building_the_Gentoo_Base_System_Minus_Kernel#copy_dns_info|here]]):
{{RootCmd
|cp -L /etc/resolv.conf /mnt/gentoo/etc/
|prompt=livecd <span style{{=}}"color:royalblue;">~ #</span>
|output=<pre>
cp: overwrite '/mnt/gentoo/etc/resolv.conf'? <type 'yes', then Enter>
</pre>
}}

Now, ensure that the various special files in {{Path|/proc}}, {{Path|/sys}} and {{Path|/dev}} are available after a {{c|chroot}}. Issue (original instructions [[../Building_the_Gentoo_Base_System_Minus_Kernel#setup_bind_mounts|here]]):
{{RootCmd
|mount -v -t proc none /mnt/gentoo/proc
|mount -v --rbind /sys /mnt/gentoo/sys
|mount -v --rbind /dev /mnt/gentoo/dev
|mount -v --make-rslave /mnt/gentoo/sys
|mount -v --make-rslave /mnt/gentoo/dev 
|prompt=livecd <span style{{=}}"color:royalblue;">~ #</span>
}}

Now we can actually enter the {{c|chroot}}. Issue (original instructions [[../Building_the_Gentoo_Base_System_Minus_Kernel#enter_chroot|here]]):
{{RootCmd
|chroot /mnt/gentoo /bin/bash
|prompt=livecd <span style{{=}}"color:royalblue;">~ #</span>
}}
Remember to source our profile correctly and set a prompt hint. Issue (original instructions [[../Building_the_Gentoo_Base_System_Minus_Kernel#chroot_prompt|here]]):
{{RootCmd
|source /etc/profile
|export PS1{{=}}"(chroot) $PS1"
|prompt=livecd <span style{{=}}"color:royalblue;">/ #</span>
}}
Finally, we can setup a second virtual console inside {{c|screen}} (just as we did [[../Building_the_Gentoo_Base_System_Minus_Kernel#second_virtual_console|before]]), which will be useful to e.g., monitor the status of long {{c|emerge}}s. Press {{Key|Ctrl}}{{Key|a}} then {{Key|c}} to start a new console. Then in that new console (which is back outside the {{c|chroot}}, to begin with) enter:
{{RootCmd
|chroot /mnt/gentoo /bin/bash
|prompt=livecd <span style{{=}}"color:royalblue;">~ #</span>
}}
followed by
{{RootCmd
|source /etc/profile
|export PS1{{=}}"(chroot:2) $PS1"
|prompt=livecd <span style{{=}}"color:royalblue;">/ #</span>
}}

Now hit {{Key|Ctrl}}{{Key|a}} then {{Key|p}} to get back to the original console.

That's it! You can now proceed to edit your {{c|chroot}}-ed system (and hopefully, to fix it). It is impossible to be specific as to what may have caused a problem, but some likely candidates include:
* '''Incorrect kernel configuration.''' In this case, run <code>buildkernel --ask --verbose</code>, enter the graphical kernel configuration editor when prompted, change the appropriate kernel settings, and then save and exit the editor. The build will continue with your modified configuration. (A problem of this sort is most likely to occur if you have ''already'' started to dabble with the configuration, since the standard flow in this tutorial assumes you have used the {{Path|/proc/config.gz}} config from the running minimal install system kernel - which is therefore to some extent 'known good' - as a basis).
** In particular, if you elected to use {{c|OpenRC}} boot [[../Building_the_Gentoo_Base_System_Minus_Kernel#choose_systemd_or_openrc|earlier]] (and not the default {{c|systemd}}), and received an error similar to <code>The filesystem /dev/mapper/vg1-root <...> does not contain a valid init=<...>/systemd</code> after entering your LUKS passphrase, then you have not correctly set up the <var>INITSYSTEM</var> variable in {{Path|/etc/buildkernel.conf}}. Fix this (either by editing {{Path|/etc/buildkernel.conf}} or using <code>buildkernel --easy-setup</code> and choosing option "{{c|7) set init system}}", then run <code>buildkernel --ask --verbose</code> again.
* '''Buggy version of {{c|buildkernel}}.''' Please note that {{c|buildkernel}} version 1.0.24 has a bug that affects booting and should not be used (earlier and later versions are not affected). Issue <code>buildkernel --version</code> to check, and if you ''do'' have the affected 1.0.24 version installed, update it (using <code>emaint sync --repo sakaki-tools && emerge -av --update buildkernel</code>), then rebuild your kernel and reboot.
* '''Missing packages.''' For example, you may have forgotten to install e.g., {{Package|net-misc/dhcpcd}} prior to reboot, preventing you from accessing the network properly. If this is the case, simply {{c|emerge}} the [[#emerge_additionals|required software]] within the chroot, and then try again. There is no need to re-run {{c|buildkernel}} in this case.
* '''Password not set for root.''' If for any reason you forgot to set a root password for the new system (as instructed [[#setup_new_root_password|above]], when you were {{c|chroot}}-ed in originally), then your attempt to log in will have been rejected. This is easily fixed by using <code>passwd root</code>.
* '''Wrong keymapping causing mangled passwords.''' If the system would not accept your {{c|gpg}} keyfile passphrase on reboot, but you were able to successfully unlock it when re-entering the {{c|chroot}} above, or, if the system would not accept your root password after a restart, then you may have not setup the <var>KEYMAP</var> variable in {{Path|/etc/buildkernel.conf}} correctly. See [[../Configuring_and_Building_the_Kernel#important_conf_vars|this earlier discussion]] for further details. (These issues can also generally be ameliorated (for most locales) through the use of only standard English letters in your passphrases, as mentioned [[../Preparing_the_LUKS-LVM_Filesystem_and_Boot_USB_Key#correct_horse_battery_staple|previously]].) Review, and if necessary, change your boot-time keymap by using <code>buildkernel --easy-setup</code>, and then re-run <code>buildkernel --ask --verbose</code>.
* '''Problems with UUIDs.''' The {{c|buildkernel}} script tries to ensure that the UUIDs you have passed it (in {{Path|/etc/genkernel.conf}} [[../Configuring_and_Building_the_Kernel#important_conf_vars|above]]) are valid, but it is still possible to make a mistake (e.g. if you have more than one LUKS partition on your system, for example). Double check these values, and, if necessary, change them (by using <code>buildkernel --easy-setup</code>) and then re-run <code>buildkernel --ask --verbose</code>.
* '''BIOS configuration problems.''' A total failure of your new system to even try to start (or if you get Windows instead!) is likely to indicate some issue with your BIOS settings. Are you sure your USB '''boot''' key is at the top of the UEFI boot order (as it should be, if {{c|buildkernel}} has [[../Configuring_and_Building_the_Kernel#add_to_boot_list|done its job]])? And that secure boot is disabled at this point, and that fast boot is off? Double check these points, then try again &mdash; for hints about entering and modifying the UEFI BIOS settings, please refer to [[../Creating_and_Booting_the_Minimal-Install_Image_on_USB#boot_minimal_install_iso|these earlier notes]]. (You should also double-check that the first (and only) partition on your USB boot key is marked as an EFI system partition and is formatted {{c|fat32}}; see [[../Preparing_the_LUKS-LVM_Filesystem_and_Boot_USB_Key#setup_system_partition|this discussion]].) A very few EFI systems also do not look for a boot executable under the standard {{Path|/EFI/Boot/bootx64.efi}} path, but instead will use {{Path|/EFI/Microsoft/Boot/bootmgfw.efi}}.<ref>Smith, Roderick W. [http://www.rodsbooks.com/refind/installing.html#naming "The rEFInd Boot Manager: Installing rEFInd: Alternative Naming Options"]</ref> If that's the case for your target machine, change the EFI boot file path using <code>buildkernel --easy-setup</code>, then re-run <code>buildkernel --ask --verbose</code>.

{{Note|If you try to fix things that involve using the graphical kernel configuration editor, and you are connected over {{c|ssh}} from your helper machine, be aware that you may get some pretty strange characters displayed. This can happen if your helper's locale is not present on the target (in the host operating system that is, not the {{c|chroot}}, since {{c|sshd}} is running in the former context).<ref name="set_locale_failed">ServerFault Q&A Site: [http://serverfault.com/questions/304469/setting-locale-failed-force-certain-locale-when-connecting-through-ssh "Setting locale failed: force certain locale when connecting through ssh"]</ref> In this case, simply open up a chroot directly at the target's keyboard, and perform the {{c|buildkernel}} from there; i.e., directly at the machine, issue:
{{RootCmd
|chroot /mnt/gentoo /bin/bash
|prompt=livecd <span style{{=}}"color:royalblue;">~ #</span>
}}
followed by:
{{RootCmd
|source /etc/profile
|export PS1{{=}}"(chroot:direct) $PS1"
|prompt=livecd <span style{{=}}"color:royalblue;">/ #</span>
}}
and then:
{{RootCmd
|buildkernel --ask --verbose
|prompt=<span style{{=}}"color:gray;">(chroot:direct)</span> livecd <span style{{=}}"color:royalblue;">/ #</span>
}}
}}

Once you have made your changes and are ready to have another go at rebooting, simply proceed from the section [[#exit_chroot_and_restart|"Cleanly Dismounting the {{c|chroot}} and Restarting"]] in the main text. Good luck!

== <span id="next_steps">Next Steps (and Fork in the Road)</span> ==

Now that you have successfully booted into Gentoo from UEFI, we can proceed to configure your system. At this point, you need to follow one of two tracks for the final set of chapters (10-14), depending on your [[../Building_the_Gentoo_Base_System_Minus_Kernel#choose_systemd_or_openrc|earlier choice of init system]]:
* users targeting '''{{c|OpenRC}}''' (the default) should [[../Completing_OpenRC_Configuration_and_Installing_Necessary_Tools|click here]] to go to the next chapter on the regular track, "Completing {{c|OpenRC}} Configuration and Installing Necessary Tools"; whereas
* users targeting '''{{c|systemd}}''' should instead [[../Configuring_systemd_and_Installing_Necessary_Tools|click here]] to go to the next chapter on the alternative track, "Configuring {{c|systemd}} and Installing Necessary Tools".


== <span id="notes">Notes</span> ==
{{reflist}}

{| class="wikitable" style="margin: 1em auto 1em auto;"
|-
| rowspan=2|[[../Configuring_and_Building_the_Kernel|< Previous]]
| rowspan=2|[[../|Home]]
| [[../Completing_OpenRC_Configuration_and_Installing_Necessary_Tools|Next ({{c|OpenRC}}) >]]
|-
| [[../Configuring_systemd_and_Installing_Necessary_Tools|Next ({{c|systemd}}) >]]
|}

[[Category:Sakaki's EFI Install Guide]]