Advanced Setup Guide

Subscription groups and server filters

Group structure: source, purpose, and traceability

Subscription groups answer “where did these servers come from?” They do not replace routing policies. Create a separate group for each configuration source, then note its purpose—for example, everyday use, temporary testing, or core compatibility checks. Group names help you organize and select servers; they do not determine which route an app uses. To choose an outbound by domain or address, configure routing instead.

Where to set it up: In v2rayN's subscription group settings, add a group, give it a recognizable name, and enter the subscription URL in the group's address field. Save and update that group only. First confirm that parsing succeeds, then check that the servers appear in the expected group. Menu names may change between versions. Look for the group name, subscription URL, and update controls rather than relying on screenshot coordinates.

Protect your information: Subscription URLs often contain account-identifying paths or parameters and should be treated as credentials. Don't copy the full URL into group notes, and redact sensitive parts from troubleshooting screenshots. Before sharing an exported configuration, check server addresses, user identifiers, and authentication fields. Removing the subscription link alone does not make exported server configurations safe to share.

Filtering rules: know what you're matching

Server filters: First check whether the filter applies to content returned by a subscription, imported servers, or just the list currently shown in the interface. A search box usually changes what's visible without deleting configurations; a subscription filter can affect the next import. Confusing the two can make servers look missing when a display filter is still active or an update filtered them out.

Matching syntax: Filter fields don't always support regular expressions, and case-sensitivity rules may vary. Test with a short term you know exists before combining conditions. If the field supports regex, Work|Test can match either term in a note. In a plain-text field, the same input may be treated as one literal string and return no results.

Tighten conditions gradually: Start with a broad match, confirm the configurations you need appear, then add exclusions one at a time. Avoid complex negative matches up front: providers can rename server notes, and parentheses, spaces, and region abbreviations may not be stable. Check the configuration and core logs to confirm protocol support; a keyword in a server note isn't enough.

Verify updates: distinguish download errors from parsing errors

Update path: A subscription update is a network request made by the client; it doesn't test whether your browser can open a webpage. If a direct request can't retrieve the content, consider a setting such as “use proxy for subscription updates”—but only if you already have a working outbound. Enabling proxy updates before the first connection is established can create a dependency loop, so get a basic connection working first.

Parsing results: After an update reports success, check more than the total number of entries. Verify protocol, address, port, and group assignment. The response might be an expired-subscription notice or an authentication page: a successful network request doesn't guarantee valid subscription data. If the logs show a format error, check that the URL was copied in full and hasn't expired, then confirm the client supports the subscription format.

Local changes: Manually edited subscription servers may be replaced the next time the subscription updates. For changes you need to keep, use a separate configuration supported by the client or copy the servers into a manually managed group, and record how they differ from the source. Avoid editing the same configuration in multiple groups; it makes it hard to tell which copy is active.

Recovery steps: If servers suddenly disappear, clear the list search first, disable any newly added filters, and then update only the affected group. Compare the error logs and original configuration format before deleting and rebuilding all subscriptions. For more specific update failures, see v2rayN subscription update failures and automatic update settings. For update schedules across multiple sources, continue to Manage multiple subscriptions.

Routing rules in practice

Request path: inbound, matching, and outbound

How routing works: An app's request enters through an inbound. The core checks the destination domain, address, port, and other conditions against routing rules, then sends the connection to the selected outbound. System proxy or TUN determines whether a request enters this path at all; routing only handles traffic already passed to the core. If an app isn't using the local proxy, changing domain rules repeatedly usually won't affect its connections.

Rule order: Rules are generally checked in order, and the first match selects the outbound. Put specific exceptions before broader rules. Conditions within one rule object usually all need to match, while entries within the same condition array usually match if any one applies. Combining domain and address conditions in one object can therefore produce a narrower match than expected.

Protocol boundaries: VMess, VLESS, and Trojan are connection protocols. REALITY is a transport-security configuration; none of these replaces routing. Importing a server only means the client recognized its configuration format—it doesn't mean every available core supports every field. Choose a protocol based on the server settings, then confirm which core is actually running. Don't change a server's protocol just to match a routing rule.

