From 4f506e1b1666cc4c0b0c11478e8e8525565e497f Mon Sep 17 00:00:00 2001 From: Jonathon Anderson Date: Wed, 18 Mar 2026 13:19:01 -0600 Subject: [PATCH] Clarify functionality of syncuser commands and overlay in documentation Signed-off-by: Jonathon Anderson --- CHANGELOG.md | 1 + internal/app/wwctl/image/syncuser/root.go | 17 +++++--- userdocs/images/syncuser.rst | 53 ++++++++++++++++++----- userdocs/overlays/overlays.rst | 10 +++-- 4 files changed, 59 insertions(+), 22 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f99fff5b..b3d312e7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -69,6 +69,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - `hosts` overlay added to the default system overlay list - Distinguish between OS images and overlay images in documentation - Updated `MAINTAINING.md` to document golang version policy +- Clarified functionality of syncuser commands and overlay in documentation ## v4.6.5, 2026-01-12 diff --git a/internal/app/wwctl/image/syncuser/root.go b/internal/app/wwctl/image/syncuser/root.go index 1efae9b0..70ab44b0 100644 --- a/internal/app/wwctl/image/syncuser/root.go +++ b/internal/app/wwctl/image/syncuser/root.go @@ -9,10 +9,15 @@ var ( baseCmd = &cobra.Command{ DisableFlagsInUseLine: true, Use: "syncuser [OPTIONS] IMAGE", - Short: "Synchronizes user in image", - Long: `Synchronize the uids and gids from the host to the image. -Users/groups which are only present in the image will be preserved if no -uid/gid collision is detected. File ownerships are also changed.`, + Short: "Synchronize UIDs/GIDs from the server to an OS image", + Long: `Synchronize UIDs and GIDs from the server into an OS image, updating +/etc/passwd, /etc/group, and file ownerships within the image. Users and +groups that exist only in the image are preserved unless a UID/GID collision +is detected. + +This command affects the image itself (a one-time operation at build/import +time). To also make host users available on provisioned nodes at runtime, add +the "syncuser" overlay to the node or profile.`, RunE: CobraRunE, ValidArgsFunction: func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) { if len(args) != 0 { @@ -29,8 +34,8 @@ uid/gid collision is detected. File ownerships are also changed.`, ) func init() { - baseCmd.PersistentFlags().BoolVar(&write, "write", true, "Synchronize uis/gids and write files in image") - baseCmd.PersistentFlags().BoolVar(&build, "build", false, "Build image after syncuser is completed") + baseCmd.PersistentFlags().BoolVar(&write, "write", true, "Synchronize UIDs/GIDs and write files in OS image") + baseCmd.PersistentFlags().BoolVar(&build, "build", false, "Build OS image after syncuser is completed") } // GetRootCommand returns the root cobra.Command for the application. diff --git a/userdocs/images/syncuser.rst b/userdocs/images/syncuser.rst index 289d90ee..569237b3 100644 --- a/userdocs/images/syncuser.rst +++ b/userdocs/images/syncuser.rst @@ -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. diff --git a/userdocs/overlays/overlays.rst b/userdocs/overlays/overlays.rst index 7d2625c7..9b497389 100644 --- a/userdocs/overlays/overlays.rst +++ b/userdocs/overlays/overlays.rst @@ -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