Advanced Configuration / Reference Guide

V2Ray Advanced Configuration Guide

Trace issues along the traffic path, from subscription updates to outbound selection.

If you’re new to V2Ray, start with the quick-start guide to import a profile, connect, and verify your setup. Then return here to adjust advanced options. This page is organized by topic; you don’t need to enable every feature. v2rayN is our recommended desktop client. On Android, choose v2rayNG or v2flyNG based on the core you need—see the client downloads. The sections below distinguish client menus, system settings, and core configuration fields. Names and support may vary by client version.

Subscription Groups and Server Filtering

Separate what gets imported from what gets displayed

Subscription groups identify where profiles come from. A group usually corresponds to one subscription URL and the profiles imported when that URL is updated. Selecting a group only filters the list; it does not switch the active connection or change the core’s routing rules. In v2rayNG, add a group under “Subscription Group Settings,” enter a label and URL, save, then return to the profile list and update it. In v2rayN, open the group settings from the subscription group menu. If the client supports updating the current group, select the target group first, then update it. Choose “Update all” only when you want to refresh every source. Grouping and filtering options in v2flyNG depend on the current interface; don’t look for another client’s menu labels.

After importing, check that the expected profiles appear in the list, then select a specific entry before connecting. An update may recreate managed profiles, replacing a previously selected entry with a new one of the same name—or removing it entirely. The group name shown at the top doesn’t confirm which profile is actually running. Check the selected profile and connection logs. If profiles have the same label, compare their protocol, transport, and port locally. There’s no need to copy server or subscription URLs to an external troubleshooting site.

Find out where filtering is applied

Start by checking where the input field appears. Search in the profile list usually narrows only what’s visible; clearing it should show the profiles again. A filter in subscription group settings may instead determine which profiles are imported when the group is updated. Changes to the latter usually need another update to verify and may affect the existing list. To troubleshoot, clear the list search, return to the target group, then inspect its import conditions. Don’t change all three at once—you won’t know whether profiles weren’t saved, were grouped elsewhere, or were simply hidden by search.

Use a regular expression in a filter field only when the setting explicitly supports regex. For example, if a provider labels test profiles with the prefix Lab-, the expression below can match that prefix. It isn’t a subscription URL or a routing rule. Test against two known labels—one that should match and one that shouldn’t—then check whether the interface keeps or excludes matches. In case-sensitive implementations, labels starting with lowercase letters won’t match. If the provider changes its label format, the expression may remain valid but stop matching any profiles.

^Lab-

Tell a failed fetch from an empty filtered result

When an update fails, first check whether the client received subscription content it could parse. Timeouts, certificate errors, and access denied errors occur during fetching. A successful request that imports nothing may mean the response was a login page, used a format the client can’t parse, or was entirely excluded by the filter. Check the update log for request errors, then temporarily clear the group’s filter and retry only that group. If profiles appear, refine the filter. If not, check whether the URL has expired and whether the provider supplied a subscription URL, a single-profile link, or a file intended for another tool.

Some clients let you choose whether subscription requests go direct or through the current proxy. If an existing connection works but updates fail, compare whether both request paths can reach the subscription service. If no profile works, updating through the current proxy may create a loop. Restore a working connection path first, then decide whether subscription updates should always use it. A successful update only confirms that the content was downloaded and parsed; it doesn’t mean every imported profile can connect. Test one known-compatible profile next. Bulk speed tests are no substitute for a basic connectivity check.

Keep a control profile

Before changing a filter on an existing group, note the original settings and keep a verified local profile. Don’t turn your production group into a test group, and never include a subscription URL in a troubleshooting screenshot. Treat the full URL as a credential, even if the interface hides part of it.

Routing Rules in Practice

Make sure requests reach the core first

Routing only handles connections that reach the core. On desktop, apps that ignore the system proxy may never enter the core when only system proxy mode is enabled. On Android, apps excluded from per-app proxying won’t be handled by these rules either. Before troubleshooting, pick an app that you know passes through the client and check whether its requests appear in the logs. If there’s no request in the logs, don’t start by changing domain rules. Check the system proxy, the app’s own proxy settings, VPN permission, or whether the app is included in the selected list. Once traffic entry is confirmed, determine whether a rule failed to match or selected the wrong outbound.

