Complete V2Ray Setup Guide

01 / PREPARATION

General preparation: platform, architecture, and configuration sources

Separate the client, kernel, and subscription

A complete V2Ray setup has three parts: the graphical client handles the interface, system proxy switches, logs, and configuration management; the kernel parses protocols, establishes outbound connections, and applies routing; and the subscription or share link supplies node parameters. v2rayN is a desktop client for Windows, macOS, and Linux that centrally manages subscriptions, routing, and the system proxy. On Android, v2rayNG and v2flyNG are commonly used: the former follows the Xray kernel direction, while the latter follows the V2Fly kernel direction. Their workflows are similar, but the protocol extensions and advanced parameters they recognize are not identical.

The client itself does not automatically create usable nodes. After installation, you still need to import a valid subscription URL, a single-node share link, or enter server parameters manually. A subscription URL usually returns a group of nodes for centralized updates; share links beginning with vmess:// or vless:// usually represent one node. Do not mix the two: add subscription URLs under “Subscription groups” or “Subscription settings,” while single-node links should be imported from the clipboard, scanned as a QR code, or added manually. For the exact differences, see Share Links vs. Subscription URLs.

Confirm the processor architecture and package type

Confirm the device architecture before downloading. Windows and most Linux desktop PCs typically use x64; Macs with Apple silicon use arm64, while older Intel Macs use x64; most recent mainstream Android devices use arm64. Choosing the wrong architecture commonly results in an installer that refuses to run, an incompatible-app warning, or an immediate exit after launch. If you cannot identify an Android architecture, choose the universal package, though it is usually larger. When the device is known to be arm64, the arm64 package is the better choice.

Platform	Preferred client	Common architectures	Package choice
Windows	v2rayN	x64	Desktop or classic WPF edition
macOS	v2rayN	arm64 / x64	DMG for the matching chip
Linux	v2rayN	x64 / arm64	deb or rpm
Android	v2rayNG	arm64 / universal	Package for the matching architecture

Record the configuration baseline

Before configuring, record four items: the subscription name, the currently selected node, the proxy mode, and whether TUN is enabled. If connectivity later fails, this helps identify whether the issue is subscription parsing, node connectivity, the system proxy, or transparent interception. During the first installation, do not change routing, DNS, ports, and kernel parameters at the same time. Complete one verifiable connection with the default settings, then enable split routing and TUN one at a time; changing several variables at once makes the logs difficult to interpret.

Also confirm that the system time and time zone are correct. Some protocols rely on a time window during the handshake, so a large clock difference may appear only as a connection timeout. Then check whether another proxy tool is already occupying a listening port. Common local ports include SOCKS, HTTP, and mixed-proxy ports. Defaults vary by client, so use the actual values shown in the client settings instead of copying ports from another device. If browsers or development tools will use the proxy separately, record the client’s current listening address and port.

Understand configuration storage and sensitive data

Subscription URLs and node links may contain access parameters and should be treated like account credentials. Do not paste complete URLs into public logs, screenshots, or public discussions. For troubleshooting, it is usually enough to retain the protocol type, transport, TLS status, server port, and error message while hiding the server address, user identifier, and subscription parameters. When moving to another device, add the subscription again on the new device instead of copying the entire client data directory, because paths, permissions, and system proxy states differ across platforms.

The preparation phase is complete when the client matches the platform, the subscription source is clear, system time is correct, no obvious port conflict exists, and you know whether the setup will use the system proxy or TUN. Completing these checks before opening the platform-specific section greatly reduces cases where installation succeeds but the failure point remains unclear.

02 / WINDOWS

Windows: v2rayN installation, system proxy, and TUN

Choosing the desktop or classic WPF edition

v2rayN is the preferred client on Windows. The Download Center provides both the desktop edition and the classic WPF edition. The desktop edition uses a newer cross-platform interface and suits fresh installations or users who want workflows consistent with macOS and Linux. The classic WPF edition retains a familiar Windows layout for environments accustomed to legacy menu locations or traditional desktop interaction. Both support subscription management, node selection, system proxy, and routing, so there is no need to install both. If an older configuration is still in use, export or record the subscription first, then install the edition you intend to use.

After opening the Windows download page, choose the x64 package. Close any older client before installing to prevent locked configuration files. For an installer, use the wizard to choose a location permitted for the current user or system. If you downloaded a portable release, extract it to a fixed directory with write access rather than leaving it in a temporary folder. The client needs to save subscriptions, logs, and local settings; a read-only directory can make changes appear to succeed and then disappear after a restart.

First launch and subscription import

After the first launch, open the subscription settings, create a recognizable group name, paste the subscription URL, and run an update. When it finishes, return to the node list and confirm that at least one configuration was parsed. If the list is empty, do not enable the system proxy immediately. Check the update result first: an empty response, expired URL, failed network request, or unsupported subscription format can all produce the message “added successfully, but no nodes are available.” If you received a single-node share link, copy the complete link and use an entry such as “Import from clipboard” instead of pasting it into the subscription URL field.

