Add Docker container support

Dynamic DNS client for Cloudflare

A CLI tool for updating A/AAAA record at Cloudflare DNS with the currently detected address of the specified network interface.

Features

Supports:
- IPv4 and IPv6
- Multiple domains with the same address
- Multiple hosts in the same domain
Tries to be smart about selecting the address to use
Includes systemd service and timer files for automation
Can be run in a Docker container
Configuration via command line arguments, config file or environment variables

Usage

The rest of this section is the output of cloudflare-dynamic-dns --help.

Selects an address from the specified network interface and updates A or AAAA
records at Cloudflare for the configured domains. Supports both IPv4 and IPv6.

Required configuration options
--------------------------------------------------------------------------------

--iface: network interface name to look up for an address
--domains: one or more domain names to assign the address to
--token: Cloudflare API token with edit access rights to the DNS zone

IPv6 address selection
--------------------------------------------------------------------------------

When multiple IPv6 addresses are found on the interface, the following rules are
used to select the one to use:
1. Only global unicast addresses (GUA) and unique local addresses (ULA) are
considered.
2. GUA addresses are preferred over ULA addresses.
3. Unique EUI-64 addresses are preferred over randomly generated addresses.
4. If priority subnets are specified, addresses from the subnet with the
highest priority are selected. The priority is determined by the order of
subnets specified on the command line or in the config file.

IPv4 address selection
--------------------------------------------------------------------------------

When multiple IPv4 addresses are found on the interface, the following rules are
used to select the one to use:
1. All IPv4 addresses are considered.
2. Public addresses are preferred over Shared Address Space (RFC 6598)
addresses.
3. Shared Address Space addresses are preferred over private addresses.
4. Private addresses are preferred over loopback addresses.
5. If priority subnets are specified, addresses from the subnet with the
highest priority are selected. The priority is determined by the order of
subnets specified on the command line or in the config file.

Non-public addresses are logged as warnings but are still used. They can be
useful in private networks or when using a VPN.

NOTE: Cloudflare doesn't allow proxying of records with non-public addresses.

Daemon mode
--------------------------------------------------------------------------------

By default, the program runs once and exits. This mode of operation can be
changed by setting the --run-every flag to a duration greater than 1m. In this
case, the program will run repeatedly, waiting the duration between runs. It
will stop if killed or if failed.

State file
--------------------------------------------------------------------------------

Setting --state-file makes the program to retain the previously used address
between runs to avoid unnecessary calls to the Cloudflare API.

The value is used as the state file path. When used with an empty value, the
state file is named after the interface name and the domains, and is stored
either in the current directory or in the directory specified by the
STATE_DIRECTORY environment variable.

The STATE_DIRECTORY environment variable is automatically set by systemd. It
can be set manually when running the program outside of systemd.

Multihost mode (EXPERIMENTAL)
--------------------------------------------------------------------------------

In this mode, it is possible to assign multiple addresses to a single or
multiple domains. For correct operation, this mode must be enabled on all hosts
participating in the same domain and different host-ids must be specified for
each host (see --host-id option). This mode is enabled by passing --multihost
flag.

