Adding Static /etc/hosts Entries to Warewulf Compute Nodes

Introduction

Warewulf builds each node's /etc/hosts from the hosts overlay, not from the copy of the file on the Warewulf server. Anything you need a node to resolve that Warewulf does not already generate, such as storage or GPFS/PixStor servers, a license server, or an NFS head, has to go into that overlay.

This article shows the supported way to add those static entries so they reach every node. It targets Warewulf 4.6.x and later (including CIQ Warewulf Pro). A note at the end covers the 4.5.x layout, where the same file lives in a different overlay.

Problem

You need compute nodes to resolve a set of fixed hostnames that are not part of the Warewulf cluster itself, such as a storage fabric:

192.168.50.5    nas-mgmt
192.168.50.10   nas01
192.168.50.11   nas02

Adding them to /etc/hosts on the Warewulf server does not work. That file is the server's own, and wwctl configure hostfile only rewrites that server-side copy, so after a rebuild cat /etc/hosts on a booted compute node still shows just the loopback and auto-generated cluster entries.

Resolution

In Warewulf 4.6.x and later, /etc/hosts is produced by the distribution overlay named hosts. The hosts overlay is carried by the default profile, which Warewulf assigns to a node when it is created, so on a normal cluster every node already pulls it. That makes the overlay the right place for your static entries. Editing it creates a local site overlay that shadows the shipped one, which keeps your change and survives package updates (Warewulf never modifies a distribution overlay in place).

Edit the overlay's template file:

wwctl overlay edit hosts /etc/hosts.ww

This opens a copy of the shipped template. It already contains the loopback lines, the Warewulf server entry, and the loop that generates an entry for every node. Leave that content in place and add your static entries at the bottom, below the templated block:

# Static storage fabric entries
192.168.50.5    nas-mgmt
192.168.50.10   nas01
192.168.50.11   nas02

Save and exit, then rebuild the overlays:

wwctl overlay build

Because hosts is a runtime overlay, nodes pick up the change on the next runtime-overlay refresh without a reboot or reprovision. To force it immediately on a node, reboot it or restart wwclient there.

Verify

Confirm a site overlay was created (the SITE column reads true):

wwctl overlay list --all hosts

Render the template as it will appear on a specific node and confirm your entries are present:

wwctl overlay show hosts /etc/hosts.ww --render=node001

Then, on the node itself:

grep nas /etc/hosts

Notes

⚠️ WARNING wwctl node set and wwctl profile set --runtime-overlays (short flag -R) replace the target's overlay list, they do not append. A node's effective overlays are the union of the lists from every profile it carries plus its own node-level list, so overwriting one of those lists with just your new overlay can strip overlays the node depends on, such as ssh.authorized_keys (which delivers SSH key-based login). If you go the separate-overlay route instead of editing hosts, carry the existing names in the same command, for example wwctl node set node001 --runtime-overlays hosts,ssh.authorized_keys,myhosts. Editing the hosts overlay as shown above touches no overlay list and avoids this risk entirely.

• Template files must end in .ww. The .ww suffix is what marks a file as a template. Editing /etc/hosts.ww (as wwctl overlay edit hosts /etc/hosts.ww does) keeps templating working. A file named /etc/hosts with no suffix is copied verbatim and any template directives in it are ignored.
• A node only pulls the overlays its profiles list. A node builds its overlays from the union of the profiles it carries plus its node-level list. If wwctl overlay show hosts /etc/hosts.ww --render=node001 contains your entries but the node still does not, confirm the node actually carries the hosts overlay with wwctl node list node001 --all (look for hosts in the runtime and system overlay lists). A node whose profiles do not include default will not pull hosts at all; add it (keeping the existing names, per the warning above) or assign the profile that carries it.
• A site overlay pins the template. Once you edit hosts, your site copy shadows the shipped one completely, so it will not pick up future improvements to the distribution hosts template. Re-check it after a major Warewulf upgrade.
• Warewulf 4.5.x layout. Before 4.6.0, /etc/hosts.ww shipped inside the generic overlay rather than a dedicated hosts overlay. On 4.5.x, edit it with wwctl overlay edit generic /etc/hosts.ww and then wwctl overlay build. The same rule about not replacing the runtime overlay list applies.

Root Cause

/etc/hosts on a Warewulf node is rendered from the hosts overlay at build time and delivered with the runtime and system overlays. The copy on the Warewulf server is not the source for node content, and wwctl configure hostfile only rewrites that server-side file, so edits there never propagate. Placing the entries in the hosts overlay puts them in the path that is actually built and applied to each node that carries it.

References & related articles

Warewulf Documentation - Overlays
Overlay Management Issues while Upgrading to Warewulf Version 4.6.x