V2Ray Advanced Configuration Guide

01 / Configuration Sources

How should you set up subscription groups and server filters?

Group subscriptions by source, then filter servers by purpose. Groups answer where configurations come from and who updates them; filters control what appears in the current list. Don’t confuse the two. In v2rayN, a subscription group typically stores the subscription URL, update options, and notes. Search and filter controls in the server list simply narrow what you see. If a server isn’t listed, it may be hidden by the selected group or search terms rather than deleted.

What should you record before creating a group?

Record the group name, source, and update method before entering the URL. Choose a name that describes its source or purpose, such as “Daily” or “Backup testing,” rather than a string of easily confused numbers. Subscription URLs often contain credentials, so paste them only into the client’s URL field—not into notes, screenshots, or public documents. After saving, run one manual update and confirm the expected protocols and server names appear before enabling automatic updates. If the list is empty, don’t keep deleting and recreating the group.

In v2rayN, open the subscription group controls to edit a group and run an update. In v2rayNG and v2flyNG, look for subscription settings or the relevant group management screen. Labels for updating the current group and all groups vary by client, so check the scope before clicking. If an import produces just one server, first determine whether the link is a single-server share link or a subscription URL. Both may look like long strings, but they update differently.

Why do filters sometimes hide everything?

First check what the filter field actually does. Some fields search the list; others filter entries during subscription updates. Some accept plain text, some support regular expressions, and some provide separate include and exclude conditions. Don’t paste an expression from another client without checking compatibility. If the field supports regex, a pipe means “or,” a period matches any character, and parentheses in a name may be treated as syntax. Start with one specific keyword, check the results, then add conditions gradually.

Use exclusion conditions with extra care. If every entry is excluded, a client may keep the old list or update the group to an empty list, depending on its implementation. Back up the current configuration and note the names and protocols of servers in use before changing filters. Afterward, check a few known entries; a shorter list alone doesn’t mean the filter is correct. Server names can change, making previously valid keywords stop matching, so review filters periodically.

The update succeeded, but connections fail. What should you check next?

A successful update means the subscription was fetched and parsed; it doesn’t mean every server can connect. First check that the active entry still points to a valid server, then verify that its protocol, transport, TLS, and authentication fields are complete. Manual edits to subscription entries may be overwritten on the next update. For changes you need to keep, make a separate configuration and note its source. If you edit the original entry without tracking the change, it can be hard to tell whether a later failure came from a remote update or a local edit.

02 / Where Connections Go

How do you order and verify routing rules?

Put specific exceptions first and broad fallbacks last. V2Ray-family cores commonly evaluate rules in order and select an outbound when a rule matches. A client may insert its own rules when generating the configuration, so compare the interface order with the final configuration. Matching depends on whether the connection includes a domain or an IP address, whether sniffing is enabled, and whether the domain strategy triggers a lookup. Adding a domain rule alone doesn’t guarantee that every connection will provide a usable domain.

What are domains, IP addresses, and outbound tags?

domain defines domain matching conditions, ip defines destination IP matching conditions, and outboundTag references an existing outbound tag. A tag is an internal identifier, not a free-form note in the interface. The example tags direct, proxy, and block must all exist in the outbound configuration. Conditions from different categories, such as a domain and an IP address, generally need to match together when listed in the same rule. If you mean “match either the domain or the IP,” use separate rules.

The snippet below uses common Xray/V2Ray-style routing syntax. It is not a complete client configuration. It assumes the required geosite and geoip data is available and the referenced outbounds are defined. It blocks the ad category first, then handles private addresses and domains in China, leaving other connections to the client’s default outbound. Domain category contents depend on the data files in use; they aren’t a permanent, universal list. If a category is missing, check data support rather than repeatedly reordering rules.

{
  "routing": {
    "domainStrategy": "IPIfNonMatch",
    "rules": [
      {
        "type": "field",
        "domain": ["geosite:category-ads-all"],
        "outboundTag": "block"
      },
      {
        "type": "field",
        "ip": ["geoip:private"],
        "outboundTag": "direct"
      },
      {
        "type": "field",
        "domain": ["geosite:cn"],
        "outboundTag": "direct"
      }
    ]
  }
}

