Appearance

NetherNet Setup ​

NetherNet is the new way Bedrock Edition connects to servers. This guide covers everything that is specific to NetherNet: the Geyser options, your domain, TLS certificates, and real player IPs. For the overall setup, start with the Bedrock / Geyser setup guide.

NetherNet works with your own domain: Game Shield recognizes your server by the domain name the player typed. You do not need a separate Bedrock address for it. Players simply join with the domain your Java players already use, on port 19132.

What you need ​

  • Geyser with NetherNet support, set to transport: both (recommended) or transport: nethernet.
  • A Bedrock backend in the panel, with Geyser's port as its port.
  • A domain added in the panel's Domains section, pointing at your protected CNAME.
  • These ports reachable from NeoProtect's IP addresses:
    • TCP on Geyser's port (for example 19132) for signaling
    • UDP on Geyser's webrtc-port (for example 19133) for the game traffic

1. Configure Geyser ​

For transport: both, use the config from the Bedrock / Geyser setup guide. To accept NetherNet only, set these options in Geyser's config.yml:

yaml
bedrock:
  address: 0.0.0.0
  port: 19132
  # use "0" to re-use the 19132 port for this; this only works if you don't have "transport: both" set.
  webrtc-port: 0
  transport: nethernet
  signaling:
    mode: builtin

advanced:
  bedrock:
    signaling-trusted-proxies:
      - https://api.neoprotect.net/v2/public/servers/txt

What these options do:

  • port is the TCP port for signaling. It must match the port of your backend in the panel.
  • webrtc-port is the UDP port for the game traffic. Any free port works. With transport: nethernet, 0 reuses port over UDP. With transport: both it must differ from port, since RakNet uses that one.
  • address must stay 0.0.0.0, or your server's own network address. With 127.0.0.1, no player can connect over NetherNet.
  • signaling.mode must be builtin, see the warning below.
  • signaling-trusted-proxies lets Geyser trust the player IPs that NeoProtect forwards. See Real player IPs.

After updating your config, restart Geyser to activate NetherNet.

DANGER

Keep signaling.mode set to builtin. The nxs and hybrid modes register your server with an external signaling service, which hands players your server's real address. Those players then bypass NeoProtect completely.

Geyser also switches to nxs on its own when signaling cannot use its port. This happens with clone-remote-port: true, or when your Java server uses the same port. Keep clone-remote-port disabled and give Geyser its own port.

WARNING

Leave these Geyser options empty behind NeoProtect:

  • signaling.builtin.https: NeoProtect handles TLS for you (see step 4) and talks to Geyser over plain HTTP. With a certificate configured here, Geyser refuses those requests and NetherNet stops working.
  • signaling.builtin.advertise-addresses: Geyser already reports the addresses NeoProtect needs. Do not enter NeoProtect's IP addresses here.

2. Add your Bedrock backend ​

If you have not done so yet, add a Minecraft Bedrock backend group and a backend with your Geyser server's public IPv4 address and port. See the Bedrock / Geyser setup guide.

NetherNet uses the Bedrock backend groups of your server. The Proxy Protocol switch of the group does not apply to NetherNet.

3. Add your domain ​

  1. In the panel, open the Domains section of your server and click Add Domain.
  2. Enter your domain, such as play.example.com. A wildcard such as *.example.com covers every subdomain one level deep, but cannot get a TLS certificate (see the next step).
  3. Point the domain at your protected CNAME with a CNAME record, as described in the DNS setup guide.

If your Java players already join through this domain, there is nothing more to do: the same domain works for Java players and for Bedrock players on NetherNet (using port 19132).

NOTE

Your Bedrock RakNet address (see the RakNet guide) also accepts NetherNet, on the provided port and on the default port (19132).

4. Request a TLS certificate ​

IMPORTANT

Minecraft on iOS and iPadOS only connects over NetherNet with TLS. Without a certificate for your domain, players on iPhones and iPads cannot join through it.

Bedrock Edition sends its first NetherNet requests (signaling) over HTTP, optionally encrypted with TLS (HTTPS). On iOS and iPadOS, Minecraft explicitly requires TLS, and we therefore recommend everyone to enable it for their Minecraft Bedrock domains.

NeoProtect requests and renews a free certificate from Let's Encrypt for you. Geyser needs no certificate of its own.

  1. Make sure your domain already points at your protected CNAME.
  2. In the Domains section, click Certificate next to your domain.
  3. Click Request certificate. Issuing usually takes less than a minute.

The certificate is renewed automatically. The panel shows a Certificates missing for Bedrock (NetherNet) warning while one of your domains has none.

Things to know:

  • Wildcard domains cannot get a certificate. Add the exact domain your players use, such as play.example.com, in addition to a wildcard.
  • Deleting a domain revokes its certificate, and the certificate cannot be re-used, even if you re-add the domain.
  • For a subdomain pointing at your Bedrock RakNet address, add it in the Domains section and request a certificate for it in the same way.

