Skip to content

mtds/pxe_srv

Repository files navigation

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

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:

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.