From Zero to Advanced V2Ray Complete Guide

CHAPTER 01

Core Concepts: Separate the Core, Client, and Configuration First

Where V2Ray, V2Fly, and Xray Fit

Before configuring anything, the key is not memorizing menu locations but placing several commonly used names in the right layers. V2Ray generally refers to the proxy technology ecosystem and configuration model developed by Project V; V2Fly continues and maintains one of its core branches; Xray is another core implementation in the same technology family. The core parses configuration, creates inbounds and outbounds, performs protocol handshakes, applies DNS policies, and forwards traffic according to routing rules. It usually runs in the background and does not directly manage graphical functions such as subscription lists, tray menus, or the system proxy switch.

v2rayN, v2rayNG, and v2flyNG belong to the client layer. They turn subscription management, server selection, log viewing, and proxy modes into an interactive interface, then call the selected core to handle connections. For desktop systems, v2rayN is the primary choice and supports Windows, macOS, and Linux. On Android, v2rayNG with the Xray core is preferred; choose v2flyNG when you specifically need the v2fly core branch. Once this relationship is clear, you can tell whether a problem belongs to interface settings, subscription content, core startup, or the network environment instead of repeatedly reinstalling the entire client.

What Makes Up a Connection

A configuration capable of establishing a connection contains at least three logical parts: inbounds, outbounds, and routing. An inbound describes how local applications hand traffic to the core, such as a local SOCKS port, an HTTP proxy port, or data received through a TUN virtual network interface. An outbound describes how the core handles traffic; common tags include proxy, direct, and block. Routing sits between them and selects an outbound based on the domain, IP, port, network type, or inbound tag. Graphical clients generate part of this configuration, so you do not need to write a complete file for everyday use, but understanding the structure makes logs and rule checks much easier.

A server entry provides the address, port, identity information, protocol, and transport parameters needed for a remote connection. The protocol defines how both sides exchange data; the transport layer determines whether the data travels over TCP, WebSocket, gRPC, or another channel; security parameters such as TLS or REALITY further constrain the handshake. Any mismatch in a critical field can prevent the connection. A client being able to import a link does not mean the configuration is valid: import only confirms that its syntax was recognized. Actual usability still depends on DNS resolution, network reachability, system time, and the remote service state.

A Subscription Is Not a Protocol, and a Node Is Not a Client

A subscription URL is an entry point for distributing configuration. The client requests the URL, receives a set of server entries or structured configuration, and converts the result into a list. The subscription does not forward traffic and does not represent a particular protocol. A common mistake is treating “subscription updated successfully” as “the proxy is enabled.” The former only means that the client retrieved and parsed the list; the latter also requires selecting a server, starting the core, and directing application traffic into a local proxy or TUN inbound.

“Node” is the conventional interface term for a server configuration entry. An entry may contain VMess, VLESS, Trojan, or other protocol parameters, and may offer different transport combinations for the same remote endpoint. To judge whether an entry fits the current environment, first confirm that the client core supports its protocol and transport; then check whether the address resolves and the port is reachable; only afterward inspect the routing mode. Do not infer an entry’s purpose from its name alone: the display name is usually just a note supplied by the subscription provider and does not participate in the handshake.

The Full Path from an Application Request to a Remote Outbound

Using a browser request as an example: the browser first resolves the domain, then follows the operating system proxy settings to send the request to v2rayN’s local listening port. After the core obtains the target domain and IP, it matches routing rules from top to bottom. A match for direct sends the request through the local network, proxy sends it through the active server outbound, and block stops forwarding. If the application does not read the system proxy, the request never enters this path. In that case, configure a proxy inside the application or use TUN to capture its network traffic.

This explains why a client can show “running” without producing any actual proxy effect. Running only confirms that the core process exists; the system proxy may be disabled, the application may bypass system settings, or routing may send the target direct. Conversely, one website loading does not prove that every rule is correct, because that site may simply have taken the direct path. Validate the configuration by checking client logs, system proxy status, and the routing result for the target request instead of looking only at whether one page loads.

CHAPTER 02

Client Selection and Installation: Build a Stable Starting Point for Each Platform

The Three Clients and Their Boundaries

For desktop platforms, v2rayN is the primary choice. It brings subscription groups, server lists, system proxy, routing rules, TUN, and logs into one workspace, making it suitable for progressing from a basic connection to complex split routing. On Windows, choose either the desktop edition or the classic WPF edition based on the interface you prefer. The former uses a cross-platform desktop interface, while the latter retains the classic Windows workflow. Their core purpose is the same, and they should not run at the same time. On macOS and Linux, use the v2rayN package for the relevant platform and select the package format according to the processor architecture and distribution.

On Android, v2rayNG is the primary choice and uses the Xray core. Its configuration concepts are close to the desktop version, but traffic capture is handled through the system VPN interface and the navigation is more compact. v2flyNG is an alternative client using the v2fly core, suitable when a configuration specifically requires that core branch. Both Android clients can be installed separately, but only one system VPN session should be active for everyday connections to prevent conflicts over capture permissions. Complete packages and platform notes are available on the download page.

