User:Sakaki/Sakaki's EFI Install Guide/Final Configuration Steps under OpenRC

Currently, your target system is using a kernel configuration largely based on that shipped with the Gentoo minimal installation image (with some necessary changes imposed by ). Since this configuration is (by design!) lightweight, it leaves many options disabled (including many device drivers). As a result, at this point in the installation a number of features that may be present on your machine (such as Bluetooth, WiFi, touchscreen etc.) may not yet be usable.

In this (penultimate) chapter, we'll address that, by enabling the relevant configuration options and recompiling the kernel (using the tool's   option).

Unfortunately, it's impossible to be precise about the exact options you'll need to enable, as these vary from machine to machine. Nevertheless, we'll cover a number of the most commonly encountered requirements (and by way of example, provide explicit instructions for WiFi, Bluetooth, touchscreen, audio, and integrated card reader on the CF-AX3).

This section of the tutorial has no precise analogue in the Gentoo manual, although elements of it are reflected in Chapter 7. You may also find it useful to refer to the "Gentoo Kernel Configuration Guide" on the wiki.

We will also address some additional miscellaneous issues at the end of this chapter, namely:
 * pruning your kernel image (by removing unused modules and firmware files);
 * getting suspend and hibernate working properly;
 * setting the system default interpreter; and
 * disabling (as we no longer need it).

Let's get started!

General Approach
The general approach when looking to enable a feature which is physically supported on your machine (for example, Bluetooth), is as follows:
 * Obviously, check whether the feature already works (it's always possible that your current kernel already has the necessary options enabled or modularized). If it does, great, you're done!
 * Otherwise, ensure your boot USB key is inserted, then invoke (as )  in a terminal (which will run the   tool).
 * Collect as much information as possible about the physical device (vendor name, model name etc.), using tools such as, and  (in a separate terminal window).
 * If the device description should match one given in the specific CF-AX3 instructions below, implement the given kernel configuration shorthand fragment (using the  interface).
 * Otherwise, search (still via the interface; see the tutorial earlier) for a suitable option, and then enable (or modularize) it (and any dependencies). If you can't find anything suitable this way, do a web search based on the information collected. (Unfortunately, there is no automated tool to do this for you).
 * Once you have made all desired changes, exit and save, thereby allowing  to continue and create a new kernel; and then reboot. With luck, your desired feature should now be operational.
 * If all else fails, invoke  again, try modularizing all options under the appropriate sub-menu in the   interface, then save and exit, to create a new kernel as before. If, after a reboot, the desired feature is operational, you should then be able to locate its driver using   (after which you can rerun   if you like, to turn off all other unneeded items and recompile). This approach (i.e., turn on pretty much everything so that something will work ^-^) is actually the one taken by many Linux distributions (such as Ubuntu) for their 'generic' kernels, so don't feel shy to try it if need be.

Tweaking your kernel configuration to enable machine features is one of the more frustrating tasks you have to do when bringing up a system under Linux. In this tutorial, I've deliberately postponed it till near the end - when you already have all the other elements of a functioning system in place.

To make the process concrete, I'll now lay out the changes necessary to enable the main features of the Panasonic CF-AX3 laptop. You will obviously need to adapt what follows depending on your particular target machine.

Specific Configuration Recipes (Using CF-AX3 as an Example)
In what follows, we will cover the following (common) features, using the Panasonic CF-AX3 as a (fairly typical) example (it is a reasonably feature-rich Ultrabook, so some of these may apply directly to your system too):
 * 1) WiFi;
 * 2) Bluetooth;
 * 3) Integrated touchscreen;
 * 4) Integrated webcam;
 * 5) Audio;
 * 6) Integrated (SD etc.) card reader;
 * 7) LCD screen backlight.

To reiterate, what follows is simply an example, for a particular PC (the CF-AX3). Where necessary, follow the steps above to set the necessary options for your particular choice of target machine.

Preliminaries
Ensure your boot USB key is inserted in the target machine, and then (at the terminal within the GNOME session that we opened earlier), issue:

