Run Xray core on an OpenWrt Bypass Router: Transparent Proxy Setup Guide

Map the traffic path between the bypass router and main router

A bypass router does not take over your whole network just because it is plugged in. LAN devices must send traffic to it, or the main router must have explicit policies to forward selected traffic there. This guide uses a single-interface bypass router on the same subnet: the main router handles the internet connection and DHCP, while OpenWrt receives traffic from selected devices and either sends it directly or routes it through an Xray outbound.

The upstream path is “device → OpenWrt → main router → upstream network.” Devices on the same subnet usually communicate directly over Layer 2; changing the default gateway does not automatically route that traffic through the bypass router. OpenWrt's default gateway should remain the main router. Do not also set the main router's default gateway to the bypass router, or you may create a forwarding loop.

Understand the difference between Xray core, clients, and transparent proxying

Xray is a core that handles inbounds, routing, and outbounds; it does not include an OpenWrt network management interface. v2rayN is a desktop client, v2rayNG is an Android client that uses the Xray core, and v2flyNG is an Android client that uses the v2fly core. Their subscription management interfaces are not OpenWrt service configuration, and a subscription URL is not an Xray JSON configuration file.

An explicit proxy only handles applications that connect to its proxy port. Transparent proxying intercepts traffic at the network layer. Starting Xray, opening an inbound port, or changing a device's gateway alone is not enough. Transparent proxying also requires Linux forwarding, firewall matching, policy routing, and correct return-path handling.

Check OpenWrt's basic configuration in order

The menu paths below refer to the commonly used LuCI interface; labels may vary by translation and theme. OpenWrt 22.03 and later use firewall4 and nftables by default, while older versions commonly use firewall3 and iptables. Identify your system first, then use the appropriate rule syntax. Do not combine commands from both systems in one startup script.

1. Identify the system

   Open Status → Overview and note the firmware version and target platform. In a terminal, run ubus call system board and uname -m. The core binary must match the device architecture and runtime environment; a desktop installer will not run on a router.

2. Set the network address

   Go to Network → Interfaces → LAN → Edit → General Settings. Set the protocol to Static address, then configure the example address 192.168.10.2, netmask 255.255.255.0, and IPv4 gateway 192.168.10.1. Replace these with values for your subnet before saving and applying.

3. Disable duplicate DHCP service

   Go to Network → Interfaces → LAN → Edit → DHCP Server → General Setup and select Ignore interface, leaving the main router responsible for assigning addresses. This step applies to the same-subnet topology in this guide, not to setups where OpenWrt manages a separate downstream subnet.

4. Verify the router itself can connect

   Check the time and time zone under System → System, then verify the default route, DNS resolution, and upstream connectivity. A badly incorrect system clock can break TLS connections. If the router itself cannot connect reliably, do not start by changing transparent proxy rules.

5. Test the Xray core

   Install or deploy Xray from a trusted source compatible with your firmware, then run xray version to confirm the installed version. Check the configuration with xray run -test -config /etc/xray/config.json. The file path here is an example convention; check the startup script to confirm which path the service actually reads.

A successful test only means the configuration can be parsed; it does not confirm that the remote server is reachable. Check the server address, port, protocol, transport, and TLS settings. For VMess or VLESS, match each setting to the provider's configuration. Do not guess security, flow, or transport settings based on the protocol name alone.

ubus call system board
uname -m
ip -4 route show
sysctl net.ipv4.ip_forward
xray version
xray run -test -config /etc/xray/config.json

These commands inspect and test the setup; they do not configure the firewall for you. Enable net.ipv4.ip_forward as required for forwarding, and confirm that the firewall allows the necessary LAN forwarding. Do not disable the entire firewall as a troubleshooting shortcut, and never expose a proxy inbound to the upstream interface.

Plan the transparent inbound, traffic marking, and loop prevention

Common transparent proxy methods include REDIRECT and TPROXY. REDIRECT is often used to redirect TCP traffic and cannot be extended to UDP simply by copying the TCP configuration. TPROXY can handle TCP and UDP, but requires compatible kernel modules, firewall rules, and policy routing. This guide uses TPROXY to explain how the layers fit together; it does not provide a one-click ruleset for unspecified firmware.

These are planning values, not performance test results. Port 12345 must match the TPROXY target port in the firewall rules. Routing table 100 is only an optional ID; check that another service is not already using it. Plan the mark value consistently too, so it does not conflict with existing multi-WAN or policy routing rules.

{
  "inbounds": [
    {
      "tag": "lan-tproxy",
      "listen": "0.0.0.0",
      "port": 12345,
      "protocol": "dokodemo-door",
      "settings": {
        "network": "tcp,udp",
        "followRedirect": true
      },
      "streamSettings": {
        "sockopt": {
          "tproxy": "tproxy"
        }
      }
    }
  ]
}

