Reference Guide / Chapter 07

Advanced V2Ray Configuration Guide

Subscriptions, routing, and DNS resolution—from configuration requirements to verification.

For your first setup, follow the quick start guide: import a subscription, select a node, connect, and verify. Use this page to troubleshoot specific questions after confirming a basic connection. If you haven't installed a client yet, v2rayN is the recommended desktop option. Choose a package for your OS and architecture on the client downloads page. Examples involving core fields use Xray. If the client UI and core configuration use different terms, rely on the active configuration and logs.

01 / Subscription catalog

Subscription groups and server filters

Know the difference between subscription sources, nodes, and list filters

A subscription is a configuration source; a node is a connection entry imported from that source. Groups make sources easier to identify, while filters narrow down what you see. Neither controls routing: putting a node in a work group won't automatically send work apps through it. The client node list isn't a traffic log, either. An entry in the list only confirms that it was imported—not that the remote server is reachable, authentication succeeded, or a request worked.

In v2rayN's subscription group manager, create a separate group for each source, then enter its subscription URL and a local note. Use the note to describe the source and its purpose, such as “Test route · Group A,” rather than copying the remote list title. If the source later renames its nodes, you can still find them by source. Keep manually added nodes that need to persist in a separate group from subscriptions that may overwrite them on refresh. Before refreshing, check how the client handles manually added entries in that group.

After the first update, switch to the relevant group and check for the expected protocol, region, or purpose labels. Then test a familiar node. If you're already connected, don't treat “update this group” and “switch active node” as the same action: clients may keep the previous selection or choose another node if the current entry is gone. After updating, confirm which node is actually active. Don't rely only on a highlighted row or a latency result from an earlier test.

Build filters with narrow, verifiable criteria

Start with keywords you can check against the original list, such as a route label agreed on with the source. Once naming conventions are consistent, check whether your client version supports regular expressions or filtering during subscription import. A search usually changes only what's displayed; an import filter can prevent entries from being added at all. Before enabling import filtering, check the UI to see whether matches are kept or excluded. The same expression can produce opposite results depending on that setting.

If the UI confirms that regular expressions are supported and node names use consistent prefixes and separators, use ^(HK|SG)- to find notes starting with either prefix. This example matches strings only; it doesn't identify actual server locations and won't match entries starting with a bracket or space. Test a few examples that should match and a few that shouldn't. If the source changes its prefixes to full-width characters, investigate the naming change before broadening the filter to match anything.

If you only want to hide notice entries, search the view and compare results against actual nodes. Don't bulk-delete entries just because their names contain “expiry” or “traffic.” Some sources use those terms in real plan labels, while others include informational entries that look like unavailable nodes. Check the source's naming conventions and the entry fields rather than relying on a keyword. After filtering, make sure you haven't hidden the node you're currently using.

Diagnose empty groups and duplicate notes

If a group is empty after an update, first clear the list search or filter to check whether entries are hidden or the subscription failed to import. Then check the update result, whether the client can parse the response, and whether the source changed its subscription format. If only a few entries are missing, compare their names and types with visible entries in the same group. If the whole group is empty, check shared conditions and connection status first; don't edit node settings one by one.

Duplicate notes don't necessarily mean duplicate nodes. Different sources may use the same region label but have different addresses, ports, transports, or authentication details. Conversely, a single connection may be renamed between refreshes. Compare the source group and connection fields, and record only the differences you need locally. Don't paste subscription URLs or complete node configurations into public records. The subscription groups and server filters example explains how to name and maintain lists from multiple sources.

Test view search, subscription import filters, and bulk deletion separately. Search can be cleared at any time; the other two can change which entries are available, so make sure you can restore them before adjusting.

02 / Traffic routing

V2Ray routing rules in practice

Work out the result from domains, addresses, and rule order

