Implementing UEFI support with Satellite 6.2

This article was originally published on the Red Hat Customer Portal. The information may no longer be current.

Satellite 6 does not currently support UEFI, but thanks to John Herr from Red Hat and the Foreman Hooks plug-in, it is possible to achieve some level of integration for bare-metal or virtualized provisioning. This tutorial is for

Red Hat Enterprise Linux 7.1 running Satellite 6.1 and using Grub2 for PXE booting systems (instead of traditional PXELinux). This example configuration uses Satellite 6 with Capsule running on the same server. Required conditions:

• Satellite 6.2 running on Red Hat Enterprise Linux 7.1+
• Both DHCP and TFTP running on Satellite Server (not possible with external Capsule)
• Provisioned clients - RHEL7 (for RHEL6 filename options must point to Grub1 EFI loader instead - this can be only used in homogeneous environment e.g. either all clients RHEL7 or all clients RHEL6)

Satellite 6.3 is coming out with native UEFI support, therefore this workaround is not required anymore with this version.

INSTALL THE PACKAGES THAT CONTAIN THE EFI BOOT FILES

# yum -y install shim grub2-efi

COPY THE FILES TO THE /VAR/LIB/TFTPBOOT DIRECTORY

# cp /boot/efi/EFI/redhat/{shim,grubx64}.efi /var/lib/tftpboot
# cd /var/lib/tftpboot
# chcon --reference chain.c32 {shim,grubx64}.efi

CREATE THE UEFI BOOT MENU
This menu loads the configuration file from the /var/lib/tftpboot/uefi directory that matches the MAC address of the system being booted.

# echo 'configfile uefi/${net_default_mac}' > /var/lib/tftpboot/grub.cfg

# mkdir /var/lib/tftpboot/uefi
# setfacl -m u:foreman:rwx /var/lib/tftpboot/uefi

CONFIGURE DHCP
DHCP is configured to specify the value of "filename" according to the architecture option returned by the client. Edit the /etc/dhcp/dhcpd.conf file and change the PXE Handoff section to read as follows.

# PXE Handoff
next-server 1.2.3.4;
option architecture code 93 = unsigned integer 16 ;
if option architecture = 00:00 {
   filename "pxelinux.0";
} elsif option architecture = 00:09 {
   filename "shim.efi";
} elsif option architecture = 00:07 {
   filename "shim.efi";
} elsif option architecture = 00:06 {
   filename "shim.efi";
} else {
   filename "pxelinux.0";
}

RESTART THE DHCPD DAEMON

# systemctl restart dhcpd

INSTALL THE HOOKS PLUG-IN

# yum -y install tfm-rubygem-foreman_hooks
# katello-service restart

In Satellite 6.1 the package is named rubygem-foreman_hooks.

INSTALL JGREP UTILITY

This small utility is used in the scripts, but it is not shipped with Satellite 6. You can install from Rubygems:

# gem install jgrep
Fetching: jgrep-1.4.1.gem (100%)
Successfully installed jgrep-1.4.1
Parsing documentation for jgrep-1.4.1
Installing ri documentation for jgrep-1.4.1
1 gem installed

# which jgrep
/usr/local/bin/jgrep

During Satellite upgrades, make sure the utility is working properly and reinstall if needed. To test if jgrep utility works try this:

# echo '{}' | jgrep

PREPARE THE ENVIRONMENT FOR THE HOOKS

# cd /usr/share/foreman/config/hooks/
# mkdir -p /usr/share/foreman/config/hooks/host/managed/{after_build,before_provision}

CREATE THE HOOK THAT WILL RUN AFTER THE HOST ENTERS BUILD MODE
Place the following in the /usr/share/foreman/config/hooks/host/managed/after_build/50-uefi.sh file

