V2Ray Advanced Configuration Guide

Subscription Groups & Server Filtering

Understand the difference between a subscription and a server selection

A subscription is a collection of server configurations provided by a remote source. A group is a local way to organize those configurations in the client. The selected server is the outbound actually used for a connection. These serve different purposes. Keep subscriptions from different sources in separate groups so you can identify which source failed to update and prevent similarly named servers from getting mixed together. When adding a subscription, give the group a clear name, enter the URL, and run an update manually. Then check the server count and protocol types in that group instead of relying only on a success message.

In v2rayN, subscription settings and the server list let you choose a group. Depending on the version, groups may appear in a sidebar, a top-level selector, or subscription settings. The workflow is the same: select a group, update it, filter the current list, and choose a server. If old entries still appear after an update, make sure you’re viewing the group you just updated. Switching groups usually changes the list view; it may not change the active server. Check the active selection separately—don’t assume the first visible item is the one currently in use.

Filtering changes the view, not the subscription

Filtering helps narrow down a long server list. For example, search by a region label in the server name, then identify the right entry by protocol or remarks. Names come from subscription providers and aren’t standardized, so a search term is only a local filter; it doesn’t confirm a server’s location, availability, or security. If entries disappear from view, clear the search and group filters before deciding they were removed during an update. Don’t use filtered results alone to decide what to delete, especially when multiple subscriptions use the same server names.

When comparing servers, use the same test method and network conditions for each one. A TCP connection test checks only part of the connection process. Loading a webpage also depends on the TLS handshake, DNS resolution, routing, and the destination service. Ranking servers by a single latency result can hide these differences. First read How V2Ray Latency Tests Compare, then test actual access through your shortlisted servers. Treat speed-test results as one factor, not a permanent performance rating to put in subscription remarks.

Keep local changes separate

Subscription providers control server addresses, ports, and credentials. Changes made directly to subscription-managed entries may be overwritten the next time the subscription updates. To make a temporary change, copy the server into a separate local entry and note why you changed it. Test the connection before deciding whether to keep the copy. It won’t update along with the remote subscription, so keep the original and test entry distinct. When troubleshooting transport settings, change one parameter at a time so you can tell local experiments apart from subscription changes.

If an update produces many entries with the same name, check whether the same source was added more than once before deleting anything. Two groups might point to the same subscription URL with different update settings, or the provider might reuse names. Compare each group’s source and its entries before taking action. Before removing a group, note which group contains the active server and choose a fallback. Removing displayed entries is not the same as removing a subscription source; read the client’s confirmation prompt carefully.

If the update request itself fails, first check that the subscription URL is still reachable. Then check whether the system proxy is sending the update traffic through an unavailable outbound. Some clients let you choose a separate connection method for subscription updates; pick one that works with your current network. If the error mentions DNS resolution or a connection timeout, troubleshoot the network path first. If the update succeeds but no servers appear, check whether the response uses a subscription format the client supports. Don’t keep clicking Update instead of reading the error. Once the source is reachable again, update it and verify the entries changed.

Managing Multiple Subscriptions and Update Scope

Organize subscriptions by purpose instead of combining every source

With multiple subscriptions, the main challenge isn’t the number of entries—it’s knowing where each configuration came from. Create groups by use case, device, or how the source is maintained, and give each group its own name and update settings. Choose names that distinguish the sources rather than calling everything “Default” or “Favorites.” Groups also help identify servers when two subscriptions use the same name. These instructions focus on desktop v2rayN. Android clients v2rayNG and v2flyNG maintain their own subscription records; don’t expect desktop groups to sync automatically to a mobile device.

After adding a source, update only that group first. Check that the expected number of entries appears, the server protocols are recognized, and your existing active server still works. Only then consider automatic updates. More frequent updates aren’t always better: they can add noise from failed requests and replace the list while you’re using it. If the source changes infrequently, manual updates and before-and-after checks are often easier to track.

Know what an update can change

