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

```bash
# 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:

```bash
sudo nano /etc/powerdns/ddns.conf
```

Update the following variables:

```bash
# 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

```bash
# 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:

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

### Service Management

```bash
# 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:

```bash
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:

```bash
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`:

```bash
# 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:

```bash
# 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:**
```bash
# 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:

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

### Logs Analysis

Check for specific error patterns:

```bash
# 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

```bash
# 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.