Rule order and the default route

In Xray’s ordered routing rules, the first matching rule determines how a request is handled; evaluation doesn’t continue to find a more specific rule. Put exact domains, specific private network ranges, and exceptions for dedicated inbounds before broader rules. When a single rule has different fields, such as a domain and a port, they generally all need to match; satisfying just one isn’t enough. To route traffic for a domain or an address range, create two rules with the same target. If no rule matches, the first outbound in the list is generally used. A graphical client may add rules automatically or rearrange them, so check the effective configuration to confirm the actual priority.

Common domain and address conditions
ConditionWhat it matchesLimitations
full:example.comMatch the exact domainDoes not match its subdomains.
domain:example.comMatch the domain and its subdomainsUseful for routing an entire domain tree the same way.
192.168.50.0/24Match a specified IPv4 rangeUse the actual network range; don’t assume every LAN uses the same prefix.
geoip:privateMatch private addresses in the rule dataDepends on the rule resources in use and the ranges they include.

Choose a domain strategy, then test both matching and non-matching cases

AsIs doesn’t proactively resolve the target domain to match address-based rules. IPIfNonMatch can resolve the address if domain-based routing doesn’t produce a match, then try matching by address. If a broad rule matched earlier, address-based rules further down can’t change the result. IPOnDemand resolves the domain when matching requires an address, increasing the chance that DNS will be involved. None of these strategies forces every app to use the core’s DNS, nor do they set the address family for outbound connections. If an explicit domain rule is enough, there’s no need to resolve every relevant request in advance just to route it.

This is an example of a top-level Xray routing object. Merge it into an existing configuration, and make sure the outbound list contains an outbound named direct. To apply it only to test apps, add an inbound tag condition; don’t start the core with this snippet as a complete configuration. Replace the example network range with one you can access for testing. If you don’t need the LAN condition, remove the second rule rather than leaving a rule with an unclear match range.

{
  "routing": {
    "domainStrategy": "IPIfNonMatch",
    "rules": [
      {
        "type": "field",
        "domain": ["full:example.com"],
        "outboundTag": "direct"
      },
      {
        "type": "field",
        "ip": ["192.168.50.0/24"],
        "outboundTag": "direct"
      }
    ]
  }
}

Test at least three types of requests: the exact domain that should match, a subdomain that shouldn’t match, and an address that should match the network range rule. The subdomain doesn’t need to host a website; use outbound logs to check the routing result rather than inferring it from the response or whether the domain exists. If domain requests appear only as IP addresses in the logs, first check whether the app resolved them before they reached the core. Then check whether “Enable Sniffing” is appropriate for that inbound. Sniffing can recover limited target information from supported, identifiable traffic, but it can’t guarantee a domain will be available for every connection. If the rule matches but the page still won’t load, check outbound dialing and the destination port instead of changing rule order again.

Optimize DNS Configuration

Find out who’s asking and who’s answering

A single visit may involve several stages of DNS resolution. An app might use the system resolver or its own encrypted DNS. The core may resolve a domain for routing, or leave it for the remote outbound to handle. The proxy server’s domain may also need to be resolved before the connection can be established. Changing one DNS setting won’t automatically affect the others. First note the scope of the problem: is one browser failing, are all apps routed through the client affected, or can the client itself not resolve the server’s domain? These point respectively to app-level resolution, core DNS, and bootstrap resolution before connecting.

When v2rayN uses system proxy mode on desktop, don’t assume terminals and browsers use the same proxy or DNS behavior. On Android, distinguish system “Private DNS” from client options such as “Enable local DNS”: similar names, different roles. With a VPN enabled, whether an app’s DNS queries are captured depends on whether the app is routed through the VPN, the DNS settings supplied by the system, and whether the app sends its own encrypted queries. To diagnose, temporarily compare automatic and custom DNS in one test app, then restore the original setting. You don’t need to permanently disable system-wide settings first.

Match each resolver to its purpose

