Skip to content

Commit

Permalink
docs: final tweaks before 1.14.0 (#892)
Browse files Browse the repository at this point in the history
  • Loading branch information
@favonia
favonia authored Aug 25, 2024
1 parent c89f9a6 commit 7e33c6a
Show file tree
Hide file tree
Showing 3 changed files with 6 additions and 5 deletions.
3 changes: 2 additions & 1 deletion CHANGELOG.markdown
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,9 @@ As a reminder, since 1.13.0, **the updater will no longer drop superuser privile
Other notable changes:

1. The global Cloudflare account ID will no longer be used when searching for DNS zones. `CF_ACCOUNT_ID` will be ignored.
2. To reduce network traffic and delay, the Cloudflare API token will no longer be additionally verified via the Cloudflare’s token verification API. Instead, the updater will locally check whether it looks like a valid [Bearer Token](https://oauth.net/2/bearer-tokens/).
2. To reduce network traffic and delay, the Cloudflare API token will no longer be additionally verified via [Cloudflare’s token verification API](https://developers.cloudflare.com/api/operations/user-api-tokens-verify-token). Instead, the updater will locally check whether the token looks like a valid [Bearer Token](https://oauth.net/2/bearer-tokens/) before using the API.
3. Many parts of the [README](./README.markdown) have been rewritten to improve clarity and to document the support of WAF lists.
4. The DNS record updating algorithm was revised to be more deterministic, which means the updater will not give up updating stale DNS records (and create new ones) when there are errors; it will simply try again next time. As a result, in very rare cases, the updater may need more rounds to recover from errors.

### Bug Fixes

Expand Down
6 changes: 3 additions & 3 deletions README.markdown
View file
Original file line number Diff line number Diff line change
Expand Up @@ -265,7 +265,7 @@ _(Click to expand the following items.)_
| `DOMAINS` | Comma-separated fully qualified domain names or wildcard domain names that the updater should manage for both `A` and `AAAA` records. Listing a domain in `DOMAINS` is equivalent to listing the same domain in both `IP4_DOMAINS` and `IP6_DOMAINS`. |
| `IP4_DOMAINS` | Comma-separated fully qualified domain names or wildcard domain names that the updater should manage for `A` records |
| `IP6_DOMAINS` | Comma-separated fully qualified domain names or wildcard domain names that the updater should manage for `AAAA` records |
| 🧪 `WAF_LISTS` | 🧪 Comma-separated references of [WAF lists](https://developers.cloudflare.com/waf/tools/lists/custom-lists/) the updater should manage. A list reference is written in the format `account-id/list-name` where `account-id` is your account ID and `list-name` is the list name; it should look like `0123456789abcdef0123456789abcdef/mylist`. 💡 See [how to find your account ID](https://developers.cloudflare.com/fundamentals/setup/find-account-and-zone-ids/). |
| 🧪 `WAF_LISTS` | 🧪 Comma-separated references of [WAF lists](https://developers.cloudflare.com/waf/tools/lists/custom-lists/) the updater should manage. A list reference is written in the format `account-id/list-name` where `account-id` is your account ID and `list-name` is the list name; it should look like `0123456789abcdef0123456789abcdef/mylist`. If the referenced WAF list does not exist, the updater will try to create it. 💡 See [how to find your account ID](https://developers.cloudflare.com/fundamentals/setup/find-account-and-zone-ids/). |

> 🧪 The feature to manipulate WAF lists is experimental (introduced in 1.14.0) and is subject to changes. In particular, the updater currently deletes unmanaged IPs from WAF lists (e.g., deleting IPv6 addresses if you disable IPv6), but another reasonable implementation is to leave them alone. Please [open a GitHub issue](https://github.com/favonia/cloudflare-ddns/issues/new) to provide feedback. Thanks!
Expand Down Expand Up @@ -315,7 +315,7 @@ _(Click to expand the following items.)_
| Name | Meaning | Default Value |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
| `CACHE_EXPIRATION` | The expiration of cached Cloudflare API responses. It can be any positive time duration accepted by [time.ParseDuration](https://golang.org/pkg/time/#ParseDuration), such as `1h` or `10m`. | `6h0m0s` (6 hours) |
| `DELETE_ON_STOP` | Whether managed DNS records and WAF lists should be deleted on exit. It can be any boolean value accepted by [strconv.ParseBool](https://pkg.go.dev/strconv#ParseBool), such as `true`, `false`, `0` or `1`. | `false` |
| `DELETE_ON_STOP` | Whether managed DNS records and WAF lists should be deleted on exit. It can be any boolean value accepted by [strconv.ParseBool](https://pkg.go.dev/strconv#ParseBool), such as `true`, `false`, `0` or `1`. 🐞🧪 **KNOWN ISSUE: if a WAF list is used in a rule, you cannot delete it.** In future versions, the updater may attempt to empty a list when it fails to delete it, but this has not been implemented yet. | `false` |
| `TZ` | The timezone used for logging messages and parsing `UPDATE_CRON`. It can be any timezone accepted by [time.LoadLocation](https://pkg.go.dev/time#LoadLocation), including any IANA Time Zone. 🤖 The pre-built Docker images come with the embedded timezone database via the [time/tzdata](https://pkg.go.dev/time/tzdata) package. | `UTC` |
| `UPDATE_CRON` | The schedule to re-check IP addresses and update DNS records and WAF lists (if needed). The format is [any cron expression accepted by the `cron` library](https://pkg.go.dev/github.com/robfig/cron/v3#hdr-CRON_Expression_Format) or the special value `@once`. The special value `@once` means the updater will terminate immediately after updating the DNS records or WAF lists, effectively disabling the scheduling feature. 🤖 The update schedule _does not_ take the time to update records into consideration. For example, if the schedule is `@every 5m`, and if the updating itself takes 2 minutes, then the actual interval between adjacent updates is 3 minutes, not 5 minutes. | `@every 5m` (every 5 minutes) |
| `UPDATE_ON_START` | Whether to check IP addresses (and possibly update DNS records and WAF lists) _immediately_ on start, regardless of the update schedule specified by `UPDATE_CRON`. It can be any boolean value accepted by [strconv.ParseBool](https://pkg.go.dev/strconv#ParseBool), such as `true`, `false`, `0` or `1`. | `true` |
Expand All @@ -335,7 +335,7 @@ _(Click to expand the following items.)_
<details>
<summary>🐣 Parameters of new DNS records and WAF lists</summary>

> 👉 The updater will preserve existing parameters (TTL, proxy states, comments, etc.). Only when it creates new DNS records or new WAF lists, the following settings will apply. To change existing parameters, you can go to your [Cloudflare Dashboard](https://dash.cloudflare.com) and change them directly. If you think you have a use case where the updater should actively overwrite existing parameters in addition to IP addresses, please [let me know](https://github.com/favonia/cloudflare-ddns/issues/new).
> 👉 The updater will preserve existing parameters (TTL, proxy states, DNS record comments, etc.). Only when it creates new DNS records and new WAF lists, the following settings will apply. To change existing parameters, you can go to your [Cloudflare Dashboard](https://dash.cloudflare.com) and change them directly. If you think you have a use case where the updater should actively overwrite existing parameters in addition to IP addresses, please [let me know](https://github.com/favonia/cloudflare-ddns/issues/new). 🐞🧪 **KNOWN ISSUE: existing comments attached to individual WAF list items (not WAF lists themselves) are not preserved** because the Cloudflare API does not provide an easy way to update existing WAF list items. The comments will be lost when the updater deletes stale WAF list items and creates new ones.
| Name | Meaning | Default Value |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
Expand Down
2 changes: 1 addition & 1 deletion internal/provider/happy_eyeballs.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ import (
const HappyEyeballsAlternativeDelay = time.Second / 2

// Hint1111BlocakageText is the explanation of why we want the parallel detection algorithm.
const Hint1111BlocakageText string = "Many IPv4 detection methods use 1.1.1.1 to obtain your public IPv4 address, but it is not uncommon for your ISPs or routers to block or intercept 1.1.1.1. To work around the blockage, the updater may connect to 1.0.0.1 if 1.1.1.1 does not immediately respond. Whichever returns first will be used in the future." //nolint:lll
const Hint1111BlocakageText string = "You are using an IPv4 provider that connects to 1.1.1.1 to obtain your public IPv4 address, but it is not uncommon for your ISPs or routers to block or intercept 1.1.1.1. To work around the blockage, the updater may connect to 1.0.0.1 if 1.1.1.1 does not immediately respond. Whichever returns first will be used in future IP detection." //nolint:lll

// Hint1111Blockage prints out a message that explains the parallel connection to 1.0.0.1.
func Hint1111Blockage(ppfmt pp.PP) { ppfmt.Hintf(pp.Hint1111Blockage, "%s", Hint1111BlocakageText) }
Expand Down

0 comments on commit 7e33c6a

Please sign in to comment.