CONFIGURATION MANUAL

v2rayN Advanced Setup Guide

Check settings to understand their scope; use connection results to see where they take effect.

Use this page after establishing your first connection. For installation, importing a subscription and checking connectivity, start with the Getting Started guide. To switch platforms or reinstall, choose the right package from the Download Center. v2rayN is the recommended desktop client, and the GUI instructions below use it. The JSON examples follow Xray's configuration format; don't paste them into editors for other cores.

Setting names may differ between client interfaces and cores. Change one layer at a time, then retest the same app and destination. First check whether the entry was imported, then whether traffic reaches the expected inbound, and finally verify DNS results and outbound selection. For beginner issues such as an empty list or startup failures, see 10 Common v2rayN Questions from Beginners.

Subscription Groups and Server Filters

Understand the difference between source groups, list search and import filters

A subscription group keeps its source URL, update options and imported server entries together. Search above the server list only narrows the current view; it doesn't clear the subscription cache. A filter in the group editor may instead skip non-matching entries during updates. The same search term in both places can produce different results. Group names identify sources in the client and don't affect protocol connections. Name groups by their purpose and source, and never put access tokens from URLs in group names, screenshots or support logs.

Open the subscription group settings from v2rayN's “Subscription Group” menu, add a source and save, then select that group in the main list. Choose the current subscription from the update menu rather than updating everything at once. For the first update, keep all original entries and leave filters blank. When it finishes, clear the list search and confirm that at least one entry in the group works. Then note how this source names its servers. Establish a complete baseline first so you can tell whether entries disappear because the provider changed them, importing failed or a local filter removed them.

Build filters from complete server remarks

Filters usually apply to server remarks, not addresses, protocol properties or custom group names. If the current interface supports regular expressions, test against a remark you know exists before applying the pattern more broadly. For example, if remarks begin with “Home” followed by whitespace or a hyphen, the expression below also matches a remark that is exactly “Home.” Enter it directly in the regex field, without the slash delimiters used in some programming languages. If the field accepts plain text only, use a distinctive, stable term and check the results individually.

^Home(?:[\s-]|$)

Don't infer filter behavior from the option name. Depending on the interface, matches may be kept, excluded or used only for display. Before saving, read the field hint. After updating, check one remark that should be kept and one that should be excluded. Full-width punctuation, em dashes, leading spaces and capitalization can all affect matches. To allow several prefixes, group the alternatives and place the start anchor outside the group. Avoid starting with an overly broad expression and patching it with exceptions; if the source changes its naming, it becomes hard to tell why entries are included.

When a filter is set at the group level, changing it usually requires updating that group; existing entries may not be recalculated immediately. Save a copy of the original rule locally and note which entries are in use before updating. Some sources rebuild group entries during an update, changing their internal IDs and potentially invalidating your selection. Select the entries again afterward and test a connection. Base filters on naming maintained by the source, not local remarks that may disappear after an update. Keep independently maintained configurations separate from auto-updated groups.

Use logs to diagnose an empty list

If the list is empty after an update, first check the update log to see whether a response was received. A timeout, an invalid URL and content that can't be parsed are different problems. For a timeout, check your network, update method and whether the URL is still valid. For a parsing error, check whether the source returned a subscription format the client recognizes rather than a login page or error message. If parsing succeeded but no entries were imported, clear the group filter and refresh that group alone. Then check whether the wrong group is selected or a search term is still active. Don't replace several sources with the same URL, and never post a full subscription URL in a public report.

If some entries from the same source import successfully, check the log for skipped types, then distinguish unsupported formats from remarks that didn't match the filter. Temporarily narrow the filter to one verified remark to see whether the rule is the cause. If disabling the filter restores entries but they still won't connect, investigate the entry's protocol settings, the selected core and the connection log instead of repeatedly changing the filter. Organize other groups only after this source is stable. See Managing Multiple Subscriptions for ways to update groups separately and keep backup sources.

Routing Rules in Practice

Match addresses as they reach the core

Routing determines which rule a connection matches and which outbound handles it. It doesn't enable proxying for an app, nor can it match requests that never reach the core. In v2rayN, open the routing settings and confirm that the ruleset being edited is enabled in the main window before changing rule order. The system proxy, an app's own local proxy setting and TUN can send connections through different inbounds. For troubleshooting, hold one entry path constant; changing all three at once can make results look random.