After selecting a node, run the client’s connection test or establish a connection once. A test only indicates whether the target can complete a handshake; it does not mean every website will use that node. For a real check, enable the system proxy and visit a browser page known to use it. Some already-running applications cache proxy settings and continue using the old connection after the system proxy changes; fully quit and reopen such applications.

How system proxy mode works

The system proxy primarily affects applications that follow Windows proxy settings. After selecting “Automatically configure system proxy” or an equivalent mode, v2rayN points the system proxy to its local listening port. Restore the system proxy before closing the client; otherwise the system may keep pointing to the local port, leaving the browser unable to access the network after the client exits. Normal shutdown usually handles this automatically, but forced termination, an abnormal shutdown, or blocked permissions can leave the setting behind.

Check the proxy switch in Windows Network & Internet proxy settings. If the manual proxy still points to 127.0.0.1 while v2rayN is stopped, turn it off and test a direct connection. The system proxy does not forcibly intercept every program: some games, command-line tools, virtual machines, and applications with their own network stack may ignore it. For those cases, specify an HTTP or SOCKS proxy inside the application or consider TUN.

TUN mode and permissions

TUN creates a virtual network interface that sends more traffic from applications that do not read system proxy settings into the client. It usually requires administrator privileges, and creating the interface for the first time may trigger a system prompt. Quit other networking tools that create virtual adapters, then start v2rayN normally and enable TUN. Do not run multiple transparent interception tools at once, or routing tables and DNS settings may overwrite one another. After TUN starts, test an ordinary webpage first, then an application that normally ignores the system proxy. If all connectivity drops, turn off TUN first to restore basic networking.

Startup, logs, and common blocks

If the client needs to run at login, enable v2rayN’s startup option, but do not confuse “start the program automatically” with “enable the system proxy automatically.” The former only starts the client process; the latter determines whether the system proxy is changed after startup. On shared computers or devices that frequently change networks, it is safer to start the client and manually confirm the node before enabling the proxy. If a node stops working after a laptop wakes from sleep, switch nodes once or restart the kernel before considering a reinstall.

When the client fails to start or crashes, first confirm that the installation directory is writable, the old process has exited, and the local port is available. Then check the system runtime environment and security policy. The log message “address already in use” usually indicates a listening-port conflict; a configuration parsing error points to a recently imported node or custom route. Do not delete all configuration as a first step. Back up the configuration directory, move the newest additions aside, and restart. For a fuller troubleshooting path, see Client Won’t Open or Keeps Crashing.

The Windows section is complete when subscriptions update, a node can be selected, the browser follows the expected path with the system proxy enabled, and direct access returns after the proxy is disabled. Enable TUN only when you need to cover programs that ignore the system proxy. Keep a matching log excerpt after each change to distinguish an unavailable node, a leftover proxy setting, a port conflict, and a virtual adapter issue.

03 / MACOS

macOS: chip selection, permissions, and proxy interception

Confirm the chip and install v2rayN

macOS uses the v2rayN desktop edition. Before downloading, open System Information or “About This Mac” and check the processor or chip field. If it shows Apple silicon, choose the arm64 DMG; if it shows an Intel processor, choose the x64 DMG. A package that does not match the chip may fail to open or may run through a compatibility layer, adding another troubleshooting variable. Open the macOS download page, select the file for your chip, open the DMG, and move the app to the Applications folder.

If the first launch is blocked by the system, do not keep double-clicking. Open Privacy & Security and review recently blocked applications. After confirming that the name matches the newly installed v2rayN, choose to allow it to open. You can also right-click the app in Applications and choose Open so the system displays a clear confirmation once. After approval, it should normally launch from Launchpad or the Applications folder. Exact paths may vary by minor system release; see Opening v2rayN on macOS and Handling Network Permissions.

Importing subscriptions and checking menu bar status

After the client starts, confirm that the main window or menu bar icon is visible. To add a subscription, create a group, paste the URL, save it, update it, and then select a configuration from the node list. If the address will not paste, check whether the clipboard contains leading or trailing spaces, line breaks, or explanatory text added by a chat app. A subscription URL must be one continuous string. For a single-node link, use the clipboard import entry and then verify that the protocol, port, transport, and TLS fields are complete.

Closing a macOS application window does not necessarily stop its process. After clicking the close button, v2rayN may remain in the menu bar and continue maintaining the proxy. When troubleshooting or preparing to restart, quit from the menu bar and then confirm in Activity Monitor that the related process has ended. If you simply close the window and install another copy, two instances may compete for the same local port.

System proxy and network services

