[docs-scanner] Confusing historical limitation framing in rootless troubleshooting

Open Beginner friendly
#25,968 0 comments 0 reactions 0 assignees View on GitHub

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=host were not reachable from the real host network namespace.

Followed by:

--net=host doesn't listen ports on the host network namespace

This was an expected behavior until Docker Engine v29.5, as the daemon was namespaced inside RootlessKit's
network namespace. Use docker run -p instead, 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:

  1. 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
  2. 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
  3. It's unclear whether --net=host now works correctly in v29.5+ or if users should still use docker run -p as 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from docker/docs

All issues in docker/docs

Similar issues

More Documentation issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.