matchbox/Documentation/api.md

API

iPXE Script

Serves a static iPXE boot script which gathers client machine attributes and chainloads to the iPXE endpoint. Configure your DHCP server or iPXE server to boot from this script (e.g. set dhcp-boot:dhcp-boot=tag:ipxe,http://bootcfg.domain.com/ipxe/boot.ipxe if using dnsmasq).

GET http://bootcfg.foo/boot.ipxe
GET http://bootcfg.foo/boot.ipxe.0   // for dnsmasq

Response

#!ipxe
chain ipxe?uuid=${uuid}&mac=${net0/mac:hexhyp}&domain=${domain}&hostname=${hostname}&serial=${serial}

iPXE

Finds the spec matching the attribute query parameters and renders the spec boot settings (kernel, options, initrd) as an iPXE script.

GET http://bootcfg.foo/ipxe

Query Parameters

Name	Type	Description
uuid	string	Hardware UUID
mac	string	MAC address

Response

#!ipxe
kernel /assets/coreos/899.6.0/coreos_production_pxe.vmlinuz cloud-config-url=http://bootcfg.foo:8080/cloud?uuid=${uuid}&mac=${net0/mac:hexhyp} coreos.autologin
initrd  /assets/coreos/899.6.0/coreos_production_pxe_image.cpio.gz
boot

Pixiecore

Finds the spec matching the attribute query parameters and renders the boot settings as JSON to implement the Pixiecore API spec. Currently, Pixiecore only provides the machine's MAC address for matching.

GET http://bootcfg.foo/pixiecore/v1/boot/:MAC

URL Parameters

Name	Type	Description
mac	string	MAC address

Response

{
  "kernel":"/assets/coreos/899.6.0/coreos_production_pxe.vmlinuz",
  "initrd":["/assets/coreos/899.6.0/coreos_production_pxe_image.cpio.gz"],
  "cmdline":{
    "cloud-config-url":"http://bootcfg.foo/cloud?mac=ADDRESS",
    "coreos.autologin":""
  }
}

Cloud Config

Finds the spec matching the attribute query parameters and renders the corresponding cloud-config file.

GET http://bootcfg.foo/cloud

Query Parameters

Name	Type	Description
uuid	string	Hardware UUID
mac	string	MAC address

Response

#cloud-config
coreos:
  units:
    - name: etcd2.service
      command: start
    - name: fleet.service
      command: start

Ignition Config

Finds the spec matching the attribute query parameters and renders the corresponding Ignition config as JSON.

GET http://bootcfg.foo/ignition

Query Parameters

Name	Type	Description
uuid	string	Hardware UUID
mac	string	MAC address

Response

{
  "ignitionVersion": 1,
  "storage": {},
  "systemd": {
    "units": [
      {
        "name": "hello.service",
        "enable": true,
        "contents": "[Service]\nType=oneshot\nExecStart=\/usr\/bin\/echo Hello World\n\n[Install]\nWantedBy=multi-user.target"
      }
    ]
  },
  "networkd": {},
  "passwd": {}
}

OpenPGP Signatures

OpenPGPG signature endpoints serve ASCII armored detached signatures of rendered configs when signing is enabled. See OpenPGP Signing.

Endpoint	ASCII Signature Endpoint
Ignition	http://bootcfg.foo/ignition.asc
Cloud-init	http://bootcfg.foo/cloud.asc
iPXE	http://bootcfg.foo/boot.ipxe.asc
iPXE	http://bootcfg.foo/ipxe.asc
Pixiecore	http://bootcfg.foo/pixiecore/v1/boot.asc/:MAC

Get an Ignition config and its detached signature.

GET http://bootcfg.foo/ipxe?attribute=value

Response

#!ipxe
kernel /assets/coreos/899.6.0/coreos_production_pxe.vmlinuz cloud-config-url=http://bootcfg.foo:8080/cloud?uuid=${uuid}&mac=${net0/mac:hexhyp} coreos.autologin
initrd  /assets/coreos/899.6.0/coreos_production_pxe_image.cpio.gz
boot

GET http://bootcfg.foo/ipxe.asc?attribute=value

Response

-----BEGIN PGP SIGNATURE-----

wsBcBAEBCAAQBQJWoDHyCRCzUpbPLRRcKAAAqQ8IAGD+eC9kzc/U7h9tgwvvWwm9
suTmVSGlzC5RwTRXg6CKuW31m3WAin2b5zWRPa7MxxanYMhhBbOfrqg/4xi1tfdE
w7ipmmgftl3re0np75Jt9K1rwGXUHTCs3yooz/zvqSvNSobG13FL5tp+Jl7a22wE
+W7x9BukTytVgNLt3IDIxsJ/rAEYUm4zySftooDbFVKj/SK5w8xg4zLmE6Jxz6wp
eaMlL1TEXy3NaFR0+hgbqM/tgeV2j6pmho8yaPF63iPnksH+gdmPiwasCfpSaJyr
NO+p24BL3PHZyKw0nsrm275C913OxEVgnNZX7TQltaweW23Cd1YBNjcfb3zv+Zo=
=mqZK
-----END PGP SIGNATURE-----

API Resources

Specs

Get a Spec definition by id (UUID, MAC).

http://bootcfg.foo/spec/:id

URL Parameters

Name	Type	Description
id	string	spec identifier

Response

{
  "id": "etcd",
  "boot": {
    "kernel": "/assets/coreos/899.6.0/coreos_production_pxe.vmlinuz",
    "initrd": [
      "/assets/coreos/899.6.0/coreos_production_pxe_image.cpio.gz"
    ],
    "cmdline": {
      "coreos.autologin": "",
      "coreos.config.url": "http://bootcfg.foo:8080/ignition?uuid=${uuid}&mac=${net0/mac:hexhyp}",
      "coreos.first_boot": ""
    }
  },
  "cloud_id": "",
  "ignition_id": "etcd.yaml"
}

Assets

If you need to serve static assets (e.g. kernel, initrd), bootcfg can serve arbitrary assets from -assets-path at /assets/.

assets/
└── coreos
    └── 835.9.0
        ├── coreos_production_pxe.vmlinuz
        └── coreos_production_pxe_image.cpio.gz
    └── 899.6.0
        ├── coreos_production_pxe.vmlinuz
        └── coreos_production_pxe_image.cpio.gz