Skip to content

docs: add AllowTcpForwarding prerequisite to Hetzner SSH tunnel step#54564

Merged
vincentkoc merged 1 commit into
openclaw:mainfrom
satishkc7:docs/hetzner-ssh-tcp-forwarding
Apr 29, 2026
Merged

docs: add AllowTcpForwarding prerequisite to Hetzner SSH tunnel step#54564
vincentkoc merged 1 commit into
openclaw:mainfrom
satishkc7:docs/hetzner-ssh-tcp-forwarding

Conversation

@satishkc7

Copy link
Copy Markdown
Contributor

Summary

  • Problem: The Hetzner guide recommends accessing the gateway via SSH tunnel but does not mention that AllowTcpForwarding must be enabled in the VPS sshd config for this to work.
  • Why it matters: Users with hardened SSH configs hit a silent, cryptic failure - channel 3: open failed: administratively prohibited: open failed - with no indication that sshd config is the cause.
  • What changed: Added a prerequisite note to the SSH tunnel step in the Hetzner guide explaining the AllowTcpForwarding setting, the exact error they will see if it is disabled, and a systemctl restart sshd reminder.
  • What did NOT change: No code changes. Docs only.

Change Type (select all)

  • Bug fix
  • Feature
  • Refactor required for the fix
  • Docs
  • Security hardening
  • Chore/infra

Scope (select all touched areas)

  • Gateway / orchestration
  • Skills / tool execution
  • Auth / tokens
  • Memory / storage
  • Integrations
  • API / contracts
  • UI / DX
  • CI/CD / infra

Linked Issue/PR

Root Cause / Regression History (if applicable)

N/A - docs gap, not a regression.

Regression Test Plan (if applicable)

N/A

User-visible / Behavior Changes

Users following the Hetzner guide now see a prerequisite note about AllowTcpForwarding before the tunnel command.

Security Impact (required)

  • New permissions/capabilities? No
  • Secrets/tokens handling changed? No
  • New/changed network calls? No
  • Command/tool execution surface changed? No
  • Data access scope changed? No

Repro + Verification

Environment

  • OS: Hetzner Ubuntu 22.04 VPS with hardened sshd config
  • Runtime/container: N/A (docs only)

Steps

  1. Follow Hetzner guide with hardened sshd (AllowTcpForwarding no)
  2. Run ssh -N -L 18789:127.0.0.1:18789 root@YOUR_VPS_IP
  3. See channel 3: open failed: administratively prohibited: open failed

Expected

  • Docs warn about this requirement before the tunnel command

Actual (before fix)

  • No mention of AllowTcpForwarding anywhere in the guide

Evidence

Human Verification (required)

  • Verified scenarios: confirmed the exact error message matches the issue report and that AllowTcpForwarding local is the minimal safe setting for this use case
  • Edge cases checked: AllowTcpForwarding yes also works but is broader than needed; local is the right recommendation for this setup
  • What you did not verify: live VPS test (docs-only change)

Review Conversations

  • I replied to or resolved every bot review conversation I addressed in this PR.
  • I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

  • Backward compatible? Yes
  • Config/env changes? No
  • Migration needed? No

Failure Recovery (if this breaks)

  • How to disable/revert this change quickly: Revert docs/install/hetzner.md
  • Known bad symptoms reviewers should watch for: None

Risks and Mitigations

None - docs-only change.

@openclaw-barnacle openclaw-barnacle Bot added docs Improvements or additions to documentation size: XS labels Mar 25, 2026
@greptile-apps

greptile-apps Bot commented Mar 25, 2026

Copy link
Copy Markdown
Contributor

Greptile Summary

This docs-only PR fills a real gap in the Hetzner guide: users with hardened SSH configs hit a cryptic channel 3: open failed: administratively prohibited error when running the SSH tunnel because AllowTcpForwarding is disabled. The added prerequisite block is technically accurate — AllowTcpForwarding local is the minimal correct setting for ssh -L, the quoted error string matches the real sshd rejection, and systemctl restart sshd is the right follow-up.

  • The technical content (AllowTcpForwarding local, error message, restart command) is all correct.
  • One minor readability issue: the existing opener "After the shared build and launch steps, tunnel from your laptop:" now leads into a prerequisite block rather than directly to the tunnel command, making the phrase appear twice in close succession. A one-word change to that opener (see inline comment) would clean this up.

Confidence Score: 5/5

  • Safe to merge — docs-only change with accurate technical content and no code impact.
  • All technical details are correct, the change directly addresses a known user pain-point, and the only issue is a minor phrasing redundancy that does not affect correctness or user safety.
  • No files require special attention.
Prompt To Fix All With AI
This is a comment left during a code review.
Path: docs/install/hetzner.md
Line: 211

Comment:
**Introductory sentence now misleads**

Line 211 still reads "…tunnel from your laptop:" as if the tunnel command immediately follows, but the new prerequisite block is inserted in between. The phrase appears again at line 225 ("…and run the tunnel from your laptop:"), so the opener reads as redundant and misleading.

```suggestion
    After the shared build and launch steps, complete the following setup to open the tunnel:
```

How can I resolve this? If you propose a fix, please make it concise.

Reviews (1): Last reviewed commit: "docs: add AllowTcpForwarding prerequisit..." | Re-trigger Greptile

Comment thread docs/install/hetzner.md Outdated
@vincentkoc

Copy link
Copy Markdown
Member

