User:Sakaki/Sakaki's EFI Install Guide/Configuring systemd 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. Re-establishing networking, and setting up an ssh session from the helper PC;
2. Setting up systemd 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!

Important
This chapter is only for those users who decided earlier to target systemd init, rather than OpenRC. It is part of the 'alternative track' set of chapters. If you are here by mistake, click here to go to the default (OpenRC) version of this page.

Note
In what follows, you may also find it useful to refer to Saikat Basak's "systemd on Gentoo" tutorial and of course the Gentoo wiki page on systemd.

Re-establishing Networking and ssh

Our first order of business is to get back our network connection, then sshd, so we can log in remotely, and use the facilities of the helper machine to complete the install.

To bring up your network interface, issue (directly at the keyboard of the target PC):

localhost ~ #ifconfig enp0s25 up

Note
Substitute the interface name you wrote down before rebooting for enp0s25 in the above (this will start with wl, not en, if using WiFi for the install).

Tip
If you have forgotten to write down the name, you can see all available (wired) Ethernet adaptors using the command:

localhost ~ #ifconfig -a

This command does not show available wireless adaptors.

Next, if you are performing this install over WiFi, we need to ensure that wpa_supplicant can be started by dhcpcd (NB: if using wired Ethernet for the install, you should skip the following commands). Issue:

localhost ~ #mv -v /etc/wpa.conf /etc/wpa_supplicant/wpa_supplicant.conf

Note
The /etc/wpa.conf file was created earlier.

Note
We will delete this file later, once net-misc/networkmanager takes over (with GNOME).

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

(chroot) livecd / #if ! [ -s /lib/dhcpcd/dhcpcd-hooks/10-wpa_supplicant ]; then cp -vf /usr/share/dhcpcd/hooks/10-wpa_supplicant /lib/dhcpcd/dhcpcd-hooks/; fi

Now we need to ensure that the DHCP service is started (by systemd), both immediately, and also automatically whenever the system starts up. We use the systemctl command to achieve this. Issue:

localhost ~ #systemctl enable dhcpcd

localhost ~ #systemctl start dhcpcd

Note
You no longer need to add a .service tag on when using systemctl (so a simple dhcpcd will suffice, rather than dhcpcd.service).

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

Wait for a minute or so, and then check to see that you have been allocated an IP address:

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

Note
If using WiFi for the install, and you do not receive a valid IP address via the above procedure, then it is possible that dhcpcd has failed to invoke wpa_supplicant properly. In this case, you can try starting it manually on the wireless interface in question. To do so, issue:

localhost ~ #systemctl start wpa_supplicant@wlp2s0

Substitute the wireless network interface name you wrote down previously for wlp2s0 in the above command. Wait a minute or so, and then examine the output of ifconfig again, to see if you are now connected.
If you do need to manually start wpa_supplicant in this manner, you'll need to remember to do so each time during the rest of the tutorial after a reboot into Linux is called for, up until the point where the NetworkManager service is configured. Most systems should not experience this issue, however.

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.

Right, we can now start the ssh daemon (and ensure it auto-starts on boot). Issue:

localhost ~ #systemctl enable sshd

localhost ~ #systemctl start sshd

