Update syncuser documentation

Signed-off-by: Jonathon Anderson <janderson@ciq.com>

CHANGELOG.md

@@ -22,7 +22,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - Updated overlay flags to `wwctl <node|profile> <add|set> [--runtime-overlays|--system-overlays]`. #1495
 - syncuser overlay reads host passwd and group database from sysconfdir. #1736
 - syncuser overlay skips duplicate users and groups in passwd and group databases. #829
-- `wwctl image syncuser --write` is true by default.
+- `wwctl image syncuser --write` is true by default. #1736
+- Update syncuser documentation. #1736
 
 ### Fixed
 

userdocs/contents/images.rst

@@ -196,27 +196,30 @@ See ProxyFromEnvironment_ For more information.
 Syncuser
 ========
 
-At import time Warewulf checks if the names of the users on the host
-match the users and UIDs/GIDs in the imported image. If there is
-mismatch, the import command will print out a warning.  By setting the
-``--syncuser`` flag you advise Warewulf to try to syncronize the users
-from the host to the image, which means that ``/etc/passwd`` and
-``/etc/group`` of the imported image are updated and all the files
-belonging to these UIDs and GIDs will also be updated.
+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). Some system services (notably "munge") require a user to have
+the same UID across all nodes.
 
-A check if the users of the host and image matches can be
-triggered with the ``syncuser`` command.
+With the addition of the "syncuser" overlay, Warewulf syncuser also supports
+defining local users on the Warewulf server for synchronization to cluster
+nodes.
+
+If there is mismatch between the server and the image, the import command will
+print out a warning.
+
+Syncuser may be invoked during image import, exec, shell, or build.
 
 .. code-block:: console
 
-   # wwctl image syncuser image-name
+   # wwctl image import --syncuser docker://ghcr.io/warewulf/warewulf-rockylinux:9 rockylinux-9
+   # wwctl image exec --syncuser rockylinux-9 -- /usr/bin/echo "Hello, world!"
+   # wwctl image shell --syncuser rockylinux-9
+   # wwctl image build --syncuser rockylinux-9
+   # wwctl image syncuser rockylinux-9
 
-With the ``--write`` flag it will update the image to match the
-user database of the host as described above.
-
-.. code-block:: console
-
-   wwctl image syncuser --write image-name
+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.
 
 Listing All Imported Images
 ===========================

userdocs/contents/overlays.rst

@@ -157,9 +157,11 @@ syncuser
 --------
 
 The **syncuser** overlay updates ``/etc/passwd`` and ``/etc/group`` to include
-all users on both the Warewulf server and from the image. To function
-properly, ``wwctl image syncuser`` must have also been run on the image
-image to synchronize its user and group IDs with those of the server.
+all users on 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.
 
 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