🌐 English | 中文 | 한국어

Router Systems

HY2 SCALE supports running on router systems with Docker, including devices with custom or stripped-down Linux kernels. These environments often have non-standard netfilter modules or restricted iptables, which HY2 SCALE handles automatically via compatibility mode.

Deployment on Router Systems

Recommended: Non-Host Network

docker run -d --name hy2scale \
  --network hy2net --ip 192.168.10.4 \
  --cap-add NET_ADMIN --cap-add NET_RAW \
  --device /dev/net/tun \
  -v /path/to/data:/data \
  hy2scale:latest

Note: No --privileged required. NET_ADMIN + NET_RAW capabilities are sufficient.

Key Differences from Standard Linux

Aspect	Standard Linux	Router Systems
Network mode	--network host	Bridge network with static IP
iptables	Works normally	May be broken (custom kernel modules)
L2TP mode	iptables DNAT	TUN capture + gvisor netstack
IKEv2 mode	iptables DNAT	xfrm bridge + AF_PACKET
Routing rules	iptables DNAT	Not available
Capabilities	NET_ADMIN	NET_ADMIN + NET_RAW
TUN device	Auto-created	--device /dev/net/tun required

How Compat Mode Works

Auto-Detection

HY2 SCALE automatically detects restricted environments using testIptablesAvailable():

testIptablesAvailable()
├── true  → Standard path (iptables DNAT + transparent proxy)
└── false → Compatibility path (TUN/xfrm + gvisor netstack)

This function tests if iptables-legacy -t nat -L -n succeeds. On router systems with custom kernels, it may fail because:

• The kernel includes proprietary netfilter targets not recognized by standard iptables
• Standard iptables binaries cannot parse these custom targets

No configuration needed — compat mode is activated automatically. On standard Linux, the compat code never executes.

L2TP Compatibility Mode

Standard L2TP uses iptables to DNAT PPP traffic to a transparent proxy. In compat mode, this is replaced with:

PPP Client
  ↓ (L2TP/IPsec tunnel)
xl2tpd + pppd (assigns IP from pool)
  ↓
Policy routing: ip rule from 192.168.25.0/24 lookup TABLE_Y
  ↓
Kernel TUN interface (hy2cap0)
  ↓
gvisor netstack (TCP/UDP forwarders)
  ↓
Exit routing through mesh

1. Policy routing directs PPP subnet traffic to a routing table
2. The routing table sends traffic through a kernel TUN device (hy2cap0)
3. gvisor netstack reads packets from the TUN and provides TCP/UDP handling
4. TCP/UDP forwarders map connections to users and apply exit routing

IKEv2 Compatibility Mode

Standard IKEv2 uses iptables to DNAT xfrm interface traffic. In compat mode, this is replaced with:

IKEv2 Client
  ↓ (IKE + ESP tunnel, UDP 500+4500)
strongSwan (creates xfrm interfaces: ikec0, ikec1, ...)
  ↓
AF_PACKET raw socket captures decapsulated packets
  ↓ (filters PACKET_OUTGOING to avoid loops)
gvisor netstack (TCP/UDP forwarders)
  ↓
Exit routing through mesh
  ↓
Response: raw IP socket → xfrm interface → kernel ESP encapsulation

1. strongSwan creates xfrm interfaces for each tunnel (if_id_in/out = %unique)
2. AF_PACKET (SOCK_RAW) captures decapsulated packets from xfrm interfaces
3. PACKET_OUTGOING packets are filtered to prevent capture loops
4. gvisor netstack handles TCP/UDP and applies exit routing
5. Responses are injected back through the xfrm interface for ESP encapsulation

This approach bypasses the FORWARD chain entirely, which is blocked in non-host container network namespaces.

MTU Settings

Router system deployments use lower MTU values to accommodate ESP overhead:

Protocol	Standard MTU	Router System MTU
L2TP	1280	1280
IKEv2	1400	1300

IKEv2 MSCHAPv2 on Router Systems

IKEv2 MSCHAPv2 mode is compatible with router built-in IKEv2 clients:

1. Upload a CA certificate on the TLS page
2. Enable IKEv2 in MSCHAPv2 mode
3. HY2 SCALE auto-signs a server certificate using the CA
4. Configure the router's IKEv2 client with the CA cert and user credentials

Troubleshooting

VPN services show as "Limited"

This means iptables is not available. On router systems this is expected — compat mode handles VPN traffic differently. The "Limited" badge indicates that standard-mode VPN features are unavailable, but compat-mode equivalents are active.

L2TP/IKEv2 not working

1. Check capabilities: ensure both NET_ADMIN and NET_RAW are set
2. Check TUN device: ensure --device /dev/net/tun is passed
3. Enable debug mode (DEBUG=true) and check logs for:
   • iptables available: false — confirms compat mode activation
   • TUN device creation messages
   • xfrm interface creation messages

Cannot connect from LAN clients

If using bridge network mode, ensure:

1. The container has a static IP on the Docker network
2. The router has a route to the Docker network
3. Port forwarding is configured for VPN ports (500, 4500, 1701)

Debug Logging

docker run -d --name hy2scale \
  -e DEBUG=true \
  --network hy2net --ip 192.168.10.4 \
  --cap-add NET_ADMIN --cap-add NET_RAW \
  --device /dev/net/tun \
  -v /path/to/data:/data \
  hy2scale:latest

Debug mode logs:

• iptables detection results
• Capability and host network checks
• TUN device read/write operations
• AF_PACKET packet captures
• gvisor netstack forwarder connections
• Policy routing table setup

Recovery After Router Reboot

After a router reboot, Docker containers restart but may lose network configuration. Ensure:

1. Docker network is recreated with the correct subnet
2. The container uses --restart unless-stopped
3. Static IP is within the Docker network range

If the container fails to start after reboot, remove and recreate it with the same volume mount to preserve configuration.