Advanced V2Ray Configuration Guide

1. Subscription Groups and Server Filters

Subscriptions provide a source for server configuration updates; groups are how the client organizes those sources and their entries. Keep the two concepts separate: seeing a group in the server list does not mean routing rules reference it, and viewing a group does not mean a server in it is active. Before reorganizing, check the selected server, its subscription, and the current routing mode. Record a configuration that already connects successfully so you have a baseline for troubleshooting.

Group by Source, Then Filter by Purpose

In v2rayN’s subscription group settings, give each source a recognizable name and enter its corresponding URL. Use names that describe the source or purpose, such as “Daily” or “Test,” rather than a temporary server name. Save the group, update it, and check that its entries appear in the expected place. Keep manually imported links in a separate group where possible; otherwise, cleaning up subscription entries could also delete configurations you meant to keep.

Subscription URLs often contain access credentials and should be treated as sensitive. Don’t include the full URL in screenshots, public support posts, or shared documents, and don’t swap URLs from different sources as a test. If an update fails, first determine whether it failed while downloading the subscription or parsing its contents. Download failures may involve network access, certificates, or authorization; parsing failures may point to a format or client compatibility issue. Group names are for local identification—renaming one won’t fix an invalid URL.

Search Results vs. Persistent Filters

The search box in a server list usually filters only what is currently displayed. A filter in subscription group settings may instead affect which servers are retained or shown after an update. Read the field’s hint before using it, and check whether it matches server remarks, addresses, or another property. Test with a short keyword known to exist, check the results, then add conditions. Don’t enter a generic regular expression in a field that accepts plain keywords, or assume every client uses the same matching behavior.

If a field explicitly supports regular expressions, (?i)(test|backup) can match either keyword without regard to case. Whether this syntax works depends on the field’s regex engine; if it isn’t supported, use the plain-text filter provided by the interface. Test inclusion and exclusion conditions separately, especially around spaces, full-width punctuation, and special characters in remarks. A filter that’s too broad leaves unwanted entries; one that’s too narrow can make the list appear empty after a successful update.

Verify Server Details After an Update

Subscription updates may add, remove, or rename servers, and entries with the same name may not have identical connection settings. After an update, check more than the remark: verify the protocol, server address, port, and transport. For a server you rely on, confirm how the client preserves your selection during updates. If an old entry disappears, a highlighted replacement in the list doesn’t prove that the client switched to it. Select the intended server again and test with a new connection.

If entries are duplicated, first determine whether the same source provided them more than once or several groups contain the same server. Before deleting duplicates, preserve the original subscription relationship so an update doesn’t recreate them—or remove entries with different transport settings by mistake. Grouping and filtering controls may be in different places on Android, but the approach is the same: isolate one source, inspect its entries, then test a connection. Bulk-deleting based only on similar names can hide meaningful configuration differences.

2. Routing Rules in Practice

Routing handles connections that have already reached the core. The system proxy determines whether an application sends a connection to the local entry point; routing then selects an outbound. These layers aren’t interchangeable. Before configuring rules, map the actual path: application, entry point, destination identification, rule matching, outbound. If an application isn’t using the system proxy at all, changing domain rules usually won’t affect how it connects. For a comparison of these two settings, see System Proxy vs. Routing Mode.

Rules Are Checked in Order: Put Specific Conditions First

Rules are generally checked in order, and the first match selects the outbound, so put exceptions before broad rules. A sensible starting order is specific business exceptions, categories to block, local network addresses, commonly direct destinations, and finally the default outbound. Don’t just group rules under “direct,” “proxy,” and “block.” If an earlier rule already matches a destination, a later, more specific rule never gets a chance to apply.

When a rule includes different fields such as domains, ports, and network types, those fields usually all have to match. Multiple entries within a domain array, by contrast, are alternatives. Putting “this domain or this port” in one rule can produce an intersection when you expected a union; use separate rules for alternatives. Before editing, decide whether to match by domain or by resolved address—this also determines whether DNS needs to be involved.

Start with Minimal Direct and Block Rules

