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

From Gentoo Wiki
Jump to:navigation Jump to:search


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. Making sure your system's efifvarfs is writable (no longer the default as of OpenRC 0.28);
  6. Performing a precautionary reboot without the plymouth graphical boot manager;
  7. 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

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 to come up on boot earlier), and then ssh 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:

localhost ~ #ifconfig 
enp0s25: flags=4163<UP,BROADCAST,RUNNING,MULTICAST>  mtu 1500
        inet 192.168.1.106  netmask 255.255.255.0  broadcast 192.168.1.255
        ... etc ...

Hopefully, dhcpcd 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): you wrote this down earlier. Make a note of this address, you will need it shortly.

Note
If you need to bring up a network interface with a static IP, please see the "Manual Network Configuration" section of chapter 3 of the Gentoo handbook.

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 sshd started up on boot (and of course will be different from those created by the sshd instance we started in the outer, 'host' system earlier):

localhost ~ #for K in /etc/ssh/ssh_host_*key.pub; do ssh-keygen -l -f "${K}"; done
Note
By default, the above command will now display SHA-256 fingerprints in Base64 format (as used by more modern versions of the ssh client program); however, if your ssh client still uses MD5 fingerprints, you can display these using the following command instead:
localhost ~ #for K in /etc/ssh/ssh_host_*key.pub; do ssh-keygen -l -E "md5" -f "${K}"; done

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 run), and will refuse to connect via ssh (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 ~/.ssh/known_hosts. Issue:

user@pc2 $sed -i '/^[^[:digit:]]*192.168.1.106[^[:digit:]]/d' ~/.ssh/known_hosts
Note
Substitute whatever IP address you got back from ifconfig above for 192.168.1.106 in the above command.

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

user@pc2 $ssh root@192.168.1.106
Note
Substitute whatever IP address you got back from ifconfig above for 192.168.1.106 in the above command.
Tip
Remember, if you have a large number of existing keys in your ~/.ssh directory, you may get a Too many authentication failures error when attempting to connect. In this case (which will not affect most users), simply add the -o PubkeyAuthentication=no option to your ssh command.[1]

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

... additional output suppressed ...
Are you sure you want to continue connecting (yes/no)? <type 'yes', then Enter>
... additional output suppressed ...
Password: <enter the password for root>
... additional output suppressed ...
Note
The root password required here is the one you set within the chroot earlier in the tutorial (the same one you used to log in directly at the keyboard a short time ago.)

Setting Remaining OpenRC Configuration Options

Next, and before we invoke screen again, we'll want to set our hostname (and a number of other OpenRC options). Note that all subsequent commands should be issued via the ssh 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 koneko. Issue:

localhost ~ #nano -w /etc/conf.d/hostname

Edit the file so it reads:

FILE /etc/conf.d/hostnameSet your desired hostname
hostname="koneko"

Save, and exit nano.

Note
Substitute your own choice of machine name for koneko in the above.

Now issue the following to pick up the change:

localhost ~ #/etc/init.d/hostname restart

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

localhost ~ #exec bash --login

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:

koneko ~ #eselect locale list 
Available targets for the LANG variable:
  [1]   C *
  [2]   C.utf8
  [3]   POSIX
  [4]   en_GB
  [5]   en_GB.iso88591
  [6]   en_GB.utf8
  [ ]   (free form)
Note
Your list of targets will also most likely differ from the one shown above, depending on the choices your made when running locale-gen earlier. (Also, your prompt will of course be different, and reflect your personal choice of hostname.)

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 6 in the list, en_GB.utf8, but yours will most likely vary. Issue:

koneko ~ #eselect locale set 6
koneko ~ #source /etc/profile
Note
Substitute for the number 6 in the above, with the correct value to select your UTF-8 profile from the list provided by eselect locale list.

Check that this choice has been reflected in the file /etc/env.d/02locale; issue:

localhost ~ #nano -w /etc/env.d/02locale

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

FILE /etc/env.d/02localeCheck language and collation settings, append LC_COLLATE if missing
LANG="en_GB.utf8"
LC_COLLATE="C"

Save (if you made changes), and exit nano.

Note
The LANG value in the /etc/env.d/02locale file may well differ, depending on the eselect locale choice you just made.
Note
We have set the collation order to "C" here, per the Gentoo wiki recommendation.

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.

Note
We can't use man xkeyboard-config, as the relevant software x11-misc/xkeyboard-config is not (yet) emerged on the target PC; however, if this command works on your helper PC, you can also review the list it provides there.

In my case, the correct code is jp. Then, issue:

localhost ~ #mkdir -p -v /etc/X11/xorg.conf.d
localhost ~ #nano -w /etc/X11/xorg.conf.d/00-keyboard.conf

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

FILE /etc/X11/xorg.conf.d/00-keyboard.confSet keyboard mapping for X
Section "InputClass"
        Identifier "system-keyboard"
        MatchIsKeyboard "on"
        Option "XkbLayout" "jp"
EndSection

Save, and exit nano.

Note
Substitute for jp in the above with a value appropriate for your own keyboard! For example, a standard US layout would use Option "XkbLayout" "us" here; a standard UK layout, Option "XkbLayout" "gb".
Note
There are many other options possible here; see the Xorg Guide on the Gentoo Wiki for further details.

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 Backspace (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 /etc/conf.d/consolefont file (which is read by the optional OpenRC consolefontservice) in order to fix their virtual console text display. See the setfont 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.[2][3][4]

Issue:

koneko ~ #nano -w /etc/conf.d/consolefont

And edit that file, so that the only uncommented lines read as follows:

FILE /etc/conf.d/consolefontSetting the console font (example only, adjust as needed)
consolefont="lat1-16"
consoletranslation="8859-1_to_uni"
Note
You should set an appropriate font and mapper for your system. You may find the information in the Gentoo wiki "Localization Howto" document useful. The above consolefont and unicodemap settings should work for a US machine also.
Important
If, after a reboot, you find that e.g., pressing the Backspace key (when typing on your target machine's keyboard directly) produces strange characters on the screen, in the first instance try commenting out the consolefont line in /etc/conf.d/consolefont (by placing a # symbol at the start), then rebooting.
Note
You can also specify unicodemap in the /etc/conf.d/consolefont file, but that's generally unnecessary, since most fonts include a Unicode mapping table anyway.

Save and exit the nano editor.

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

koneko ~ #rc-update add consolefont boot
koneko ~ #rc --service consolefont start

Finally, whether or not you modified /etc/conf.d/consolefont above, regenerate your environment:

koneko ~ #env-update && source /etc/profile

Post-Boot Script

At this point, it's useful to setup an /etc/local.d/postboot.start 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 plymouth), meaning that you sometimes get grey lines at the top or bottom of the console screen.

To create the script, issue:

koneko ~ #nano -w /etc/local.d/postboot.start

and place the following text in that file:

FILE /etc/local.d/postboot.startA script to run when boot completed
#!/bin/bash
# commands in this script will be run once the main boot process is complete

# ensure the framebuffer is properly cleared...
cat /dev/zero > /dev/fb0 2>/dev/null || true
Note
Under OpenRC, the local service (which is enabled by default) will run any executable /etc/local.d/<name>.start files at the final phase of system startup, and any executable /etc/local.d/<name>.stop files at the first phase of system shutdown.
Note
The cat of zeros will stop automatically when the end of the framebuffer (/dev/fb0) is reached; this will be after 1920*1080*4 (rgba) = 8294400 bytes on the CF-AX3, but of course your system may vary.

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

koneko ~ #chmod -v 755 /etc/local.d/postboot.start

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 /etc/local.d/postboot.start 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:

koneko ~ #date

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

koneko ~ #date MMDDhhmmYYYY

to set it.

Note
Obviously, substitute for MMDDhhmmYYYY with the actual, numerical date and time. For example, to set the date/time to 5:12pm on February 9th 2017 (local time), you would issue:
koneko ~ #date 020917122017
Note
To reiterate, the date set should have carried across the reboot OK, unless there is an issue with your real-time-clock (which we will look at next).

By default, OpenRC will use the hwclock 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 /etc/conf.d/hwclock, and are discussed further here.

Force the RTC into sync with the system clock now; issue:

koneko ~ #hwclock --systohc
Note
This is different from the default behaviour in Windows (which will use local time for the RTC), so we will modify the setting in Windows, later in the tutorial.

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

koneko ~ #date; hwclock --show

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 This is koneko.(none)-style message at console login. To fix this, enter:

koneko ~ #nano -w /etc/issue

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

FILE /etc/issueModify the string to read as follows
This is \n (\s \m \r) \t

Save and exit nano.

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

koneko ~ #nano -w /etc/hosts

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

FILE /etc/hostsEnsure you have aliases for your chosen machine name
# IPv4 and IPv6 localhost aliases
127.0.0.1       koneko localhost
::1             koneko localhost

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

Note
Substitute your own choice of machine name (which you set just recently) for koneko in the above command.

OpenRC Logging

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

koneko ~ #nano -w /etc/rc.conf

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

FILE /etc/rc.confTurn on OpenRC logging
# rc_logger launches a logging daemon to log the entire rc process to
# /var/log/rc.log
# NOTE: Linux systems require the devfs service to be started before
# logging can take place and as such cannot log the sysinit runlevel.
rc_logger="YES"
Tip
If you wish, you can also set rc_parallel="YES" in this file, which will speed up your boot times. It is perfectly safe to do so for most standard systems.

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

Emerging Additional System Tools

Next, we will emerge 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 screen environment back. Issue:

koneko ~ #screen
koneko ~ #export PS1="(1) $PS1"

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

koneko ~ #export PS1="(2) $PS1"

Now hit Ctrla then p to get back to the original console.

Note
Of course, there is no chroot to worry about any more, as we are booted natively into our new system.

We'll begin by installing app-admin/syslog-ng as the logger, so that we can view and parse regular textual log files. Issue:

(1) koneko ~ #emerge --ask --verbose app-admin/syslog-ng 
... additional output suppressed ...
Would you like to merge these packages? [Yes/No] <press y, then press Enter>
... additional output suppressed ...
Note
As before, you can switch to the second console to watch the progress with showem, if you like.

Per bug #406623, we need to make a minor configuration change to avoid binary zero characters getting written to the /var/log/messages file (making it look like a binary file to tools like grep; 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:

(1) koneko ~ #sed -i 's/threaded(yes)/threaded(no)/g' /etc/syslog-ng/syslog-ng.conf

Now start it up (and enable at boot):

(1) koneko ~ #rc-update add syslog-ng default
(1) koneko ~ #rc --service syslog-ng start
Note
There are other choices of logger available to you, as discussed here. In what follows, I'm going to assume you have chosen to install syslog-ng.

Next, we need a cron daemon for scheduled commands. We'll choose sys-process/cronie, a fork of vixie-cron. Issue:

(1) koneko ~ #emerge --ask --verbose sys-process/cronie 
... additional output suppressed ...
Would you like to merge these packages? [Yes/No] <press y, then press Enter>
... additional output suppressed ...

Enable and start it:

(1) koneko ~ #rc-update add cronie default
(1) koneko ~ #rc --service cronie start
Note
Per the Gentoo Handbook, installing a cron daemon is optional, but highly recommended, as many other system tools rely on it.[5] The rest of this tutorial assumes you have chosen to install it.

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

(1) koneko ~ #emerge --ask --verbose sys-apps/mlocate 
... additional output suppressed ...
Would you like to merge these packages? [Yes/No] <press y, then press Enter>
... additional output suppressed ...

There is no service to explicitly enable for mlocate. It automatically adds an entry (for updatedb[6]) to /etc/cron.daily on installation.

Note
Per the Gentoo Handbook, installation of mlocate is optional.

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

(1) koneko ~ #emerge --ask --verbose app-admin/logrotate 
... additional output suppressed ...
Would you like to merge these packages? [Yes/No] <press y, then press Enter>
... additional output suppressed ...

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

Note
Use of a log rotation service is optional, but recommended. You can set the preferences for log rotation with logrotate in the file /etc/logrotate.conf, and with application-specific files under /etc/logrotate.d. See the logrotate manual page for more details.[7]

We have already activated sshd, 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 sys-fs/dosfstools. Issue:

(1) koneko ~ #emerge --ask --verbose sys-fs/dosfstools 
... additional output suppressed ...
Would you like to merge these packages? [Yes/No] <press y, then press Enter>
... additional output suppressed ...
Note
This package is required when working with UEFI volumes (in particular, for the mkfs.vfat command[8]), so it is strongly recommended that you install it (and the rest of this tutorial assumes you have indeed done so).

We have already installed and activated dhcpcd, 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:

(1) koneko ~ #emerge --ask --verbose sys-apps/{usbutils,hwinfo} 
... additional output suppressed ...
Would you like to merge these packages? [Yes/No] <press y, then press Enter>
... additional output suppressed ...

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

Check that these work. Issue:

(1) koneko ~ #lsusb

and review the output, then:

(1) koneko ~ #hwinfo | less

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

Note
Installation of both of these packages is optional, but recommended.

Now we'll emerge some useful Portage tools. Issue:

(1) koneko ~ #emerge --ask --verbose app-portage/{mirrorselect,eix,gentoolkit,euses} 
... additional output suppressed ...
Would you like to merge these packages? [Yes/No] <press y, then press Enter>
... additional output suppressed ...

Here's what these packages provide:

  • mirrorselect we've already used (in the minimal install image system) - it is a tool to simplify the selection of Gentoo mirror servers;
  • eix 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;
  • gentoolkit 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;
  • euses is a simple tool that allows you to query for use flag descriptions quickly.
Note
Installation of all of the above packages is optional, but highly recommended (and the rest of this tutorial will assume that you have indeed done so).
Tip
If you use the eix utility on the command line, you may find that its output has an unpleasant background colour effect, particuarly on white-background terminals. To fix this, simply issue:[11]
(1) koneko ~ #echo "SOLARIZED=true" > /etc/eixrc/99-colour

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, genup, to do this as part of the sakaki-tools ebuild repository (aka 'overlay'). To install it now, issue:

(1) koneko ~ #emerge --ask --verbose app-portage/genup 
... additional output suppressed ...
Would you like to merge these packages? [Yes/No] <press y, then press Enter>
... additional output suppressed ...
Note
When genup is emerged, it will setup the configuration files /etc/eix-sync.conf and /etc/eixrc/01-cache, per the instructions in this wiki article. This ensures that eix-sync will also sync all active layman ebuild repositories, and that it will regenerate cached metadata on a sync (and use the metadata on an eix-update for a speed-up and better accuracy). Please note that if you do not have the app-portage/layman package installed (which, if you have been following these instructions, you will not at this point), then you will see the error message when running genup:
/usr/bin/eix-sync: line xxx: layman: command not found
 * layman -S failed
This is to be expected and not a cause for concern.

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

(1) koneko ~ #genup --no-kernel-upgrade

You can read more about genup via its manpage. However, in summary, when invoked in non-interactive ('batch') mode (as here), and with the --no-kernel-upgrade flag, it will:

  • update your Portage tree (including any active ebuild repositories, such as sakaki-tools) and the eix cache (using emaint sync --auto / eix-sync);
  • remove any prior emerge resume history (using emaint --fix cleanresume)
  • ensure Portage itself is up-to-date (using emerge --oneshot --update portage);
  • ensure genup itself is up-to-date (using emerge --oneshot --update genup), restarting if not;
  • emerge any packages which have been updated, or whose use flags have changed (using emerge --deep --with-bdeps=y --changed-use --update --backtrack=50 @world);
  • remove any unreferenced packages (using emerge --depclean);
  • rebuild any external modules if necessary (such as those for VirtualBox) (using emerge @module-rebuild)
  • rebuild any packages depending on stale libraries (using emerge @preserved-rebuild);
  • update old Perl modules not caught by emerge (using perl-cleaner);
  • remove stale versions of Python from the eselect list (using eselect python cleanup);
  • not attempt to rebuild the kernel, even if a new version of sys-kernel/gentoo-sources has become available (because we specified --no-kernel-upgrade);
  • remove any unreferenced packages again (using emerge --depclean);
  • re-emerge any packages depending on libraries removed by the previous step (using revdep-rebuild);
  • rebuild any packages depending on stale libraries again (using emerge @preserved-rebuild);
  • remove any unused source tarballs (using eclean --deep distfiles); and
  • update environment settings as a precautionary measure (using env-update);
  • update eix package metadata (using eix-sync -0); and
  • run any custom updaters in /etc/genup/updaters.d.
Note
If you should have any issues when running genup, particularly the deep emerge stage, then you may find it useful to refer to these earlier notes. (As of version 1.0.4, genup will automatically retry failed emerge runs with make parallelism inhibited.)
Important
With rsync-based updates over a slow network connection, you will sometimes encounter the situation when the update of the gentoo repository fails validation (as a change is committed to it mid-download, making the overall gemato signature incorrect). If this happens to you, simply run genup again. And if you have the problem repeatedly, switch to using webrsync, as described here.
Note
For avoidance of doubt, genup will signature-verify the Gentoo repo before using it, since we set things up that way earlier (here and here). As before, warnings that the key is not certified with a trusted signature are to be expected[12] and do not impact the signature check validity.

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

* There are no configuration file changes pending review.

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

* genup: Warning: There are configuration file changes pending review!
* genup: Warning: Please run dispatch-conf to interactively resolve them.

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

(1) koneko ~ #dispatch-conf

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

Note
The dispatch-conf tool is discussed in more detail in the bootstrapping section earlier.
Important
If net-misc/openssh has just been updated, you may be prompted a change to /etc/ssh/sshd_config, undoing the ability to log in with a password. As we still require this for now, any such proposed change to this file should be zapped (rejected).
Note
If you prefer, you can add the --ask flag to genup, in which case it will run dispatch-conf for you at the appropriate point in the update. Alternatively, you can also force genup to invoke dispatch-conf even in non-interactive (batch) mode, by appending the --dispatch-conf option.
Note
If you should have any issues when running genup, particularly the deep emerge stage, then you may find it useful to refer to these earlier notes.
Note
For avoidance of doubt, the @world set includes the @system set.

Ensuring efivarfs is Writable

Unfortunately, as of sys-apps/openrc-0.28, the special /sys/firmware/efi/efivars filesystem (which maintains a mapping to the EFI variables, held on non-volatile storage on your machine) has changed[13] to being mounted read-only by default (at odds with systemd, incidentally, which still mounts it read-write). While modern (>= 1.0.31) versions of buildkernel will automatically deal with this problem, it is inconvenient should you want to e.g. use efibootmgr 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:

(1) koneko ~ #nano -w /etc/fstab

and append the following line to that file:

FILE /etc/fstabAppend line to ensure efivarfs still writable under OpenRC >= 0.28
efivarfs /sys/firmware/efi/efivars efivarfs rw,nosuid,nodev,noexec,relatime 0 0

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

Note
With this entry in your /etc/fstab, OpenRC will mount efivarfs read-write automatically on subsequent boots. Note that the efivarfs filesystem is only available when booted under UEFI.

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

(1) koneko ~ #umount -v efivarfs && mount -v efivarfs

Verify that it has remounted correctly:

(1) koneko ~ #mount | grep efivarfs 
efivarfs on /sys/firmware/efi/efivars type efivarfs (rw,nosuid,nodev,noexec,relatime)

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

Tip
If you don't want to leave eifvarfs writeable all the time, you can omit the /etc/fstab edit suggested above, instead issuing:
(1) koneko ~ #mount -o remount,rw /sys/firmware/efi/efivars
prior to any operation that requires (manual) write-access to efivarfs, and then issuing:
(1) koneko ~ #mount -o remount,ro /sys/firmware/efi/efivars

afterwards, to revert.

This is somewhat fiddly, however, so in the remainder of this guide I'm going to assume you have elected to mount efivarfs permanently read-write (per the main body of the text).

Performing a Precautionary Reboot without plymouth

To be cautious, we will now reboot the system to check that our changes to the OpenRC 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 plymouth 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 screen virtual terminals, and then the ssh connection itself. Issue:

(1) koneko ~ #exit

which will close the first screen terminal, then:

(2) koneko ~ #exit

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

koneko ~ #exit

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

localhost ~ #reboot

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 gpg keyfile for your LUKS partition (this is the passphrase you set up earlier). Type this in (directly at the target machine keyboard), and press Enter. 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.

Note
If, having rebooted, you find strange characters being printed out when you press e.g. the Backspace key, please see the note above.

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

koneko ~ #less /var/log/rc.log

Provided this shows [ ok ] against all services, then all is well (you can press Page Up and Page Down to page through the output here, and q to quit).

Note
We set up OpenRC to produce logs earlier.

Next, ensure that your active kernel is still selected (occasionally, the /usr/src/linux link can be removed if the above genup step upgraded your sys-kernel/gentoo-sources package). Issue:

koneko ~ #eselect kernel list

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:

koneko ~ #eselect kernel set 1

to select it.

Enabling plymouth, 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 plymouth. We'll also take this chance to migrate our bootfile from /EFI/Boot/bootx64.efi to the less generic /EFI/Boot/gentoo.efi.

Note
On some systems (for example, when running Gentoo as a VirtualBox guest), you should not change the bootfile location, but rather leave it set as /EFI/Boot/bootx64.efi. For avoidance of doubt, plymouth may still be used in such situations.
Important
If you do change the bootfile location to /EFI/Boot/gentoo.efi below, please note that by default you will still have your prior kernel present on the boot USB key, with the path /EFI/Boot/bootx64.efi. Since this can cause 'versionitis' issues in the future (for example, if your BIOS attempts to boot it, because the EFI boot order has become corrupted for some reason), feel free to delete the older /EFI/Boot/bootx64.efi file from the USB key, once you have verified that the new /EFI/Boot/gentoo.efi variant works.

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

koneko ~ #buildkernel --easy-setup
... significant amounts of output suppressed in what follows ... 
* Current configuration (from /etc/buildkernel.conf):

  EFI system partition UUID:  2498f874-ad8f-484e-8aba-81ac1c9665b6
  LUKS root partition UUID:   8111286a-d24e-4ba2-b6af-d0650fab4130
  GPG keyfile partition UUID: DEFAULT (=EFI system partition UUID)
  GPG keyfile (for LUKS):     luks-key.gpg                        
  EFI boot directory:         /EFI/Boot                           
  EFI boot file:              bootx64.efi                         
  Plymouth theme:             NONE (textual boot)                 
  Boot-time keymap:           jp                                  
  Init system:                OpenRC

* Please choose an option:
1) Set EFI system partition  6) Set boot-time keymap
2) Set LUKS root partition   7) Set init system
3) Set LUKS key options      8) Exit without saving
4) Set EFI boot file path    9) Save and exit
5) Set boot splash options
Your choice: press 5 then Enter
* Current boot splash settings:
* Using textual boot (no Plymouth)
* Please choose your desired boot splash setting (or GO BACK):
1) Use textual boot (no Plymouth)
2) Use Plymouth graphical boot splash ('fade-in')
3) GO BACK
Your choice: press 2 then Enter
* New boot splash settings:
* Using Plymouth on boot, with theme 'fade-in'
* Current configuration (from /etc/buildkernel.conf - MODIFIED):

  EFI system partition UUID:  2498f874-ad8f-484e-8aba-81ac1c9665b6
  LUKS root partition UUID:   8111286a-d24e-4ba2-b6af-d0650fab4130
  GPG keyfile partition UUID: DEFAULT (=EFI system partition UUID)
  GPG keyfile (for LUKS):     luks-key.gpg                        
  EFI boot directory:         /EFI/Boot                           
  EFI boot file:              bootx64.efi                         
  Plymouth theme:             fade-in                 
  Boot-time keymap:           jp                                  
  Init system:                OpenRC