Confirm architecture and permissions before installation

Processor architecture determines whether an installation package can start. Common Windows and Linux desktop computers usually use x64; ARM-based devices need arm64. On macOS, check the chip or processor field in System Information: select the Apple Silicon package when Apple silicon is shown, and x64 when Intel is shown. On Android, check the ABI in device information or a hardware inspection page. Most current mainstream devices support arm64; if you cannot confirm, use the universal package, which is usually larger.

Installation permissions affect the system proxy, virtual network interfaces, and service registration. A normal system proxy usually only changes settings for the current user; TUN mode must create a virtual network interface and adjust the routing table, so it may request administrator authorization. Authorization should occur when the user actively enables the relevant feature. If the client opens but TUN cannot start, check permissions and driver status before changing the server protocol. Enterprise devices may also centrally manage proxies or network extensions; handle those restrictions within the system administration boundary.

Minimum Checks After First Launch

When opening the client for the first time, do not enable every option immediately. First confirm that the main interface renders correctly, that the core path is visible in settings, and that the log window opens; then import a subscription. The v2rayN interface typically includes subscription groups, a server list, system proxy, and routing settings. v2rayNG centers on the configuration list, the selected entry, and the connection button. Keep the system proxy disabled at this stage so installation issues remain separate from configuration issues.

Next check the system time, time zone, and basic network status. Handshakes involving TLS and REALITY are sensitive to clock skew, and an incorrect system time may appear as a certificate or handshake failure. First use a direct connection to confirm that ordinary websites and DNS work, then start the client. If the current network requires a captive-portal login, complete it first, since the login page is often more reliable before the proxy starts. After switching networks, wait for the system to obtain a new address and DNS information before reconnecting.

Windows PowerShell
Get-Date
Get-NetIPConfiguration
Test-NetConnection example.com -Port 443

macOS / Linux
date
curl -I https://example.com

These commands only verify the local clock, network-interface configuration, and basic HTTPS connectivity; they do not determine whether a proxy server works. If the basic connection already fails, restore local networking first. If it works but the client core cannot start, inspect configuration parsing and port usage. This prevents repeatedly changing subscription entries while the network itself is disconnected.

Upgrades, Parallel Installations, and Configuration Directories

Before upgrading the client, stop the running core and record the current subscription groups, routing mode, and custom rules. Client configuration is usually stored in a user or application-data directory, with the exact location depending on the platform and installation method. Before an in-place upgrade, use the client’s backup or export function to save important settings. Do not treat cache files, logs, or the server list as your only backup. A subscription URL can be refreshed, but manually added servers, routing rules, and DNS settings may not be recoverable from the subscription.

A computer can retain different interface editions for migration testing, but do not let two clients listen on the same local port or modify the system proxy simultaneously. Port conflicts commonly appear in logs as “address already in use” or a listen failure. When switching clients, first clear the system proxy set by the old client and exit it completely, then start the new client. If an abnormal exit leaves a proxy address behind, disable it in the operating system network settings before enabling it again from the client.

CHAPTER 03

Subscription Import: Retrieve Configuration and Create Groups

How Subscription URLs Work and How to Store Them

A subscription URL is usually an HTTPS URL whose path or query parameters contain a token used to identify an account. It lets the client periodically retrieve a server list, so treat it like account credentials and do not publish it on public pages, screenshots, or in logs. When copying the URL, preserve every character from the scheme to the end, and make sure a chat tool has not truncated the query parameters. The client stores the URL, not the webpage body; seeing encoded text or a download response after opening it in a browser does not mean the URL is invalid.

https://example.com/sub?token=xxxx

The address above shows only a common structure. Actual subscriptions may use different paths and parameter names. When importing one, do not manually remove apparently unnecessary equals signs, slashes, or percent-encoded characters, as they may belong to the token or signature. If the copied value ends with spaces or line breaks, remove those invisible characters first. When a subscription URL is rotated, edit the existing group instead of creating duplicate groups repeatedly, so old and new servers do not become mixed in one list.

Importing and Updating in v2rayN

On desktop, create a subscription group first, then place the URL in the group settings. Open the relevant subscription-group menu, enter a group name and subscription URL, save, and run an update. The group name is only for local identification, so name it by purpose or source; it does not affect the remote response. After a successful update, the server list is generated from the subscription. If the update policy removes old entries, the new result replaces the group’s previous entries, so manually added servers should be kept in a separate group.

After updating, check that the entry count is reasonable, the protocols are recognized, and address and port columns are present before selecting an active server. Do not click update repeatedly while a request is in progress: concurrent requests may trigger rate limits and make the logs harder to read. For multiple subscriptions, create one group per source and set update intervals as needed. For further organization, see multi-subscription groups and keyword filtering to manage groups, filters, and routing purposes separately.

Importing in v2rayNG and v2flyNG