A subscription update may add, change, or remove servers from that source. It doesn’t restore all client settings: check local routing, DNS, system proxy status, and other groups separately. Likewise, local routing changes aren’t written back to the subscription. If access stops working after an update, determine whether the server configuration changed or whether routing or DNS was also modified around the same time. Compare with a previously working local entry, then review the update log and active selection. This is often faster than reinstalling the client.

Some providers reuse server names even when the address or transport settings have changed. An unchanged name doesn’t prove the configuration is unchanged. If you’re running a complex routing test before an update, export the client settings or keep a change log without sensitive details. After the update, check the fields used by the active server. Full exports may contain subscription URLs or server credentials; store them securely and don’t post them publicly. When sharing troubleshooting details, include only relevant fields and remove credentials.

Handling Stale Sources and Duplicate Entries

If a source has been failing to update for a long time, troubleshoot it separately so it doesn’t hold up work on other sources. Check whether its URL is reachable and whether it returns any content before deciding to pause updates or remove the group. Pausing and deleting are different: pausing keeps the existing servers for comparison, while deleting may also clear the group’s local list. Before deletion, switch to another working server and check that automatic selection or routing rules don’t depend on the group. One network timeout doesn’t mean a subscription is permanently inactive.

Duplicate servers aren’t always mistakes. Entries with the same name may use different protocols, ports, or transports; entries with the same address may have different settings in different sources. Compare them individually rather than deleting by display name. If the source itself is duplicated, keep the one that updates reliably and has clear details, then remove the other from the update schedule. Clear list filters afterward, verify that the active server belongs to the retained group, and test access. This helps prevent a cleanup that succeeds but breaks your current connection.

A one-line change log is enough for each adjustment: note the group, action, active server, and test result. Don’t include server credentials. With multiple subscriptions, this helps answer two key questions: which update first caused the problem, and which group to use for rollback. If an issue only occurs on one device, compare subscription update times and local routing on both. The same source URL doesn’t guarantee that every client currently has the same entries.

Routing Rules in Practice: Matching and Outbound Order

First make sure traffic reaches the client

Routing rules decide which outbound handles a connection that has already reached the core. They can’t automatically proxy traffic that never enters the client. A browser using the system proxy typically sends requests to a local HTTP or SOCKS listener. Apps that ignore system proxy settings need their own proxy configuration or TUN capture. Before writing rules, confirm how the target app’s traffic enters the client. Otherwise, even a correct rule won’t have the intended effect. Matching also depends on domain visibility: a connection identified only by its destination IP can’t match a domain category that the client never sees.

Common routing modes are rule-based, proxy all, and direct all, but actual behavior depends on the configuration generated by the client. In rule-based mode, rules are usually checked from top to bottom; the first match selects an outbound, and unmatched connections use the default outbound. Check each rule’s conditions, order, outbound tag, and default path. A broad rule placed first can prevent more specific rules below it from ever matching. Start with a few easy-to-understand rules, then add them one at a time. Don’t import several unrelated rule sets all at once.

Start with clear matching conditions

The snippets below show how domain categories, specific domains, and LAN addresses serve different purposes. They illustrate configuration structure; in the client, make sure the proxy and direct outbound tags exist and that the core has the domain-category data required by the rules. geosite: matches category data; it isn’t a substring search. domain: and full: match differently. For a precise target, start by testing with full:.

{
  "routing": {
    "domainStrategy": "AsIs",
    "rules": [
      {
        "type": "field",
        "domain": ["full:example.com"],
        "outboundTag": "proxy"
      },
      {
        "type": "field",
        "domain": ["geosite:private"],
        "outboundTag": "direct"
      },
      {
        "type": "field",
        "ip": ["geoip:private"],
        "outboundTag": "direct"
      }
    ]
  }
}

AsIs tends to preserve the domain for domain-based rule matching. If you need to match on the resolved address, understand when the selected domain strategy triggers a lookup and whether the result is checked against IP rules. Changing this setting can affect both DNS request volume and routing matches, so don’t infer behavior for all traffic from one website. geoip:private covers private address ranges. If you can’t reach a LAN device, check this rule, the address returned by DNS, and whether the system sends LAN traffic through the client.

Use comparisons to find rule conflicts