When the system proxy is enabled, the client adjusts the proxy settings for the active network service. macOS can have Wi-Fi, Ethernet, and other network services at the same time, so confirm that the active service has the proxy applied after switching networks. If it works on Wi-Fi but fails on Ethernet, toggle the system proxy once before concluding that the node is broken. Browsers and most desktop applications read the system proxy, but command-line tools vary; when necessary, set proxy environment variables for the current terminal session.

export HTTP_PROXY="http://127.0.0.1:local HTTP port"
export HTTPS_PROXY="http://127.0.0.1:local HTTP port"
export ALL_PROXY="socks5://127.0.0.1:local SOCKS port"

# Restore direct connection for the current terminal
unset HTTP_PROXY HTTPS_PROXY ALL_PROXY

Replace the port in the examples with the listening port actually shown in v2rayN settings. Environment variables affect only programs launched from the current terminal that read those variables. They do not replace the system proxy or automatically affect other terminal windows. When troubleshooting command-line access, run env first to check for stale proxy variables. A client port that has changed while the terminal still points to the old port is a common reason why the browser works but command-line requests fail.

TUN, network extensions, and authorization

When TUN is enabled, the system may request local administrator credentials or confirmation to add a network extension. Complete authorization through the system prompt and settings page. If authorization is denied, the client may still run normally with the system proxy, but TUN cannot be created. After enabling it, the system network settings may show a new interface or related status. Do not delete the interface manually; first disable TUN and quit v2rayN, then handle any leftover entry.

On corporate networks, guest Wi-Fi, and hotspots requiring web authentication, complete network login before enabling TUN. Otherwise the sign-in page may be blocked by the proxy or DNS interception. If a network appears connected but carries no data after switching, follow this order: disable TUN, confirm direct access works, update the subscription again, and re-enable TUN. This avoids repeatedly changing nodes before the underlying network is ready.

Sleep recovery and leftover proxy settings

After a Mac wakes from sleep, roams between Wi-Fi networks, or switches hotspots, an existing connection may be stale. Check the client log for a new outbound connection before testing access. If the system proxy remains enabled while the local kernel has not recovered, applications will keep sending traffic to an unoccupied port. Disable the system proxy first, confirm direct connectivity, then restart the client and enable it again. If global access fails after a forced quit, also check whether HTTP, HTTPS, and SOCKS remain selected in the active network service’s proxy details.

For automatic startup after login, use the client’s startup option or the system login-item manager, but avoid configuring both. Setting both can launch two processes within a short period. A stable setup keeps one startup entry and clearly defines whether the system proxy is changed automatically. The macOS acceptance order is: pass the system permission check, update the subscription successfully, confirm the menu bar status, verify that the system proxy can be toggled, and confirm recovery after switching networks. Validate TUN separately rather than during the first installation.

04 / LINUX

Linux: deb, rpm, desktop proxy, and startup

Choose the distribution package format

Linux desktop platforms use v2rayN. Choose deb for Debian, Ubuntu, and common derivatives; choose rpm for Fedora, Rocky Linux, openSUSE, and other rpm-based environments. For a typical desktop x64 processor, choose the x64 package; for an arm64 device, use the matching arm64 package. The package format and architecture must both match; the desktop environment name alone is not enough to identify the package type. Run the following commands in a terminal to confirm the architecture and distribution information:

uname -m
cat /etc/os-release

x86_64 generally corresponds to x64, and aarch64 generally corresponds to arm64. The ID and ID_LIKE fields in distribution information can help identify the package-management family. Open the Linux download page and choose the matching file. Do not treat a package like an archive and run its contents directly; installing through the system package manager registers the desktop entry, dependencies, and uninstall information.

Install deb or rpm

Switch to the download directory in a terminal and install the package with the system package manager. The filename depends on what you downloaded; type the first few characters and press Tab to complete it instead of spelling it manually. In the commands below, the filename represents a package already downloaded to the current directory:

# Debian / Ubuntu family
sudo apt install ./v2rayN-downloaded-package.deb

# Fedora family
sudo dnf install ./v2rayN-downloaded-package.rpm

Use apt install ./package.deb or dnf install ./package.rpm; these handle dependencies more reliably than calling a low-level unpacking command directly. After installation, launch v2rayN from the desktop application list. If no entry appears, run the application command in a terminal and look for missing libraries, display services, or permission errors, then refresh the desktop application database. Do not bulk-install unknown runtime libraries to fix one missing dependency; use the exact package name reported by the package manager.

Desktop proxy and environment variables

GNOME, KDE, and other desktop environments provide network proxy settings, but their locations and automatic coverage differ. v2rayN’s system proxy function attempts to integrate with the desktop proxy configuration. During verification, first check whether the proxy mode in the desktop settings has changed, then test with a browser. Exporting HTTP_PROXY only in a terminal does not enable the proxy for the entire desktop; conversely, an enabled desktop proxy does not guarantee that every command-line tool will read it.