Warning
As configured, sshd allows some rather insecure things, such as remote log-in as root. While this is useful at the moment (and relatively benign given the machine is on a subnet, presumably behind a firewall), do consider editing the /etc/ssh/sshd_config file once all configuration is complete, to disallow this. You should also consider moving to public key authentication for ssh login, once everything else is in place.

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 you started sshd for the first time, above (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.

Check the (relevant) key fingerprint 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 Up systemd Configuration Options

Next, and before we invoke screen again, we'll want to set up our locale (and a number of other systemd 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 ~ #hostnamectl set-hostname koneko

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

Note
By default, this sets all three of your static, transient and pretty hostnames. You can find out more about what this means via the hostnamectl manpage.

Check that it worked:

localhost ~ #hostnamectl status

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.

Now we need to inform systemd of our choice. Issue:

koneko ~ #localectl set-locale LANG="${LANG}" LC_COLLATE="C"

Note
We leave the collation order as "C" here, per the Gentoo wiki recommendation. If you like, you can set other specific variables here also to partially override the LANG variable; see the localectl manpage for more details.

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

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

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

koneko ~ #localectl list-keymaps | grep -i jp

Note
Replace jp in the above command with a string appropriate to your keyboard, such as us, uk etc.

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

koneko ~ #localectl set-keymap jp106

Note
Substitute for jp106 in the above with a value appropriate for your own keyboard, taken from the list returned by the localectl list-keymaps command. For example, a standard US layout would use us here; a standard UK layout, uk.

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

koneko ~ #loadkeys jp106

Note
Substitute the value you used in localectl set-keymap for jp106 in the above.

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

koneko ~ #localectl status

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

koneko ~ #localectl --no-convert set-x11-keymap jp,gb

Note
The --no-convert option prevents localectl from from attempting to loop back and infer a console keymap from the X11 ones specified.

Note
This particular setting is specific to my system and is included here for interest only; you will most likely not need to explicitly augment the X11 keymap in this manner, and so can safely ignore this command.

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

This involves setting the FONT and FONT_MAP variables in the /etc/vconsole.conf file (which is read by the systemd vconsole-setup service). 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. Issue:

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

And append the following lines to the file:

FILE /etc/vconsole.confSetting the console font (example only, adjust as needed)

FONT=lat1-16
FONT_MAP=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 FONT and FONT_MAP 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 FONT line in /etc/vconsole.conf (by placing a # symbol at the start), then rebooting.

Note
You can also specify FONT_UNIMAP in the /etc/vconsole.conf file, but that's generally unnecessary, since most fonts include a Unicode mapping table anyway.

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

Finally, whether or not you modified /etc/vconsole.conf above, re-generate your environment, and check all looks good with the locale settings:

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

koneko ~ #localectl status

Post-Boot Script

At this point, it's useful to setup an /etc/postboot script (and invoking systemd service) that will be run each time the main boot process has concluded. We will use this to address three minor glitches:

1. Often, the systemd-vconsole-setup service (which reads the /etc/vconsole.conf file that we set up above) can end up being run too early, meaning that these settings get applied, but are then overridden.
2. The virtual console does not always fully clear the frame buffer properly (particularly, when taking over from plymouth), meaning that you sometimes get grey lines at the top or bottom of the console screen.
3. (Optional) Depending on the version of gdm (which we'll set up shortly), plymouthd may remain running in the background (even though plymouth-quit-wait.service has completed). This can consume CPU and cause screen glitches.

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

Instead, we'll create a new systemd service, which we'll instruct to run as part of the multi-user.target (boot synchronization point, similar to runlevel 3), and specify that it should run after the plymouth-quit-wait.service. Per the Gentoo wiki, we'll place the systemd service file in /etc/systemd/system.

Issue:

koneko ~ #nano -w /etc/systemd/system/postboot-script.service

Then place the following text in the file:

FILE /etc/systemd/system/postboot-script.serviceCreating a service to run a script after boot completed

[Unit]
Description=Execute /etc/postboot Script
After=plymouth-quit-wait.service

[Service]
Type=oneshot
ExecStart=/etc/postboot
RemainAfterExit=yes

[Install]
WantedBy=multi-user.target

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

koneko ~ #nano -w /etc/postboot

and place the following text in the file:

FILE /etc/postbootA 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
# ...and then re-run the vconsole setup (it may have run too early)
systemctl restart systemd-vconsole-setup

# ensure plymouth really has stopped (uncomment only if you have problems with this)
#if pgrep "plymouthd" > /dev/null 2>&1; then
#    plymouth quit
#fi

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/postboot

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

koneko ~ #systemctl enable postboot-script

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

Time and Date

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

koneko ~ #timedatectl status | grep -i time

If the time is not correct, issue:

koneko ~ #timedatectl set-time "YYYY-MM-DD hh:mm:ss"

to set it.

Note
Obviously, substitute for YYYY-MM-DD hh:mm:ss with the actual, numerical date and time. For example, to set the date/time to 5:12pm on February 9th 2014 (local time), you would issue:

koneko ~ #timedatectl set-time "2014-02-09 17:12:00"

Note
To reiterate, systemd should have automatically picked up this setting, so most users will find they do not need to execute the above timedatectl set-time <...> command.

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

koneko ~ #timedatectl set-timezone "Europe/London"

Note
Substitute your own timezone for Europe/London in the above command. This should be the same value as that you chose when setting the timezone earlier. You can see a full list of available timezones by issuing:

koneko ~ #timedatectl list-timezones

We also need to tell systemd to save the time in UTC format to the system's real-time-clock (RTC). Issue:

koneko ~ #timedatectl set-local-rtc 0

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 ~ #timedatectl status | grep -i time

and check that the reported Universal time and RTC time 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.

Lastly, 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.

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 as well as systemd's somewhat controversial (and not entirely crash-resistant) binary log format. 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.

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

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 ~ #systemctl enable syslog-ng@default

(1) koneko ~ #systemctl start syslog-ng@default

Note
You can omit the installation of syslog-ng if you are comfortable with the binary journald logs. Or, select a different logger - the choice is yours.

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 ~ #systemctl enable cronie

(1) koneko ~ #systemctl start cronie

Note
Per the Gentoo Handbook, installing a cron daemon is optional, but highly recommended, as many other system tools rely on it. 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) 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.

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), 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. The hwinfo package provides (inter alia) the eponymous hwinfo tool, which can be used to generate a system overview log.

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:

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

Performing a Precautionary Reboot without plymouth

To be cautious, we will now reboot the system to check that our changes to the systemd 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 ~ #systemctl reboot

Note
This is the preferred way to reboot a systemd machine from the command line.

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 systemd-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 ~ #systemctl --failed

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

Note
On certain versions of systemd, you may be notified that the plymouth-start.service unit failed during boot. As we have not yet enabled plymouth using buildkernel, this is to be expected, and the error may be ignored at this point.

Note
If installing over WiFi, and you had to manually restart wpa_supplicant earlier, then it's likely you'll see one or more failed units relating to this problem in the output from the above command. These can safely be ignored.

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

* 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:                systemd

* 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:                systemd

* 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
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 ~ #systemctl 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
If the plymouth graphical screen remains 'hanging around' (even though the boot appears to have completed, so you can e.g., log in via ssh), try in the first instance uncommenting the last three lines of the /etc/postboot script which you set up earlier (you can do this via ssh), after which you can try rebooting again.
For avoidance of doubt, this issue will not affect most users: allow sufficient time for the boot to complete, before assuming you are affected by it.

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

* 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:                systemd

* 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 ~ #systemctl 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".

Notes

< Previous

Home

Next >