Skip to main content

Minecraft Worlds

Quickstart: Bring a World Up

    Allocate IP, Velocity route, and DNS:

    sudo /data/minecraft/velocity/ipctl create <name> --dns

    (Allocates backend IPv6 fd77:7777:5010::1337:3c:d00d:<hex>/64, adds route in velocity.toml, configures <name>.drheck.dev in Unbound on danknasty, and syncs to deSEC).

    Configure the backend server: In your backend server's server.properties:

    server-ip=fd77:7777:5010::1337:3c:d00d:<hex>
server-port=25565
online-mode=false

    (If using Paper/Fabric modern player forwarding, enable Velocity forwarding and paste the secret from /data/minecraft/velocity/forwarding.secret).

    Start backend & Velocity:

      Launch your backend Minecraft server. Start or reload Velocity: 
      cd /data/minecraft/velocity && java -jar velocity.jar
      (Or reload config in Velocity console with /velocity reload).

      Connect: Join using <name>.drheck.dev (standard port 25565).

      Quickstart: Take a World Down

        Stop the backend server: Run stop in the Minecraft server console or terminate its process.

        Disable or remove proxy routing & DNS:

          Temporary takedown (disable in Velocity only): 
          sudo /data/minecraft/velocity/ipctl velocity disable <name>
          Complete teardown (release IP, remove Velocity route, purge DNS): 
          sudo /data/minecraft/velocity/ipctl delete <name> --dns

          Architecture & Design Details

          1. Unified Endpoint Model

          All public and LAN client connections resolve to the single Velocity Proxy endpoint pair:

            IPv4: 10.0.0.113 IPv6: fd77:7777:5010::1337:f1ac:d00d:3c

            Whether connecting via minecraft.drheck.dev, survival.drheck.dev, or another server subdomain, players connect to this same IP pair on standard port 25565.

            2. SNI / Virtual Host Routing (forced-hosts)

            Minecraft clients transmit the domain name entered in the multiplayer menu during the handshake packet. Velocity inspects this hostname and routes traffic according to forced-hosts in /data/minecraft/velocity/velocity.toml:

            [servers]
survival = "[fd77:7777:5010::1337:3c:d00d:1]:25565"

[forced-hosts]
"survival.drheck.dev" = [
    "survival"
]

            Any unmatched hostnames fallback to the try lobby list.

            3. Backend IPv6 Address Scheme

            Each backend Minecraft server is isolated on a dedicated, internal Unique Local Address (ULA) on interface eth77 of ul:

              Prefix: fd77:7777:5010::1337:3c:d00d:<hex>/64 Port: Each server binds to standard port 25565 on its assigned IPv6 address. Security: Backend IPv6 addresses are not published in external DNS or forwarded via router NAT/firewall. Only Velocity communicates directly with the backends over internal IPv6.

              4. Network & DNS Automation (ipctl)

              The tool /data/minecraft/velocity/ipctl automates the entire provisioning workflow:

                Local Network (ul): Appends or removes Address=fd77:7777:5010::1337:3c:d00d:<hex>/64 # <name> in /etc/systemd/network/20-wired.network and triggers networkctl reload. Proxy Configuration: Updates [servers] and [forced-hosts] inside /data/minecraft/velocity/velocity.toml. Router DNS (danknasty): When --dns is passed:
                  Updates the git working tree at /home/luke/git/router_config/unbound.conf. Verifies syntax using doas unbound-checkconf. Deploys the configuration to /var/unbound/etc/unbound.conf. Restarts Unbound via doas rcctl restart unbound. Verifies local resolution via dig @10.0.0.1. Executes python3 /home/luke/git/router_config/dns_danger_sync.py --force to synchronize public A and AAAA records on deSEC.io.