PXESrv is a Sinatra HTTP server hosting iPXE network boot configurations to:
- Boot all clients from a default boot configuration (boot menu for interactive installers).
- Redirect a single time (once) to a desired boot configuration.
- Boot into interactive OS installers like CentOS Anaconda or Debian Installer
- Boot into automatic provisioning like CentOS Kickstart or Debian Preseed
- Forward to a provisioning services like FAI or Cobbler
- Persistently boot a client specific static redirect boot configuration:
PXESrv serves a configuration file, from its document root directory, which is read from a POSIX file-system:
- The configuration can be altered creating/editing files in a directory tree (eventually via remote login SSH, Clustershell).
- Easy integration with configuration management systems like Chef, Puppet, CFengine, Ansible, SaltStack.
Why using this tool? PXEsrv can be useful in environments where (for whatever reason):
- it's not possible to use external resources (e.g. like those located on big cloud providers like AWS, MS Azure, Google Cloud Platform, etc.);
- ready-made provisioning solutions from external parties (be them open source or commercial software) cannot be purchased or easily adopted.
PXEsrv can be easily integrated on an existing infrastructure when the following services are already in place:
- DNS (e.g. ISC BIND)
- DHCP (e.g ISC DHCP)
- HW support for PXE booting
- IP Management (optional) (e.g. ONA, NetBox from DigitalOcean, etc.)
The DHCP server must be able to provide an option with the location for network
booting (AKA the filename
option), which will then be used to point to the
PXEsrv URL:
# ISC DHCP configuration example
host 10.10.10.1 {
fixed-address 10.10.10.1;
hardware ethernet 00:AA:BB:CC:DD:EE;
option host-name "myhost";
[...]
filename "http://example.fqdn:4567/redirect";
}
Once the node to be installed is able to contact PXEsrv, the process will proceed from there and it's up to the admins decide if an interactive installation or an automatic provisioning system should be started.
Environment variables for the PXESrv service daemon:
Environment | Description |
---|---|
PXESRV_ROOT | Path to the HTTP server document root (i.e. public/) |
PXESRV_LOG | Path to the log file, defaults to /var/log/pxesrv.log |
By default the response to all clients /redirect
requests is...
...unless a configuration in one of the following directories...
$PXESRV_ROOT/once/
(symbolic links)
$PXESRV_ROOT/static/
...changes the boot target.
Path | Description |
---|---|
/redirect | Entry path for all client requests |
/default | Default response path, unless a client has a specific boot configuration |
/once/{client-ip} | Redirect a client once to a linked boot configuration |
/static/{client-ip} | Redirect a client to a specific static boot configuration |
The sub-directory public/
, aka $PXESRV_ROOT
contains an example iPXE configuration.
The shell script source_me.sh adds the tool-chain in this repository to your shell environment:
# load the environment from var/aliases/*.sh
source source_me.sh && env | grep ^PXESRV
File | Description |
---|---|
var/systemd/pxesrv.service | Example PXESrv systemd service unit file |
Use a systemd service unit to manage the pxesrv
daemon:
# link to the service executable (expected by the systemd unit)
ln -s $PXESRV_PATH/pxesrv /usr/sbin/pxesrv
# install the service unit file
cp $PXESRV_PATH/var/systemd/pxesrv.service /etc/systemd/system/
systemctl daemon-reload
# link to the document root within this repo
ln -s $PXESRV_ROOT /srv/pxesrv
# start the PXESrv using Systemd
systemctl enable --now pxesrv
File | Description |
---|---|
Dockerfile | Example Docker file to build a PXESrv image |
Build a PXESrv Docker container and start it:
# build a docker container image
buildah build -f Dockerfile -t pxesrv
# start the container
podman run --rm \
--detach \
--interactive \
--tty \
--name pxesrv \
--publish 4567:4567 \
--volume $PXESRV_ROOT:/srv/pxesrv \
pxesrv
For Debian take a look to the debian/ sub-directory.
Use the pxesrv.spec to build an RPM package...
Please refer to PACKAGES.md for detailed instructions.
Install Sinatra on the hosting node:
# install dependencies on Debian
apt install -y ruby-sinatra
# install dependencies on Fedora
dnf install -y rubygem-sinatra
Start the โด pxesrv
service deamon
# start the service for development and testing in foreground
$PXESRV_PATH/pxesrv -p 4567
Please refer to DEVELOPMENT.md for detailed instructions.