This routing snippet uses common Xray / V2Fly fields; it is not a complete startup configuration. It assumes the existing configuration already defines direct, block, and a default proxy outbound, and that the required rule resources are installed. AsIs means the core won’t resolve a domain just to evaluate IP rules when no address is available yet. Destinations that already arrive as IP addresses can still match IP rules.

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

There’s no rule field named final here, because it isn’t a general-purpose keyword in this kind of JSON routing configuration. When no rule matches, the first outbound in the list is usually used; graphical clients may also generate their own fallback rule. Inspect the final generated configuration rather than relying on abbreviated labels in the interface. To send remaining TCP and UDP connections through the proxy, you can add corresponding network rules at the end, but make sure the outbound supports the required traffic.

Check Domain Visibility and Rule Resources

Domain rules work only if the core can identify the destination domain. Passing a domain through an HTTP or SOCKS entry point is different from an application resolving it through the system first and then submitting an IP address. Traffic sniffing can recover domains from some protocol data, but it can’t identify every connection. If a rule looks right but never matches, check the destination format in the logs first, then review sniffing settings instead of adding more variations of the same domain.

geosite and geoip require the corresponding resource files and categories. Missing resources or category names that aren’t in the installed files can cause startup or configuration errors. Use the client’s resource manager to confirm the file location matches the core in use; don’t just put files in an arbitrary working directory. For every new rule category, test a reproducible destination with a new connection and record the outbound it matches. More rules don’t automatically mean more accurate routing.

3. DNS Configuration

DNS configuration needs to answer three questions: who makes the query, which resolver receives it, and how the connection to that resolver is routed. System resolution, an application’s built-in resolver, and core DNS are separate layers; there’s no single “enable DNS” switch that covers them all. Before changing settings, identify whether the problem is a failed lookup, a result that doesn’t suit the chosen outbound, or routing that can’t see the domain. You can only tell whether to change the system, client, or application once you know where the query originates.

Start with Basic Resolution, Then Add Domain-Specific Resolvers

Start with an easy-to-observe, conventional DNS setup. Confirm that both server domains and ordinary websites resolve before adding domain-specific resolvers. This example shows only the core DNS section: queries for specified domains go to one resolver first, while other queries can use another. It doesn’t automatically send DNS queries through a proxy or control system DNS for every application. Before using it, confirm that the resolvers are reachable on your current network and appropriate for your environment.

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

A server with domains prioritizes matching queries for the specified domains, but fallback behavior, failure handling, and result filtering also depend on the core and other fields. Don’t assume a priority rule enforces strict isolation. If you need to prevent fallback, check which fallback options your core supports and verify the behavior in its logs. A client’s “remote DNS” label isn’t a universal JSON field shared by every core.

Routing Resolution vs. Outbound Resolution

Routing-level domainStrategy controls whether domains are resolved to check IP rules. The same field in a direct outbound affects how direct destinations are resolved and dialed. These fields live in different places and do different jobs. For example, routing with IPIfNonMatch can resolve a destination after domain rules fail, then try IP rules; it doesn’t mean all connections use a particular remote resolver. After changing the strategy, check both rule matches and whether DNS queries have increased.

Pay special attention to resolving the proxy server’s own domain during startup. If reaching a DNS service requires the proxy, while establishing the proxy connection depends on that same DNS service, the setup has a circular dependency. Give the server domain an independent resolution path, or use a clearly sourced and maintained server address configuration. Don’t rely indefinitely on a temporary resolved address instead of managing the domain; a server address change can break the connection without any apparent configuration change.

Caching, Dual Stack, and Application-Specific DNS

After a DNS change, browsers, operating systems, and the core may still have old results cached, and existing connections won’t be resolved again. For a reliable test, close existing connections in the target application, clear caches using the system’s supported method if needed, and make a new request. Check IPv4 and IPv6 results separately, too. If resolution returns an IPv6 address but the outbound or current network can’t connect over IPv6, the symptom may be a long delay rather than an explicit DNS error.

An application’s built-in encrypted DNS may bypass the system resolver, so changing system DNS alone won’t produce the expected result. In a TUN setup, don’t assume every encrypted query can be identified through port rules. Temporarily disable application-specific resolution in a controlled test to verify the system path, then decide whether it needs to be supported. In environments with enterprise domains, local device names, or split DNS, preserve the existing resolver path so internal names aren’t sent to a public resolver that can’t resolve them.

