User:Sakaki/Sakaki's EFI Install Guide/Completing OpenRC Configuration and Installing Necessary Tools

In this section, we'll be following along with Chapter 9 of the Gentoo handbook, although of course you are at this point already booted into your new system (in contrast to the handbook flow).

The steps we'll be undertaking are:
 * 1) Noting our IP address, and re-establishing an ssh session from the helper PC;
 * 2) Setting up additional OpenRC configuration options, such as locale;
 * 3) Emerging additional system tools, such a logger, cron daemon etc.;
 * 4) Ensuring the system is fully up-to-date (using genup from sakaki-tools);
 * 5) Performing a precautionary reboot without the plymouth graphical boot manager;
 * 6) Enabling the graphical boot manager (plymouth), and restarting.

Once this is complete, we'll be in a position to configure secure boot, and bring up GNOME 3.

So, let's get going with the configuration!

Noting IP Address and Re-Establishing ssh</tt>
Our first order of business is to check our IP address (the network connection - whether wired or wireless - should have started automatically, given that we set up dhcpcd</tt> to come up on boot earlier), and then ssh</tt> in again, so that we can use the facilities of the helper machine to complete the install.

<span id="post_reboot_ip">Wait for a moment or two post-boot, and then check to see that you have been allocated an IP address:

Hopefully, dhcpcd</tt> will have autoconfigured an interface, as shown. You should of course look for the name corresponding to the interface on your machine (rather than enp0s25</tt>): you wrote this down earlier. Make a note of this address, you will need it shortly.

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 sshd</tt> started up on boot (and of course will be different from those created by the sshd</tt> 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 sshd</tt> run), and will refuse to connect via ssh</tt> (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 ssh</tt>. From the helper, issue:

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

<span id="set_openrc_config_opts">Setting Remaining OpenRC</tt> Configuration Options
Next, and before we invoke screen</tt> again, we'll want to set our hostname (and a number of other OpenRC</tt> options). Note that all subsequent commands should be issued via the ssh</tt> connection on the helper PC, unless otherwise specified.

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

Edit the file so it reads:

Save, and exit nano</tt>.

Now issue the following to pick up the change:

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

<span id="set_locale_openrc">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 <tt>*</tt>. Now choose a UTF-8 variant from the list (per the Gentoo handbook). For my particular case, that's option 5 in the list, <tt>en_GB.utf8</tt>, but yours will most likely vary. Issue:

Check that this choice has been reflected in the file ; issue:

Review the file, appending the <tt>LC_COLLATE</tt> specification (if missing) as follows:

Save (if you made changes), and exit <tt>nano</tt>.

We already set up the keymap for use in (post-boot) virtual terminals earlier. However, we also need to make sure our X11 setup (which we'll exercise shortly) is correct. Confusingly, X Windows uses a different naming system for keyboard layouts from the virtual console and the initramfs settings.

Find the appropriate X keyboard layout by scrolling through the list provided here.

In my case, the correct code is <tt>jp</tt>. Then, issue:

and place the following text in that file (substituting the keyboard layout name you just looked up):

Save, and exit <tt>nano</tt>.

We are nearly done - the last step in this section 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).

However, some users will need to set the <tt>consolefont</tt> and <tt>consoletranslation</tt> variables in the file (which is read by the optional <tt>OpenRC</tt> <tt>consolefont</tt>service) in order to fix their virtual console text display. See the <tt>setfont</tt> 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 edit that file, so that the only uncommented lines read as follows:

<span id="fix_strange_characters_on_backspace">

Save and exit the <tt>nano</tt> editor.

Ensure that the necessary service will come up on boot, and start it (to pull in your new font settings):

<span id="regenerate_env">Finally, whether or not you modified above, regenerate your environment:

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

Note that this should now reflect the timezone you set earlier. If the time is not correct, set it now in MMDDhhmmYYYY format (Month, Day, hour, minute, year):

to set it.

By default, <tt>OpenRC</tt> will use the <tt>hwclock</tt> service to load and save the system clock on your machine on startup and shutdown, and will do so based on UTC (unless instructed otherwise). The settings may be found in the file, and are discussed further here.

<span id="openrc_utc">Force the RTC into sync with the system clock now; issue:

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

and check that the reported times (which will both be shown in your local timezone) are in close agreement.

<span id="misc_networking_openrc">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 "<tt>This is koneko.(none)</tt>"-style message at console login. To fix this, enter:

and remove the <tt>.\0</tt> string from that file, so it reads:

Save and exit <tt>nano</tt>.

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

And modify the <tt>127.0.0.1</tt> and <tt>::1</tt> lines in the 'localhost aliases' section, so they read:

Save and exit <tt>nano</tt>.

<span id="boot_logging_openrc">OpenRC Logging
Lastly, it will be useful to turn on <tt>OpenRC</tt> logging, so that you can easily check for any errors post-boot. Issue:

Scroll down to the <tt>rc_logger</tt> section, and modify the lines so they read:

Save and exit <tt>nano</tt>. The log will be written to by default.

<span id="emerge_misc_system_tools">Emerging Additional System Tools
Next, we will <tt>emerge</tt> 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 <tt>screen</tt> environment back. Issue:

As before, setup a second virtual console inside <tt>screen</tt>, which will be useful to e.g., monitor the status of long <tt>emerge</tt>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. Issue:

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 <tt>grep</tt>). Issue:

Now start it up (and enable at boot):

Next, we need a <tt>cron</tt> daemon for scheduled commands. We'll choose, a fork of <tt>vixie-cron</tt>. Issue:

Enable and start it:

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