Android clients generally let you add the URL in subscription settings, return to the main screen, and run an update. The system must allow the client to access the network; battery restrictions, background-data limits, or broken Private DNS can all cause the request to fail. After the update, entries appear in the main list and one must be selected as the active configuration. Selection only determines which configuration will be used for the next connection; it does not establish a system VPN session. Start the connection and confirm that the VPN indicator appears in the status bar.

Maintain subscription data for v2rayNG and v2flyNG separately. Although some common sharing links can be recognized by both, the two cores may differ in their support timelines for newer protocol fields and extensions. If a configuration cannot be parsed by one client, first check whether it contains fields unsupported by that core instead of assuming the entire subscription is invalid. If the subscription offers entries tailored to different cores, use the one matching the client.

The Difference Between Update, Parse, and Connection Success

A subscription update has three independently testable stages. First, the HTTP request succeeds, meaning the client can reach the URL and receive a response. Second, the content parses successfully, meaning the returned format can be converted into server entries. Only the third stage selects an entry and establishes a proxy connection. A normal response with an empty list usually points to content format, account status, or filtering conditions. A populated list whose entries all fail to connect requires checking server parameters, time, DNS, and the current network.

Read log errors by stage. A domain-resolution failure means the subscription domain did not return an IP; a connection timeout means the request did not complete in time; unauthorized or forbidden responses usually involve the URL token, account status, or request policy; a parse failure means the response is not in the format expected by the client. If the client is configured to update subscriptions through a proxy that is itself unavailable, the update can form a dependency loop. Temporarily switch to direct updates while troubleshooting, then restore the original policy after the update succeeds.

Grouping, Filtering, and Deduplication

Groups are useful for more than visual organization: they define the scope of update and deletion operations. Keep work, everyday browsing, and test configurations separate so updating one source does not overwrite another group. When server names include region or purpose keywords, use the client’s filtering feature to narrow the list. Filtering changes only what is displayed or selected; it does not alter the remote configuration. Observe naming patterns before creating a filter, so a broad keyword does not select unrelated entries.

Duplicate entries commonly result from importing the same subscription multiple times, duplicate responses from the subscription service, or retaining an old group during migration. First identify each entry’s group, then remove the old source. Do not bulk-delete by display name alone, because different configurations may use the same note. If old entries remain after an update, check whether the group uses an append policy. For long-term maintenance, let automatic updates manage subscription entries and keep manual configurations in a separate group; their lifecycles differ, and mixing them increases the risk of accidental deletion.

Shortest Diagnostic Path for a Failed Subscription Update

First disable the option to update subscriptions through a proxy and make one request over the current direct network. Then check that the URL is complete, the system time is correct, and the subscription domain resolves. If only one URL fails while others work, the issue is more likely its permissions or response. If all URLs fail, inspect DNS, leftover system proxy settings, and security-software network policies. If no servers appear after an update, check whether name filtering is enabled or whether the response was identified as a web error page.

Do not repeatedly delete and reinstall the client to fix a single subscription error: reinstalling does not change the remote response or repair an incorrect URL. Keep one failed log, identify the request stage and status, and then decide whether to edit the URL, change the update network, or adjust resolution. For more focused issues, browse Frequently Asked Questions under “Installation and Configuration” and “Troubleshooting”.

CHAPTER 04

Proxy Modes: Decide Which Applications Hand Requests to the Client

System Proxy and Core Routing Solve Different Problems

The system proxy sends requests from applications that honor the operating system proxy settings to the client’s local port. Core routing then decides whether a request that has entered the client goes through the proxy, direct, or block outbound. The former controls “whether it enters”; the latter controls “where it goes afterward.” Many confusing configurations come from treating them as one switch: even if routing selects the proxy globally, an application that ignores the system proxy will not enter automatically; even with the system proxy enabled, routing may send a specific target direct.

v2rayN’s “auto-configure system proxy” mode suits browsers and desktop applications that follow system settings. Once enabled, the client points the operating system proxy address to its local listening port. Clearing the system proxy removes that setting; “do not change system proxy” starts only the core, leaving other applications to connect to the local port manually. PAC mode uses a rule file to return different proxy decisions to applications. For everyday use, start with automatic system proxy configuration and combine it with core routing for split traffic; this is the easiest path to understand.

Understanding Global, Rules, and Bypass-Mainland Modes

In a client interface, “global” usually means that traffic entering the core uses the proxy outbound by default. It is useful for briefly isolating routing problems, but it does not force every application to be captured. Rule mode matches the routing table one rule at a time, commonly sending local networks, private addresses, and selected domain sets direct while sending other requests through the proxy. Bypass-mainland mode is a preset rule combination that typically sends mainland China domains and IPs direct and proxies other targets. Presets make it easy to get started, but check real applications for misclassification.

Choose a mode based on the task. For everyday browsing, rule mode or bypass-mainland mode usually avoids unnecessary proxy paths. To debug whether a target is misclassified, temporarily compare it with global mode. To proxy only one development tool, leave “do not change system proxy” selected and enter the local SOCKS or HTTP address in that tool. For comparisons and typical scenarios, read the differences between system proxy, global, and bypass-mainland modes.

