DynamicDNS

DynamicDNS is a lightweight, cross-platform Minecraft plugin and proxy extension that keeps your subservers connected and reachable even when hosted on dynamic IP addresses (such as home servers or VPS nodes without static IPs).

No separate port forward, custom daemons or DNS propagation delays are required — address changes are synchronized in real-time directly through Minecraft's native networking layer.

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 open ports or firewall adjustments are needed on the proxy.
• HMAC-SHA256 Handshake Verification: Cryptographic handshake signatures verify authenticity without exposing the raw secret token over the wire, with seamless backward-compatibility for legacy payloads.
• Proxy Configuration Persistence: Automatically registers, updates, and persists subserver addresses directly into velocity.toml (Velocity) or config.yml (BungeeCord).
• Subserver Status & Last Update Tracking: Displays real-time registration status and accurate last update timestamps recorded directly on the proxy.
• Multiple DDNS Providers:
  • Cloudflare DNS API: Automated updates for root or subdomain A (IPv4) and AAAA (IPv6) records with configurable proxy (orange cloud) status.
  • DuckDNS: Instant HTTP/HTTPS updates with dual-stack IPv4 and IPv6 support.
  • No-IP / DynDNS v2: Automated hostname updates using HTTP Basic Auth.
  • Dynu DDNS: Updates Dynu domains and SRV records automatically with your current public IP address or ngrok hostname.
• Dual-Stack IPv4 & IPv6 Detection: Native public IPv4 and IPv6 resolution via redundant global lookup services.
• Built-in ngrok Tunneling: Automatically exposes local servers via ngrok TCP tunnels and propagates the assigned public tunnel endpoint to your proxy or Dynu.
• Integrated Modrinth Update Checker: Checks for new releases against the Modrinth API asynchronously in the background.
• All-in-One Universal Jar: One unified artifact supports all platforms.

Supported Platforms

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         |
+-------------------------------------------------------------------+

1. The subserver runs a repeating background task sending a handshake ping to the proxy's regular Minecraft address and port.
2. The payload contains the subserver identifier, target port/IP, and a 32-character HMAC-SHA256 signature calculated with the shared secret token.
3. The proxy verifies the signature using its shared secret.
4. The proxy updates the subserver route dynamically in memory, persists it to file, records the proxy-side last update timestamp, and terminates the sync ping handshake without proxying player traffic.

Installation & Setup

1. Proxy Setup (Velocity or BungeeCord)

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

   server_sync:
     enabled: true
     token: "YOUR_SECRET_TOKEN" # If left blank, a UUID token is automatically generated on startup
   

4. Copy the secret token for use on your subservers.

2. Subserver Setup (Paper, Spigot or Sponge)

1. Drop DynamicDNS.jar into your subserver's plugins/ (or mods/ on Sponge) directory.
2. Start or restart the 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 your proxy
     name: "survival"                    # The server ID registered on the proxy
     target_address: "proxy.host:25565"  # Host and port of your proxy server
     interval: 30                        # Sync interval in seconds
   

4. Reload the configuration with /dynamicdns reload or restart the subserver. The proxy will automatically register the subserver's current IP and port.

Commands & Permissions

The dynamicdns.admin permission grants full access to all commands. By default, permissions are granted to server operators (op) or administrators.