If a new rule doesn’t work, first check whether an earlier rule already matches, then verify the outbound tag referenced by the rule. If a domain rule doesn’t match, check whether the request entered the client with its domain intact, whether the app resolved it first, and whether the required category data is available. If an IP rule doesn’t match, check the destination address and how the domain strategy handled it. The routing target in the logs is more useful than “the page won’t load.” Keep separate issues distinct: a DNS failure happens before the destination connection starts, while a proxy server connection failure may have nothing to do with the destination domain rule.

To test a specific site, place an exact-domain rule before broader category rules and note the original order. After testing, restore the order and test a direct destination, a proxied destination, and a LAN address separately. If only one category fails, check its rule or outbound. If all three fail, start with the traffic entry point and system proxy status. For more on the difference between connection tests and actual access, see V2Ray Latency Testing Explained. A successful speed test only confirms that the part of the route it tested worked; it doesn’t validate every routing path.

When updating rule sets, check what the categories mean and which entries they cover—not just whether the files loaded. A broad category can include domains you intended to handle separately. If access changes unexpectedly, review recently updated rules and their order before changing servers. Keeping an exact rule for a key destination is often easier to maintain than accumulating exceptions. The goal is to make every rule’s match and outbound clear, not to maximize the number of rules.

DNS Configuration and Resolution Paths

Track resolution, routing, and connections separately

DNS converts domain names into addresses, but a proxy client also has to decide which resolver to use, which outbound sends the query, and whether the result is used for routing. A site opening in your browser doesn’t mean every app uses the same DNS path. Apps may resolve names themselves or cache old results. When troubleshooting, note how the target app’s traffic enters the client, then check the client logs for the domain, resolution errors, and outbound selection. Don’t change system DNS, client DNS, and routing mode all at once before confirming the traffic entry point; it will be hard to tell which change affected the result.

In v2rayN, graphical settings may be transformed when the core configuration is generated. After saving DNS settings, make sure the core reloads and inspect the generated dns and routing sections. System proxy mode mainly handles apps that follow the proxy setting; system DNS queries don’t necessarily pass through the proxy listener. TUN captures more traffic, but an app’s own DNS behavior can still matter. So “system proxy enabled” doesn’t mean “the client handles all DNS.” To find the actual path, check whether the request reaches the core and which outbound the core selects.

Choose a specific resolver for each query

This simplified example shows the DNS fields in an Xray core configuration, including a fallback resolver and rules for specific domains. The example addresses only illustrate how the fields relate; choose reachable DNS services that suit your network. LAN names, internal company domains, and public domains may need different resolution paths. domains determines which domains a resolver applies to; it doesn’t set their final proxy outbound.

{
  "dns": {
    "servers": [
      {
        "address": "localhost",
        "domains": ["geosite:private"]
      },
      "1.1.1.1"
    ]
  }
}

If LAN devices depend on a local resolver, sending every query to a public resolver may make internal names unresolvable. Conversely, sending all public domains to a resolver that only knows internal names can cause timeouts. Test one public domain and one LAN name to find out which group is affected. Also check whether routing rules let the DNS server address use the intended outbound. Changing domain match rules won’t fix a network path if the resolver itself is unreachable.

Avoid misdiagnosis from cached results and repeated lookups

After changing DNS, existing connections and app caches may continue using the old address. Close the relevant app connections and make new requests to verify the change. If needed, check system and browser caches separately instead of just refreshing the page. If the domain resolves but access still fails, note the resolved address and whether routing chose direct or proxy. If only the browser fails, check for its own proxy or Secure DNS settings. If only one command-line tool fails, check its environment variables and local SOCKS or HTTP port.

DNS and routing also intersect in a common way: IP-based rules need an address, while domain-based rules need a recognizable domain. Resolving a domain too early can remove the information a domain rule needs; skipping resolution entirely prevents address-based checks. Before choosing a domain strategy, identify which destinations rely on domain categories and which rely on IP categories, then inspect the generated configuration’s actual behavior. No single strategy is right for every network.