Local SOCKS and HTTP Ports

The core commonly provides both SOCKS and HTTP local inbounds. SOCKS forwards TCP and may support UDP depending on the client implementation; an HTTP proxy is better suited to applications with native HTTP CONNECT support. Ports are generated by the client configuration, so do not copy fixed numbers from another tutorial. When configuring a separate application, read the local listening address and actual port from the current client settings. The host is typically the loopback address 127.0.0.1, which prevents exposing the local proxy to the LAN.

Application settings also distinguish “proxy DNS” from “local resolution.” Some SOCKS clients resolve domains locally and send only the IP to the proxy; others send the domain through the remote link for resolution. The former may bypass core routing rules based on domains, while the latter preserves domain information more effectively. When an application offers an socks5h-style mode, hostname resolution usually travels to the proxy with the SOCKS request. Choose the option that matches the core’s DNS and routing policies.

HTTP_PROXY=http://127.0.0.1:local-http-port
HTTPS_PROXY=http://127.0.0.1:local-http-port
ALL_PROXY=socks5h://127.0.0.1:local-socks-port

These lines illustrate the structure of the environment variables. In actual use, replace the text port names with the numbers shown by the client. Command-line tools use the proxy only when they read these variables; closing the terminal or clearing them may restore direct connections. Do not configure conflicting proxy sources at the same time, such as system proxy, environment variables, and an in-app proxy pointing to different clients, because the request path becomes difficult to determine.

How to Confirm That the System Proxy Is Working

First confirm in the v2rayN status bar that the system proxy is set to automatic configuration. Then open a page in a browser that follows the system proxy while watching the client access log. A new connection in the log shows that the request entered the core. If there is no log entry, check whether the browser uses its own proxy, whether a direct policy is active, or whether it inherited environment variables from an old process. Fully quitting and reopening the browser can eliminate some connection-pool and proxy-setting caches.

If the log contains the request but the target fails, inspect the routing tag and outbound error. A direct match means the rules chose a direct connection; a timeout after reaching the proxy outbound points to the remote link or network. If direct access still fails after disabling the system proxy, the operating system may retain an old address. Check the manual proxy fields in network settings, clear unused loopback addresses and ports, and let the client configure them again.

How Mobile Devices Capture Traffic

v2rayNG and v2flyNG receive application traffic through the system VPN interface, so you do not need to configure each browser’s system proxy separately. After tapping connect, the system requests a VPN session; once allowed, the client determines traffic paths using routing and per-app settings. A connection icon only shows that the interface exists; use logs to confirm that the active configuration connected to the remote server. After switching networks, entering power-saving mode, or running in the background for a long time, the system may reclaim the process. Check battery optimization and background-run permissions.

Per-app proxying limits which applications enter the client, making it useful for separating work applications from other traffic. During setup, distinguish “proxy selected apps only” from “bypass selected apps”; their meanings are opposite. Reconnect after changing the list so the system reloads the routing. If an application has its own proxy configured, avoid creating a second forwarding layer with the system VPN; restore the application’s default network settings before testing.

CHAPTER 05

Split Routing: Choose Outbounds by Domain, IP, and Inbound

Rules Match from Top to Bottom

The key to routing rules is not their number but their order. The core usually checks the list from top to bottom. Once a request matches a rule, it uses that outbound and stops checking later ordinary rules. Put narrow, clearly intended rules first and broad fallback rules later. For example, block advertising domains before a general domain-proxy rule, and send LAN and private addresses direct before the default proxy. Reversing the order can produce incorrect results even when every rule is syntactically valid.

Domain rules work only when the core has access to the target domain. If an application resolves locally and submits only an IP, geosite rules may not match, leaving geoip or other IP rules as the only option. Conversely, IP rules require a resolution result, so the DNS strategy and returned address affect them. Stable split routing requires the application inbound, DNS, and routing to be designed together rather than copying a rule list in isolation.

geosite, geoip, and domainStrategy

geosite matches domain-based rule sets. For example, geosite:cn denotes the corresponding domain collection, while geosite:category-ads-all is commonly used for advertising domains. geoip matches IP collections: geoip:private targets private addresses and geoip:cn targets the corresponding regional IPs. Rule data is updated with the client or core resources. If the logs say a collection is missing, check that the resource files are complete and that the tag is supported by the current data set.

domainStrategy determines when routing resolves a domain to an IP. AsIs favors matching the original domain and does not proactively resolve it for IP rules. IPIfNonMatch resolves an IP only after domain rules fail to match, then continues matching. IPOnDemand resolves more proactively when a rule needs an IP. For everyday mixed domain-and-IP routing, IPIfNonMatch is common because it preserves domain matching while allowing later IP rules to work; the final choice should also account for DNS configuration and performance.