Routing decides which outbound handles a connection entering the core. If an app doesn't send traffic through the client, routing rules never get a chance to apply. If an app supplies only the destination address, the core may not know the original domain. Before writing rules, identify the inbound the traffic uses and which details are available at that point: domain, address, port, or something else. System proxy, explicit proxy, and TUN inbounds may see different inputs.

Xray evaluates routing rules in order; the first match determines the outbound. Put exceptions before general rules, or later, more specific conditions won't be reached. When a rule object specifies both a domain and a port, both conditions must match. To match a domain or a separate address range, use two rules instead of combining both conditions in one object. If hit logs aren't available, temporarily narrow a test rule to a single target to isolate it from other rules.

Use full: to match an exact hostname. For example, full:example.com doesn't include subdomains, while domain:example.com matches the domain and its subdomains. Specify address ranges in CIDR notation, and distinguish between address families: listing IPv4 private ranges won't automatically cover IPv6. geosite and geoip refer to collections that depend on data files; available tags and their coverage depend on the data actually loaded. Start with explicit conditions that are easy to verify, then switch to collections when managing many targets.

Test exact exceptions before adding a default route

This routing snippet can be added to an Xray root configuration, provided outbounds already defines direct and proxy. The first rule sends a sample domain directly; the second catches TCP and UDP traffic. Before replacing any configuration, check whether your existing routing includes inbound-specific rules or DNS rules that need to stay. Don't import this example as a complete client configuration.

{
  "routing": {
    "domainStrategy": "AsIs",
    "rules": [
      {
        "type": "field",
        "domain": ["full:example.com"],
        "outboundTag": "direct"
      },
      {
        "type": "field",
        "network": "tcp,udp",
        "outboundTag": "proxy"
      }
    ]
  }
}

For verification, use an app that can send a domain as the target and route its request through the client inbound. Compare the inbound and outbound tags in the core access log. Test one connection that should match the exact rule, then another reachable domain that isn't covered to check the fallback. Start a new connection for each test: a browser may reuse an existing one, so saving a rule won't necessarily produce a new routing decision. Closing the test connections is an easier way to isolate variables than repeatedly restarting the whole device.

Separate rule matching failures from outbound connection failures

AsIs doesn't resolve domains to help routing; it doesn't mean resolution is unnecessary for the connection that follows. With IPIfNonMatch, Xray resolves a domain and tries matching its address only if the initial rule scan finds no match. If an always-matching fallback rule is at the end, the initial scan has already ended, so you can't rely on this additional lookup. If routing must depend on the resolved address, redesign the rule order and resolution strategy, then check whether the change adds queries or latency.

If there are no access logs, first check whether traffic reaches the inbound. If there's a log but the outbound tag is wrong, check the target format, earlier rules, and active configuration. If the tag is correct but the request fails, investigate outbound connectivity, upstream resolution, and transport requirements. Don't add another broad rule for a timed-out connection; that usually masks a transport issue instead of fixing a match. For more examples, see routing syntax and match priority.

03 / Name resolution

Optimize V2Ray DNS configuration

Distinguish system, app, and core DNS queries

System DNS serves programs that use the system resolver API. Apps such as browsers may also have their own encrypted DNS settings. The core's DNS configuration is used for queries it initiates itself and traffic explicitly sent through the relevant processing path. Changing the client's upstream resolver doesn't automatically replace every app's resolver. When troubleshooting, identify who sends the query, who returns the answer, and who uses the address to open the connection. These may be different components.

For example, in system proxy mode, some apps can pass a domain directly to the proxy, while others resolve it locally first. Different results for the same domain in two apps don't by themselves prove that the upstream resolver returned a bad answer. Start by checking the system's view with a system lookup tool, then reproduce the issue in the app and check whether the core log shows the domain. If the system lookup works but the app doesn't, check whether the app bypasses system settings and whether its selected resolver endpoint is reachable on the local network.

Start by comparing against one reachable upstream

