Ansible Role: ddclient

Installs and configures ddclient for dynamic DNS updates.

Example Playbook

---
- hosts: servers
  roles:
    - role: ddclient
      vars:
        ddclient_daemon_interval: 300 # Checks IP every 5 minutes (default, can be omitted)
        ddclient_ipv4_detection: # Use ipify service to get your public IPv4 address
          method: webv4
          source: ipify-ipv4
        ddclient_ipv6_detection: {} # Disable ipv6 detection
        ddclient_protocols: # Use cloudflare to update your DNS records
          - protocol: cloudflare
            zone: example.com
            password: "{{ vault_cloudflare_token }}"
            ttl: 600
            domains:
              - home.example.com
              - vpn.example.com

Role Variables

Note

Read the ddclient general documentation to familiarize yourself with the global configuration options.

IPv4 Detection Configuration

The ddclient_ipv4_detection dictionary contains:

Key	Default	Description
method	webv4	Detection method: ipv4, ifv4, webv4, fwv4, cmdv4
source	dyndns	Source URL/interface/command (provider name or full URL)
skip_pattern		Pattern to skip in output

IPv6 Detection Configuration

The ddclient_ipv6_detection dictionary contains the same keys as IPv4, with method supporting: ipv6, ifv6, webv6, fwv6, cmdv6

To disable either IPv6 or IPv4 detection, set to empty dict:

ddclient_ipv6_detection: {}

Firewall Authentication

Only applicable if using the IP detection method fw.

Variable	Default	Description
ddclient_fw_login		Firewall login username
ddclient_fw_password		Firewall password

Protocol Configuration

Common keys:

Key	Required	Description
protocol	Yes	Protocol type (e.g., cloudflare, dyndns2, namecheap)
domains	Yes	List of hostnames to update
login	Yes*	Username/email/domain
password	Yes*	Password/API key/token
zone	No	Zone/domain name (Cloudflare, nsupdate)
ttl	No	DNS TTL in seconds
server	No	update DNS information on this server
mx	No	Mail exchanger hostname
backupmx	No	Backup MX flag (yes/no)
wildcard	No	Wildcard DNS flag (yes/no)
custom	No	Custom domain flag (yes/no)
tcp	No	Use TCP instead of UDP (yes/no)

Note

*Required fields depend on the protocol Read the ddclient protocol documentation to know which options must be specified for a given protocol.

Daemon Settings

Variable	Default	Description
ddclient_daemon_interval	300	Check interval in seconds (0 = run once)
ddclient_foreground	false	Run in foreground (don't fork)
ddclient_pid	""	PID file path (empty = use default)
ddclient_cache	""	Cache file path (empty = use default)

Network Settings

Variable	Default	Description
ddclient_ssl	true	Use SSL/HTTPS for updates
ddclient_proxy		HTTP proxy hostname (empty = no proxy)
ddclient_timeout	0	Connection timeout in seconds (0 = no timeout)

Logging Settings

Variable	Default	Description
ddclient_syslog	true	Log to syslog
ddclient_facility	daemon	Syslog facility
ddclient_priority	notice	Syslog priority
ddclient_mail		Email address for notifications
ddclient_mail_failure		Email address for failure notifications
ddclient_verbose	false	Verbose output
ddclient_quiet	false	Suppress unnecessary update messages
ddclient_debug	false	Debug output

Update Behavior

Variable	Default	Description
ddclient_exec	true	Execute updates (false = dry-run)
ddclient_retry	false	Retry failed updates
ddclient_force	false	Force updates even if unnecessary
ddclient_postscript		Script to run after update

More Example Playbooks

Multiple Providers

---
- hosts: servers
  roles:
    - role: ddclient
      vars:
        ddclient_protocols:
          - protocol: cloudflare
            zone: company.com
            login: token
            password: "{{ vault_cloudflare_password }}"
            domains:
              - www.company.com
              - api.company.com
          - protocol: dyndns2
            server: domains.google.com
            login: service-login
            password: "{{ vault_service_password }}"
            domains:
              - backup.ddns.net

Interface-based Detection (Server with Public IP)

---
- hosts: servers
  roles:
    - role: ddclient
      vars:
        ddclient_ipv4_detection:
          method: ifv4
          source: eth0
        ddclient_protocols:
          - protocol: cloudflare
            zone: example.com
            login: token
            password: "{{ vault_cloudflare_token }}"
            domains:
              - server.example.com

Dual-Stack (IPv4 + IPv6)

---
- hosts: servers
  roles:
    - role: ddclient
      vars:
        ddclient_ipv4_detection:
          method: webv4
          source: checkip.amazonaws.com
        ddclient_ipv6_detection:
          method: webv6
          source: checkipv6.dyndns.org
        ddclient_protocols:
          - protocol: cloudflare
            zone: example.com
            login: admin@example.com
            password: "{{ vault_cloudflare_token }}"
            ttl: 600
            domains:
              - dualstack.example.com

Dry-Run Mode (Testing)

---
- hosts: servers
  roles:
    - role: ddclient
      vars:
        ddclient_exec: false  # Don't actually update DNS
        ddclient_verbose: true
        ddclient_protocols:
          - protocol: cloudflare
            zone: example.com
            login: token
            password: test-token
            domains:
              - test.example.com

IP Detection Methods

Web-based (webv4/webv6)

Queries a web service to detect public IP. Best for systems behind NAT.

ddclient_ipv4_detection:
  method: webv4
  source: checkip.amazonaws.com  # or dyndns, googledomains, etc.

Interface-based (ifv4/ifv6)

Reads IP directly from a network interface. Best for servers with public IPs.

ddclient_ipv4_detection:
  method: ifv4
  source: eth0

Firewall/Router-based (fwv4/fwv6)

Queries router's status page for WAN IP.

ddclient_ipv4_detection:
  method: fwv4
  source: 192.168.1.1/Status.htm
  skip_pattern: "WAN IP Address"
ddclient_fw_login: admin
ddclient_fw_password: routerpass

Command-based (cmdv4/cmdv6)

Executes a custom script/command to get IP.

ddclient_ipv4_detection:
  method: cmdv4
  source: /usr/local/bin/get-public-ip.sh

License

MIT