Real player IPs ​

The Proxy Protocol switch in the panel does not apply to NetherNet. Instead, NeoProtect forwards the player's IP in the X-Forwarded-For header of the signaling request. Geyser only trusts this header from the addresses in signaling-trusted-proxies:

yaml
advanced:
  bedrock:
    signaling-trusted-proxies:
      - https://api.neoprotect.net/v2/public/servers/txt

This setting does two things:

  • Geyser sees the real player IP while the connection is set up. This includes connection checks by Geyser extensions.
  • NeoProtect's addresses are exempt from Geyser's connection limit. Geyser's signaling accepts only 8 connections at a time per IP address. All your players reach Geyser through a few NeoProtect addresses, so without this exemption, players can fail to connect while many join at once.

Geyser loads the IP list once at startup. If NeoProtect's IP addresses change, restart Geyser.

The HAProxy whitelist and NetherNet ​

If you enabled use-haproxy-protocol for RakNet, do not leave haproxy-protocol-whitelisted-ips empty. An empty list means something different for each transport:

  • For RakNet, an empty list means proxy protocol is trusted from any address
  • For NetherNet, an empty list means proxy protocol is trusted from no address

Fill the list with one of these:

  • https://api.neoprotect.net/v2/public/servers/txt (recommended) only trusts NeoProtect's addresses.
  • 0.0.0.0/0 trusts every address, just like the empty list did for RakNet before. Only use it if a firewall makes sure that nobody but NeoProtect can reach Geyser.

How a NetherNet connection works ​

NOTE

You do not need this section for the setup. It explains what happens behind the scenes, which helps when something does not work.

A NetherNet connection is made in two phases. Signaling uses HTTP over TCP to agree on how to connect. The game traffic then flows over WebRTC on UDP. Game Shield sits in the middle of both:

  1. The game client asks play.example.com:19132 for the server status over HTTPS (or HTTP). Game Shield finds your server by the domain name, gets the status (MOTD and player count) from your Geyser and answers. If your backend does not answer or does not support NetherNet, the game falls back to RakNet.
  2. When the player joins, the game sends an SDP offer. It describes the connection and lists the addresses where the game can be reached, called ICE candidates. Game Shield replaces these addresses with its own and forwards the offer to Geyser's TCP port, together with the player's IP (via the X-Forwarded-For header).
  3. Geyser replies with an SDP answer that lists the addresses where it receives WebRTC traffic: its network addresses, each with its webrtc-port. Game Shield picks the address to send traffic to, then replaces all addresses with its own before passing the answer on to the player.
  4. Now, the client and Geyser exchange connectivity checks and set up an encrypted connection (DTLS). Game Shield forwards these packets in both directions. The encryption runs end to end between the game and Geyser, so Game Shield cannot read or change your game traffic.

How Game Shield picks the address ​

Geyser lists all of its own network addresses in the answer. Behind a NAT or in a container, these are often private addresses that cannot be reached from the internet.
Therefore, Game Shield ignores private/local IPv4 addresses and all IPv6 addresses. If no public IPv4 address candidate is sent by Geyser, Game Shield uses your backend IP from the panel, together with the port Geyser announced via a private/local address.

This is why forwarding works behind a router or in a container: forward your webrtc-port from your public IP to Geyser using the same port number, and enter that public IP as your backend in the panel.

Troubleshooting ​

Bedrock players only connect over RakNet, or not at all ​

NetherNet is not reaching your Geyser, so the game falls back to RakNet.

  • Check that Geyser logged Built-in signaling started on ... at startup, and that transport is both or nethernet.
  • Check that the backend port in the panel is Geyser's port, and that the backend is in a Minecraft Bedrock group.
  • Check that TCP on that port is open for NeoProtect's IP addresses.
  • Check that players join with a domain, which is added in the panel.

The server shows up in the list, but joining times out ​

Signaling works, but the game traffic does not get through.

  • Check that the UDP webrtc-port is open for NeoProtect's IP addresses.
  • Behind a NAT or in a container, check that the webrtc-port is forwarded with the same port number.
  • Check that Geyser's address is not 127.0.0.1.
  • Check that your host's own firewall/protection does not filter UDP traffic from us.

Players on iOS/iPadOS cannot join, everyone else can ​

The domain they use probably has no TLS certificate. Request one. Remember that wildcard domains cannot get a certificate, and that a subdomain pointing at your Bedrock frontend has to be added in the Domains section first.

The certificate request fails ​

The panel shows the reason next to the domain. Most often, the domain does not point at NeoProtect yet, or an extra A record points somewhere else. Fix your DNS records, wait until the change has spread, then request the certificate again.

Players fail to connect while many join at once ​

Add NeoProtect's IP list to signaling-trusted-proxies, as shown in Real player IPs.

NOTE

Stuck on any step? Contact support and we will help.