diff --git a/.travis-scripts/dictionary.txt b/.travis-scripts/dictionary.txt index f54624ff..78d68dd1 100644 --- a/.travis-scripts/dictionary.txt +++ b/.travis-scripts/dictionary.txt @@ -22,6 +22,7 @@ devel DHCP DNS DPM +EFI EL EPEL ESX @@ -53,6 +54,7 @@ IP iptables IPMI IPv +ISC jrha JSON Kerberos @@ -90,6 +92,7 @@ postgresql PowerDNS predeployment protobuf +PXELINUX PyPI quattor Quattor @@ -112,8 +115,11 @@ stratuslab subnet subnets symlink +SYSLINUX systemd +TFTP th +UEFI UGent UID UMD diff --git a/_config.yml b/_config.yml index 24b17847..0c6ce0ac 100644 --- a/_config.yml +++ b/_config.yml @@ -16,6 +16,9 @@ collections: development: output: true permalink: /development/:title.html + initial_installation: + output: true + permalink: /aii/:title.html other: output: true permalink: /other/:title.html diff --git a/_includes/docmenu.md b/_includes/docmenu.md index fc4846a1..45e29686 100644 --- a/_includes/docmenu.md +++ b/_includes/docmenu.md @@ -5,7 +5,7 @@ Documentation categories must match a Jekyll collection name. If the collection name contains underscores, they are replaced by space in the documentation menu {% endcomment %} -{% assign submenu_categories = "quattor, aquilon, template_library, development, other" | split: ", " %} +{% assign submenu_categories = "quattor, aquilon, template_library, initial_installation, development, other" | split: ", " %} {% for topic in submenu_categories %} {% assign topic_words = topic | split: "_" %} {% capture topic_title %}{% for word in topic_words %}{{ word | capitalize }} {% endfor %}{% endcapture %} diff --git a/_initial_installation/uefi-support.md b/_initial_installation/uefi-support.md new file mode 100644 index 00000000..a4da1e82 --- /dev/null +++ b/_initial_installation/uefi-support.md @@ -0,0 +1,123 @@ +--- +layout: article +title: UEFI Support in AII +author: Michel Jouvin +menu: UEFI Support +redirect_from: /documentation/2017/02/27/uefi-support.html +--- + +# {{ page.title }} + +Quattor 17.3 introduced UEFI support in AII. It is based on using the Grub2 EFI loader instead of PXELINUX or SYSLINUX. This page describes +how to enable it, when you have an AII working configuration for legacy BIOS. + + +## Changes to AII Server Configuration + +By default, AII server configuration requires no change to enable the UEFI support (the UEFI boot configuration files are produced in +addition to the PXELINUX ones) but a few additional files must be installed on the TFTP server, in a directory called by default `grub-efi`, +in the same location where your `pxelinux.cfg` directory is. The required files are: + +* Grub2 EFI loader: see the section below +* `localboot.cfg` for Grub2 EFI: recommended file is provided by `aii-pxelinux` RPM and installed in `/usr/share/doc/aii-pxelinux-VERSION/eg` + (`localboot.cfg.grub2`). + +Also the DHCP server configuration must be updated to recognise the UEFI vendor class and use the appropriate boot loader and configuration files. +On an ISC DHCP server, this is typically done by adding in the `dhcpd` configuration (in the file dedicated to Quattor-managed machines for +example) something like: + +``` +option space PXE; +option PXE.mtftp-ip code 1 = ip-address; +option PXE.mtftp-cport code 2 = unsigned integer 16; +option PXE.mtftp-sport code 3 = unsigned integer 16; +option PXE.mtftp-tmout code 4 = unsigned integer 8; +option PXE.mtftp-delay code 5 = unsigned integer 8; +option arch code 93 = unsigned integer 16; # RFC4578 + +# This should be the group where you have the Quattor-related dhcpd parameters. +group { + + # grubx64.efi path (quattor/grub2-efi) should be adjusted to reflect its path + # relative to the TFTP server root. This must be the directory where the Grub2 + # configuration files are located (and not its parent as for PXELINUX). + if option arch = 00:07 { + filename "quattor/grub2-efi/grubx64.efi"; + } else if option arch = 00:09 { + filename "quattor/grub2-efi/grubx64.efi"; + } else { + filename "quattor/pxelinux.0"; + } + + .... (your existing configuration) + +``` + +See [SYSLINUX documentation](http://www.syslinux.org/wiki/index.php?title=PXELINUX#UEFI) for more details on the DHCP server configuration. + +### Building the Grub2 UEFI boot loader + +EL7 provides a `grub2-efi` package (there is no Grub2 package for EL6): the boot loader is `/boot/efi/EFI/centos/grubx64.efi`. Unfortunately, it +is hardly usable without being rebuilt, as the default paths it uses are generally inappropriate and it may also lack the support for installing +an EL6 machine (EL6 cannot be installed with the `linuxefi` command and requires the `linux` command to be used). + +*Note: the Grub2 UEFI boot loader provided by EL7 can be used on an AII server running EL6.* + +To rebuild your own Grub2 boot loader, install the the packages `grub2-tools` (commands to manage Grub2) and `grub2-efi-modules` (Grub2 modules). +There are several possibilities but the recommended method is to use is `grub2-mkimage` command to build a boot loader image tailored for your +configuration. `grub2-mkimage` important options are: + +* `--prefix`: defines where the additional Grub modules (if any) are located. You need + to start this path with `(pxe)` which means that the modules are reachable through + the TFTP server and that the following path is relative to the TFTP server root. For + example, `(pxe)/grub2-modules` means that the Grub2 modules are located in directory + `grub2/modules` under the TFTP server root. Note that if you rebuild the Grub2 boot + loader as suggested here, this directory is not used. +* List of modules to add to the boot loader image: they are passed as parameters to `grub2-mkimage`. + You typically need `efi_gop efi_uga efinet linux linux16 linuxefi`: `linux` is not needed if you + don't intend to install EL6 machine with Grub2 UEFI (but this is + harmless to add them if you have some control over the persons who can trigger the installation). +* `--format=x86_64-efi`: required for the boot loader to be usable with a UEFI firmware. +* `--output`: name of the boot loader file produced by the command. This is the file that + you need to copy to your TFTP server directory where the Grub2 configuration files will be generated + by `aii-shellfe --conigure` (this directory must match your DHCP server configuration, see above). + +A typical `grub2-mkimage` command with the prefix example explained above (to be update according to your configuration) is: + +``` +grub2-mkimage --format=x86_64-efi --output=grubx64.efi --prefix='(pxe)/grub2-modules' efi_gop efi_uga efinet linux linuxefi +``` + +See the [Grub2 manual](https://www.gnu.org/software/grub/manual/grub.html) for details. + +### New `aii-shellfe` Configuration Options + +New `aii-shellfe` configuration options have been introduced with the UEFI support. Look at +`/usr/share/doc/aii-server-VERSION/eg/aii-shellfe.conf` file for a list of all these options +and their expected values. + +UEFI support has been designed to work without any change to the configuration. One exception +is `grub2_efi_kernel_root` that controls the path to the kernel to be loaded. Grub2 EFI interprets +the path differently from PXELINUX: the path must be an absolute path (starting with a `/`) which +is the path relative to the TFTP server root. If you use the default directory name for Grub2 +configuration files (`grub2-efi`) and if your Quattor TFTP server directory is two levels under +`/` (like in `/tftproot/quattor` when `/tftproot` is the TFTP server root), the default value should +be appropriate. Else you may need to adjust the path with `grub2_efi_kernel_root`. Enable TFTP +server verbose mode to troubleshoot problems related to this path. + +## Changes to Host Profiles + +There is no change required to activate the use of UEFI for a given machine. Grub2 UEFI boot will +be used if the machine firmware is configured to use UEFI, PXELINUX will be used if the firmware is +configured to use legacy BIOS. The DHCP request will contain the information and the appropriate +configuration will be selected. + +Nevertheless, to be able to successfully install the machine through Grub2 UEFI, the first partition +of the system disk must dedicated to Grub2. If you use the template library, this partition is +automatically added if you define the variable `DISK_BIOS_TYPE_UEFI` to true. Else, you need to +ensure that the first partition created has a size of 200 MB and has its flag set to `bios_grub`. + +*Note: it is harmless to define variable `DISK_BIOS_TYPE_UEFI` on every machine, even if it is still +using the legacy BIOS. The only exception is if you want to boot a disk larger than 2 GB with the +legacy BIOS: in this case the variable `DISK_BOOT_ADD_BIOSBOOT_PART` must be defined instead +(and the partition flag is not the one expected by Grub2 UEFI).*