{
  "routing": {
    "domainStrategy": "IPIfNonMatch",
    "rules": [
      {
        "type": "field",
        "domain": [
          "geosite:category-ads-all"
        ],
        "outboundTag": "block"
      },
      {
        "type": "field",
        "ip": [
          "geoip:private"
        ],
        "outboundTag": "direct"
      },
      {
        "type": "field",
        "domain": [
          "geosite:cn"
        ],
        "outboundTag": "direct"
      },
      {
        "type": "field",
        "ip": [
          "geoip:cn"
        ],
        "outboundTag": "direct"
      }
    ]
  }
}

This JSON shows a routing object that can be placed in an Xray configuration, provided the complete configuration defines outbounds named block and direct. The default proxy is usually selected by the client when no rule matches, or explicitly assigned by a final broad fallback rule. Before copying the snippet, verify the outbound tags generated by the client. Different clients may use different tag names, and a mismatch causes the core to report a missing outbound at startup.

Build a Minimal, Explainable Rule Set

For an initial custom setup, keep only four intentions: block clearly unwanted domain sets, send private networks direct, send explicitly chosen domains and IPs direct, and send everything else to the default proxy. For every added rule, be able to answer “what does it match, why is it here, and which outbound handles a match?” If you cannot, leave it out for now. A huge rule set from an unknown source adds update dependencies and makes misclassification harder to locate.

Direct access to private addresses is especially important. LAN printers, router administration pages, file shares, and local development services usually sit in private ranges and should not be sent through a remote proxy. Besides geoip:private, you can add rules for target ports, inbound tags, or explicit ranges. When accessing the LAN through TUN, also confirm that virtual-interface routes have not overridden the local link. Direct is only the core’s decision; the operating system routing table must still be able to reach the target.

Refine Routing by Domain, Port, and Process

Custom domains can use full names, subdomain suffixes, keywords, or regular expressions. Prefer full-domain and suffix matching because the results are easier to predict. Keywords can match unrelated sites, while regular expressions should be kept simple and documented. Port rules are useful for limiting a specific service, but a port alone cannot identify website ownership; the same port may carry many services. When combining domains and ports in one field rule, the conditions usually apply together, so confirm the core’s matching semantics before configuring it.

Process-based routing depends on platform capabilities and the client implementation. Even when the interface offers process-name rules, permissions, process spawning, and containers can affect detection. Process rules are best used as supplementary desktop controls, not as a replacement for domain and IP rules. Application updates may change executable names or paths and invalidate older rules. During maintenance, verify the actual process identification in the logs rather than checking only that the rule still exists.

DNS Leaks and Misaligned Routing

If a target domain is resolved directly by local DNS while the connection itself uses a proxy, the resolution request and application connection follow different paths. This can produce regionally inconsistent results, lose domain information needed for routing, or cause resolution failures. The solution is not simply changing the DNS address; define which DNS servers resolve which domains and which outbound carries those DNS requests. Core DNS, system DNS, browser secure DNS, and TUN DNS interception may all coexist, so minimize duplicate layers.

During troubleshooting, first disable the browser’s independent DNS feature and test through the unified system-and-client path. Then check whether the target domain remains visible in logs, which outbound carries the DNS query, and whether the returned address enters the expected IP rule. For further checks, read V2Ray DNS leak testing and configuration in practice. After changing DNS, clear system and application caches and reconnect; otherwise old results may continue to affect the diagnosis.

Post-Change Routing Checklist

After saving routing changes, reload the core and confirm that the logs show no field, tag, or resource errors. Visit one target expected to go direct, one expected to use the proxy, and one LAN address. Check each request’s domain, IP, and outbound tag. Finally, switch networks and test again to rule out DNS caches and old connection pools. If only one application ignores the rule, check whether it reads the system proxy, uses independent DNS, reuses an old connection, or has QUIC enabled.

Keep a short explanation and reason for every routing change. Record it directly when the client supports notes; if you edit JSON, keep the intent in external documentation rather than adding comments to strict JSON files. Confirm whether a rule is required by another inbound before deleting it. Long-term stable rule sets are often shorter because explicit defaults and a few exceptions are easier to verify than layers of overlapping rules.

CHAPTER 06

TUN Mode: Capture Traffic That Ignores the System Proxy

The Fundamental Difference Between TUN and System Proxy

A system proxy depends on applications actively reading the operating system settings. TUN creates a virtual network interface so the operating system sends IP traffic matching the routing table to the client. This provides broader coverage for applications that lack proxy settings, some command-line programs, and UDP-dependent scenarios. The tradeoff is an additional configuration layer: besides core inbounds and routing rules, you must handle virtual-interface permissions, system routes, DNS interception, MTU, and LAN bypass.

TUN is not a “faster system proxy” and should not be the first solution to every problem. If a browser already works reliably through the system proxy, finish validating the subscription, server, and routing first, then enable TUN. This establishes that the basic proxy chain works and narrows later diagnosis to the virtual interface and system network layers. Starting directly with TUN makes it difficult to distinguish a server, DNS, permission, or routing-table failure.

Permission and Conflict Checks Before Enabling TUN