#!/bin/bash
# update, create, before_destroy, etc.
HOOK_EVENT=$1
# to_s representation of the object, e.g. host's fqdn
HOOK_OBJECT=$2
HOOK_OBJECT_FILE=$(mktemp -t foreman_hooks.XXXXXXXXXX)
trap "rm -f $HOOK_OBJECT_FILE" EXIT
cat > $HOOK_OBJECT_FILE
hook_data() {
  if [ $# -eq 1 ]; then
    jgrep -s "$1" < $HOOK_OBJECT_FILE
  else
    jgrep "$*" < $HOOK_OBJECT_FILE
  fi
}
pxe_dir=/var/lib/tftpboot/pxelinux.cfg
uefi_dir=/var/lib/tftpboot/uefi
leases=/var/lib/dhcpd/dhcpd.leases
mac=$( hook_data host.mac )
dash_mac=$( hook_data host.mac | tr ':' '-' )
name=$( hook_data host.name )
sed -i "/supersede server.filename/d" ${leases}
ks_info=$( sed -n 's/.*\sks=\(.*\)/\1/p' ${pxe_dir}/??-${dash_mac} )
kernel=$( sed -n 's/\s*kernel\s*\(.*\)/\1/p' ${pxe_dir}/??-${dash_mac} )
initrd=$(  sed -n 's/.*\sinitrd=\(.*\)/\1/p' ${pxe_dir}/??-${dash_mac} | sed 's/\s.*//' )
[[ ! -d ${uefi_dir} ]] && mkdir -p ${uefi_dir}

cat << EOF > ${uefi_dir}/${mac}
set timeout=5
menuentry 'Provision ${name}' {
  linuxefi ${kernel} ip=dhcp ks=${ks_info}
  initrdefi ${initrd}
  }
EOF
echo "UEFI HOOK: deployed ${uefi_dir}/${mac}"

Test the hook first simulating deployment of fake host named "test" with MAC address AA:BB:CC:DD:EE:FF:

# cat >/var/lib/tftpboot/pxelinux.cfg/01-AA-BB-CC-DD-EE-FF <<FAKE
DEFAULT linux
LABEL linux
KERNEL boot/vmlinuz
APPEND initrd=boot/initrd.img ks=http://fake/unattended/provision?token=b9a9bacd-28ab-42a9-8266-27996eaee322 network ks.sendmac
IPAPPEND 2
FAKE

# /usr/share/foreman/config/hooks/host/managed/after_build/50-uefi.sh create test
{"host": {"mac": "AA:BB:CC:DD:EE:FF", "name": "test"}}
CTRL+D
UEFI HOOK: deployed /var/lib/tftpboot/uefi/AA:BB:CC:DD:EE:FF

There should be no errors in the above command, except the "deployed" message. The following file should be created, it can be removed now:

# cat /var/lib/tftpboot/uefi/AA:BB:CC:DD:EE:FF
set timeout=5
menuentry 'Provision test' {
  linuxefi  ip=dhcp ks=http://fake/unattended/provision?token=b9a9bacd-28ab-42a9-8266-27996eaee322 network ks.sendmac
  initrdefi boot/initrd.img
  }

# rm /var/lib/tftpboot/uefi/AA:BB:CC:DD:EE:FF

CREATE THE HOOK THAT WILL RUN AFTER THE HOST IS INSTALLED
Place the following in the /usr/share/foreman/config/hooks/host/managed/before_provision/60-uefi-after.sh file

#!/bin/bash
# update, create, before_destroy etc.
HOOK_EVENT=$1
# to_s representation of the object, e.g. host's fqdn
HOOK_OBJECT=$2
HOOK_OBJECT_FILE=$(mktemp -t foreman_hooks.XXXXXXXXXX)
trap "rm -f $HOOK_OBJECT_FILE" EXIT
cat > $HOOK_OBJECT_FILE
cp $HOOK_OBJECT_FILE /tmp/out.after.object
hook_data() {
  if [ $# -eq 1 ]; then
    jgrep -s "$1" < $HOOK_OBJECT_FILE
  else
    jgrep "$*" < $HOOK_OBJECT_FILE
  fi
}
pxe_dir=/var/lib/tftpboot/pxelinux.cfg
uefi_dir=/var/lib/tftpboot/uefi
mac=$( hook_data host.mac )
dash_mac=$( hook_data host.mac | tr ':' '-' )
name=$( hook_data host.name )
cat << EOF > ${uefi_dir}/${mac}
set timeout=5
menuentry 'Localboot ${name}' {
     insmod part_msdos
     insmod chain
     configfile (hd0,gpt1)/efi/redhat/grub.cfg
}
EOF
echo "UEFI HOOK: deployed ${uefi_dir}/${mac}"

Test it the similar way:

# /usr/share/foreman/config/hooks/host/managed/before_provision/60-uefi-after.sh create test
{"host": {"mac": "AA:BB:CC:DD:EE:FF", "name": "test"}}
UEFI HOOK: deployed /var/lib/tftpboot/uefi/AA:BB:CC:DD:EE:FF

# cat /var/lib/tftpboot/uefi/AA:BB:CC:DD:EE:FF
set timeout=5
menuentry 'Localboot test' {
     insmod part_msdos
     insmod chain
     configfile (hd0,gpt1)/efi/redhat/grub.cfg
}
# rm /var/lib/tftpboot/uefi/AA:BB:CC:DD:EE:FF

Set the file permissions and correct SELinux file contexts:

# chmod 755 /usr/share/foreman/config/hooks/host/managed/after_build/50-uefi.sh
# chmod 755 /usr/share/foreman/config/hooks/host/managed/before_provision/60-uefi-after.sh
# restorecon -RvvF /usr/share/foreman/config/hooks

Because the hooks require permission to modify the /var/lib/dhcpd.leases file, set a facl to allow it:

# setfacl -R -m u:foreman:rwx /var/lib/dhcpd

When a new host is created and enters "build mode" in Satellite 6, the PXE configuration on the TFTP configuration is modified to use Grub2 for both UEFI and non-UEFI systems instead of the default PXELinux (which does not support UEFI yet).