# Set variables for the current shell session only
export http_proxy="http://127.0.0.1:local HTTP port"
export https_proxy="http://127.0.0.1:local HTTP port"
export all_proxy="socks5://127.0.0.1:local SOCKS port"

# Clear the current session
unset http_proxy https_proxy all_proxy

When the local listener is bound only to the loopback address, only programs on the same machine can connect. To let other devices on the same LAN use the port, you must explicitly allow LAN connections, adjust the listening address, and configure the firewall. This broadens the exposure of the service and is not required for a first installation. Unless there is a clear need, keep loopback-only listening enabled.

TUN, capability authorization, and routing

TUN on Linux requires /dev/net/tun, along with permission to create interfaces, modify routes, and handle DNS. The desktop client may request access through an authorization dialog or rely on an installed permission-management component. If enabling TUN fails, first check that the TUN device exists, then look for “permission denied,” “operation not permitted,” or route-addition failures in the logs. Do not run the entire graphical client as root for an extended period; this can change ownership of configuration files in the user directory and prevent the regular user from saving settings later.

Virtual machines, container desktops, and restricted enterprise environments may disable TUN. The system proxy can still work, so keep that working option first. If TUN causes only domain access to fail while direct-address connections work, focus on DNS. If all traffic stops immediately, check the default route, policy routing, and other virtual networking software for conflicts. After disabling TUN, confirm that the virtual interface and additional routes were removed before starting another test.

Login startup and desktop sessions

The graphical client should start after the user desktop session is established. Prefer v2rayN’s built-in startup setting; if the desktop environment does not handle it correctly, use a user-level systemd service. The service must wait for the graphical session and network to be ready and must run as the current user. See Linux Installation and Startup Configuration for the full procedure. After configuring startup, actually log out and back in to test it; running a service command once is not enough to confirm success.

When startup fails, check user-level logs rather than the system service list. Common causes include a program path that changed after an update, unavailable display environment variables, a desktop keyring that has not unlocked, and a network that has not obtained an address. For devices frequently used across different networks, let the client start automatically but do not force TUN on immediately. Complete network authentication and establish the desktop session first, then confirm the current network environment before enabling it.

Uninstalling, upgrading, and preserving configuration

For an upgrade, install a new package matching the current distribution and architecture over the existing one. Quit the client normally first so the kernel process and configuration files are not locked. Uninstalling through the package manager usually does not remove every configuration file in the user’s home directory, so old subscriptions may reappear after reinstalling. If the goal is a completely fresh configuration, back up the user configuration directory and rename the old directory instead of deleting it. This keeps subscriptions and routing rules recoverable.

The Linux section is complete when the system package manager recognizes v2rayN, the desktop entry launches, subscriptions and nodes are saved under the current user, the desktop proxy can restore direct access, and the routing table is normal after TUN is disabled. If the issue occurs only in terminal tools, check environment variables first; if it affects only graphical applications, check the desktop proxy; if the entire system is affected, inspect TUN, DNS, and routing.

05 / ANDROID

Android: v2rayNG, v2flyNG, and system VPN interception

Choose the client and architecture

v2rayNG is the preferred Android client; choose v2flyNG when you need the V2Fly kernel direction. Both clients provide arm64 and universal packages. Mainstream phones released after 2015 typically use arm64, but verify the device information whenever possible. Choose arm64 when confirmed; otherwise choose the universal package. Do not keep both clients connected at the same time, because Android normally allows only one active VPN session of this type.

Download the package from the Android download page. The system may ask you to allow the current browser or file manager to install applications. Grant this permission only to the app actually opening the package, then disable the source permission after installation. If installation fails, check whether an app with the same name came from a different signing source, whether storage is sufficient, and whether the file finished downloading. Do not repeatedly tap Install and obscure the original error.

Import subscriptions and single-node links

After opening v2rayNG or v2flyNG, add the subscription URL to a subscription group and run an update. When it finishes, select a node from the configuration list. Copy a single-node share link to the clipboard and use the clipboard import function; scan QR codes through the client’s scanning entry and grant camera access when requested. If duplicate entries appear, you probably imported from the clipboard multiple times or added the same subscription to several groups. Keep the copy with the clearest source.

Mobile clipboards may truncate long links during copying. When import fails, paste the content into a local text editor and confirm that the protocol prefix, trailing parameters, and all characters in between are intact. Do not edit encoded share links manually inside an instant-messaging window; changing one character can break parsing. If nodes do not change after an update, confirm that you are viewing the correct subscription group and check the update notice before treating unchanged server content as a client failure.

First connection and system confirmation

Select a node and tap Connect. Android will show a system confirmation dialog for creating a VPN connection. The connection indicator appears in the status bar only after you approve it. A selected node in the client does not mean system traffic has entered the proxy. For the first verification, keep the default routing and DNS, connect, and test with a browser. If the browser works, test other applications. If the connection indicator appears but no application can access the network, disconnect first and confirm that mobile data or Wi-Fi itself works.

