DirtSimpleP2P/README.md

DirtSimpleP2P

DirtSimpleP2P lets a public Bungee/Waterfall proxy reach a Paper/Spigot server that is running at home behind NAT.

You do not need to open the Minecraft port on your home router. The backend server connects outbound to your public proxy/VPS, then Minecraft traffic is carried through that tunnel.

What You Get

• One jar file for both servers
• No home router port forwarding
• Works with a public Bungee/Waterfall proxy
• Works with a backend Paper/Spigot server
• Secret-token authentication
• Automatic secret-token generation
• Optional TLS encryption with generated self-signed certificates
• Multiple Minecraft player connections over one tunnel
• Fast reconnect with heartbeat-based latency tolerance
• /dsp2p status and /dsp2p doctor commands
• Simple properties config files

Current Status

This is still a development build, not a paid release build yet.

The tunnel core exists and the plugin jar builds. TLS can now generate a self-signed certificate when enabled, but before paid release it should get more real-world testing on actual Bungee and Paper servers.

Build The Jar

From this project folder, run:

mvn clean package

The plugin jar will be here:

plugin/target/DirtSimpleP2P-0.1.0-SNAPSHOT.jar

Use this same jar on both servers.

Basic Setup

You need two Minecraft-side servers:

• Public proxy server: BungeeCord, Waterfall, or another Bungee-compatible proxy
• Backend server: Paper or Spigot

The public proxy is usually on a VPS. The backend server can be at home.

Step 1: Install On Bungee

Put this jar in your Bungee/Waterfall plugins folder:

DirtSimpleP2P-0.1.0-SNAPSHOT.jar

Start the proxy once, then stop it.

DirtSimpleP2P will create:

plugins/DirtSimpleP2P/config.properties

Open that file.

Step 2: Configure Bungee

On the Bungee/proxy server, use:

role=frontend
node.name=bungee-frontend

tunnel.listenHost=0.0.0.0
tunnel.listenPort=24445
tunnel.authToken=GENERATED_AUTOMATICALLY

tunnel.connectTimeoutMillis=5000
tunnel.heartbeatIntervalMillis=2000
tunnel.heartbeatTimeoutMillis=8000
tunnel.heartbeatMissesBeforeDisconnect=4
tunnel.reconnectInitialMillis=250
tunnel.reconnectMaxMillis=10000

tunnel.tls.enabled=false
tunnel.tls.allowInsecure=true
tunnel.tls.autoGenerate=true
tunnel.tls.keyStore=certs/frontend.p12
tunnel.tls.keyStorePassword=
tunnel.tls.requireClientAuth=false

routes=minecraft
route.minecraft.frontendBindHost=127.0.0.1
route.minecraft.frontendBindPort=25566

Change:

• tunnel.listenPort only if port 24445 is already used

The plugin automatically generates tunnel.authToken on first start.

Copy the generated Bungee token into the backend server config. The token must match on both sides.

To enable TLS on Bungee, change:

tunnel.tls.enabled=true
tunnel.tls.allowInsecure=false

When Bungee starts, DirtSimpleP2P will generate:

plugins/DirtSimpleP2P/certs/frontend.p12

It will also fill in tunnel.tls.keyStorePassword if that value is blank.

Step 3: Point Bungee At The Local Tunnel

In your Bungee server config, set the backend server address to:

127.0.0.1:25566

That is not your home server IP. DirtSimpleP2P listens there locally on the proxy server.

Step 4: Install On Paper Or Spigot

Put the same jar in your backend Minecraft server plugins folder:

DirtSimpleP2P-0.1.0-SNAPSHOT.jar

Start the backend server once, then stop it.

DirtSimpleP2P will create:

plugins/DirtSimpleP2P/config.properties

Open that file.

Step 5: Configure Paper Or Spigot

On the backend server, use:

role=backend
node.name=paper-backend

tunnel.connectHost=YOUR_BUNGEE_OR_VPS_IP
tunnel.connectPort=24445
tunnel.authToken=PASTE_THE_BUNGEE_TOKEN_HERE

tunnel.connectTimeoutMillis=5000
tunnel.heartbeatIntervalMillis=2000
tunnel.heartbeatTimeoutMillis=8000
tunnel.heartbeatMissesBeforeDisconnect=4
tunnel.reconnectInitialMillis=250
tunnel.reconnectMaxMillis=10000