For home or office devices, use a resolver that actually knows the records for that network. Switching everything to a public resolver may make internal hostnames unresolvable, even if their private IP addresses are already allowed to go direct by routing rules. Conversely, sending every public domain to a server that only answers for internal names may cause timeouts. Xray’s built-in DNS lets server entries use domains to specify which domains they should match first; also consider whether other servers are used as fallbacks. Specifying a domain range alone doesn’t force queries to stay isolated. If internal domains must go only to an internal resolver, check fallback settings and how each client’s core handles DNS.

When using a DNS-over-HTTPS resolver, work out how the resolver’s own domain will be resolved. If its initial lookup depends on the same service that hasn’t been connected yet, startup can get stuck in a loop. Likewise, if the resolver is reachable only through a proxy outbound, but the proxy’s address depends on that resolver, the proxy and DNS will wait on each other. Set up an independently reachable bootstrap path for services that need to be resolved before connecting, then handle ordinary traffic domains. Adding more upstreams won’t fix a dependency loop; it may only appear to work while the cache is valid.

Verify the returned addresses separately from connectivity

On a desktop with nslookup, start by checking the addresses returned through the system resolver. The commands below query IPv4 and IPv6 records separately; they don’t prove that the core gets the same results for the same domain. To check core behavior, make sure the request reaches it, start a new connection, and inspect the relevant DNS or outbound logs. Use the same test domain each time and record the returned address type, latency, and error message so you can compare results across configuration changes.

nslookup -type=A example.com
nslookup -type=AAAA example.com

If a dual-stack connection often tries an unreachable IPv6 address first, compare the actual IPv4 and IPv6 connection results to confirm an address-family connectivity issue rather than a DNS timeout. The core’s queryStrategy can limit the address types queried by its built-in DNS, but it doesn’t change the system’s IPv6 settings or block apps from using IPv6 literal addresses directly. Treat it as a configuration choice with a specific scope. If the same domain returns different addresses from two resolvers, that doesn’t automatically indicate a fault: caching, geolocation-based answers, and different network vantage points can all cause differences. Judge by whether the connection succeeds and whether the returned address belongs to the expected network.

Change one resolution stage at a time

Note the existing upstreams and domain conditions, then change one setting. Test with a new connection; restart the test app if needed to distinguish app caching from a setting that didn’t take effect. Record lookup failures separately from connection failures that occur after a successful lookup. Don’t lump both together as “DNS is down.”

TUN Mode and System Traffic Capture

Know why you’re switching modes

System proxy mode works for desktop apps that honor proxy settings. TUN captures traffic through a virtual network interface and system routes, which can help with apps that ignore proxy settings. It changes how traffic enters the proxy chain, but doesn’t guarantee every connection can be forwarded by the current outbound. For example, if an app sends UDP traffic, receiving it on the virtual interface only confirms that traffic capture works. Forwarding still depends on the capture component, routing, outbound protocol, and server support. If the target app already works through the system proxy, keeping the current mode makes it easier to isolate problems.

In v2rayN, first close other tools that change system proxy settings or create virtual network adapters. Confirm the selected profile works in its current mode, then find the “TUN Mode” switch in the main interface and grant any permissions required by your system. Creating a virtual interface and changing routes may require extra privileges; the exact requirements and client support depend on the platform and configuration. On Android, traffic capture uses Android VpnService to handle selected apps—don’t apply desktop network adapter instructions. The first connection requires system permission. If only one app can’t be captured, check the per-app proxy list and bypass mode first, then see VPN permissions and per-app proxying.

Check that traffic capture is active on each platform
Platform and clientCheck firstThen verify
Windows · v2rayNPermission prompts, virtual interface status, and any existing VPNCompare routes and target app logs before and after toggling the setting.
macOS / Linux · v2rayNWhether the current release includes the option, and system permissionsCheck that traffic capture is active; test a local and an external destination.
Android · v2rayNG / v2flyNGSystem VPN permission and which apps are allowed through the VPNTest an app on the allowlist and one that isn’t.

Distinguish routing loops from scope conflicts

If the internet stops working immediately after switching modes, turn off TUN and check whether the previous mode works again. If it does, and the logs keep trying to connect to the same server while TUN is on, check whether outbound connections are being routed back into the virtual interface. Many clients arrange for their own connections to bypass the interface, but multiple network adapters, another active VPN, or manually configured default routes can break that assumption. Don’t delete the system default route. First disable competing traffic-capture tools and restore automatic settings, then use the capture component’s options to check the connection that should leave through the physical interface.