First determine whether the core receives a domain name or an IP address. When an app passes the domain to a local proxy, domain rules can match it directly. If the app resolves the name itself before connecting, the inbound may see only the destination IP. Traffic sniffing can sometimes recover a domain from a familiar protocol handshake, but only when the request includes recognizable information; it isn't a universal substitute for passing the domain. If the log shows only an IP, check the app's proxy settings and whether sniffing is active on the inbound. Then decide whether the app should pass the domain or whether to add a subnet rule for a controlled range of addresses.

Put exceptions before broader rules

Xray checks routing rules in order; the first match determines where a connection goes. To send one exact maintenance domain directly while proxying other connections under the same suffix, put the full-domain rule first and the suffix rule after it. full: matches an exact name; domain: matches the specified domain and its subdomains. Use separate rules to express the two priorities. Different fields in a single rule generally all have to match: for example, specifying both a domain and a port matches connections to that port on that domain, not either condition independently.

This Xray routing snippet demonstrates rule order with the reserved domain example.net. Merge it into the test configuration's existing object with the same name; don't replace the entire ruleset. Both tags must exist in outbounds and point to the intended destinations. If your interface uses different tags, substitute those rather than creating duplicate outbounds with the same names. The example hosts under this reserved domain don't depend on publicly accessible services. To verify matching, substitute a test domain you can resolve and reach.

{
  "routing": {
    "domainStrategy": "IPIfNonMatch",
    "rules": [
      {
        "type": "field",
        "domain": ["full:maintenance.example.net"],
        "outboundTag": "direct"
      },
      {
        "type": "field",
        "domain": ["domain:example.net"],
        "outboundTag": "proxy"
      }
    ]
  }
}

Check what happens when no rule matches

AsIs doesn't resolve domains for routing matches. IPIfNonMatch resolves a domain if it matches no rule, then tries address-based rules. IPOnDemand triggers resolution when matching a rule that requires an IP address. The domain strategy isn't the outbound's final DNS resolution strategy. A DNS entry in the log doesn't tell you whether the connection ultimately went direct or through a proxy. If a catch-all rule at the end covers all traffic, an earlier rule may already match, so don't expect IPIfNonMatch to retry preceding IP rules.

Test an exact domain, a different host under the same suffix and a host outside the rule's scope. Then use the logs to verify the inbound and outbound tags. If no rule matches, Xray uses the first outbound in the configuration by default, so changing outbound order can also affect unmatched connections. If the log shows only the first outbound, check for a missing match condition or an inactive ruleset. Initiate a fresh connection as well: existing long-lived connections may not be rebuilt immediately with the new rules, so reusing an old session can skew the test.

If traffic is routed incorrectly, save or copy the current rule order, then temporarily move the new rule and retest. If the rule is at fault, narrow it to one controlled domain before expanding it to a suffix, subnet or port range. If the log reports a missing domain or IP data file, fix the reference or restore the original data-file source rather than rewriting the entire routing setup. To verify the exact request path, compare logs for the same request; don't rely on homepage stats or general impressions of connectivity to judge an individual rule.

DNS Configuration

Identify which layer is making the query

The browser, operating system, proxy core and remote proxy can all resolve domain names. Even resources on the same page may use different paths. A system lookup tool shows only the resolver it actually uses; the browser and core may get different answers. On the same network, choose a stable public domain and an internal domain you are authorized to use. Record the system results and core logs for both. If the system resolves a name but the proxy app fails, first check whether the app passes a domain or an IP to the proxy. Don't immediately replace the system resolver.

In v2rayN's parameter settings, confirm which core is actually in use, then open its DNS settings. Native, custom and client-generated configurations have different entry points. If a standalone custom configuration is running, changes to ordinary settings may not be merged into it. After saving, inspect the active configuration and reload the core if needed. In the logs, note the queried domain, returned address type, whether the query timed out and which outbound handled the request. This helps distinguish a failed lookup from an unreachable address or a query sent through the wrong outbound.

Limit dedicated resolvers to specific domains

