V2Ray Advanced Configuration Guide

01 · Subscriptions and entries

Subscription groups and server filters

A subscription URL is the source for retrieving server configurations; a group is how the client organizes entries locally. They are not the same thing. A group is usually linked to one source, but it can also contain servers added manually. Before changing advanced settings, keep three things separate: source, display name, and purpose. The source is used for updates, the name helps identify entries, and the purpose helps you filter them. Naming a group “Work” does not automatically route work apps through its servers. Actual traffic depends on the active server, routing rules, and how traffic is captured by the proxy.

Create groups you can trace

In v2rayN’s subscription group settings, add a group, give it a short, stable note, and paste the complete subscription URL. Keep the entire URL, including any query parameters. A stray newline, space, or punctuation copied from a webpage can change the request. After saving, update only that group. Check the update message and entry count, then verify that each server has a complete protocol, address, and port. Avoid adding multiple sources and updating them all at once: if the list comes back empty, it will be harder to tell whether the URL is wrong, the request failed, or the source returned no entries.

Subscription URLs may contain account credentials. Hide the full URL before sharing screenshots, logs, or exported configurations. Routine management does not require sending subscriptions to unfamiliar conversion tools. If a source offers a client-specific format, use the option intended for your client. A response that displays in a browser is not necessarily parseable by the client. A sign-in page, expiration notice, or error page may return a successful HTTP status without containing a valid server list. Check the client’s update log rather than relying on whether the page opens.

Display filters vs. update filters

List search usually hides entries temporarily; clear the search to see all servers again. Filters in some subscription group settings can affect what gets imported, so excluded servers may never appear in the local list after an update. Read the field description first and confirm whether the filter applies to display or updates. Start with a simple keyword, such as a region tag in a note. Use regular expressions only when the interface explicitly supports them; not every text field uses the same matching rules.

For a note filter that supports regular expressions, Work|Backup matches either term, while ^Work matches notes that begin with “Work.” Case sensitivity, blank notes, and exclusion syntax depend on how that field is implemented, so do not assume another tool’s syntax will work. Before saving a complex filter, confirm that at least one existing entry matches, then update the group on its own. If the results suddenly go empty, remove the filter and update again. Do not delete the entire group right away, or you could lose local notes and manually added entries too.

Keep a way to roll back updates and changes

A subscription update can overwrite server settings, replace identifiers, or remove entries deleted by the source. For manual changes you need to keep, copy the entries into a separate local group and note why you changed them. Do not rely on subscription entries to retain custom settings over time. After updating, check that the active server is still there and make a real web request. A latency test only reflects the probe path; it does not prove that everything works. For help choosing servers, see how to weigh latency, pricing, region, and protocol.

02 · Matching and traffic routing

V2Ray Routing Rules in Practice

Routing decides which outbound handles a connection that has already reached the core. It does not automatically send every app through the client, and it is not the same as the system proxy switch. If an app bypasses the local proxy, the core never gets a chance to match its rules. When troubleshooting routing, first make sure the request reaches the client; then check its destination, matched rule, and final outbound. Separating traffic capture, rule matching, and forwarding makes problems easier to isolate than replacing the entire routing preset.

Understand rule order and match conditions

Common cores evaluate rules in order, so a broad rule near the top can prevent a more specific rule below it from matching. Put explicit local services and specific domains first, then broader address ranges, and handle the default route last. Multiple conditions of different types in one rule generally all have to match; multiple values in a domain list are alternatives. Do not put a domain condition and an unrelated address condition in one rule expecting either to match independently. Evaluate each rule as a complete set of conditions.

Domain syntax has its own boundaries: full:example.com matches only that exact domain, while domain:example.com matches the domain and its subdomains. A plain string may use broader keyword matching. For a single service, prefer an exact domain or an explicit domain suffix. IP rules can be unreliable when a destination uses multiple addresses or returns different results on different networks; one IP rarely represents an entire site. Rules that rely on geographic databases also require the relevant data files to exist and be readable by the active core.

Start with the smallest rule set

