ansible-role-ddclient/README.md

# Ansible Role: ddclient

Installs and configures ddclient for dynamic DNS updates.

## Example Playbook

```yaml
---
- 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](https://ddclient.net/general.html) 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:
```yaml
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](https://ddclient.net/protocols.html) 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

```yaml
---
- 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)

```yaml
---
- 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)

```yaml
---
- 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)

```yaml
---
- 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.

```yaml
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.

```yaml
ddclient_ipv4_detection:
  method: ifv4
  source: eth0
```

### Firewall/Router-based (fwv4/fwv6)
Queries router's status page for WAN IP.

```yaml
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.

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

## License

MIT