There is no service to explicitly enable for <tt>mlocate</tt>. It automatically adds an entry (for <tt>updatedb</tt> ) 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 <tt>sshd</tt>, 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 <tt>dhcpcd</tt>, 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, <tt>usbutils</tt> provides similar facilities to the <tt>pciutils</tt> package (present in the @system set), but for USB devices. In particular, the <tt>lsusb</tt> command it includes is very useful. The <tt>hwinfo</tt> package provides (inter alia) the eponymous <tt>hwinfo</tt> 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 <tt>emerge</tt> some useful Portage tools. Issue:

Here's what these packages provide:
 * <tt>mirrorselect</tt> we've already used (in the minimal install image system) - it is a tool to simplify the selection of Gentoo mirror servers;
 * <tt>eix</tt> 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;
 * <tt>gentoolkit</tt> 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;
 * <tt>euses</tt> 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 <tt>genup</tt> utility script, from the <tt>sakaki-tools</tt> 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 <tt>genup</tt> via its manpage. However, in summary, when invoked in non-interactive ('batch') mode (as here), and with the <tt>--no-kernel-upgrade</tt> flag, it will:
 * update your Portage tree (including any active overlays, such as <tt>sakaki-tools</tt>) and the <tt>eix</tt> cache (using <tt>eix-sync</tt>);
 * remove any prior <tt>emerge</tt> resume history (using <tt>emaint --fix cleanresume</tt>)
 * ensure Portage itself is up-to-date (using <tt>emerge --oneshot --update portage</tt>);
 * emerge any packages which have been updated, or whose use flags have changed (using <tt>emerge --deep --with-bdeps=y --newuse --update --backtrack=50 @world</tt>);
 * rebuild any external modules if necessary (such as those for VirtualBox) (using <tt>emerge @module-rebuild</tt>)
 * rebuild any packages depending on stale libraries (using <tt>emerge @preserved-rebuild</tt>);
 * update old Perl and Python modules not caught by <tt>emerge</tt> (using <tt>perl-cleaner</tt> and <tt>python-updater</tt>);
 * not attempt to rebuild the kernel, even if a new version of has become available (because we specified <tt>--no-kernel-upgrade</tt>);
 * remove any unreferenced packages (using <tt>emerge --depclean</tt>);
 * re-emerge any packages depending on libraries removed by the previous step (using <tt>revdep-rebuild</tt>);
 * rebuild any packages depending on stale libraries again (using <tt>emerge @preserved-rebuild</tt>);
 * remove any unused source tarballs (using <tt>eclean --deep distfiles</tt>); and
 * update environment settings as a precautionary measure (using <tt>env-update</tt>).

Assuming that completed successfully (you receive the message "<tt>All done - your system is now up-to-date!</tt>"), look at the preceding few lines of output from <tt>genup</tt>. If you see:

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

then (as instructed) you need to run <tt>dispatch-conf</tt> (this is an inherently interactive process, and so is not called by <tt>genup</tt> 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 <tt>plymouth</tt>
To be cautious, we will now reboot the system to check that our changes to the <tt>OpenRC</tt> 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 <tt>plymouth</tt> 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 <tt>screen</tt> virtual terminals, and then the <tt>ssh</tt> connection itself. Issue:

which will close the first <tt>screen</tt> terminal, then:

to close the second one. Then exit the enclosing <tt>ssh</tt> session itself:

Now, ensure your boot USB key is inserted, and then, directly on the target machine (i.e., at it's 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 <tt>gpg</tt> 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 <tt>OpenRC</tt>-related started up OK (do this directly at the target machine's keyboard, there's no need to re-establish <tt>ssh</tt>/<tt>screen</tt> for this short interlude):

Provided this shows  against all services, then all is well (you can press  and  to page through the output here, and  to quit).

<span id="reboot_with_plymouth">Enabling <tt>plymouth</tt>, 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 <tt>plymouth</tt>. 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 <tt>buildkernel --easy-setup</tt> tool to turn on Plymouth (the following is an example only; the values shown will vary for your machine). Issue:

Specifying a <tt>plymouth</tt> theme will have <tt>buildkernel</tt> automatically turn on the <tt>quiet</tt> and <tt>splash</tt> kernel command line options, disable the 'penguin logo' display on boot (via <tt>CONFIG_LOGO</tt>) and instruct <tt>genkernel</tt> to ensure that the necessary <tt>plymouth</tt> modules are installed into the initramfs. Of course, we need to run <tt>buildkernel</tt> 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 <tt>make clean</tt> by default, so it shouldn't take long).

When you get the message "<tt>All done!</tt>", 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 <tt>gpg</tt> 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 <tt>plymouth</tt> Doesn't Work Properly
If you encounter problems when using <tt>plymouth</tt> (for example, it failing to accept your <tt>gpg</tt>-encrypted LUKS keyfile passphrase), you'll need to fall back to the textual boot manager (as debugging <tt>plymouth</tt> is beyond the scope of this tutorial). Fortunately, because <tt>buildkernel</tt> 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 / <tt>chroot</tt>.

<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 <tt>mount</tt> on your helper PC):

Enter the <tt>root</tt> password (for the helper PC, that is), and then as <tt>root</tt>, 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 <tt>plymouth</tt> during <tt>init</tt>) and replace it with the previous version. If you have only run <tt>buildkernel</tt> once since changing the path of the bootfile (from to ) in the last step, then issue:

otherwise, if you have run <tt>buildkernel</tt> 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 <tt>buildkernel</tt>) will not attempt to use <tt>plymouth</tt> during <tt>init</tt>. 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 <tt>gpg</tt> 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 under OpenRC".