Internal services often need an internal resolver to return private addresses, but not every domain has to follow the same lookup path. This Xray snippet is for a test environment with an existing local DNS service: port 5353 on localhost handles lab.example.net and its subdomains; other queries can use the system resolver. This isn't a configuration for a listening server and won't start one. Before using it, confirm that the test resolver listens on the corresponding loopback port. The system resolver must not depend on this Xray DNS setup through another setting, or the lookups will loop.

{
  "dns": {
    "servers": [
      {
        "address": "127.0.0.1",
        "port": 5353,
        "domains": ["domain:lab.example.net"],
        "skipFallback": true
      },
      "localhost"
    ],
    "disableFallbackIfMatch": true
  }
}

skipFallback keeps this server out of general fallback; disableFallbackIfMatch prevents fallback to a general resolver when a dedicated domain scope matches. This can expose failures in internal-domain lookups instead of silently returning a different answer from another resolver. If independent network testing confirms that redundancy is needed, add a resolver that knows the same internal records rather than removing the restriction. Also note that built-in DNS handles only queries actually sent to it. Adding this snippet alone won't redirect every system request or app-managed lookup.

If the upstream uses an encrypted DNS endpoint identified by a domain name, the client must first be able to resolve and reach that endpoint. Don't send this initial lookup to the same upstream before the connection is established. If DNS traffic uses a proxy, also check that the proxy server's own domain can be resolved independently. Record these two dependencies before configuring dedicated and general resolvers. Otherwise, the logs may show a string of timeouts that look like an upstream outage, even though no connection has left the machine. For troubleshooting, temporarily return to a known-working DNS setup, verify proxy connectivity, then restore the encrypted upstream.

Test address families, cache and connectivity separately

Change query strategies only after confirming how each address family works on your network. An app may request both IPv4 and IPv6 addresses; getting both doesn't mean both paths are reachable. If a page takes a long time to open, check the logs to see which queries completed and which connections timed out, then choose a strategy that suits the app. Don't disable an entire address family as a first step. Cached results can also make a change appear ineffective. Exit the test app or clear its DNS cache, flush the system cache if needed, then start a new connection. An old page still loading isn't proof that the change worked.

To roll back, restore the original server order, domain scopes and query strategy—not just one address. If the failure occurs only with TUN enabled, check which DNS queries the virtual adapter intercepts. If the response is a clearly synthetic address, see FakeDNS for how it interacts with routing. Slow performance may also be a node or network issue. Follow A Layer-by-Layer Guide to Troubleshooting Slow Speeds and use the same destination to distinguish DNS delays from transfer time after the connection is established.

TUN Mode

Establish a system proxy baseline first

The system proxy works only when apps use the configured proxy settings. TUN starts a virtual network adapter and passes packets matching system routing conditions to a traffic-interception component. The adapter being present doesn't mean all traffic goes through it: OS route priorities, excluded subnets, other virtual interfaces and apps bound to physical adapters can all change the outcome. Before enabling TUN, use v2rayN in system proxy mode to test a browser, then choose an internal service you're authorized to access as a comparison. Record the results and connectivity for both on the original network so you can identify which path changed.

Before testing, disable other clients that modify system routes or DNS. On a network managed by your organization, follow its policies and don't change centrally managed settings. For the first test, don't change the server, routing rules, DNS and TUN parameters at the same time. Prefer to restore the system proxy to its original state so the same app isn't explicitly connecting to a local proxy while also being affected by virtual adapter rules. If you must keep other adapters enabled, record their status and purpose so you can check whether disabling TUN restores the original path.

Enable the adapter and check what it captures

In v2rayN, select a working server and confirm the current routing setup, then enable TUN in the main window. Creating an adapter or changing system routes requires system authorization; follow the prompts from the client and OS. If a startup warning appears, check the client log for adapter creation and route changes instead of repeatedly toggling the switch. The traffic-interception component may use a different core from the server connection. Saving an Xray configuration successfully doesn't mean that component accepted the same inbound, DNS or exclusion settings. Check each component's logs separately.

Use the read-only commands in the table below to inspect system routes. They are for comparison and don't replace logs. Check before and after enabling TUN, focusing on which interface handles the proxy server, internal services and an ordinary destination. Implementations may divide the captured traffic using more specific prefixes or policy routing, so the default route alone can't tell you whether traffic is being intercepted.

