Reverse proxy amendments 2 (#616)

* Reverse Proxy Doc Amendments

- update custom domains page to more closely reflect wording in the UI, added screenshots
- add warning to index page that reverse proxy feature does not currently work with pre-shared keys/rosenpass

* Update navigation order (move reverse proxy below network routes)

* update migration guide to mention the need for TWO cname records (proxy and proxy wildcard)

Author: shuuri-labs

public/docs-static/img/manage/reverse-proxy/custom-domains-start-verification.png

@@ -156,16 +156,6 @@ export const docsNavigation = [
                     }
                 ]
             },
-            {
-                title: 'Reverse Proxy',
-                isOpen: false,
-                links: [
-                    { title: 'Overview', href: '/manage/reverse-proxy' },
-                    { title: 'Custom Domains', href: '/manage/reverse-proxy/custom-domains' },
-                    { title: 'Authentication', href: '/manage/reverse-proxy/authentication' },
-                    { title: 'Access Logs', href: '/manage/reverse-proxy/access-logs' },
-                ]
-            },
             {
                 title: 'Network Routes',
                 isOpen: false,
@@ -199,6 +189,16 @@ export const docsNavigation = [
                     }
                 ]
             },
+            {
+                title: 'Reverse Proxy',
+                isOpen: false,
+                links: [
+                    { title: 'Overview', href: '/manage/reverse-proxy' },
+                    { title: 'Custom Domains', href: '/manage/reverse-proxy/custom-domains' },
+                    { title: 'Authentication', href: '/manage/reverse-proxy/authentication' },
+                    { title: 'Access Logs', href: '/manage/reverse-proxy/access-logs' },
+                ]
+            },
             {
                 title: 'DNS',
                 isOpen: false,

public/docs-static/img/manage/reverse-proxy/custom-domains-verification.png

@@ -1,11 +1,11 @@
 import {Note} from "@/components/mdx"
 
 export const description =
-    'Configure free and custom domains for NetBird Reverse Proxy services, including CNAME validation and DNS setup.'
+    'Configure free and custom domains for NetBird Reverse Proxy services, including CNAME verification and DNS setup.'
 
 # Custom Domains
 
-When you create a reverse proxy service, you need to assign it a domain. NetBird provides built-in domains that are automatically available for every account, and also supports custom domains where you bring your own domain name. This page explains how both types work and walks you through adding and validating a custom domain.
+When you create a reverse proxy service, you need to assign it a domain. NetBird provides built-in domains that are automatically available for every account, and also supports custom domains where you bring your own domain name. This page explains how both types work and walks you through adding and verifying a custom domain.
 
 ## Built-in domains
 
@@ -43,7 +43,7 @@ Built-in domains are a quick way to get started. They receive automatic TLS cert
 
 ## Custom domains
 
-Custom domains let you use your own domain name (e.g., `app.example.com`) for reverse proxy services. Custom domains work identically in both cloud and self-hosted deployments. Before a custom domain can be used, you must validate ownership by creating a CNAME record in your DNS provider.
+Custom domains let you use your own domain name (e.g., `app.example.com`) for reverse proxy services. Custom domains work identically in both cloud and self-hosted deployments. Before a custom domain can be used, you must verify ownership by creating a CNAME record in your DNS provider.
 
 To manage custom domains, navigate to **Reverse Proxy** > **Custom Domains** in the NetBird dashboard.
 
@@ -61,15 +61,15 @@ Follow these steps to add a custom domain to your account:
     <img src="/docs-static/img/manage/reverse-proxy/custom-domains-add.png" alt="Add Domain modal showing domain name and proxy cluster fields" className="imagewrapper"/>
 </p>
 
-After saving, the domain appears in your list with an **unvalidated** status. You must complete CNAME validation before you can use the domain with a service.
+After saving, the domain appears in your list with a **Pending Verification** status. You must complete CNAME verification before you can use the domain with a service.
 
-## Validating a custom domain
+## Verifying a custom domain
 
 To prove that you own the domain, NetBird requires you to create a specific CNAME record in your DNS provider.
 
 ### Step 1: Create the CNAME record
 
-In your DNS provider, create a CNAME record for the `validation` subdomain of your custom domain, pointing to the proxy cluster address. The CNAME target depends on your deployment type:
+In your DNS provider, create a wildcard CNAME record for your custom domain, pointing to the proxy cluster address. The CNAME target depends on your deployment type:
 
 - **Cloud deployments** - point to a NetBird-hosted cluster address (e.g., `eu.proxy.netbird.io`)
 - **Self-hosted deployments** - point to your own proxy URL (e.g., `proxy.mycompany.com`)
@@ -78,28 +78,34 @@ For example, on a cloud deployment:
 
 | Record Type | Name | Value |
 |-------------|------|-------|
-| `CNAME` | `validation.proxy.example.com` | `eu.proxy.netbird.io` |
+| `CNAME` | `*.proxy.example.com` | `eu.proxy.netbird.io` |
 
 On a self-hosted deployment:
 
 | Record Type | Name | Value |
 |-------------|------|-------|
-| `CNAME` | `validation.proxy.example.com` | `proxy.mycompany.com` |
+| `CNAME` | `*.proxy.example.com` | `proxy.mycompany.com` |
 
-The exact target value depends on the proxy cluster you selected when adding the domain. The NetBird dashboard displays the required CNAME target after you save the domain.
+The exact target value depends on the proxy cluster you selected when adding the domain. The NetBird dashboard displays the required CNAME record and target after you save the domain.
 
-### Step 2: Validate in the dashboard
+### Step 2: Verify in the dashboard
 
-After creating the DNS record, return to the **Reverse Proxy** > **Custom Domains** page and click **Validate** next to the domain.
+After creating the DNS record, return to the **Reverse Proxy** > **Custom Domains** page and click **Verify Domain** next to the domain.
 
 <p>
-    <img src="/docs-static/img/manage/reverse-proxy/custom-domains-validation.png" alt="Domain validation status showing CNAME record details" className="imagewrapper"/>
+    <img src="/docs-static/img/manage/reverse-proxy/custom-domains-verification.png" alt="Domain verification modal showing CNAME record details" className="imagewrapper-big"/>
 </p>
 
-NetBird performs a CNAME lookup on `validation.<your-domain>` and verifies that it resolves to a known proxy cluster. Once validation succeeds, the domain status changes to **validated** and it becomes available in the domain selector when creating or editing services.
+Confirm that the dialog reflects CNAME record you added to your domain provider and click **Start Verification**. 
+
+<p>
+    <img src="/docs-static/img/manage/reverse-proxy/custom-domains-start-verification.png" alt="Start Verification Dialog" className="imagewrapper"/>
+</p>
+
+NetBird performs a CNAME lookup on `*.<your-domain>` and verifies that it resolves to a known proxy cluster. Once verification succeeds, the domain status changes to **Active** and it becomes available in the domain selector when creating or editing services.
 
 <Note>
-    DNS changes can take time to propagate. If validation fails immediately after creating the CNAME record, wait a few minutes and try again. In some cases, DNS propagation can take up to 48 hours depending on your provider and TTL settings.
+    DNS changes can take time to propagate. If NetBird does not find the record immediately, please wait up to 24 hours and try again.
 </Note>
 
 ## Managing custom domains
@@ -108,11 +114,11 @@ The **Custom Domains** page lists all domains associated with your account, incl
 
 ### Viewing domains
 
-The domain list shows each domain along with its type (Free, Cluster, or Custom), the associated proxy cluster, and the current validation status.
+The domain list shows each domain along with its type (Free, Cluster, or Custom), the associated proxy cluster, and the current verification status.
 
-### Re-validating a domain
+### Re-verifying a domain
 
-If a custom domain becomes unvalidated - for example, after a DNS configuration change - you can click **Validate** to trigger a new CNAME lookup.
+If a custom domain returns to **Pending Verification** status - for example, after a DNS configuration change - you can click **Verify Domain** to trigger a new CNAME lookup.
 
 ### Deleting a custom domain
 
@@ -126,7 +132,7 @@ To remove a custom domain, click the delete action next to the domain in the lis
 
 When you create or edit a reverse proxy service, the domain selector presents all available domains:
 
-- All **validated** custom domains
+- All **Active** custom domains
 - All built-in domains - **Free** domains (cloud) or **Cluster** domains (self-hosted)
 
 To assign a domain to a service, enter a **subdomain** on the left side of the selector and choose a **base domain** on the right side. The full public URL for your service is the combination of both:
@@ -141,19 +147,19 @@ All domain types receive automatic TLS certificates managed by the proxy.
 
 ## Troubleshooting
 
-### Domain shows as unvalidated
+### Domain shows as Pending Verification
 
-Verify that the CNAME record for `validation.<your-domain>` is correctly configured and points to the right proxy cluster address. For cloud deployments, this is a NetBird-hosted address (e.g., `eu.proxy.netbird.io`). For self-hosted deployments, this is your own proxy URL (e.g., `proxy.mycompany.com`). Use a DNS lookup tool to confirm the record has propagated:
+Verify that the wildcard CNAME record for `*.<your-domain>` is correctly configured and points to the right proxy cluster address. For cloud deployments, this is a NetBird-hosted address (e.g., `eu.proxy.netbird.io`). For self-hosted deployments, this is your own proxy URL (e.g., `proxy.mycompany.com`). Use a DNS lookup tool to confirm the record has propagated:
 
 ```bash
-dig CNAME validation.proxy.example.com
+dig CNAME *.proxy.example.com
 ```
 
 If the record does not appear, check your DNS provider for typos or wait for propagation to complete.
 
 ### CNAME pointing to the wrong cluster
 
-The CNAME record must resolve to one of your available proxy clusters. If you selected a different cluster when adding the domain, the validation lookup will fail. Verify the expected target value on the Custom Domains page in the dashboard and update your DNS record accordingly.
+The CNAME record must resolve to one of your available proxy clusters. If you selected a different cluster when adding the domain, the verification lookup will fail. Verify the expected target value on the Custom Domains page in the dashboard and update your DNS record accordingly.
 
 ### Domain already in use
 

src/components/NavigationDocs.jsx

@@ -1,4 +1,4 @@
-import {Note} from "@/components/mdx"
+import {Note, Warning} from "@/components/mdx"
 
 export const description =
     'Expose internal services to the public internet with automatic TLS, authentication, and traffic routing through the NetBird mesh network.'
@@ -13,6 +13,9 @@ NetBird Reverse Proxy lets you expose internal services running on peers or behi
 <Note>
     **Self-hosted requirement:** Self-hosted deployments **must** use [Traefik](/selfhosted/reverse-proxy) as their reverse proxy. Traefik is the only supported reverse proxy that provides TLS passthrough, which is required for the Reverse Proxy feature to function correctly.
 </Note>
+<Warning>
+    The Reverse Proxy feature does not currently support pre-shared keys or Rosenpass. If your network relies on either of these features, reverse proxy services will not function as expected.
+</Warning>
 
 ## How it works
 

src/pages/manage/reverse-proxy/custom-domains.mdx

@@ -150,15 +150,16 @@ The Traefik labels configure a **TCP router** that:
 The `HostSNI(*)` rule acts as a catch-all for any domain not matched by the existing NetBird HTTP routers. The `priority=1` ensures this TCP router only handles traffic that no other router claims. Any domain pointing to your server that isn't `netbird.example.com` will be forwarded to the proxy.
 </Note>
 
-### Step 4: Set up wildcard DNS
+### Step 4: Set up DNS records
 
-Create a wildcard DNS record pointing to the server running your NetBird stack:
+Create two DNS records pointing to the server running your NetBird stack — one for the base proxy domain and one wildcard for service subdomains:
 
-```
-*.proxy.example.com  →  <your-server-IP>
-```
+| Type | Name | Content |
+|------|------|---------|
+| `CNAME` | `proxy.example.com` | `netbird.example.com` |
+| `CNAME` | `*.proxy.example.com` | `netbird.example.com` |
 
-This ensures that all service subdomains (e.g., `myapp.proxy.example.com`, `dashboard.proxy.example.com`) resolve to your server where Traefik forwards them to the proxy container.
+The base domain record is required because a wildcard DNS record does not cover the bare domain itself. The wildcard record ensures that all service subdomains (e.g., `myapp.proxy.example.com`, `dashboard.proxy.example.com`) resolve to your server where Traefik forwards them to the proxy container.
 
 ### Step 5: Apply changes