Which domain strategy should you use?

AsIs means routing won’t proactively resolve a domain for IP-based rules. IPIfNonMatch typically tries to resolve the domain if no domain rule matches, then uses the result for further matching. IPOnDemand triggers resolution when the matching process needs an IP address. These strategies affect routing evaluation; they aren’t the same as DNS behavior across the whole system. If you only need a specific domain to go direct, use an explicit domain rule rather than making every request go through IP matching first.

If a site in mainland China is still routed through a proxy, check which rule matches before switching everything to direct. Confirm the domain is covered by the category, that no broader proxy rule comes first, and that the app isn’t connecting to a cached IP address. If the default outbound is set to proxy, unmatched connections going through the proxy is expected. For testing, temporarily add an exact domain rule and start a new connection in the same app. Existing long-lived connections may not migrate when the configuration changes, and refreshing a page may reuse an old connection.

How can you keep routing rules manageable?

Organize rules into layers—local resources, service-specific exceptions, category rules, and fallback policy—and document the purpose of each exception. For local network devices, routing private IP addresses direct is usually more reliable than relying on device domain categories. Internal business domains may also need a dedicated DNS path; changing the outbound alone won’t fix name resolution. Don’t put broad rules matching all ports or all networks first, or narrower rules later won’t get a chance to match. After making changes, test one known direct destination, one known proxied destination, and one local network destination.

For each test, record the destination domain, app, matching rule, and outbound tag—not just whether the site opened. A site may serve its page and images from different domains, so a direct connection to the main page doesn’t mean every resource uses the same route. For more on protocol fields, read VMess vs. VLESS. Routing and protocol selection are separate layers.

03 / Name Resolution

Where should you start when optimizing DNS?

Map the query path before choosing a resolver. An app may use system DNS, its own encrypted DNS, or pass the domain to the core through the proxy protocol. The core may also resolve domains separately for routing decisions and direct outbounds. So configuring DNS in the client doesn’t mean every app query will use it. Start by identifying which component sends the query, which route it takes, and who uses the response—not by adding several public resolvers to a list.

Why treat local and remote domains differently?

Local device names and company domains often resolve only through a local or organization-provided resolver. Public domains may return different CDN addresses depending on the resolver’s location. Sending all internal domains to a public resolver can return no result; forcing all public queries through a local resolver can return addresses that don’t match the proxy exit location. Split DNS aims to match resolution results to the route used for access, not to declare one resolver universally better than another.

The snippet below shows a basic setup that prefers one resolver for domains in the China domain category and uses another for other queries. It illustrates the structure of dns.servers only; it doesn’t guarantee that queries are sent through a proxy or direct connection. The core implementation, query protocol, and routing settings still determine the path. Don’t replace the client’s entire DNS configuration with this snippet. In particular, TUN setups may need related settings generated by the client for the virtual adapter and DNS interception.

{
  "dns": {
    "servers": [
      {
        "address": "223.5.5.5",
        "domains": ["geosite:cn"]
      },
      "1.1.1.1"
    ]
  }
}

Why can encrypted DNS still fail to connect?

A DNS-over-HTTPS resolver must be reachable before it can answer queries. If its address is a domain name, resolving that name can itself require DNS, creating a bootstrap problem. If the proxy server address is also a domain and its lookup is required to go through a proxy that isn’t connected yet, the setup has a circular dependency. First ensure the server and resolver hostnames have independent, reachable resolution paths, then configure routes for other domain queries. Don’t rely on a hard-coded server IP as a permanent workaround; remote addresses can change.

Don’t confuse domain strategy with DNS server selection. Routing’s domainStrategy determines when to resolve a domain for matching; a direct outbound may also have its own domain resolution strategy. Even with routing set to AsIs, the domain may still need to be resolved when the direct connection is made. Conversely, having an IP address for routing doesn’t prevent a browser or another app from making its own DNS query. Troubleshoot query routing and application connection routing separately; don’t draw conclusions from a single DNS test site.

How should you handle caches and dual-stack networks?

