Cloudflare Proxied Domains

Reoclo’s managed proxy (Caddy) issues certificates automatically. By default it uses the HTTP-01 challenge, which needs Let’s Encrypt to reach your server directly. When a domain is behind Cloudflare’s proxy (the orange cloud), that path does not work reliably.

With a Cloudflare API token, Reoclo switches those domains to the DNS-01 challenge. Caddy publishes a TXT record through the Cloudflare API, Let’s Encrypt reads it from DNS, and the certificate is issued without a direct connection.

Prerequisites

• A server connected with the Reoclo runner, with the managed proxy enabled (server page, Proxy tab).
• A Cloudflare account that manages the zone (for example example.com).
• An admin role in your organisation (the DNS providers page needs the servers edit-settings permission).

Step 1: Create the API token in Cloudflare

1. In the Cloudflare dashboard, open My Profile > API Tokens > Create Token. Account API tokens work too (Manage Account > API Tokens).
2. Choose Create Custom Token.
3. Add these permissions:
   • Zone > Zone > Read
   • Zone > DNS > Edit
4. Under Zone Resources, select Include > Specific zone and pick the zone. Do not grant all zones.
5. Optional: under Client IP Address Filtering, add the public IP addresses of the Reoclo servers that will use the token. Add both the IPv4 address and the IPv6 prefix (the /64). A server with IPv6 connects to Cloudflare over IPv6, so an IPv4-only filter blocks it. To see the address Cloudflare sees, run this on the server: curl -s https://api.cloudflare.com/cdn-cgi/trace | grep ip=. Reoclo verifies the token from those servers, so a token restricted to other addresses fails verification.
6. Create the token and copy it. Cloudflare shows it only once.

Step 2: Set the Cloudflare SSL/TLS mode

In the zone’s SSL/TLS settings, select Full (strict). Your server will hold a valid certificate, so strict mode is safe. Flexible mode sends plain HTTP to your server and breaks redirects. Until you link the domain in Step 4, strict mode shows error 526 for it.

Step 3: Add the token in Reoclo

1. In Reoclo, open Infrastructure > DNS providers.
2. Select Add provider.
3. Enter a label and paste the token.
4. Select the servers the token may be used from. Nothing is pre-selected: the token is a secret, so servers are opted in. If the token has an IP restriction, select only the servers whose IPs you allowed.
5. Select Add and verify.

Reoclo sends the token to each selected server and runs three checks from there: the token is active, the token can read at least one zone, and the token can create a DNS record. The last check creates a TXT record named _reoclo-dns-check.<zone> and deletes it immediately.

When at least one server passes, the provider shows active and lists the zones the token covers. Each server shows its own result. A failed server shows the reason, for example “Cloudflare rejected the token from server web-2. If the token has a client IP restriction, add this server’s public IPv4 and IPv6 addresses.”

You can add more than one token. When two active tokens on the same server cover the same zone, Reoclo uses the most recently added token. Reoclo shows an “Also covered by” hint on those tokens. Tokens on different servers can cover the same zone without conflict. You can give each server its own token with a client IP restriction.

To rotate a token, open Edit on the provider and paste the replacement into Replace API token. Reoclo verifies the replacement from the assigned servers first and only swaps it when the checks pass; a failing replacement leaves the current token in place.

Wildcard domains (*.example.com) on the managed proxy need this token. HTTP-01 cannot issue a wildcard certificate. Reoclo waits to serve a wildcard domain until you assign a token that covers its zone to the server.

Step 4: Add the domain

Add and verify the domain as described in Custom Domains. Keep the orange cloud on.

On the domain page, the Routing card shows Certificate: DNS-01 via Cloudflare (label). The DNS summary shows Proxied via Cloudflare instead of a DNS mismatch.

On the server’s Proxy tab, the route shows a DNS-01 badge. The certificate is usually issued within a minute of the next reconcile.

Let Reoclo write the records

When a token covers a zone, Reoclo can write the records it expects for a domain in that zone. The token needs the same Zone:DNS:Edit permission as DNS-01.

Reoclo writes only these records:

• The A record for the domain, with the IP address of the linked server.
• The CNAME record, when you set an expected CNAME instead.
• The _reoclo-verify TXT record, when verification is pending.

Reoclo never writes other records in the zone.

Create the record when you link a domain

On the Link domain form, the DNS record on Cloudflare card appears when a token covers the zone. Create the DNS record on Cloudflare is on by default. Reoclo creates the record after it links the domain.

If a record with a different value already exists, Reoclo does not change it. The domain page shows the reason and offers Fix on Cloudflare.

Proxy through Cloudflare is off by default, so the record is DNS-only (gray cloud). If you turn it on, set SSL/TLS to Full (strict) in Cloudflare first.