* Please choose an option:
1) Set EFI system partition  6) Set boot-time keymap
2) Set LUKS root partition   7) Set init system
3) Set LUKS key options      8) Exit without saving
4) Set EFI boot file path    9) Save and exit
5) Set boot splash options
Your choice: press 4 then Enter
NB - users on VirtualBox should leave the EFI boot file path as is
Only change this (to /EFI/Boot/gentoo.efi)  on a 'real' PC
* Current EFI boot file setting:
* EFI boot file path: /EFI/Boot/bootx64.efi
*  (under EFI system partition mountpoint)
* Please choose your desired EFI boot file setting (or GO BACK):
1) Use /EFI/Boot/bootx64.efi (recommended for initial USB install)
2) Use /EFI/Microsoft/Boot/bootmgfw.efi (fallback for certain systems)
3) Use /EFI/Boot/gentoo.efi (recommended for post-install use)
4) GO BACK
Your choice: press 3 then Enter
* New EFI boot file setting:
* EFI boot file path: /EFI/Boot/gentoo.efi
*  (under EFI system partition mountpoint)

* Current configuration (from /etc/buildkernel.conf - MODIFIED):

  EFI system partition UUID:  2498f874-ad8f-484e-8aba-81ac1c9665b6
  LUKS root partition UUID:   8111286a-d24e-4ba2-b6af-d0650fab4130
  GPG keyfile partition UUID: DEFAULT (=EFI system partition UUID)
  GPG keyfile (for LUKS):     luks-key.gpg                        
  EFI boot directory:         /EFI/Boot                           
  EFI boot file:              gentoo.efi                         
  Plymouth theme:             fade-in                 
  Boot-time keymap:           jp                                  
  Init system:                OpenRC