In the multihost mode, the program will manage only the DNS records that have
the same host-id as the one specified on the command line or in the config file.
If an existing record has no host-id but has the same address as the target one,
it will be claimed by this host via setting the corresponding host-id. Any other
records will be ignored. This allows multiple hosts to share the same domain
without interfering with each other. The host-id is stored in the Cloudflare DNS
comments field (see https://developers.cloudflare.com/dns/manage-dns-records/reference/record-attributes/).

Persistent configuration
--------------------------------------------------------------------------------

The program can be configured using a config file. The default location is
$HOME/.cloudflare-dynamic-dns.yaml. The config file location can be overridden
using the --config flag. The config file format is YAML. The following options
are supported (with example values):

iface: eth0
token: cloudflare-api-token
domains:
- example.com
- "*.example.com"
# === optional fields
# --- mode
stack: ipv6
# --- UI
log-level: info
# --- logic
priority-subnets:
- 2001:db8::/32
- 2001:db8:1::/48
multihost: true
host-id: homelab-node-1
# --- DNS record details
proxy: enabled
ttl: 180
# --- daemon mode
run-every: 10m
state-file: /tmp/cfddns-eth0.state

Environment variables
--------------------------------------------------------------------------------

The configuration options can be specified as environment variables. To make an
environment variable name, prefix a flag name with CFDDNS_, replace dashes with
underscores, and convert to uppercase. List values are specified as a single
string containing elements separated by spaces.
For example:

CFDDNS_CONFIG=/path/to/config.yaml
CFDDNS_IFACE=eth0
CFDDNS_TOKEN=cloudflare-api-token
CFDDNS_DOMAINS='example.com *.example.com'
CFDDNS_STACK=ipv6
CFDDNS_LOG_LEVEL=info
CFDDNS_PRIORITY_SUBNETS='2001:db8::/32 2001:db8:1::/48'
CFDDNS_MULTIHOST=true
CFDDNS_HOST_ID=homelab-node-1
CFDDNS_PROXY=enabled
CFDDNS_TTL=180
CFDDNS_RUN_EVERY=10m
CFDDNS_STATE_FILE=/tmp/cfddns-eth0.state

Usage:
cloudflare-dynamic-dns [flags]

Flags:
--config string config file (default is $HOME/.cloudflare-dynamic-dns.yaml)
--domains strings Domain names to assign the address to.
-h, --help help for cloudflare-dynamic-dns
--host-id string Unique host identifier. Must be specified in multihost mode.
Must be a valid DNS label. It is stored in the Cloudflare DNS comments field in
the format: "host-id (managed by cloudflare-dynamic-dns)"
--iface string Network interface to look up for an address.
--log-level string Sets logging level: trace, debug, info, warning, error, fatal, panic. (default "info")
--multihost Enable multihost mode.
In this mode it is possible to assign multiple addresses to a single domain.
For correct operation, this mode must be enabled on all participating hosts and
different host-ids must be specified for each host (see --host-id option).
--priority-subnets strings Subnets to prefer over others.
If multiple addresses are found on the interface,
the one from the subnet with the highest priority is used.
--proxy string Override proxy setting for created or updated DNS records.
If set to "auto", preserves the current state of an updated record.
Allowed values: "enabled", "disabled", "auto". (default "auto")
--run-every string Re-run the program every N duration until it's killed.
The format is described at https://pkg.go.dev/time#ParseDuration.
The minimum duration is 1m. Examples: 4h30m15s, 5m.
--stack string IP stack version: ipv4 or ipv6 (default "ipv6")
--state-file string Enables usage of a state file.
In this mode, the previously used address is preserved
between runs to avoid unnecessary calls to Cloudflare API.
Automatically selects where to store the state file if no
value is specified. See the State file section in usage.
--token string Cloudflare API token with DNS edit access rights.
--ttl int Time to live, in seconds, of the DNS record.
Must be between 60 and 86400, or 1 for 'automatic'. (default 1)
-v, --version version for cloudflare-dynamic-dns

Installation

AUR

There are two packages in AUR ( 1, 2 ), that can be used on Arch-based distros:

yay -S cloudflare-dynamic-dns
# OR
yay -S cloudflare-dynamic-dns-bin

Docker

See the container registry page for details.

docker pull ghcr.io/zebradil/cloudflare-dynamic-dns:latest

DEB, RPM, APK

See the latest release page for the full list of packages.

Manual

Download the archive for your OS from the releases page.

Or get the source code and build the binary:

git clone https://github.com/Zebradil/cloudflare-dynamic-dns.git
# OR
curl -sL https://github.com/Zebradil/cloudflare-dynamic-dns/archive/refs/heads/master.tar.gz | tar xz

cd cloudflare-dynamic-dns-master
go build -o cloudflare-dynamic-dns main.go

Now you can run cloudflare-dynamic-dns manually (see Usage section).

If you want to do some automation with systemd, cloudflare-dynamic-dns has to be installed system-wide (it is possible to run systemd timer and service without root privileges, but I do not provide ready-to-use configuration for this yet):

sudo install -Dm755 cloudflare-dynamic-dns -t /usr/bin
sudo install -Dm644 systemd/* -t /usr/lib/systemd/system
sudo install -m700 -d /etc/cloudflare-dynamic-dns/config.d

Usage examples

Run manually

Follow the steps from the Installation section.
Run ./cloudflare-dynamic-dns --domains 'example.com,*.example.com' --iface eth0 --token cloudflare-api-token
- NOTE: instead of compiling cloudflare-dynamic-dns binary, it can be replaced with go run main.go in the command above.

Instead of specifying command line arguments, it is possible to create ~/.cloudflare-dynamic-dns.yaml with the following structure:

iface: eth0
token: cloudflare-api-token
domains:
  - example.com
  - "*.example.com"

And then run ./cloudflare-dynamic-dns (or go run main.go) without arguments. Or put the configuration in any place and specify it with --config flag:

./cloudflare-dynamic-dns --config /any/place/config.yaml

Run in a Docker container

For the binary, the usage is the same as for the manual run. For the Docker container, we need to mount the configuration file into the container and provide access to the network stack of the host machine:

docker run --rm \
  --volume="/any/place/config.yaml:/config.yaml" \
  --network=host \
  ghcr.io/zebradil/cloudflare-dynamic-dns:latest \
    --config=/config.yaml

To run the program in daemon mode, add --run-every flag (and --detach if you want to run it in the background):

docker run --rm \
  --volume="/any/place/config.yaml:/config.yaml" \
  --network=host \
  --detach \
  ghcr.io/zebradil/cloudflare-dynamic-dns:latest \
    --config=/config.yaml \
    --run-every=5m

Systemd service and timer

It is possible to run cloudflare-dynamic-dns periodically via systemd. This requires privileged access to the system. Make sure that required systemd files are installed (see Installation section for details).

# 1. Create configuration file `/etc/cloudflare-dynamic-dns/config.d/<name>.yaml`
#    For example (I use "example.com" as <name>, replace the values according to your needs):
sudo tee -a /etc/cloudflare-dynamic-dns/config.d/example.com.yaml <<EOF
iface: eth0
token: cloudflare-api-token
domains:
  - example.com
  - "*.example.com"
EOF

# 3. Enable systemd timer
sudo systemctl enable --now [email protected]

This way (via running multiple timers) you can use multiple configurations at the same time.

By default, a timer is triggered one minute after boot and then every 5 minutes. It is not configurable currently.

State files are used to avoid unnecessary requests to Cloudflare API. They're created in /var/lib/cloudflare-dynamic-dns/ and named using configuration variables in corresponding config files (iface and a hash of domains). A state file contains an address which was set in a Cloudflare DNS AAAA or A record during the last successful run. If the current address is the same as the one in the state file, no additional API requests are done.

Development

Builds and releases are done with goreleaser.

There are several ways to build the application:

# Build with go for the current platform
go build -o cloudflare-dynamic-dns main.go

# Build with GoReleaser for all configured platforms
task go:build

# Use Docker
docker build -t cloudflare-dynamic-dns -f dev.Dockerfile .

Check the Taskfile.yml for more details.

GeReleaser

⚠️ Do not change .goreleaser.yml manually, do changes in .goreleaser.ytt.yml and run task misc:build:goreleaser-config instead (requires ytt installed).

Documentation

The usage section is generated by the update_readme script. For convenience, task docs:update-readme can be used to run it.

License

MIT

Disclaimer

This project is not affiliated with Cloudflare.

	h := fnv.New64a()
	domainHash := h.Sum([]byte(strings.Join(domains, " ")))
	stateFilepath = fmt.Sprintf("%s_%s_%x", iface, stack, domainHash)

zebradil / cloudflare-dynamic-dns Goto Github PK

cloudflare-dynamic-dns's Introduction

Dynamic DNS client for Cloudflare

Features

Usage

Installation

AUR

Docker

DEB, RPM, APK

Manual

Usage examples

Run manually

Run in a Docker container

Systemd service and timer

Development

GeReleaser

Documentation

License

Disclaimer

cloudflare-dynamic-dns's People

Contributors

Stargazers

Watchers

Forkers

cloudflare-dynamic-dns's Issues

Ignored or Blocked

Detected dependencies

Recommend Projects

Recommend Topics

Recommend Org