Skip to content

Commit 76efe78

Browse files
favoniafavonia
committed
fixup: document Cloudflare trace hosts
1 parent 27156ab commit 76efe78

1 file changed

Lines changed: 11 additions & 10 deletions

File tree

‎README.markdown‎

Lines changed: 11 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ A feature-rich and robust Cloudflare DDNS updater with a small Docker image. It
3535

3636
### 🔒 Security and Privacy
3737

38-
- 🙈 By default, public IP addresses are obtained from [Cloudflare’s debugging endpoints](https://api.cloudflare.com/cdn-cgi/trace). The updater uses only Cloudflare-owned endpoints, which minimizes the impact on privacy because it already uses the Cloudflare API to update DNS records.
38+
- 🙈 By default, public IP detection stays with Cloudflare: the `cloudflare.trace` provider contacts Cloudflare-operated HTTPS trace endpoints, and the updater already contacts Cloudflare to update DNS records. See [IP Detection](#ip-detection) for the current endpoint list.
3939

4040
- 🛡️ By default, the updater uses only HTTPS or [DNS over HTTPS](https://en.wikipedia.org/wiki/DNS_over_HTTPS) to detect IP addresses. This makes it harder for someone else to trick the updater into updating your DNS records with wrong IP addresses. See the [Security Model](docs/designs/features/network-security-model.markdown) for more information.
4141

@@ -440,14 +440,15 @@ There have been reports of intermittent issues with the default provider `cloudf
440440

441441
### 🤔 I got <code>context deadline exceeded</code> and IP detection failed
442442

443-
The first thing to check is whether a container can reach Cloudflare from the Docker environment at all. A simple way to test that is to run a minimal image such as `alpine` and try both DNS resolution and HTTPS connectivity:
443+
First check the updater logs to identify the provider and IP family that timed out. If the failed provider is `cloudflare.trace`, test every current built-in endpoint from a diagnostic container that uses the same Docker network and proxy settings as the updater. The commands below match the README's `network_mode: host` setup and test IPv4; replace `--ipv4` with `--ipv6` for an IPv6 failure. If the updater uses another Docker network, attach the diagnostic container to that network instead.
444444

445445
```bash
446-
docker run --rm alpine nslookup api.cloudflare.com
447-
docker run --rm alpine wget -qO- https://api.cloudflare.com/cdn-cgi/trace
446+
docker run --rm --network host curlimages/curl:latest --fail --show-error --silent --ipv4 https://api.cloudflare.com/cdn-cgi/trace
447+
docker run --rm --network host curlimages/curl:latest --fail --show-error --silent --ipv4 https://www.cloudflare.com/cdn-cgi/trace
448+
docker run --rm --network host curlimages/curl:latest --fail --show-error --silent --ipv4 https://connectivity.cloudflareclient.com/cdn-cgi/trace
448449
```
449450

450-
If `nslookup` fails, your Docker setup likely has a DNS problem. If `wget` fails, that primary trace endpoint is unavailable from the container, but the updater may still succeed through another Cloudflare trace endpoint. Check the updater logs for the actual detection result. If detection still times out, try increasing `DETECTION_TIMEOUT` (for example, `DETECTION_TIMEOUT=1m`).
451+
If curl reports `Could not resolve host`, fix DNS resolution in the container network. Any other curl failure means that HTTPS endpoint is unavailable under the tested network and IP family. One failed endpoint does not by itself mean detection must fail, because another endpoint can return a valid response first. However, restrictive outbound policies should allow all three hosts to preserve fallback behavior. If all three commands succeed but detection still times out, check the updater logs for response-validation failures, then try increasing `DETECTION_TIMEOUT` (for example, `DETECTION_TIMEOUT=1m`).
451452

452453
If that still does not help, please [open a GitHub issue](https://github.com/favonia/cloudflare-ddns/issues/new/choose) and include your setup details, relevant configs with secrets redacted, and any logs you have so that we can investigate further.
453454

@@ -588,7 +589,7 @@ The emoji “🧪” marks experimental features, and the emoji “🤖” marks
588589
589590
| Provider Name | Explanation |
590591
| --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
591-
| `cloudflare.trace` | Get the IP address from Cloudflare’s debugging endpoints. If the primary endpoint is slow or unavailable, the updater automatically tries other Cloudflare trace endpoints. **This is the default provider.** |
592+
| `cloudflare.trace` | <p>Get the IP address from Cloudflare’s HTTPS trace endpoints. The current built-in endpoints are `https://api.cloudflare.com/cdn-cgi/trace`, `https://www.cloudflare.com/cdn-cgi/trace`, and `https://connectivity.cloudflareclient.com/cdn-cgi/trace`.</p><p>During one detection, the updater may contact more than one endpoint and uses the first valid response received before `DETECTION_TIMEOUT` expires. **This is the default provider.**</p><p>⚠️ If outbound HTTPS is restricted by hostname, allow all three hosts.</p> |
592593
| `cloudflare.doh` | Get the IP address by querying `whoami.cloudflare.` against [Cloudflare via DNS-over-HTTPS](https://developers.cloudflare.com/1.1.1.1/encryption/dns-over-https/). |
593594
| `local` | <p>Get the IP address via local network interfaces and routing tables. The updater will use the local address that _would have_ been used for outbound UDP connections to Cloudflare servers. (No data will be transmitted.)</p><p>⚠️ The updater needs access to the host network (such as `network_mode: host` in Docker Compose) for this provider, for otherwise the updater will detect the addresses inside [the default bridge network in Docker](https://docs.docker.com/engine/network/drivers/bridge/) instead of those in the host network.</p> |
594595
| 🧪 `local.iface:<iface>` (available since version 1.15.0) | <p>🧪 Get IP addresses via the specific local network interface `iface`. Since version 1.16.0, the updater collects all matching global unicast addresses of the selected IP family (IPv4 or IPv6) instead of just the first one, then reconciles DNS records and WAF lists against that full set.</p><p>⚠️ The updater needs access to the host network (such as `network_mode: host` in Docker Compose) for this provider, for otherwise the updater cannot access host network interfaces.</p><p>🤖 The updater ignores the prefix length reported by the interface, because it commonly describes its local subnet, not the range the updater should claim. The updater uses the default prefix lengths from `IP4_DEFAULT_PREFIX_LEN` or `IP6_DEFAULT_PREFIX_LEN` instead.</p> |
@@ -632,10 +633,10 @@ The emoji “🧪” marks experimental features, and the emoji “🤖” marks
632633
<details>
633634
<summary>⏳ Operation Timeouts <sup><em>click to expand</em></sup></summary>
634635
635-
| Name | Meaning | Default Value |
636-
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
637-
| `DETECTION_TIMEOUT` | The timeout of each attempt to detect IP address, per IP version (IPv4 and IPv6). It can be any positive time duration accepted by [time.ParseDuration](https://pkg.go.dev/time#ParseDuration), such as `1h` or `10m`. | `5s` (5 seconds) |
638-
| `UPDATE_TIMEOUT` | The timeout of each attempt to update DNS records, per domain and per record type, or per WAF list. It can be any positive time duration accepted by [time.ParseDuration](https://pkg.go.dev/time#ParseDuration), such as `1h` or `10m`. | `30s` (30 seconds) |
636+
| Name | Meaning | Default Value |
637+
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
638+
| `DETECTION_TIMEOUT` | The timeout for each IP detection attempt, per IP family. A provider may make multiple requests during one detection attempt; all of them share this timeout. It can be any positive time duration accepted by [time.ParseDuration](https://pkg.go.dev/time#ParseDuration), such as `1h` or `10m`. | `5s` (5 seconds) |
639+
| `UPDATE_TIMEOUT` | The timeout of each attempt to update DNS records, per domain and per record type, or per WAF list. It can be any positive time duration accepted by [time.ParseDuration](https://pkg.go.dev/time#ParseDuration), such as `1h` or `10m`. | `30s` (30 seconds) |
639640
640641
</details>
641642

0 commit comments

Comments
 (0)