This Xray-style routing snippet is not a complete configuration. It sends the test domain and private network addresses to the direct outbound, leaving other connections to follow the existing default behavior. It assumes an outbound tagged direct; change the tag too if yours is different. When merging this into a custom configuration, keep the existing inbounds and proxy outbounds—do not replace the entire file with the snippet. If the GUI routing editor generates these fields, make changes there to prevent them from being overwritten the next time the core starts.

{
  "routing": {
    "domainStrategy": "AsIs",
    "rules": [
      {
        "type": "field",
        "domain": ["domain:example.com"],
        "outboundTag": "direct"
      },
      {
        "type": "field",
        "ip": ["127.0.0.0/8", "10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16"],
        "outboundTag": "direct"
      }
    ]
  }
}

DNS resolution strategy is not a routing preset

AsIs tells the routing stage to use the target information it already has without resolving a domain just to apply an IP rule. IPIfNonMatch tries to resolve the domain if it did not match, then checks the resulting address. IPOnDemand may resolve it as soon as an IP condition is encountered. These strategies affect query volume and rule matching, but do not automatically send DNS requests to the right server. Before using address-based rules, check your DNS settings and resolution path. Then decide whether routing needs to resolve domains, rather than adding unnecessary dependencies to a rule that could use a domain match.

For a test, choose one destination, make one new request, and check the access log for its target and outbound tag. Browsers may reuse existing connections, so close the affected connection or reopen the app after changing rules. If domain rules never match, check whether the app gives the core only an IP address and whether sniffing can recover the domain. Reordering rules cannot fix missing information. For the basics, see proxy modes explained. If you still cannot access sites after connecting, work through the step-by-step troubleshooting checklist.

03 · Queries and resolution paths

Optimizing DNS settings

DNS settings are about more than “choosing a different server.” A request may involve the app’s resolver, the operating system resolver, the client’s built-in DNS, and the resolution path used by the remote proxy for the destination domain. A browser using encrypted DNS may bypass regular system DNS requests altogether. Start by identifying who makes the query, where it goes, and who uses the result. Changing a setting only helps if that component actually handles the request.

Separate bootstrap DNS from DNS for regular traffic

If a proxy server uses a domain name, its IP address must be resolved before the client can connect to it. This is bootstrap DNS. Sending every query through a proxy that is not connected yet can create a loop: the client needs the proxy to resolve the proxy’s own address. Keep a working direct resolution path for the server’s domain, or use an address explicitly provided by the source. Do not permanently pin an address you resolved yourself; the source may rotate or change it. Design DNS for regular destinations separately, based on their outbound routes.

Before changing DNS in v2rayN, note the current routing preset, core type, and DNS editing method. Some interfaces have separate DNS templates for regular proxy and TUN modes; others offer advanced editing of the core configuration. Changing a template that the current mode does not use will have no effect. After saving, restart the relevant core and check the logs to confirm that the configuration loaded. If a field is unrecognized, restore the previous configuration and check the syntax supported by your active core. Do not guess based on a similarly named setting in another core.

What common DNS parameters do

This shows the minimum fields commonly used by Xray’s built-in DNS, for structure only. A public resolver is not the right choice for every network; first make sure it is reachable. UseIPv4 explicitly requests IPv4 only for testing, and should not be treated as a permanent setting for every environment. If you need IPv6, restore the relevant query strategy once IPv6 works across your system, network, and proxy path. This snippet does not receive all system DNS requests or automatically capture DNS in TUN mode.

{
  "dns": {
    "servers": ["1.1.1.1"],
    "queryStrategy": "UseIPv4"
  }
}

Troubleshoot one symptom at a time

If all domains fail but numeric addresses work, check resolver connectivity and the outbound used for queries. If only certain domains fail, inspect domain-based routing, the cache, and upstream responses. If resolution succeeds but connections time out, focus on whether the returned addresses are reachable. Encrypted DNS certificate checks depend on the correct system time; using a domain name for the resolver may also require bootstrap DNS. Change one variable at a time and keep notes on query times and error types. Do not switch resolvers, routing strategies, and proxy servers all at once.

