[docs-scanner] Confusing historical limitation framing in rootless troubleshooting
Nobody has claimed this yet.
- Dominant language
- Markdown
- Stars
- 4.7k
- Forks
- 8.5k
- Avg merge
- 2d 18h
- Merged PRs (30d)
- 108
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
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.
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.
Assessment
- Tech stack
- docker
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 1/5
- Estimated time
- Under an hour
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 90/100