SystemCommandWhat to check first
Windowsroute printInterface list, active routes and metrics.
macOSnetstat -rnDestination subnet, next hop and interface name.
Linuxip route show table all、ip rule showRoute table and interface referenced by policy rules.

If every destination times out after TUN takes over, first check whether connections to the proxy server itself are being routed back through the virtual adapter. If they need to bypass it, use the interception component's interface binding or exclusion options so the server connection uses the actual network interface. Excluding a fixed IP may not work long-term if the server uses a domain name. If only local network services stop working, check whether their subnets were incorrectly routed through the virtual adapter. Adjust only the subnets you need; don't bypass every private address or send all internal traffic through the proxy.

Troubleshoot DNS, UDP and MTU separately

If a known IP address is reachable but its domain name isn't, check whether the interception component sends DNS queries to the expected resolver. If regular web pages work but a real-time app doesn't, check its transport protocol, whether the inbound receives the relevant packets and whether the selected outbound supports that traffic. Consider MTU only if small requests work but larger transfers stall. Compare with TUN disabled, note the original value and make incremental changes on a clearly defined test path, reconnecting each time. Speed-test fluctuations alone don't prove an MTU problem.

When testing is done, disable TUN first. Check that the adapter and routes have returned to baseline, and restore the system proxy if its original purpose requires it. If internal domains still resolve incorrectly, inspect the current system DNS settings and check whether any processes are still running. Don't blindly delete unfamiliar interfaces or routes. Test again after sleep or a Wi-Fi network change, since the interface and next hop may have changed. For more symptom comparisons, see Configuring the TUN Virtual Adapter.

FakeDNS

Trace synthetic addresses back to their original domains

FakeDNS returns a synthetic address, not the target server's real address. The component returns an address to the requester while storing a mapping between that address and the domain. When the app connects to the address, the interception inbound must receive the connection and recover the domain from the same mapping. Only then can routing use the domain and the selected outbound connect to the actual destination. This is often useful when an app resolves a domain before sending packets. FakeDNS changes how a domain is preserved and recovered; it doesn't speed up all DNS queries or guarantee that every app uses the same inbound.

First get TUN working with FakeDNS disabled, and verify that ordinary DNS, inbound interception and domain rules each work. Then confirm that the component answering DNS and the one receiving packets share the same mapping. If another component handles interception, check its supported settings and configuration format; don't paste Xray fields into its editor. If your test environment lets you observe only one component's logs, at minimum record the returned address at the requester and check at the inbound whether the subsequent connection reached the expected process.

Keep the address pool, DNS routing and inbound recovery in sync

The following three snippets are specific to Xray. They define a test address pool and enable synthetic resolution only for lab.example.net. When merging them, keep other resolvers and existing routing rules. First confirm that the pool doesn't overlap with a real network, another virtual adapter or a corporate test subnet. The example range is for testing and may not suit every live environment. Pool capacity isn't a limit on concurrent connections; it affects how many domain mappings can be stored. If the pool fills up or the process restarts while an app still has an old synthetic address cached, old pages and new queries may behave differently.

{
  "fakedns": [
    {
      "ipPool": "198.18.0.0/15",
      "poolSize": 4096
    }
  ],
  "dns": {
    "servers": [
      {
        "address": "fakedns",
        "domains": ["domain:lab.example.net"],
        "skipFallback": true
      },
      "localhost"
    ],
    "disableFallbackIfMatch": true
  }
}

The Xray inbound receiving connections to synthetic addresses needs the corresponding sniffing settings. Merge the fields below into the experimental inbound object; don't add another inbound or enable them globally. If that inbound already has other sniffing types, merge rather than overwrite them. This test needs to recover the actual destination domain to establish a connection, so the example doesn't use routeOnly, which is only for routing decisions. After enabling it, check that traffic from the synthetic pool actually reaches this inbound. A synthetic DNS response alone doesn't prove the connection followed this path.

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

An outbound connection needs the real destination, so it mustn't query the same synthetic range and receive another address from the pool. In your test, verify that the actual connection uses a DNS path that returns a real address—for example, remote DNS resolution by the proxy or a direct outbound using a resolver that returns real records. The proxy server's own domain must also stay outside the synthetic range. Preserve the original resolution path for internal file services, device discovery and apps that rely on real addresses for access control. Consider expanding the test scope only after confirming those services still work.