IPv6 issues are especially easy to confuse with DNS problems. Receiving an IPv6 address does not mean your local network or proxy outbound can connect to it. Conversely, disabling IPv6 everywhere may break services that otherwise work. Test with a controlled query type first and see whether the failure changes with the address family; then decide whether to fix the network or change the strategy. After switching between Wi-Fi, Ethernet, or mobile networks, reconnect if needed and clear relevant caches. Browsers and the operating system have separate caches, so restarting the client may not clear every old result.

04 · Capturing traffic

Enabling and rolling back TUN mode

TUN captures IP packets through a virtual network interface, making it useful for apps that ignore system proxy settings. It is not a proxy protocol. Traffic entering TUN still needs routing, DNS handling, and an outbound connection; the actual behavior depends on the backend. v2rayN can use a dedicated TUN backend for traffic capture, so the TUN switch in the interface is not simply a field in the Xray core configuration. Check the current client documentation and runtime logs to identify the backend before adjusting its stack, routes, or DNS settings.

Verify the basic connection before enabling TUN

First, confirm that the server can access your target service using the regular system proxy. Then check whether the operating system permits creating a virtual interface and changing routes. Windows may require the appropriate permissions or a client service; macOS and Linux may need authorization or a supporting service. Insufficient permissions, interface creation failures, and server connection failures are different problems—use the logs to troubleshoot each separately. See the download center for desktop installers. Do not install extra components from unknown sources to work around an error you have not diagnosed.

Before enabling TUN, temporarily quit other software that changes default routes, DNS, or virtual interfaces, and note whether your network works as expected. Be especially careful when working remotely on another device: changing routes can immediately drop your management connection, so have a local recovery option ready. For the first test, do not also enable strict routing, custom subnet exclusions, or FakeDNS. Keep the defaults, verify that the interface comes up, the proxy server connects, and common sites load, then add features one at a time.

Understand the stack, auto-routing, and exclusions

The network stack converts captured packets into connections the backend can handle. Implementations may differ in system compatibility, UDP support, and resource use. A stack that works on one system is not necessarily the best choice for every device. Auto-routing sends target traffic through the virtual interface; exclusions preserve the original path for local services, LAN traffic, or specific connections. First confirm that the backend properly excludes connections to the proxy server itself, so outbound traffic does not re-enter TUN and get captured repeatedly.

MTU is the maximum packet size an interface can carry; a larger value is not always faster. If small pages load but large downloads, specific apps, or some connections stall, check path MTU and fragmentation as well as the server and DNS. Make small adjustments within the backend’s supported range, establish a fresh test connection each time, and keep the original value. Setting the MTU to a number found online based on one page load can hide the real problem, which may return when you switch networks.

Platform differences and testing order

On Android, v2rayNG and v2flyNG typically use the system VPN interface to capture app traffic. Their permission prompts and interface management are different from the virtual interface setup on desktop. Per-app proxy settings, LAN bypass, and background restrictions can all affect which traffic is captured. Stop another client using the same type of interface before connecting. Battery-saving settings that terminate background processes can also drop the connection when the screen locks. Do not apply desktop client service installation instructions to Android.

Test in order: a regular website, the local gateway or a LAN service, an app that needs UDP, then network switching and waking the device. If enabling TUN cuts off all access, turn it off, confirm that regular networking has recovered, and check interface, route, and DNS logs. If problems continue after disabling it, quit the client, check for a leftover system proxy, and reconnect to the network. Only tune strict routing and excluded subnets after traffic capture is stable. Restoring network access comes before adding more advanced settings.

05 · Domain mapping

FakeDNS and DNS capture

FakeDNS assigns synthetic addresses to domains and uses the mapping to recover the original domain when a connection arrives. These addresses are for internal client use; they are not the website’s real server addresses. This is useful when an app resolves a domain itself and then connects using only an IP: the proxy may still recover the domain, apply domain-based routing, or pass the name to a remote resolver. FakeDNS does not improve server quality by itself, and cannot work on its own without DNS and traffic capture.

Check that the mapping loop is complete