This example assumes the trusted recursive resolver on your network is 192.168.1.1 and accepts standard DNS queries from your device. Use it as written only if both conditions are true; otherwise, replace it with the resolver address actually provided by your network. Add the dns object to an Xray root configuration that supports the field, then confirm that the relevant core features use it. This snippet doesn't take over system queries or force other apps to use that resolver.

{
  "dns": {
    "servers": ["192.168.1.1"],
    "queryStrategy": "UseIP"
  }
}

UseIP allows queries for both address families. Use UseIPv4 or UseIPv6 temporarily for comparison only when you've confirmed that one family has no usable network path and need to narrow down the issue. Querying just one address family isn't a general speed boost: if a target has records only for the other family, there may be no usable answer. Compare DNS lookup time and connection time separately. If lookup is fast but the connection is slow, changing upstreams may not help.

Before configuring multiple resolvers, decide what each one should handle. Internal hostnames usually need a resolver that can see the internal zone; public domains can use another trusted upstream. If your configuration supports per-domain DNS servers, check what happens when a match fails or the upstream times out. An internal hostname returning “not found” from another resolver doesn't mean the internal service is down; the query may have gone to the wrong DNS view.

Check encrypted DNS bootstrap and caching

Encrypted DNS requires the client to connect to its upstream first. If the upstream address is a hostname, the client may need to resolve it before it can establish the encrypted connection. If that initial lookup depends on a connection that hasn't been established yet, bootstrap fails in a loop. Check startup logs to distinguish a hostname lookup timeout from an unreachable endpoint or certificate validation failure. Use a trusted, independently reachable resolution path to bootstrap; don't disable normal certificate validation just to clear an error.

Also distinguish the outbound used for DNS queries from the outbound used for the destination being resolved: a website using one route doesn't mean its DNS request uses the same one. After changing the upstream, confirm that the core sends a fresh query, then record the returned address and the address used for the actual connection. The system, apps, and core may each cache results, so clearing only one cache may not change what happens. If the old address appears in just one app, restart it or clear its own cache before resetting all network settings.

After optimizing DNS, verify four things: existing public domains resolve, a name expected not to exist returns the right response, internal names still use the intended resolution path, and connections after the change work. If results are intermittent, note whether the issue occurs only during startup, after a network change, or continuously. This helps distinguish bootstrap issues, stale caches, and an unstable upstream. The layered guide to diagnosing connection speed gives you a test sequence for separating DNS issues from route problems.

04 / System traffic capture

TUN mode and traffic capture scope

Start by confirming why you need a virtual network interface

A system proxy gives its address to apps that choose to use it. TUN uses a virtual network interface to send traffic matching system routes to the client. It can cover apps that ignore proxy settings, but enabling it doesn't automatically capture all network traffic. Which destinations pass through the virtual interface depends on the address family, routing table, interface priority, and client configuration. When troubleshooting, first check whether traffic reaches the virtual interface instead of immediately changing the core's remote node.

On desktop, first confirm that the same node works through the system proxy in v2rayN, then check whether your current build supports TUN and has the required permissions. On mobile, use the system VPN authorization flow provided by the client. If no authorization prompt appears or the system says another service has taken over the connection, check the system status first. Don't copy desktop field names to mobile; the two may use different inbounds and exclusion methods.

Platform checks before and after enabling traffic capture
PlatformBefore enablingWhat to check first if something goes wrong
WindowsConfirm permission to create a virtual interface and check for an existing VPN.Compare the interface and destination routes; check whether another virtual adapter is taking priority.
macOSConfirm that the current client build supports this mode and grant any required permissions.Compare the active routes with other simultaneous connections on the system.
AndroidConfirm system VPN authorization and check the app allowlist or exclusion list.Check whether the target app is within the capture scope and whether it disconnects in the background.
LinuxConfirm that the client can create an interface and install routes.Check policy routing, the current network environment, and client logs.

Enable in stages and watch for traffic loops