When switching from Wi-Fi to mobile data, existing connections may need to be rebuilt. Battery-saving policies can also restrict background processes after the screen locks, leaving a connection icon visible while the kernel has stopped transferring data. In system battery settings, allow the client the necessary background activity and avoid one-tap cleaners that force-stop it. Settings vary by device manufacturer; the goal is to let the client maintain its foreground service and network activity while connected.

Per-app proxy and bypass rules

Android clients commonly provide per-app proxy controls: you can send only selected apps through the proxy or let selected apps bypass it. These modes work in opposite directions, so confirm the active mode before configuring it. For the first setup, keep the global app scope, verify the basic connection, and filter later. With “proxy selected apps only,” forgetting to select the browser makes the node appear ineffective; with “bypass selected apps,” checked apps connect directly.

System components, download managers, and embedded web pages may send requests from different processes. Selecting only the main app does not necessarily cover every system service it invokes. If a sign-in page opens but downloads fail, temporarily disable per-app restrictions for comparison. Once filtering is confirmed as the cause, add the related components gradually instead of immediately changing the node protocol or DNS.

On-demand connections, always-on VPN, and LAN access

Always-on VPN in system settings attempts to keep the client connected after the network returns, which suits stable configurations and devices that use one client long term. Enabling “Block connections without VPN” expands interception, but the device may lose all connectivity when the node is unavailable or the client is not running. During first installation, do not enable both options at once. First confirm subscription updates, node switching, and recovery after disconnecting.

Accessing printers, casting devices, router admin pages, or other LAN services may require bypassing LAN traffic. Typical private ranges include 10.0.0.0/8, 172.16.0.0/12, and 192.168.0.0/16. If the internet works through the proxy but LAN devices disappear, check whether routing is sending private addresses to a remote outbound. Do not mark an unknown address range as direct without reason; use the actual LAN range.

Logs, battery use, and background failures

When troubleshooting on mobile, first check whether the timestamps in the client log match your recent actions. Connection timeouts, DNS resolution failures, configuration parsing errors, and the system stopping the service are different branches. If the app disconnects immediately after returning from the background, focus on battery optimization. If the old node remains displayed after switching, disconnect and reconnect. If only one app fails, check per-app settings and whether it uses private DNS or a specialized network stack.

A persistent connection keeps a foreground service active and normally consumes network data and battery. If battery use is unusually high, first rule out frequent node reconnects, weak-signal network changes, and an excessively verbose log level. Do not leave the most detailed logging enabled; restore the normal level after troubleshooting. The Android section is complete when system connection approval succeeds, a browser verifies access, direct access returns after disconnecting, connections can be rebuilt after network changes, and per-app rules and background policies match the intended scope.

06 / SUBSCRIPTION AND ROUTING

Subscription management, node selection, and split routing

The complete subscription update flow

Updating a subscription is not simply “downloading a list.” The client requests the subscription URL, reads the response, parses nodes in a supported format, and writes them to the selected group. A failure can occur at any step: the request depends on network access and URL status, parsing depends on the format and kernel capabilities, and writing may be affected by configuration-directory permissions or group settings. After updating, check the notice, group name, and change in node count rather than only whether the button appeared to work.

Do not add the same subscription to multiple groups. Duplicates create similarly named nodes and make it difficult to tell which update produced the active one. Create stable groups by purpose or source; there is no need to encode versions or dates in their names, since the client status or logs show update times. Before deleting a subscription, check whether “also delete nodes under this subscription” is selected, so you do not leave orphaned configurations. When the subscription URL changes, edit the original group and update it instead of creating multiple temporary groups.

Node parameters and compatibility limits

Whether a node can be imported depends on whether the client and kernel recognize its protocol, transport layer, and additional parameters. VMess and VLESS describe only part of a connection; the configuration may also include TCP, WebSocket, gRPC, TLS, REALITY, service name, path, and server name fields. If import succeeds but connection fails, check whether key fields were lost during copying or subscription conversion. When moving between clients, re-import the original subscription whenever possible instead of handing one client’s internal configuration file to another platform.

A node name is only a label for identification and says nothing about actual route quality. Test by establishing a real connection through one node and use the logs for interpretation. A single failed latency test may mean that the target does not answer probes, the current network is lossy, or the handshake did not complete; a low one-off latency does not guarantee stable transfer. The goal is to determine whether a connection can be established, DNS resolution completes, and requests reach the intended outbound—not to chase a fixed number.

How routing rules are matched