The full path has four steps: the app’s query reaches the intended resolver, the resolver returns a synthetic address, the app connects to it, and the client receives the connection and recovers the domain. Bypassing the client at any step can break the flow. For example, a browser’s encrypted DNS may skip the mapping resolver; the system may receive a synthetic address but route the connection directly over the physical network; or the resolver and connection handler may use different implementations. Simply enabling sniffing will not necessarily fix these cases.

First make sure regular TUN and real DNS resolution work reliably, then decide whether you need FakeDNS. The TUN backend used by v2rayN may have its own synthetic-address mechanism; do not assume it is interchangeable with FakeDNS in an Xray configuration just because the names are similar. Check the field names, address pool, caching, and routing requirements for the actual backend. Do not enable both mechanisms with the same address range unless you have a clear compatibility design. Different modules may hold different mappings, so the same synthetic address could refer to different domains.

Address pools and mapping capacity

This Xray-style snippet illustrates how the address pool, DNS server selection, and inbound sniffing relate to one another. It is not a complete file you can use to replace a client configuration. Merge the inbound sniffing fields into the inbound that actually receives the traffic; do not add them randomly to the root object. 198.18.0.0/15 is a common choice for a synthetic address pool, but first make sure your LAN does not use or specially route this range, and that connections using it stay on the proxy capture path.

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

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

poolSize sets the mapping capacity; it does not mean the number of servers that can be used at once. When many different domains are visited, capacity and eviction behavior determine whether an old address can still be mapped back to its name. An app may keep a DNS result after the core restarts and loses the mapping, causing connections to the old synthetic address to fail. If an app acts up after a client restart, quit the app, clear its relevant DNS cache, and reconnect before changing proxy protocols.

Exceptions and symptoms

Check separately whether synthetic addresses are suitable for LAN hostnames, device discovery, apps that require real IPs, and services that need special DNS records. Some apps expect results from a particular network range or pass them to another process the client does not capture. Configure exceptions using the backend’s supported method. Exception domains should return real addresses and have matching direct or proxy rules. Do not return synthetic addresses while also excluding their range from client traffic capture.

During troubleshooting, check whether the system or app received a synthetic address, whether the connection reached the capture interface, and whether the logs show the original domain being recovered. If a synthetic address appears in a physical network connection, fix traffic capture and routing first—not the DNS server. When disabling FakeDNS, account for cached results: switch back to real resolution, restart affected apps, flush the system cache if needed, and confirm that no connections still depend on old mappings. Turning off the setting while stale addresses remain can prolong the problem after the configuration is restored.

06 · Sources and maintenance

Managing multiple subscriptions and update policies

The goal of managing multiple subscriptions is to keep sources separate, control the impact of updates, and preserve a recoverable setup—not to merge every server into one long, hard-to-read list. Use a separate group for each source, with a stable note such as “source code + purpose,” and keep temporary test sources apart. Establish management rules before adding sources and running bulk updates. Otherwise, duplicate names, different protocols, and changing subscriptions get mixed together, making it easy to select the wrong server and hard to trace where its settings came from.

Know how groups, entries, and active connections relate

Selecting a group often changes only the list view; it does not necessarily change the active server. Some interfaces let you select a server within the group and switch immediately. Check the active indicator rather than relying on the group name shown at the top. Server notes are not unique identifiers: different sources may use the same name, and a source may rename an entry during an update. To investigate an update, compare the protocol, destination address, port, and transport settings—not just the display name.

Be cautious with automatic deduplication, too. Two servers with the same address and port are not necessarily equivalent; identity fields, TLS names, paths, or flow-control settings may differ. Unless you know which fields the client uses to detect duplicates, do not bulk-delete entries just to shorten the list. If you need to trim it, filter by group first and save any necessary local notes. Then update the group once to make sure the source does not re-add the same entries.

Set sensible limits for automatic updates

Choose an update interval based on how often the source changes and how you use the client. Updating too often adds requests and troubleshooting noise; it will not fix a source that is already unavailable. Manually update new sources first. Once they prove stable, enable a scheduled policy if the client supports it. Scheduled updates may not run as expected when the device is asleep, the network is not ready, or background processes are paused. Check the latest update result before important use instead of assuming the schedule ran.