4. TUN Mode and System Traffic Capture

TUN uses a virtual network interface to capture system IP traffic, which is useful for applications that can’t easily be configured to use an HTTP or SOCKS proxy. The difference from a system proxy is the layer where traffic enters—not a guarantee that all traffic will use the proxy. Connections entering TUN still pass through routing rules, so local, direct, and blocked traffic can all remain in place. A client’s TUN feature may also rely on an additional networking component; that doesn’t mean the current Xray or V2Fly configuration natively has the same TUN fields.

Establish a Baseline Before Capturing Traffic

Before enabling TUN, verify in system proxy mode that the server connects, common domains resolve, and basic routing behaves as expected. Then close other tools that may capture system traffic, and note the current network adapters, default gateway, and DNS state before enabling TUN. For the first test, enable only the essential capture options; don’t also add process rules, complex exclusions, and FakeDNS. This makes it easier to tell whether a problem comes from the changed entry point or an existing outbound configuration.

Handle permission errors separately from network errors. Desktop systems may require administrator approval, permission to create a virtual interface, or authorization for a helper component. Android clients generally use the system VPN permission to capture app traffic. Granting permission only allows the system to create an entry point; it doesn’t confirm that traffic can reach a remote server. If startup fails, check permissions, component files, and interface conflicts first. Don’t keep changing server protocols before the entry point has even been created.

Prevent Loops and Keep Local Network Access

The proxy component’s own outbound connections must not re-enter the same TUN entry point, or they can form a loop that causes repeated connection attempts and rapidly repeating logs. Clients usually handle automatic routing and exclude their own traffic, but custom network settings can disrupt those defaults. If enabling TUN cuts off all network access, disable it to restore connectivity, then check automatic routing, interface binding, and exclusions. Don’t reinstall several network components at once while offline.

Local network access also involves private addresses, multicast discovery, broadcasts, and local DNS. Adding direct routes for private addresses can help with ordinary address-based access, but it doesn’t guarantee that every device discovery protocol works through traffic capture. Test with a known local gateway or device address first, then check name resolution and automatic discovery. If the address works but the name doesn’t, check DNS first. If only automatic discovery fails, investigate multicast and the application’s discovery mechanism.

Test DNS and UDP in Stages

TUN can receive UDP traffic, but that doesn’t mean the selected server or protocol path can carry it. Test regular web access, UDP-dependent applications, and local network access separately; opening one page in a browser isn’t a complete test. If a specific application fails, check whether it uses its own resolver, a special destination port, or another network interface. Then decide whether to adjust the capture scope, DNS path, or use an existing outbound that supports what it needs.

When testing is complete, turn off TUN first, then confirm that virtual routes and DNS have been restored, and finally check whether the system proxy is still in the desired state. If the network doesn’t recover after an unexpected exit, reopen the client and disable traffic capture normally before checking system settings. For macOS installation approval and network permissions, see Permission Setup. Installers and platform downloads are in the Download Center; this chapter doesn’t provide additional component downloads.

5. FakeDNS and Domain Mapping

FakeDNS returns virtual addresses instead of real DNS results and keeps an internal mapping between each domain and its virtual address. The application connects to the virtual address, then the capture component or core uses the mapping to recover the domain. The goal is to preserve domain information so routing and subsequent resolution can work together—not to provide real addresses that can be reached directly. If a query goes through FakeDNS but the connection bypasses the corresponding capture path, the application may try to connect to the virtual address directly and fail.

DNS Queries and Connections Must Use the Same Mapping Path

Before enabling FakeDNS, confirm that both the core and client fully support it, including DNS responses, capture of the address pool, and domain recovery. A setting that can be saved isn’t proof that the entire path works. This snippet shows the relationship between the address pool and DNS server for cores that support this structure. It still needs to be integrated with an existing configuration and paired with an entry point, routing, and outbound. The example address pool uses a range reserved for benchmarking; it isn’t a real public destination.

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

