PXESrv

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:
  • Chainload external (third party) boot configurations, or provisioning systems like Foreman or CoreOS Matchbox
  • Boot stateless, immutable live-systems with initramfs and OverlayFS (to the node main memory (RAM))

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.

Motivation

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.)

Configuration

DHCP

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.

PXESrv

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...

$PXESRV_ROOT/default

...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.

Deployment

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

Systemd Unit

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

Docker Container

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

Packages

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.

Development

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.