Difference between pages "Funtoo:Keychain" and "UEFI Install Guide"

From Funtoo
(Difference between pages)
Jump to navigation Jump to search
 
 
Line 1: Line 1:
{{Article
{{Note|This material has been integrated into the main [[Funtoo Linux Installation]] guide, so please look at that guide if you are installing Funtoo Linux. Editors: this page still contains some good content that we might want to move over there.}}
|Subtitle=Official Project Page
|Author=Drobbins
}}
<tt>Keychain</tt> helps you to manage SSH and GPG keys in a convenient and secure manner. It acts as a frontend to <tt>ssh-agent</tt> and <tt>ssh-add</tt>, but allows you to easily have one long running <tt>ssh-agent</tt> process per system, rather than the norm of one <tt>ssh-agent</tt> per login session.


This dramatically reduces the number of times you need to enter your passphrase. With <tt>keychain</tt>, you only need to enter a passphrase once every time your local machine is rebooted. <tt>Keychain</tt> also makes it easy for remote cron jobs to securely &quot;hook in&quot; to a long running <tt>ssh-agent</tt> process, allowing your scripts to take advantage of key-based logins.
This tutorial will show you how to install Funtoo on a UEFI system. UEFI, also known as the [[Wikipedia:Unified Extensible Firmware Interface|Unified Extensible Firmware Interface]], is a new firmware interface that is used on some newer computers as a replacement for the traditional PC BIOS. It has an integrated boot loader, so setting up booting is different.  


== Download and Resources ==
This tutorial is meant to be an "overlay" over the Regular Funtoo Installation. Follow the normal installation and only follow steps in this tutorial when dealing with partitioning and configuring the boot loader (GRUB). All steps are otherwise identical to the regular installation process.


The latest release of keychain is version <tt>2.7.2_beta1</tt>, and was released on July 7, 2014. The current version of keychain supports <tt>gpg-agent</tt> as well as <tt>ssh-agent</tt>.
== What Are We Doing? ==


Keychain is compatible with many operating systems, including <tt>AIX</tt>, <tt>*BSD</tt>, <tt>Cygwin</tt>, <tt>MacOS X</tt>, <tt>Linux</tt>, <tt>HP/UX</tt>, <tt>Tru64 UNIX</tt>, <tt>IRIX</tt>, <tt>Solaris</tt> and <tt>GNU Hurd</tt>.
This guide will show you how to set up your UEFI system to load the GRUB boot loader, which will then load your Funtoo Linux kernel and initramfs. This is the "UEFI + GRUB" method as described on the [[Boot Methods]] page.


=== Download ===
== First Steps ==