to create a 'last known good' backup of the current kernel (and configuration) on the boot USB key. Although does create a backup of the previous version when it is run, that backup is not persistent, and will be overwritten the next time buildkernel is executed. Keeping a (timestamped) backup via  ensures that there's no risk we run  twice between reboots, thereby losing our reference point.

Next, issue:

Because you have not specified  here, but you have specified , the process will run through by itself (assuming no errors) to the point where you can modify the kernel configuration using the standard -based   editor GUI. You can now use that interface to enable specific features as specified in the kernel configuration shorthand 'recipes' given below.

Now, because it will be useful to have a second terminal available (for work etc.), open one now within GNOME. Click in the current terminal window (the one showing the  interface, then press  to spawn a new one. In this fresh window, log in as root:

The password required here is the one you set up earlier in the tutorial (and have used when -ing in previously).

WiFi
The CF-AX3 has integrated WiFi, based on an Intel 7260 device. To find out which network controllers you have on your machine, issue the following in the second terminal (the one not displaying the interface):

and observe the output.

In the case of the CF-AX3, this returns:

(your machine will most likely differ).

On the CF-AX3, the built-in Ethernet adaptor is (obviously!) already working under the current kernel configuration, but the Intel 7260 wireless card is not.

Now, while the firmware for this 7260 is already included in (which we installed earlier), using it requires MVM firmware support (which, at the time of writing, the minimal-install kernel configuration has disabled).

Set the following options (within ) to rectify this, and thereby activate WiFi:

Incidentally, the 7260 device also supports WiMAX, but as of the time of writing, the ebuilds for do not, so I have not detailed its activation here.

Bluetooth
Like many modern notebooks, the CF-AX3 has an integrated Bluetooth modem. To see information about your system's Bluetooth hardware, issue in the second terminal (the one not displaying the interface):

To enable it on the CF-AX3, set the following options (this will work for many other machines too):

You must now ensure that the Bluetooth service will start on boot. To do so, issue:

Touchscreen
As is increasingly common, the CF-AX3 has a touchscreen (an eGalaxTouch device in this case). You can generally find out more information about your touchscreen (and touchpad, if present, although this is likely already supported at this point in the install), by issuing in the second terminal (the one not displaying the interface):

To enable the eGalaxTouch device (this will also work for many other touchscreen panels), set the following options:

Webcam
The CF-AX3 has an integrated webcam (a common feature on many laptops and netbooks). You can find out more information about your machine's webcam by issuing in the second terminal (the one not displaying the interface):

To enable the webcam on the CF-AX3 (this will work for many modern machines, as many webcams are UVC devices), set the following options:

Audio
The CF-AX3 has an integrated Intel HD audio device, accessed on the PCI bus. You can find out more information about your machine's soundcard by issuing in the second terminal (the one not displaying the interface):

As configured, sound works 'out of the box' for the CF-AX3, but the Wikipedia:PulseAudio sound server complains about lack of high resolution timer support, and insufficiently large buffers. To address these problems on the CF-AX3, set the following options

Card Reader
The CF-AX3 has an integrated SD/MMC card reader. You can find out more information about your machine's reader by issuing in the second terminal (the one not displaying the interface):

Although the necessary kernel options ( and ) for this card are modularized in the minimal install kernel, there is a bug impacting the CF-AX3 (and many other machines) which prevents correct initialization when a card is inserted. To fix this, still in the second terminal, issue:

Others
There are a couple of other devices on the CF-AX3 which I have not dealt with here:
 * The CF-AX3 has an i7 processor with Intel's Management Engine; if you really want access to this scarily-out-of-band coprocessor, enable the setting in the kernel configuration.
 * It also has a number of integrated sensors (geomagnetic, gyroscopic, acceleration etc.); however, these are not generally supported by Linux applications at the moment, so I haven't detailed their setup here.

Of course, as mentioned earlier, your particular target platform will have its own set of devices that may well not have been mentioned here (for example, MemoryStick readers, digital TV receivers etc.), and you should obviously adapt your kernel configuration accordingly.

Lastly, if you find that your early boot splash is being interrupted with the error message, then you should ensure that only the KVM option (Intel or AMD) appropriate to your processor is set in the configuration. The relevant options are and.

Finishing Up
When satisfied with your configuration, exit, saving changes. Once you have done so, will automatically create a new kernel with the newly created configuration, sign it, and copy it over to the boot USB key. Wait for the process to complete (you get the message ). Then (leaving the boot USB key inserted) restart your target machine (you can do this from within GNOME, by clicking on the 'power' icon (in the top right of the screen), clicking on the 'power' button in the dropdown menu that then appears, and then clicking on the 'Restart' button in the dialog).

The machine should then power cycle (you will be cleanly logged out of GNOME first). When it restarts, as before, you will need to enter your LUKS keyfile passphrase (the one you created earlier), directly at the target machine keyboard to unlock the LUKS partition. You should then be presented with a GNOME login page (as previously). Directly at the target machine, click on your (regular) user name then, when prompted, type in the (regular user) password you set up earlier (ensure you have the correct keyboard settings, if relevant, as discussed above).

You should now be able to use all the features of your machine that you just enabled (such as WiFi etc.).

LCD Screen Backlight (Addressing the i915 Regression)
One final note. Like most laptops, the CF-AX3 has a dimmable backlight on its LCD screen. With modern kernels (3.17+) and the i915 graphics driver (as used by many Ultrabooks), you may find that you cannot change the display brightness using the standard GNOME controls. This is a regression; if it affects you, first use the process described in "Preliminaries", above to get a root terminal, then issue:

Locate the line specifying ADDITIONALKERNELCMDS. If it is currently commented out (the line starts with a character), then uncomment and edit that line so it reads:

Save and exit the editor.

Now, ensure that you have the boot USB key inserted, and issue:

to rebuild the kernel. Wait for the process to finish (you receive the message ""). Then power cycle the machine as described in "Finishing Up", above.

When you log in again to GNOME, you should find that the screen brightness controls now operate correctly.

Cleaning Up the Kernel Configuration (Optional Step)
As your current Linux kernel is largely derived from the minimal-install image configuration, it contains a lot of modularized and enabled features that are irrelevant to your machine (for example, all the specific x86 platform support drivers for vendors other than yours). While this bloat is mostly harmless, there are a few negative side effects of having features you don't need, for example:
 * the kernel image is larger (which makes boot time slightly longer) &mdash; even even where most features are modularized &mdash; since all modules are copied into the initramfs, which is then integrated into the kernel itself. This can be an important consideration if you choose to migrate your kernel into the (somewhat cramped) Windows EFI system partition (instructions for which are provided later);
 * more code must be (uselessly) compiled each time you upgrade your kernel, which costs time; and
 * more features = a larger attack surface exposed to malware.

Furthermore, to ensure that all necessary devices can be properly initialized during early boot, by default a complete copy of is included within the initramfs too (as was discussed earlier). This directory is ~300MiB uncompressed at the time of writing, and while the vast majority of its contents will have no relevance to your target machine's hardware, they certainly will swell the resulting kernel image significantly &mdash; so much so, in fact, that it becomes impossible to fit it inside a typical existing Windows EFI system partition (100MB at the time of writing).

Accordingly, you may wish to take steps to pare down the number of unnecessary modules and/or unnecessary firmware files contained within the bootable kernel image created by. If so, instructions for these (optional) steps are provided in the subsections immediately following.

Removing Unnecessary Kernel Modules from the initramfs
The safest way to remove unneeded modules from your kernel configuration is as follows:
 * 1) as root, run  ; then
 * 2) manually deslect those modules which appear to have no local relevance (working on a small section at a time for manageability);
 * 3) reboot (once the new kernel has been built); then
 * 4) test for regression (reverting or rebuilding the kernel if necessary); and
 * 5) repeat steps 1 through 4, until an acceptably small configuration is obtained.