Use three checkpoints to locate the failure

First, check whether the DNS query returns an address from the pool. If it doesn't, the app may be bypassing the intercepted DNS path or the test domain may not match the configured scope. Second, check whether the connection reaches the intended inbound. If the returned address is in the pool but the inbound logs show nothing, check whether routing sends the pool through the actual interception interface. Third, check whether the routing log shows the recovered domain. If the inbound receives the address but can't recover the domain, rule out a stale cached address, an expired mapping or different processes handling DNS and the connection before changing domain rules.

To roll back, remove both synthetic DNS routing and the interception settings that depend on the synthetic pool. After restoring ordinary DNS, make the test app query again; clear the system cache if needed and close processes holding old connections before testing the same domain. If domain recovery is disabled but synthetic addresses are still being returned, requests may be sent to an unrelated interface by ordinary address rules. Changing DNS while reusing an old cache can look the same. A successful rollback means the app gets an ordinary address and the request follows its original path—not merely that a setting appears to be off.

Managing Multiple Subscriptions

Manage update sources separately from their use

First separate sources by how they update, then choose entries by purpose. Two URLs from the same service may share update limits; two entries with the same remark may belong to different accounts or use different transport settings. Don't put everything in one batch-updated group just to keep the list tidy. Use group names that identify the source without exposing account details, and keep local notes on each group's purpose, update method and support channel. Whether a source is a useful backup depends on its actual dependencies, not the region in its remark or its position in the list.

Add each URL in the group settings and update one group at a time. After checking the import results, select an entry from that group in the main list and inspect the connection log before moving on. If the interface offers a batch-update option, enable it only after manual testing succeeds. Groups used occasionally or maintained by hand can remain separate. Put manually managed entries with no update URL in their own group. Manual edits to the server list may not survive the next update, so store important independent test configurations separately and note why they differ from the source.

Plan update paths that don't depend on each other

A subscription update is a separate request; it isn't the same as successfully connecting with an entry. If the client lets you choose whether updates use the current proxy, check which path works for each source. Watch for circular dependencies—for example, when updating requires the current node, but that node can't be restored until the subscription updates. Keep a verified access path, or test from a network where the source is reachable without a proxy. If an update fails, don't immediately delete entries that still work locally. Check whether the problem is a connection failure, expired authorization, rate limiting or a change in response format.

For scheduled updates, follow each source's permitted frequency. Stagger updates across groups or run them manually. If a batch update fails, test one group at a time and note which group failed and which network path was used. Distinguish automatic updates at startup from updates you started yourself so the logs don't show results from another task. An empty result for one group doesn't mean every group needs to be rebuilt. Check that group's source content and filter conditions before deciding whether to update the rest; this limits the impact of a batch refresh.

A source update can change ports, protocol settings and remarks—not just add entries. Matching names don't guarantee identical configurations, and different names don't necessarily mean different routes. To deduplicate, compare protocol, server address, port, transport settings and purpose locally. Start within one group to avoid losing a backup entry by deleting across groups. Even if two groups ultimately connect to the same service, renewal and update mechanisms may differ. Preserving source boundaries is often more useful than keeping only one display name.

Make switching and rollback easy to retest

Before updating, note the current group, active entry and routing setup. Afterward, check that familiar entries are still present, explicitly select the one you want to use and start a new test connection. If a backup group works but the main group fails, test both against the same destination with the same routing settings; don't change the network mode at the same time. A successful connection with a different speed only shows that this test took a different path. To compare performance, separate connection setup time from transfer time and repeat under the same conditions. Don't permanently delete a source based on one list order or test run.

Before migrating or rolling back, back up the configuration using the client's supported method and restrict access to the backup. It may contain subscription URLs, account identifiers and server connection settings; don't share it in group chats or store it in a public directory. For rollback, restore only the affected group and leave the others unchanged. Then decide whether to stop its existing auto-update schedule. If you can restore only the entire configuration, save a copy of the current one first so you don't overwrite routing or DNS changes made since the restore point. Finally, confirm that the entry used for the actual connection matches the logs; don't rely on the selected group label alone.

Custom Outbounds