* ''Release Archive''
To install Funtoo Linux on a UEFI system, first you need to boot SysRescueCD in UEFI mode. To do this, enable UEFI in your BIOS, and if necessary disable legacy booting. After some fiddling, you should be able to boot SysRescueCD and get a black and white text menu instead of the traditional aqua/cyan-colored menu. The black and white menu indicates that you booted SysRescueCD in UEFI mode. Once you've accomplished this, you're ready to continue with your Funtoo Linux installation and partition your drive. See below for details.
** [http://www.funtoo.org/distfiles/keychain/keychain-2.7.2_beta1.tar.bz2 keychain 2.7.2_beta1]
** [http://www.funtoo.org/distfiles/keychain/keychain-2.7.1.tar.bz2 keychain 2.7.1]


* ''Apple MacOS X Packages''
{{fancynote|If the <tt>/sys/firmware/efi</tt> directory exists, then you have successfully booted in EFI mode and will be able to configure your Funtoo system to boot in EFI mode. If the directory doesn't exist, fix this first. It is a requirement for setting up EFI booting.}}
** [http://www.funtoo.org/distfiles/keychain/keychain-2.7.1-macosx.tar.gz keychain 2.7.1 MacOS X package]


Keychain development sources can be found in the [http://www.github.com/funtoo/keychain keychain git repository]. Please use the [https://bugs.funtoo.org Funtoo Linux bug tracker] and [irc://irc.freenode.net/funtoo #funtoo irc channel] for keychain support questions as well as bug reports.
== Partitioning ==


=== Project History ===
To set up your partitions for UEFI booting, you will create a ~500MB FAT32 partition on <tt>/dev/sda1</tt>, and set it to type <tt>EF00</tt> using <tt>gdisk</tt>.


Daniel Robbins originally wrote <tt>keychain</tt> 1.0 through 2.0.3. 1.0 was written around June 2001, and 2.0.3 was released in late August, 2002.
<console>
 
Command: ##i##n ↵
After 2.0.3, <tt>keychain</tt> was maintained by various Gentoo developers, including Seth Chandler, Mike Frysinger and Robin H. Johnson, through July 3, 2003.
Partition Number: ##i##1 ↵
 
First sector: ##i##↵
On April 21, 2004, Aron Griffis committed a major rewrite of <tt>keychain</tt> which was released as 2.2.0. Aron continued to actively maintain and improve <tt>keychain</tt> through October 2006 and the <tt>keychain</tt> 2.6.8 release. He also made a few commits after that date, up through mid-July, 2007. At this point, <tt>keychain</tt> had reached a point of maturity.
Last sector: ##i##+500M ↵
 
Hex Code: ##i##EF00
In mid-July, 2009, Daniel Robbins migrated Aron's mercurial repository to git and set up a new project page on funtoo.org, and made a few bug fix commits to the git repo that had been collecting in [http://bugs.gentoo.org bugs.gentoo.org]. Daniel continues to maintain <tt>keychain</tt> and supporting documentation on funtoo.org, and plans to make regular maintenance releases of <tt>keychain</tt> as needed.
</console>
 
== Quick Setup ==


=== Linux ===
This partition will serve as your Funtoo <tt>/boot</tt> filesystem as well as the partition that the UEFI firmware can read to load GRUB. Then you will set up swap on <tt>/dev/sda2</tt> and your root filesystem on <tt>/dev/sda3</tt>. To create the FAT32 filesystem, type:


To install under Gentoo or Funtoo Linux, type
<console>
<console>
###i## emerge keychain
# ##i##mkfs.vfat -F 32 /dev/sda1
</console>
</console>


For other Linux distributions, use your distribution's package manager, or download and install using the source tarball above. Then generate RSA/DSA keys if necessary. The quick install docs assume you have a DSA key pair named <tt>id_dsa</tt> and <tt>id_dsa.pub</tt> in your <tt>~/.ssh/</tt> directory. Add the following to your <tt>~/.bash_profile</tt>:
Your <tt>/etc/fstab</tt> entry for this filesystem will also differ, and will look like this:


{{file|name=~/.bash_profile|body=
<pre>
eval `keychain --eval --agents ssh id_rsa`
/dev/sda1 /boot vfat noatime 1 2
}}
</pre>


If you want to take advantage of GPG functionality, ensure that GNU Privacy Guard is installed and omit the <tt>--agents ssh</tt> option above.
== Kernel ==


=== Apple MacOS X ===
=== VFAT ===


To install under MacOS X, install the MacOS X package for keychain. Assuming you have an <tt>id_dsa</tt> and <tt>id_dsa.pub</tt> key pair in your <tt>~/.ssh/</tt> directory, add the following to your <tt>~/.bash_profile</tt>:
Make sure you add VFAT support to your kernel if you are building it manually.


{{file|name=~/.bash_profile|body=
=== EFI Framebuffer ===
eval `keychain --eval --agents ssh --inherit any id_dsa`
}}


{{Fancynote|The <tt>--inherit any</tt> option above causes keychain to inherit any ssh key passphrases stored in your Apple MacOS Keychain. If you would prefer for this to not happen, then this option can be omitted.}}
If you have the following option enabled in your kernel, then uvesafb and efifb will not be able to detect the framebuffer:


== Background ==
{{kernelop|title=Bus options (PCI etc.)|desc=
    [*] Mark VGA/VBE/EFI FB as generic system framebuffer (NEW)
}}


You're probably familiar with <tt>ssh</tt>, which has become a secure replacement for the venerable <tt>telnet</tt> and <tt>rsh</tt> commands.
If you have that option enabled, ''you must also enable'':


Typically, when one uses <tt>ssh</tt> to connect to a remote system, one supplies a secret passphrase to <tt>ssh</tt>, which is then passed in encrypted form over the network to the remote server. This passphrase is used by the remote <tt>sshd</tt> server to determine if you should be granted access to the system.
{{kernelop|title=Device Drivers,Graphics support,Frame buffer Devices|desc=
    [*]  Simple framebuffer support
}}


However, OpenSSH and nearly all other SSH clients and servers have the ability to perform another type of authentication, called asymmetric public key authentication, using the RSA or DSA authentication algorithms. They are very useful, but can also be complicated to use. <tt>keychain</tt> has been designed to make it easy to take advantage of the benefits of RSA and DSA authentication.
This is the preferred method of using the EFI framebuffer, the efifb and uvesafb drivers will be used as a fallback if the above is not compatible.
=== Grub method ===


== Generating a Key Pair ==
==== Unmask Grub 2.02_beta2 ====


To use RSA and DSA authentication, first you use a program called <tt>ssh-keygen</tt> (included with OpenSSH) to generate a ''key pair'' -- two small files. One of the files is the ''public key''. The other small file contains the ''private key''. <tt>ssh-keygen</tt> will ask you for a passphrase, and this passphrase will be used to encrypt your private key. You will need to supply this passphrase to use your private key. If you wanted to generate a DSA key pair, you would do this:
Unmask the latest version of GRUB by placing this in your <code>/etc/portage/package.unmask</code>:


<console># ##i##ssh-keygen -t dsa
<pre>
Generating public/private dsa key pair.</console>
sys-boot/grub
You would then be prompted for a location to store your key pair. If you do not have one currently stored in <tt>~/.ssh</tt>, it is fine to accept the default location:
</pre>


<console>Enter file in which to save the key (/root/.ssh/id_dsa): </console>
The 2.00 version of GRUB has known issues with UEFI booting. Using 2.02 is essential for having this boot method work reliably.
Then, you are prompted for a passphrase. This passphrase is used to encrypt the ''private key'' on disk, so even if it is stolen, it will be difficult for someone else to use it to successfully authenticate as you with any accounts that have been configured to recognize your public key.


Note that conversely, if you '''do not''' provide a passphrase for your private key file, then your private key file '''will not''' be encrypted. This means that if someone steals your private key file, ''they will have the full ability to authenticate with any remote accounts that are set up with your public key.''
==== Emerging GRUB ====


Below, I have supplied a passphrase so that my private key file will be encrypted on disk:
You will still use GRUB as a boot loader, but before emerging grub, you will need to enable EFI booting. To do this,
add the following line to <tt>/etc/portage/make.conf</tt>:


<console>Enter passphrase (empty for no passphrase): ##i#########
<pre>
Enter same passphrase again: ##i#########
GRUB_PLATFORMS="efi-64"
Your identification has been saved in /var/tmp/id_dsa.
</pre>
Your public key has been saved in /var/tmp/id_dsa.pub.
The key fingerprint is:
5c:13:ff:46:7d:b3:bf:0e:37:1e:5e:8c:7b:a3:88:f4 root@devbox-ve
The key's randomart image is:
+--[ DSA 1024]----+
|          .      |
|          o  . |
|          o . ..o|
|      . . . o  +|
|        S    o. |
|            . o.|
|        .  ..++|
|        . o . =o*|
|        . E .+*.|
+-----------------+</console>


== Setting up Authentication ==
Then, <tt>emerge grub</tt>. You will notice <tt>efibootmgr</tt> getting pulled in as a dependency. This is expected and good.


Here's how you use these files to authenticate with a remote server. On the remote server, you would append the contents of your ''public key'' to the <tt>~.ssh/authorized_keys</tt> file, if such a file exists. If it doesn't exist, you can simply create a new <tt>authorized_keys</tt> file in the remote account's <tt>~/.ssh</tt> directory that contains the contents of your local <tt>id_dsa.pub</tt> file.
==== Installing GRUB ====


Then, if you weren't going to use <tt>keychain</tt>, you'd perform the following steps. On your local client, you would start a program called <tt>ssh-agent</tt>, which runs in the background. Then you would use a program called <tt>ssh-add</tt> to tell <tt>ssh-agent</tt> about your secret private key. Then, if you've set up your environment properly, the next time you run <tt>ssh</tt>, it will find <tt>ssh-agent</tt> running, grab the private key that you added to <tt>ssh-agent</tt> using <tt>ssh-add</tt>, and use this key to authenticate with the remote server.
Now, for the magic of getting everything in place for booting. You should copy your kernel and initramfs (if you have one -- you will if you are following the default install) to <tt>/boot</tt>. GRUB will boot those. But how do we get UEFI to boot GRUB? Well, we need to run the following command:


Again, the steps in the previous paragraph is what you'd do if <tt>keychain</tt> wasn't around to help. If you are using <tt>keychain</tt>, and I hope you are, you would simply add the following line to your <tt>~/.bash_profile</tt> or if a regular user to<tt>~/.bashrc</tt> :
<console>
# ##i##grub-install --target=x86_64-efi --efi-directory=/boot --bootloader-id="Funtoo Linux [GRUB]" --recheck /dev/sda
</console>
This command will simply install all the stuff to <tt>/boot/EFI</tt> and <tt>/boot/grub</tt> that your system needs to boot. In particular, the <tt>/boot/EFI/grub/grubx64.efi</tt> file will be created. This is the GRUB boot image that UEFI will load and start.


{{file|name=~/.bash_profile|body=
A more detailed explanation of the flags used in the above command:
eval `keychain --eval id_dsa`
* <code>--target=x86_64-efi</code>: Tells GRUB that we want to install it in a way that allows it to boot in UEFI
}}
* <code>--efi-directory=/boot</code>: All GRUB UEFI files will be installed in ''/boot''
* <code>--bootloader-id="Funtoo Linux [GRUB]"</code>: This flag is not necessary for GRUB to boot. However, it allows you to change the text of the boot option in the UEFI BIOS. The stuff in the quotes can be set to anything that you would like.  
* <code>--recheck</code>: If a device map already exists on the disk or partition that GRUB is being installed on, it will be removed.
* <code>/dev/sda</code>:The device that we are installing GRUB on.


The next time you log in or source your <tt>~/.bash_profile</tt> or if you use <tt>~/.bashrc</tt>, <tt>keychain</tt> will start, start <tt>ssh-agent</tt> for you if it has not yet been started, use <tt>ssh-add</tt> to add your <tt>id_dsa</tt> private key file to <tt>ssh-agent</tt>, and set up your shell environment so that <tt>ssh</tt> will be able to find <tt>ssh-agent</tt>. If <tt>ssh-agent</tt> is already running, <tt>keychain</tt> will ensure that your <tt>id_dsa</tt> private key has been added to <tt>ssh-agent</tt> and then set up your environment so that <tt>ssh</tt> can find the already-running <tt>ssh-agent</tt>. It will look something like this:
==== Configuring GRUB ====


Note that when <tt>keychain</tt> runs for the first time after your local system has booted, you will be prompted for a passphrase for your private key file if it is encrypted. But here's the nice thing about using <tt>keychain</tt> -- even if you are using an encrypted private key file, you will only need to enter your passphrase when your system first boots (or in the case of a server, when you first log in.) After that, <tt>ssh-agent</tt> is already running and has your decrypted private key cached in memory. So if you open a new shell, you will see something like this:
OK, now UEFI has the GRUB image it needs to boot. But we still need to configure GRUB itself so it finds and boots your kernel and initramfs. This is done by performing the following steps. Since boot-update doesn't yet support UEFI, we will use boot-update, but then edit our <code>/boot/grub/grub.cfg</code> to support UEFI booting.  


This means that you can now <tt>ssh</tt> to your heart's content, without supplying a passphrase.
First, you will need to edit <code>/etc/boot.conf</code>. Format this as you would if you were booting without UEFI. If you are not sure how this should look, below is an example of what it could look like if you are booting from an unencrypted ext4 partition:


You can also execute batch <tt>cron</tt> jobs and scripts that need to use <tt>ssh</tt> or <tt>scp</tt>, and they can take advantage of passwordless RSA/DSA authentication as well. To do this, you would add the following line to the top of a bash script:
{{file|name=/etc/boot.conf|desc=|body=
boot {
        generate grub
        default "Funtoo Linux"
        timeout 3
}


{{file|name=example-script.sh|body=
"Funtoo Linux" {
eval `keychain --noask --eval id_dsa` || exit 1
        kernel vmlinuz[-v]
        params += rootfstype=ext4 root=/dev/sda2
}
}}
}}


The extra <tt>--noask</tt> option tells <tt>keychain</tt> that it should not prompt for a passphrase if one is needed. Since it is not running interactively, it is better for the script to fail if the decrypted private key isn't cached in memory via <tt>ssh-agent</tt>.
After you have edited your <code>/etc/boot.conf</code> file, run <code>boot-update</code>. If you check your <code>/boot/grub/grub.cfg</code> now, you should see something like this:


== Keychain Options ==
{{file|name=/boot/grub/grub.cfg|desc=|body=
set timeout=3


=== Specifying Agents ===
  insmod part_gpt
  insmod fat
  set root=(hostdisk//dev/sda,gpt1)
  search --no-floppy --fs-uuid --set 3CFD-6884
if loadfont /grub/unifont.pf2; then
  set gfxmode=text
  insmod gfxterm
  insmod vbe
  terminal_output gfxterm
fi


In the images above, you will note that <tt>keychain</tt> starts <tt>ssh-agent</tt>, but also starts <tt>gpg-agent</tt>. Modern versions of <tt>keychain</tt> also support caching decrypted GPG keys via use of <tt>gpg-agent</tt>, and will start <tt>gpg-agent</tt> by default if it is available on your system. To avoid this behavior and only start <tt>ssh-agent</tt>, modify your <tt>~/.bash_profile</tt> as follows:
set menu_color_normal=cyan/blue
set menu_color_highlight=blue/cyan


{{file|name=~/.bash_profile|body=
menuentry "Funtoo Linux - vmlinuz-3.16.3" {
eval `keychain --agents ssh --eval id_dsa` || exit 1
  insmod part_gpt
  insmod fat
  set root=(hostdisk//dev/sda,gpt1)
  search --no-floppy --fs-uuid --set 3CFD-6884
  linux /vmlinuz-3.16.3 video=uvesafb:1920x1080-32,mtrr:3,ywrap rootfstype=ext4 root=/dev/sda2
  set gfxpayload=text
}
set default=0
}}
}}


The additional <tt>--agents ssh</tt> option tells <tt>keychain</tt> just to manage <tt>ssh-agent</tt>, and ignore <tt>gpg-agent</tt> even if it is available.
To get your <code>/boot/grub/grub.cfg</code> to support booting with UEFI, make your <code>/boot/grub/grub.cfg</code> look like this:
{{file|name=/boot/grub/grub.cfg|desc=|body=
set timeout=3


=== Clearing Keys ===
  insmod part_gpt
  insmod fat
  insmod efi_gop
  insmod efi_uga
  set root=(hostdisk//dev/sda,gpt1)
  search --no-floppy --fs-uuid --set 3CFD-6884
if loadfont /grub/unifont.pf2; then
  set gfxmode=auto
  insmod gfxterm
  insmod vbe
  terminal_output gfxterm
fi


Sometimes, it might be necessary to flush all cached keys in memory. To do this, type:
set menu_color_normal=cyan/blue
set menu_color_highlight=blue/cyan


<console># ##i##keychain --clear</console>
menuentry "Funtoo Linux - vmlinuz-3.16.3" {
Any agent(s) will continue to run.
  insmod part_gpt
 
  insmod fat
=== Improving Security ===
  set root=(hostdisk//dev/sda,gpt1)
 
  search --no-floppy --fs-uuid --set 3CFD-6884
To improve the security of <tt>keychain</tt>, some people add the <tt>--clear</tt> option to their <tt>~/.bash_profile</tt> <tt>keychain</tt> invocation. The rationale behind this is that any user logging in should be assumed to be an intruder until proven otherwise. This means that you will need to re-enter any passphrases when you log in, but cron jobs will still be able to run when you log out.
  linux /vmlinuz-3.16.3 video=uvesafb:1920x1080-32,mtrr:3,ywrap rootfstype=ext4 root=/dev/sda2
 
  set gfxpayload=keep
=== Stopping Agents ===
}
 
set default=0
If you want to stop all agents, which will also of course cause your keys/identities to be flushed from memory, you can do this as follows:
}}
 
<console># ##i##keychain -k all</console>
If you have other agents running under your user account, you can also tell <tt>keychain</tt> to just stop only the agents that <tt>keychain</tt> started:
 
<console># ##i##keychain -k mine</console>
 
=== GPG ===
 
Keychain can ask you for your GPG passphrase if you provide it the GPG key ID. To find it out:
<console>
$##i## gpg -k
pub  2048R/DEADBEEF 2012-08-16
uid                  Name (Comment) <email@host.tld>
sub  2048R/86D2FAC6 2012-08-16
</console>
 
Note the '''DEADBEEF''' above is the ID. Then, in your login script, do your usual
 
<console>
$##i## keychain --dir ~/.ssh/.keychain ~/.ssh/id_rsa DEADBEEF
$##i## source ~/.ssh/.keychain/$HOST-sh
$##i## source ~/.ssh/.keychain/$HOST-sh-gpg
</console>
 
=== Learning More ===
 
The instructions above will work on any system that uses <tt>bash</tt> as its default shell, such as most Linux systems and Mac OS X.


To learn more about the many things that <tt>keychain</tt> can do, including alternate shell support, consult the keychain man page, or type <tt>keychain --help | less</tt> for a full list of command options.
The lines that we have added and altered do the following:
* <code>insmod efi_gop</code> and <code>insmod efi_uga</code>: Both of these involve adding support for the UEFI framebuffer to GRUB.
* <code>set gfxmode=auto</code>: Instead of having the GRUB boot option screen being displayed at the smallest resolution possible, changing this to auto will make it fit the resolution of your display.


I also recommend you read my original series of articles about [http://www.openssh.com OpenSSH] that I wrote for IBM developerWorks, called <tt>OpenSSH Key Management</tt>. Please note that <tt>keychain</tt> 1.0 was released along with Part 2 of this article, which was written in 2001. <tt>keychain</tt> has changed quite a bit since then. In other words, read these articles for the conceptual and [http://www.openssh.com OpenSSH] information, but consult the <tt>keychain</tt> man page for command-line options and usage instructions :)
== Known Issues ==
*With pure UEFI boot mode, with legacy mode disabled, following error expected:  
** video driver not supported, boot hangs, hard reboot required.
*Choose UEFI first, next legacy driver. It depends on motherboard vendor and efi bios version.
**In UEFI bios choose grub option, if your succeeded with above guide, additional menu should appear in Boot Menu, otherwise it boots into EFI shell: <code>grub:NAME of you hard drive</code>
* On some systems, installing the packages that are required for UEFI booting with any gcc later than a 4.x.x release may lead to a black screen after the GRUB screen. To fix this, before you begin installing any packages on your system, emerge =gcc-4.6.4-r2 and proceed with the installation as usual. Remember to switch your compiler back to the version of gcc that came with your system after you have finished installing. To do this, use <code>gcc-config 2</code>.


* [http://www.ibm.com/developerworks/library/l-keyc.html Common Threads: OpenSSH key management, Part 1] - Understanding RSA/DSA Authentication
=== Done! ===
* [http://www.ibm.com/developerworks/library/l-keyc2/ Common Threads: OpenSSH key management, Part 2] - Introducing <tt>ssh-agent</tt> and <tt>keychain</tt>
* [http://www.ibm.com/developerworks/library/l-keyc3/ Common Threads: OpenSSH key management, Part 3] - Agent forwarding and <tt>keychain</tt> improvements


As mentioned at the top of the page, <tt>keychain</tt> development sources can be found in the [http://www.github.com/funtoo/keychain keychain git repository]. Please use the [http://groups.google.com/group/funtoo-dev funtoo-dev mailing list] and [irc://irc.freenode.net/funtoo #funtoo irc channel] for keychain support questions as well as bug reports.
Remember to follow all other steps in the regular Funtoo Install Guide. Assuming you did everything correctly, your system should now boot via UEFI! We will be adding UEFI support to boot-update soon to make this process easier.


[[Category:HOWTO]]
[[Category:HOWTO]]
[[Category:Projects]]
[[Category:First Steps]]
[[Category:Articles]]
{{ArticleFooter}}

Revision as of 18:14, January 5, 2015

   Note

This material has been integrated into the main Funtoo Linux Installation guide, so please look at that guide if you are installing Funtoo Linux. Editors: this page still contains some good content that we might want to move over there.

This tutorial will show you how to install Funtoo on a UEFI system. UEFI, also known as the Unified Extensible Firmware Interface, is a new firmware interface that is used on some newer computers as a replacement for the traditional PC BIOS. It has an integrated boot loader, so setting up booting is different.

This tutorial is meant to be an "overlay" over the Regular Funtoo Installation. Follow the normal installation and only follow steps in this tutorial when dealing with partitioning and configuring the boot loader (GRUB). All steps are otherwise identical to the regular installation process.

What Are We Doing?

This guide will show you how to set up your UEFI system to load the GRUB boot loader, which will then load your Funtoo Linux kernel and initramfs. This is the "UEFI + GRUB" method as described on the Boot Methods page.

First Steps

To install Funtoo Linux on a UEFI system, first you need to boot SysRescueCD in UEFI mode. To do this, enable UEFI in your BIOS, and if necessary disable legacy booting. After some fiddling, you should be able to boot SysRescueCD and get a black and white text menu instead of the traditional aqua/cyan-colored menu. The black and white menu indicates that you booted SysRescueCD in UEFI mode. Once you've accomplished this, you're ready to continue with your Funtoo Linux installation and partition your drive. See below for details.

   Note

If the /sys/firmware/efi directory exists, then you have successfully booted in EFI mode and will be able to configure your Funtoo system to boot in EFI mode. If the directory doesn't exist, fix this first. It is a requirement for setting up EFI booting.

Partitioning

To set up your partitions for UEFI booting, you will create a ~500MB FAT32 partition on /dev/sda1, and set it to type EF00 using gdisk. 

Command: n ↵
Partition Number: 1 ↵
First sector: ↵
Last sector: +500M ↵
Hex Code: EF00

This partition will serve as your Funtoo /boot filesystem as well as the partition that the UEFI firmware can read to load GRUB. Then you will set up swap on /dev/sda2 and your root filesystem on /dev/sda3. To create the FAT32 filesystem, type: 

root # mkfs.vfat -F 32 /dev/sda1

Your /etc/fstab entry for this filesystem will also differ, and will look like this: 

/dev/sda1		/boot		vfat		noatime	1 2

Kernel

VFAT

Make sure you add VFAT support to your kernel if you are building it manually.

EFI Framebuffer

If you have the following option enabled in your kernel, then uvesafb and efifb will not be able to detect the framebuffer:

Under Bus options (PCI etc.):

[*] Mark VGA/VBE/EFI FB as generic system framebuffer (NEW)

If you have that option enabled, you must also enable:

Under Device Drivers-->Graphics support-->Frame buffer Devices:

[*]   Simple framebuffer support

This is the preferred method of using the EFI framebuffer, the efifb and uvesafb drivers will be used as a fallback if the above is not compatible.

Grub method

Unmask Grub 2.02_beta2

Unmask the latest version of GRUB by placing this in your /etc/portage/package.unmask: 

sys-boot/grub

The 2.00 version of GRUB has known issues with UEFI booting. Using 2.02 is essential for having this boot method work reliably.

Emerging GRUB

You will still use GRUB as a boot loader, but before emerging grub, you will need to enable EFI booting. To do this, add the following line to /etc/portage/make.conf: 

GRUB_PLATFORMS="efi-64"

Then, emerge grub. You will notice efibootmgr getting pulled in as a dependency. This is expected and good.

Installing GRUB

Now, for the magic of getting everything in place for booting. You should copy your kernel and initramfs (if you have one -- you will if you are following the default install) to /boot. GRUB will boot those. But how do we get UEFI to boot GRUB? Well, we need to run the following command: 

root # grub-install --target=x86_64-efi --efi-directory=/boot --bootloader-id="Funtoo Linux [GRUB]" --recheck /dev/sda

This command will simply install all the stuff to /boot/EFI and /boot/grub that your system needs to boot. In particular, the /boot/EFI/grub/grubx64.efi file will be created. This is the GRUB boot image that UEFI will load and start.

A more detailed explanation of the flags used in the above command:

  • --target=x86_64-efi: Tells GRUB that we want to install it in a way that allows it to boot in UEFI
  • --efi-directory=/boot: All GRUB UEFI files will be installed in /boot
  • --bootloader-id="Funtoo Linux [GRUB]": This flag is not necessary for GRUB to boot. However, it allows you to change the text of the boot option in the UEFI BIOS. The stuff in the quotes can be set to anything that you would like.
  • --recheck: If a device map already exists on the disk or partition that GRUB is being installed on, it will be removed.
  • /dev/sda:The device that we are installing GRUB on.

Configuring GRUB

OK, now UEFI has the GRUB image it needs to boot. But we still need to configure GRUB itself so it finds and boots your kernel and initramfs. This is done by performing the following steps. Since boot-update doesn't yet support UEFI, we will use boot-update, but then edit our /boot/grub/grub.cfg to support UEFI booting.

First, you will need to edit /etc/boot.conf. Format this as you would if you were booting without UEFI. If you are not sure how this should look, below is an example of what it could look like if you are booting from an unencrypted ext4 partition:

   /etc/boot.conf 
boot {
        generate grub
        default "Funtoo Linux"
        timeout 3
}

"Funtoo Linux" {
        kernel vmlinuz[-v]
        params += rootfstype=ext4 root=/dev/sda2
}

After you have edited your /etc/boot.conf file, run boot-update. If you check your /boot/grub/grub.cfg now, you should see something like this:

   /boot/grub/grub.cfg 
set timeout=3

  insmod part_gpt
  insmod fat
  set root=(hostdisk//dev/sda,gpt1)
  search --no-floppy --fs-uuid --set 3CFD-6884
if loadfont /grub/unifont.pf2; then
   set gfxmode=text
   insmod gfxterm
   insmod vbe
   terminal_output gfxterm
fi

set menu_color_normal=cyan/blue
set menu_color_highlight=blue/cyan

menuentry "Funtoo Linux - vmlinuz-3.16.3" {
  insmod part_gpt
  insmod fat
  set root=(hostdisk//dev/sda,gpt1)
  search --no-floppy --fs-uuid --set 3CFD-6884
  linux /vmlinuz-3.16.3 video=uvesafb:1920x1080-32,mtrr:3,ywrap rootfstype=ext4 root=/dev/sda2
  set gfxpayload=text
}
set default=0

To get your /boot/grub/grub.cfg to support booting with UEFI, make your /boot/grub/grub.cfg look like this:

   /boot/grub/grub.cfg 
set timeout=3

  insmod part_gpt
  insmod fat
  insmod efi_gop
  insmod efi_uga
  set root=(hostdisk//dev/sda,gpt1)
  search --no-floppy --fs-uuid --set 3CFD-6884
if loadfont /grub/unifont.pf2; then
   set gfxmode=auto
   insmod gfxterm
   insmod vbe
   terminal_output gfxterm
fi

set menu_color_normal=cyan/blue
set menu_color_highlight=blue/cyan

menuentry "Funtoo Linux - vmlinuz-3.16.3" {
  insmod part_gpt
  insmod fat
  set root=(hostdisk//dev/sda,gpt1)
  search --no-floppy --fs-uuid --set 3CFD-6884
  linux /vmlinuz-3.16.3 video=uvesafb:1920x1080-32,mtrr:3,ywrap rootfstype=ext4 root=/dev/sda2
  set gfxpayload=keep
}
set default=0

The lines that we have added and altered do the following:

  • insmod efi_gop and insmod efi_uga: Both of these involve adding support for the UEFI framebuffer to GRUB.
  • set gfxmode=auto: Instead of having the GRUB boot option screen being displayed at the smallest resolution possible, changing this to auto will make it fit the resolution of your display.

Known Issues

  • With pure UEFI boot mode, with legacy mode disabled, following error expected:
    • video driver not supported, boot hangs, hard reboot required.
  • Choose UEFI first, next legacy driver. It depends on motherboard vendor and efi bios version.
    • In UEFI bios choose grub option, if your succeeded with above guide, additional menu should appear in Boot Menu, otherwise it boots into EFI shell: grub:NAME of you hard drive
  • On some systems, installing the packages that are required for UEFI booting with any gcc later than a 4.x.x release may lead to a black screen after the GRUB screen. To fix this, before you begin installing any packages on your system, emerge =gcc-4.6.4-r2 and proceed with the installation as usual. Remember to switch your compiler back to the version of gcc that came with your system after you have finished installing. To do this, use gcc-config 2.

Done!

Remember to follow all other steps in the regular Funtoo Install Guide. Assuming you did everything correctly, your system should now boot via UEFI! We will be adding UEFI support to boot-update soon to make this process easier.

Retrieved from "https://www.funtoo.org/index.php?title=Funtoo:Keychain&oldid=8329"