https://github.com/ananace/foreman_ipxe
Support for selectively booting chainloaded iPXE with Foreman
https://github.com/ananace/foreman_ipxe
foreman-ipxe ipxe theforeman
Last synced: 6 months ago
JSON representation
Support for selectively booting chainloaded iPXE with Foreman
- Host: GitHub
- URL: https://github.com/ananace/foreman_ipxe
- Owner: ananace
- License: mit
- Created: 2017-09-01T13:42:39.000Z (about 8 years ago)
- Default Branch: master
- Last Pushed: 2018-10-11T11:25:18.000Z (almost 7 years ago)
- Last Synced: 2025-04-13T12:39:29.411Z (6 months ago)
- Topics: foreman-ipxe, ipxe, theforeman
- Language: Ruby
- Homepage:
- Size: 37.1 KB
- Stars: 4
- Watchers: 2
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# 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](https://theforeman.org/plugins/#2.3AdvancedInstallationfromGems)
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
| Foreman Version | Plugin Version |
| --------------- | --------------:|
| >= 1.14 | ~> 0.1 |
| >= 1.18 | ~> 0.2 |
| >= 1.20 | *merged in Foreman* |
## 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;
```erb
<%#
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.
```sh
git clone git://git.ipxe.org/ipxe.git
cd ipxe/src
cat < 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"](http://ipxe.org/howto/chainloading#breaking_the_loop_with_the_dhcp_server).
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](http://opensource.org/licenses/MIT).