From b046b65d4ee52776e93debc8dcaf47deda036bfc Mon Sep 17 00:00:00 2001 From: Maycon Santos Date: Fri, 11 Sep 2026 18:11:29 +0200 Subject: [PATCH] [doc] Explain custom domain verification expiry (#969) * [doc] Explain custom domain verification expiry Describe the 48-hour verification deadline, hourly cleanup, and activity event so administrators know why a pending domain disappears and how to register it again. Include the upgrade window and the exception for legacy service use. * [doc] Explain custom domain name normalization Describe how new custom domain registrations normalize case, internationalized names, and a trailing dot, and reject malformed or wildcard names. --- src/pages/manage/reverse-proxy/custom-domains.mdx | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/src/pages/manage/reverse-proxy/custom-domains.mdx b/src/pages/manage/reverse-proxy/custom-domains.mdx index 3dd52afa..2109ae07 100644 --- a/src/pages/manage/reverse-proxy/custom-domains.mdx +++ b/src/pages/manage/reverse-proxy/custom-domains.mdx @@ -57,6 +57,8 @@ Follow these steps to add a custom domain to your account: 4. Select the target **proxy cluster** that will handle traffic for this domain. 5. Click **Save**. +NetBird stores new domain names in lowercase and converts internationalized names to ASCII (punycode). A trailing dot is removed. Equivalent spellings, such as `App.Example.com.` and `app.example.com`, refer to the same registration. Invalid names and wildcard registrations such as `*.example.com` are rejected; enter the domain without the wildcard prefix. +

Add Domain modal showing domain name and proxy cluster fields

@@ -108,6 +110,16 @@ NetBird performs a CNAME lookup on `*.` and verifies that it resolv DNS changes can take time to propagate. If NetBird does not find the record immediately, please wait up to 24 hours and try again. +### Verification deadline + +Complete verification within 48 hours of adding a custom domain. Retrying verification does not extend this deadline. Once a domain becomes **Active**, it is exempt from this expiry. + +NetBird removes expired, unverified registrations at management server startup and every 60 minutes. With management running normally, removal happens between 48 and 49 hours after registration. The account's activity log records **Unvalidated domain registration expired**. After removal, you can add the domain again and complete verification within a new 48-hour window. + + + When upgrading a self-hosted management server, existing unverified registrations receive a 48-hour verification window. Legacy registrations that still have services using their domain are retained for administrator review. + + ## Managing custom domains The **Custom Domains** page lists all domains associated with your account, including both built-in and custom domains.