• Interception layer: Identify the test device on LAN ingress and send selected TCP and UDP traffic to the transparent inbound. Do not indiscriminately intercept traffic on every interface.
• Routing layer: Use policy routing to send marked packets to the local receive path. Check ip rule show and ip route show table 100 to confirm the rules are actually in place.
• Exclusion layer: Exclude destinations that should not be proxied, such as LAN, loopback, and multicast addresses, as well as other reserved ranges relevant to your setup.
• Loop prevention: Make sure connections from Xray to remote servers are not intercepted again. Design bypass rules based on source, destination endpoint, or a dedicated mark, and account for address changes when resolving domain-based endpoints.
• Return-path layer: With a single interface on the same subnet, direct replies may bypass the router. Evaluate selective SNAT, ICMP redirects, and connection tracking for your topology. SNAT hides the original device's address, so do not apply it broadly without a reason.

Keep firewall traffic selection separate from Xray routing

The OpenWrt firewall decides which packets enter Xray; routing.rules decides which outbound handles traffic once it is inside the core. If the firewall bypasses a connection, Xray never sees it, so even a precise domain rule cannot take effect. Use the firewall for essential address exclusions and access scope, and manage domain and traffic-category rules centrally in the core's routing configuration.

Xray evaluates routing rules in order; the first match determines the outbound. Put explicit LAN destinations and special cases before broad rules to prevent an overly broad rule from catching traffic intended for later conditions. outboundTag must exactly match the tag of an existing outbound. Do not copy routing rules without adding their corresponding outbounds.

• domainStrategy: AsIs does not actively resolve domains just to match routing rules against IP addresses.
• If a domain rule does not match, IPIfNonMatch may resolve the domain and retry matching against IP rules. It is not a switch that sends all DNS traffic through a proxy.
• Transparent connections usually reach the core with a destination IP. Whether domain rules can match depends on the DNS design or whether sniffing can provide domain information; sniffing cannot recover domains for every protocol.
• If you use geosite or geoip, confirm that the data files exist, the paths are correct, and the categories match your expectations. Missing files should not be mistaken for a server problem.

Plan DNS and IPv6 separately

Changing the IPv4 gateway does not automatically route DNS and IPv6 through the bypass router. Devices may still send DNS requests to the main router, or use an IPv6 default route advertised by the main router to reach the upstream network directly. To test DNS through the bypass router, set the test device's DNS server to 192.168.10.2, but only if a working DNS service is actually listening there.

1. Choose a single DNS entry point.A common setup is to have OpenWrt's dnsmasq handle LAN requests on port 53 and forward them according to an explicit policy. Check for port conflicts first so another DNS process is not bound to the same address and port.
2. Prevent DNS loops.If dnsmasq forwards requests to another DNS service on the same router, that service's upstream must not point back to dnsmasq. If the proxy server itself uses a domain name, provide an initial resolution path that does not depend on a proxy connection that has not been established yet.
3. Distinguish core DNS from LAN DNS.Xray's dns settings are used for DNS resolution within the core; they do not automatically make LAN devices use Xray for DNS. Device requests must pass through an actual DNS listener and forwarding path.
4. Check encrypted DNS.Browsers and apps may use their own encrypted DNS, independently of the system DNS settings. When testing, identify the resolution path being used. A single nslookup result does not tell you how every app resolves domains.
5. Check IPv6.Check the default routes for IPv4 and IPv6 separately on the test device. To handle IPv6, plan router advertisements, the IPv6 firewall, and transparent forwarding separately. If you are not handling IPv6 yet, explicitly limit the scope of testing on the test device.

Test with one device before expanding access

Set the test device's IP address to 192.168.10.100 and its gateway to 192.168.10.2. First confirm that you can reach the main router's admin page, LAN devices, and regular direct destinations, then test destinations that require a proxy. After confirming TCP web access, test UDP apps and DNS separately. Opening a web page does not prove the entire transparent proxy path is working.

After testing with one device, consider configuring the main router to distribute the bypass router as the IPv4 gateway with DHCP option 3, and a verified DNS server with option 6. The exact settings depend on the main router's firmware. Keep a record of the original gateway so you can restore it, and remember that devices may retain old leases. Do not change the whole network at once without a way to roll back.

• Check persistence:After a reboot, confirm that the Xray service, policy routes, and firewall rules are still in place. Avoid relying on changes that only took effect temporarily in the command line.
• Check configuration ownership:If a management component generates the configuration, do not also maintain the same file and rule chain manually. Updates could overwrite your changes or conflict with them.
• Check logging overhead:Temporarily increase logging while troubleshooting, then restore an appropriate level. Frequent long-term writes add storage and device overhead. Remove destination details, credentials, and device identifiers before sharing logs.
• Check actual load:Monitor CPU, memory, connection count, and temperature. Throughput depends on hardware, protocol, and network conditions; you cannot infer a fixed speed from the inbound port or device name.

Continue with the advanced handbook to review routing rule order and DNS settings. If concepts are getting mixed up, use the glossary to distinguish inbounds, outbounds, and system proxies. The key to a reliable bypass-router setup is to verify each layer in sequence: basic connectivity first, core outbounds next, and transparent forwarding last.