Also distinguish between updating through the proxy and updating directly. If a source is reachable only over a particular route, explicitly choose the path for update requests. But do not make your only working subscription update depend entirely on the active server you are about to replace. After changing the update route, test one group separately, note the network error type in the logs, and hide the full subscription URL. If several groups fail at once, check shared network and proxy dependencies first; you usually do not need to rebuild each source.

Backups, migration, and retiring sources

Before moving to another client, use the interface’s export or backup feature and check whether it includes subscription URLs, manual servers, routing, and DNS settings. Backup scopes are not interchangeable, and one share link usually cannot restore an entire setup. Backup files may contain identifying information, so store them somewhere secure. After restoring on another device, confirm that local ports, file paths, service permissions, and virtual interface settings are appropriate. Do not assume all network settings from the old device will carry over.

When retiring a source, switch to a verified working server first, disable automatic updates for that group, then decide whether to delete it or keep a local record. Deleting the active entry may drop the connection, while some apps continue to reuse old connections—making it seem as if requests still follow the old route after the list changes. After deletion, establish a fresh test connection and check for routing rules or custom outbounds that still reference the entry. Remove subscriptions you no longer use from the update list to avoid needless failure notifications.

As your setup grows, keep a brief change log: which group changed, what type of setting was updated, what you tested, and how to roll back. Do not include full subscription URLs or identity fields. The point is to connect failures with recent changes, not to build another complex configuration system. If you cannot tell whether an issue came from a source update or a local setting, import the same source into a separate group and compare its entries and connection results without changing your stable group.

07 · Tags and forwarding

Custom outbounds and merging configurations

An outbound defines how the core makes a connection; routing uses tags to direct requests to the appropriate outbound. Adding outboundTag to a rule does not create that outbound—the tag must exist in the final runtime configuration, with matching spelling and capitalization. Custom outbounds are for specific forwarding needs, not a replacement for every GUI setting. For everyday use, let v2rayN manage standard server configurations and keep custom configuration to the parts you actually need. This makes updates and migration easier.

Check where the final configuration comes from

A graphical client usually generates its runtime configuration from the active server, routing preset, and DNS template. Direct edits to a temporary generated file may be overwritten the next time you switch servers or start the core. First identify whether the current editor is for a server, routing, or a complete custom configuration; each controls a different scope. With a full custom configuration, check whether the client still adds local inbounds, logging, and management interfaces. Do not assume every GUI option remains active.

Before making changes, export the working configuration and check the logs to confirm which core is running. Xray and V2Fly both use JSON-style configurations, but they do not support exactly the same fields or protocols. Configurations for other TUN backends are even less interchangeable. When merging a snippet, preserve the root object, arrays, and commas. Duplicate keys in the same object may be silently overwritten by the parser. A successful syntax check only means the format is valid; the core must also accept the fields and establish a connection.

Understand tags through direct and local forwarding

This Xray-style outbound snippet shows two tags: direct connects directly, while local-socks sends requests to a SOCKS service on the local loopback address. The second outbound works only if a service is actually listening on that local port; the example port is not a default for all clients. Do not point it at the inbound port used by the same configuration, or you may create a forwarding loop. If an outbound array already exists, merge in the required objects rather than replacing the existing proxy outbounds.

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

In this type of configuration, traffic that matches no routing rule usually uses the first outbound in the array. The example therefore defaults to direct connections; it is not a complete everyday proxy configuration. When merging, preserve the existing default outbound and use a precise rule to reference the new tag. Start by sending one test domain to local-socks and confirming the local service works, then broaden the match. Do not test a newly added outbound with a rule that captures every connection; a mistake could disrupt all traffic.

Chaining traffic vs. choosing an exit

Having multiple outbounds does not mean requests pass through them in sequence. A connection typically selects one outbound; a chain is created only when an explicitly configured mechanism supported by the core links them. A chain also raises questions about which hop resolves server names, which handles UDP, what happens if the first hop fails, and which logs to inspect. Unless you have a specific need, avoid adding layers just for the sake of “one more hop”—they increase connection time and make problems harder to trace.

