ddns-pdns-updater/README.md

PowerDNS DDNS Updater

Hybrid DDNS service for PowerDNS environments. Automatically synchronizes external Infomaniak DNS updates with PowerDNS internal A record management via systemd service and timer.

Features

• Dual DNS Management: Updates both external (Infomaniak) and internal (PowerDNS) DNS records
• Automatic IP Detection: Fetches current external IP using ifconfig.me
• Smart Updates: Only updates records when IP address changes
• Comprehensive Logging: Tracks IP changes and DNS updates with timestamps
• Systemd Integration: Runs automatically as background service with configurable intervals
• Multi-Domain Support: Manages multiple internal PowerDNS domains from single configuration
• Error Handling: Validates IP addresses and handles API failures gracefully

Architecture

The service consists of four main components:

1. Main Script (pdns-ddns) - Core logic for IP detection and DNS updates
2. Configuration (ddns.conf) - API credentials and domain settings
3. Systemd Service (pdns-ddns.service) - Service definition for one-shot execution
4. Systemd Timer (pdns-ddns.timer) - Scheduler running every minute

Installation

1. Clone and Setup Files

# Create directories
sudo mkdir -p /etc/powerdns

# Copy files to system locations
sudo cp pdns-ddns /usr/local/bin/
sudo cp ddns.conf /etc/powerdns/
sudo cp pdns-ddns.service /etc/systemd/system/
sudo cp pdns-ddns.timer /etc/systemd/system/

# Make script executable
sudo chmod +x /usr/local/bin/pdns-ddns

2. Configure Settings

Edit the configuration file:

sudo nano /etc/powerdns/ddns.conf

Update the following variables:

# Infomaniak API credentials
INFOMANIAK_TOKEN="your-infomaniak-api-token"
INFOMANIAK_DOMAIN="your-external-domain.com"

# Internal PowerDNS domains (space-separated)
POWERDNS_DOMAINS="internal1.com internal2.xyz"

# DNS record TTL in seconds
TTL=300

3. Enable and Start Service

# Reload systemd configuration
sudo systemctl daemon-reload

# Enable and start the timer
sudo systemctl enable pdns-ddns.timer
sudo systemctl start pdns-ddns.timer

# Check status
sudo systemctl status pdns-ddns.timer

Configuration

Infomaniak API Setup

1. Log into your Infomaniak account
2. Navigate to API settings
3. Generate an API token with DNS management permissions
4. Add the token to INFOMANIAK_TOKEN in the configuration

PowerDNS Requirements

The script requires PowerDNS with the following tools installed:

• pdnsutil - PowerDNS utility for zone management
• Proper permissions for the script to modify DNS zones

Supported Domains

• External: Single Infomaniak-managed domain
• Internal: Multiple PowerDNS zones (space-separated in config)

Usage

Manual Execution

Run the script manually for testing:

sudo /usr/local/bin/pdns-ddns

Service Management

# Check timer status
sudo systemctl status pdns-ddns.timer

# View recent service runs
sudo systemctl status pdns-ddns.service

# Check logs
sudo journalctl -u pdns-ddns.service -f

# Stop/start the timer
sudo systemctl stop pdns-ddns.timer
sudo systemctl start pdns-ddns.timer

Changing Update Interval

Edit the timer configuration:

sudo nano /etc/systemd/system/pdns-ddns.timer

Modify the OnCalendar setting:

• Every minute: OnCalendar=*:*
• Every 5 minutes: OnCalendar=*:*/5
• Every hour: OnCalendar=hourly

Then reload and restart:

sudo systemctl daemon-reload
sudo systemctl restart pdns-ddns.timer

Logging

IP Change History

The service maintains an IP change log at /var/log/ddns-ip-history.log:

# View recent IP changes
sudo tail -f /var/log/ddns-ip-history.log

# View all changes
sudo cat /var/log/ddns-ip-history.log

System Logs

View detailed execution logs:

# Follow live logs
sudo journalctl -u pdns-ddns.service -f

# View recent logs
sudo journalctl -u pdns-ddns.service --since "1 hour ago"

# View logs with timestamps
sudo journalctl -u pdns-ddns.service -o short-iso

Troubleshooting

Common Issues

Script fails with permission errors:

# Ensure proper ownership and permissions
sudo chown root:root /usr/local/bin/pdns-ddns
sudo chmod 755 /usr/local/bin/pdns-ddns

Infomaniak API errors:

• Verify API token has DNS management permissions
• Check domain name spelling in configuration
• Ensure API token hasn't expired

PowerDNS errors:

• Verify pdnsutil is installed and accessible
• Check PowerDNS service is running: sudo systemctl status pdns
• Ensure script has permissions to modify DNS zones

IP detection fails:

• Check internet connectivity
• Verify curl is installed
• Test manually: curl -s ifconfig.me

Debug Mode

Run the script manually to see detailed output:

sudo bash -x /usr/local/bin/pdns-ddns

Logs Analysis

Check for specific error patterns:

# API errors
sudo journalctl -u pdns-ddns.service | grep -i error

# IP changes
sudo journalctl -u pdns-ddns.service | grep "IP changed"

# PowerDNS operations
sudo journalctl -u pdns-ddns.service | grep "PowerDNS"

Security Considerations

• Store API tokens securely in the configuration file
• Limit file permissions: sudo chmod 600 /etc/powerdns/ddns.conf
• Regularly rotate Infomaniak API tokens
• Monitor logs for unauthorized access attempts
• Consider firewall rules for PowerDNS management access

Dependencies

Required Packages

# Ubuntu/Debian
sudo apt update
sudo apt install curl jq

# CentOS/RHEL
sudo yum install curl jq

# PowerDNS (if not already installed)
sudo apt install pdns-server pdns-tools

System Requirements

• Linux system with systemd
• PowerDNS server with pdnsutil
• Internet connectivity for IP detection and Infomaniak API
• Root or sudo access for DNS modifications

License

This project is open source. Feel free to modify and distribute according to your needs.

Contributing

Contributions are welcome! Please ensure any changes maintain compatibility with existing PowerDNS and Infomaniak setups.