netboot/pixiecore

Pixiecore

Pixiecore is an all-in-one tool to manage network booting of machines. It can be used either as a simple tool for ad-hoc network boots, or as a building block of machine management infrastructure.

Why?

Booting a Linux system over the network is quite tedious. You have to set up a TFTP server, reconfigure your DHCP server to recognize PXE clients, and send them the right set of magical options to get them to boot, often fighting rubbish PXE ROM implementations.

Pixiecore aims to simplify this process, by packing the whole process into a single binary that can cooperate with your network's existing DHCP server. You don't need to reconfigure anything else in the network.

If you're curious about the whole process that Pixiecore manages, you can read the details in README.booting.

Installation

Install Pixiecore via go get:

go get go.universe.tf/netboot/cmd/pixiecore

Pixiecore is also available in other formats:

• Docker image on Docker Hub: danderson/pixiecore
• Rkt ACI image on Quay.io: quay.io/pixiecore/pixiecore

Using Pixiecore in static mode ("I just want to boot a machine")

Run the pixiecore binary, passing it a kernel and initrd, and optionally some extra kernel commandline arguments. For example, here's how you make all machines in your network netboot into the alpha release of CoreOS, with automatic login:

sudo pixiecore boot \
  https://alpha.release.core-os.net/amd64-usr/current/coreos_production_pxe.vmlinuz \
  https://alpha.release.core-os.net/amd64-usr/current/coreos_production_pxe_image.cpio.gz \
  --cmdline='coreos.autologin'

That's it! Any machine that tries to boot from the network will now boot into CoreOS.

That's a bit slow to boot, because Pixiecore is refetching the images from core-os.net each time a machine tries to boot. We can also download the files and use those:

wget https://alpha.release.core-os.net/amd64-usr/current/coreos_production_pxe.vmlinuz
wget https://alpha.release.core-os.net/amd64-usr/current/coreos_production_pxe_image.cpio.gz
sudo pixiecore boot \
  coreos_production_pxe.vmlinuz \
  coreos_production_pxe_image.cpio.gz \
  --cmdline='coreos.autologin'

Sometimes, you want to give extra files to the booting OS. For example, CoreOS lets you pass a Cloud Init file via the cloud-config-url kernel commandline parameter. That's fine if you have a URL, but what if you have a local file?

For this, Pixiecore lets you specify that you want an additional file served over HTTP to the booting OS, via a template function. Let's grab a cloud-config.yml that sets the hostname to pixiecore-test, and serve it:

wget -O my-cloud-config.yml https://goo.gl/7HzZf2
sudo pixiecore boot \
  coreos_production_pxe.vmlinuz \
  coreos_production_pxe_image.cpio.gz \
  --cmdline='coreos.autologin cloud-config-url={{ ID "./my-cloud-config.yml" }}'

Pixiecore will transform the template invocation into a URL that, when fetched, serves my-cloud-config.yml. Similarly to the kernel and initrd arguments, you can also pass a URL to the ID template function.

Pixiecore in API mode

Think of Pixiecore in API mode as a "PXE to HTTP" translator. Whenever Pixiecore sees a machine trying to netboot, it will ask a remote HTTP API (which you implement) what to do. The API server can tell Pixiecore to ignore the machine, or tell it to boot into a given kernel/initrd/commandline.

Effectively, Pixiecore in API mode lets you pretend that your machines speak a simple JSON protocol when trying to netboot. This makes it far easier to play with netbooting in your own software.

To start Pixiecore in API mode, pass it the URL of your API endpoint:

sudo pixiecore api https://foo.example/pixiecore

The endpoint you provide must implement the Pixiecore boot API, as described in the API spec.

You can find a sample API server implementation in the api-example subdirectory. The code is not production-grade, but gives a short illustration of how the protocol works by reimplementing a subset of Pixiecore's static mode as an API server.

Running in containers

Pixiecore is available both as an ACI image for rkt, and as a Docker image for Docker Engine. Both images are automatically built whenever the github repository changes.

Because Pixiecore needs to listen for DHCP traffic, it has to run with access to the host's networking stack. Both Rkt and Docker do this with the --net=host commandline flag.

sudo rkt run --net=host \
  --volume images,kind=host,source=/var/images \
  --mount volume=images,target=/image \
  quay.io/pixiecore/pixiecore -- \
    boot /image/coreos_production_pxe.vmlinuz /image/coreos_production_pxe_image.cpio.gz

sudo docker run \
  --net=host \
  -v .:/image \
  danderson/pixiecore \
    boot /image/coreos_production_pxe.vmlinuz /image/coreos_production_pxe_image.cpio.gz