* Please choose an option:
1) Set EFI system partition  6) Set boot-time keymap
2) Set LUKS root partition   7) Set init system
3) Set LUKS key options      8) Exit without saving
4) Set EFI boot file path    9) Save and exit
5) Set boot splash options
Your choice: press 9 then Enter

* Configuration saved to /etc/buildkernel.conf.
* Be sure to run buildkernel, to rebuild the kernel with the new
* settings, before rebooting.
... significant amounts of output suppressed in the above ...
Note
Once you have things working, you can directly edit /etc/buildkernel.conf and set the variable PLYMOUTHTHEME to be a plymouth theme that you like. You can get a list of available themes by issuing:
koneko ~ #plymouth-set-default-theme --list
However, stay with the fade-in theme for the moment.

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

koneko ~ #buildkernel

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

Note
If buildkernel exits with an error, complaining that the efivarfs is not writeable, double-check that you have made the necessary (under OpenRC) changes to address this issue, which were detailed earlier. If you find you haven't, don't worry, you can apply the necessary fixes now (working directly at the machine's keyboard), and, once done, try running buildkernel again.
Note
Since you now are booted under EFI, this will also add an EFI boot entry for your new kernel and set it at the top of the EFI boot list.

When you get the message "All done!", reboot. To do so, ensure that the boot USB key is still inserted in the target machine, then issue:

koneko ~ #reboot

When the target system restarts, you should now see a graphical password entry screen, as shown below. Enter your LUKS keyfile gpg 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:

Graphical (plymouth) Prompt for GPG/LUKS Passphrase...
...And Subsequent Boot-Time Animation

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

Important
With certain graphics cards, plymouth may actually not be able to display a graphical boot splash at this point in the install, due to missing kernel graphics drivers. If this happens to you, and you get a textual prompt for your gpg passphrase, despite having enabled plymouth, there is no need to worry. Just type in your passphrase and continue with the install; plymouth is running. Once you set up the correct kernel graphics drivers, which we will get to shortly, plymouth's graphical boot splash should also (automatically) start working.
Tip
If you are having difficulties with the graphical LUKS keyfile gpg passphrase entry screen, pressing Esc will revert plymouth to a text-based mode, where you can see any error messages etc. Also, if the boot process appears to 'hang' at the graphical splash screen after typing the passphrase, reboot, and then try this approach (i.e., pressing Esc).
Note
Similarly, depending on your installed version of sys-boot/plymouth, under OpenRC you may only see a simplified 'three square boxes' startup progress screen, rather than the full animation shown in the screenshots above. However, once you set up the correct Direct Rendering Manager graphics drivers in the kernel shortly, you should find that it is replaced by a properly rendered graphic (as above). It won't otherwise affect the operation of your system.
Note
Due to genkernel not including certain plymouth modules into the initramfs, you normally won't get any textual prompts or progress indicators overlaid on the graphical splash during boot (unless plymouth has to fall back completely into text mode, as just mentioned). I haven't fixed this here as I quite like the resulting minimalist look.

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.

Note
Obviously, there's not much point having a graphical boot splash followed by a textual console, but this is only a staging point, we are shortly going to install GNOME3!

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

If plymouth Doesn't Work Properly

Note
If you managed to successfully boot using plymouth (and even if plymouth used its fallback text mode), then you should skip to the next section now - the following is only for troubleshooting a failed boot.

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

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

user@pc2 $su --login root

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

root@pc2 #mkdir -v -p /mnt/tmpefi
root@pc2 #mount -v -t vfat /dev/sdU1 /mnt/tmpefi
Note
Replace /dev/sdU1 in the above with the appropriate device path for the USB key's first partition on your helper PC, such as /dev/sdc1, /dev/sdd1 etc. You can find the path using the lsblk command.

Next, delete the old (failed) kernel and config (the one that tries to use plymouth during init) and replace it with the previous version.

Tip
Since all the essential commands below are simply file delete and copy operations over a FAT32 filesystem on a USB key, you can even carry them out on a Windows box (via the GUI or CLI), in a pinch. This is useful to bear in mind for later reference, should you be trying to fall back to a previous kernel at a point when you don't have a Linux helper PC immediately available.

If you have only run buildkernel once since changing the path of the bootfile (from /EFI/Boot/bootx64.efi to /EFI/Boot/gentoo.efi) in the last step, then issue:

root@pc2 #rm -v /mnt/tmpefi/EFI/Boot/gentoo.efi /mnt/tmpefi/EFI/Boot/config
root@pc2 #cp -v /mnt/tmpefi/EFI/Boot/bootx64.efi /mnt/tmpefi/EFI/Boot/gentoo.efi
root@pc2 #cp -v /mnt/tmpefi/EFI/Boot/config.old /mnt/tmpefi/EFI/Boot/config

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

root@pc2 #rm -v /mnt/tmpefi/EFI/Boot/gentoo.efi /mnt/tmpefi/EFI/Boot/config
root@pc2 #cp -v /mnt/tmpefi/EFI/Boot/gentoo.efi.old /mnt/tmpefi/EFI/Boot/gentoo.efi
root@pc2 #cp -v /mnt/tmpefi/EFI/Boot/config.old /mnt/tmpefi/EFI/Boot/config
Note
If you didn't change the EFI bootfile path (for example, because you are running on VirtualBox), then issue:
root@pc2 #rm -v /mnt/tmpefi/EFI/Boot/bootx64.efi /mnt/tmpefi/EFI/Boot/config
root@pc2 #cp -v /mnt/tmpefi/EFI/Boot/bootx64.efi.old /mnt/tmpefi/EFI/Boot/bootx64.efi
root@pc2 #cp -v /mnt/tmpefi/EFI/Boot/config.old /mnt/tmpefi/EFI/Boot/config
Note
If you happen to have used buildkernel's --snapshot-backup option in the past (to ensure a 'known good' kernel was preserved), you'll also see (kernel and config) files in /mnt/tmpefi/EFI/Boot with prefixed timestamps. For example, if you had previously issued buildkernel --snapshot-backup on 4 May 2014 at 12:23:07 say, you would see the files 2014-05-04-12-23-07-gentoo.efi.old and 2014-05-04-12-23-07-config.old in the /mnt/tmpefi/EFI/Boot directory. You can use such files instead of gentoo.efi.old and config.old, if you like.

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

root@pc2 #sync
root@pc2 #umount -v /mnt/tmpefi
root@pc2 #rmdir -v /mnt/tmpefi
root@pc2 #exit
Note
I have assumed in the above that your helper machine does not automount the USB key. However, if it does, that's no problem, you can simply do the delete-and-replace operation graphically. Similarly, since the boot key is formatted with fat32, you should be able to insert it into any Windows machine and make the necessary changes. Just remember that in either of these two cases, your mountpoint will not be /mnt/tmpefi.

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.

Important
If you still can't get the machine to boot, you'll need to follow the instructions given earlier to boot with the minimal install USB key, unlock the LUKS partition, mount the LVM volumes, then chroot and make any necessary changes.

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

koneko ~ #buildkernel --easy-setup
... significant amounts of output suppressed in what follows ... 
* Current configuration (from /etc/buildkernel.conf):

  EFI system partition UUID:  2498f874-ad8f-484e-8aba-81ac1c9665b6
  LUKS root partition UUID:   8111286a-d24e-4ba2-b6af-d0650fab4130
  GPG keyfile partition UUID: DEFAULT (=EFI system partition UUID)
  GPG keyfile (for LUKS):     luks-key.gpg                        
  EFI boot directory:         /EFI/Boot                           
  EFI boot file:              gentoo.efi                         
  Plymouth theme:             fade-in                 
  Boot-time keymap:           jp                                  
  Init system:                OpenRC

* Please choose an option:
1) Set EFI system partition  6) Set boot-time keymap
2) Set LUKS root partition   7) Set init system
3) Set LUKS key options      8) Exit without saving
4) Set EFI boot file path    9) Save and exit
5) Set boot splash options
Your choice: press 5 then Enter
* Current boot splash settings:
* Using Plymouth on boot, with theme 'fade-in'
* Please choose your desired boot splash setting (or GO BACK):
1) Use textual boot (no Plymouth)
2) Use Plymouth graphical boot splash ('fade-in')
3) GO BACK
Your choice: press 1 then Enter
* New boot splash settings:
* Using textual boot (no Plymouth)