If external websites work but devices on the same subnet don’t, compare the device’s local address with the actual subnet. There are two different kinds of “bypass” to consider: a system route can keep a subnet from entering the virtual interface at all; a core routing rule can send a request that has entered the interface through a direct outbound. A core direct rule only matters after the request reaches the core—it can’t fix an app that the system routed elsewhere or assigned incorrectly. Conversely, if an entire range is excluded at the system level, those requests won’t appear in the core logs. Don’t rely on an interface saying “bypassed” to identify which layer is responsible.

Run three independent regression tests

First, open a new connection to an external website and confirm browsing and DNS work. Second, access a known local network service and confirm traffic capture hasn’t changed the expected internal route. Third, test the app that originally ignored the system proxy to confirm the mode change fixed the problem. If you need UDP, test the feature in the target app itself; a browser opening a regular webpage doesn’t prove UDP works. Rerun the necessary tests after switching between wired, Wi-Fi, and mobile networks. The default gateway and address family may change, so an exclusion range that worked before may no longer apply.

To roll back, stop traffic capture using the client’s switch, then confirm that the original system proxy state and local access are restored. Before exiting, keep a brief note of the first error, distinguishing permission denied, interface creation failure, route setup failure, and forwarding failure after startup. On Android, if the system is set to always-on VPN, stopping the client may not restore direct access. Check the system VPN settings against your network policy; don’t assume the client failed to stop. For other common connection issues, see Troubleshooting.

FakeDNS Address Mapping and Limitations

How synthetic addresses map back to domains

FakeDNS assigns a synthetic address from a configured pool to a queried domain and saves the mapping. The app then connects to that address. The component receiving the connection uses the mapping to recover the domain, allowing the core to route by domain or pass it on as the outbound target. This doesn’t assign a new real address to the destination server or encrypt all DNS requests. The key is that the lookup and connection must use components that share and understand the same mapping. An app using a known IP directly, or resolving through its own DNS path to get a real address, won’t naturally use this mapping flow.

A common misconfiguration is to alter DNS lookups without capturing the resulting connections. For example, an app receives a synthetic address from a captured resolver, but its connection bypasses the virtual interface because of the per-app list or an address exclusion. The logs may show a timeout to the synthetic address, or the core may not see the request at all. Another possibility is that the capture component receives the connection but lacks the mapping or FakeDNS destination recognition, so it passes the synthetic address to an outbound as-is. These cases look similar, but require different fixes: check traffic capture scope in the first case and core recognition in the second. Changing the regular DNS upstream won’t fix either one.

Address pool size and scope

This is an Xray top-level fakedns address pool snippet using an IPv4 range reserved for benchmarking. It describes only the pool and mapping capacity; it doesn’t enable the complete feature by itself. poolSize is neither the number of concurrent connections nor the number of subscription profiles. It limits how many address-to-domain mappings the pool can retain. Match the capacity to the number of available addresses in the subnet and the number of domains commonly used at once. Don’t reuse this range if it’s already used by an internal test network in your environment. Check whether the system, virtual interface, or another tool is already using it.

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

When assembling an Xray configuration manually, also make sure the selected DNS queries can use fakedns and that the receiving inbound enables the corresponding destination recognition—for example, by using fakedns in sniffing settings for a supported inbound. A graphical client or TUN component may manage its own synthetic address mechanism, with different options and parameters from Xray’s top-level object. Don’t mix mappings generated by one layer with a separate address pool in another and assume they can resolve each other. Use one clearly defined configuration to create and consume the mappings, then check which outbound the traffic actually uses.

Test with limited scope and plan a rollback

For a trial, use one controllable app and one test domain. First establish a baseline with regular DNS: note whether it resolves, whether the core sees a domain or an address, and which outbound is selected. After enabling FakeDNS, have the app open a new connection. Check whether it received an address from the pool and whether the traffic-capture logs recover the expected domain. Don’t draw conclusions from a DNS lookup in a terminal alone: the terminal and target app may use different resolution and traffic-capture paths. If rules based on addresses suddenly stop matching, check whether they match the synthetic address, the recovered domain, or a real address resolved later.

