From eb6ce7d86c0615543a6acef8933726283d643a29 Mon Sep 17 00:00:00 2001 From: Jonathon Anderson Date: Tue, 11 Feb 2025 09:48:33 -0700 Subject: [PATCH] Update syncuser documentation Signed-off-by: Jonathon Anderson --- CHANGELOG.md | 3 ++- userdocs/contents/images.rst | 35 ++++++++++++++++++---------------- userdocs/contents/overlays.rst | 8 +++++--- 3 files changed, 26 insertions(+), 20 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d21e08e6..9c61077b 100644 --- a/CHANGELOG.md +++ b/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 [--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 diff --git a/userdocs/contents/images.rst b/userdocs/contents/images.rst index 60d10e73..253b2b58 100644 --- a/userdocs/contents/images.rst +++ b/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 =========================== diff --git a/userdocs/contents/overlays.rst b/userdocs/contents/overlays.rst index 5587fcba..5b465258 100644 --- a/userdocs/contents/overlays.rst +++ b/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