iOS clients cannot connect through Tailscale VPN due to MTU issues - Workaround with initContainer

[mo124121]

Problem Description

When running Bedrock Minecraft Server in Kubernetes with Tailscale operator for VPN access, iOS clients (iPhone/iPad) fail to connect while Windows clients work normally. iOS clients get stuck at "Locating server" phase after initial authentication.

Environment

• Server: itzg/minecraft-bedrock-server (Bedrock Server 1.21.102.1)
• Kubernetes: On-premise 1.33.3
• CNI: Cilium 1.18.0
• VPN: Tailscale Operator 1.86.2
• Service: LoadBalancer with tailscale.com/expose: "true" annotation

Client versions:

• ✅ Windows 11 + Tailscale 1.86.2 + Minecraft 1.21.101 → Working
• ❌ iOS 16.7.11 + Tailscale 1.84.1 + Minecraft 1.21.101 → Stuck at "Locating server"
• ✅ iOS direct LAN connection → Working

Root Cause Analysis

Network Path

Server Pod → kube-proxy (server node) → kube-proxy (tailscale pod node) → Tailscale Pod → Client

Findings from tcpdump investigation

1. ICMP Fragmentation Needed messages: At the second kube-proxy hop, I observed ICMP Type 3 Code 4 (Fragmentation Needed and DF Set) responses, indicating packets with DF flag couldn't be fragmented.

2. Server behavior: The Bedrock server kept retransmitting the same packets repeatedly when receiving these ICMP messages.

3. Platform differences:

   • Windows clients: Only packets smaller than 1280 bytes were observed (no fragmentation needed)
   • iOS clients: Server attempted to send larger packets that required fragmentation

Deep Dive into RakNet Protocol and MTU Negotiation

Based on our investigation, I believe the following is happening:

1. RakNet MTU Discovery: The RakNet protocol (used by Bedrock) has a built-in MTU discovery mechanism during connection initialization. Clients communicate their MTU capabilities to the server.

2. Platform MTU handling differences:

   • Windows: VPN adapters explicitly expose MTU values that applications can query
   • iOS: No explicit MTU configuration available to applications (Tailscale app cannot provide MTU info to Minecraft client)

3. Server adaptation behavior:

   • When Windows clients connect, the server appears to receive MTU information and adjusts packet sizes accordingly (staying under 1280 bytes)
   • When iOS clients connect through Tailscale in K8s, the server doesn't receive proper MTU information and attempts to send larger packets

4. Control experiment:

   • I tested Bedrock server + Tailscale directly on WSL (not in Kubernetes) following Tailscale's documentation
   • iOS clients could connect successfully in this setup
   • tcpdump showed fragmented packets were being transmitted (DF flag not set)
   • This suggests the server adapts its behavior based on the network interface's MTU visibility

Hypothesis

The Bedrock server appears to have two modes of operation:

1. When it can directly see the network adapter's MTU → allows fragmentation (DF flag not set)
2. When running in containers/K8s where MTU is abstracted → uses DF flag and expects client MTU negotiation

iOS clients through Tailscale cannot properly communicate their effective MTU due to iOS platform limitations, causing the connection to fail during the "Locating server" phase.

Solution

Add an initContainer to explicitly set the MTU on the pod's default route:

initContainers:
  - name: setup-mtu
    image: busybox:latest
    command:
      - /bin/sh
      - -c
      - |
        ip route
        ip route change default via $(POD_IP) dev eth0 mtu 1280
        ip route
    env:
      - name: POD_IP
        valueFrom:
          fieldRef:
            fieldPath: status.podIP
    securityContext:
      capabilities:
        add:
          - NET_ADMIN

The MTU value of 1280 was chosen to match the Tailscale gateway pod's adapter MTU.

Impact

This workaround successfully allows iOS clients to connect through Tailscale VPN while maintaining compatibility with other clients.

Why Posting Here

Since this repository includes Kubernetes YAML examples, others using similar setups might encounter the same issue. This information could save someone hours of debugging when combining this image with VPN overlays like Tailscale.

Questions for the Community

If anyone has encountered similar issues or knows a more elegant solution than the initContainer workaround, I'd love to hear about it!

References

• RakNet Protocol Documentation
• Run a private Minecraft server with Tailscale

Acknowledgment

Finally, I want to thank you for maintaining this excellent Docker image! Thanks to your work, my family can enjoy playing Minecraft together with minimal maintenance effort. This project has been invaluable for our home server setup. Thank you!

[itzg]

Fantastic research and write-up. That sounds like a great solution.

If you would like to contribute an example in the repo's https://github.com/itzg/docker-minecraft-bedrock-server/tree/master/examples directory then that would be great too.

[mo124121]

@itzg
Thank you for your reply and the suggestion!

I created a PR #554, please take a look!