ipPool sets the range of virtual addresses that can be assigned, and poolSize sets the pool capacity. Coordinate the address pool with real networks and ranges used by other traffic-capture tools; don’t pick a subnet just because it looks unusual. A larger pool isn’t automatically better—choose a size that fits the core implementation and your needs. After changing the pool, applications won’t refresh cached addresses automatically; resolve the domain again and establish a new connection.

The Entry Point Must Recover the Domain, Not Just Return a Virtual Address

On entry points that support FakeDNS recovery, a common approach is to enable the corresponding sniffing capability. This is still a snippet inside an entry object; don’t replace the entire inbounds array with it. fakedns attempts to recover domains from the mapping, while HTTP and TLS sniffing can identify some application-layer traffic. Check what the current core actually supports and whether additional entry point settings are needed; graphical clients may generate the configuration differently.

{
  "sniffing": {
    "enabled": true,
    "destOverride": ["http", "tls", "fakedns"]
  }
}

Some configurations also provide routeOnly, which uses sniffed results for routing without rewriting the actual connection destination. Don’t apply this option indiscriminately to FakeDNS: if the final destination remains a virtual address, the connection can’t be made to the real domain. First confirm that domain recovery and destination handling are complete, then consider sniffing for routing only. Combining sniffing options from unrelated guides is usually harder to troubleshoot than keeping the client’s defaults.

Check for Stale Mappings and Bypassed Queries

After disabling FakeDNS, an application may keep using a cached virtual address. Close its existing connections, clear the relevant DNS cache if necessary, and test again; restarting the core alone may not clear browser or system results. Conversely, if an application continues using a real address after FakeDNS is enabled, that doesn’t immediately mean FakeDNS is broken. Make a new query that you know uses the intended DNS path, then check the returned address and subsequent domain recovery logs.

Application-specific DNS, connections to fixed IPs, and local network names can all create edge cases. A fixed IP has no domain to recover; internal names need a resolver that knows how to answer them. Start by limiting FakeDNS to a controlled test scope, then expand it only after websites, local network access, and essential applications all work. If the problem appears only after enabling it, restore conventional DNS and the original capture method first, and compare the logs. Don’t also expand the address pool and add several fallback resolvers at the same time.

6. Managing Multiple Subscriptions and Update Behavior

The goal of managing multiple subscriptions is to keep sources, updates, and usage traceable—not to combine everything into one confusing list. Give each subscription its own name, update policy, and purpose, and keep test sources separate from everyday ones. Subscriptions provide connection parameters; don’t assume they control every application setting. Before importing, check whether the content is a server list or a full configuration that includes routing, DNS, and other settings. Don’t treat a broader configuration change as a routine server update.

Distinguish Source Downloads from Applying Configuration

An update can be broken into three stages: fetching remote content, parsing it into client entries, and applying a selected entry to the current connection. Success at one stage doesn’t mean the next one has finished. After an update completes, check the changed entries and current selection, then establish a new connection. Some applications keep existing sessions open even after loading new settings, so an already-open page can’t tell you whether the switch worked. Check the actual outbound and runtime logs for a new connection.

Check the network path used to update subscriptions separately. Fetching a subscription through the current proxy may help if direct access is unavailable, but it can create a “the update depends on the broken server” problem when that subscription is meant to fix the server. Keep a working update method or independent fallback configuration, and note which sources need the proxy. Don’t keep toggling a proxy-for-updates option without knowing what it does. First identify whether the failure is at the connection, authorization, certificate, or DNS stage.

Reduce Uncertainty from Automatic Updates

Automatic updates suit reliable sources, but schedule them for a time when you can check the result rather than starting with frequent updates. Update manually several times first to confirm the source format is stable and the selected server remains available. Subscription URLs with time-sensitive credentials can expire, too. Frequent retries won’t fix an authorization problem; they can fill the logs with repeated errors and hide the original cause.

If the client can keep existing entries or remove entries that are no longer valid during an update, understand the trade-off. Keeping them makes temporary rollback easier, but the list may accumulate unusable configurations. Removing them keeps the list in sync with the source but may immediately remove the entry you’re using. Check for a separate backup before choosing a cleanup policy. Don’t assume a future subscription update will preserve temporary manual changes; copy any such server into a clearly labeled standalone configuration if needed.

