Configuring User Sync with the Syncuser Overlay in Warewulf 4.6

Introduction

Warewulf 4.6.0 introduced structural changes to how user account data is synchronized across compute nodes. This includes the introduction of a new syncuser overlay and changes in how passwd and group files are managed. These updates are designed to streamline user syncing, but require explicit configuration.

Problem

In Warewulf 4.5.x, user syncing was often handled by embedding /etc/passwd and /etc/group content directly into overlays like generic. Running wwctl overlay build after adding users on the head node was typically enough to propagate changes.

With Warewulf 4.6.x:

• The new syncuser overlay is not automatically included in node profiles.
• wwctl image build no longer syncs users by default — it requires --syncuser.
• User and group files are sourced from sysconfdir (which defaults to /etc), rather than hardcoded paths.
• wwctl image syncuser writes changes by default but doesn't rebuild the image unless --build is used.

Without awareness of these changes, users may find that adding or modifying users on the head node no longer reflects on compute nodes.

Symptoms

• New users are not present on compute nodes after image or overlay rebuild.
• Changes to UIDs/GIDs are ignored, even after re-syncing.
• The syncuser overlay appears empty or is missing if not manually configured.

Resolution

To correctly sync users in Warewulf 4.6:

1. Attach the syncuser overlay to the node profile:

  wwctl profile set <profile> --runtime-overlays <comma,separated,list,of,current,overlays>,syncuser

2. Ensure passwd/group are in sysconfdir (typically /etc/), or symlink them if necessary:

ln -sf /etc/passwd /path/to/sysconfdir/passwd
ln -sf /etc/group /path/to/sysconfdir/group

3. When importing images (previously containers), use the --syncuser flag:

wwctl image import --syncuser docker://<path_to_image>

4. Run image syncuser with --build if you want changes applied immediately:

wwctl image syncuser <image_name> --build

5. Rebuild overlays:

wwctl overlay build

Root Cause

The Warewulf 4.6 update decoupled user syncing from overlays like generic, formalizing it under the new syncuser overlay. This adds clarity and modularity but requires updated workflows. Without explicitly enabling syncuser, user changes on the head node will not propagate.

Notes

• The changelog for v4.6.0 outlines the full syncuser redesign. Refer to it when upgrading or troubleshooting.
• Running wwctl image syncuser without --build updates the image’s user database but does not trigger a rebuild.

References & related articles

Warewulf 4.6.0 Release Notes – Syncuser Section