After making changes, keep a stable set of test targets: one LAN name, one domain that should go direct, and one that should use the proxy. Record whether each resolves and which outbound handles the connection. Reuse the same targets after subscription or rule-set updates to see whether a change occurred during resolution, rule matching, or the remote connection. If queries succeed but return an unexpected address, check the local network’s DNS response, app caches, and domain-specific rules instead of replacing the whole DNS setup based on one failed page load.

TUN Mode and the Limits of System Proxy

Choose how traffic enters the client

The system proxy provides a local proxy endpoint to apps that support it. Browsers and some desktop apps connect to this endpoint, but not every app reads the system proxy setting. TUN creates a virtual network interface and routes eligible IP traffic through the client. It can cover more apps, but adds variables such as routing tables, virtual interfaces, DNS capture, and permissions. First verify the server, subscription, and basic routing with system proxy mode. Enable TUN only when an app bypasses the system proxy or you need broader traffic capture.

TUN settings in desktop v2rayN may require system permissions and additional network components. The exact controls vary by system and client version. Before enabling TUN, note the working state: active server, system proxy mode, DNS settings, and routing mode. When it starts, check whether the client reports that the virtual interface was created successfully; don’t rely on the toggle alone. Some systems require network extension or administrator permissions. Repeatedly switching the toggle won’t fix a permission or component error—address the issue identified in the logs first.

Check the network environment for your platform

The table lists troubleshooting areas; it doesn’t mean the same commands apply to every operating system. If other virtual network tools are running, both programs may try to change the default route or DNS. Quit them one at a time, then test v2rayN on its own. If an app works in system proxy mode but not with TUN, compare the traffic entry point and DNS path in each mode before switching servers. When the server stays the same but the access method changes, the issue is more likely in local traffic capture.

Test traffic capture with a small set of targets

After enabling TUN, test a regular website, a LAN device, and an app that previously ignored the system proxy. Each points to a different kind of issue: a website failure may involve DNS or the default outbound; a LAN failure may mean private addresses are being sent through the proxy; an app-specific failure may involve its own network stack or protocol. Keep the active server unchanged during testing. If toggling TUN reliably reproduces the issue, check interface startup logs, routing tables, and DNS status instead of reimporting the subscription.

Other programs may still use the local proxy listener while TUN is enabled, but don’t configure the same app to use multiple access methods unnecessarily. If an app has a manual SOCKS proxy and is also captured by TUN, its traffic path can be hard to trace. Temporarily leave only one clear entry point while troubleshooting. Once it works, decide whether to restore the app-level setting. The same applies to terminal tools: check whether environment variables still point to a local HTTP or SOCKS port. After stopping TUN, verify that the virtual interface and its routes have been removed before checking whether normal networking has recovered.

If network access still fails after disabling TUN, check in order whether the system proxy points to a stopped local port, DNS still uses an unreachable address, and the default route has been restored. Don’t reset every network setting at once; identify the change that remains. On devices used on both office and home networks, test LAN access on each network because private address ranges and internal DNS may differ. TUN is properly configured not just when the toggle is on, but when its capture scope, LAN exceptions, and shutdown recovery all behave as expected.

FakeDNS: Uses and Limitations

How synthetic addresses work

In supported traffic paths, FakeDNS returns a temporary synthetic address for a domain and stores the mapping between the address and the original domain. When the app connects to that address, the core can recover the domain and continue domain-based routing. This helps when a network path loses domain information too early; it isn’t a public DNS service that replaces every resolver. The synthetic address isn’t the destination’s real address. Copying it into a network tool outside the client usually won’t produce the same result.

Before enabling FakeDNS, confirm that the problem is actually that domain rules can’t see the domain. If the logs already show the destination domain and the rule matches, FakeDNS only adds complexity. A typical check is to make sure the app’s traffic reaches the core, DNS requests follow the intended path, and the app’s resulting connection returns to the core. Capturing DNS without capturing the subsequent connection—or capturing the connection while another system resolver returns a real address—doesn’t complete the mapping path.

Check the address pool and routing