Creating a virtual network interface usually requires administrator privileges. When enabling TUN, v2rayN may request authorization or install related components. Afterward, a new virtual interface should appear in the system’s network-interface list. If the logs show interface creation failure, access denied, or route-write failure, grant permission through the approved system method and check whether endpoint security is blocking virtual interfaces. Do not repeatedly toggle the switch to work around an error; repeated attempts may leave temporary routes behind.

Other VPNs, virtual machines, containers, and security software may also modify routing tables or DNS. Before enabling TUN, exit unnecessary tools of the same kind and record the default gateway and DNS on the baseline network. If two tools both claim the default route, traffic may enter the wrong interface or form a loop. When parallel operation is necessary, define boundaries with more-specific networks and route priorities instead of letting both tools capture everything.

Routing Tables, Strict Routing, and Auto Route

Auto route writes system routes for the TUN interface so target traffic enters the virtual adapter. Strict routing further limits paths that could bypass TUN, helping keep DNS and application traffic consistent, but it may also affect virtual machines, LAN discovery, or special interfaces. On the first setup, use the client’s recommended auto-route settings. After basic access works, decide whether a stricter policy is needed.

When LAN access fails, first confirm that direct system routes for private ranges remain in place, then check that geoip:private points to direct in the core. Both conditions are required: the operating system must send the LAN target to the correct gateway, and the core must choose the direct outbound. If a corporate network uses unusual internal ranges, add explicit network rules instead of assuming every internal address falls within common private ranges.

Windows PowerShell
Get-NetRoute | Sort-Object RouteMetric
Get-DnsClientServerAddress

macOS
netstat -rn
scutil --dns

Linux
ip route
ip address

These commands observe changes to interfaces, the default route, and DNS before and after TUN is enabled. Check whether the expected interface owns the default route, whether LAN ranges still have more-specific routes, and whether temporary routes disappear after TUN is disabled. Output differs by operating system, so do not copy another person’s interface names or gateway addresses directly.

DNS Interception and FakeDNS

TUN receives IP packets, while routing rules often depend on domains. DNS interception sends system DNS requests to the core so it can preserve the relationship between domains and resolution results. FakeDNS can assign a temporary mapped address to a domain; when an application connects to that address, the core restores the original domain and applies routing. These mechanisms improve domain-based routing, but their address pool must not conflict with LAN, virtual-machine, or other VPN ranges.

When a domain resolves but cannot connect, check whether another route has captured the FakeDNS address range. When the network remains broken after closing the client, confirm that system DNS and routes were restored. Some applications use built-in or encrypted DNS and may bypass ordinary system DNS requests; disable independent resolution in the application or use TUN routing to ensure its resolution traffic also enters the client. Enable one primary DNS design at a time to avoid system DNS, client DNS, and browser DNS overwriting one another.

MTU, UDP, and Connection Problems

MTU determines the maximum size of an individual network packet. Proxy encapsulation adds overhead on top of TUN. If the path does not allow fragmentation or drops necessary control messages, an MTU that is too large can make small pages load while large files or specific websites stall. For these symptoms, gradually lower the TUN MTU within the client’s supported range, reconnect after each change, and test the same target. Do not start with an extremely small value, because it increases packet count and processing overhead.

UDP support depends jointly on the server protocol, outbound capability, and client settings. Voice, gaming, DNS, and QUIC-based connections may use UDP. If UDP fails while TCP works, first check whether the current configuration permits UDP, then whether the TUN inbound receives it and routing sends it to the correct outbound. To isolate the issue quickly, temporarily disable QUIC in the browser and see whether pages recover; this is only a diagnostic step, and the final fix should address UDP or routing.

When TUN Is Suitable for Long-Term Use

TUN is a better fit when you need to capture multiple applications that do not support system proxies, depend on UDP, or require one routing policy across desktop programs. If you use only a browser and standard office tools, the system proxy is usually simpler and coexists more easily with LAN services. For long-term TUN use, check after system updates that virtual-interface permissions are unchanged, verify that network switches rebuild the default route, and confirm after sleep recovery that DNS still points to a valid interface.

When migrating from system proxy to TUN, clear the system proxy first so the same request does not enter the local proxy and then get captured by TUN. After enabling it, use logs to confirm that the inbound tag comes from TUN, then test TCP, UDP, LAN access, and DNS separately. For complete steps and platform differences, see how v2rayN TUN mode works and how to enable it.

CHAPTER 07

Routine Maintenance: Updates, Backups, Logs, and Troubleshooting

Separate Maintenance into Four Layers

Stable use depends on four areas: the client application, the core and rule resources, subscription data, and local custom configuration. Their update sources and risks differ. A client update may change the interface and migration logic; a core update affects protocols and configuration fields; resource updates affect geosite and geoip matching; subscription updates replace server entries. Updating everything at once makes it difficult to identify which layer caused a problem.

A safer approach is to update in batches. Export local settings and custom rules first, then update the client and confirm that it starts. Next check that the core and resources load, and finally update subscriptions one at a time and test the active server. If you only need to refresh servers, do not change routing and DNS at the same time. After each maintenance task, record what changed and which paths were tested so you can quickly restore the last working setup if a regression appears.