ProjectClownfish pushed a narrow repair to this branch so the original contributor path can stay canonical.

Source PR: #54564
Validation: pnpm check:changed
Contributor credit is preserved in the branch history and PR context.

@clawsweeper

clawsweeper Bot commented Apr 28, 2026

Copy link
Copy Markdown
Contributor

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve.

Keep this PR open. Current main still documents the Hetzner SSH tunnel without the requested AllowTcpForwarding local prerequisite or the administratively prohibited failure symptom, and the latest release tag lacks it too. The PR is a narrow docs/changelog patch tied to the already-closed report #54557, with no security-sensitive file changes in the provided diff.

Best possible solution:

Keep this PR open for maintainer review and merge, or land an equivalent docs/changelog change that adds AllowTcpForwarding local before the Hetzner SSH tunnel command, mentions the administratively prohibited failure symptom, and preserves credit for the related reports #54557 and #54954.

What I checked:

  • Current main lacks the requested Hetzner guidance: At current checkout a820a307dfeb950fa633c0ae6fb2386a35a91991, the Hetzner-specific access step goes directly from “tunnel from your laptop” to the ssh -N -L 18789:127.0.0.1:18789 root@YOUR_VPS_IP command, with no AllowTcpForwarding, sshd_config, restart, or administratively prohibited text. Public docs: docs/install/hetzner.md. (docs/install/hetzner.md:220, a820a307dfeb)
  • Targeted repository search found no landed equivalent: Searches for AllowTcpForwarding, administratively prohibited, sshd_config, TCP-forwarding phrasing, and the Hetzner tunnel command found SSH tunnel references but no landed docs/changelog text for the requested prerequisite or failure symptom. (a820a307dfeb)
  • Latest release lacks the docs fix: The latest release tag v2026.4.26 contains the same Hetzner access step without the TCP-forwarding prerequisite or failure symptom, so this is not already shipped. Public docs: docs/install/hetzner.md. (docs/install/hetzner.md:220, be8c24633aaa)
  • OpenSSH behavior supports the proposed setting: The local sshd_config manpage says AllowTcpForwarding accepts yes/all/no/local/remote, and that local allows local forwarding only while remote allows remote forwarding only, matching the PR’s ssh -L tunnel use case.
  • PR scope and security review: The provided PR metadata shows only CHANGELOG.md and docs/install/hetzner.md changed, adding the AllowTcpForwarding local prerequisite, the failure string, and restart guidance. It does not touch workflows, scripts, lockfiles, dependency sources, publishing metadata, secrets handling, generated/vendor code, or executable install/build paths. (docs/install/hetzner.md:218, cbb259691e5c)
  • History and routing evidence: Current-main blame and git log -S for the Hetzner access heading and tunnel command point to 7b2b0d07e84e3e124bdd55747f30ca4946e15edd, authored by Peter Steinberger. The PR timeline also records Vincent’s narrow branch repair at cbb259691e5c7939d17b3ce791f5dfd872d6759a. Public docs: docs/install/hetzner.md. (docs/install/hetzner.md:220, 7b2b0d07e84e)

Likely related people:

  • steipete: Current-main blame and git log -S for the Hetzner access block point to Peter Steinberger’s recent docs import/update commit, and the latest release tag inspected for this surface is also under his release history. (role: current docs path maintainer; confidence: high; commits: 7b2b0d07e84e, be8c24633aaa; files: docs/install/hetzner.md, CHANGELOG.md)
  • vincentkoc: The PR timeline says Vincent pushed the narrow branch repair to preserve the contributor path, and the provided PR metadata identifies cbb259691e5c7939d17b3ce791f5dfd872d6759a as the current PR head touching the Hetzner docs and changelog. (role: recent maintainer follow-up; confidence: medium; commits: cbb259691e5c; files: docs/install/hetzner.md, CHANGELOG.md)

Remaining risk / open question:

  • Closing this PR now would drop an active docs/changelog patch for a gap that still exists in current main and in v2026.4.26.
  • The content is SSH hardening guidance, so maintainers should still review the final wording and distro-appropriate restart command before merge; no supply-chain or executable-path risk was found in the provided diff.

Codex review notes: model gpt-5.5, reasoning high; reviewed against a820a307dfeb.

@vincentkoc vincentkoc added clawsweeper Tracked by ClawSweeper automation and removed clownfish:merge-ready labels Apr 28, 2026
@vincentkoc vincentkoc self-assigned this Apr 29, 2026
@vincentkoc vincentkoc force-pushed the docs/hetzner-ssh-tcp-forwarding branch from cbb2596 to e3a4a0a Compare April 29, 2026 03:14
@vincentkoc vincentkoc merged commit ab5c802 into openclaw:main Apr 29, 2026
38 checks passed
github-actions Bot pushed a commit to Desicool/openclaw that referenced this pull request May 9, 2026
github-actions Bot pushed a commit to Desicool/openclaw that referenced this pull request May 24, 2026
jameslcowan pushed a commit to jameslcowan/openclaw that referenced this pull request Jun 2, 2026
sablehead pushed a commit to sablehead/openclaw that referenced this pull request Jun 10, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

clawsweeper Tracked by ClawSweeper automation docs Improvements or additions to documentation size: XS triage: low-signal-docs Candidate: docs-only change looks low signal; maintainer review needed.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Feature]: Hetzner guide: SSH tunnel requires AllowTcpForwarding to be enabled in sshd config

3 participants