English | 中文

DDNS Tool

An intelligent DNS update tool designed for dynamic IP servers. Automatically triggers server IP changes when client heartbeat times out, ensuring continuous service availability.

Features

Server

• Automatically fetches current IP and updates Cloudflare DNS
• Supports multiple IP service URLs with automatic failover
• Supports various IP response formats (plain text, JSON, etc.)
• Listens for client heartbeats using reliable TCP protocol
• Automatically changes IP after heartbeat timeout with exponential backoff strategy
• Monitors IP changes every minute and updates DNS automatically
• Comprehensive logging with log rotation

Client

• Sends TCP heartbeat to server every 30 seconds
• Automatic reconnection and error handling
• Heartbeat success rate statistics
• Logging support with rotation

Requirements

• Debian/Ubuntu system
• Python 3.6+
• pip3
• systemd

Installation

Server Installation

1. Clone or download this project to your server

2. Install server:

   sudo ./install.sh server

3. Edit configuration file /etc/ddns/server_config.yaml:

   domain: your-subdomain.example.com
   cf_email: your-email@example.com
   cf_key: your-cloudflare-api-key
   get_ip_url: http://your-ip-service.com/get_ip
   change_ip_url: http://your-ip-service.com/change_ip
   port: 8888
   heartbeat_timeout: 180

4. Start service:

   sudo systemctl start ddns-server
   sudo systemctl enable ddns-server

Client Installation

1. Clone or download this project to client machine

2. Install client (replace your-server.com with actual domain):

   sudo ./install.sh client your-server.com 8888

3. Start service:

   sudo systemctl start ddns-client
   sudo systemctl enable ddns-client

Configuration

Server Configuration

• domain: Domain to update (must be managed by Cloudflare)
• cf_email: Cloudflare account email
• cf_key: Cloudflare API key (global API key)
• get_ip_url: API URL to get current IP, supports:
  • Single URL string: get_ip_url: http://your-ip-service.com/get_ip
  • URL list (tries in order):

    get_ip_url:
      - http://your-ip-service.com/get_ip
      - https://api.ipify.org
      - http://ip.42.pl/raw

  • Supports various formats: plain IP text, JSON format, etc., automatically extracts IP address
• change_ip_url: API URL to change IP
• port: TCP listening port (default 8888)
• heartbeat_timeout: Heartbeat timeout in seconds (default 180)
• ttl: DNS A record TTL in seconds (default 60)
• log_dir: Log file directory (default /var/log/ddns)
• debug: Enable debug logging (default false)

Getting Cloudflare API Key

1. Login to Cloudflare
2. Go to Profile -> API Tokens
3. View Global API Key

Service Management

Server

# Check status
sudo systemctl status ddns-server

# View logs
sudo journalctl -u ddns-server -f

# Restart service
sudo systemctl restart ddns-server

Client

# Check status
sudo systemctl status ddns-client

# View logs
sudo journalctl -u ddns-client -f

# Restart service
sudo systemctl restart ddns-client

How It Works

1. Server fetches current IP on startup and updates DNS record
2. Server listens on TCP port for client heartbeat connections
3. Client establishes TCP connection every 30 seconds to send heartbeat, server responds with acknowledgment
4. If no heartbeat received within 3 minutes, server requests IP change
5. After IP change, uses exponential backoff strategy (3 minutes, 6 minutes, 12 minutes... up to 24 hours)
6. Server checks for IP changes every minute and updates DNS automatically
7. All operations are logged to files with rotation support

Log Files

• Server logs: /var/log/ddns/ddns_server.log
• Client logs: /var/log/ddns/ddns_client.log
• Automatic log rotation: server keeps 5 files (10MB each), client keeps 3 files (5MB each)

Troubleshooting

1. Check if Python dependencies are installed completely
2. Verify configuration file permissions (should be 600)
3. Check if firewall allows TCP port (default 8888)
4. View log files for detailed error information:

   # Real-time server logs
   tail -f /var/log/ddns/ddns_server.log
   
   # Real-time client logs
   tail -f /var/log/ddns/ddns_client.log