Rule snippets: merge carefully and check tags

Example: This partial Xray routing snippet sends private addresses and the mainland China domain set to the outbound named direct. Before using it, confirm that the outbound exists and that the required rule data files are available. The snippet doesn't define a proxy outbound or specify where unmatched requests go, so it doesn't mean all remaining traffic will use a proxy.

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

Outbound tags: outboundTag references an outbound identifier, not an arbitrary display name. Clients may generate different tags, so check the active configuration before referring to one. If validation passes but runtime logs report a missing outbound, check spelling and capitalization first. If the client changes the tag when regenerating its configuration, use a supported routing editor instead.

Domain strategy: AsIs matches using existing domain information and doesn't resolve addresses just to apply IP rules. IPIfNonMatch attempts resolution after domain matching fails, then checks address rules. IPOnDemand triggers resolution when a rule needs address information. The latter strategies add DNS dependencies; resolving more aggressively doesn't automatically make matching more accurate.

Verify rule matches: use logs to separate routing from connection issues

What the core can see: If an app sends a domain through SOCKS, the core can match it directly. If the app resolves the name itself and sends only an address, the core has different information to work with. Traffic sniffing can recover domains from some protocols, but not every connection can be identified. If logs show only an address, first check what information the request carries, then decide whether sniffing, DNS changes, or TUN may help.

How to verify: Choose a specific test request, minimize background app traffic, and check the connection's inbound, destination, and outbound tag. If the request uses the correct outbound but still fails, investigate that outbound's connectivity and server settings. If it uses the wrong one, check rule order, domain visibility, and whether the address set includes the destination. A webpage loading quickly is not proof that the expected routing rule matched.

Fallback behavior: In a custom configuration, unmatched traffic usually goes to the default outbound, which can depend on outbound list order. GUI clients may also generate their own fallback rules. Document this behavior before adding or reordering outbounds. Moving a direct outbound to the top could send previously proxied unmatched requests directly, with a much broader impact than adding one rule.

Rollback: Add one type of condition at a time, and keep a record of the previous rule order and current outbound. If something breaks, disable the new rule first, then restart the core or create a new test connection; existing connections may not be matched again. For rule-set terminology, see the glossary. If a connection still fails after matching the correct rule, follow the server timeout troubleshooting steps.

DNS configuration

Resolution layers: find out who's making the query

The resolution path: The system resolver, a browser's secure DNS, the client's built-in DNS, and server-side resolution may all be involved. Changing client DNS won't necessarily affect queries sent directly by a browser. Enabling the system proxy doesn't mean every system query enters the core, either. Before tuning DNS, map the actual path: check whether the app submits a domain or an address, and identify which layer chooses the resolver.

Classify the issue: A domain that won't resolve, a resolved address that can't be reached, slow lookups, and traffic sent to the wrong route are different problems. If an address is returned but the connection times out, changing resolvers may not help. If a domain returns different addresses on different networks, that isn't automatically a problem—distributed services may return results based on the request's location. Check connection logs and the destination network.

Avoid circular dependencies: DNS tuning isn't about piling on more public resolvers; it's about reducing unnecessary dependencies. The core may need to resolve a server hostname before it can connect, while your DNS setup may require that same connection to be available. Keep a basic resolution path that works on the current network, then adjust lookups for other domains gradually.

Field guide: address families and domain-based queries

Basic example: This partial Xray built-in DNS configuration illustrates resolver selection and address-family handling. The addresses are examples of configuration structure only; check that they are reachable on your network and suit your needs before using them. This snippet doesn't redirect system DNS into the core or define which outbound carries DNS traffic, so it can't handle DNS for an entire device by itself.

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

Query scope: domains in a server object specifies which domains should prefer that server, but it doesn't guarantee that other servers will never receive related queries. Fallback behavior, expected-address conditions, and core implementation can all affect subsequent attempts. If you need to strictly control where queries go, check the fallback fields supported by your core and verify behavior through logs or local network monitoring.

