DynamicDNS ✅ Keeps your subserver online by auto-updating it

Cross-platform Minecraft plugin and proxy extension for dynamic IP environments

Keep your backend subservers connected to your proxy without static IPs, port forwarding, external daemons, or DNS propagation delays. Synchronize address updates instantly through native Minecraft networking.

★ Key Features

• Port-Free Subserver Synchronization: Subservers ping the proxy using native Minecraft Handshake packets signed with HMAC-SHA256 (sync.v2.<name>.<port>.<signature>). No extra firewall ports or open sockets needed.
• Cryptographic Security: Handshake signatures verify authenticity without exposing your raw secret token over the network.
• Automatic Proxy Configuration Persistence: Updates and saves subserver IP/port changes directly to velocity.toml (Velocity) or config.yml (BungeeCord).
• Live Status & Timestamp Tracking: Monitor real-time subserver registrations and proxy-recorded last update timestamps.
• Popular DDNS Providers Supported:
  • Cloudflare DNS API: Automated root or subdomain A and AAAA updates with configurable Cloudflare proxy status.
  • DuckDNS: Fast HTTP/HTTPS updates with dual-stack IPv4 and IPv6 support.
  • No-IP / DynDNS v2: Hostname updates via HTTP Basic Auth.
  • Dynu DDNS: Automated domain and SRV updates for dynamic IPs or ngrok endpoints.
• Dual-Stack IPv4 & IPv6 Detection: Redundant global lookup services resolve external addresses accurately.
• Built-in ngrok Tunneling: Automatically create TCP tunnels for local/home-hosted servers and propagate endpoints to the proxy or Dynu.
• Universal Jar: One unified binary runs everywhere — on both proxies and backend game servers.

★ Supported Platforms
Proxies:

• Velocity: 3.x / 4.x
• BungeeCord / Waterfall: 1.8.8 – 26.4

Subservers (Backends):

• Paper / Purpur / Spigot / Folia: 1.8.8 – 26.4
• Sponge: SpongeAPI 8+ (Minecraft 1.16.5+)

★ How It Works

+-------------------------------------------------------------------+
|               Subserver (Spigot / Paper / Sponge)                 |
|                                                                   |
|   1. Periodically sends handshake ping:                           |
|      virtualHost = "sync.v2.<name>.<port>.<hmac>"                 |
+---------------------------------+---------------------------------+
                                  |
                (Standard Minecraft Port, e.g. 25565)
                                  v
+-------------------------------------------------------------------+
|                 Proxy (Velocity / BungeeCord)                     |
|                                                                   |
|   2. Intercepts incoming handshake/ping connection                |
|   3. Verifies HMAC-SHA256 signature                               |
|   4. Updates subserver address in proxy server registry           |
|   5. Saves updated address to velocity.toml or config.yml         |
|   6. Records 'last update' timestamp and drops connection         |
+-------------------------------------------------------------------+

★ Installation & Setup
1. Proxy Setup (Velocity or BungeeCord)

1. Place DynamicDNS.jar into your proxy's plugins/ folder.
2. Start or restart the proxy to generate plugins/DynamicDNS/config.yml.
3. Open the config and enable synchronization:
   

   server_sync:
     enabled: true
     token: "YOUR_SECRET_TOKEN" # Generates automatically if left empty

4. Copy your secret token to configure backend servers.

2. Subserver Setup (Paper, Spigot, Sponge)

1. Place DynamicDNS.jar into your backend's plugins/ (or mods/ on Sponge) folder.
2. Start or restart the backend server to generate config.yml.
3. Configure plugins/DynamicDNS/config.yml:
   

   server_sync:
     enabled: true
     token: "YOUR_SECRET_TOKEN"          # Must match the token set on the proxy
     name: "survival"                    # Server ID registered in velocity.toml / config.yml
     target_address: "proxy.host:25565"  # Host and port of your proxy server
     interval: 30                        # Sync interval in seconds

4. Run /dynamicdns reload or restart the backend server.

★ Configuration Reference

# Global debug logging - logs every sync ping sent and hook execution
debug: false

# Automatically check for updates on startup via Modrinth
check_updates: true

# Configuration for ngrok - creates secure tunnels to local servers
ngrok:
  enabled: false
  token: ""
  region: "US"

# Configuration for Dynu Dynamic DNS - updates a domain record with current IP address
dynu:
  enabled: false
  domain: "example.dynu.com"
  client: ""
  secret: ""

# Configuration for Cloudflare DNS API (A and AAAA records)
cloudflare:
  enabled: false
  api_token: ""
  zone_id: ""
  record_name: "play.yourdomain.com"
  proxied: false
  update_ipv6: false

# Configuration for DuckDNS
duckdns:
  enabled: false
  domain: "myserver"
  token: ""
  update_ipv6: false

# Configuration for No-IP / DynDNS v2
noip:
  enabled: false
  hostname: "myserver.ddns.net"
  username: ""
  password: ""

# Subserver address synchronization via Minecraft Handshake ping
server_sync:
  # Enable synchronization (true on proxy to accept pings; true on subserver to send pings)
  enabled: false
  # Shared secret token for authenticating subservers with the proxy
  token: ""
  # Subserver identifier configured on the proxy (Subserver only, e.g. "survival")
  name: "survival"
  # Target proxy address and port (Subserver only, e.g. "123.123.123.123:25565")
  target_address: "123.123.123.123:25565"
  # Interval in seconds between sync pings sent to proxy (Subserver only)
  interval: 30

★ Commands & Permissions

• /dynamicdns status (alias: /ddns status)
  Displays active hooks, registered subservers, and last update timestamps.
  Permission: dynamicdns.status
  
• /dynamicdns sync (alias: /ddns sync)
  Forces an immediate sync ping to the proxy (subserver only).
  Permission: dynamicdns.sync
  
• /dynamicdns reload (alias: /ddns reload)
  Reloads config.yml and restarts background tasks.
  Permission: dynamicdns.reload
  
• /dynamicdns update (alias: /ddns update)
  Checks Modrinth for available plugin releases.
  Permission: dynamicdns.update

Administrative bypass permission: dynamicdns.admin (granted to server operators by default).