PHXTUNNEL Deployment Guide

This guide documents how to deploy PHXTUNNEL from opsahil89/PHXTUNNEL. The current version is a self-hosted WireGuard proxy and forwarding automation stack for standard Linux nodes, Proxmox VE hosts, and split proxy/backend deployments where the public proxy and private backend are separate machines.

What PHXTUNNEL Automates

PHXTUNNEL provisions a WireGuard endpoint, generates client configuration, and applies persistent NAT or DNAT policy through nftables. In Proxmox mode, it can configure bridge-level gateway behavior for VM subnets so selected services are exposed while private traffic remains routed through controlled interfaces.

The updated release also includes a simpler beginner guide in the upstream repository and support for split proxy/backend setups. This is useful when a public-IP VPS acts as the tunnel proxy while a private backend server or Proxmox node hosts the actual services.

Prerequisites

Use a Debian, Ubuntu, or Proxmox host with root or sudo access.

Install base dependencies:

sudo apt update
sudo apt install -y python3 wireguard-tools nftables qrencode iproute2

One-Line Installation

For a standard interactive installation:

curl -fsSL https://raw.githubusercontent.com/opsahil89/PHXTUNNEL/master/install.sh | sudo bash

If installing from a local checkout:

git clone https://github.com/opsahil89/PHXTUNNEL.git
cd PHXTUNNEL
sudo ./install.sh

After installation, runtime files are maintained under /opt/phoenix-tunnel and generated configuration is written into system paths such as:

• /etc/phoenix-tunnel/config.json
• /etc/phoenix-tunnel/phoenix.nft
• /etc/wireguard/wg0.conf

Wizard Flow

During setup, PHXTUNNEL asks for:

• Public endpoint IP or DNS name
• Internal WireGuard subnet (example 10.100.0.0/24)
• Port forwarding mappings (single ports or ranges)
• Environment mode (linux or proxmox)
• Optional DNS, IPv6, MTU, and kill-switch policy

Example mapping format:

51820 UDP -> 172.16.50.10:51820

Split Proxy and Backend Mode

The updated software adds a split deployment mode for cases where the public proxy server and the backend service node are separate. This is commonly used when the public VPS receives internet traffic and forwards selected traffic over WireGuard to a private backend or Proxmox environment.

On the public proxy server:

sudo ./setup.py setup-proxy

If you are using the one-line installer:

curl -fsSL https://raw.githubusercontent.com/opsahil89/PHXTUNNEL/master/install.sh | sudo bash -s -- setup-proxy

The proxy setup asks for the backend WireGuard public key. If the backend key is not available yet, press Enter and PHXTUNNEL will generate a backend configuration at:

/var/lib/phoenix-tunnel/backend/backend-wg0.conf

On the backend server or Proxmox node:

sudo ./setup.py setup-backend

For one-line backend installation:

curl -fsSL https://raw.githubusercontent.com/opsahil89/PHXTUNNEL/master/install.sh | sudo bash -s -- setup-backend

The backend setup asks for the proxy WireGuard public key, which is printed when setup-proxy completes.

Common Operational Commands

Run from the project runtime path:

sudo ./setup.py install
sudo ./setup.py setup-proxy
sudo ./setup.py setup-backend
sudo ./setup.py wizard
sudo ./setup.py apply
sudo ./setup.py status
sudo ./setup.py health
sudo ./setup.py export-client client-1 --qr
sudo ./setup.py rollback

These commands cover install, split proxy/backend setup, configuration wizard execution, policy apply, health checks, client export, and rollback.

Proxmox Deployment Notes

When proxmox mode is selected, PHXTUNNEL can detect bridge interfaces such as vmbr0, assign bridge gateway addressing, and persist forwarding behavior for VM subnets. This pattern is useful when VMs require private routed access with selective public port forwarding.

A typical layout is:

Internet -> Proxmox public IP -> wg0 -> vmbr0 gateway -> VM subnet

For simple Proxmox deployments, the upstream project now includes SIMPLE_GUIDE.md, which explains the same workflow without deep networking terminology.

Validation and Troubleshooting

Basic checks:

sudo /opt/phoenix-tunnel/setup.py status
sudo /opt/phoenix-tunnel/setup.py health
sudo wg show
sudo nft list ruleset

If traffic fails after tunnel establishment, verify:

• net.ipv4.ip_forward=1
• Correct outbound interface selection
• Cloud provider allows UDP on WireGuard listen port
• VM default gateway points to configured bridge gateway (for Proxmox)

If a generated configuration causes connectivity problems, use rollback and restart the tunnel/firewall services:

sudo /opt/phoenix-tunnel/setup.py rollback
sudo systemctl restart wg-quick@wg0 phoenix-tunnel-firewall.service

Updating Existing Installs

For Git-based installations, use the upstream update helper:

sudo PHX_ROOT=/opt/phoenix-tunnel /opt/phoenix-tunnel/scripts/update.sh

After updating, run status and health checks before changing production port mappings.

For related transport engineering guidance, see GRE Tunnel Setup Guide, Routing Consistency, and Regional Connectivity.