Configuration Reference · v2rayN
V2Ray Advanced Configuration Guide
After your first connection works, use this guide to check configuration options for subscriptions, routing, DNS resolution, and traffic capture. If you have not verified a basic connection yet, follow the import, connect, and test steps in the Getting Started Guide first. Then return and change one layer at a time.
Subscription Groups & Server Filters
Set the update scope before importing servers
Subscription groups identify where server entries come from and which entries an update affects. They are not routing policies and do not automatically select an outbound for any app. Using v2rayN, the preferred desktop client, as an example, add a group in subscription management, give the source a recognizable note, and enter its subscription URL. Save it, switch to that group, and use the option to update only that group. This avoids changing other sources during your first check. Depending on the interface, the update option may be labeled “Update current subscription” or appear in the group menu. What matters is whether it updates the current group or all groups—not where the button appears.
When the update finishes, do more than check for a success message. Confirm the group contains usable entries, then select an expected server and check that its protocol and transport match the provider’s details. Set it as the active server and make a real request using a connection mode you have already verified. A successful subscription request, successful list parsing, and a working server from the list are three separate outcomes. Even a normal response may contain only a login page, an error message, or a subscription format the client cannot parse.
Distinguish import filters from list search
Search above the server list usually affects only what is visible. A server filter in the group settings may instead change which entries are actually imported during an update. Before changing it, confirm whether it matches notes, protocols, or another field, and whether matching entries are kept or excluded. Unless the client explicitly documents regex support, start with a plain keyword you know exists; do not paste an expression with pipes and parentheses. Choose a stable prefix the source uses over time, not a temporary label that may change.
If possible, compare results in a disposable test group using the same source: first import without filters, then add a condition that matches only a few entries, and finally clear it and update again. If the entries are still missing after clearing list search, the search box is not merely hiding them. If the client explicitly uses regex, check whether anchors restrict matches to the start of the string and whether parentheses change how alternatives apply. Full-width punctuation in Chinese aliases can differ from ordinary hyphens; copying a short snippet from the server note is more reliable than typing the full name.
Trace an empty list back to the update stage
When an update fails, first identify whether the error occurred before the request, while reading the response, or during entry parsing. If no request was sent, check that the group was saved and enabled and that you chose the right update action. If the log reports a certificate or time error, correct the system clock and check the connection path; do not hide the problem by weakening certificate validation. If a response was received but no entries could be imported, temporarily remove the group filter and retry in a separate test group. If that still imports nothing, ask the source to confirm the output format and link status rather than continuing to change routing rules.
Some sources are reachable only over a specific network path. Test updates both directly and through the current proxy; do not delete working servers before testing the latter, or you may lose the connection needed to update. On Android, you can use the same approach to check subscription management in v2rayNG or v2flyNG, but do not assume desktop group fields transfer one-to-one. Find installers and platform options on the Get the client page. For help diagnosing update errors, see Subscription update failures and auto-refresh intervals.
V2Ray Routing in Practice: Rule Order & Default Outbound
First confirm traffic reaches the core
Routing rules apply only to traffic that reaches the proxy core. In system proxy mode, apps that honor system proxy settings usually send requests to the client; apps with their own proxy settings may use a different path. TUN captures more traffic, but system route exclusions and app behavior still affect the result. Before testing a rule, make a request from an app you know passes through the client and check whether the connection appears in the runtime log. If the log shows no request, a successful or failed visit to the target does not tell you whether the rule matched.
In v2rayN routing settings, duplicate a working configuration before editing it. Note three things: the order in which rules run, the outbound each match selects, and the default route when nothing matches. Put exceptions before broader rules. For example, to send one subdomain through a specific outbound, place its rule before a rule covering the parent domain. Do not infer scope from rule names alone: exact-domain, domain-suffix, and keyword matches cover different targets. A suffix match often includes subdomains that meet its boundary conditions.
Test domain and IP matching separately
Whether the core sees a domain or an IP address depends on the inbound and the form of the destination supplied by the app. If an app resolves the name itself and gives the client an IP, a domain-only rule usually cannot match that address directly. Some inbounds can recover the domain through protocol sniffing, but this depends on the protocol and inbound settings; do not assume sniffing is available for every connection. Conversely, if the inbound receives a domain, an IP rule can match only if the core resolves it for routing. Test IP rules with a direct IP destination and domain rules with a controlled domain. Keep the two results separate.
| Domain strategy | When resolution happens during routing | What to check |
|---|---|---|
AsIs | Does not resolve the destination domain specifically for routing. | Do not expect IP rules alone to match an incoming domain. |
IPIfNonMatch | If nothing matches on the first pass, resolve the domain and try matching again. | An earlier broad match may prevent IP rules from running. |
IPOnDemand | May trigger resolution when a rule requiring IP information is evaluated. | The position of IP-based rules can affect when resolution occurs. |
Use comparison requests to pinpoint a misfiring rule
Suppose you want a local management subnet to connect directly and a test domain to use the proxy. Add an explicit private-network exception, then a rule for the test domain, and finally confirm the default outbound. Prepare three requests: a known management address, a target covered by a named rule, and a comparison domain that is neither managed nor listed in a rule. Make one new connection at a time, recording the inbound, destination form, and outbound tag. Apps may reuse existing connections, so close old connections after changing rules and restart the test app if needed. Refreshing a page over a reused connection does not prove the new policy failed to take effect.
If the explicit exception works but all other targets take an unexpected path, check the fallback rule or default outbound first. If only entries relying on a rule set misbehave, test a minimal rule with an exact domain or explicit subnet. Confirm its order and outbound, then check the rule-set tags and load logs. Do not update rule sets, switch cores, and change DNS at the same time: each can change the outcome and make comparisons inconclusive. For more help reading logs, see Common errors and how to diagnose them.
DNS Configuration: Resolver Sources & Request Paths
Distinguish app, system, and core DNS resolution
Start DNS troubleshooting by finding out who is making the query—not by switching resolvers. Apps using system DNS follow the operating system’s network settings. A browser with its own encrypted DNS may connect directly to its upstream. The proxy core may also resolve names when matching IP-based rules, resolving server addresses, or handling captured DNS requests. These behaviors can coexist. Entering a remote DNS server in the client does not mean every system query will use it. Likewise, a website loading through the proxy does not prove the proxy core resolved its domain.
To establish a baseline, keep your current connection mode and choose one ordinary public domain and one name that must resolve on your LAN. Check that the public name returns a plausible result and that the LAN name still returns an internal address. If the public query works but the internal name fails, first check whether the internal domain is being sent to a resolver that knows only public records. For internal organizational names, use a test target supplied by your administrator and follow network policy; do not send real internal domains to external DNS services for comparison.
Configure upstream resolvers and domain-based rules
In v2rayN DNS settings, first check which core is active and whether it uses a configuration generated by the standard interface or a custom configuration. DNS structures are not interchangeable across cores. If the interface supports assigning resolvers, configure the upstream for internal names first, then the default upstream for regular queries. “Remote” means only that the upstream is not on the local machine; it does not tell you whether requests to it are proxied. For encrypted DNS, also check the address format, the route used to reach the upstream, and how its domain is initially resolved.
If both the proxy server’s domain and the encrypted DNS upstream’s domain rely on a resolution chain available only after the proxy is up, startup can enter a loop: the core needs to resolve the server before it can connect, but the resolver cannot be reached until the proxy is available. A common symptom is a timeout on the first request after changing settings, while an existing connection temporarily masks the issue. To test, restore the previous DNS setup, exit the client, and restart it. Confirm a cold start works before re-enabling settings one at a time. If the original path starts successfully, provide an independently reachable resolver for connection setup rather than simply increasing the timeout.
Compare resolution results and connection results separately
During verification, check the log for DNS errors first, then test the destination connection separately. If there are no usable records, a timeout, or an unexpected address family, check the upstream and query policy. If an address is returned but the connection fails, check whether the outbound can reach it. In a dual-stack environment, a failed connection over one address family does not mean DNS resolution failed. Record IPv4 and IPv6 results, the address the app ultimately chose, and the actual connection error separately. Do not apply a permanent restriction to every resolver and app just to make one test pass.
After changing settings, app, system, and client DNS caches may not all expire at once. Close old connections, test with a controlled name you have not used before or restart the test app, then compare results across paths. If needed, temporarily disable the browser’s own DNS resolution while keeping the connection mode unchanged to help identify the query source. Restore the setting after testing. If results differ only in the browser, check its DNS options before concluding that the system resolution path changed. For test criteria and steps, see DNS leak testing and prevention settings.
TUN Mode: Traffic Capture, Exclusions & Rollback
Choose a capture method for your apps
System proxy settings provide connection details that apps can choose to honor or ignore. TUN uses a virtual network interface and system routes to send eligible traffic through the client’s processing chain. It can cover apps that do not use the system proxy and help investigate app behavior across transport types, but it does not send all traffic through the same outbound. Route exclusions, local interfaces, address-family support, and app-specific connection behavior all affect the path. If system proxy mode already works for your needs, there is no need to add another capture layer just to get the same result.
Before enabling TUN, note your current network interface, LAN access, client connection mode, and DNS settings. Confirm you can disable TUN and restore the original setup. On desktop, start by testing with v2rayN and check whether your operating system requires specific permissions or a service. Android apps v2rayNG and v2flyNG use the system’s network capture capabilities, so their interface terminology may differ from desktop clients. If another virtual network or work network is already capturing traffic, check whether they can run together. On organization-managed devices, ask an administrator to confirm policy rather than removing management components yourself.
Check the interface first, then the apps
After enabling TUN in the client, check the core log for interface creation, route, or permission errors. An enabled switch does not prove the system routes were applied, nor does it mean DNS and UDP are handled the same way. Once the interface is stable, first test a destination that already works through the system proxy, then test an app that does not use it. For a meaningful comparison, note whether the system proxy is on or off. If both are enabled, an app request sent through the system proxy does not prove TUN captured it.
If LAN access fails, first test a known-good management address, then a relevant LAN hostname. If the address fails, check whether its subnet should remain on a direct route, whether it overlaps with the virtual address pool, and which interface the system actually routes through. If the address works but the hostname does not, check the internal DNS path first. Do not exclude a large address range to restore access to a single service. Keep exclusions aligned with the actual local subnet, or other traffic that should be captured may bypass the client too.
Diagnose routing loops and loss of connectivity after switching
If all access fails after enabling TUN, check whether the connection to the proxy server is being routed back through the virtual interface. Disable TUN and verify the server is still reachable. Then check whether the client supports automatic interface selection and, on multi-NIC systems, whether the selected interface is on the active network. An interface binding saved before switching between wired, wireless, or an existing virtual network may no longer be valid. If you must specify it manually, bind only to a verified interface or use a client-supported exclusion, and keep a record of the original setting.
If only one category of app is affected, do not assume the proxy server is at fault. Test short-lived and persistent connections separately, noting whether failure occurs before connection or after data starts flowing. If small requests work but larger transfers often stall, check whether the virtual interface MTU fits the current path while keeping other settings unchanged. If only UDP traffic fails, check TUN capture, client rules, and support for that traffic on the selected outbound separately. To roll back, disable TUN first, then confirm system proxy and DNS settings have returned to their expected state. Re-test sleep or network-switch issues on the same network; restarting the app may restore access, but it does not identify the cause.
FakeDNS: Domain Mapping & When to Use It
What virtual addresses are for
Apps usually resolve a domain before connecting, then pass the resulting IP address to the network interface. If the traffic capture layer sees only that address, domain-based routing has no direct domain to match. FakeDNS handles this by returning a virtual address for captured DNS queries while the core keeps a mapping from that address to the original domain. When the app connects to the virtual address, the capture chain can recover the domain from the mapping for routing or outbound processing. A virtual address is not the destination server’s real DNS record or a fixed outbound identifier. Without the mapping state that created it, the address no longer has its original meaning.
This mechanism depends on two conditions: the query must enter the resolver chain that provides the mapping, and the subsequent connection must return to a processing chain that can recognize it. If only the DNS query goes through FakeDNS while the connection bypasses the client, the app may try to reach an unusable virtual address. Conversely, if an app uses its own resolver and gets a real address, TUN can capture the connection but cannot recover a FakeDNS mapping that was never created. That is why “TUN is enabled” and “the app is using FakeDNS” must be verified separately.
Enable it only after the basic path is stable
With FakeDNS off, first confirm that TUN works, ordinary domains resolve, and LAN services are reachable. Note the active core and DNS setup, then check whether the client provides a complete FakeDNS configuration for that core. Do not copy a virtual address pool field from one core to another, or set the pool without checking DNS rules and inbound domain recovery. After enabling FakeDNS, make a request from a freshly started test app and check that the captured query, returned address type, recovered destination name, and final routing result all line up.
The address pool must not overlap with networks already used by the device, internal organizational routes, or other virtual interfaces. A range not normally used for public services may still be in use on your local network. Check for overlap across the full ranges, not just matching starting addresses. In dual-stack environments, test IPv4 and IPv6 queries separately. Seeing a virtual mapping for one address family does not prove queries for the other use the same path.
Preserve real addresses for internal services
Some apps cache resolution results and pass them to another process or device. Others rely directly on a service’s real address for discovery or access. A successful ordinary web request is not enough to judge compatibility in these cases. For internal domains and services that require real addresses, first check whether the configuration can use regular DNS for those domains, then compare with an address you know is reachable. Do not try to fix this by adding the virtual address range to direct-routing rules; that skips the domain recovery step that should happen first.
If the first visit works after enabling FakeDNS but requests time out for a while after restarting the core, the app may still have a cached virtual address whose mapping no longer exists in the new process. To roll back, disable FakeDNS, restore the regular upstream, reconnect the client, and clear old connections and relevant caches in the test app. Do not treat results from an uncleared cache as proof that the policy is still working. If you can confirm traffic capture but not domain recovery and internal service access, regular DNS is easier to maintain. For more on address pools and compatibility, see How FakeDNS works and what to check before enabling it.
Manage Multiple Subscriptions: Refresh, Switch & Roll Back
Separate sources by group; do not merge entries by note
A single group controls how a set of servers is imported. Managing multiple subscriptions ensures other sources stay available when one source has a problem. Create separate groups for different sources, using stable names to distinguish primary, backup, and test subscriptions. If one source offers two formats, import them separately for testing before deciding which to keep. Identical notes in different groups do not mean the entries point to the same server. Different addresses, protocols, transports, or authentication parameters can change how they connect. Do not bulk-delete entries with the same display name just to tidy the list.
Before updating in v2rayN, check which group the active connection uses and whether an update will replace that group’s existing entries. If the current server is in the primary group about to be refreshed, verify a connection using the backup group first, then update the primary. If you need to keep manually edited server entries for testing, put them somewhere subscription refresh will not overwrite, and confirm the changes comply with the source’s terms. Do not confuse a subscription definition with a local-only edit; on reimport, the client will generally use the definition returned by the source.
Choose a clear network path for updates
A subscription update is a request to access the subscription URL; it is separate from connecting to a server in the list. One subscription may update directly while another is reachable only through a working connection. Determine the update path for each source before using batch refresh. If the client offers only one network path for the whole update operation, manually refresh groups with special requirements rather than applying one group’s network conditions to every source. For intermittent failures, note whether they follow waking the device, switching networks, or changing servers before adjusting the refresh schedule.
Set the auto-update interval according to how often the source changes, provider limits, and the scheduling options the client supports. Refreshing too often amplifies brief outages, rate limits, and DNS issues; it does not guarantee you will get updates as soon as servers change. Before enabling auto-update, complete at least one manual refresh and confirm it does not remove backup groups, and that you can distinguish failure, an empty result, and intentional deletion. If the client has no per-group scheduling, a predictable manual refresh order is more reliable than assuming background updates will always run on time.
Use a repeatable group-switching routine
Choose an ordinary public destination as a connection baseline, then prepare a second destination for the service you need to test. After switching servers, request the baseline first to confirm the inbound and outbound work, then test the service destination. This helps distinguish an unavailable server from a rule that does not apply to a particular target. If your test needs UDP, separately test a real UDP service you use; a working web page does not prove every protocol and outbound works. Record the group and note used before and after switching, but never include subscription URLs with credentials, full configurations, or share links in public troubleshooting reports.
If the primary group suddenly becomes empty after a refresh, pause auto-update for that group or stop refreshing repeatedly. Leave other groups unchanged, then use the comparison steps in Subscription Groups & Filters to find the cause. If the backup group still works, keep the working connection and investigate the primary source separately. If the backup fails too, check shared dependencies such as the system network, resolver, capture mode, and certificate time before editing servers one by one. When moving settings to Android, confirm the subscription supports the relevant core; do not assume desktop routing or auto-update settings transfer directly. For common installation and switching issues, see FAQ.
Custom Outbounds: Tags, Rules & Minimal Configuration
Decide when a custom configuration is needed
An outbound defines how a connection is handled; routing rules define when a request is sent to that outbound. On desktop, simply switching the active subscription server usually works with the outbound generated by the interface. Maintain a custom configuration only when different destinations genuinely need different handling or you need to verify that core fields work as expected. First check the configuration mode for the current v2rayN entry and the selected core. Temporary configurations generated by the interface may be rebuilt when you switch servers or restart. Editing those files is not maintainable; keep a separate file the client can import and note which entry loads it.
With a custom file, do not assume routing, DNS, or inbound settings from a regular subscription entry will be merged into it. Check the scope of the active mode: does the core read the entire file independently, or does the client generate an outer configuration? Then verify that every outbound tag is unique, that each rule references a tag that exists, and which outbound handles requests that match no rule. A tag has no network behavior by itself: writing direct does not create a direct connection, and writing proxy does not import a server from your subscription.
Test direct and blocked connections on localhost
The following is a complete minimal configuration that can be given directly to the Xray core. It creates a SOCKS inbound accessible only on the local machine, sends unmatched destinations directly using the first outbound, and routes the exact domain example.net to a block outbound. The example needs no remote server or credentials. It is for testing rules and tags, not a snippet to append to any client-exported file. If the port is already in use, change it in both the configuration and the test app’s connection settings.
{
"log": {
"loglevel": "warning"
},
"inbounds": [
{
"tag": "local-test",
"listen": "127.0.0.1",
"port": 11080,
"protocol": "socks",
"settings": {
"auth": "noauth",
"udp": false
}
}
],
"outbounds": [
{
"tag": "direct",
"protocol": "freedom",
"settings": {}
},
{
"tag": "reject",
"protocol": "blackhole",
"settings": {}
}
],
"routing": {
"domainStrategy": "AsIs",
"rules": [
{
"type": "field",
"inboundTag": ["local-test"],
"domain": ["full:example.net"],
"outboundTag": "reject"
}
]
}
}
Load the configuration with the selected Xray core, then point a SOCKS-capable test app to 127.0.0.1:11080 and make sure it sends the domain—not a pre-resolved address—to the SOCKS inbound. A connection to example.net should be blocked; another known-reachable public domain should connect directly. If both targets fail, first check the listening port and whether the test app is using this endpoint. If the block does not happen, check whether you used a different hostname, the app resolved it locally, or an old connection was reused. This example does not enable UDP or test TUN; do not use it to assess app UDP support.
Extend the minimal file one step at a time
To add a remote outbound, use the protocol and transport parameters provided for a server you are authorized to use. Add a uniquely tagged entry under outbounds, then add a narrowly scoped domain rule that references it. Keep the existing direct and block tests unchanged. First confirm the new rule selects the new outbound, then test the remote handshake separately. Supported protocol and transport combinations depend on the core; changing only the protocol name does not make old authentication and transport fields valid. Before choosing a protocol, see VMess and VLESS: authentication, encryption, and transport differences, then check the actual configuration supplied by your source. For chained outbounds, also verify that the proxy server’s domain resolution and connection path can be established independently of the new outbound.
Keep the custom file separate from your everyday configuration, and retain the client entry you have already verified. Before routing real traffic through it, run three checks: does the target reach the expected inbound, does the match select the expected tag, and does the outbound connect successfully? If only one stage fails, roll back that stage alone. If the core fails to start, switch back to your everyday entry and restore the original system proxy or capture settings before testing the custom file without live traffic. A configuration that reproduces a minimal test case is more useful for troubleshooting than a full setup that happens to work only on one device.