Server Routes

The Warewulf provisioning daemon, warewulfd, serves all boot and provisioning resources over HTTP. Each resource type has a dedicated route, and nodes are identified by their Warewulf ID (wwid).

{wwid} is typically the node’s default MAC address: a colon-separated hexadecimal string, e.g., aa:bb:cc:dd:ee:ff. Dashes are accepted in place of colons and are normalized automatically.

Note

The port warewulfd listens on is configured with warewulf:port in warewulf.conf (default: 9873). When TLS is enabled, a second listener is started on the port configured with warewulf:tls port (default: 9874).

URL Patterns

Every provisioning route (except /status) supports six equivalent URL patterns for specifying the node identity:

/{stage}/{wwid}           # wwid in path
/{stage}?wwid={wwid}      # wwid as query parameter
/{stage}                  # wwid resolved from ARP cache

/provision/{wwid}?stage={stage}
/provision?wwid={wwid}&stage={stage}
/provision?stage={stage}  # wwid resolved from ARP cache

The /efiboot/ route is an exception: the path segment contains the boot file name rather than a wwid, and the node is identified via ?wwid= or ARP:

/efiboot/{file}                    # file in path, wwid from ARP
/efiboot/{file}?wwid={wwid}        # file in path, explicit wwid
/efiboot?wwid={wwid}&file={file}   # both as query parameters

Common Query Parameters

Most provisioning routes accept the following query parameters:

  • wwid: Warewulf ID of the node, typically its default MAC address. Used when the node identity is not embedded in the URL path. Takes priority over ARP lookup; the path always takes priority over the wwid query parameter.

  • assetkey: Hardware asset tag. If the node has an AssetKey configured in nodes.conf, the server requires this parameter to match before serving any content. See Security below.

  • uuid: System UUID of the requesting node. Accepted for logging purposes.

  • compress: Compression format for the response. The only supported value is gz. When compress=gz is specified, the server serves a pre-built gzip-compressed version of the file. If no compressed version exists, the server returns 404 Not Found.

Provisioning Routes

/ipxe/{wwid}

Serves a rendered iPXE boot script for the node identified by {wwid}.

The script is rendered as a Go template from a file in /etc/warewulf/ipxe/. The specific template used is determined by the node’s Ipxe field (defaulting to default); for example, a node with Ipxe: dracut receives the template from /etc/warewulf/ipxe/dracut.ipxe.

If the requesting node is not known to Warewulf, the server falls back to serving /etc/warewulf/ipxe/unconfigured.ipxe.

Query parameters: assetkey, uuid

/kernel/{wwid}

Serves the raw kernel binary for the node identified by {wwid}. The kernel is taken from the node’s assigned image.

Query parameters: assetkey, uuid, compress

/image/{wwid}

Serves the raw OS image file for the node identified by {wwid}.

Query parameters: assetkey, uuid, compress

/initramfs/{wwid}

Serves the initramfs binary for the node identified by {wwid}. The initramfs is extracted from the node’s assigned image based on the node’s kernel version. This route is used in two-stage boot configurations. See Two-stage boot: dracut for details.

Query parameters: assetkey, uuid, compress

/system/{wwid}

Serves the system overlay image for the node identified by {wwid}. The system overlay is rendered at provisioning time and contains configuration files that are static for the lifetime of the boot.

When autobuild overlays is enabled in warewulf.conf, the server will automatically rebuild the overlay if it is out of date relative to nodes.conf or the overlay source files.

Query parameters: assetkey, uuid, compress

/runtime/{wwid}

Serves the runtime overlay image for the node identified by {wwid}. The runtime overlay is rendered on demand and may contain node-specific secrets. wwclient fetches the runtime overlay periodically during normal operation.

When warewulf:secure is enabled in warewulf.conf, this route requires that the request originate from a privileged TCP port (port number less than 1024). This prevents unprivileged users on a node from retrieving the runtime overlay.

When TLS is enabled in warewulf.conf, this route requires that the request arrive over HTTPS. Plain-HTTP requests are rejected with 403 Forbidden. The HTTPS listener port is configured with warewulf:tls port.

Query parameters: assetkey, uuid, compress

/efiboot/{file}

Serves EFI boot files for GRUB-based booting. The requesting node is identified by ?wwid= (preferred) or, if not supplied, by an ARP lookup of the client’s IP address against the kernel’s ARP cache (/proc/net/arp). This route is intended for EFI HTTP Boot clients, where the firmware fetches a boot URI from DHCP and cannot perform variable substitution.

Note

On large clusters the kernel’s default ARP cache limits may be exceeded, causing node identification to fail. See ARP Cache Overflow on Large Clusters for tuning guidance.

The {file} component determines what is served:

  • shim.efi: Serves the shim.efi binary extracted from the node’s assigned image.

  • grub.efi (or grubx64.efi, grubaa64.efi, grubia32.efi, grubarm.efi, grub-tpm.efi): Serves the GRUB EFI binary extracted from the node’s assigned image.

  • grub.cfg: Serves a rendered GRUB configuration file from /etc/warewulf/grub/grub.cfg.ww. The configuration is rendered as a Go template for the identified node.

Because shim.efi resolves subsequent files relative to its own load URL, GRUB and grub.cfg are also fetched from the /efiboot/ path. The grub.cfg served by this route uses ${net_default_mac} to embed the node’s wwid in all further provisioning URLs, directing subsequent requests to the per-node /grub/{wwid} route.