For the first test, record the current node, system proxy status, and any local network destinations you need to reach. If the client allows it, disable any explicit proxy previously configured for the test app to avoid having one request affected by two proxy entry points. After enabling TUN, test a regular webpage, then the target app, local devices, and any service that relies on datagrams. Start a new connection for each test and compare logs before and after enabling TUN. A working webpage proves only that this specific path works.

Make sure the client's underlying connection to the remote server isn't routed back through the virtual interface. If it is, the client's own traffic may loop, making the node unreachable as soon as TUN is enabled and causing repeated retries in the logs. Check that the client correctly excludes the node's upstream connection, uses the intended physical interface, and still selects it after a network change. Don't exclude a whole large address range just to bypass one upstream.

LAN access also depends on where traffic is routed. Excluding a private route at the system level before traffic reaches the virtual interface is different from sending traffic through the core and matching a direct outbound. The first won't produce the same inbound logs; the second still depends on which resolver and outbound the core uses. If a printer is reachable by address but not by name, first check LAN name discovery or internal DNS before narrowing the traffic capture scope.

Test protocols separately and plan how to roll back

If only voice or real-time traffic in a particular app fails, test UDP separately from ordinary TCP connections. A packet reaching the virtual interface doesn't prove that the selected outbound and remote link can handle that protocol. If small requests work but large pages or sustained transfers stall, compare different networks and check whether the virtual interface MTU fits the actual link. Without comparison results, don't change the MTU, DNS, and transport settings all at once—you won't know which change helped if things recover.

To roll back, disable TUN first and confirm that the client removed the interface settings or routes it added. Then restore the original system proxy if needed. Test the local gateway, a public domain, and connections that worked before. If something is still wrong, check for leftover proxy, route, or VPN settings rather than clearing the entire system routing table. To establish a baseline with the system proxy again, return to the connection and verification guide.

05 / Domain mapping

FakeDNS mappings and troubleshooting limits

Why synthetic addresses must stay on the same processing path

With a suitable traffic capture path, FakeDNS doesn't immediately resolve a domain to the service's real address. Instead, it assigns a synthetic address from a configured pool and saves the mapping between that address and the domain. The app then connects to the synthetic address. The core handling that connection must receive it and look up the original domain to apply domain-based routing and establish the next connection. A synthetic address is a local mapping key, not the location of the remote service.

This is useful when an inbound sees only the destination address but routing still needs the domain. It can't identify an address hard-coded by an app or recover traffic that has bypassed the capture path. If an app obtains the real address itself, or another local program handles DNS, the connection may not carry this mapping. First confirm that ordinary DNS and TUN work independently, then introduce FakeDNS as a separate change.

Receiving a synthetic address verifies only half the path. You also need to confirm that a new connection to that address is captured and that routing uses the correct original domain.

Check the address pool separately from the enablement requirements

This snippet defines a single IPv4 synthetic address pool for Xray, using a subnet from a range reserved for testing and benchmarking as an example. Before using it, check whether the range is already used by system routes, virtual interface addresses, container networks, or other proxies. poolSize sets the mapping pool capacity; it isn't the number of concurrent connections. If the pool is small and many different domains are accessed in a short time, older mappings may be evicted sooner than expected.

{
  "fakedns": [
    {
      "ipPool": "198.18.0.0/16",
      "poolSize": 4096
    }
  ]
}

Setting an address pool alone doesn't enable the full processing path. If your client has an integrated toggle, confirm that it generates the required DNS capture, synthetic responses, and inbound domain recovery settings. For a manual setup, Xray's DNS server list can use fakedns for the relevant targets, and the inbound receiving connections to synthetic addresses must enable sniffing and support recovering domains from fakedns. System routes must also send the pool to the corresponding inbound. Verify each part against your actual implementation; a DNS toggle alone doesn't replace virtual network interface routing.

