Configuration Reference / v2rayN
Advanced v2rayN Configuration Guide
For your first installation, importing a subscription, or testing a connection, start with the Quick Start. This guide assumes you already have a working connection and breaks settings down by subscription source, traffic entry point, name resolution, and outbound route. v2rayN is the recommended desktop client. If you still need an installer, check the platform and architecture on the client downloads page.
Subscription Groups and Server Filtering
Label the source before organizing names
In v2rayN, open “Subscription Group Settings” and add a note to each subscription that identifies its source and purpose, such as “Daily use” or “Maintenance backup.” Notes help identify groups; they do not rewrite server addresses or become routing conditions. Even if you change a local note, the server records returned by the provider still depend on the subscription URL. Likewise, identical server names in two subscriptions do not prove that they share a source URL or connection settings. When organizing the list, group by source first, then review server notes. This is easier to verify than renaming entries one by one in the “All” view.
Treat manually added servers separately from subscription-managed records. If you need to keep a test configuration long term, do not leave it only in a list that may change when a subscription refreshes. Confirm how to retain it locally before cleaning up subscription groups. If the client lets you copy a configuration into a separate group, check that the new record no longer depends on subscription updates; otherwise, maintain it as a standalone configuration. Do not use display order to mark frequently used servers: a source update may change both the order and the notes. Selecting a record is also different from making it the active server, so check the active status in the main window after changing it.
Keep display filtering separate from update filtering
Use list search for temporary lookups; clearing the search should bring the existing records back. A filter in subscription settings may affect imports or updates, determining which records enter the group during that operation. The two require different checks: testing list search does not require another update, while testing a subscription filter means updating the target group and checking which records remain. If the interface has separate list-filter and subscription “Filter” fields, use their help text to confirm what each does. Do not assume they are the same persistent rule.
If the filter field in your version explicitly supports regular expressions, start with a simple pattern. The expression below matches notes ending in “Backup” or “Test,” with optional trailing whitespace. It does not determine whether those records are kept or excluded; that depends on the field’s documented behavior. Test it against one note you expect to match and one you expect not to match. Do not use a full subscription URL, account identifier, or connection settings as test data. A regular search box recognizing a pipe character is not evidence that it supports regular expressions.
(Backup|Test)\s*$
Recover from an empty list and restore a verifiable state
If a group is empty after an update, first clear list searches and other view filters, then check the update log for parsed records. A failed fetch, an empty parse result, and a filter that removes everything can all look like “no new entries,” but each needs a different fix. For a failed fetch, check the network route used for the update and whether the subscription is still valid. For an empty parse result, check the format returned by the source. If filtering removed everything, temporarily clear the filter expression, update only the current group, and count the records again. Do not start by updating every group; changes elsewhere can make it harder to identify the setting responsible.
If only a few records remain, check whether the note format has changed. An added suffix, full-width parentheses changed to half-width, or a tag moved from the end to the beginning can all cause an existing expression to miss records. Narrow the expression to a naming convention that is genuinely stable. If the source has no stable format, use temporary list search rather than relying on an overly specific import rule. Filtering can organize display or import results; it cannot determine protocol compatibility or replace a connection test. Once the list is restored, verify the active status and a real request using a server you know works.
Routing Rules in Practice
Distinguish the traffic entry point from outbound matching
Routing rules only handle traffic that has reached the core. When a browser uses the system proxy, its requests may enter through the client; apps that do not use the system proxy usually will not enter through the same path automatically. Before deciding a rule is ineffective, confirm that the app’s connection actually passes through the client. For comparison, configure the app to use the client’s local proxy listener, or check the TUN entry point on platforms where it is supported. Routing rules are not a global operating-system network switch; changing a rule will not send processes that bypass the client into the core.
In v2rayN’s routing interface, select the rule set currently in use before editing an individual rule. A new rule set that has not been enabled will not take over the running configuration. In Xray’s order-based routing, put narrow exceptions first, general rules afterward, and a catch-all last. Multiple match fields in one rule usually need to match together. If you want “this domain or this IP range to go direct,” create separate domain and address rules rather than expecting a rule with both conditions to mean “or.”
Verify rule order with controlled domains
The following is a replaceable routing object for an Xray configuration, not a complete configuration. Keep the existing entry points and other fields, and make sure the corresponding outbound tags direct and proxy already exist. The example sends a public example domain and its subdomains through the direct outbound, and all other TCP or UDP traffic through the proxy outbound. In practice, replace the example domain with one you are authorized to test and can reach reliably. If editing in a GUI, fill in the relevant fields rather than pasting the entire object into a single domain field.
{
"domainStrategy": "AsIs",
"rules": [
{
"type": "field",
"domain": ["domain:example.com"],
"outboundTag": "direct"
},
{
"type": "field",
"network": "tcp,udp",
"outboundTag": "proxy"
}
]
}
Use domain: to match a domain and its subdomains; use full: for an exact hostname match. If the entry point receives only an IP address, AsIs will not reverse-resolve it to the requested domain, so a domain exception may not match. Some entry points can recover a domain from recognizable connection data, but results depend on the protocol, entry-point settings, and traffic. Do not assume sniffing can recover the domain from every connection. To cover connections made directly to a literal IP, add a separate address condition for a target you have confirmed you manage.
Check matches and outcomes in order
Test rule matching first, then test the service. Open new connections to both an exception target and a target that does not match the exception. If logs show the entry point, destination, or outbound tag, check each one. Browsers reuse pooled connections, so a page continuing to load does not prove that a new rule took effect. Close old connections or use a clean test session. Once the tag is correct, check whether the connection actually completes. If direct is selected but the service is unreachable, the destination may not be accessible on the current network. Before changing the tag, confirm which route should reach that destination.
If you use geosite or geoip lists, check whether the asset file exists, whether the category includes the target, and whether rule order is correct as separate items. Category data changes over time, so a category name alone does not prove that a particular domain is included. For troubleshooting, compare against an explicit domain rule first, then decide whether to restore the list. When no rule matches, Xray typically uses the first outbound in the outbound list. The example has an explicit catch-all to avoid relying on list order. Record the old rule set before saving so you can revert if a broad change causes problems instead of layering on more exceptions.
DNS Configuration
Start with the layer that actually makes the query
On the same device, the operating system, browser, and proxy core may all resolve names. System DNS serves apps that use the operating system’s resolver; a browser may have its own Secure DNS; and Xray’s dns object provides resolution within the core. They may use different upstreams and return different answers. If the system network panel still shows the old address after you change the client’s DNS settings, that alone does not mean the change failed. First identify which layer supplies the app’s answer, then inspect that layer’s query path.
Also distinguish the destination domain from the proxy server’s domain. The destination domain is the service the app wants to reach; the server domain may need to be resolved before the proxy connection can be established. If resolving the server domain depends on the very proxy that has not connected yet, you can create a loop. When troubleshooting, first confirm that the server can be resolved and connected to independently, then adjust the lookup policy for destination domains. “Which outbound carries the DNS request?” and “Which outbound carries the final connection?” are separate questions; do not use the answer to one to infer the other.
Set the upstream, address family, and scope of the change
The following is a minimal Xray dns reference object. Put it in the top-level dns field of a complete configuration. The example specifies a public DoH service by IP address, avoiding an extra dependency on resolving the upstream hostname, and limits queries handled by this part of the core to IPv4. The upstream must still be reachable over the path used to make the query. On networks with enterprise DNS or internal zones, retain the resolvers required by your organization. This object does not automatically route every app’s DNS through the core or change the DNS settings of the system resolver.
{
"servers": ["https://1.1.1.1/dns-query"],
"queryStrategy": "UseIPv4"
}
| Check | What it does | How to verify |
|---|---|---|
servers | Set the upstream for core DNS | Compare core logs with upstream reachability |
queryStrategy | Limit the address families used for core queries | Compare A and AAAA records with actual reachability |
| Browser Secure DNS | Control the browser’s own resolution path | Retest with the same app and destination |
Requesting IPv4 only can help isolate a problem, for example, to check whether failures are caused by an unreachable IPv6 path. If a destination is IPv6-only or the local network relies on IPv6, this setting may omit necessary answers and is not a general-purpose optimization. With dual-stack enabled, resolving an address does not guarantee that the system has a usable route to it. Check both address families for the same destination and note whether the query returned no answer, the connection failed to establish, or the app retried on an existing connection. Do not judge a DNS policy by how quickly a page loads once.
Verify caching, split DNS, and fallback behavior
Some names on a corporate network should be resolved by an internal resolver. A public upstream may return a different answer or no answer at all. Choose one internal destination and one public destination for comparison, then verify the resolver, the network where each answer applies, and the actual connection path. For split DNS, first define which names the dedicated upstream handles, then set the default upstream for other domains. Do not let public DNS override internal corporate records, and do not assume that different answers for the same domain from different network locations are necessarily wrong.
After a change, verify with a new connection and account for separate system, browser, and core caches. Command-line lookup tools often query a specific resolver directly; they can verify the upstream response but cannot by themselves prove that the app uses the same path. If the issue appears only in a browser, check that browser’s Secure DNS and cache. If it occurs only with TUN, check whether TUN actually handles DNS. To roll back, restore the original upstream and routing rules, then retest the original samples. If resolution succeeds but the page still will not load, use the FAQ to distinguish a connection problem from an application-layer error.
TUN Mode
Decide why the app needs a virtual interface
The system proxy provides a forwarding entry point for apps that follow proxy settings. TUN uses a virtual network interface and operating-system routes to receive selected IP traffic. It is often used for desktop apps without their own proxy settings, but whether traffic reaches it still depends on system routes, client configuration, and app behavior. TUN does not add another proxy route or replace routing rules in the core. Think of it as changing the traffic entry point: rules can decide whether to go direct, through a proxy, or elsewhere only after traffic reaches that entry point.
First confirm that the active server works in v2rayN’s current mode, then check the “Enable Tun” control in the main window. Permissions, virtual-interface setup, and core implementations can vary across desktop platforms; follow the client’s prompts and your system’s administrative procedures. Do not disable system-wide protections just to troubleshoot. If macOS shows a warning when opening the app or requesting permission, read the macOS installation and network permissions guide first. Determine whether the issue is app launch, system proxy, or network permission rather than treating all three as the same failure.
Switch modes while changing one variable at a time
Before enabling TUN, note the original system proxy state, active server, and current routing set. If possible, turn off the system proxy for the test app if it would otherwise be intercepted twice, and make sure you are clearing only the settings added by this client—not an existing organization proxy. Pause other routing tools you manage that might conflict, and leave the server and DNS settings unchanged. After enabling TUN, check that the client and core started, then confirm that the virtual interface appeared, and finally verify that test traffic actually enters it. Checking these three in order is more reliable than changing more settings as soon as a toggle changes color.
Test at least two kinds of destinations: a request from an app that should use the proxy, and a service that should use the local network. If a public destination works but a printer or internal service does not, distinguish name resolution from address reachability. An address may be reachable on the same device while an app that depends on local network discovery still cannot find the service. Multicast, broadcast, and link-local communication differ from ordinary web requests, so a working webpage does not prove that device discovery works. Keep the system routes required by local services, compare against the exclusion options the client actually supports, and check for overlapping subnets on another virtual interface.
Troubleshoot lost connectivity, loops, and resume from sleep
If enabling TUN causes widespread connectivity loss, turn it off and confirm the previous mode works again. Then enable it once more and capture the earliest error. If interface creation fails, check permissions, drivers, and competing virtual interfaces first. If the interface is created but connections keep retrying, check the default route and the proxy server’s own outbound path. If traffic used to connect to the server is sent back into the same virtual interface, a loop may result. Check how the client protects its own connections and which physical interface it uses; do not mask an entry-point problem by routing every destination direct.
If only a few apps have problems, check whether they reused connections opened before TUN was enabled, then compare address families and transport types. Small web requests may work while long-lived connections or larger transfers stall; this can be related to the maximum packet size supported by the path. Do not blindly enter interface settings copied from online posts. Record the original value, confirm the environment, and test one change at a time. After the device wakes from sleep or changes networks, recheck the default route and virtual-interface status. If connectivity still fails after TUN is disabled, check whether the system proxy still points to a local port and whether routes added by the client have been removed.
FakeDNS
Understand what synthetic addresses are for
FakeDNS returns a synthetic address for queries matching its criteria and records the mapping between the domain and address in the core. The app then connects to that address. If the connection returns through the entry point that holds the mapping, the core may be able to recover the original domain and apply domain-based rules. This does not mean the remote service is actually at the synthetic address, nor does it eliminate all real DNS lookups when a connection is made. For direct connections or outbounds that need a real address, the actual destination still needs to be resolved at the appropriate layer.
FakeDNS depends on a complete loop between the query and the subsequent connection. If an app uses its own resolver outside the system and gets a real address, the synthetic flow may never happen. If it gets a synthetic address but the subsequent connection bypasses the client, the mapping cannot be used. The latter often looks like a lookup tool returned an answer but the app cannot connect. Before enabling FakeDNS, establish a repeatable baseline with ordinary TUN and DNS. Confirm that the target app sends queries through the expected DNS entry point and sends subsequent IP connections to the same core that can recover the mapping.
Scope, mapping pools, and exclusions
The following is a minimal reference snippet for Xray’s top-level fakedns field, showing how to specify an address pool and capacity. It defines the pool only; it does not enable synthetic resolution by itself. The full flow also requires the core DNS to use FakeDNS for selected queries and the connection entry point to enable sniffing that can recover the domain. If the GUI client already generates the relevant configuration, inspect what is there rather than adding a second pool to the same entry point. Available GUI options depend on the client and selected core.
{
"fakedns": [
{
"ipPool": "198.18.0.0/15",
"poolSize": 4096
}
]
}
Keep the pool range distinct from addresses used by local subnets, test networks, and other virtual interfaces. The example range is for reference and is not guaranteed to be conflict-free on every device. Bigger is not always better: the mapping must remain available for as long as the app uses the synthetic answer, while frequent lookups and long-lived app caches increase the risk of mismatches or expired mappings. Start by testing a clearly defined set of domains, then expand the scope. Apps that need real addresses for local discovery, corporate sign-in, or device management should keep their existing resolution path; do not include internal services in the first test.
Find the missing link from the symptom
If you do not see a synthetic answer, first check whether the app has its own resolver or cache, then confirm which DNS entry point actually received the query. If you get a synthetic answer but routing does not show the original domain, check whether the app’s connection enters the right interface, whether the entry point has the required domain-recovery capability enabled, and whether the app’s address still has a valid mapping in the current pool. If the correct domain and outbound tag appear but the connection fails, investigate the outbound and resolution of the real destination instead of repeatedly changing pool capacity.
Do not verify a website’s identity by opening a synthetic IP in a browser. Connecting directly to an IP changes the request semantics and may omit the hostname the app would normally send. Have the app open a new connection to the original domain, then check the recovered domain and matched outbound in the logs. When you finish testing and disable FakeDNS, restore the original DNS selection before ending test sessions that may still hold synthetic answers. Clear caches as needed using the app’s and system’s normal procedures. If the client has restarted but the app reused an old synthetic answer, query again rather than expecting a new process to reuse the previous mapping automatically.
Managing Multiple Subscriptions
Separate sources, updates, and everyday switching
When you have multiple subscriptions, create one group per source. Group notes can define their purpose, such as daily use, short-term testing, or keeping an older configuration. Do not pack the provider, current connection quality, and protocol type into one name: the source is relatively stable, connection quality changes over time, and protocols may change with upstream updates. A group note only needs to answer “Where did these records come from, and why keep them?” Server notes identify entries within a group; there is no need to repeat the group name in each one.
When adding a source for the first time, update that group manually. Check that it returns a parseable list, the entries look as expected, and common protocols are compatible with the selected core before enabling automatic updates. Use v2rayN on desktop. On Android, do not choose between v2rayNG and v2flyNG based only on interface similarity. Check the subscription’s protocols, transport settings, and core support together; see Xray vs. V2Fly: Core Differences. Seeing a record only means the client recognized enough information to display it; it does not guarantee runtime support for that combination of settings.
Set clear limits for update failures
Automatic updates are best for stable sources that you have already verified with a manual update. Choose an interval based on the provider’s allowed frequency and how often it actually changes; frequent refreshes are not a way to check server status. Update sources separately where possible so each error can be traced to a specific group. The network request that updates a subscription is not the same as using a server from that subscription to establish a proxy connection. An update can fail while existing connections still work, and a newly updated server may not yet be tested. Track these states separately.
If the interface offers multiple update routes, first test the target source using a route you know is reachable. When updating through the current proxy, consider whether there is an independent recovery path if that proxy fails. Before switching to a direct update, confirm that the source allows it and is reachable from that network. Do not clear all groups just because one subscription failed. Keep existing working entries, identify whether the failure occurred during the request, response parsing, or import, and then decide whether to pause automatic updates for that group alone.
Handle content changes, duplicates, and URL rotation
Upstream updates may add or remove records, rename them, or change their settings. Identical names do not necessarily mean duplicates, and different names do not necessarily mean separate routes. Before cleanup, compare at least the protocol, address, port, and transport method; never copy credentials into public records. If you are unsure whether a refresh replaces or merges entries, manually update one group and compare the active server, new entries, and entries that disappeared. If an important route vanishes, do not immediately change the entire routing setup. Restore connectivity using a verified backup source, then investigate the changes in the original group separately.
When a subscription URL changes, if possible, put the new URL in a separate group for a short test: update it, check protocol compatibility, and complete a real request from an app. Once it is confirmed as a replacement, stop updates for the old group and remove its records if needed. If the source does not allow both URLs to coexist, record the group name, filter conditions, and selected server first, and keep another verified connection path before replacing the URL. Subscription URLs often contain account credentials. For troubleshooting, share only the group note, failure stage, and a sanitized error—not the original URL or a full export.
The same boundaries apply when moving to another device. Migrate one essential source first and confirm it works with the client and network there, then move over filtering and automatic update settings. Active servers, system proxy state, and local interfaces differ between devices; importing a list alone cannot reproduce the entire runtime environment. When you finish, keep a maintenance note without connection secrets: source purpose, update method, test destination, and the last issue successfully resolved.
Custom Outbounds
Define the role before choosing where to configure it
An outbound describes how the core handles a connection it has already received. It can connect directly through the system network, forward traffic using a specified proxy protocol, or explicitly reject the connection. Routing rules refer to outbounds through outboundTag. Server records are how the client manages connection settings; outbounds are execution objects in the runtime configuration, and the two do not always map one-to-one. Custom outbounds are useful when you need stable references to multiple handling paths. For a temporary switch of the active server, the main window’s active server and routing set are usually enough.
First check which settings the v2rayN interface lets you edit and whether you are running a client-generated configuration or maintaining a complete configuration yourself. A runtime-generated file edited directly may be overwritten the next time you save, change servers, or restart. If you maintain a complete file through a custom configuration option, you are also responsible for the relationships between entry points, DNS, routing, and outbounds; do not assume every GUI setting will be merged automatically. Before you start, keep a configuration that launches successfully and note the local listening ports and current routing set so you can confirm that apps reconnect through the right entry point after rollback.
Combine outbounds and routing with explicit tags
The following is a top-level Xray configuration snippet that defines two outbounds with different behavior. direct uses freedom to connect directly, while blocked uses blackhole to reject connections. This is not a complete configuration with an entry point, and it does not include a proxy server. When merging it, keep the existing outbounds and add the required objects to the same array. If a tag already exists, reuse it or rename it deliberately rather than pasting in a duplicate. Tags referenced by routing rules must match those strings exactly.
{
"outbounds": [
{
"tag": "direct",
"protocol": "freedom",
"settings": {}
},
{
"tag": "blocked",
"protocol": "blackhole",
"settings": {}
}
]
}
The connection is rejected as intended only when a rule matches blocked. For testing, choose a destination where interruption is acceptable, add a specific rule for it before the usual catch-all, and make a new connection for comparison. Do not use the operating system’s connectivity-check target to test blocking; system status indicators may then diverge from actual reachability. If the configuration has no explicit catch-all rule, check the first item in the outbound array. Changing array order can send traffic that matches no rule to a different outbound, even if the rules themselves are unchanged.
Check startup, rule matching, and actual connectivity
Collect evidence in three stages. First, confirm that the core accepts the configuration: check that it parses, the current core supports the protocol, and tag references match the local listening settings. Second, confirm that requests reach the intended outbound: test two destinations, one that matches the new branch and another that should stay on the existing branch. Third, confirm that the outbound can complete its task: check network reachability for a direct route, the server’s resolution and connection for a proxy route, and that a reject rule affects only the test scope. A successful startup does not prove that routing is correct, and a matched tag does not prove that the remote destination is reachable.
When adding a real proxy outbound, do not copy a protocol name from another core’s configuration and expect it to work. Check the current core’s configuration format, transport and security settings, the resolution path for the server address, and supported transport types. If timeouts occur, compare under the same conditions using an outbound you have already verified. If only the new outbound fails, investigate that branch instead of changing system DNS or expanding TUN coverage. Verify each change with a new session to avoid misdiagnosis caused by reused connections.
After testing, archive configuration according to its purpose: keep a recoverable full configuration in a protected location, and share only troubleshooting notes with rule order, field names, and sanitized errors. A short note about why a change was made—for example, “Moved the internal test domain ahead of direct-route exceptions”—is more useful than a stack of unexplained test configurations. For tag and rule concepts, see the glossary. If even the basic entry point is no longer reliable, restore the configuration first, then return to the connection checks in the Quick Start.