Skip to content

docs(rootless): setuptool needs a pam_systemd session #25874

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

Open
locker95 wants to merge 1 commit into
base: main
Choose a base branch
from
+19 −0
Open

docs(rootless): setuptool needs a pam_systemd session #25874

Show file tree
Hide file tree
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
6 changes: 6 additions & 0 deletions content/manuals/engine/security/rootless/_index.md
View file
Open in desktop

@AkihiroSuda AkihiroSuda Sep 8, 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.

We already have helpful error messages in https://github.com/moby/moby/blob/e0c1583c7891b34bd199fdf9e02fb7c7b65bb1ca/contrib/dockerd-rootless-setuptool.sh#L97-L109

Original file line number Diff line number Diff line change
Expand Up @@ -91,6 +91,12 @@ export PATH=/usr/bin:$PATH
export DOCKER_HOST=unix:///run/user/1000/docker.sock
```

Run the installer from a real login session (`ssh` as yourself, or
`machinectl shell $USER@`). `$XDG_RUNTIME_DIR` must be `/run/user/$(id -u)`.
If it is empty or something like `~/.docker/run`, the script cannot see
systemd and tells you to start `dockerd-rootless.sh` by hand. See
[Troubleshooting](./troubleshoot.md#unable-to-install-with-systemd-when-systemd-is-present-on-the-system).

@AkihiroSuda AkihiroSuda Sep 8, 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.

This is lengthy and decreases readability.

"The installer will fail if $XDG_RUNTIME_DIR is not set. See Troubleshooting.` should be enough.


If `dockerd-rootless-setuptool.sh` is not present, you may need to install the `docker-ce-rootless-extras` package manually, e.g.,

```console
Expand Down
13 changes: 13 additions & 0 deletions content/manuals/engine/security/rootless/troubleshoot.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -110,6 +110,19 @@
```
Where `myuser@` is your desired username and @ signifies this machine.

The same "systemd not detected" message appears when `$XDG_RUNTIME_DIR` is
missing or is a fallback such as `~/.docker/run`. On a systemd host it must

@AkihiroSuda AkihiroSuda Sep 8, 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.

"The same" is misleading, as "when $XDG_RUNTIME_DIR is
missing" typically happens when sudo is used

be `/run/user/$(id -u)` so `systemctl --user` can reach the session bus.
Setting `XDG_RUNTIME_DIR` to the path printed by a failed install does not
fix that. Log in with `pam_systemd` first (`ssh`, graphical console, or

Check warning on line 117 in content/manuals/engine/security/rootless/troubleshoot.md

View workflow job for this annotation

GitHub Actions / validate (vale) 

[vale] reported by reviewdog 🐶
[Docker.RecommendedWords] Consider using 'sign in' instead of 'Log in'

Raw Output:
{"message": "[Docker.RecommendedWords] Consider using 'sign in' instead of 'Log in'", "location": {"path": "content/manuals/engine/security/rootless/troubleshoot.md", "range": {"start": {"line": 117, "column": 11}}}, "severity": "INFO"}
`machinectl shell`), then check:

```console
$ echo $XDG_RUNTIME_DIR
/run/user/1000
$ systemctl --user status
```

### Errors when starting the Docker daemon

**\[rootlesskit:parent\] error: failed to start the child: fork/exec /proc/self/exe: operation not permitted**
Expand Down