Merging, Deduplication, and Source Trust

Deduplicate by comparing actual connection settings, not just remarks. The same server address may have different ports, transport paths, or security settings, so it can’t necessarily be merged. Different names may also refer to the same connection. Clean up one source at a time, then check for duplicates across sources while keeping source identifiers. If the client doesn’t explain which fields its automatic deduplication uses, test it in a dedicated group and inspect the results before applying irreversible cleanup to everyday entries.

Sources may also include remote resource URLs or unfamiliar extension fields. Import only what you need, and pause to verify the purpose of any step that asks to overwrite system settings, change all routing, or grant extra permissions. Don’t submit subscription URLs to unknown online conversion services: they may contain access credentials, and conversion can change the meaning of the configuration. For an incompatible format, first check which client formats the provider supports, then consider a local, reviewable conversion method.

Preserve the Configuration Relationships When Moving Devices—Not Every Runtime Setting

When moving to another device, record group names, subscription purposes, essential rules, and manual settings, then use the client’s supported export and import features. Don’t copy desktop paths, ports, or network permissions directly to Android. Device-specific TUN settings need to be checked again, too. After importing, update each source separately, restore one basic connection, and then add advanced rules. This helps distinguish source problems from platform differences instead of leaving you with a fault involving several changes at once.

7. Custom Outbounds and Tag References

Outbounds define how connections leave the core, and routing rules reference them by tag. Proxy, direct, and block aren’t just three fixed buttons—they’re configuration objects and the relationships between them. Before customizing, check whether the client lets you edit a complete configuration, partial outbounds, or graphical routing fields; each is merged differently. Editing a temporary runtime file may be overwritten when you switch servers or restart, so it isn’t a reliable source for persistent settings.

Start with Traceable Tag References

Give every referenced outbound a clear, unique tag, and make sure each routing rule’s outboundTag matches it exactly. Differences in case, spacing, or spelling can break a reference. This example shows two complete basic outbound objects, but it isn’t a replacement for the client’s entire outbound array; replacing it would also remove the existing proxy outbound. Check the current structure for objects with the same tags to avoid duplicate definitions.

{
  "outbounds": [
    {
      "tag": "direct",
      "protocol": "freedom",
      "settings": {}
    },
    {
      "tag": "block",
      "protocol": "blackhole",
      "settings": {}
    }
  ]
}

freedom connects directly to the destination using the local network; blackhole discards matching connections. Direct access doesn’t guarantee the destination is reachable—it still depends on local DNS, the address family, the gateway, and the firewall. Blocking won’t necessarily show a consistent error; the application may report a connection failure or retry. Check actual outbound logs during testing instead of inferring whether a rule worked from a browser message.

Check the Default Outbound and Explicit Routes Together

When no routing rule matches, a standard core configuration usually uses the first outbound; a client may also generate a fallback rule. Changing outbound order is therefore a behavioral change, not just list cleanup. Used on its own, the snippet above puts direct first, which does not mean “proxy by default.” If the proxy should be the default, check the position of the existing proxy outbound or the client’s generated rules. Don’t assume the selected server in the interface overrides the order in the complete configuration.

To send a particular type of traffic through a separate outbound, first confirm that the object exists in the final configuration, then add the most specific routing condition. Servers in a subscription group don’t automatically become individually referenceable outbounds, and the currently selected server may always use a fixed tag. Multiple outbounds require client support for generating them or a custom configuration that can run as a whole. Naming a server with a tag in its remark doesn’t create an outbound.

Proxy Chains Require an Explicit Dialing Relationship

Multi-hop forwarding and choosing among multiple outbounds are different things. With multiple outbounds, different connections can take different paths; a proxy chain sends the same connection through several stages in sequence. Before configuring chained dialing, check the fields supported by the current core, the reachability of every server, and the risk of a loop. Don’t copy a dialing field from one core to another without confirming that it supports the same syntax. Test each outbound separately before chaining them to pinpoint which stage fails.