After changing the configuration, reconnect and account for caches maintained by the system, app, and core. Tests may still use old results until caches expire. On dual-stack networks, check address records separately: a successful IPv4 test doesn’t prove IPv6 traffic follows the expected route. Disabling IPv6 queries at one layer may not stop an app from using a cached address. If your network supports dual stack, check resolution, routing, and outbound connectivity for both rather than treating IPv6 as something to disable by default.

If DNS queries succeed but pages still fail, check routing and transport logs. Server rejections, TLS mismatches, and reset connections won’t be fixed by switching resolvers. Compare common connection issues in the Help Center.

04 / System Traffic Interception

How does TUN differ from the system proxy?

TUN receives system traffic through a virtual network interface. A system proxy provides a proxy address to apps that support the setting. Browsers usually honor the system proxy, but some command-line tools, background services, and apps with their own network stacks may not. TUN can capture a broader range of traffic, but adds dependencies involving permissions, routing, DNS, and the virtual adapter. Make sure a regular proxy connection works before enabling TUN. Otherwise, failures in both the connection and system interception make troubleshooting harder.

What should you check before enabling TUN?

Save a working configuration, note the current system proxy state, and confirm that the client supports TUN on your platform. v2rayN may use different helper components or runtime methods on different desktop platforms, and the TUN feature may not be implemented by the same core used for the selected server. Don’t infer virtual adapter support from the server protocol alone. Grant the permissions required by the client. If creating an interface or changing routes fails, resolve the permission or component issue before changing subscription servers.

On Android, v2rayNG and v2flyNG typically use the system VPN interface to capture traffic, and the authorization prompt is part of the system workflow. Other network tools using the same interface may conflict, so disable them before testing. On desktop, enterprise VPNs, virtual machine networks, and security software may also change routes or DNS. Don’t delete every network adapter to troubleshoot. Disable related software first, keep the original settings, and check whether networking recovers when the client exits.

Why can’t I reach local network devices after enabling TUN?

First check whether local network addresses are being captured and whether a more specific route or bypass setting applies. Printers, file shares, and admin pages may use private IP addresses, internal domains, or local network discovery protocols; these are different kinds of traffic. Routing private addresses direct usually handles ordinary connections that reach the core, but some broadcast, multicast, and discovery features still depend on the system interface and interception method. Test with the device’s IP address first, then troubleshoot name resolution and discovery. Don’t add a large number of domain exceptions all at once.

The server connection itself must be kept out of interception to prevent a routing loop. Clients typically handle this with interface binding, route exclusions, or another mechanism, but those assumptions can fail when the default adapter changes, another tunnel is enabled, or routes are edited manually. If logs repeatedly show attempts to connect to the same server after startup, or the network immediately recovers when TUN is disabled, check the outbound interface and exclusion rules first. Don’t add the server address to ordinary proxy rules to “strengthen interception”—that can make the problem worse.

How should you troubleshoot UDP, MTU, and wake-from-sleep issues?

If webpages work but voice, games, or other UDP apps fail, first check that the selected protocol, server, and transport support the required forwarding. TUN can capture traffic, but that doesn’t mean the remote server can forward it. If small requests work but larger transfers stall, then investigate path MTU and fragmentation. Don’t lower the MTU at random when you see a timeout. Rule out server and destination issues first, then make small adjustments within the client’s supported range and save the original value so you can restore it.

After waking from sleep or switching Wi-Fi networks, the active interface and default route may have changed. Reconnect the client, check whether the virtual interface has rebound, and confirm that system DNS still points to a reachable address. If internet access still fails after exiting the client, restore the system proxy, DNS, and routes separately rather than just closing the window. If browser and terminal behavior differs, see Troubleshooting App-Specific System Proxy Issues to determine whether the problem is app compatibility or system interception.

05 / Domain Mapping

When does FakeDNS work?

FakeDNS returns a synthetic address that the core can recognize, not the destination website’s real IP. When an app connects to that address, the core maps it back to the domain from the earlier query, then routes the connection or connects to the remote destination. This preserves the domain an app originally requested, especially in traffic interception setups where the system would otherwise lose it after DNS resolution. Both the query and the subsequent connection must pass through the same correlatable processing flow. If only one is intercepted, the connection may fail.

Why must both queries and connections be intercepted?

