# DNS and Proxy Configuration Guide


This guide will show you how to configure DNS records and proxy settings to work with your Zerops applications.

:::important Cloudflare
If you're using Cloudflare, check out our dedicated [Cloudflare DNS Configuration Guide](/references/networking/cloudflare) for step-by-step instructions specific to Cloudflare's interface and features.
:::

## DNS Configuration

DNS records for Zerops services can be configured in two main ways:
* **With Proxy**: Routes traffic through proxy services, providing additional security and performance features (recommended for DDoS protection)
* **Without Proxy (DNS Only)**: Direct connection to your Zerops service's IP address

DNS allows you to set two records based on IP address type:
* **A** record for **IPv4** - Zerops offers either a free **shared** IPv4 or a paid **dedicated** IPv4
* **AAAA** record for **IPv6** - Zerops provides a free **dedicated** IPv6

### Using CNAME Records

CNAME can be used for non-apex domains (subdomains) or with DNS providers that support CNAME flattening at the apex. When you set up a CNAME in Zerops, it internally creates A and AAAA records pointing to your project.

To find your CNAME target value, go to your service in the Zerops GUI, navigate to **Public access & internal ports**, and select the **CNAME** option when adding a domain.

```
Type    Name              Content                         Proxy status       TTL
CNAME   <your-domain>     <your-project-cname-target>     DNS only/Proxied   Auto
```

:::warning Using Proxy with Shared IPv4
When using any CDN or proxy service with CNAME records, you should **exclude the shared IPv4**. Toggle off "Shared IPv4 included in the CNAME" in the Zerops GUI.

Zerops does a reverse lookup of the AAAA record of the domain for requests to our shared IPv4 address. If you use a shared IPv4 and also enable a proxy for the AAAA record, Zerops will not be able to correctly route the request because it sees the proxy's IP instead of your project's IPv6.

This setting affects all domains in your project.
:::

### With Proxy

#### IPv6 only
```bash
Type    Name              Content                Proxy status   TTL
AAAA    <your-domain>     <your-project-ipv6>    Proxied        Auto
```

:::note
Make sure your proxy service supports IPv4 to IPv6 translation for this configuration to work for **both IPv4 and IPv6** users.

Do not add a proxied A record with shared IPv4 - doing so would prevent the proxy from properly routing IPv4 traffic to your service.
:::

#### Dedicated IPv4
```bash
Type    Name              Content                Proxy status   TTL
A       <your-domain>     <your-dedicated-ipv4>  Proxied        Auto
# Optional
AAAA    <your-domain>     <your-project-ipv6>    Proxied        Auto
```

:::tip
Adding also AAAA record can be beneficial as visitors with IPv6 support will connect directly via IPv6.
:::

#### Shared IPv4 *(not recommended)*
```bash
Type    Name              Content                Proxy status  TTL
AAAA    <your-domain>     <your-project-ipv6>    DNS only      Auto
A       <your-domain>     <zerops-shared-ipv4>   Proxied       Auto
```

:::tip Why Not?
Zerops does a reverse lookup of the AAAA record of the domain for requests to our shared IPv4 address. If you use a shared IPv4 and also enable a proxy for the AAAA record, Zerops will not be able to correctly route the request.

Use [IPv6 only](#ipv6-only) or dedicated IPv4 configurations instead.
:::

### Without Proxy

#### Shared IPv4
```bash
Type    Name              Content                Proxy status   TTL
AAAA    <your-domain>     <your-project-ipv6>    DNS only       Auto
A       <your-domain>     <zerops-shared-ipv4>   DNS only       Auto
```

:::note Both A + AAAA Required
Adding AAAA record is essential for shared IPv4 configuration as it serves as a [security measure](#understand-shared-ipv4) to prevent unauthorized domain claims.
:::

#### Dedicated IPv4
```bash
Type    Name              Content                Proxy status   TTL
A       <your-domain>     <your-dedicated-ipv4>  DNS only       Auto
# Optional
AAAA    <your-domain>     <your-project-ipv6>    DNS only       Auto
```

:::tip
Adding also AAAA record can be beneficial as visitors with IPv6 support will connect directly via IPv6.
:::

#### IPv6 only
```bash
Type    Name              Content                Proxy status   TTL
AAAA    <your-domain>     <your-project-ipv6>    DNS only       Auto
```

:::note
This configuration will only work for users with IPv6 connectivity, which may limit your service accessibility.
:::

## Wildcard Domain Configuration

Zerops supports wildcard domains (`*.<your-domain>`) that allow routing all subdomains to your project.

### 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 `*.<your-domain>` in the Name field:

```bash
Type   Name              Content               Proxy status       TTL
A      *.<your-domain>   <your-ipv4-address>   DNS only/Proxied   Auto
AAAA   *.<your-domain>   <your-ipv6-address>   DNS only/Proxied   Auto
```

#### Method B: Using a CNAME record
First configure A and AAAA records for your main domain (`<your-domain>`), then set up a CNAME record:

```bash
Type    Name              Content         Proxy status       TTL
CNAME   *.<your-domain>   <your-domain>   DNS only/Proxied   Auto
```

### Certificate Validation

For proper HTTPS certificate functionality with wildcard domains, configure:
```bash
Type    Name                            Content                     Proxy status   TTL
CNAME   _acme-challenge.<your-domain>   <your-domain>.zerops.zone   DNS only       Auto
```

This record enables Zerops to issue and verify a wildcard certificate for your domain.

### Higher-Level Wildcard Subdomains

You can also set up higher-level wildcard subdomains like `*.<subdomain>.<your-domain>`:

#### Method A: Direct configuration
```bash
Type   Name                          Content               Proxy status       TTL
A      *.<subdomain>.<your-domain>   <your-ipv4-address>   DNS only/Proxied   Auto
AAAA   *.<subdomain>.<your-domain>   <your-ipv6-address>   DNS only/Proxied   Auto
```

#### Method B: Using a CNAME record
```bash
Type    Name                          Content                     Proxy status       TTL
CNAME   *.<subdomain>.<your-domain>   <subdomain>.<your-domain>   DNS only/Proxied   Auto
```
or
```bash
Type    Name                          Content         Proxy status       TTL
CNAME   *.<subdomain>.<your-domain>   <your-domain>   DNS only/Proxied   Auto
```

For certificate validation:
```bash
Type    Name                                        Content                                 Proxy status   TTL
CNAME   _acme-challenge.<subdomain>.<your-domain>   <subdomain>.<your-domain>.zerops.zone   DNS only       Auto
```

### Combining Main Domain and Wildcard Domain

To use both `<your-domain>` and `*.<your-domain>`, specify both variants in your [Zerops configuration](/references/networking/public-access#http-routing-setup). Zerops automatically issues a single shared certificate for both the main domain and all its subdomains.

## Validation Steps

Test your configuration:
```bash
# Check DNS resolution
dig AAAA <your-domain>

# Verify connectivity
curl -vI https://<your-domain>

# Test IPv4 access
curl -4 -v https://<your-domain>

# Test IPv6 access
curl -6 -v https://<your-domain>
```

## 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
   - **Provider-specific certificate problems**: Consult your DNS provider's documentation for SSL/TLS configuration requirements

## 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 `<your-domain>`) 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 `*.<your-domain>`) 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.<your-domain> CNAME <your-domain>.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