To validate a custom outbound, first check the downstream service’s listening address and port, then confirm the tag exists, and finally inspect rule matches and connection errors. A connection-refused error points to the listening service; a missing-outbound error points to the tag or configuration merge. If you see loops or repeated connections, stop the relevant core immediately and restore the baseline. Reintroduce changes one at a time. For more on how cores and GUI clients fit together, see the guide to the Project V open-source ecosystem. A client’s name is not the same thing as an outbound protocol.

08 · Compatibility and validation

Validating protocols, cores, and configuration

Before completing advanced setup, check compatibility at every layer: can the client express these settings, can the selected core parse the fields, does the server support the corresponding features, and does the current network allow the connection? Failure at any layer can break the setup. A client option does not guarantee that every server can use it, and seeing a note after import does not mean every parameter was retained. Use v2rayN to manage desktop configurations; on Android, choose v2rayNG or v2flyNG for your needs. Check the actual core and import results for supported features.

Check protocol, transport, and security separately

VLESS, VMess, Trojan, and Shadowsocks use different identity and connection mechanisms; you cannot convert between them by changing the protocol name alone. The transport defines how a connection is carried, while TLS or REALITY settings involve handshake and target identity parameters. Troubleshoot layer by layer: check the protocol and identity fields, then the address and port, then the transport and service name, and finally the TLS name or required REALITY fields. Do not fill in values from another server when the source does not provide them.

VLESS does not provide the same transport encryption as TLS, so use the security layer required by the server. REALITY and XTLS Vision are not interchangeable protocol tags; they depend on compatible security-layer, flow-control, and core support. Common handshake failures can result from an incorrect server name, key-related fields, short ID, or system time—not from a routing rule. For how the concepts and settings fit together, see how REALITY and XTLS Vision work. Always test with the complete parameters provided by the source.

Switching cores is not a universal fix

Xray and V2Fly are core options in the Project V ecosystem; graphical clients translate interface settings into runtime configuration for the core. v2rayNG primarily uses Xray, while v2flyNG is built around V2Fly. Configurations that depend on specific extensions may not transfer unchanged between them. Core selection in v2rayN also needs to match the protocol and configuration template. Before switching, note the current core and enabled advanced features, stop the existing connection, and check whether the new core starts successfully. Do not rely on the interface’s running icon alone.

If some fields disappear after import, first check whether the share format can represent them and whether the client supports that format. If necessary, verify each field in the GUI, but never paste real identity credentials into a public support request. If the core fails to start, check configuration syntax, unknown fields, port conflicts, and required files first. If it starts but the handshake fails, check server parameters, system time, and network connectivity. These failures need different fixes; switching cores at random only muddies the evidence.

Use a repeatable validation process

After each change, validate in the same order: confirm the core loaded the configuration, verify the local entry point, test one regular domain, one destination that should connect directly, and one that should use the proxy. Only then test additional features such as TUN, UDP, IPv6, or synthetic addresses. A page loading in a browser only proves that the path used for that page worked at that moment. Reconnect long-running sessions and background apps, and test after switching networks so existing connections do not hide problems in the new configuration.

Organize logs around the time, destination, inbound, matched rule, and outbound tag. Keep the original error category, but hide subscription URLs, identity fields, and unnecessary personal browsing history. Temporarily increasing the log level can help locate a problem; restore an appropriate level once it is fixed to avoid excessive long-term logging. If a change spans several sections, return to the last working setup and restore settings layer by layer: subscriptions, routing, DNS, traffic capture, then extensions. This is more repeatable than tuning while the system is still in an abnormal state.

This page explains how configuration settings depend on one another; you do not need to enable every feature. Keep a setup you can explain, validate, and restore: apps are captured as expected, local services remain accessible, DNS and routing agree, and subscription updates do not break manual settings. To set up a connection from scratch, return to the quickstart guide. To search by symptom, see the FAQ. Tie each test result to the change that prompted it, and advanced settings become a maintainable setup rather than a one-off experiment.