Apps that discover LAN devices, rely on internal DNS, or make decisions based on real addresses are better served by keeping the real DNS results they need. If a service is on the same subnet, check that both its local hostname and the connection to it take the right path; simply excluding the domain from the synthetic range isn’t enough. When the address pool is exhausted, mappings are evicted, or a component restarts, an app’s cache may still hold an old synthetic address. If new pages work in the same app but an old one fails, close the old connection and restart the test app before changing the pool size.

Check caches after disabling the setting

To roll back, restore regular DNS and the original traffic-capture settings, then have the test app resolve the domain again. Turning off the setting doesn’t immediately remove synthetic addresses already cached by the app. Confirm that a fresh lookup returns a real address and the connection no longer targets the synthetic range before deciding whether the issue is resolved.

Manage Multiple Subscriptions and Roll Back Changes

Group by update ownership, not current latency

Keep each subscription’s source separate. Name groups by provider, purpose, or who maintains them—for example, separate regular sources, temporary test sources, and manually added profiles. Use labels that identify the scope without copying URLs or account details. Don’t organize groups by speed-test results: rankings change with the network, while a profile’s source and update owner don’t. If regular and test profiles come from the same source, use the client’s labels, filters, or a separate test environment where possible instead of fetching the same URL more than once.

Keep manually imported profiles, profiles with notes you need to preserve, and short-term troubleshooting profiles separate from automatically updated entries where possible. When a subscription refreshes, the client may recreate its entries based on the source, so local notes added to subscription-generated profiles may not survive. If you need a snapshot, use the client’s copy feature to save it separately and mark that it won’t track changes from the source. Review periodically whether you still need the copy. Don’t accumulate old entries just to avoid losing profiles; that makes it easier to select one that no longer works.

Update and verify one group at a time

Before maintenance, confirm which profile is currently working and which group it belongs to, then update one source at a time. After the refresh, check whether the group is unexpectedly empty, whether the profiles are still recognizable, and whether common protocol and transport fields look right. If the profile count changes sharply, don’t immediately update other groups for comparison. Use that group’s update log to distinguish a source response change from a parsing difference or filtering effect, then test one representative profile. Once the group behaves as expected, move on to the next one. This helps isolate changes without interrupting other sources.

If scheduled refresh is available, avoid times when you need a stable connection. Don’t have multiple devices refresh the same source frequently, and don’t use rapid retries instead of troubleshooting. If requests are being rate-limited, follow the provider’s rules and reduce the refresh frequency; a failed refresh doesn’t mean the profiles are invalid. For subscriptions that require the current proxy, first confirm that the connection still works, then refresh. A source that can’t be updated shouldn’t affect other groups that are working independently. Treat automatic updates, automatic profile selection, and automatic system proxy activation as separate features, even if their failures look similar.

Handle duplicates, migrations, and device differences

Don’t delete a profile just because its label matches another one. The same name can refer to different sources or transport settings, while different names can refer to the same server with different configurations. Before cleaning up, compare the source group, protocol, address and port, transport, and security settings locally. Determine whether the sources actually overlap or whether the client is showing common profiles across groups. If two active sources maintain duplicate entries, deleting one group is usually a better fit than deleting profiles one by one—but first check whether app rules or startup options rely on profiles in that group.

When moving from v2rayN to Android, don’t assume the entire desktop configuration directory can be imported as-is. Recreate group labels and subscription sources as needed; configure platform-specific system proxy, TUN, and per-app settings separately. v2rayNG and v2flyNG may also produce different results from the same subscription because they use different cores, and not every protocol or field has an equivalent implementation. Test one representative profile first, then restore custom routing and DNS settings step by step. Assess incompatible entries against the target client and core’s capabilities instead of counting them as network failures.

Prepare a rollback before updating