Understand outbound objects and rule references

An outbound object defines how the core handles a connection. Its tag is just the name rules use to refer to it; the action comes from protocol and its settings. Naming a tag direct doesn't make it connect directly—the configuration must use the corresponding direct protocol. Before adding an outbound, list the inbound, rules, destination and fallback path for unmatched traffic. If you only need to change where existing traffic goes, reuse an existing outbound. Add a new object only when it genuinely handles traffic differently; that avoids duplicating settings that then need maintenance in multiple places.

The client generates ordinary GUI configurations, and edits to files in the runtime directory may be overwritten when you switch servers or restart. If using v2rayN's custom configuration option, first choose a core that matches the configuration format and import a complete test file. Before running it, check whether the client requires separate settings for listening ports and management options. A complete custom configuration isn't an outbound added to the current subscription entry; existing routing, probes and DNS settings may not be merged automatically. Keep the original setup and run only one listener during testing.

Test direct and blocked traffic through a loopback inbound

This is a complete minimal Xray test configuration for checking tag-based routing through a SOCKS inbound accessible only from the local machine. It doesn't depend on a remote proxy or change the system proxy. Before testing, stop any process using the port or choose an unused local port for the test configuration and update the request commands to match. The configuration blocks one exact domain and sends other requests directly through the first outbound. This helps distinguish a routing match problem from a remote connection issue. It's an isolated test file; don't overwrite your active configuration.

{
  "log": {
    "access": "access.log",
    "loglevel": "warning"
  },
  "inbounds": [
    {
      "tag": "local-test",
      "listen": "127.0.0.1",
      "port": 10808,
      "protocol": "socks",
      "settings": {
        "auth": "noauth",
        "udp": false
      }
    }
  ],
  "outbounds": [
    {
      "tag": "direct",
      "protocol": "freedom",
      "settings": {}
    },
    {
      "tag": "block",
      "protocol": "blackhole",
      "settings": {}
    }
  ],
  "routing": {
    "domainStrategy": "AsIs",
    "rules": [
      {
        "type": "field",
        "inboundTag": ["local-test"],
        "domain": ["full:example.org"],
        "outboundTag": "block"
      }
    ]
  }
}

If Xray is installed locally and available from the command line, save this configuration as config.json in a test directory where logs can be written. Run the first command below to check that it loads, then the second to start it. In a separate terminal, run both requests. If curl is aliased to another command in your shell, explicitly invoke the actual curl executable. --socks5-hostname passes the domain to the inbound, preventing it from being resolved first and missing the exact-domain rule. The direct request also depends on local access to the destination; don't assume a particular remote response.

xray run -test -config config.json
xray run -config config.json

curl --max-time 10 --socks5-hostname 127.0.0.1:10808 https://example.org/
curl --max-time 10 --socks5-hostname 127.0.0.1:10808 https://example.net/

The first request should use block; the second should select direct. Exact error messages vary by system and tool. If both fail, first check whether the process is listening on the port and whether access logs show requests reaching the inbound, then check outbound tags and the system network. If both succeed, make sure the environment's NO_PROXY setting didn't bypass the proxy and that the running process is using this configuration. Keep only the logs needed for testing, noting the inbound, destination and outbound. Avoid retaining full access logs longer than necessary.

Check dependencies and rollback before adding a real outbound

When adding an authorized remote outbound, use a unique tag and set its protocol parameters according to the server's actual configuration. First route a narrowly scoped test rule to that tag; don't immediately change the first outbound. Check how the server's domain is resolved, whether its endpoint is reachable and whether its own connection is being sent back through the virtual adapter. If multiple outbounds are combined in one configuration, verify that each connection's required upstream is available; don't make two paths depend on each other as upstreams. Starting successfully only proves the configuration loaded—it doesn't guarantee a remote handshake or a successful request to the final destination.

Before deleting an outbound, remove or update every rule that references it, then delete the object and reload. If outbound order changes, retest requests that match no rule. When you're done, stop the test process, restore the normal client configuration and confirm that the expected process is listening on the local port. Restore the system proxy or TUN as needed. For future troubleshooting, start with one inbound, one rule and one known destination. Once a single path is reproducible, add subscriptions, DNS and traffic interception back into the full chain.