tunnel.tls.enabled=false
tunnel.tls.allowInsecure=true
tunnel.tls.trustOnFirstUse=true
tunnel.tls.pinnedCertificateSha256=

routes=minecraft
route.minecraft.backendTargetHost=127.0.0.1
route.minecraft.backendTargetPort=25565

Change:

• tunnel.connectHost to your public proxy/VPS IP or domain name
• tunnel.authToken to the same secret used on Bungee
• route.minecraft.backendTargetPort if your backend Minecraft server is not on 25565

Do not put your home IP in the Bungee config. The backend connects out to the proxy.

To enable TLS on Paper/Spigot, change:

tunnel.tls.enabled=true
tunnel.tls.allowInsecure=false

Leave this enabled for the easiest setup:

tunnel.tls.trustOnFirstUse=true

On the first successful TLS connection, the backend saves the Bungee certificate fingerprint here:

tunnel.tls.pinnedCertificateSha256=

After that, the backend will only trust that same Bungee certificate.

Step 6: Start Everything

Start the public Bungee/Waterfall proxy first.

Then start the backend Paper/Spigot server.

If it works, the Bungee logs should show that a backend tunnel authenticated.

Players should connect to your normal public proxy address. Bungee sends them to 127.0.0.1:25566, and DirtSimpleP2P carries the connection to the backend server.

Commands

Run these commands in game or from the server console:

/dsp2p status

Shows whether the agent is running, whether the tunnel is connected, active streams, TLS state, and the last important event.

/dsp2p doctor

Checks the config and prints useful setup/security hints.

Permission:

dirtsimplep2p.command

On Paper/Spigot it defaults to server operators. On Bungee, give that permission to staff who should see tunnel diagnostics.

Firewall Notes

On the public proxy/VPS, allow:

24445/tcp

On the home router, you do not need to forward:

25565/tcp

Your backend server must be allowed to make outbound connections to the proxy/VPS.

Reconnect Behavior

DirtSimpleP2P is tuned to notice real drops quickly while still tolerating short latency spikes.

Default behavior:

• Heartbeat every 2 seconds
• Warns in status if heartbeats are delayed
• Disconnects after about 8 seconds of no tunnel traffic
• First reconnect retry after about 250ms
• Backoff grows up to 10 seconds if the proxy/VPS is still unreachable

Useful config values:

tunnel.heartbeatIntervalMillis=2000
tunnel.heartbeatTimeoutMillis=8000
tunnel.heartbeatMissesBeforeDisconnect=4
tunnel.reconnectInitialMillis=250
tunnel.reconnectMaxMillis=10000

If your users are very far from the VPS or your home internet has frequent latency spikes, increase tunnel.heartbeatMissesBeforeDisconnect to 5 or 6.

Common Problems

Plugin says the token is still the default

Restart once on each side so DirtSimpleP2P can generate a token.

Then copy the generated Bungee token into the backend config. The token must be the same on both sides.

Backend says connection refused

Check that:

• Bungee/proxy server is running
• DirtSimpleP2P started on Bungee
• tunnel.connectHost points to the proxy/VPS
• tunnel.connectPort matches the Bungee tunnel.listenPort
• The VPS firewall allows that TCP port

Bungee cannot connect to backend server

Make sure your Bungee backend server entry points to:

127.0.0.1:25566

Also make sure the backend Paper/Spigot server is running and connected to the tunnel.

Players disconnect or freeze

Check both server logs. Look for:

• reconnect messages
• heartbeat timeout messages
• stream reset messages
• backend target connection failed

Security Notes

The secret token is important. Do not share it.

Local-test configs use:

tunnel.tls.enabled=false
tunnel.tls.allowInsecure=true

For a better setup, enable TLS on both sides:

tunnel.tls.enabled=true
tunnel.tls.allowInsecure=false

The Bungee side generates a self-signed certificate. The Paper/Spigot side pins that certificate after the first successful connection.

Trust-on-first-use is convenient, but the very first TLS connection is still the sensitive moment. For a stricter setup, copy the fingerprint from the Bungee log and paste it into the backend config before the first connection.