Query parameters: assetkey, uuid, wwid, file

  • file: The EFI file to serve (shim.efi, grub.efi, or grub.cfg). Used when the file name is not embedded in the URL path.

Note

/efiboot/ is the recommended route for EFI HTTP Boot clients. For TFTP-booted GRUB clients that know their own wwid, use /grub/{wwid} to fetch the per-node GRUB configuration directly.

/grub/{wwid}

Serves a rendered GRUB configuration file for the node identified by {wwid}. The configuration is rendered from /etc/warewulf/grub/grub.cfg.ww as a Go template. This route is the preferred method for TFTP-booted GRUB clients to fetch their per-node configuration, as the node identity is explicit in the URL rather than resolved via ARP.

Query parameters: assetkey, uuid, wwid

/provision/{wwid}

A legacy dispatcher route. The provisioning stage is determined by the stage query parameter, which is dispatched to the appropriate handler:

  • stage=ipxe → /ipxe/

  • stage=kernel → /kernel/

  • stage=image → /image/

  • stage=initramfs → /initramfs/

  • stage=system → /system/

  • stage=runtime → /runtime/

  • stage=grub → /grub/

Query parameters: stage (required), assetkey, uuid, compress

Status Route

/status

Returns a JSON object containing the last-known provisioning status for all nodes that have contacted the server. No authentication is required.

{
  "nodes": {
    "node01": {
      "node name": "node01",
      "stage": "RUNTIME_OVERLAY",
      "sent": "2 kB",
      "ipaddr": "10.0.1.1",
      "last seen": 1712345678
    }
  }
}

The stage field reflects the most recent provisioning stage completed for the node. Possible values include IPXE, KERNEL, IMAGE, INITRAMFS, SYSTEM_OVERLAY, RUNTIME_OVERLAY, and EFI.

REST API

When enabled in warewulf.conf, warewulfd exposes a REST API under /api/. The API provides programmatic access to nodes, profiles, images, and overlays. Interactive documentation is available at /api/docs.

When TLS is enabled, access to the REST API can additionally be restricted to HTTPS-only requests by setting api: tls: true in warewulf.conf.

See REST API for full details.

Files Route

/files/{path}

Serves static files from the warewulf files directory (wwfilesdir in warewulf.conf, defaulting to /var/lib/warewulf/files). Subdirectories are supported.

Every request must identify a node, either via the ?wwid= query parameter (a hardware address) or by ARP cache lookup of the requesting IP. If no node can be identified, the server returns 401 Unauthorized.

When secure is enabled in warewulf.conf, requests must originate from a privileged port (< 1024); otherwise 403 Forbidden is returned. If the node has an AssetKey configured, the ?assetkey= parameter must be present and match; a missing key returns 401 Unauthorized and an incorrect key returns 403 Forbidden.

# Place files in the warewulf files directory:
$ cp myfile.txt /var/lib/warewulf/files/
$ mkdir -p /var/lib/warewulf/files/scripts
$ cp setup.sh /var/lib/warewulf/files/scripts/

# Fetch from a compute node:
$ curl http://<server>:9873/files/myfile.txt?wwid=00:00:00:00:00:01
$ curl http://<server>:9873/files/scripts/setup.sh?wwid=00:00:00:00:00:01

Directory listing is disabled; requests for a directory path return 404 Not Found.

Template rendering: Adding the ?render query parameter renders the file as a Go template for the identified node, with the same template functions and data available as in overlay templates. Without ?render, files are returned as raw bytes. The path must refer to a .ww template file. If the path does not end in .ww but a .ww-suffixed version exists, that file is used automatically. Using ?render on a path where no .ww file can be found returns 400 Bad Request if the exact file exists, or 404 Not Found if neither form exists.

# Place a template in the files directory:
$ echo 'hostname={{ .Hostname }}' > /var/lib/warewulf/files/info.ww

# Fetch the raw template:
$ curl http://<server>:9873/files/info.ww?wwid=00:00:00:00:00:01

# Fetch the rendered template (explicit .ww suffix):
$ curl 'http://<server>:9873/files/info.ww?render&wwid=00:00:00:00:00:01'

# Fetch the rendered template (implicit .ww suffix):
$ curl 'http://<server>:9873/files/info?render&wwid=00:00:00:00:00:01'

Query parameters: wwid, assetkey, render

Security

Several mechanisms are available to restrict access to provisioning routes.

Asset key validation

If a node is configured with an AssetKey in nodes.conf, the Warewulf server will only respond to provisioning requests that include a matching ?assetkey= query parameter. Requests with a missing or incorrect asset key receive 401 Unauthorized. The asset key is typically a hardware-level firmware string (an “asset tag”) that is accessible only with root or physical access.

# wwctl node set node01 --assetkey "SYSTEM-ASSET-TAG"

Secure mode

When warewulf:secure is set to true in warewulf.conf, the /runtime/ route requires that requests originate from a privileged TCP source port (port number less than 1024). Because only processes running as root can bind to privileged ports, this prevents unprivileged users on a cluster node from downloading the runtime overlay.

TLS

When TLS is enabled in warewulf.conf, the /runtime/ route rejects plain-HTTP requests with 403 Forbidden. Runtime overlays must be fetched over HTTPS. Because iPXE and GRUB cannot handle HTTPS, the kernel, image, and system overlay continue to be served over plain HTTP even when TLS is enabled.

See Security for instructions on enabling TLS and generating certificates.