HTTP API¶

iPXE script¶

Serves a static iPXE boot script which gathers client machine attributes and chainloads to the iPXE endpoint. Use DHCP/TFTP to point iPXE clients to this endpoint as the next-server.

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

Response

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

Client's booted with the /ipxe.boot endpoint will introspect and make a request to /ipxe with the uuid, mac, hostname, and serial value as query arguments.

iPXE¶

Finds the profile for the machine and renders the network boot config (kernel, options, initrd) as an iPXE script.

GET http://matchbox.foo/ipxe?label=value

Query parameters

Name	Type	Description
uuid	string	Hardware UUID
mac	string	MAC address
*	string	Arbitrary label

Response

#!ipxe
kernel /assets/coreos/1967.3.0/coreos_production_pxe.vmlinuz coreos.config.url=http://matchbox.foo:8080/ignition?uuid=${uuid}&mac=${mac:hexhyp} coreos.first_boot=1 coreos.autologin
initrd  /assets/coreos/1967.3.0/coreos_production_pxe_image.cpio.gz
boot

GRUB2¶

Finds the profile for the machine and renders the network boot config as a GRUB config. Use DHCP/TFTP to point GRUB clients to this endpoint as the next-server.

GET http://matchbox.foo/grub?label=value

Query parameters

Name	Type	Description
uuid	string	Hardware UUID
mac	string	MAC address
*	string	Arbitrary label

Response

default=0
timeout=1
menuentry "CoreOS" {
echo "Loading kernel"
linuxefi "(http;matchbox.foo:8080)/assets/coreos/1967.3.0/coreos_production_pxe.vmlinuz" "coreos.autologin" "coreos.config.url=http://matchbox.foo:8080/ignition" "coreos.first_boot"
echo "Loading initrd"
initrdefi "(http;matchbox.foo:8080)/assets/coreos/1967.3.0/coreos_production_pxe_image.cpio.gz"
}

Cloud config¶

DEPRECATED: Finds the profile matching the machine and renders the corresponding Cloud-Config with group metadata, selectors, and query params.

GET http://matchbox.foo/cloud?label=value

Query Parameters

Name	Type	Description
uuid	string	Hardware UUID
mac	string	MAC address
*	string	Arbitrary label

Response

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

Ignition Config¶

Finds the profile matching the machine and renders the corresponding Ignition for machine consumption.

GET http://matchbox.foo/ignition?label=value

Query parameters

Name	Type	Description
uuid	string	Hardware UUID
mac	string	MAC address
*	string	Arbitrary label

Response

{
  "ignition": { "version": "3.3.0" },
  "systemd": {
    "units": [{
      "name": "example.service",
      "enabled": true,
      "contents": "[Service]\nType=oneshot\nExecStart=/usr/bin/echo Hello World\n\n[Install]\nWantedBy=multi-user.target"
    }]
  }
}

Generic config¶

Finds the profile matching the machine and renders the corresponding generic config with group metadata, selectors, and query params.

GET http://matchbox.foo/generic?label=value

Query parameters

Name	Type	Description
uuid	string	Hardware UUID
mac	string	MAC address
*	string	Arbitrary label

Response

{
  “uuid”: “”,
  “mac”: “52:54:00:a1:9c:ae”,
  “osInstalled”: true,
  “rawQuery”: “mac=52:54:00:a1:9c:ae&os=installed”
}

Metadata¶

Finds the matching machine group and renders the group metadata, selectors, and query params in an "env file" style response.

GET http://matchbox.foo/metadata?mac=52-54-00-a1-9c-ae&foo=bar&count=3&gate=true

Query Parameters

Name	Type	Description
uuid	string	Hardware UUID
mac	string	MAC address
*	string	Arbitrary label

Response

META=data
ETCD_NAME=node1
SOME_NESTED_DATA=some-value
MAC=52:54:00:a1:9c:ae
REQUEST_QUERY_MAC=52:54:00:a1:9c:ae
REQUEST_QUERY_FOO=bar
REQUEST_QUERY_COUNT=3
REQUEST_QUERY_GATE=true
REQUEST_RAW_QUERY=mac=52-54-00-a1-9c-ae&foo=bar&count=3&gate=true

OpenPGP signatures¶

OpenPGP signature endpoints serve detached binary and ASCII armored signatures of rendered configs, if enabled. See OpenPGP Signing.

Endpoint	Signature Endpoint	ASCII Signature Endpoint
iPXE	`http://matchbox.foo/ipxe.sig`	`http://matchbox.foo/ipxe.asc`
GRUB2	`http://bootcf.foo/grub.sig`	`http://matchbox.foo/grub.asc`
Ignition	`http://matchbox.foo/ignition.sig`	`http://matchbox.foo/ignition.asc`
Cloud-Config	`http://matchbox.foo/cloud.sig`	`http://matchbox.foo/cloud.asc`
Generic	`http://matchbox.foo/generic.sig`	`http://matchbox.foo/generic.asc`
Metadata	`http://matchbox.foo/metadata.sig`	`http://matchbox.foo/metadata.asc`

Get a config and its detached ASCII armored signature.

GET http://matchbox.foo/ipxe?label=value
GET http://matchbox.foo/ipxe.asc?label=value

Response

Assets¶

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

matchbox.foo/assets/
└── coreos
    └── 1967.3.0
        ├── coreos_production_pxe.vmlinuz
        └── coreos_production_pxe_image.cpio.gz
    └── 1153.0.0
        ├── coreos_production_pxe.vmlinuz
        └── coreos_production_pxe_image.cpio.gz