* Current configuration (from /etc/buildkernel.conf - MODIFIED):

  EFI system partition UUID:  2498f874-ad8f-484e-8aba-81ac1c9665b6
  LUKS root partition UUID:   8111286a-d24e-4ba2-b6af-d0650fab4130
  GPG keyfile partition UUID: DEFAULT (=EFI system partition UUID)
  GPG keyfile (for LUKS):     luks-key.gpg                        
  EFI boot directory:         /EFI/Boot                           
  EFI boot file:              gentoo.efi                         
  Plymouth theme:             NONE (textual boot)                 
  Boot-time keymap:           jp                                  
  Init system:                OpenRC

* Please choose an option:
1) Set EFI system partition  6) Set boot-time keymap
2) Set LUKS root partition   7) Set init system
3) Set LUKS key options      8) Exit without saving
4) Set EFI boot file path    9) Save and exit
5) Set boot splash options
Your choice: press 9 then Enter

* Configuration saved to /etc/buildkernel.conf.
* Be sure to run buildkernel, to rebuild the kernel with the new
* settings, before rebooting.
... significant amounts of output suppressed in the above ...

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

koneko ~ #buildkernel

Once the build completes, reboot:

koneko ~ #reboot

and you should be back to a textual boot (where you of course need to enter the LUKS keyfile gpg 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).

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

Notes

  1. ↑ Server Fault: "How to recover from 'Too many Authentication Failures for user root'"
  2. ↑ setfont manpage
  3. ↑ Linux Gazette: "Into the Mist: How Linux Console Fonts Work"
  4. ↑ Kuhn, Marcus. "UTF-8 and Unicode FAQ for Unix/Linux"
  5. ↑ cron daemon manpage
  6. ↑ updatedb manpage
  7. ↑ logrotate manpage
  8. ↑ mkfs.vfat manpage
  9. ↑ lsusb manpage
  10. ↑ hwinfo manpage
  11. ↑ Gentoo Forums: "eix colors changed"
  12. ↑ Information Security Stack Exchange: "Ways to sign gpg public key so it is trusted?"
  13. ↑ Gentoo Archives: gentoo-dev: "newsitem: openrc-0.28 mounts efivars read only"
< Previous Home Next >
Retrieved from "https://wiki.gentoo.org/index.php?title=User:Sakaki/Sakaki%27s_EFI_Install_Guide/Completing_OpenRC_Configuration_and_Installing_Necessary_Tools&oldid=1031136"