Running Xray on a router means configuring the core, traffic interception, policy routing, and DNS. This guide is for users who already connect with a desktop client and want to move the proxy entry point to a gateway. Choose a main router or bypass gateway, test TCP, UDP, DNS resolution, and return paths with one device, then expand interception gradually. Addresses and ports below are examples, not a one-click configuration for every firmware.
Xray Core vs. Client: What Each One Does
Xray is the core program that handles inbound and outbound connections and routing rules. v2rayN is a desktop client that manages configurations and launches the core; moving a working node from v2rayN to a router does not move the entire desktop proxy setup. A Linux gateway also needs firewall rules, forwarding, DNS services, and service management.
VMess and VLESS are proxy protocols, not traffic interception methods. The node's protocol, transport, TLS, and REALITY settings must match the server. REDIRECT and TPROXY determine how LAN traffic reaches the local core. A successful outbound connection only confirms that one part of the setup works.
- Core configuration: Define the listening endpoint, node outbound, direct outbound, and domain or IP matching rules.
- System networking: Route selected devices' traffic to the inbound endpoint and ensure replies return to the originating device.
- DNS path: Determine which service resolves domains, which route queries take, and whether the results work with your routing rules.
- Service management: Handle startup, restarts, logs, permissions, and recovery. A shared node link does not provide these.
Main Router or Bypass Gateway: Choose by Failure Impact
The main router usually handles the WAN connection, DHCP, NAT, and default gateway. Its interception point is clear, but a bad rule can affect the whole network. A bypass gateway keeps testing separate from the main router and makes it easy to start with one device. The tradeoff is that you must plan the default gateway, DNS, and return path—plugging in an Ethernet cable alone will not route traffic through it.
Test with One Device via a Bypass Gateway
RecommendedKeep the main router's current settings and point one test device's IPv4 gateway and DNS to the bypass gateway. If something goes wrong, restore automatic settings on that device to limit the impact.
Best for: first-time deployments, testing transparent proxying, and keeping the existing network intact
Centralized Interception on the Main Router
Handle client traffic at its actual forwarding point for a simpler topology. Before making changes, back up DHCP, firewall, and DNS settings, and make sure you have local access for recovery.
Best for: users familiar with Linux networking and centrally managing multiple devices
Bottom line: start with one device, not a network-wide DHCP change
Set the test device's gateway and DNS manually. Verify recovery after a power cycle before changing the DHCP scope; don't combine initial troubleshooting with a network-wide migration.
Example: a bypass gateway on the same subnet as the main router. The main router is 192.168.10.1, the bypass gateway is 192.168.10.2, and the test device is 192.168.10.100. Set the bypass gateway's default route to the main router and the test device's default gateway to the bypass gateway. Check that these addresses are unused, and exclude static addresses from the DHCP pool.
Transparent Proxying: REDIRECT vs. TPROXY
Transparent proxying routes traffic through gateway rules even when devices have no HTTP or SOCKS proxy configured. A typical path is “device → gateway firewall → Xray inbound → routing → outbound.” If traffic never passes through the gateway, changing Xray routing rules won't help.
| Method | Typical use | Deployment notes |
|---|---|---|
| Explicit proxy | Apps configured to use a proxy | A successful node connection does not mean all device traffic is intercepted |
| REDIRECT | Commonly used for transparent TCP interception | Configure original-destination detection; this does not mean UDP is covered |
| TPROXY | TCP and UDP | Requires transparent sockets, packet marks, and policy routing |
TPROXY cannot be set up with a single firewall rule. The kernel and firewall backend must support it, marked packets must be routed locally through policy routing, and the Xray inbound must have the matching transparent-proxy settings. On nftables systems, don't mix in iptables scripts from unknown sources. Even if compatibility commands are available, inspect the rules they actually create.
- Exclude reserved destinations: Based on your network, exclude destinations that should not be proxied, such as loopback, LAN, broadcast, and multicast addresses. Preserve router management and DHCP traffic.
- Exclude node connections: Connections to the proxy server must not be intercepted by the same entry point, or they will loop.
- Separate forwarded and local traffic: Forwarded traffic and traffic generated by the gateway itself use different hooks. For the initial setup, intercept LAN-forwarded traffic only.
- Avoid mark conflicts: Policy routing marks may be shared with multi-WAN, traffic shaping, and other features. Check existing rules and masks before choosing marks.
Don't disable the entire firewall to troubleshoot. Allow access to transparent-proxy listening ports only from necessary sources; never expose them to the WAN. If logs show permission errors, check the capabilities required for transparent sockets and the service's runtime identity rather than running every service with elevated privileges indefinitely.
DNS Routing: Keep Resolution and Egress Aligned
A website failing to load doesn't necessarily mean the node is down. A device may still use DNS provided by the main router, or an app's encrypted DNS may bypass the intended entry point. Even when DNS queries reach the bypass gateway, a mismatch between the resolver's outbound route and the traffic route can return addresses unsuitable for the current egress.
12345 is an arbitrary example, not a port reserved for Xray. The firewall's forwarding destination must match the inbound listening port. Traditional DNS may use both UDP and TCP, so don't allow only UDP port 53. Encrypted DNS can't be identified by simply checking for traffic on port 53.
- Check what clients receive: Inspect the DNS address actually assigned to the device. It should point to the intended resolver, not just reflect an upstream address changed in the router UI.
- Test each case separately: Try internal domains, direct-access domains, and domains accessed through the proxy. Record the returned addresses and the actual egress path.
- Check bootstrap resolution: If the node address is a domain, make sure it can be resolved before the proxy connection is established. Avoid a dependency loop where DNS needs the proxy and the proxy is waiting for DNS.
- Clear caches: After changing rules, clear relevant caches on the device and gateway, then restart the test app so stale resolutions and connections don't skew results.
Domain-based routing also depends on how destination information is obtained. Transparent inbounds commonly see the original destination as an IP address. Sniffing can recover domains from recognizable protocols, but not from every connection. If you need domain-based rules, review the DNS design, sniffing settings, and rule order together; enabling sniffing alone is not a complete solution.
Deploy in Stages: From Outbound Tests to One-Device Interception
The steps below apply to a typical Linux gateway. Configuration paths and service names depend on how Xray was installed; /etc/xray/config.json and xray.service are examples. Confirm the actual paths on your system first. Minimal firmware may use a different service manager.
-
Document the network
Record the main router's address, DHCP range, DNS, interface names, and firewall rules. Make sure you can recover through a wired connection or local console; don't rely only on the remote connection you're changing.
-
Test outbound
Check the processor architecture and Xray version, then test the node configuration. Verify outbound access with an explicit proxy listening only on loopback. Don't add network-wide interception rules yet.
-
Check the inbound
Choose a transparent inbound port and check whether it is already in use. For TPROXY, also verify the inbound's transparent setting, system support, policy routing, and packet marks; confirming that the process is running isn't enough.
-
Intercept one device
Match traffic from the test device
192.168.10.100only. Test TCP first, then verify with an outbound that actually supports UDP forwarding. A working website is not a substitute for a UDP test. -
Test DNS end to end
Point the test device's DNS to the configured resolver and test direct, proxied, and LAN access, as well as IPv6. Check the core and firewall logs at the same time.
-
Verify recovery
Reboot the gateway and confirm services start in the right order and rules persist. Simulate a core failure and check the planned failure behavior before deciding whether to expand interception through DHCP.
Run read-only checks before changing forwarding rules
# Check the program version and configuration; a passing config test does not prove remote connectivity
xray version
xray run -test -config /etc/xray/config.json
# Inspect IPv4 and IPv6 routes, plus IPv4 policy routing
ip -4 route show
ip -6 route show
ip -4 rule show
# Inspect listening ports and the current nftables rules
ss -lntup
nft list ruleset
# Only for systemd installations where the service is named xray
systemctl status xray --no-pager
journalctl -u xray -n 80 --no-pagerReading some rules and process information may require administrator privileges. Check whether rule counters increase as test traffic passes through. If they don't, check the interface, source address, and chain hook first. If they increase but the core logs show nothing, check the port, policy routing, and inbound configuration. Avoid changing multiple layers at once, or it will be hard to tell what fixed the issue.
Routing and Performance: Find Bottlenecks with Evidence
Routing rules are usually evaluated in order, with behavior also affected by protocol, domain policies, and IP resolution. Put clear LAN rules and necessary exceptions first, followed by service-specific routing and a fallback outbound. If you route by source address, domain, and destination IP, document what each rule is for instead of moving rules around and hoping for the best.
| Symptom | Check first | Next step |
|---|---|---|
| Explicit proxy works, transparent proxy fails | Interception rules, policy routing, original destination | Watch rule counters and inbound logs for one device |
| Web browsing works, real-time apps fail | UDP interception, outbound support, MTU | Test UDP separately and check for retransmissions or fragmentation |
| Some domains take a long time to load | DNS entry point, upstream route, IPv6 | Query A and AAAA records separately, then test each route |
| Speed drops as load increases | CPU, memory, connection tracking table | Compare direct and proxied results for the same destination at the same time |
Don't mistake a router's advertised Wi-Fi speed for proxy throughput. Encryption, connection count, single-core performance, and cooling all affect results. Test with a wired device when possible, using the same node and test destination, and record CPU usage. A single peak speed-test result can't distinguish wireless interference from gateway processing limits.
- IPv6: Intercepting IPv4 alone does not mean every app uses the proxy. Check router advertisements, the IPv6 default route, firewall, and DNS AAAA responses. Decide whether IPv6 should be intercepted separately or remain direct.
- Traffic offloading: Hardware or software offloading may bypass the rules you expect to apply. Temporarily disable it in a controlled test, compare results, and re-enable it only after confirming compatibility.
- Reverse-path checks: Complex policy routing may conflict with strict reverse-path filtering. Check interface settings and evidence of dropped packets before making targeted changes; don't blindly copy commands that disable checks globally.
- Failure behavior: Decide whether traffic should stop proxying or fall back to a direct connection if the core exits. A direct fallback changes the egress path and should never happen implicitly by default.
FAQ: Troubleshooting a Bypass Gateway
Can't reach the router's admin page after switching to a bypass gateway?
Restore the test device's original main-router gateway and confirm that the management page is reachable. Then check for address conflicts, subnet masks, forwarding settings, and LAN address exclusions on the bypass gateway. Management traffic should not be sent through the proxy outbound. Keep a local access method available while troubleshooting.
The node works in v2rayN but fails on the router. Why?
Compare the Xray versions and complete outbound settings on both systems. Check the server port, transport path, SNI, and REALITY settings, then verify the router's clock and node-domain resolution. Test outbound through an explicit proxy first; only configure transparent interception after that works.
Can changing DNS alone, without changing the default gateway, proxy all traffic?
No. DNS controls name resolution; it does not change the next hop for ordinary IP packets. Without another explicit traffic-steering mechanism, the device continues to use its default route. Check the device's routing table, then decide how to route the traffic you want through the bypass gateway.
It stops working after a reboot but works when started manually. What should I check?
Check the startup order for network readiness, time synchronization, DNS, and the core service. Make sure firewall reloads don't remove custom chains or policy routes. Save service logs and rule snapshots separately so repeated manual restarts don't hide dependency problems.
After deployment, keep a record of settings you can use to roll back: device gateway and DNS, bypass gateway address, transparent port, rule locations, service name, and failure behavior. After updating the core or changing a subscription, retest in this order: outbound → interception → DNS → dual-stack → reboot. For more on the core and DNS setup, see the core guide and DNS configuration guide.