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 /overlay-file/ and /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 node 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, overlay

  • overlay: A comma-separated list of overlay names. When specified, only the named overlays are served (rather than the node’s full system overlay set).

/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, overlay

  • overlay: A comma-separated list of overlay names. Same behavior as for /system/.

/overlay-file/{overlay}/{path}

Provides direct access to an individual file within a named overlay. This route uses a different URL structure than the other provisioning routes: the overlay name is in the second path segment, and the file path within the overlay follows.

If the render parameter is provided, the file is rendered as a Go template for the specified node and the rendered content is returned. If render is absent, the raw file bytes are returned without any template processing.

If the requested path does not end in .ww but a .ww-suffixed version of the file exists, and a render node is specified, the server automatically serves the .ww template.

Query parameters:

  • render: Node ID to render the template for. If not specified, the raw file is returned.

Note

This route does not require authentication via assetkey and does not perform node lookup by hardware address.

/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.

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, overlay

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.

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.