Routing rules usually match domains, addresses, ports, network types, or process information, then send traffic to a proxy, direct, or blocking outbound. Rule order matters: more specific conditions should precede broad rules, followed by a default outbound. If a broad rule matches first, later precise rules never take effect. Before editing, record the current routing mode. Afterwards, test one target that should go direct and another that should use the proxy to confirm both paths behave as expected.

Domain rules and address rules operate at different stages. An application requests a domain first; after DNS returns an address, the kernel may match that address against address rules. With domain sniffing enabled, the kernel may also recover the destination domain from traffic for further routing. More sniffing is not always better: some nonstandard protocols, encrypted connections, and LAN services should not be rewritten. Keep the client defaults during the first setup and adjust them only for a clearly identified issue.

{
  "routing": {
    "domainStrategy": "AsIs",
    "rules": [
      {
        "type": "field",
        "ip": [
          "geoip:private"
        ],
        "outboundTag": "direct"
      },
      {
        "type": "field",
        "domain": [
          "domain:example.com"
        ],
        "outboundTag": "proxy"
      }
    ]
  }
}

The example shows the rule structure: private addresses go to the direct outbound, while the specified example domain goes to the proxy outbound. In actual use, outboundTag must match an outbound tag already present in the current configuration. If the client uses different tag names, copying the example directly will make the rule point to a nonexistent outbound. Graphical clients usually provide a preset routing interface; edit there first, and only modify the underlying JSON when you understand the generated result.

System proxy, PAC, and global routing

The system proxy sends applications that follow system settings to a local port; routing rules then decide which outbound handles the traffic after it enters the kernel. Do not confuse these layers. If an application never enters the local proxy, even complete kernel routing rules cannot affect it. If it enters the proxy but a rule sends it direct, the result is “the client is enabled, but the target still connects directly.” PAC or an automatic configuration script makes an earlier choice at the system-proxy layer, so troubleshooting must determine whether PAC failed to select the proxy or kernel routing selected direct access.

For a simple and stable setup, let the system proxy send browser traffic to the client, then let kernel routing decide between direct and proxy outbounds. Use TUN only when more applications need to be intercepted. Do not enable multiple PAC sources, custom browser proxy extensions, and the system proxy at the same time. Multiple decision layers can send the same domain different ways in different applications. Keep one entry point so the logs accurately reflect requests.

Safe change procedure after a subscription update

Updating a subscription may remove old nodes, add new ones, or rename entries. If the active node is removed, the client may switch to another configuration or retain a stale reference. After updating, confirm that the selected item still exists and reconnect. If custom routing points to a specific outbound by node tag, check whether the tag changed with the update. When a group contains many nodes, clear subscription groups and fixed outbound tags are more reliable than display names.

The recommended order is: record the current node and routing mode, update the subscription, confirm the parsing result, select a node, test with default routing, and then restore custom rules. If the update causes an immediate failure, switch back to a node retained from before the update for comparison. For subscription and routing concepts, see the Glossary, including protocols, outbounds, split routing, and DNS. This avoids treating interface labels as if they belonged to the same configuration layer.

07 / TUN AND DNS

TUN, DNS, and system networking boundaries

When TUN is necessary

TUN receives system traffic through a virtual network interface and covers programs that do not read the system proxy. If browsers and ordinary desktop applications already work through the system proxy, there is no need to enable TUN merely for a “more complete” configuration. Game launchers, some command-line tools, applications with independent network stacks, and scenarios requiring broad interception are the main reasons to consider TUN. TUN adds four variables—routing, DNS, permissions, and the virtual interface—so it covers more traffic but also creates a longer troubleshooting chain.

Before enabling it, close other tools that modify the default route or create virtual adapters, and record the system proxy state. In most cases, TUN and the system proxy should not duplicate responsibility for the same traffic; whether both can be enabled depends on the client implementation. If unsure, follow the client defaults first. After enabling TUN, immediately test three targets: an ordinary domain, a LAN address, and a program that ignores the system proxy. Record each result separately instead of summarizing everything as “can open a webpage.”

Strict routing and traffic loops

TUN must prevent the client’s own server connection from being sent back into TUN, or a loop will form. Graphical clients usually exclude the kernel process, server address, or specific interface automatically. Preserve these exclusions when editing routes manually. Typical loop symptoms include rapidly repeated connections in the log and abnormally rising traffic counters while no request completes. Turn off TUN first; do not keep switching nodes. Once networking is restored, inspect the exclusion routes.

Strict routing reduces traffic bypasses but may affect virtual machines, containers, LAN discovery, and internal corporate networks. If LAN devices disappear after enabling it, check that private addresses remain direct, multicast and broadcast traffic are not being intercepted, and the active interface has the expected priority. Virtual adapters on Windows, network extensions on macOS, and policy routing on Linux work differently, so do not apply one platform’s exported routing table directly to another.

Which layers handle DNS requests

