sendnrw/netbird-docs
2
0
Fork 0
mirror of https://github.com/netbirdio/docs.git synced 2026-04-16 15:36:36 +00:00
Code Issues Packages Projects Releases Wiki Activity

Document TLS-ALPN-01 challenge requirements for reverse proxy (#656)

Browse Source
This commit is contained in:
shuuri-labs
2026-03-16 15:26:52 +01:00
committed by GitHub
parent 31a1eb5642
commit 8680e5e822
2 changed files with 16 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
src/pages/manage/reverse-proxy/index.mdx
View File

@@ -140,6 +140,18 @@ The proxy supports two modes for TLS certificate management:
When a certificate is successfully issued, the proxy notifies the management server and the service status changes to `active`.
#### TLS-ALPN-01 requirements
The default ACME challenge type (`tls-alpn-01`) validates domain ownership by responding on port 443 with a special TLS certificate containing the `acme-tls/1` ALPN protocol. For this challenge to succeed, the following conditions must be met:
- **Port 443 must be publicly reachable** - Let's Encrypt connects to your server on port 443 to perform the challenge. If port 443 is blocked by a firewall or not forwarded correctly, certificate issuance will fail.
- **No geo-blocking** - Let's Encrypt validates from multiple global locations simultaneously. If your firewall or CDN blocks requests from non-local IP ranges, some or all validation attempts will fail and the certificate will not be issued.
- **ALPN protocol support** - If there is an additional proxy or load balancer in front of the NetBird proxy, it must support passing through the `acme-tls/1` ALPN protocol. Traefik and Caddy handle this natively through TLS passthrough. Nginx, Apache, and some CDN providers (such as Cloudflare) may strip or fail to negotiate the `acme-tls/1` protocol, causing the challenge to fail.
<Note>
If any of these requirements cannot be met in your environment, switch to the `http-01` challenge type by setting `NB_PROXY_ACME_CHALLENGE_TYPE=http-01`. The HTTP-01 challenge validates over port 80 using a plain HTTP request and does not depend on ALPN protocol support. However, it requires port 80 to be accessible from the internet.
</Note>
**Static certificate mode** - Provide your own certificate and key files. This is useful for wildcard certificates or certificates from a corporate CA. Configure with:
| Environment variable | Description |

4
src/pages/selfhosted/migration/enable-reverse-proxy.mdx
View File

@@ -422,6 +422,10 @@ If your self-hosted deployment currently uses Nginx, Caddy, or another reverse p
2. Ensure the wildcard DNS record resolves correctly: `dig myapp.proxy.example.com`
3. Check proxy logs for ACME errors: `docker compose logs proxy | grep -i acme`
4. If using `http-01` challenge type, ensure port 80 is also accessible
5. Ensure no geo-blocking is active on your firewall or CDN - Let's Encrypt validates from multiple global locations simultaneously, and blocking non-local IPs will cause validation to fail
6. If you have an additional proxy or load balancer in front of Traefik, verify it supports the `acme-tls/1` ALPN protocol required by the `tls-alpn-01` challenge. Some providers (such as Cloudflare) may not pass through this protocol. If this is an issue, switch to `NB_PROXY_ACME_CHALLENGE_TYPE=http-01`
For a full explanation of TLS-ALPN-01 requirements, see [TLS-ALPN-01 requirements](/manage/reverse-proxy#tls-alpn-01-requirements).
### TLS passthrough not working