Initial role commit

2025-11-29 20:45:14 -05:00
parent 9842c9de76
commit 7cca78254e
7 changed files with 464 additions and 2 deletions
--- a/README.md
+++ b/README.md
@@ -1,3 +1,256 @@
-# ansible-role-ddclient-cloudflare
+# Ansible Role: ddclient

-Simple Ansible for setting up Dynamic DNS with ddclient and cloudflare
+Configures and manages 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