Which Backups Are Worth Keeping

The server list can be retrieved again, but subscription URLs, group structure, manually added servers, routing rules, DNS, ports, and TUN parameters are locally managed information and should be backed up. When using the client’s export function, confirm whether the export includes subscription URLs and sensitive fields, and store the backup in a controlled location. Screenshots are useful for recording interface state but are not a complete backup because long URLs, hidden fields, and rule order cannot be reliably restored.

When migrating to another device, do not copy every cache and runtime state file. Install the client for the matching platform, import the subscription and necessary rules, then adjust them for the new device’s architecture, permissions, and network environment. Listening ports, interface names, and system proxy state may not be suitable for direct migration. After restoring, begin with a minimal system-proxy test and enable TUN and advanced DNS only after it works.

Read Logs Starting with the First Error

Core logs often contain several cascading errors after one root cause. A DNS resolution failure can leave the connection target empty, followed by outbound failure and request closure. A port conflict can prevent an inbound from being created, after which every application fails to connect. During troubleshooting, finding the first clear error after the current startup is more useful than looking only at the final timeout. Clear the log or note the time before retesting so old errors are not mistaken for the current state.

Classify common messages by stage. Configuration parse errors point to fields, JSON structure, or tags; listen failures usually involve port conflicts or permissions; domain-resolution failures belong to DNS; connection refused means the target is reachable but no service accepts the port; timeouts may occur in the local network, remote link, or handshake; authentication and handshake errors usually require checking the server entry’s protocol parameters and system time. If logs contain server addresses or subscription information, remove sensitive content before sharing them.

Build a Reproducible Troubleshooting Process

Step one: check the basic network. Close the client and confirm that ordinary networking, DNS, and system time work. Step two: check the client process. Start the core with a known-good configuration and confirm there are no parsing or listening errors. Step three: enable the system proxy, test with a browser that follows system settings, and watch the logs. Step four: compare global and rule modes to determine whether the issue is split routing. Step five: enable TUN and inspect the virtual interface and DNS. Each step should build on the success of the previous one.

If the problem began after switching networks, reconnect the active server first because old TCP connections and DNS results may be invalid. If it appears after waking from sleep, check that the core process, virtual interface, and system proxy still agree. When the client exits without clearing the system proxy, applications continue trying to connect to a nonexistent local port and every page fails immediately. Clearing the system proxy is more direct than changing servers.

Update Frequency for Subscriptions and Rules

Subscriptions do not need to be updated repeatedly every time the client opens. Set a reasonable interval based on how often the source changes and keep a manual update option. Excessive updates increase request failures and frequent list reshuffling; leaving a subscription unchanged too long preserves expired entries. Stagger update times across groups to avoid simultaneous requests. If the active server is removed during an update, the client may switch to another entry, so confirm the selected entry afterward.

Rule-resource updates can change collection contents. Important business domains should not rely only on broad collections; add clearer high-priority rules when needed. After updating resources, spot-check common direct, proxy, and block targets, especially internal domains and LAN services. If a new resource causes trouble, correct the specific target with a custom rule first and then analyze the collection change instead of piling on overlapping rule packages.

Handle Configuration and Diagnostic Data Safely

Subscription URLs, server identity fields, and exported complete configurations may contain account information. Restrict access to backups, retain only the error context when sharing logs, and replace addresses, tokens, and identity fields. Do not paste a complete configuration into a public forum. To demonstrate a problem, the protocol type, transport, error stage, and anonymized routing structure are usually enough for diagnosis.

Before remote assistance, create a temporary backup and record the current system proxy and TUN states. Afterward, check whether subscription groups, custom rules, and operating-system network settings changed. When client behavior changes suddenly, compare local settings first instead of focusing only on the server. For more symptoms and recovery steps, see the Troubleshooting section of the FAQ.

CHAPTER 08

Advanced Path: From a Working Setup to an Explainable Setup

Phase One: Lock In a Minimal Working Path

The starting point for advanced work is not adding parameters but building a minimal path that can be reproduced reliably. Choose one client, one active server, automatic system proxy configuration, and a simple routing policy. Record the local inbound, default outbound, and DNS behavior. Confirm that browser requests appear in the logs and that direct and proxy targets use the expected outbounds. Compare every later change with this baseline so its effect is clear.

During the baseline phase, do not use multiple clients, multiple system-proxy sources, or multiple DNS interception layers at once. When v2rayN handles desktop connections, make it the only tool that changes the system proxy. On Android, keep one active VPN session. The server list can be large, but fix one entry for testing. If the entry and configuration change simultaneously, the cause of a different result cannot be determined.

Phase Two: Understand Configuration Objects and Tags

Once you can read a complete configuration, focus on inbounds, outbounds, routing, dns, and log. Inbound tags can distinguish system proxy, TUN, or a specific application source; outbound tags direct routing to proxy, direct, block, or another path; DNS servers can also be assigned an outbound path. Tag names are customizable, but every reference must match. Many “rules do not work” problems are actually inconsistent tag spelling or scope.