When accessing a domain, an application may use system DNS, a browser’s built-in resolver, encrypted DNS, or DNS intercepted by the client. If no domain request appears in the client log, that does not necessarily mean the application is offline; it may have resolved the name itself. Conversely, resolving an address does not guarantee that the outbound connection will succeed. Troubleshoot in two steps: confirm that the domain returns a sensible address, then confirm which outbound handles the connection to that address.

After TUN is enabled, the client may take over system DNS and forward requests to the configured server. If all domains fail while direct-address access works, focus on the DNS listening port, upstream reachability, and port conflicts. If only some domains resolve incorrectly, check split DNS, caches, and domain rules. After changing DNS, restart related connections or clear the system cache; otherwise applications may continue using old results.

Symptom	Check first	Comparison test
All domains fail	DNS listener, upstream DNS, port conflicts	Disable TUN and test system resolution
Only LAN domains fail	Local DNS, private-domain rules	Access a LAN address directly
Resolution succeeds but the connection times out	Node, outbound, routing rules	Review logs for the connection stages
The old result remains after switching nodes	System and application DNS caches	Restart the application and reconnect

Fake DNS and domain mapping

Some TUN configurations use Fake DNS: they first return an internal mapped address to the application, then recover the original domain when the client receives the connection. This preserves domain information for routing, but the mapped address range, routes, and client state must remain consistent. If the client exits while the mapping remains cached by the system or application, access may temporarily fail. Disable TUN, restore system DNS, clear the relevant caches, and reconnect.

Do not casually layer Fake DNS with other local DNS services. If the system already has ad-blocking DNS, local development resolution, or container DNS, map the request path first: identify who listens on the local port, who the upstream is, and which component applies domain rules. Two services competing for one port cause immediate startup failure; circular forwarding causes persistent timeouts. A stable setup should have one clear system entry point that forwards to the next service.

LANs, hotspots, and virtual environments

If NAS devices, printers, or router admin pages become unreachable after enabling TUN, private-address routing or local DNS is usually involved. Try the device address directly. If the address works but the hostname does not, fix local DNS; if the address also fails, check whether the private subnet was incorrectly sent through the proxy. When a device shares its hotspot, whether other devices’ traffic enters TUN depends on system forwarding and client capabilities; do not infer it from the host device’s connection status.

Virtual machines and containers often have separate bridges, DNS, and routing. The host’s system proxy usually does not automatically enter the virtual environment, and TUN may cover only part of the traffic because of interface priorities. During troubleshooting, inspect the default route and DNS separately on the host and inside the virtual environment instead of blaming the node for a container connection failure. If only development tools need a proxy, explicitly setting the local proxy address in the tool or environment is often easier to maintain than expanding TUN coverage.

A stable start-and-stop sequence

Recommended startup order: confirm that the basic network works, start the client, update the subscription and select a node, verify the system proxy, then enable TUN. For shutdown, stop TUN first, confirm that the virtual interface and additional routes are removed, restore the system proxy, and finally quit the client. If the network fails after an abnormal restart, check leftover state in reverse: is the system proxy still pointing locally, does the virtual interface remain, and is DNS still pointing to a stopped listener?

This chapter is complete when network behavior is predictable before and after toggling TUN, the LAN scope is clear, DNS has one entry point, and the system recovers after the client exits. If the system proxy already covers the applications you use, keeping the simpler configuration is fine; broader interception is not automatically better for the device.

08 / TROUBLESHOOTING

Common configuration issues and layered troubleshooting

Establish the failure layer first

Effective troubleshooting starts by identifying the affected layer. Layer one is the device’s basic network; direct access should work with the client off. Layer two is the subscription and configuration; the client should parse nodes. Layer three is the kernel connection; logs should show an outbound connection or a clear error. Layer four is system interception; application traffic must enter the local proxy or TUN. Layer five is routing and DNS; requests should reach the expected outbound. Skipping the earlier layers and changing advanced parameters usually makes the symptoms harder to interpret.

Change one variable at a time and record the result before and after. If a node cannot connect, switch to one other node on the same network first. If all fail, inspect the subscription and network; if only one fails, its configuration is more likely at fault. If the browser fails while the client test succeeds, check the system proxy. If the system proxy works but one independent application fails, inspect that application’s proxy settings or TUN. This comparison provides more information than repeated reinstalls.

Subscription update fails

When a subscription update fails, first confirm that the URL is complete, has no leading or trailing spaces, and was added under subscription settings rather than the single-node import entry. Then determine whether the notice reports a failed network request, an empty response, or a parsing failure. Retry a request failure after restoring basic connectivity; an empty response requires checking the subscription source; a parsing failure requires confirming that the client supports the returned format. Do not rewrite a subscription URL as a share link or manually remove query parameters that appear unnecessary.

If an update succeeds but no new nodes appear, check the current group, filters, and duplicate-handling rules. Some updates replace the existing group rather than append to it; if the server content has not changed, the list should remain the same. If old nodes still work but new ones are missing, create a temporary group for comparison, then merge or remove it after confirmation so duplicates do not accumulate.