If you need internal DNS, first test an exception using a local resolver expected to return real addresses. Some internal apps compare resolved addresses, make a second connection, or use service discovery, so their behavior may change when they receive a synthetic address. To preserve internal resolution, make sure queries for internal domains go to the right upstream and check how connections to real private addresses are routed. A DNS exception alone won't help if the corresponding traffic route is wrong.

Retest the response, mapping recovery, and connection in sequence

Start a query from the app you actually use and check whether the answer falls within the configured address pool. If it returns a real address, check app-specific DNS, caches, and DNS exceptions. If it returns a synthetic address but the core logs no connection, check system routes and capture scope. If a connection is logged but no domain can be recovered, check whether the process recently restarted, the address came from an old cache, or the DNS response and traffic went through different instances. Only then investigate the target outbound and remote connection.

Don't use a probe to a synthetic address to decide whether a website is reachable. Make a new connection from the actual app and check the route that the domain is expected to match. When finishing the test, restore normal DNS first, clear any app or system cache that still holds synthetic addresses, and disable traffic capture using the client's procedure. If you turn off the virtual interface while an app is still using an old address, connections to it may fail temporarily. Repeatedly changing nodes won't fix that.

06 / Updates and maintenance

Manage multiple subscriptions and update policies

Give each source its own update boundary

Groups help organize nodes; managing multiple subscriptions means deciding when to refresh, what to keep if an update fails, and how to restore a connection. Separate long-term, trial, and manually maintained configurations so one full update doesn't change every option at once. Keep a short local index of group names, purposes, last successful refreshes, and verification results. Public notes should document troubleshooting, not subscription URLs, credentials, or exports of entire node groups.

When adding a second source, update it manually in a separate group and leave the active node in the first group unchanged. Once you've confirmed that the entries are complete, explicitly select and test a node in the new group. This separates “subscription downloaded” from “connected using a node from it.” If you do both at once, it's hard to tell whether a disconnect was caused by replacing the old node, a refresh that depends on it, or an unavailable new node.

Set automatic refresh intervals according to how often the source changes and how you use it. Refreshing too often creates unnecessary requests; refreshing too rarely may miss useful configuration changes. For frequently used groups, observe changes and failures for a while before enabling automatic updates. For groups used only occasionally, a manual refresh before connecting makes changes easier to track. If the UI allows only one schedule for all groups, leave time to verify important updates instead of assuming every group will refresh successfully.

Separate fetch, parsing, and activation results

Step one is fetching the data. A connection timeout may come from the current network, the subscription endpoint, or the proxy path. If the server responds with a login page, the request may have completed without returning node data. Step two is parsing: the client may be able to reach the subscription URL but still be unable to parse its response format. Step three is selecting and activating a node. Even after the list updates, confirm which entry the outbound uses and whether the previous active connection is still in use.

If a source can only be fetched through an existing connection, don't delete your only working node before trying to refresh it. Keep a verified recovery path, then refresh that group on its own. Don't change multiple sources at once until you've understood their dependencies. A node keeping the same note after an update doesn't prove its connection settings are unchanged. If needed, compare protocol, address, port, and transport locally, then verify by starting a new connection.

If several nodes are available, don't reorder your long-term preferences based on a single latency test. Use the same test target, similar time of day, and the same entry point to compare connection success and real-world performance over repeated tests. A probe may measure only a handshake or a short application round trip, not sustained transfer stability. Consider the service you're using and your plan requirements too; see the node selection comparison for more.

Sync naming conventions across devices, not every setting

Desktop and mobile clients can share group names and purpose labels, but support for import formats, filtering, connection inbounds, and automatic updates may differ. v2rayNG uses the Xray core; v2flyNG is an alternative that uses the V2Fly core. Desktop client configuration files may also contain local ports, routing, and UI settings, so they aren't portable subscriptions. First verify the source in the target client using the subscription import guide, then migrate any settings you need one by one.

