Switch branches/tags
Nothing to show
Find file History
Permalink
Type Name Latest commit message Commit time
..
Failed to load latest commit information.
api-example Delete the api-example binary I accidentally committed a while ago. Feb 5, 2018
cli gofmt -s all the things again. Feb 6, 2018
README.api.md Add an advanced option to pass in a raw iPXE script. Feb 4, 2018
README.booting.md Replace Pixieboot -> Pixiecore Oct 10, 2018
README.ipv6.md pixiecore: note the problem with using ULAs for v6 addressing. Jan 20, 2017
README.md Simplify and add TL;DR with `quick xyz` option Aug 12, 2018
README.testing.md Rename README.testing to README.testing.md so that github formats it. Jan 16, 2018
boot.ipxe Explain which DHCP response is missing Aug 28, 2018
boot_configuration.go Remove unneccessary conversions, further appeasing lint. Feb 6, 2018
booters.go Clean up more lint errors. Feb 6, 2018
booters_test.go pixiecore: set Content-Length when serving the kernel/initrd. Sep 15, 2016
bootgraph.dot pixiecore: flesh out the boot graph. Sep 18, 2016
bootgraph.svg pixiecore: flesh out the boot graph. Sep 18, 2016
dhcp.go Refactor firmware identification to be a bit easier to follow. #63 Feb 5, 2018
dhcpv6.go gofmt -s all the things again. Feb 6, 2018
http.go Add an advanced option to pass in a raw iPXE script. Feb 4, 2018
http_test.go pixiecore: Add a basic HTTP status UI. Sep 19, 2016
logging.go Remove unused enum value. Feb 7, 2018
pixicorev6.go Appease golint some more with docstrings and unexporting of functions. Feb 6, 2018
pixiecore-ui.png pixiecore: shrink the screenshot again. Sep 19, 2016
pixiecore.go Refactor firmware identification to be a bit easier to follow. #63 Feb 5, 2018
pixiecore.service Resolves #57: Add RF_NETLINK to RestrictedAddressFamilies in SystemD … Mar 25, 2018
pxe.go Refactor firmware identification to be a bit easier to follow. #63 Feb 5, 2018
tftp.go pixiecore: Add a basic HTTP status UI. Sep 19, 2016
urlsign.go Clean up more lint errors. Feb 6, 2018
urlsign_test.go pixiecore: factor out URL signing/decoding, and unit test it. Aug 15, 2016

README.md

Pixiecore

Pixiecore is an tool to manage network booting of machines. It can be used for simple single shot network boots, or as a building block of machine management infrastructure.

license api cli cli

Pixiecore UI

TL;DR

pixiecore quick xyz --dhcp-no-bind

Then try to boot another machine from the same network.

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

Pixiecore is available in a variety of forms. All of them automatically track this repository, so you always get the latest build.

Go get

Build the latest Pixiecore via go get:

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

Debian/Ubuntu

A Debian/Ubuntu package is available from packagecloud.io. They have extensive configuration instructions for a variety of mechanisms, but the quick version is:

sudo apt-get install -y apt-transport-https
curl -L https://packagecloud.io/danderson/pixiecore/gpgkey | sudo apt-key add -
echo "deb https://packagecloud.io/danderson/pixiecore/debian stretch main" >/etc/apt/sources.list.d/pixiecore.list
sudo apt-get update
sudo apt-get install pixiecore

Note that you should reference debian/stretch regardless of your actual distro. The pixiecore binary is built statically and should work fine on all distros, so we only build one variant of the package. Please file a bug if you hit problems with this setup.

Container images

Docker and ACI autobuilds are available. They track the latest code from this repository.

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

Demos and users

Pixiecore was used alongside waitron in a presentation at the OpenStack summit in 2016.

If you use Pixiecore, we'd love to hear about it, and know more about how you're using it. You can open a pull request to be added to this list, file an issue for me to add you, or just email me at dave(at)natulte.net if you'd like to give feedback privately.

  • waitron uses Pixiecore to manage automated server installation based on machine templates.