Skip to main content

Minecraft Worlds

Quickstart: Bring a World Up

  1. Allocate IP, VelocitySNI route,Route, and DNS:

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

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

  2. 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=falsetrue

    (IfBackend usingservers Paper/Fabricrun modernstock playervanilla forwarding, enable Velocity forwarding and paste the secret fromMinecraft, /data/minecraft/velocity/forwarding.secretonline-mode=true, listening on standard port 25565).

  3. Start backendthe &server: Velocity:

    • Launch your backend Minecraft server.
    server Starton orUL. reloadIt Velocity:binds 
    cdto /data/minecraft/velocityits &&dedicated javaIPv6 -jar velocity.jar
    (Or reload config in Velocity console with /velocity reload). address.

    Connect: JoinPlayers connect using <name>.drheck.dev (standard port 25565). Microsoft account authentication takes place directly between the client and your backend server.

    Quickstart: Take a World Down

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

    2. Disable or remove proxyrouter routingmapping & DNS:

      • Temporary takedown (disable in Velocityrouter only): 
        sudo /data/minecraft/velocity/ipctl velocityroute disable <name>
      • Complete teardown (release IP, remove VelocityHAProxy 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 VelocityMinecraft ProxyRouter endpoint pair:

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

    Whether connecting via minecraft.pokelovers.drheck.dev, survival.drheck.dev, or anotherany other server subdomain, players connect to this sameexact IP pair on standard port 25565.

    2. Transparent TCP SNI / Virtual HostHandshake Routing (forced-hosts)HAProxy)

    MinecraftRather clientsthan transmitusing thean domainapplication-level nameproxy entered(which inbreaks thevanilla multiplayerDiffie-Hellman menu during the handshake packet. Velocity inspects this hostnameencryption and routes traffic according toforces forced-hostsonline-mode=false), HAProxy performs transparent pre-handshake packet inspection:

      HAProxy listens dual-stack on 10.0.0.113:25565 inand /data/minecraft/velocity/velocity.toml: 
      [servers]
survival = "[fd77:7777:5010::1337:3c:f1ac:d00d:1]3c]:25565"25565.
      [forced-hosts]When "survival.a player connects, HAProxy peeks at the initial unencrypted Minecraft handshake packet (0x00) via /etc/haproxy/minecraft.lua and extracts the requested hostname (e.g. pokelovers.drheck.dev"dev). =It [looks "survival"up ]the target backend in /etc/haproxy/minecraft_hosts.map.

      Any

      It unmatchedsplices hostnamesthe fallbackraw TCP stream directly to that server's dedicated internal IPv6 address on port 25565. The client and backend perform native Microsoft/Mojang online-mode=true authentication directly over the tryspliced lobbyTCP list.connection.

      3. Backend IPv6 Address Scheme

      Each backend Minecraft server is isolated on a dedicated, internaldedicated 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 notcompletely publishedinternal inand externalhidden DNS or forwarded via router NAT/firewall. Only Velocity communicates directly withbehind the backendsproxy over internal IPv6.router.

      4. Network & DNS Automation (ipctl)

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

      • Local Network (ul): Appends or removes # <name> and Address=fd77:7777:5010::1337:3c:d00d:<hex>/64 # <name> in /etc/systemd/network/20-wired.network and triggers networkctl reload.
      • ProxyRouter Configuration:Configuration (ul): Updates [servers]/etc/haproxy/minecraft_hosts.map and [forced-hosts]backend insidestanzas in /data/minecraft/velocity/velocity.tomletc/haproxy/haproxy.cfg, then reloads haproxy.service.
      SSH Key Verification: Verifies that key SHA256:7Xr0vCxgfpPhbKE3hN9fE2IC9y4x3Kj+kYmXwzgJY3s (ultra-arikui) is loaded in the agent before running remote router commands. Router DNS (danknasty): When --dns is passed:
      1. Updates the git working tree at /home/luke/git/router_config/unbound.conf.
      2. Verifies syntax using doas unbound-checkconf.
      3. Deploys the configuration to /var/unbound/etc/unbound.conf.
      4. Restarts Unbound via doas rcctl restart unbound.
      5. Verifies local resolution via dig @10.0.0.1.
      6. Executes python3 /home/luke/git/router_config/dns_danger_sync.py --force to synchronize public A and AAAA records on deSEC.io.