When binding an outbound to an interface or source address, account for network changes. A fixed wireless interface may stop working after switching to Ethernet, and a fixed source address may no longer belong to the device after its address is renewed. These fields suit environments with predictable network conditions; they aren’t a general fix for every connection problem. For ordinary direct connections, letting the system choose a route is easier to maintain. If you need multiple adapters, document how to check and recover from interface changes.

Inspect the Generated Configuration Before Relying on It

After saving custom settings, run the client’s configuration check and inspect the startup logs. Verify that tags are unique, references resolve, the default outbound is correct, and custom objects were merged rather than overwritten. If the interface settings don’t match runtime behavior, troubleshoot using the configuration that actually took effect. For differences between projects and cores, see How Project V, V2Fly, and Xray Are Related. Check which settings are supported before deciding whether to switch cores.

8. Validation, Logs, and Rollback

Advanced configuration needs a repeatable validation process. Change one thing at a time to solve a clearly defined problem, and write down the expected result before editing—for example, “this business domain uses the specified outbound” or “local network addresses remain direct.” Don’t update subscriptions, switch cores, enable TUN, and change DNS all at once, then judge the result from one website. The more changes you bundle together, the harder it is to identify the cause; you may end up reverting everything and losing useful test results.

Build a Minimal Test Matrix

Prepare at least four checks: access to an ordinary domain, a known direct destination, a connection that needs the proxy, and a local network resource. Choose stable targets you’re authorized to access, and record the expected entry point and outbound for each. Add specific tests for UDP, dual stack, or particular applications when relevant. Test with new connections rather than repeatedly refreshing a page that may reuse an old session; connection pools and browser caches can make a configuration change look ineffective.

Read Logs by Connection Stage

First check whether the core started successfully. If startup didn’t finish, there’s no reason to test remote access yet. Next, check whether the local entry point received the connection, then inspect the destination domain or address, rule selection, and outbound error. A port conflict is a local listening issue; a lookup failure is a DNS issue; a timeout may indicate the remote destination isn’t reachable; and a certificate error usually occurs during the secure handshake. These problems can’t all be fixed by “trying another server.”

Set the log level to what troubleshooting requires, then restore the normal level when you’re done instead of leaving verbose logging enabled. Before sharing logs, redact subscription URLs, user identifiers, authentication fields, and unnecessary internal domains, and include only the relevant lines around the error. Timing matters: note which log lines correspond to a manual test so background application requests aren’t mistaken for the connection you’re investigating. For more detail on common errors, see How to Read Runtime Logs.

Roll Back in Reverse Order of Recent Changes

Roll back the most recent change first, then retest the baseline. If FakeDNS caused the issue, restore conventional DNS and clear stale mapped results. If TUN caused it, stop traffic capture and check that system routes and DNS are restored. If a custom outbound caused it, restore the original tags and default outbound order. Turning off one interface switch doesn’t guarantee that all related state has been cleared. Test a new connection after each rollback step to avoid being misled by cached data.

Keep a verified configuration and a short set of notes long-term. Record the client, actual core, entry method, required rule resources, and any special permissions. Your backup doesn’t need every temporary log, but it should preserve the essential configuration relationships. After a software update, check that the basic connection works before testing custom settings. If the application crashes at startup, see Fix Startup Crashes and Check Directory Permissions rather than mistaking an application startup issue for a routing problem.

Keep a Reference Record of Working Settings

After validation, note why each non-default setting exists in a sentence—for example, “this domain must use internal DNS” or “this service uses a separate outbound.” Describe the need, not just the field value, so you can decide whether the setting is still necessary when the environment changes. After subscription, network, or core changes, recheck the items directly affected. There’s no need to redo unrelated checks; keeping maintenance focused makes it manageable.

If you still can’t isolate the issue, narrow it down to one connection, one set of rules, and one outbound. Prepare a redacted configuration snippet and its corresponding logs, then consult the Troubleshooting FAQs. To reestablish the basic workflow, return to Getting Started. To change the installation platform or device architecture, visit the Download Center. The goal of this guide is to make every configuration change explainable, verifiable, and easy to roll back.