Address-family selection: If your network has working dual-stack connectivity, don't permanently restrict an address family just to reduce log noise. Temporarily using UseIPv4 can help determine whether the other address family is involved. If that fixes the issue, check system routes, outbound support, and server listeners. Built-in DNS settings only affect the relevant lookups; they don't change addresses supplied directly by apps.

Caching and fallback: make test results easy to interpret

Cache interference: After changing resolvers, the system, browser, and client may all keep using cached results. Close existing connections first, then flush the caches for the components involved or restart the app if needed; there's no reason to reboot the whole device every time. Record the addresses returned and outbound tags before and after the change so you can tell whether the new settings took effect or an old, still-reachable address was reused.

Fallback trade-offs: A backup resolver can help if one path fails, but it also makes resolution behavior more complex. If every resolver times out, the issue may be the query's outbound path or the network rather than the domain. If only certain domains fail, check domain-set matching and returned addresses before making a global DNS change that could disrupt other apps.

Local network: Printers, LAN hosts, and internal services may rely on router DNS or a local search domain. Sending every query to a public resolver can break those names. Keep a local resolution path for known internal domains and confirm their addresses still route directly. Adding a DNS record won't help if its private address is sent to a remote outbound.

Validate in stages: First confirm that an ordinary domain resolves and connects in system proxy mode. Then enable TUN, and evaluate FakeDNS last. Keep each change reversible and don't change the address family, resolver, and routing policy at the same time. For certificate name mismatches, see TLS handshakes and how to check SNI; don't disable certificate verification to mask DNS or configuration errors.

TUN mode

Traffic capture: a virtual adapter isn't an outbound

What TUN does: A virtual network adapter passes traffic selected by system routes to a user-space process, making it useful for apps that ignore the system proxy. TUN changes how traffic enters the client; it won't fix server authentication, an unreachable server, or incorrect routing rules. You'll still need a working outbound, a valid DNS path, and system routes that don't repeatedly capture the client's own connections.

How the modes differ: System proxy relies on apps honoring the OS proxy settings. TUN receives packets closer to the network layer. They can coexist in some environments, but when troubleshooting for the first time, test one capture method at a time. If a browser works but another app doesn't, that app may simply ignore the system proxy; this doesn't mean every server or core needs replacing.

Core responsibilities: Desktop TUN may rely on a separate component working alongside the proxy core, and the actual combination determines its configuration fields and permissions. Don't paste an online configuration containing a tun field into just any Xray configuration. Use v2rayN's TUN settings where possible, then check startup logs to confirm the relevant components are running.

Enable TUN: from a baseline to system routes

Connection baseline: Before enabling TUN, test a known-working server in system proxy mode and note the selected server, routing mode, and DNS settings. Exit other network tools that may change routes or create virtual adapters so they don't compete for the default route. Leave FakeDNS off for now; first test ordinary DNS and TUN separately so the results are clear.

Permissions: On Windows, creating an adapter or adding routes may require elevated permissions. macOS and Linux may also require system authorization or service permissions; follow the client prompts. If the setting switches back off immediately, check for a permission denial, component startup failure, or adapter creation error instead of repeatedly toggling it. After granting permission, confirm that the routes were actually created.

Android behavior: v2rayNG and v2flyNG typically capture Android traffic through the system VPN interface, which requires permission on first use. This is implemented differently from desktop TUN, so don't copy desktop settings field by field. Other apps using the same system interface may conflict; before switching, check which client currently handles traffic capture.

Verify traffic capture: First test an app that didn't follow the system proxy, then check the client's connection log for the expected destination. Next, confirm that regular websites, LAN services, and subscription updates still work. A visible adapter or connected icon isn't enough: DNS routing, outbound routing, and app connectivity can each fail even after the adapter is created successfully.

Common conflicts: bypasses, loops, and packet size

Bypass the client itself: The proxy component's connections to its server need a proper bypass path; otherwise, they can re-enter the virtual adapter and form a loop. The client usually creates the necessary routes, but manually changing the default route, interface binding, or custom outbounds can break them. If logs show repeated attempts to establish the same connections and everything fails, disable recent changes and restore the client's default capture settings first.