If the core answers the query but the connection bypasses it, the system may try to connect directly to an address that isn’t a real server. Conversely, if an app uses its own encrypted DNS to get a real IP, a connection entering TUN may not have a matching FakeDNS mapping. First identify where DNS requests enter the system, then check which component receives traffic to the returned address. Enabling TUN alone doesn’t prove the mapping flow is complete. FakeDNS integration varies by client, and some interception methods use a different configuration format; check the actual components in use.

The Xray/V2Ray core snippet below uses the relevant configuration format and shows only the synthetic address pool and DNS server selection. It also requires compatible inbound settings, sniffing-based domain recovery, and routing; pasting it alone won’t enable the feature. Make sure the address pool doesn’t overlap with test networks in use. If the environment already has routes for the same subnet, resolve the conflict first. With a graphical client, prefer its complete set of options to avoid changing one field while missing related settings.

{
  "fakedns": [
    {
      "ipPool": "198.18.0.0/15",
      "poolSize": 65535
    }
  ],
  "dns": {
    "servers": ["fakedns"]
  }
}

Are FakeDNS and sniffing the same thing?

No. FakeDNS restores a domain from an earlier query record; sniffing tries to identify application-layer destination details from the start of a connection, such as some HTTP or TLS information. Sniffing can’t identify every protocol, nor does it automatically map every IP address back to a domain. FakeDNS depends on an existing mapping. Some cores connect FakeDNS through a specific sniffing option, but the two features still use different sources of information. Check the fields supported by your core version and don’t mix option names from different configuration formats.

Also distinguish “use only for routing” from “rewrite the actual connection destination.” Some sniffing settings use the detected domain only for rule matching, while the connection still goes to the original IP. Others may cause the outbound to resolve the domain again. These behaviors can affect CDNs, certificate validation, and compatibility with certain apps. If an app fails after sniffing is enabled, first disable destination rewriting or compare results using a client-supported exclusion rule. Don’t delete every domain rule at once.

Why can some apps still fail after interception is disabled?

An app may have cached a synthetic address. After FakeDNS is disabled, new connections can still use that cached address, but the core no longer maps it back to a domain. Close the app’s connections and clear its DNS cache first; restart the app if needed. Consider both system caches and the core’s mapping state. Clearing only the system cache may not help if the browser still has its own cached results. When switching configurations, try to stop the app from opening new connections so old mappings and new DNS results don’t overlap.

Compatibility testing should cover browsers, apps that rely on local network discovery, and programs with their own DNS. If regular DNS already preserves domains and supports your routing needs, there’s no need to enable FakeDNS just to have more options. If you need it, test one app first and confirm that queries, mapping recovery, and outbound routing behave as expected before expanding interception. If problems arise, return to regular DNS rather than layering on more sniffing and rewrite settings.

06 / Updates & Maintenance

How can you manage multiple subscriptions without overwriting each other?

Keep remotely managed subscriptions separate from locally maintained configurations. Multiple subscriptions can provide servers from different sources or for different purposes, but they don’t automatically provide failover or share settings just because their names are similar. Create a separate group for each source and save local edits separately with a note about their purpose. This makes it easier to troubleshoot one source or understand what will be affected when you remove an old subscription. Don’t keep every URL and manually added server in one group, and don’t rely on list order to remember which entry is active.

How should you handle duplicate names and imports?

Compare the source and key connection parameters before deciding entries are duplicates. Two servers with the same name may use different ports, protocols, or transports; a renamed entry may still be the same server. Clients may deduplicate based on the address, protocol fields, or an internal identifier, so don’t assume deduplication will preserve manual edits. Export a backup and verify a few known entries before performing a large cleanup. If the list is hard to navigate, improve groups and filters instead of deleting every entry that looks similar.

Preserve management settings when moving between devices. Exporting a single share link usually won’t include subscription update settings, routing, DNS, or client preferences; exporting the full configuration may expose more sensitive information. Decide whether you need to move server parameters or the entire client setup. Desktop and Android clients may not share the same configuration structure. The safest approach is to recreate the subscription and migrate rules section by section, rather than importing a desktop client’s internal configuration directly into a mobile client.

When should you enable automatic updates?