Fix on Cloudflare

When a record is missing or points elsewhere, or the last publish failed, Reoclo shows Fix on Cloudflare. It appears on the domain’s DNS tab and on the DNS page. Select it to see the changes before Reoclo makes them:

1. Reoclo reads the current records from the zone through one of the servers assigned to the token.
2. The preview lists each record with its action: Create, Update, Delete, Unchanged, or Conflict.
3. Select Apply on Cloudflare to make the changes.

A Conflict row blocks the apply. The preview shows the reason. Fix the cause in Cloudflare or in the domain settings, then open the preview again.

An update keeps the proxy state of the record. A create uses the Proxy through Cloudflare switch in the preview.

Reoclo records each publish in the audit log with the changes it made. Platform administrators can turn this feature off with the dns_publish feature flag.

How it works

• Reoclo stores the token encrypted. It never appears in the API, in logs, or in the effective Caddy configuration. Caddy reads it from a file inside its configuration volume at /etc/caddy/dns/.
• The managed proxy image is Caddy with the caddy-dns/cloudflare module. Reoclo moves servers to this image once, with one to two seconds of proxy downtime. Until a server runs it, the route shows “Waiting for this server to run the managed Caddy image” and keeps HTTP-01.
• Deleting a provider removes its token files from the servers on the next reconcile. Routes under its zones fall back to HTTP-01.

The Proxy tab runtime strip

The Proxy tab shows the state of the reoclo-caddy container: running since when, the Caddy version, the image, and when it was last observed.

• Start appears when the container is stopped or missing. Reoclo enables the proxy and recreates the container.
• Restart appears when the container is running.
• To stop the proxy, click Change in the reverse proxy section, select None, then click Confirm. A plain container stop is undone on the next reconcile. This removes the proxy container and its volumes, including issued certificates. Certificates are issued again after you enable the proxy.

Troubleshooting

”No DNS provider covers this zone”

No active token lists this domain’s zone. Check the zones on the provider. If the zone is missing, the token was created for a different zone; create a new token with the correct zone and add it.

”A DNS provider covers this zone but is not assigned to this server”

Edit the provider and select the server the domain is bound to. Reoclo verifies the token from that server when you save.

”The DNS provider token failed its check from this server”

Open DNS providers and read the server’s result. Common causes:

• The token has a client IP restriction that does not include this server. Add the server’s public IPv4 address and its IPv6 prefix (the /64) in Cloudflare, then select Verify. Servers with IPv6 reach Cloudflare over IPv6, so the IPv4 address alone is not enough. Run curl -s https://api.cloudflare.com/cdn-cgi/trace | grep ip= on the server to see the address Cloudflare sees.
• The token lacks Zone:DNS:Edit. Edit the token in Cloudflare, then select Verify.
• curl is not installed on the server. Install it and select Verify.

”Waiting for this server to run the managed Caddy image”

The server has not moved to the managed image yet. The Proxy tab shows Updating Caddy image while this happens. If it stays for more than a few minutes, check that the server can pull images from Docker Hub (run the Proxy tab’s preflight and check the registry_reachable result).

DNS status shows “mismatch” with a Cloudflare hint

The domain is proxied but no active token covers its zone. Add a provider for that zone. The status turns ok on the next DNS check.

The certificate is still from Cloudflare

Cloudflare serves its own edge certificate to visitors. That is expected. DNS-01 issues the certificate between Cloudflare and your server (the origin certificate). Select Full (strict) in Cloudflare so that connection is verified.

”The zone changed since the preview”

Someone changed the zone between the preview and Apply on Cloudflare. Open Fix on Cloudflare again to see a new preview.

”A app.example.com already holds 198.51.100.1”

Reoclo found a record with a different value when it linked the domain. The link flow never replaces an existing record. Open the domain page and select Fix on Cloudflare to replace it after a preview.

”Both an A record and a CNAME are expected”

The domain has an expected A record and an expected CNAME. A name cannot hold both. Open the Settings tab of the domain and clear one of them.

Cloudflare shows error 525 or 526

Both errors mean that Cloudflare could not accept the TLS handshake with your server for this hostname.

• 525: the server refused the handshake. Older proxy configurations did this for a hostname with no route. Reoclo now answers every handshake, so this error clears on the next reconcile. If it stays, open the server’s Proxy tab and read the last error.
• 526: the SSL mode is Full (strict) and the server has no valid certificate for this hostname. The domain is not linked, or the certificate is not issued yet. For a hostname with no route the proxy presents a certificate from its own local CA. Strict mode rejects that certificate.

To fix 526, link the domain to an application on the server (Step 4). Reoclo issues the certificate with DNS-01 within a minute. Until then, you can set the SSL mode to Full to see the “Powered by Reoclo” page.