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  session from the helper PC;
 * 2) Setting up additional  configuration options, such as locale;
 * 3) Emerging additional system tools, such a logger,  daemon etc.;
 * 4) Ensuring the system is fully up-to-date (using  from );
 * 5) Making sure your system's  is writable (no longer the default as of OpenRC 0.28);
 * 6) Performing a precautionary reboot without the  graphical boot manager;
 * 7) Enabling the graphical boot manager, 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
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 to come up on boot earlier), and then  in again, so that we can use the facilities of the helper machine to complete the install.

Wait for a moment or two post-boot, and then check to see that you have been allocated an IP address. Working directly at the keyboard of the target PC, issue:

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

Now take 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 started up on boot (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 against the one presented, and then, if it matches, continue as below:

Setting Remaining Configuration Options
Next, and before we invoke again, we'll want to set our hostname (and a number of other  options). Note that all subsequent commands should be issued via the connection on the helper PC, unless otherwise specified.

Hostname
We'll begin by setting our hostname. Choose whatever name you like; I'm going to use. Issue:

Edit the file so it reads:

Save, and exit.

Now issue the following to pick up the change:

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

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:

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

Review the file, appending the LC_COLLATE specification (if missing) as follows:

Save (if you made changes), and exit.

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. Then, issue:

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

Save, and exit.

We are nearly done - the last step in this section is to ensure that the 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 consolefont and consoletranslation variables in the file (which is read by the optional  service) in order to fix their virtual console text display. 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 edit that file, so that the only uncommented lines read as follows:



Save and exit the editor.

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

Finally, whether or not you modified above, regenerate your environment:

Post-Boot Script
At this point, it's useful to setup an script, which will be run each time the main boot process has concluded. We will use this to address the following glitch:
 * 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.

To create the script, issue:

and place the following text in that file:

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

That's it, the script will now be run automatically at the conclusion of each system boot! You can of course add your own commands to the script, if you like.

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

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.

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.

Also, 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:

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

OpenRC Logging
Lastly, it will be useful to turn on logging, so that you can easily check for any errors post-boot. Issue:

Scroll down to the section, and modify the lines so they read:

Leave the rest of the file as-is. Save and exit. The log will be written to by default.

<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. 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 ; although marked as fixed in the bug tracker, the issue appears to affect some later versions too, so the below workaround is still recommended on modern systems). 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 I 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 additional ebuild repositories (aka 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
As there are quite a few interlocking steps required to properly keep a Gentoo system up-to-date, I have provided a convenience script,, to do this as part of the ebuild repository (aka 'overlay'). To install it now, issue:

Assuming this looks OK, execute the script to bring your system fully 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 ebuild repositories, such as ) and the cache (using   /  );
 * remove any prior resume history (using  )
 * ensure Portage itself is up-to-date (using );
 * ensure itself is up-to-date (using  ), restarting if not;
 * emerge any packages which have been updated, or whose use flags have changed (using );
 * remove any unreferenced packages (using );
 * rebuild any external modules if necessary (such as those for VirtualBox) (using )
 * rebuild any packages depending on stale libraries (using );
 * update old Perl modules not caught by (using  );
 * remove stale versions of Python from the list (using  );
 * not attempt to rebuild the kernel, even if a new version of has become available (because we specified  );
 * remove any unreferenced packages again (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 );
 * update package metadata (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="efivarfs_rw">Ensuring is Writable
Unfortunately, as of, the special filesystem (which maintains a mapping to the EFI variables, held on non-volatile storage on your machine) has changed to being mounted read-only by default (at odds with , incidentally, which still mounts it read-write). While modern (>= 1.0.31) versions of will automatically deal with this problem, it is inconvenient should you want to e.g. use  to set the boot order manually, modify secure boot settings from the command line, etc..

To work around this issue (and revert to read-write mounting), issue:

and append the following line to that file:

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

Next, ensure that the filesystem is writeable in the current session:

Verify that it has remounted correctly:

Check particularly that "" is present in the output property list, as above.

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

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

Next, ensure that your active kernel is still selected (occasionally, the link can be removed if the above  step upgraded your  package). Issue:

and check that the current kernel (at the moment, there should only be one version in the list) has an asterisk marking it. If it does not, then issue:

to select it.

<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. To do so, ensure that the boot USB key is still inserted in the target machine, then 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:

(The exact display you see may differ from the above.)

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.

If that all worked, click here to skip to the next section now.

<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 under OpenRC".