Node selected but connection fails

First check the system time, current network, and node parameters. A timeout in the log usually means the connection did not complete and may indicate an unreachable address, packet loss, or an unresponsive server. A connection refusal usually means the address is reachable but nothing accepts connections on that port. A configuration parsing error indicates a malformed parameter structure. TLS, server name, transport path, and service name must match the node source; do not replace them with commonly seen values based on guesswork.

When the same node works on one platform but fails on another, compare protocol fields and kernel capabilities rather than just the node name. Re-importing from the original subscription is usually more reliable than copying a client’s internal JSON. If v2rayNG imports an extension that v2flyNG cannot recognize, choose the compatible client according to the kernel direction instead of leaving the missing field blank and forcing a connection.

Client shows connected but applications are unchanged

This is usually a system-interception issue. On desktop platforms, check that the system proxy points to the client’s current listening port; on Android, confirm that the system VPN approval is complete. Then check whether the application reads the system proxy and whether it established a long-lived connection before the proxy was enabled. Fully quit and reopen the application to rule out cached connections. If a browser has an additional proxy extension configured, disable it temporarily so it cannot override the system settings.

Command-line programs may require proxy environment variables, while games and applications with independent network stacks may require TUN. Do not conclude that the node is unavailable just because one application ignores the system proxy. Use a browser known to follow the system proxy as the baseline, confirm that it works, and only then broaden interception.

No network access after closing the client

The most common cause is a system proxy still pointing to a stopped local port. On Windows and macOS, disable the manual proxy or automatic proxy configuration in system network settings. On Linux, check the desktop proxy and terminal environment variables; on Android, check the system connection status and always-on VPN setting. If TUN was enabled, also confirm that the virtual interface, default route, and DNS have been restored. Test direct access first, then restart the client.

Forced termination is more likely than a normal exit to leave stale state behind. For regular use, disable the system proxy and TUN from the client menu before quitting. If the problem returns after every reboot, check for duplicate startup entries or another network tool that writes proxy settings at login. Do not let multiple programs manage the same system proxy switch.

Port conflicts and kernel startup failures

When the log says that a port is already in use, quit other proxy clients and confirm that v2rayN, v2rayNG, or v2flyNG has no duplicate instance. A kernel process from a previous abnormal exit may also still be running. End only the obsolete process you have identified, then restart. If you must change the listening port, update the browser, terminal environment variables, and every other tool that depends on it; otherwise the client may use the new port while applications continue connecting to the old one.

# Linux: find the process listening on a specified port
ss -lntp

# Windows PowerShell: view TCP listeners
Get-NetTCPConnection -State Listen

# macOS: view TCP listeners
lsof -nP -iTCP -sTCP:LISTEN

Do not terminate a system process whose purpose you cannot confirm. Use the command output to map the port to a process, then decide whether to close an old client or change the new client’s port. A listener bound to 127.0.0.1 is accessible only from the local machine; a listener on all interfaces also requires checking LAN access settings and the firewall.

Network-wide outage after enabling TUN

Disable TUN immediately and confirm that basic networking returns. Then check permissions, the virtual interface, routing, and DNS in that order. Insufficient permissions usually appear while the interface is being created; a route conflict sends traffic the wrong way after creation; DNS problems more often affect domains specifically. If a virtual machine, container network, or other virtual-adapter tool is also running, temporarily stop one of them for comparison.

On Android, also check whether the system retains another VPN configuration. On desktop platforms, check whether multiple clients start automatically. During recovery, do not re-enable every feature at once: start with the node connection, then the system proxy, and TUN last. Proceed only after each layer passes so you can identify where the failure is introduced.

Organize logs and continue researching

Before reporting an issue, record the operating system, client name, package architecture, whether you used the system proxy or TUN, when the issue occurred, and the most recent change. Include only the log lines around the failure and hide subscription URLs, user identifiers, server addresses, and other sensitive data. Describe reproducible steps, such as “subscription update succeeded; after selecting a node and enabling the system proxy, browser requests timed out; disabling the system proxy restored direct access,” rather than simply saying “it does not work.”

If the cause remains unclear, visit FAQ to browse basic concepts, setup, usage tips, and troubleshooting. Beginners can also read V2Ray: Ten Questions and Answers to understand kernels, subscriptions, and proxy modes. After troubleshooting, remove temporary logging, test ports, and routes, and keep a verified stable configuration.

Final acceptance of the complete setup should cover four states: the subscription updates after the client starts, the target application uses the proxy as expected after a node connects, direct access returns when the system proxy or TUN is disabled, and a connection can be rebuilt after a reboot or network change. Meeting all four confirms that installation, configuration, system interception, and recovery paths are complete.