Update manually and verify the results before setting a schedule. Choose an update interval based on how often the source actually changes; frequent requests aren’t necessary just to keep things “fresh.” Sleep, network changes, or temporary source outages can cause scheduled updates to fail. Some clients run update tasks only while they’re open, so a schedule doesn’t mean updates happen when the device is off. Also distinguish direct updates from updates through a proxy: the latter depend on an active connection. If a subscription is reachable only through a proxy, keep a verified working configuration available.

Updating and changing the active server are separate actions. If the source removes the active entry, the client may keep using its loaded configuration until restart or report an invalid entry on reload. After updating, confirm the active entry still exists, then reconnect and test it. Don’t assume automatic server selection is available unless you’ve configured a selection mechanism supported by the client. Interface sorting, test-result sorting, and active status are independent; the first entry isn’t necessarily the one in use.

In what order should you troubleshoot a failed subscription fetch?

Check that the URL is complete, then check the retrieval path, and finally check the format. A missing query parameter, a trailing space, or a login page returned by the source can all look like a parsing error. Identify whether the error is a connection timeout, an authorization failure, or a content parsing problem before deciding what to do. For connection failures, check the network and proxy update path; for authorization failures, check access to the source; for parsing failures, check format compatibility. Never post a full subscription URL in a public help thread—error messages may also expose credentials.

Treat backup files as sensitive too. Before sharing screenshots, hide URLs, authentication fields, and personal notes. Delete temporary export files after migration. If you’re switching clients, choose a platform on the client downloads page, verify the new setup, and only then remove the old one. The goal of managing multiple subscriptions is to keep sources, updates, and local changes traceable—not to make the list as long as possible. Clearly understanding the purpose of each group is more valuable than keeping many duplicate configurations.

07 / Combining Configurations

How do custom outbounds work with routing?

Define an outbound first, then reference its tag in routing rules. Outbounds describe how connections leave the core; routing determines which outbound handles each connection. A client’s “custom configuration” option may replace the entire configuration rather than append a snippet, while “custom outbound” may allow editing only one field. Check the editing scope before changing anything. Otherwise, a pasted outbound object may be parsed as a complete configuration or overwrite local listeners and DNS settings generated by the client.

What rules apply to tags and the default outbound?

Outbound tags should be unique, stable, and easy to recognize. Match spelling and capitalization exactly when referencing a tag in a routing rule; a server note isn’t an outbound tag. Common V2Ray/Xray configurations use the first outbound when no rule matches, but graphical clients may reorder outbounds or generate a default entry. Check the final running configuration. To send one type of traffic direct, add a matching route instead of changing the order of every outbound. That keeps the change narrow and easier to undo.

The basic outbound snippet below shows three patterns: direct connection, blocking, and connecting to a local SOCKS service. It isn’t a complete configuration. The third outbound is useful only if a working SOCKS service is listening on the specified local port. That service must not point to the current core’s inbound port, or it will create a loop. The example uses a loopback address to avoid exposing a local helper service to the LAN. If you need access from other devices, configure the listen address, authentication, and access controls separately.

{
  "outbounds": [
    {
      "tag": "direct",
      "protocol": "freedom",
      "settings": {}
    },
    {
      "tag": "block",
      "protocol": "blackhole",
      "settings": {}
    },
    {
      "tag": "local-socks",
      "protocol": "socks",
      "settings": {
        "servers": [
          {
            "address": "127.0.0.1",
            "port": 1081
          }
        ]
      }
    }
  ]
}

Why aren’t multiple subscriptions the same as a proxy chain?

Multiple subscriptions are separate configuration sources. A proxy chain requires an outbound’s underlying connection to pass through another outbound or helper service. The relevant fields depend on the running core and protocol implementation, and configurations for different cores aren’t interchangeable. Even if the interface lets you choose a preceding proxy, confirm whether it applies to subscription fetching, server connections, or application traffic; those are different scopes. Map each hop’s destination and connection responsibility before changing settings. This is more reliable than relying on a label like “upstream proxy.”

Every additional hop adds a dependency, so troubleshoot from the outermost reachable layer. First test the local helper service on its own, then check whether it can connect to the target server, and finally verify that the application’s routing rule selects that outbound. Don’t enable several proxies that point to one another, especially if the system proxy, TUN, and local SOCKS service are forwarding traffic in a loop. If logs repeat rapidly or connections keep opening and dropping, rule out a loop before checking authentication and transport settings.