Unfortunately, such a process can easily take a full day (or more) to complete fully.

<span id="using_localmodconfig">Fortunately, however, there is a quicker, automatic method to remove unnecessary modules: namely, the  tool, which is standard utility shipped with the kernel source code. To be fair, this is a little riskier than doing things by hand (since the utility causes any modules not currently loaded by the kernel to be purged from the configuration, which in turn can result in some (wanted) filesystem drivers, crypto modules, codepages etc. being dropped). Moreover, there are lots of 'false positive' loaded modules retained as well (e.g. ATA drivers) when you use this method, so it certainly isn't perfect. Nevertheless, it is convenient and 'one-shot' in nature, so, if you do wish to try out for yourself, proceed as follows.

<span id="open_root_gnome_term">First, if you don't have a root terminal open already in GNOME, do so now: press the, and type 'terminal', then press. A standard-issue terminal window should open. Become root:

The password required here is the one you set up earlier in the tutorial (and have used when -ing in).

<span id="make_snapshot_backup">Then in this terminal, issue:

to create a 'last known good' timestamped backup of the current kernel (and configuration) on the USB boot key (this ensures that there's no risk we lose our 'safe' version, which might otherwise happen were we to run twice in a row between test reboots).

Ensure you have any important devices plugged in (so their driver modules will be loaded). When ready, switch to the kernel directory, and ask to do its magic then return:

Finally, ensure you have the boot USB key inserted, and create a new kernel based on the stripped-down configuration:

This will allow you to review the proposed configuration for sanity in the  tool, and make any necessary changes.

When satisfied with your final configuration, exit, saving any changes. Once you have done so, will automatically create a new kernel with the newly created configuration, sign it, and copy it over to the boot USB key, as before. Once the process completes (you get the message ), you can check the new size of your kernel image, by issuing:

Obviously, your output will differ, depending upon your kernel version, the number of modules removed etc.

Then &mdash; leaving the USB key inserted &mdash; reboot, and login again, in the normal manner.

If you find, when rebooted, that some previously working facilities of your target machine have regressed, simply run (as root)  again, restore any necessary modules, and reboot once  has completed building the new kernel, repeating as necessary until your system is fully functional again.

<span id="pare_down_firmware">Removing Unnecessary Firmware from the initramfs
<span id="remove_unnecessary_firmware">With the module set reduced, we can now turn our attention to the major driver of kernel image size &mdash; the default inclusion of a complete copy of in the kernel's integral initramfs.

Fortunately, we can easily modify what is included here, through use of the  function in. Recall that creates an uncompressed working copy of the final initramfs in the  staging directory (and leaves it around on exit, for convenience of review), so we can look there for the largest firmware subdirectories, in search of candidates for pruning.

<span id="begin_firmware_slimdown">To begin, ensure the boot usb key is inserted, then open (as before) a root terminal, and issue:

Your results will most likely differ, depending on the version of installed on your target system.

Have a look through the output list, and make a note of any that are irrelevant to your system. For example, a little checking with (and  ), shows that the CF-AX3 has no peripherals from netronome, liquidio, AMD or qed (inter alia), so we obviously don't need any of those vendors' firmware to be able to boot (remember, all firmware will still be present on your root directory, under, once the boot has completed &mdash; we are only working on the initramfs here).

Now, we can't just go ahead and delete these directories from, as this staging copy will be overwritten next time we run. Instead, we need to uncomment and modify the special  hook function in. To do so, issue:

and then uncomment the lines specifying, and modify the function body, so it now reads:

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

Now, leaving the boot usb key inserted, build the kernel, and reboot to test it. Issue:

Assuming this completed successfully (you get the output ), then leave the boot USB key inserted, and reboot the system.

When it restarts, enter the passphrase and then login in the usual manner. Open a terminal, become root, and issue:

to check that there are no firmware load errors reported in the kernel's message buffer (if there are, you have probably been a bit over-aggressive with the firmware you have removed &mdash; but clearly not so aggressive that it prevented you from booting &mdash; in such a case, you can simply tweak your  and try again).

Assuming everything still appears to be functioning OK, you can then repeat the process (starting again from here) as many times as you like, removing firmware directories (and/or files) you believe to be irrelevant to system booting.

As before, you can check the final size of your kernel after each recompilation run, by using:

Obviously, your output will differ, depending upon your kernel version, the amount of pruning you have done etc. With a little effort, modern kernels can be reduced to around a 20MiB image size, and as with many things, a Pareto principle applies ^-^.

Remember, slimming your kernel image is very much an optional task, so feel free to postpone it for a rainy day (or forever if you like ^-^ !).

<span id="suspend_hibernate">Suspend and Hibernate
At this point, let's take the time to properly configure power management (suspend and hibernate), as this is a useful feature to have operational on your machine.

The default power management works well for many systems out of the box. This provides the power-management functions invoked when certain buttons are pressed on the machine. Specifically, the 'suspend' key ( on the CF-AX3) invokes the 'suspend' action (aka 'sleep'), and and the 'hibernate' key ( on the CF-AX3) invokes the 'hibernate' action (aka 'suspend to disk').

For the CF-AX3, the 'stock' configuration works perfectly for suspend (simply press and the machine will enter sleep state, with its power button light flashing slowly; slide the power button, and it will resume). However, hibernate requires a little further tweaking (it does work, but the system doesn't fully shutdown after the memory image is written to disk). To get around this, we need to request that writes the string   into, rather than   (this may be the case on your system too, but try to see if it works without making any changes first).

To achieve this, we need to add the file (which does not exist by default). If you don't have a root terminal open already in GNOME, do so now: press the, and type 'terminal', then press. A standard-issue terminal window should open. Become root:

The password required here is the one you set up earlier in the tutorial (and have used when -ing in).

Then in this terminal, issue:

Put the following text in the file:

Save and exit the editor (you can also close out the terminal if you have no further use for it).

After this, hibernate should work properly (on the CF-AX3). Press and the machine will write its memory to the LVM swap partition on the LUKS encrypted volume ( conforms the kernel command line to specify this, as noted earlier), and then automatically power off. To resume, ensure that the boot USB key is inserted, and slide the power key. Enter your LUKS password when prompted, log in to GNOME, and you should find your desktop just as you left it. As this feature uses encrypted swap, it is relatively safe to travel with the laptop hibernated in this fashion (you should unplug and carry the boot USB key separately, of course).

<span id="set_default_python">Setting the System Default Interpreter
This is a bit of an odd one, but it does seem to catch people out. Python is a widely used dynamic language. There are two major versions (2.x and 3.x), and a lot of python scripts that you find on the web use the older version. The problem is that these scripts also often start with a versionless shebang like:

On Gentoo, this will end up invoking Python 3.x (not 2.x), thereby (often) causing the script to break.

It's generally safe to set the default to refer to version 2.7 instead (since scripts that require version 3 will explicitly call it).

To do so, open a root terminal in GNOME (if you don't already have one open): press the, and type 'terminal', then press. A standard-issue terminal window should open. Become root:

The password required here is the one you set up earlier in the tutorial (and have used when -ing in).

Then in this terminal, issue:

Your output may very somewhat from the above, but if the top line is not the '2.7' version (it is in the above), set it as the default:

That's it!

<span id="disabling_sshd">Disabling
Up until now, you've been running (the secure shell daemon) on your target machine, to allow for simpler configuration via a helper PC. This is no longer required, and running such a service can present security risks. Unless you have good reason to keep it, stop now (and ensure it does not restart again on boot).

To do so, open a root terminal in GNOME (if you don't already have one open): press the, and type 'terminal', then press. A standard-issue terminal window should open. Become root:

The password required here is the one you set up earlier in the tutorial (and have used when -ing in).

Then in this terminal, issue:

<span id="next_steps">Next Steps
Once you have worked through the above points to your satisfaction, congratulations - you now have a fully functioning dual-boot machine! We'll now cover a few quick points about day-to-day maintenance, cleanup, and other software you might like to install. Click here to go to the next (and final) chapter, "Using Your New Gentoo System under OpenRC".