Skip to content

docs: explain install-time UID binding under no multi-user support #568

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
joe0BAB merged 1 commit into from
Jun 26, 2026
Merged

docs: explain install-time UID binding under no multi-user support #568

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 7 additions & 5 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -295,16 +295,18 @@ actively working to address them.
- **No multi-user support.** A single Docker Engine is shared by every user on
the host, but Secrets Engine runs as a per-user daemon. When multiple users
are logged in and using the same engine in parallel, the engine cannot
reliably route a resolution request to the right user's daemon.
reliably route a resolution request to the right user's daemon. As a
consequence, the user the daemon talks to is fixed at install time: the
package's post-install script records the installing user's UID (resolved from
`$SUDO_UID`, i.e. the user who ran `sudo apt install` / `sudo dnf install`)

@docker-agent docker-agent Jun 26, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[MEDIUM] $SUDO_UID edge case insufficiently documented for automated installs

The new text describes the happy path — sudo apt install / sudo dnf install run interactively by a user — but $SUDO_UID is unset whenever the package is installed as root directly (e.g., apt install in a Dockerfile, an Ansible playbook, a CI/CD pipeline, or any tool that invokes the package manager as root without sudo). In those cases the post-install script silently falls through to the "integration stays inert" path, with no visible indication to the operator of why.

The fallback sentence is present but phrased passively; it doesn't call out that automated/root installs are the primary trigger. Consider adding a parenthetical such as:

(This includes installs run directly as root, e.g., in CI/CD or configuration management — $SUDO_UID is only set when using sudo interactively.)

into `/etc/docker/nri/conf.d/10-secrets-engine.conf`. If the UID
cannot be determined at install time, the config is left unset and the integration stays inert until it is
configured manually.
- **Requires a keyring backend.** The daemon depends on D-Bus together with a
Secret Service provider (GNOME Keyring or KWallet). On hosts where these are
missing — typically headless or server installs — the daemon currently crashes
instead of degrading gracefully. We are working on a fix; in the meantime, the
workaround is to install and set up D-Bus and either GNOME Keyring or KWallet.
- **No automatic restart after a `dockerd` restart.** When the Docker Engine is

@docker-agent docker-agent Jun 26, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[MEDIUM] Silent removal of documented limitation may mislead users

The **No automatic restart after a \dockerd` restart.**bullet — which previously documented that the Secrets Engine daemon must be manually restarted viasystemctl --user restart docker-secrets-engine` after an engine restart — has been silently deleted with no explanation.

If this limitation was fixed by other changes, a brief note (e.g., "this limitation was resolved in …") would reassure users. If the limitation still exists, removing it leaves users without the workaround and could cause them to believe injection continues automatically after a dockerd restart. Either way, a silent removal of an operational known-issue entry is misleading for anyone consulting this section for troubleshooting.

Consider either:

  • Adding a note that this limitation was resolved, or
  • Keeping the bullet (or a condensed version) if it still applies.

restarted, the Secrets Engine daemon must be restarted manually
(`systemctl --user restart docker-secrets-engine`) for injection to keep
working.

## Legal

Expand Down
Loading