This snippet shows the FakeDNS address pool structure in Xray. It’s an example of the fakedns field, not a complete client configuration. Use an IPv6 address pool only if it fits your traffic capture setup and network. Make sure the example pool doesn’t overlap with networks already in use. The relevant DNS requests must reach FakeDNS, and the client must continue to capture connections to the synthetic addresses. Adding this section alone won’t enable the feature if traffic doesn’t enter the client.

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

Before choosing an address pool, check the current network and routes used by other virtual networking tools. If the synthetic address range overlaps with an existing route, the app may send connections to the wrong interface. During testing, keep a copy of the original DNS and TUN settings, and enable only one FakeDNS-related option at a time. Afterward, test both domain names and direct IP connections. FakeDNS mainly handles domain mappings; don’t attribute every IP connection issue to it. Also test a LAN name to make sure internal services still resolve and remain reachable.

Troubleshoot lost mappings and app behavior

An app may keep using a cached synthetic address after the client restarts or the mapping changes, causing temporary failures. Make the app resolve the name again, then check whether the new request follows the expected path. Some apps handle DNS themselves or connect to fixed IPs, which can limit FakeDNS’s effect. If only one app fails, check its network and DNS settings. If all domains fail, check DNS capture and core logs. Don’t use the address shown on a browser page to judge the mapping; check whether the core recovered the destination domain.

When using FakeDNS with domain-based routing, check rule order. If a broad IP rule handles the synthetic address first, domain-based routing may not work as intended. In the logs, look separately for four stages: the query, mapping recovery, routing match, and outbound connection. Focus on the stage that’s missing. A synthetic DNS response confirms only that the query worked; the final connection still depends on the request reaching the core and the outbound being able to reach the destination.

If ordinary DNS and your current routing work reliably, keep the configuration simple. FakeDNS addresses a specific domain-visibility problem; it isn’t a performance feature that should always be enabled. If you keep it, record the address pool, capture mode, test apps, and rollback steps. Recheck the full path whenever you change TUN or DNS. If you disable FakeDNS, make apps resolve names again so cached synthetic addresses aren’t mistaken for a new failure.

Custom Outbounds and Rule References

Outbounds are the destinations selected by routing

An outbound describes how traffic leaves the core. The common freedom outbound is used for direct connections; blackhole blocks traffic. A proxy outbound uses the server settings to determine how to connect. Routing rules refer to an outbound’s tag through outboundTag. When adding a custom outbound, check that its tag is unique, rules reference it correctly, and the default outbound still makes sense. Descriptive names make logs easier to troubleshoot than ambiguous numbers.

v2rayN usually generates a proxy outbound from the selected server. Direct edits to generated files may disappear when you switch servers, update a subscription, or restart the core. For persistent custom behavior, use the client’s custom configuration or merge feature, then inspect the final generated configuration. Merge behavior varies by configuration entry point: some replace an entire array, while others change only specific sections. Back up the original configuration, confirm the core accepts the resulting JSON, and then test actual traffic.

Create direct and block outbounds you can verify

This snippet shows how two outbounds relate to a precise domain rule. It doesn’t include proxy server settings or an inbound, so it isn’t a complete runnable configuration. The example domain only illustrates the rule structure. Use block rules carefully, especially while troubleshooting. If an overly broad rule matches a DNS service or business endpoint first, later rules can’t undo that connection.

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

When testing a custom outbound, start with one exact rule and confirm the logs show the expected outbound tag. Expand the match only after that works. A block rule may make an app time out or fail to connect; that doesn’t prove the proxy server is broken. A direct rule can still fail if local DNS or network access is unavailable. Correct routing only means traffic was assigned to the intended outbound; the outbound’s connection to the destination must be tested separately.

Keep server settings and outbound tags distinct

When you switch the active server, the proxy outbound generated by the client may change, but tags referenced by routing rules must remain resolvable. Before adding your own outbound, check the tags in the final configuration to avoid duplicates. Duplicate tags can make logs hard to interpret or send rules through the wrong outbound. If you use multiple custom proxy outbounds, specify which handles ordinary destinations and which is reserved for exact rules. Check that the required server configurations still exist. Don’t include real server addresses or credentials in public examples.