When reading a client-generated configuration, separate automatically generated content from user customizations. A client may rewrite the file at startup, so direct edits to a temporary file can disappear on the next launch. Prefer the client’s custom-configuration, routing-rule, or advanced-settings entry points. If external maintenance is necessary, understand the merge order first. When custom and generated objects use the same key, the later write may overwrite the earlier one.

{
  "log": {
    "loglevel": "warning"
  },
  "inbounds": [
    {
      "tag": "local-socks",
      "listen": "127.0.0.1",
      "port": 10808,
      "protocol": "socks",
      "settings": {
        "udp": true
      }
    }
  ],
  "outbounds": [
    {
      "tag": "direct",
      "protocol": "freedom"
    },
    {
      "tag": "block",
      "protocol": "blackhole"
    }
  ]
}

This example is useful for practicing configuration structure, but it contains no remote proxy outbound and cannot establish a proxy connection on its own. It shows the relationship between a local SOCKS inbound, a direct outbound, and a block outbound. Real clients usually assign ports and generate remote protocol fields automatically; when merging by hand, avoid conflicts with existing inbounds. Keep the listening address on the loopback interface to limit access from LAN devices.

Phase Three: Align DNS and Routing Around the Same Intent

A mature configuration answers three questions clearly: which DNS server resolves a category of domains, which outbound carries DNS requests, and which routing rule handles the result. Setting one public DNS address does not automatically solve split routing. You can choose DNS servers by domain set, send direct domains through direct DNS, send proxied domains through the proxy path, and preserve system resolution for LAN domains.

When adjusting DNS, retain one working fallback path and note whether the browser uses independent DNS. Tests should cover first-time resolution, cache hits, and network changes. If the same domain works intermittently, check whether different address families are returned, whether multiple DNS responses exist, and whether IPv4 and IPv6 follow different routing results. Disabling one address family can help isolate the issue, but the long-term choice should reflect the current network and remote capabilities.

Phase Four: Split Policies by Inbound and Scenario

When system proxy, TUN, and application-specific ports coexist, inbound tags can select different policies. For example, system proxy can handle everyday split routing, a dedicated SOCKS inbound can default to proxy, and TUN can prioritize direct LAN access while handling UDP. This is clearer than guessing application sources from an extremely long domain list. Give every inbound a defined port, purpose, and caller, and close unused inbounds promptly.

Switch scenarios through routing configuration groups instead of repeatedly editing individual rules. Save everyday, debugging, and global proxy settings as clear presets and show the active mode in the status bar. Return to the everyday rules after debugging rather than leaving global mode enabled. When multiple configuration groups share custom rules, verify update order so a preset does not continue referencing old resources.

Phase Five: Observe Connections Instead of Guessing

Advanced troubleshooting requires observability. Temporarily raise the log level enough to show routing and connection stages, reproduce one request, and then restore the normal level to prevent rapid growth. Record the target domain, resolution result, inbound tag, matched rule, outbound tag, and final error. These six items usually identify the layer at fault. Recording only “it does not open” cannot distinguish an application that never entered the proxy, a DNS failure, a direct rule match, or a remote handshake failure.

System tools can supplement client logs. Inspect listening ports to confirm that the core accepts connections, the routing table to confirm that TUN captures traffic, DNS settings to confirm the resolution entry point, and connectivity tests to confirm that the target port is reachable. Interpret tool output together with client state: a reachable target port does not prove that the protocol handshake is correct, and a running core does not prove that an application connected to the local port.

Phase Six: Establish Change and Rollback Discipline

Changing one main variable at a time is essential for long-term maintainability. Do not change DNS while modifying routing, update the client while adjusting TUN, or alter transport parameters while switching servers. Export the current configuration before each change and validate fixed test targets afterward. If it fails, roll back directly instead of adding more temporary fixes. Once a temporary fix is proven, turn it into a clear rule and remove duplicates.

Configuration documentation should record intent, not just parameters. “Send private ranges direct to reach LAN devices” is more valuable than recording only geoip:private. If rule resources or the network change later, the intent lets you implement the behavior again instead of preserving an obsolete syntax mechanically. Subscriptions, routing, DNS, and TUN should each have their own recovery method, so one failure does not require resetting everything.

Recommended Learning Order

First become comfortable with the system proxy and minimal routing, then learn subscription groups and rule order. Next understand DNS, domain strategies, and outbound tags. Once the basic path is stable, enable TUN and observe the virtual interface and routing table. Finally, tackle per-app routing, multiple inbounds, and complex DNS. Keep a simple comparison configuration at every stage. When encountering a new protocol or field, first identify whether it belongs to the protocol, transport, security, or routing layer, then consult the relevant documentation.

When you need to establish one connection quickly, return to the quick-start path. For platform packages, visit the download page. To compare the appropriate environments for v2rayN, v2rayNG, and v2flyNG, see client comparison. Use this guide as a configuration index: locate the chapter that matches the symptom, then check each layer along the data path instead of rebuilding every setting from scratch.