Phantun Documentation

Phantun is designed for high performance by focusing on the most common use cases and minimizing MTU overhead. Unlike udp2raw, Phantun does not support UDP over ICMP, UDP over UDP, anti-replay, or encryption. This trade-off results in better throughput and lower MTU overhead (12 bytes for Phantun vs 44 bytes for udp2raw).

Key differences:

• Multi-threading: Phantun supports multi-threading; udp2raw does not.
• Layer 3 mode: Phantun uses a TUN interface; udp2raw uses Raw sockets + BPF.
• Connection Model: Phantun uses separate TCP connections for each UDP connection (Client/Server model); udp2raw is Server only.
• MTU Overhead: Phantun has 12 bytes of overhead; udp2raw has 44 bytes.

Run the phantun_server binary to start listening for obfuscated TCP connections and forwarding them to a local UDP server.

Arguments:

• --local <ADDR:PORT>: The TCP port the server listens on (must match your DNAT rule).
• --remote <ADDR:PORT>: The destination UDP server address and port to which traffic is forwarded.

Example (IPv4): RUST_LOG=info /usr/local/bin/phantun_server --local 4567 --remote 127.0.0.1:1234

RUST_LOG=info /usr/local/bin/phantun_server --local 4567 --remote 127.0.0.1:1234

# Using a hostname
RUST_LOG=info /usr/local/bin/phantun_server --local 4567 --remote example.com:1234

The Phantun Client requires Source NAT (SNAT) on its physical interface to translate the private IP address assigned to the Phantun TUN interface into an address usable on the physical network. You can achieve this using masquerade.

Note: Replace eth0 with your actual physical interface name. The default Phantun Client IP is 192.168.200.2 (IPv4) and fcc8::2 (IPv6).

### Using nftables
```nftables
table inet nat {
    chain postrouting {
        type nat hook postrouting priority srcnat; policy accept;
        iifname tun0 oif eth0 masquerade
    }
}

Using iptables

iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE
ip6tables -t nat -A POSTROUTING -o eth0 -j MASQUERADE

Run the phantun_client binary to listen for local UDP packets and wrap them in TCP connections to the Phantun Server.

Arguments:

• --local <ADDR:PORT>: The local UDP address and port Phantun listens on.
• --remote <ADDR:PORT>: The Phantun Server's TCP address and port to connect to.

Example (IPv4): RUST_LOG=info /usr/local/bin/phantun_client --local 127.0.0.1:1234 --remote 10.0.0.1:4567

RUST_LOG=info /usr/local/bin/phantun_client --local 127.0.0.1:1234 --remote 10.0.0.1:4567

# Using a hostname
RUST_LOG=info /usr/local/bin/phantun_client --local 127.0.0.1:1234 --remote example.com:4567

# Using IPv6
RUST_LOG=info /usr/local/bin/phantun_client --local 127.0.0.1:1234 --remote [fdxx::1234]:4567

To build the phantun Docker image locally, run the following command from the repository root. This uses the Dockerfile located in the docker/ directory.

docker build -t phantun -f docker/Dockerfile .

The Phantun Server requires Destination NAT (DNAT) to redirect traffic from the physical interface's TCP listening port to the Phantun TUN interface address.

Note: Replace eth0 with your actual physical interface name and 4567 with the TCP port used by the Phantun server. The default Phantun Server IP is 192.168.201.2 (IPv4) and fcc9::2 (IPv6).

### Using nftables
```nftables
table inet nat {
    chain prerouting {
        type nat hook prerouting priority dstnat; policy accept;
        iif eth0 tcp dport 4567 dnat ip to 192.168.201.2
        iif eth0 tcp dport 4567 dnat ip6 to fcc9::2
    }
}

Using iptables

iptables -t nat -A PREROUTING -p tcp -i eth0 --dport 4567 -j DNAT --to-destination 192.168.201.2
ip6tables -t nat -A PREROUTING -p tcp -i eth0 --dport 4567 -j DNAT --to-destination fcc9::2

Phantun creates TUN interfaces for both the Client and Server. For the connection to work, the host kernel must have IPv4 (and optionally IPv6) forwarding enabled to route traffic between the physical NIC and the Phantun TUN interface.

To enable IPv4 forwarding, edit /etc/sysctl.conf and add: net.ipv4.ip_forward=1

Then apply the changes: sudo sysctl -p /etc/sysctl.conf

Because Phantun adds TCP/IP headers and sets the DF (Don't Fragment) bit, you must adjust the MTU of your encapsulated tunnel (like WireGuard) to prevent packet loss. Phantun does not perform IP fragmentation or reassembly.

MTU Formulas:

• IPv4: WireGuard MTU = Link MTU - 20 (IP) - 20 (TCP) - 32 (WireGuard overhead) = Link MTU - 72
• IPv6: WireGuard MTU = Link MTU - 40 (IP) - 20 (TCP) - 32 (WireGuard overhead) = Link MTU - 92

Example (1500 byte Link MTU):

• IPv4: 1500 - 72 = 1428 bytes
• IPv6: 1500 - 92 = 1408 bytes

To improve security, you can run Phantun binaries as a non-root user by granting the cap_net_admin capability. This allows the process to manage TUN interfaces without full root privileges.

sudo setcap cap_net_admin=+pe phantun_server
sudo setcap cap_net_admin=+pe phantun_client