The local SOCKS listener in a connection path should also be distinguished from an outbound. The listener receives app traffic; it isn’t the remote server. The snippet below only shows where the listening address and port are configured. Binding to localhost avoids exposing a proxy listener to your LAN unintentionally. Use a port that matches the client interface and the settings of apps that connect to it. If another process already uses the port, the core may not start; see How to Fix a Local Port Conflict.

{
  "inbounds": [
    {
      "tag": "local-socks",
      "listen": "127.0.0.1",
      "port": 10808,
      "protocol": "socks",
      "settings": {
        "auth": "noauth",
        "udp": true
      }
    }
  ]
}

To roll back a custom configuration, disable the added rules first, remove outbounds used only by those rules, and then reload the core. Deleting an outbound first leaves active rules pointing to a missing destination. After rollback, test one direct and one proxied destination to make sure no leftover rules affect the default path. If the client fails to start, check the field or tag named in the error; don’t keep adding snippets while the configuration is broken. The larger the configuration, the more important it is to give every new rule a clear purpose and a separate test.

Configuration Verification, Rollback, and Maintenance

Troubleshoot in connection-path order

Advanced configuration spans several layers, so troubleshoot along the connection path: does the app send traffic to the client, is the local listener running, does DNS return the expected result, does routing select the right outbound, and can that outbound reach the destination? Replacing the server before checking earlier steps may change the symptoms without explaining the original problem. Change one observable variable at a time and record the same test result before and after. If no apps can connect, start with the client status and system proxy. If only one domain fails, check DNS and routing rules.

Logs offer more specific clues than a browser error, but check them against the time you reproduced the issue. Reproduce it once, then review the entry, resolution, routing, and connection records from that time. If the app crashes on startup or the core doesn’t load, there won’t be a complete destination-connection log. Check the runtime environment and system permissions first; see Troubleshooting Startup Crashes. If the logs show no request for the destination, go back to the app’s proxy settings or TUN capture scope instead of changing domain rules.

Use a repeatable test matrix

Keep four test targets fixed: a regular website, a destination that should go direct, one that should use the proxy, and a LAN service. For each, record the app entry point, DNS result, matching rule, outbound, and final result—not just “works” or “doesn’t work.” When changing DNS, compare resolution and the subsequent connection. When changing routing, compare the matched rule and outbound. When changing TUN, check whether the request reaches the client. Results are comparable only when the test targets stay the same.

Use the table as a starting point, not as proof of a cause. For example, DNS may succeed while routing sends traffic through the wrong outbound; the outbound may be correct while the destination network or server connection fails. A single latency result isn’t a substitute for testing actual access. See Connection Tests vs. Download Speed Tests for what common measurement methods cover. Before drawing conclusions, make sure the test and browser access use the same active server and outbound.

Keep rollback simple

Before each round of changes, save the last working state: the active server’s group, routing mode, DNS settings, TUN status, and any custom snippets. Record the settings; store full exports containing credentials securely. If a change causes a problem, roll back in reverse order. Disable the new rules or feature first, restore DNS and the access method, then check system proxy status. Revert one item at a time and repeat the same tests to identify which change caused the issue.

Track client, subscription, and rule-data updates as separate events. They affect different things: a client update may change the interface and configuration generation, a subscription update changes the server list, and a rule-data update changes category matching. If all three happen on the same day and routing then breaks, it’s hard to identify the cause. Finish one update, run the fixed test matrix, and confirm everything works before moving on to the next. To install a desktop or Android client, choose the right platform on the Downloads page rather than mixing a download into routing troubleshooting.

When reporting a problem, include the operating system, client name, access method, failing stage, relevant error text, and tests you’ve already run. v2rayN, v2rayNG, and v2flyNG don’t have identical interfaces or core options, so name the specific client. Redact subscription URLs, server credentials, and personal network details before sharing logs. If the issue occurs during first-time setup or connection, go back to the Getting Started guide and review the main steps. If it involves subscriptions, routing, or TUN settings working together, use this guide to narrow it down one layer at a time.