Reverse Proxy: document multiple L4 port mappings

[heywander]

What this documents

• multiple TCP, UDP, and TLS passthrough mappings in one L4 service
• single ports, inclusive ranges, and listener-to-destination translation
• compatible HTTP/TCP/UDP hostname sharing and the TLS passthrough restriction
• Docker Compose and firewall publication for self-hosted listener ranges

Related implementation

• Backend: [management, proxy] Support multiple L4 port mappings per reverse-proxy domain netbird#6842
• Dashboard: [reverse-proxy] Support multiple port mappings per service dashboard#723
• Issue: L4-Reverse Proxy: Allow forwarding of multiple ports/ranges for one subdomain. netbird#5821

Validation

• npm run lint:mdx
• git diff --check

---

^{Need help on this PR? Tag /codesmith with what you need. Autofix is disabled.}

Summary by CodeRabbit

• Documentation
  • Clarified how to configure L4 reverse-proxy port mappings, including protocols and listener-to-destination port ranges.
  • Documented port conflict, ownership, automatic assignment, and hostname-sharing rules.
  • Updated migration guidance for exposing TCP, UDP, and TLS ports through the proxy and firewall.
  • Clarified that HTTP and TLS passthrough continue using port 443, while additional listeners require explicit publication.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 51145147-ba06-47ab-bd2e-477eb028d082

📥 Commits

Reviewing files that changed from the base of the PR and between 43b53a2 and ffce393.

📒 Files selected for processing (2)

• src/pages/manage/reverse-proxy/index.mdx
• src/pages/selfhosted/migration/enable-reverse-proxy.mdx

---

📝 Walkthrough

Walkthrough

Reverse proxy documentation now defines L4 port mappings and hostname-sharing behavior, and updates self-hosted migration instructions for publishing listener ports through the proxy container and host firewall.

Changes

Reverse proxy documentation

Layer / File(s)	Summary
L4 mapping and hostname rules src/pages/manage/reverse-proxy/index.mdx	Service setup now uses protocol-aware port mappings, documents range validation and listener ownership rules, and explains compatible hostname sharing.
Self-hosted listener exposure src/pages/selfhosted/migration/enable-reverse-proxy.mdx	Migration guidance adds generalized proxy port mappings, matching container ranges, firewall or VPS security-group requirements, and explicit publishing rules for additional listeners.

Estimated code review effort: 2 (Simple) | ~10 minutes

Suggested reviewers: techhuttv

Poem

A rabbit maps ports in a neat little row,
TCP and UDP know where they should go.
Hostnames share gently, TLS joins the parade,
Firewalls open where listener paths are laid.
“Hop!” says the bunny, “the proxy is upgraded!”

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately and concisely summarizes the main documentation change about multiple L4 port mappings.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

src/pages/manage/reverse-proxy/index.mdx

Oops! Something went wrong! :(

ESLint: 9.39.2

TypeError: Converting circular structure to JSON
--> starting at object with constructor 'Object'
| property 'configs' -> object with constructor 'Object'
| property 'flat' -> object with constructor 'Object'
| ...
| property 'plugins' -> object with constructor 'Object'
--- property 'react' closes the circle
Referenced from:
at JSON.stringify ()
at file:///node_modules/@eslint/eslintrc/lib/shared/config-validator.js:308:45
at Array.map ()
at ConfigValidator.formatErrors (file:///node_modules/@eslint/eslintrc/lib/shared/config-validator.js:299:23)
at ConfigValidator.validateConfigSchema (file:///node_modules/@eslint/eslintrc/lib/shared/config-validator.js:330:84)
at ConfigArrayFactory._normalizeConfigData (file:///node_modules/@eslint/eslintrc/lib/config-array-factory.js:676:19)
at ConfigArrayFactory._loadConfigData (file:///node_modules/@eslint/eslintrc/lib/config-array-factory.js:641:21)
at ConfigArrayFactory._loadExtendedShareableConfig (file:///node_modules/@eslint/eslintrc/lib/config-array-factory.js:946:21)
at ConfigArrayFactory._loadExtends (file:///node_modules/@eslint/eslintrc/lib/config-array-factory.js:814:25)
at ConfigArrayFactory._normalizeObjectConfigDataBody (file:///node_modules/@eslint/eslintrc/lib/config-array-factory.js:752:25)

src/pages/selfhosted/migration/enable-reverse-proxy.mdx

Oops! Something went wrong! :(

ESLint: 9.39.2

TypeError: Converting circular structure to JSON
--> starting at object with constructor 'Object'
| property 'configs' -> object with constructor 'Object'
| property 'flat' -> object with constructor 'Object'
| ...
| property 'plugins' -> object with constructor 'Object'
--- property 'react' closes the circle
Referenced from:
at JSON.stringify ()
at file:///node_modules/@eslint/eslintrc/lib/shared/config-validator.js:308:45
at Array.map ()
at ConfigValidator.formatErrors (file:///node_modules/@eslint/eslintrc/lib/shared/config-validator.js:299:23)
at ConfigValidator.validateConfigSchema (file:///node_modules/@eslint/eslintrc/lib/shared/config-validator.js:330:84)
at ConfigArrayFactory._normalizeConfigData (file:///node_modules/@eslint/eslintrc/lib/config-array-factory.js:676:19)
at ConfigArrayFactory._loadConfigData (file:///node_modules/@eslint/eslintrc/lib/config-array-factory.js:641:21)
at ConfigArrayFactory._loadExtendedShareableConfig (file:///node_modules/@eslint/eslintrc/lib/config-array-factory.js:946:21)
at ConfigArrayFactory._loadExtends (file:///node_modules/@eslint/eslintrc/lib/config-array-factory.js:814:25)
at ConfigArrayFactory._normalizeObjectConfigDataBody (file:///node_modules/@eslint/eslintrc/lib/config-array-factory.js:752:25)

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}