When retiring a defunct source, first disable automatic updates for its group and confirm that the active node has been switched to another group or a manually retained entry. Then remove old records. To replace a subscription URL, verify it in a new group first and archive the old group only afterward, so it remains available for recovery. If your client supports local backups, restrict access to them. If a URL is exposed, replace it using the subscription provider's management tools; changing a local note or deleting a record from one device isn't enough.

07 / Outbound connections

Custom outbounds and tag management

Check outbound tags, protocols, and settings first

An outbound defines how the core handles traffic after it receives it. A tag is an internal reference name with no built-in meaning: naming an outbound direct doesn't make it a direct connection. Its protocol and settings determine what it does. Keep tags unique, easy to identify in logs, and exactly consistent with routing references. Before renaming a tag, check which rules and other settings use it so you don't leave broken references behind.

A typical direct outbound uses freedom; a blocking outbound can use blackhole. A proxy outbound needs protocol, authentication, and transport settings that match the existing remote service. If you add an outbound for a small category of traffic, keep the existing main outbound and test with a narrowly scoped rule. Don't use the test tag as a catch-all. Silently switching traffic that should use a proxy to a direct connection when the remote link fails isn't a reliable recovery strategy.

Verify tag wiring with an exact block rule

The following example shows outbounds and routing rules that can be added to an Xray root configuration. The test domain example.com is routed to the blocking outbound when it enters the core through this configuration. Other connections with no matching rule use the first outbound, which is direct. This example is for controlled testing only; don't replace an existing proxy configuration with it as-is. If your configuration already has a tag with the same name, don't add it again.

{
  "outbounds": [
    {
      "tag": "direct",
      "protocol": "freedom",
      "settings": {}
    },
    {
      "tag": "block",
      "protocol": "blackhole",
      "settings": {}
    }
  ],
  "routing": {
    "rules": [
      {
        "type": "field",
        "domain": ["full:example.com"],
        "outboundTag": "block"
      }
    ]
  }
}

When merging this into your configuration, add any missing objects to the existing outbounds and insert the exact test condition before general rules. If routing already exists, add the rule to its existing array; don't add another root field with the same name. Load the configuration through a client-supported method and check the startup logs. First verify a destination that already works, then test the example domain. Even if the page doesn't load, confirm that the logs show a match to block; otherwise, the failure may be due to DNS resolution or an unresponsive remote host.

The block example handles only connections matching the exact domain condition. It doesn't automatically cover subdomains, connections made directly to an address, or existing sessions. Nor does it restrict all system traffic: traffic that bypasses the client inbound won't be affected by this rule. If the target should match multiple names, list the known scope, test both matches and non-matches, and only then decide whether to use a broader domain suffix rule.

Check the default route, generation boundaries, and rollback conditions

When no routing rule matches, Xray uses the first outbound in the list. So even if every explicit rule stays the same, changing the outbound order can redirect targets that aren't covered. Before making changes, decide which connections should remain unchanged, which must use a proxy, and which may be blocked; then arrange explicit rules and the default order accordingly. For each important tag, keep one example that should match and one that shouldn't. Don't use “the page loads” as a substitute for confirming the route.

Graphical clients may regenerate their runtime configuration when you switch nodes or restart the core. Direct edits to temporary files may work immediately but disappear next time the client starts. For persistent settings, use a client-supported custom configuration method and confirm whether the client manages nodes or a complete configuration controls runtime behavior. Keep a working configuration and test notes locally before switching. Check the settings on initial load, after restart, and after switching nodes to catch overrides.

If startup fails, first check whether the configuration parses, the protocol is supported, and the tags exist. If the core starts but traffic uses the wrong outbound, check rule order under routing rules. If the tag is correct but the target is unreachable, check the DNS resolution path, authentication, and outbound connection. To roll back, undo the last change first and confirm that existing connections are restored before investigating other variables. Each observation will then help guide the next change.