Foreman iPXE

Adds in PXE loaders for chainloaded iPXE (undionly.kpxe, ipxe.efi)

This is useful for when you want to selectively chainload specific hosts into iPXE without affecting all other machines with the same OS.

Installation

Follow the Foreman manual for advanced installation from gems

For full usage of this plugin, you might want to create at least a global default iPXE boot template.
You can also specify a local boot template if need be, though in the case one is missing then a default template will be rendered that just closes iPXE and lets BIOS/UEFI continue the boot with the next device.

Compatibility

Usage

Global

This plugin adds global iPXE templates for hosts, if your DHCP is set up to always boot iPXE on all hosts - or hosts have iPXE embedded as their boot software.

You’ll need to create a global default template for iPXE to support this feature, an example given below;

<%#
kind: iPXE
model: ProvisioningTemplate
name: iPXE global default
snippet: false
-%>
#!ipxe
set menu-default local
set menu-timeout 5000
:start
menu iPXE global boot menu
item --key l local     Continue local boot
item shell             Drop into iPXE shell
item reboot            Reboot system
item
item --key d discovery Foreman Discovery
choose --timeout ${menu-timeout} --default ${menu-default} selected || goto cancel
set menu-timeout 0
goto ${selected}
:cancel
echo Menu canceled, dropping to shell
:shell
echo Use the command 'exit' to return to menu
shell
set menu-timeout 0
goto start
:failed
echo Boot failed, dropping to shell
goto shell
:reboot
reboot
:local
exit
:discovery
dhcp
kernel ${next-server}/boot/fdi-image/vmlinuz0 rootflags=loop root=live:/fdi.iso rootfstype=auto ro rd.live.image acpi=force rd.luks=0 rd.md=0 rd.dm=0 rd.lvm=0 rd.bootif=0 rd.neednet=0 nomodeset proxy.url=<%= foreman_server_url %> proxy.type=foreman BOOTIF=01-${net0/mac}
initrd ${next-server}/boot/fdi-image/initrd0.img
boot || goto failed
goto start

If you need to set a host-specific iPXE template, you can set the host parameter iPXE_Template to the name of the template that should be rendered for it.

Chainloading

Without DHCP setup

To use the chainloading, you need to generate the iPXE executables first.

git clone git://git.ipxe.org/ipxe.git
cd ipxe/src
cat <<EOF > default.ipxe
#!ipxe
dhcp
chain https://foreman.example.com/unattended/iPXE
EOF
make bin/undionly.kpxe EMBED=default.ipxe
make bin-x86_64-efi/ipxe.efi EMBED=default.ipxe

The generated executables should then be uploaded to the root of your TFTP server (or depending on your root path DHCP option).

With DHCP setup

Install the officially available iPXE executables (undionly.kpxe, ipxe.efi) into your TFTP server, then follow the iPXE guide for “breaking the loop”.

You want to add a rule that passes the bootfile “https://foreman.example.com/unattended/iPXE“ to any client reporting in as user class “iPXE”.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/ananace/foreman_ipxe

License

The gem is available as open source under the terms of the MIT License.