PCA_Phobos/docs/WARP_DEV_NOTES.md

WARP in dev — modes, checks, current limits

Date: 2026-06-06 Channel: dev Version: v1.3.1-dev

What was added

The dev panel now has a dedicated WARP / WARP+ block in /settings.

Supported modes:

• egress — route client outbound traffic through WARP on the server side;
• relay — expose a UDP relay for a separate WARP/WireGuard client profile;
• custom profile — save a full custom warp.conf from the web UI;
• WARP+ key — save a license key and rebuild the profile through wgcf.

The UI also has a ? help block with plain-language explanations:

• what each mode does;
• when to use free vs custom;
• what WARP+ key changes;
• what Enable and Disable do;
• how per-client WARP works from the client list.

How the modes work

egress

Use this when you want Phobos clients to keep connecting the usual way, but send their outgoing traffic through Cloudflare WARP after they land on the server.

Implementation:

• WireGuard clients still connect to the Phobos server;
• server-side policy routing sends only selected client tunnel IPs through warp;
• NAT is done with POSTROUTING MASQUERADE;
• client rows in /clients have WARP ON/OFF, which adds/removes ip rule from <client-ip>/32.

relay

Use this when you need a separate relay endpoint for another WARP/WireGuard client profile.

Important:

• this is not a drop-in replacement for the normal Phobos router config;
• the client must use a separate WARP/WireGuard profile aimed at the relay port;
• this mode is for relay-style scenarios, not for replacing the regular home.conf path one-to-one.

Implementation:

• UDP relay rules are added with tagged iptables entries;
• incoming UDP on the selected port is DNAT'ed to the target WARP endpoint;
• outgoing packets are MASQUERADE'd back through the relay host.

custom profile and WARP+

Two ways to use a non-default profile:

• paste a full custom warp.conf;
• save a WARP+ key and let wgcf rebuild the profile from it.

This keeps the UI simple:

• free WARP still works out of the box;
• WARP+ is possible when the owner has a real key;
• no hidden magic is required outside the panel.

Live checks completed

Server-side checks

Passed:

• python3 -m py_compile app.py server/api.py
• bash -n install.sh update.sh server/phobos-warp.sh
• live status checks on dev server 64.188.81.115

Verified on the dev server:

• egress mode enables cleanly;
• current egress IPv4 is reported in status JSON;
• custom profile and WARP+ key save from the web UI;
• relay rules appear with separate tagged iptables entries.

Real router check

Router used for testing:

• public SSH: 95.72.5.253
• web: https://homesmart.netcraze.pro/dashboard

Confirmed:

• real router traffic was sent through the dev server;
• with egress enabled, a live curl https://api.ipify.org from the router returned WARP egress IP 104.28.193.219;
• this proves the real data path for router -> Phobos -> WARP -> internet.

Relay check

Confirmed:

• relay mode enables from the server side;
• relay iptables rules are created;
• counters increase on live traffic;
• a separate WARP profile pointed at the relay port completes handshake.

Not fully closed yet:

• relay handshake and packet flow were confirmed;
• a full end-to-end "internet works through relay profile" check on the router was not fully finished in a clean state before router access became limited.

Router recovery note

During live tests, WAN SSH access to the router stopped responding, so full file restore over shell was blocked.

What was still restored safely:

• temporary KeenDNS helper proxies created for testing were removed;
• temporary extra WireGuard peer entries were cleaned up;
• the router is currently left on a working direct dev WireGuard peer so it stays reachable through the test tunnel rather than returning to a broken down state.

What still needs one final shell pass later:

• restore /opt/etc/Phobos/home.conf from backup;
• restore /opt/etc/Phobos/wg-obfuscator.conf from backup;
• restore /opt/etc/Phobos/failover.conf from backup;
• restore minute cron jobs for phobos-health.sh and phobos-pull.sh.

Known backup path on the router:

• /opt/etc/Phobos/test-backup-20260606-044834

Current honest status

Ready now:

• egress mode
• per-client WARP ON/OFF
• custom profile
• WARP+ key
• UI help text

Partially verified:

• relay mode

Extra audit fixes after live testing:

• orphan WireGuard peers now show up in both Sessions and Clients as orphan-* instead of disappearing into unknown;
• orphan rows can be Kicked, Purged, and also toggled through per-peer WARP;
• client package build no longer fails when /opt/Phobos/bin is missing or OBFUSCATOR_KEY is empty;
• update / restore scripts now restart the active panel service automatically (phobos-panel or phobos-dev-test).