LAN access: If remote desktop, printers, or internal addresses stop working, check whether the private subnet is being captured and whether its route points to the direct outbound. Internal resources on some networks use non-standard address ranges, so a rule for standard private ranges may not be enough. Add the narrowest exception that covers the actual subnet; don't bypass unrelated traffic just to reach one resource.

Packet size: If some sites load but large downloads or long-lived connections stall, MTU may be worth checking—but don't change it as a first step. Rule out DNS, protocol, and server issues, then test one change at a time through the client's supported settings and save the original value. Encapsulation overhead varies between networks, so there's no single MTU that works best on every device and link.

Check stability: Re-test after waking from sleep, changing Wi-Fi networks, or switching the default adapter; old interfaces and routes may no longer work. Add domain routing or FakeDNS only after basic traffic capture is stable. For common terminology, see the FAQ. If you haven't established a first connection yet, return to the Getting Started guide rather than changing several unverified layers at once.

FakeDNS

How mapping works: preserve domains with synthetic addresses

How FakeDNS works: Instead of returning a destination server's real address, FakeDNS assigns the domain a synthetic address. When the app connects to it, a companion component looks up the original domain in the mapping table and passes it to routing or the selected outbound. This keeps domain information available for traffic that would otherwise provide only an address; the synthetic address isn't a real server on the remote network.

Requirements: The app's DNS query must use the designated FakeDNS path, and the subsequent connection must reach a component that knows the mapping. Either half alone is insufficient. If the system returns a synthetic address and sends it directly over a regular network, it usually can't reach the real destination. If the connection is captured but the query bypasses the mapping service, there's no mapping to recover.

Routing benefits: When domain rules are comprehensive and apps resolve names before connecting, FakeDNS can help maintain consistent domain-based routing. It can't fix incorrect rule order or replace every use of regular DNS. Apps that connect directly to fixed addresses or use their own encrypted DNS path may still bypass the mapping.

Configuration: address pool, DNS path, and sniffing

Configuration example: This snippet shows how an Xray address pool can be linked to its DNS service. 198.18.0.0/15 is reserved for benchmarking; it isn't the real address of a remote service. Before configuring it, check for conflicts with your existing network plan, other virtual adapters, or test environments. Resolve any overlap first rather than enabling the configuration as-is.

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

Inbound setup: The inbound receiving these connections must also be able to recover the mapping. The snippet below shows only sniffing fields to merge into the relevant inbound object; it doesn't define an inbound protocol, listen address, or port. A GUI client may already generate equivalent settings, so check the active configuration before adding duplicates. Mapping tables managed by different capture components aren't shared just by copying fields.

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

Core differences: These settings explain how the relevant Xray options work together; don't assume they can be transferred unchanged to v2flyNG or another TUN component. If your client offers a FakeDNS switch, use that interface where possible and check which core it runs. Without clear compatibility information, keeping ordinary DNS is easier to maintain than combining fields from different implementations.

Compatibility and returning to regular DNS

App compatibility: Apps that display real resolved addresses, check address ownership, discover LAN devices, or pass resolved addresses to another process may not work well with system-wide mapping. Some apps also cache synthetic addresses and keep trying to use them after the client stops. If one app fails, first check whether its DNS queries and connections follow the same processing path, then decide how narrowly to exclude it.

Cache lifetime: A mismatch between the mapping table's lifetime and an app's cache is a common cause of intermittent failures after a restart. The core may restart without its old mappings while the app still has a previously returned address. Changing servers may not help. Close old connections, clear the relevant app's DNS cache, and make a fresh query to create a new mapping.

How to verify: After enabling FakeDNS, a system or app query for a target domain should return an address from the mapping pool. The client should then associate the connection with the original domain and select the expected outbound. Seeing a reserved address alone doesn't prove the setup is complete: confirm the connection works, LAN access still works, and traffic using real addresses remains subject to the existing rules.

