Skip to content


Getting started with Grendel is easy. This quickstart guide assumes you have a rack of servers connected to a switch and configured to PXE boot. We also assume the server in which you're installing Grendel is either on the same subnet as the nodes or the switch is setup to relay DHCP packets to your Grendel server.


This guide shows how to get up and running with Grendel quickly. For notes on production deployments please see here.


Grendel can be configured using a TOML file. See here for a sample.

Assemble the Boot Image

A boot image defines the Linux Kernel, Initrd files and optionally any command line arguments. Boot images are defined using a simple JSON format. Grendel can boot any Linux kernel and initrd, for example Flatcar Linux is a distro specifically designed for running containers (fork of CoreOS). Grab a copy of the Flatcar kernel and initrd here:

$ wget
$ wget

The corresponding boot image config for Grendel would look like this:

    "name": "flatcar",
    "kernel": "flatcar_production_pxe.vmlinuz",
    "initrd": [
    "cmdline": "flatcar.autologin"

Grendel also supports booting LiveOS images. These are Linux kernel/initrd images built with Dracut live support. For more details on building custom Linux images see our Grendel Images project. We also provide pre-built images for use in testing Grendel. You can download them here.

For this tutorial, we'll be using the pre-built Ubuntu 20.04 image. First, download the kernel, initramfs, and squashfs files:

$ wget
$ wget
$ wget

Then create the following JSON file boot-image.json:

    "name": "ubuntu-focal-live",
    "kernel": "ubuntu-focal-vmlinuz",
    "initrd": [
    "liveimg": "ubuntu-focal-squashfs.img",
    "cmdline": "root=live:$liveimg BOOTIF=$mac rd.neednet=1 ip=dhcp"


Do not use these pre-built images in production. They are for testing purposes only. Default root password is: ilovelinux

Importing Nodes

Nodes can be imported into Grendel from a file in a simple JSON format:

    "name": "cpn-d13-18",
    "provision": true,
    "boot_image": "ubuntu-focal-live",
    "interfaces": [
            "fqdn": "",
            "ip": "",
            "mac": "41:69:AE:E6:61:06"

You can use any process you wish for assembling your nodes into this format. To make this easier, Grendel comes with a few built-in ways to auto-discover nodes from querying a switch, snooping DHCP packets, parsing a dhcpd.leases file, or importing from a simple TSV file. As a simple example, suppose you've harvested the required information for each of your nodes in a TAB separated file hosts.tsv:

name         mac                 ip             fqdn
cpn-d13-18   41:69:AE:E6:61:06
cpn-d13-19   41:69:AE:E6:71:16
cpn-d13-20   41:69:AE:E6:81:02

We can convert this into Grendel's host JSON format using the following command:

./grendel discover file --input hosts.tsv > hosts.json

Start services

Now that we've defined our hosts and a boot image we can start all the services necessary to netboot the nodes by running Grendel:


If your nodes are actively sending DHCP PXE boot requests these nodes will be booted into Ubuntu

sudo ./grendel --verbose serve --hosts hosts.json --images boot-image.json