populated repository

README.md

@@ -1,3 +1,260 @@
-# ddns-powerdns-updater
+# PowerDNS DDNS Updater
 
-Hybrid DDNS service for PowerDNS setups. Synchronizes external Infomaniak updates with PowerDNS internal A record management via systemd.
+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.