Disable in the right order: Turn off the relevant FakeDNS settings and restore regular resolvers first. Then flush system and app caches and close connections still using old mappings. Turning off only the virtual adapter while an app retains a synthetic address can leave it unable to connect. After restoring service, check DNS responses to make sure pool addresses are no longer treated as real remote destinations.

When to use it: Consider FakeDNS only after ordinary DNS and TUN are stable and you've confirmed that domain information is being lost. It won't help with expired subscriptions, server timeouts, or authentication failures. For more on how mapping works and when to enable it, see FakeDNS explained and when to enable it in v2rayN. Keep the configuration you used before enabling it for comparison.

Manage multiple subscriptions

Maintenance model: separate sources and use consistent names

Keep sources separate: Maintain a clear update boundary for each subscription by putting every source in its own group and storing manually managed configurations separately. Don't copy every server into one large group with no traceable source just to make the list look tidy. Clear source attribution narrows down update failures, format changes, and overwritten settings, and makes it easier to disable only the affected group.

Naming conventions: Include a source abbreviation, purpose, and maintenance method in the group name or notes, but never include account details or the full subscription URL. Keep provider-supplied server notes when useful and add a separate local identifier if needed. Whether manual renames survive an update depends on the client. Review filters that rely on server notes regularly; those notes aren't permanent identifiers.

Selection boundaries: Adding subscriptions doesn't automatically enable load balancing, failover, or app-based routing. A standard server list usually still has one active selection; multiple sources simply provide more options. To send different traffic through different outbounds, configure the routing-to-outbound relationships explicitly. Group order and list sorting don't set the core's outbound priority.

Update schedules: reduce cascading failures

Test manually: Import and update each new source on its own, check protocol and core support, and make a real connection before adding it to a regular update schedule. If you update every source at once, a failed connection makes it hard to tell whether the new subscription changed the configuration or an existing source changed too, increasing troubleshooting time.

Automatic intervals: Set update frequency based on how often the source changes and its service requirements; more frequent updates aren't necessarily more reliable. Excess requests can waste resources or trigger provider limits. If the client supports separate schedules per group, set them as needed. If it offers only one interval, choose a sustainable schedule and keep manual updates available for urgent changes.

Proxy dependencies: Proxy-based updates can help when a source is unreachable directly, but don't make every source depend on one unverified outbound. If the active server fails, proxy-based updates may fail at the same time, making every subscription look broken. Check the update request's network path before checking subscription status, and retry an affected group through a known-working connection if needed.

Deduplication, migration, and backup scope

Deduplication: The same name doesn't mean the configurations are identical, and the same address doesn't guarantee matching authentication and transport settings. Before removing a duplicate, compare protocol, port, user ID, transport, and security fields. Automatic deduplication based on only some fields could remove configurations used for different connection methods. If the criteria aren't clear, test on a copy before changing the main group.

Moving between platforms: v2rayN, v2rayNG, and v2flyNG don't have identical subscription parsing, interface storage, or custom configuration support. During migration, separately verify that subscriptions parse, servers connect, and routing and DNS settings are recreated. Importing a server list doesn't mean desktop TUN, system proxy, or every custom rule has been carried over to a mobile client.

What to back up: Save the group structure, necessary subscription information, separate local configurations, and rule settings in a controlled location. Don't rely only on temporary generated core files; they may not include source information or update settings stored by the interface. Before restoring, check which client and configuration editor the backup belongs to so you don't overwrite a different setup with outdated fields.

Change log: For each substantial change, record only the relevant behavior—for example, a group now uses proxy updates, a filter was broadened, or a rule was moved up. Don't save sensitive URLs or paste credential-bearing configurations into public notes. During troubleshooting, knowing which layer changed most recently is usually more useful than keeping lots of undocumented configuration copies.

Retiring a source: Before disabling an unused source, check that it isn't referenced by the active server, an automatic update task, or a custom outbound. Disable the group first and confirm other sources still work before deleting it, so you don't leave broken tag references. For a temporary network issue, pause updates and keep the current configuration. For expired subscriptions and parsing issues, check the FAQ and the subscription groups section step by step.

