[docs-scanner] Confusing historical limitation framing in rootless troubleshooting
Nobody has claimed this yet.
Assessment
- Difficulty
- 1/5
- Estimated time
- Under an hour
- Newbie friendliness
- 90/100
- Issue type
- Documentation
- Clarity
- Clearly specified
- Activity status
- Active
- Tech stack
- docker
- Domain
- documentation
Research direction
Open content/manuals/engine/security/rootless/troubleshoot.md and review the "Historical limitations" and --net=host troubleshooting sections. Update the wording so Docker Engine v29.5 and later behavior is clear, while preserving the workaround guidance for older versions if needed. Done means readers are not told to upgrade unnecessarily or left unsure whether --net=host works on current versions.
Written by the indexing model from the issue text.
Description
File: content/manuals/engine/security/rootless/troubleshoot.md
Issue
The "Historical limitations" section contains confusing guidance about Docker Engine v29.5 behavior:
Until Docker Engine v29.5
- Host network (
docker run --net=host) was namespaced inside RootlessKit.
This meant that ports listened by containers with--net=hostwere not reachable from the real host network namespace.
Followed by:
--net=hostdoesn't listen ports on the host network namespaceThis was an expected behavior until Docker Engine v29.5, as the daemon was namespaced inside RootlessKit's
network namespace. Usedocker run -pinstead, or upgrade to Docker Engine v29.5 or later.
Why this matters
Readers on Docker Engine v29.5 or later (current version is v29.7.2) will be confused by this framing:
- The "Historical limitations" section header suggests this is past behavior, but the subsection title "Until Docker Engine v29.5" doesn't clearly indicate what the current behavior is
- The troubleshooting entry says "upgrade to Docker Engine v29.5 or later" which implies readers might still need to upgrade, even though v29.5 was released months ago
- It's unclear whether
--net=hostnow works correctly in v29.5+ or if users should still usedocker run -pas a workaround
Suggested fix
Restructure to make the current behavior clear:
In the "Historical limitations" section:
#### Until Docker Engine v29.5
- Host network (`docker run --net=host`) was namespaced inside RootlessKit.
This meant that ports listened by containers with `--net=host` were not reachable from the real host network namespace.
**This limitation was resolved in Docker Engine v29.5.**
In the troubleshooting section, either remove the entry entirely (since it's no longer an issue) or update it to:
#### `--net=host` doesn't listen ports on the host network namespace
If you're using Docker Engine v29.4 or earlier, `--net=host` was namespaced inside RootlessKit's network namespace. Upgrade to Docker Engine v29.5 or later to resolve this limitation, or use `docker run -p` as a workaround.
Found by nightly documentation quality scanner
- Dominant language
- Markdown
- Stars
- 4.7k
- Forks
- 8.5k
- Avg merge
- 2d 16h
- Merged PRs (30d)
- 107
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from docker/docs
-
Difficulty 1/5 1-3 hours Newbie friendliness 88/100
-
Difficulty 1/5 Under an hour Newbie friendliness 95/100
-
Difficulty 1/5 Under an hour Newbie friendliness 95/100
-
Difficulty 1/5 Under an hour Newbie friendliness 92/100
-
status/triage
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
Similar issues
-
documentation
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
githubnext/gh-aw-workshop#3692 ·
-
agent/guide documentation hive/hosted-available-lke648397-260827-5n31
Difficulty 2/5 1-3 hours Newbie friendliness 90/100
-
kind/bug
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
falcosecurity/falco-website#1601 ·
-
documentation
Difficulty 2/5 Half a day Newbie friendliness 62/100
inmanta/inmanta-core#10835 ·
-
Difficulty 1/5 Under an hour Newbie friendliness 88/100
k3s-io/k3s-ansible#566 ·