kelvin/warewulf
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Clarify functionality of syncuser commands and overlay in documentation

Browse Source 
Signed-off-by: Jonathon Anderson <janderson@ciq.com>
This commit is contained in:
Jonathon Anderson
2026-03-18 13:19:01 -06:00
parent 7909598a3d
commit 4f506e1b16
4 changed files with 59 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files

53
userdocs/images/syncuser.rst
View File

@@ -2,21 +2,37 @@
Syncuser
========
Warewulf can optionally synchronize UIDs and GIDs from the Warewulf server to an
image. This can be particularly useful when there is no central directory (e.g.,
an LDAP server).
Warewulf's syncuser feature has two distinct parts that work together:
1. The **syncuser command** synchronizes UIDs and GIDs from the Warewulf server
into an OS image, updating ``/etc/passwd``, ``/etc/group``, and file
ownerships within the image.
2. The **syncuser overlay** merges users and groups from both the OS image and
the Warewulf server into the provisioned node's ``/etc/passwd`` and
``/etc/group`` at runtime.
This is particularly useful when there is no central directory (e.g., an LDAP
server). Together, these two parts ensure that UIDs and GIDs are consistent
across the server and all cluster nodes.
.. note::
Some system services (notably "munge") require a user to have the same UID across all nodes.
Combined with the "syncuser" overlay, Warewulf syncuser also supports defining
local users on the Warewulf server for synchronization to cluster nodes.
Some system services (notably "munge") require a user to have the same UID
across all nodes.
If there is a mismatch between the server and the image, the import command will
generate a warning.
Synchronizing UIDs/GIDs in an OS image
--------------------------------------
Syncuser may be invoked during image import, exec, shell, or build.
The syncuser command updates an OS image so that any user or group present on
the Warewulf server has the same UID/GID inside the image. Users and groups
that exist only in the image are preserved unless a UID/GID collision is
detected. File ownerships within the image are also updated to match.
If there is a mismatch between the server and the image, the import command
will generate a warning.
Syncuser may be invoked during image import, exec, shell, or build:
.. code-block:: console
@@ -26,5 +42,18 @@ Syncuser may be invoked during image import, exec, shell, or build.
# wwctl image build --syncuser rockylinux-9
# wwctl image syncuser rockylinux-9
After syncuser, ``/etc/passwd`` and ``/etc/group`` in the image are updated, and
permissions on files belonging to these UIDs and GIDs are updated to match.
After syncuser, ``/etc/passwd`` and ``/etc/group`` in the image are updated,
and permissions on files belonging to these UIDs and GIDs are updated to match.
The syncuser overlay
--------------------
The syncuser overlay runs at provisioning time and merges ``/etc/passwd`` and
``/etc/group`` from both the OS image and the Warewulf server. This makes users
defined on the server (but not originally in the image) available on provisioned
nodes.
For the overlay to work correctly, the image should also have been prepared with
the syncuser command (see above) so that UID/GID values are consistent.
See :ref:`Syncuser` in the overlays documentation for more detail.

10
userdocs/overlays/overlays.rst
View File

@@ -353,12 +353,14 @@ Two SSH overlays configure host keys (one set for all nodes in the cluster) and
syncuser
--------
The **syncuser** overlay updates ``/etc/passwd`` and ``/etc/group`` to include
all users on both the Warewulf server and from the image.
The **syncuser** overlay updates ``/etc/passwd`` and ``/etc/group`` at
provisioning time to include all users from both the Warewulf server and from
the image.
To function properly, ``wwctl image syncuser`` (or the ``--syncuser`` option
during ``import``, ``exec``, ``shell``, or ``build``) must have also been run on
the image to synchronize its user and group IDs with those of the server.
during ``import``, ``exec``, ``shell``, or ``build``) must also have been run on
the image to synchronize its user and group IDs with those of the server. See
:doc:`/images/syncuser` for details on both parts of the syncuser feature.
If a ``PasswordlessRoot`` tag is set to "true", the overlay will also insert a
"passwordless" root entry. This can be particularly useful for accessing a