Custom outbounds

Cores and ecosystem: know which configuration you're editing

Core relationships: Project V provides the ecosystem context for these proxy tools. V2Fly and Xray are separate core families. GUI clients handle subscriptions, the interface, and configuration generation; cores handle the actual connections. Similar-looking client interfaces don't mean they accept the same configuration. Even within one client, check protocol and field support again when switching cores.

Xray configurations: v2rayNG uses the Xray core, while v2flyNG is an alternative for V2Fly core configurations. For v2rayN, check which components are currently running. Before adding a custom outbound, confirm the active core in the client settings and startup logs. Open source means the code can be studied and maintained; it doesn't make configurations interchangeable across different implementations.

REALITY boundaries: REALITY uses connection-security parameters that must match the server's settings; it's not a local traffic-routing switch. Changing an outbound tag, adjusting a direct rule, or adding a local SOCKS outbound won't fix an incorrect server name, public key, or other connection parameter. Keep the original configuration and verify the basic connection before adding a custom chain.

Define outbounds: the minimum structure for direct and block

Definition: An outbound object's tag provides an identifier for routing rules, and protocol specifies its behavior. The example below shows a partial list of direct and block outbounds in Xray. The tags are examples and must match the routing snippet above. When merging this into an existing configuration, don't overwrite the proxy outbound or reorder the entire list before confirming the default behavior.

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

Default behavior: This snippet has no remote proxy outbound and no complete routing configuration. If you use it as the full outbound list, unmatched requests may default to the first direct outbound. A block outbound only takes effect when a rule selects it. After adding objects, check the generated configuration and default outbound, then test tag matching with one specific, narrowly scoped rule.

Local upstream: don't send connections back into themselves

Chained forwarding: Sometimes you may need to send certain requests to another controlled SOCKS service on the same machine. The snippet below defines an outbound named local-upstream that connects to a specified loopback port. Use it only if a compatible service is listening there and it isn't an inbound on the current client that receives the same traffic. Without an upstream service, this definition doesn't provide a working outbound.

{
  "tag": "local-upstream",
  "protocol": "socks",
  "settings": {
    "servers": [
      {
        "address": "127.0.0.1",
        "port": 10810
      }
    ]
  }
}

Check for loops: If a local inbound also listens on that address and port, forwarding may re-enter the same client and cause recursion or rapid failures. In TUN mode, make sure the upstream process's outbound connections aren't captured again and sent into another loop. Verify the upstream on its own, direct one test rule to it, and only then expand its scope. Don't route all traffic through it from the start.

Check capabilities: Confirm separately whether the SOCKS upstream supports authentication, domain forwarding, and UDP. A working webpage only proves that one connection path works; it doesn't prove every type of traffic can be forwarded. If only some apps fail, check their request types and the upstream's capabilities rather than copying more proxy fields and adding hard-to-observe layers.

Verify behavior: entry point, syntax, and persistence

Editing methods: Full custom configuration mode and interface-generated configuration mode usually have different maintenance responsibilities. The former may require you to define inbound, routing, DNS, and outbound settings yourself; the latter leaves some control with the client. Before saving, confirm which fields may be overwritten and whether custom settings survive a server switch. A field appearing in a temporary file doesn't prove the change will persist.

Classify errors: If startup fails immediately, check JSON commas, brackets, field types, and protocol names. If startup succeeds but no rule matches, check routing tags. If the rule matches but the connection fails, check listeners, authentication, and network reachability. You can temporarily increase the log level during a controlled test, then restore your usual setting. Don't publicly share full logs that include destination addresses or authentication details.

Keep changes maintainable: For each new outbound layer, document where its input comes from, where its output goes, and how to roll it back. If you can't answer all three, keep the client's default configuration. For installers and component options, check the client downloads page. For basic connection checks, return to the configuration guide. Once the connection is stable, add routing, DNS, and traffic-capture settings one layer at a time to avoid combining separate failures into one hard-to-reproduce problem.