Before updating, note the working profiles, client mode, and relevant rules. If you need a backup, keep it in a secure location because exports may contain subscription URLs and connection details. When asking for help, share only a redacted error type, the stage where it occurred, and steps to reproduce it. If a subscription URL is exposed, ask the provider to replace it rather than just deleting the local entry. If an update breaks an entire group, switch back to a verified control profile first and confirm the client can still connect. After a successful rollback, decide whether to restore local profiles, change the filter, or wait for the provider to fix its response.

Custom Outbounds

Decide who will maintain the complete configuration

An outbound defines how the core establishes the next connection after receiving traffic. It can connect directly, reject the connection, or use a specific proxy protocol. An outbound’s tag is an identifier used by routing rules, not the server label shown to users. A rule’s outboundTag must point to an existing tag, with matching capitalization. Adding an outbound without a routing rule that references it usually won’t have the intended effect. Adding it at the top of the outbound list may also change the path for every connection that doesn’t match a rule. Map out how inbounds, rules, and outbounds relate before deciding which layer to edit.

When a graphical client starts from a single profile, it typically generates a runtime configuration from the interface settings. Manual edits to the generated file may be overwritten when you switch profiles or restart the client. If the client supports importing a complete custom configuration, maintain a reusable copy in that mode. Don’t assume the client’s routing editor, DNS switches, or system proxy ports will be merged automatically with a full custom configuration. First confirm how the client uses the file, including the expected inbound type, listening port, core, and runtime mode. Desktop and Android have different system traffic-capture capabilities; a configuration that parses successfully isn’t necessarily portable without changes.

Use a minimal configuration to verify tags and match order

This is a complete Xray configuration for local testing. It listens for SOCKS requests only on the loopback address and uses two outbounds for direct connections and rejection. Direct remains first; only the precisely matched target is routed to the reject outbound. This example doesn’t use a remote proxy, making it useful for testing outbound tags separately from system traffic capture. Before running it, make sure the listening port isn’t already in use. If you change the port, update the test commands too. Test in an isolated environment rather than overwriting the configuration currently used by your client.

{
  "log": {"loglevel": "info"},
  "inbounds": [
    {
      "listen": "127.0.0.1",
      "port": 10808,
      "protocol": "socks",
      "tag": "local-test",
      "settings": {"auth": "noauth", "udp": false}
    }
  ],
  "outbounds": [
    {"protocol": "freedom", "tag": "direct", "settings": {}},
    {"protocol": "blackhole", "tag": "reject-test", "settings": {}}
  ],
  "routing": {
    "domainStrategy": "AsIs",
    "rules": [
      {
        "type": "field",
        "inboundTag": ["local-test"],
        "domain": ["full:example.net"],
        "outboundTag": "reject-test"
      }
    ]
  }
}

Once the configuration is running on a compatible Xray core, use the commands below on the same desktop device with curl installed. Both commands pass the target as a domain through the SOCKS inbound. The first should select direct; the second should select reject. Your local network may also be unable to reach the test domain, so compare outbound selection in the logs rather than expecting specific response codes. If neither command can connect to the local port, first check whether the configuration is running, the port is correct, and another process is using it. You haven’t reached the routing troubleshooting stage yet.

curl --max-time 10 --socks5-hostname 127.0.0.1:10808 https://example.com/
curl --max-time 10 --socks5-hostname 127.0.0.1:10808 https://example.net/

When expanding, check the core, dialing, and destination one layer at a time

When moving to a real outbound, keep the reproducible local inbound and known-good default path, then change only one target rule. If the core won’t start, check configuration syntax, protocol support, and tag validity first. If the core starts but logs no requests, check how the app enters the client. If a request selects the expected outbound but dialing fails, check server address resolution, network reachability, and whether the protocol fields match the provider’s settings. A common misdiagnosis is to change routing after seeing a TLS error, even though the outbound may already be selected correctly. Check the required handshake parameters and destination endpoint instead of moving the rule.

Before moving the configuration to another client, read Xray and V2Fly core differences to distinguish common configuration concepts from core-specific fields. After deployment, remove the test inbound and any exceptions you no longer need, then restore the usual log level. Keep a runnable copy from before deployment, and retest apps, DNS, and LAN routes using the normal traffic-capture method. If explicit proxy tests work on desktop but apps fail under system traffic capture, troubleshoot the traffic entry layer rather than rewriting an outbound that has already been verified.