Can protocol and transport settings be copied separately?

Check them together. Address, port, authentication, transport type, TLS name, and additional security parameters all affect whether a connection can be established. Changing the outbound protocol while keeping incompatible transport settings can produce a structurally valid but nonworking configuration. REALITY and related flow-control fields must also match the server; don’t enable them just because they seem more advanced. For background on how the fields relate, read How REALITY and XTLS Vision Work, then check what the current core supports.

If the client restores the previous value after saving, a subscription update, template generation, or interface write may be overwriting it. Don’t keep editing a temporary runtime file; find the actual configuration source or use the client’s supported persistent customization option. A fully custom configuration may bypass some graphical settings, so an enabled option in the interface doesn’t guarantee that its field was written. Judge the result using runtime logs, the generated configuration, and actual connection behavior together.

08 / Verification & Recovery

How should you verify and roll back configuration changes?

Break “it connects” into observable stages to determine whether a change worked: the subscription updates, the core starts, the server connection succeeds, DNS returns a result, routing selects an outbound, and the app completes its request. Each is a separate checkpoint. Keep a known-good baseline for advanced configurations and change one category of settings at a time. If you change the protocol, DNS, TUN, and routing rules together, it’s difficult to know which variable affected the result—even if connectivity eventually returns.

Choose a fixed set of test destinations

Choose destinations you’re authorized to access with predictable behavior. Test direct, proxied, and local network scenarios in the same app. Don’t rely on one all-in-one diagnostic site; it may use multiple domains, cached content, and third-party resources. Record the destination, time, active server, mode, and result—never credentials. If a test domain changes its CDN address, one result doesn’t prove the rule will keep working. Check the logs to see which rule actually matched.

Close existing connections before testing. Browsers may reuse connections, and background apps may maintain long-lived sessions that won’t necessarily reconnect when you save a routing change. Close and reopen the relevant app if needed instead of just refreshing once. Keep other test conditions consistent, such as the network, DNS method, and destination. A network change can alter the default route and DNS, so don’t attribute every change after switching networks to the client setting you just adjusted.

Where should you start when reading logs?

First check that the configuration loaded successfully during startup, then look for errors around the destination connection. Unsupported fields, missing tags, missing data files, and occupied ports are startup or configuration loading issues. Connection refusals, authentication failures, and DNS timeouts occur later. If there are no logs related to the destination, suspect that the app’s traffic isn’t reaching the client before changing servers. Increase the log level only for short-term troubleshooting, then restore an appropriate level to avoid retaining a long-term record of visited destinations.

Troubleshoot server timeouts from local conditions toward the remote server. First check the system clock, network connectivity, and subscription parameters. Then review transport and security settings in the core logs. A single server test result doesn’t prove that apps can use the connection. Some tests only connect to the server and don’t reach the application’s destination. Follow the Server Timeout Troubleshooting Steps and record local, network path, and server-side issues separately. Avoid repeatedly changing rules that are already correct.

How should you plan a reliable rollback?

Undo the most recent configuration change first, then reload the client and reconnect. If that doesn’t help, disable TUN or other interception and restore the previous system proxy and DNS settings. If FakeDNS was involved, also account for app and system caches so synthetic addresses don’t linger. A rollback isn’t the same as turning everything off; it means returning to a known-good state. Record the active mode and default outbound in your baseline. Restoring only the rules file may produce a different result if the mode has changed.

Keep client data backups separate from portable configuration snippets. Full data is useful for restoring the same environment; routing and DNS snippets make changes easier to understand. Both may contain sensitive information. Before upgrading or moving across platforms, keep the old configuration and verify that the new environment supports the relevant fields and data categories. A snippet accepted by one core isn’t a universal standard. If a field is unsupported, find out whether an equivalent feature exists instead of simply deleting the erroring field to make the core start.

You should be able to answer three questions: which layer changed, what evidence shows the change worked, and how to restore the previous state if it fails. Being able to answer all three makes a configuration maintainable. The next time a similar issue comes up, reuse the same tests and record-keeping instead of adding more temporary rules.