docker / docker/docs

[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.

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=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

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.

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.