From 8c208848384271e619e72d1dcb2245110c03577c Mon Sep 17 00:00:00 2001 From: Petra Vankova Date: Mon, 24 Mar 2025 14:20:34 +0100 Subject: [PATCH] wildcards --- apps/docs/content/features/dns.mdx | 192 +++++++++++++++++++++-------- 1 file changed, 138 insertions(+), 54 deletions(-) diff --git a/apps/docs/content/features/dns.mdx b/apps/docs/content/features/dns.mdx index ac5a5711..d37c5f26 100644 --- a/apps/docs/content/features/dns.mdx +++ b/apps/docs/content/features/dns.mdx @@ -1,6 +1,6 @@ --- title: DNS and Proxy Configuration Guide -desc: A comprehensive guide for configuring DNS records and proxy settings with Zerops applications, including shared and dedicated IPv4 setups, security measures, and troubleshooting tips. +desc: A comprehensive guide for configuring DNS records and proxy settings with Zerops applications, including shared and dedicated IPv4 setups, wildcard domains, certificate validation, and troubleshooting tips. --- This guide will show you how to configure DNS records and proxy settings to work with your Zerops applications, with specific implementation details for Cloudflare. @@ -19,8 +19,8 @@ DNS allows you to set two records based on IP address type: #### IPv6 only ```bash -Type Name Content Proxy status TTL -AAAA Proxied Auto +Type Name Content Proxy status TTL +AAAA Proxied Auto ``` :::note @@ -31,10 +31,10 @@ Do not add a proxied A record with shared IPv4 - doing so would prevent the prox #### Dedicated IPv4 ```bash -Type Name Content Proxy status TTL -A Proxied Auto +Type Name Content Proxy status TTL +A Proxied Auto # Optional -AAAA Proxied Auto +AAAA Proxied Auto ``` :::tip @@ -43,9 +43,9 @@ Adding also AAAA record can be beneficial as visitors with IPv6 support will con #### Shared IPv4 *(valid but NOT recommended)* ```bash -Type Name Content Proxy status TTL -AAAA DNS only Auto -A Proxied Auto +Type Name Content Proxy status TTL +AAAA DNS only Auto +A Proxied Auto ``` :::tip Why not? @@ -56,9 +56,9 @@ It does not make sense to expose your IPv6 address while proxying the shared IPv #### Shared IPv4 ```bash -Type Name Content Proxy status TTL -AAAA DNS only Auto -A DNS only Auto +Type Name Content Proxy status TTL +AAAA DNS only Auto +A DNS only Auto ``` :::note Both A + AAAA Required @@ -67,10 +67,10 @@ Adding AAAA record is essential for shared IPv4 configuration as it serves as a #### Dedicated IPv4 ```bash -Type Name Content Proxy status TTL -A DNS only Auto +Type Name Content Proxy status TTL +A DNS only Auto # Optional -AAAA DNS only Auto +AAAA DNS only Auto ``` :::tip @@ -79,65 +79,86 @@ Adding also AAAA record can be beneficial as visitors with IPv6 support will con #### IPv6 only ```bash -Type Name Content Proxy status TTL -AAAA DNS only Auto +Type Name Content Proxy status TTL +AAAA DNS only Auto ``` :::note This configuration will only work for users with IPv6 connectivity, which may limit your service accessibility. ::: -### Understanding Shared IPv4 Addresses {#understand-shared-ipv4} +## Wildcard Domain Configuration -Shared IPv4 allows multiple Zerops projects to use the same IPv4 address while maintaining separate routing for each project. Here's how it works: +Zerops supports wildcard domains (`*.`) that allow routing all subdomains to your project. -1. When a visitor makes a request, it first arrives at the shared IPv4 address -2. The system looks at the domain name in the request (using SNI - Server Name Indication) -3. For security, it checks if this domain properly resolves to your project's IPv6 address -4. Only if IPv6 address matches your project will the traffic be routed correctly +### DNS Configuration +#### Method A: Direct configuration of A and AAAA records +Configure wildcard DNS records following the same patterns described in the [DNS Configuration](#dns-configuration) section, using `*.` in the Name field: -This is why configuring both A (IPv4) and AAAA (IPv6) records is crucial when using shared IPv4 addresses - the IPv6 record acts as a security key that helps prevent unauthorized use of the shared IPv4 address. +```bash +Type Name Content Proxy status TTL +A *. DNS only/Proxied Auto +AAAA *. DNS only/Proxied Auto +``` -## General Troubleshooting Guide +#### Method B: Using a CNAME record +First configure A and AAAA records for your main domain (``), then set up a CNAME record: -### Common Issues +```bash +Type Name Content Proxy status TTL +CNAME *. DNS only/Proxied Auto +``` -1. **DNS Resolution Issues** - - Confirm correct record configuration - - Verify proxy status settings - - Check IPv6 address accuracy - - Allow time for DNS propagation (typically 5-10 minutes) +### Certificate Validation -2. **Connection Problems** - - Test both IPv4 and IPv6 connectivity - - Check proxy server status if applicable - - Confirm port configurations +For proper HTTPS certificate functionality with wildcard domains, configure: +```bash +Type Name Content Proxy status TTL +CNAME _acme-challenge. .zerops.zone DNS only Auto +``` -### Validation Steps +This record enables Zerops to issue and verify a wildcard certificate for your domain. -Test your configuration: -```bash -# Check DNS resolution -dig AAAA yourdomain.com +### Higher-Level Wildcard Subdomains -# Verify connectivity -curl -vI https://yourdomain.com +You can also set up higher-level wildcard subdomains like `*..`: -# Test IPv4 access -curl -4 -v https://yourdomain.com +#### Method A: Direct configuration +```bash +Type Name Content Proxy status TTL +A *.. DNS only/Proxied Auto +AAAA *.. DNS only/Proxied Auto +``` -# Test IPv6 access -curl -6 -v https://yourdomain.com +#### Method B: Using a CNAME record +```bash +Type Name Content Proxy status TTL +CNAME *.. . DNS only/Proxied Auto +``` +or +```bash +Type Name Content Proxy status TTL +CNAME *.. DNS only/Proxied Auto +``` + +For certificate validation: +```bash +Type Name Content Proxy status TTL +CNAME _acme-challenge.. ..zerops.zone DNS only Auto ``` -## Cloudflare Configuration +### Combining Main Domain and Wildcard Domain -### SSL/TLS Mode +To use both `` and `*.`, specify both variants in your [Zerops configuration](/features/access#configuring-http-routing). Zerops automatically issues a single shared certificate for both the main domain and all its subdomains. + +## Cloudflare-Specific Configuration + +#### SSL/TLS Mode Set encryption mode to `Full (strict)` or `Full` - Ensures end-to-end encryption - *Full* mode requires any SSL certificate (even if self-signed/expired), while *Full (strict)* requires a valid certificate -### Certificate Management +#### Certificate Management 1. Enable Edge Certificates to allow Cloudflare to manage SSL/TLS certificates 2. During initial setup, handle HTTPS settings in one of two ways: - **Option A (Simple but Limited)**: @@ -152,10 +173,73 @@ Set encryption mode to `Full (strict)` or `Full` ``` This rule disables Automatic HTTPS Rewrites for the certificate validation path. -### Cloudflare Troubleshooting +## Validation Steps -#### SSL Certificate Problems - - Verify `Always Use HTTPS` is disabled - - If you encounter **too many redirects** or similar SSL errors: +Test your configuration: +```bash +# Check DNS resolution +dig AAAA + +# Verify connectivity +curl -vI https:// + +# Test IPv4 access +curl -4 -v https:// + +# Test IPv6 access +curl -6 -v https:// +``` + +## Troubleshooting Guide + +1. **DNS Resolution Issues** + - Confirm correct record configuration + - Verify proxy status settings + - Check IPv6 address accuracy + - Allow time for DNS propagation (typically 5-10 minutes) + +2. **Connection Problems** + - Test both IPv4 and IPv6 connectivity + - Check proxy server status if applicable + - Confirm port configurations + +3. **Certificate Issues** + - Verify proper _acme-challenge CNAME configuration for wildcard domains + - Check that DNS records match the domains configured in Zerops + - **Cloudflare-specific certificate problems**: + - Verify `Always Use HTTPS` is disabled + - If you encounter **too many redirects** or similar SSL errors: - Double-check that SSL/TLS encryption mode is set to *Full* or *Full (strict)*, not *Flexible* - - SSL mode might show incorrectly for newly added domains, try refreshing the page if settings appear incorrect \ No newline at end of file + - SSL mode might show incorrectly for newly added domains, try refreshing the page if settings appear incorrect + +## Technical Background + +### Understanding Shared IPv4 Addresses {#understand-shared-ipv4} + +Shared IPv4 allows multiple Zerops projects to use the same IPv4 address while maintaining separate routing for each project. Here's how it works: + +1. When a visitor makes a request, it first arrives at the shared IPv4 address +2. The system looks at the domain name in the request (using SNI - Server Name Indication) +3. For security, it checks if this domain properly resolves to your project's IPv6 address +4. Only if IPv6 address matches your project will the traffic be routed correctly + +This is why configuring both A (IPv4) and AAAA (IPv6) records is crucial when using shared IPv4 addresses - the IPv6 record acts as a security key that helps prevent unauthorized use of the shared IPv4 address. + +### Certificate Verification Methods + +When issuing SSL/TLS certificates, different verification methods are used depending on the certificate type: + +#### HTTP-01 vs DNS-01 Verification + +- **Regular certificates** (for a single domain like ``) are typically issued using the **HTTP-01** challenge method. This verification checks that you control the domain by placing a specific file at a specific URL. + +- **Wildcard certificates** (for domains like `*.`) must be issued using the **DNS-01** challenge method. This method requires creating specific TXT records in your DNS configuration. + +### How Zerops Handles Wildcard Certificate Verification + +Zerops simplifies the DNS-01 challenge process: + +1. You create a CNAME record (e.g., `_acme-challenge. CNAME .zerops.zone`) +2. When a certificate needs to be issued or renewed, Zerops automatically creates the required TXT records on its `zerops.zone` domain +3. The certificate authority verifies these TXT records through the CNAME redirection +4. Once verified, the wildcard certificate is issued without requiring manual intervention \ No newline at end of file