Complete V2Ray Setup Guide for All Platforms

General preparationand configuration boundaries

Before installing, confirm the device architecture, subscription type, proxy targets, and current network status. The clearer this preparation is, the easier it will be to isolate a connection failure to one specific stage.

Separate the client, kernel, and subscription

v2rayN, v2rayNG, and v2flyNG are graphical clients. They store server details, generate runtime configurations, start the kernel, and control the system proxy. Xray and V2Fly are kernel families that actually handle connections, transport, and routing. A subscription is a set of server configurations provided by a service, typically containing an address, port, user ID, protocol, transport, TLS settings, and server name. These are different layers: the client provides the interface, the kernel executes the configuration, and the subscription supplies usable connection parameters.

Choose v2rayN first on desktop devices. Its subscription groups, server lists, and routing settings follow a similar structure across Windows, macOS, and Linux, making cross-device migration easier to verify. Android devices generally use v2rayNG with the Xray kernel; choose v2flyNG when you specifically need V2Fly kernel behavior. Do not judge compatibility by protocol name alone. Confirm that the transport layer, TLS, security settings, and server configuration all match.

Confirm the processor architecture and installer type

Common Windows desktops use x64 packages. On macOS, choose an Apple Silicon or Intel installer based on the chip. Most Android devices use arm64; when the architecture is unknown or compatibility is complicated, use the universal package. On Linux, identify both the processor architecture and package system: Debian, Ubuntu, and derivatives use deb, while Fedora, Rocky Linux, openSUSE, and similar environments generally use rpm. Choosing the wrong package type may cause the installer to refuse execution, report an architecture mismatch, or make the program exit immediately after launch.

Preserve original details and establish a baseline

Before importing, keep the subscription URL in its original text and avoid exposing it in forwarded chats, synced notes, or long-lived QR-code screenshots. A subscription URL usually grants access to an entire group of nodes and may be used by others if leaked. For the first setup, import only one subscription group and choose one confirmed working server. Establish a baseline with the default routing and DNS settings. After the baseline works, enable custom routing, TUN, FakeDNS, Mux, or per-app proxy one at a time. Changing several parameters at once makes it impossible to tell which one caused the problem.

Before you begin, close other proxy clients and confirm that the system time, time zone, and underlying network are working normally. TLS handshakes depend on an accurate clock; a significant discrepancy may appear as a certificate error or an immediate disconnect after connection. Corporate networks, guest networks, and public hotspots may restrict certain ports or UDP, so first open a regular website directly in a browser to confirm that DNS and basic connectivity work. If a manual proxy is configured on the device, record its original value before letting the client manage it, so an old address is not left behind when the client exits.

Follow a repeatable setup sequence

1. Choose the matching installerSelect by platform, processor architecture, and package system; do not substitute another build just because its filename looks similar.
2. Import one subscription groupEnter a name and subscription URL, then confirm that server entries are generated after updating.
3. Choose an active serverRun a real connection test first, then decide whether to perform batch latency tests or change the order.
4. Enable one interception methodTest system proxy and TUN separately; avoid changing the network path in two ways at once.
5. Record the working configurationSave the routing mode, DNS plan, and client settings so they can be restored after an upgrade or migration.

The goal of preparation is not to tune every option in advance, but to establish a repeatable, reversible configuration chain. When a platform has problems later, check these six layers in order: installation completeness, subscription parsing, server availability, kernel startup, whether traffic reaches the client, and DNS compatibility. This prevents a node failure from being mistaken for an installation failure and avoids repeatedly editing a subscription while an old system proxy remains active.

Windows installation, system proxy, and TUN

Windows uses v2rayN. The desktop build provides a cross-platform interface, while the classic WPF build suits users who prefer traditional Windows interactions; their subscription, server, and routing concepts are the same.

Download and installation choices

Open the Windows download section and choose the desktop or classic WPF build based on your preferences. For a new installation, start with the desktop build. Choose the classic build when you need the traditional tray workflow, already have a WPF configuration directory, or depend on an established process. Exit any older client before installing so the installer can replace files that are not in use. After installation, launch it from the Start menu. On first run, confirm that the main window opens, a client entry appears in the system tray, and the kernel type displays correctly.

If Windows shows a network access permission prompt, allow client communication according to the actual network environment. This concerns inbound listening and LAN features; it is not the same as enabling the system proxy. Managed devices may prevent standard users from installing network components or creating services. When permissions are required, use an installation method approved by the device administrator instead of repeatedly extracting the program to different folders. For portable use, avoid locations that are automatically cleaned, read-only, or excessively long.

Import a subscription and choose an active server

Open subscription group management, create one group name, and paste the subscription URL. Save it and run an update; the main list should show the protocol, alias, and server details. If the list is empty, check that the URL is complete and contains no spaces, and confirm that opening it in a browser returns valid content. After a successful update, choose a server and set it as active. Latency tests reflect only a particular test method and do not show whether a node suits every type of traffic, so initial verification should use a real web request and the target application.

A subscription update may add, modify, or remove entries based on the service response. Manually editing server parameters generated by a subscription may be overwritten at the next update. To preserve custom settings, place changes in the client’s routing or DNS configuration, or in a separate manual server group. Before deleting a subscription, confirm that it contains no uniquely usable configuration. Re-adding the same URL may create a new group identifier, and the previous order and selection may not be preserved.

Three system proxy states

The Windows system proxy mainly affects browsers and desktop programs that follow system proxy settings. Common states are clear the system proxy, set the system proxy, and leave the system proxy unchanged. For daily use, choose “Set system proxy,” then “Clear system proxy” when exiting. “Leave unchanged” is useful when a browser proxy is configured manually, only selected programs should use a local port, or another network tool manages the system proxy. After switching, open Windows proxy settings and confirm that the address points to the local loopback address and the port matches v2rayN’s current listener.

If the browser cannot connect after the client exits, first check whether the system proxy remains enabled. Restart v2rayN and clear it, or disable the manual proxy in system settings. Do not replace the local listening port with the remote server port from the subscription: the former is the entry point for applications connecting to v2rayN, while the latter is the kernel’s destination on the server side. They serve completely different purposes.

ipconfig /flushdns
netsh winhttp show proxy
Get-NetTCPConnection -State Listen | Select-Object LocalAddress,LocalPort,OwningProcess

These commands refresh the Windows DNS cache, show the WinHTTP proxy status, and check local listening ports. The browser’s system proxy and the WinHTTP proxy are separate settings, so netsh winhttp show proxy may show a direct connection while the browser is still using the system proxy. Troubleshooting requires checking Windows settings, the client state, and the target program’s own proxy options.

TUN mode and platform-specific issues

TUN creates a virtual network interface so programs that do not read system proxy settings can still enter the client. Before enabling it, establish one stable connection through the system proxy, then confirm that v2rayN’s TUN component and permissions are ready. First-time activation may request administrator permission or install a network interface. Once successful, the system routing table should show the corresponding interface, and the original path should return when the client stops. Sleep, network changes, and abnormal exits can leave the virtual interface present while the kernel is no longer running, making every application appear offline.

Games, virtual machines, container software, and corporate network clients may modify routing or DNS at the same time. When conflicts occur, disable TUN and restore the system proxy for comparison, then decide whether to exclude the target subnet with routing rules or adjust virtual adapter priority. LAN printers, network storage, and remote desktop addresses should usually remain direct. Do not send every private address range to the remote server, or LAN devices may become unreachable, domain authentication may slow down, and local development services may disconnect.

If TUN stops working after a Windows update or network driver change, restart the system and check that the virtual interface loads correctly. Security software may restrict newly created listening ports or network interfaces; configure explicit rules based on the process path and the purpose of the local listener. If logs show that the kernel started but the browser generates no request entries, the problem is usually at the system proxy or application proxy layer. If requests enter the client but fail to reach the remote server, continue checking server parameters, DNS, TLS, and current network restrictions.

macOS installation, chip selection, and network permissions

macOS uses the v2rayN desktop build. The key steps are choosing the correct chip build, completing first-launch authorization, and understanding the boundary between system proxy and network extension permissions.

Identify the chip and complete installation

Open “About This Mac” and check the chip or processor. If an Apple chip is listed, choose the Apple Silicon installer; if an Intel processor is listed, choose the Intel installer. Open the macOS download section and get the matching DMG. Open the disk image, drag the app to the Applications folder, and launch it from there. Do not run it long-term directly from the mounted disk image, as upgrades, saved permissions, and automatic startup may become unreliable.

On first launch, macOS confirms the app’s source and network access permissions. Follow the system prompts to authorize it before importing a configuration. If double-clicking does nothing, check Privacy & Security for a blocked-open request and confirm that the installer architecture matches the device. An Apple Silicon device may run an incorrectly installed Intel build through a compatibility layer in some environments, but it should not be the default choice; a native build is more direct for startup, resource usage, and network component compatibility.

Subscription imports and menu bar status

The v2rayN subscription workflow is the same as on Windows: create a subscription group, enter the URL, update it, and choose an active server. After the main window closes, the program may still be running in the menu bar, so check the menu bar rather than the window alone when deciding whether the client has exited. If the server list does not change after an update, check the selected group first, then review the update log. Multiple groups with the same name are easy to confuse, so use short, clear names based on purpose or service source.

After choosing a server, start the kernel and confirm in the log that there are no configuration parsing errors. Then enable the system proxy. macOS stores proxy settings per network service, so different Wi-Fi, wired, or other network services may have independent states. If the browser suddenly connects directly after changing networks, check whether the active network service is still configured by the client. Conversely, if web access fails after the client exits, check whether old HTTP, HTTPS, or SOCKS proxy addresses remain in the system network settings.

System proxy, terminal, and standalone proxy programs

The system proxy mainly covers applications that follow macOS network proxy settings. Terminal commands, development tools, and some cross-platform programs may read environment variables or ignore system settings entirely. To route a command-line program through the local proxy, set the relevant variable only in the current terminal session and replace the port with v2rayN’s actual listener. Closing the terminal session clears it, avoiding permanent proxy variables in global startup scripts.

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
env | grep -i proxy

Read “local HTTP port” and “local SOCKS port” from the client settings; do not copy values from another device. If a program supports only an HTTP proxy, do not enter a SOCKS address. Some command-line tools treat uppercase and lowercase environment variables differently. During troubleshooting, consult the tool’s documentation and use env | grep -i proxy to see which variables exist in the current session.

TUN, DNS, and sleep recovery

TUN mode requires higher-level network permissions. The first activation may ask you to approve a network extension, enter the device password, or allow background items. Authorization only loads the component; it does not guarantee correct routing. After enabling it, verify a regular webpage, a LAN address, a terminal request, and the target application in sequence. If only LAN access fails, check direct rules for private addresses. If every domain fails while a known address works directly, focus on DNS. If the device is completely offline after waking, stop TUN, exit the client, and start it again.

The macOS network service order, private relay-style network features, enterprise configuration profiles, and other virtual networking programs can all change the traffic path. During troubleshooting, run only one program responsible for taking over the default route. After switching from a home network to a public network, server reachability, UDP support, and DNS responses may change; the pre-switch state cannot alone prove a client failure. The safest recovery order is to disable interception and restore direct access, restart the kernel, then enable the proxy again.

Upgrades and configuration migration

Before upgrading, exit v2rayN from the menu bar and record the current subscription groups, routing mode, kernel type, and local ports. Replacing the app usually does not alter the configuration, but copying all runtime files from an old directory may bring along stale caches or obsolete components. A safer approach is to retain the subscription URLs and clearly defined custom rules, then migrate them after confirming basic functions in the new program. If the old and new builds use incompatible configuration structures, re-import the subscription instead of editing the internal database manually.

After migration, check login items and background item lists so the old and new programs do not start together. If two similar menu bar entries appear, exit every instance and launch the target version from the Applications folder. Log directories and temporary configuration may contain server details. Before sharing diagnostic material, remove subscription URLs, user IDs, domains, and ports. Keeping only the error type, stage, and necessary kernel message is usually enough to locate the problem.

Linux installation, desktop integration, and permissions

Linux uses the v2rayN desktop build. Before installing, confirm the distribution’s package system, processor architecture, desktop session, and graphical dependencies so interface problems are not mistaken for kernel problems.

deb, rpm, and processor architecture

Debian, Ubuntu, Linux Mint, and similar environments usually use deb; Fedora, Rocky Linux, and distributions using RPM package management use rpm. Check the device architecture with uname -m: the common x86_64 corresponds to x64, while aarch64 corresponds to arm64. When opening the Linux download section, match both conditions. Matching only the package format makes the installer refuse; matching only the architecture but choosing the wrong package system leaves the required package metadata unavailable.

uname -m
cat /etc/os-release
echo "$XDG_CURRENT_DESKTOP"
echo "$XDG_SESSION_TYPE"

/etc/os-release identifies the distribution and base system, while XDG_CURRENT_DESKTOP and XDG_SESSION_TYPE identify the desktop environment and whether the session uses X11 or Wayland. v2rayN’s proxy kernel does not depend on one particular desktop protocol, but tray icons, window scaling, startup behavior, and system proxy integration may vary by desktop environment. A server or minimal installation without a complete graphical session is not suitable for deploying a graphical client as a system service.

Install with the system package manager

A deb package can be opened in a graphical software installer or installed with the system package command; the same applies to rpm packages. The value of command-line installation is that it clearly shows missing dependencies, not that it bypasses distribution package management. Use the actual downloaded filename and do not treat sample text as a literal path.

sudo apt install ./downloaded-v2rayN-package.deb
sudo dnf install ./downloaded-v2rayN-package.rpm

After installation, launch it from the desktop application list. If no window appears, run the application entry in a terminal to observe error output, then check graphical libraries, display-server environment variables, and write permissions for the user directory. Do not run a graphical client as root long-term. Root creates a separate configuration under the administrator’s home directory and may prevent the regular user from reading files generated later. Elevation is needed only when installing packages, configuring TUN, or changing system-level network settings as prompted.

Subscriptions, system proxy, and desktop environment differences

Subscription imports still follow this order: create a group, update its contents, choose a server, and start the kernel. After the kernel starts, check the local HTTP and SOCKS listeners before deciding how to route application traffic through the client. GNOME, KDE Plasma, and other desktop environments store system proxy settings differently, and whether v2rayN can write them automatically depends on the current desktop integration. If the browser does not use the proxy after automatic setup, manually verify the loopback address and port in the desktop network settings, but do not retain an old client’s proxy value at the same time.

Terminal programs commonly read the http_proxy, https_proxy, or all_proxy environment variables. Graphical programs may follow the desktop proxy or use their own settings. Services managed by systemd do not automatically inherit environment variables from a login terminal; declare them explicitly in the service configuration. During troubleshooting, first determine whether the target is a browser, terminal process, desktop application, or system service, then check the corresponding entry point rather than looking only at the desktop proxy switch.

TUN, routing tables, and local services

Linux TUN requires kernel support, a device node, and permission to create a network interface. Before enabling it, check whether /dev/net/tun exists. Containers, virtual machines, network namespaces, and firewall managers may all add policy routes or packet marks. If v2rayN reports that TUN is running but traffic does not enter the kernel, check the default route, policy routes, DNS destination, and whether the firewall allows forwarding through the virtual interface. Do not clear the entire firewall without understanding the existing rules; this can disrupt system services and container networking.

ip address
ip route
ip rule
ss -lntup
resolvectl status

Use ip route to confirm the default route and private-network paths, ip rule to inspect policy routing, ss to verify that local proxy ports are listening, and resolvectl status to view DNS on systems using systemd-resolved. If the distribution uses another resolver, inspect the relevant network management service instead of repeatedly overwriting /etc/resolv.conf. On many distributions, this file is generated dynamically by NetworkManager or a resolver service, so manual changes may disappear after reconnecting.

Tray icons, startup, and upgrades

Some desktop environments do not display traditional tray icons by default, making it difficult to tell whether the client is still running after the window closes. Test the window-close behavior during first use and confirm the exit method through the process list. When configuring startup, keep only one desktop autostart entry; do not duplicate it between user-level startup files and desktop settings. Duplicate instances may compete for the same local port, causing the second instance to fail while subscription updates work but no proxy listener exists.

Exit every instance before upgrading, then install the new package with the distribution’s package manager. If dependencies conflict, read the exact package names and version constraints provided by the package manager instead of blindly removing desktop runtime libraries. Migrate subscriptions, routing, and DNS settings; runtime caches and generated files do not need to be copied wholesale. After upgrading, verify each layer in order: interface startup, kernel startup, local listeners, system proxy, and TUN.

Android installation, background operation, and per-app proxy

On Android, v2rayNG is the first choice and uses the Xray kernel by default; choose v2flyNG when you need V2Fly kernel behavior. Their import, connection, and per-app proxy workflows are similar.

Choose an arm64 or universal installer

Recent mainstream Android phones and tablets usually use arm64, so choose the matching installer first. If the architecture is unknown, the system is older, or installation reports incompatibility, use the universal package instead. A universal package contains code for more architectures and is usually larger, but offers broader compatibility. In the Android download section, choose the client first and then the architecture: v2rayNG is the usual choice; install v2flyNG only when V2Fly kernel behavior is specifically required.

Before installing, confirm that the system allows the current browser or file manager to open the downloaded installer. This permission is usually managed separately for each source app, and can be disabled for that source after installation. For an in-place upgrade, the application identifier must remain the same. If the system reports a signature mismatch, do not force the replacement; back up the subscription URL and custom settings, then confirm that the installed app and the new package come from the same source. Uninstalling clears the app’s private configuration, so do not uninstall while troubleshooting before saving subscription details.

Import subscriptions and QR codes

Copy the subscription URL, add a configuration under subscription groups, and run an update. QR codes are useful for importing a single server or service-provided subscription, but confirm the source before scanning. Gallery recognition may require storage or photo access, while camera scanning requires camera permission; grant each only when using the feature. After importing, check that entries contain the address, port, protocol, and transport details. Garbled names usually do not affect connectivity, but an entirely empty list indicates that the subscription was not parsed correctly.

Choose a server and tap the connect button. The system displays a network connection permission dialog; after confirmation, a network indicator appears in the status bar. This means the app has obtained the traffic entry point, not that the remote connection succeeded. Check the v2rayNG log and open a real webpage to verify it. If the connection drops immediately, focus on configuration parsing, port conflicts, and system restrictions on app startup. If it stays connected but webpages do not open, check server reachability, DNS, and the routing mode.

Background operation and battery settings

Android manufacturers’ power-saving policies may restrict v2rayNG after the screen turns off. Symptoms include a disconnect after the device has been locked, a persistent notification with no traffic, or reconnection when returning to the app. In system battery settings, allow the client to run in the background and add it to protected or unrestricted apps. Menu names vary by device; the relevant settings allow background activity, disable automatic freezing, and prevent cleanup tools from terminating the client process.

Keeping the client alive in the background does not mean disabling every power-saving feature. First determine whether the problem occurs only after locking the screen, switching mobile networks, or extended standby, then adjust v2rayNG specifically. If battery use rises significantly, check for unnecessary global proxying, frequent subscription updates, continuous latency tests, or high-overhead Mux settings. See v2rayNG background operation and battery troubleshooting, and address system restrictions, per-app proxy settings, and connection parameters one at a time.

Per-app proxy and LAN bypass

Per-app proxy controls which applications enter v2rayNG. An allow-list mode means only selected apps use the proxy; a bypass mode keeps selected apps direct. Before enabling it, identify the active mode so payment, LAN-control, or corporate-authentication apps are not accidentally sent to a remote server. System components, browser engines, and apps may call one another. Selecting only the main app does not guarantee that externally opened webpages or download services follow the same path.

LAN device addresses, router administration pages, casting devices, and network storage should usually remain direct. If they become unreachable after connecting v2rayNG, check whether the routing mode includes direct rules for private addresses. The local subnet changes when switching between mobile and Wi-Fi networks, so a rule for the old network may not apply to the new one. General private-address rules are usually more stable than individual device addresses, but enterprise networks may use more complex internal ranges that must be added based on the actual network.

Switching networks and restoring connections

When switching from Wi-Fi to mobile data, the underlying address, DNS, and IPv6 conditions all change. The app may retain a connected system state even though its old remote session has expired. Normally the kernel rebuilds the connection; if traffic remains stalled, toggle the client connection once instead of immediately deleting the subscription. Public Wi-Fi often requires browser-based authentication, so pause the proxy, complete the sign-in, and reconnect afterward.

If only one app cannot connect, first disable per-app proxy to compare, then check whether the app uses private DNS, built-in QUIC, or its own proxy settings. If every app fails, look for DNS timeouts, connection refusals, or TLS messages in the log. When requesting help, keep only the error stage and type; remove complete server addresses, user IDs, and subscription contents. Mobile problems often involve background restrictions and network changes, so record whether the app works in the foreground or only fails in the background, and whether Wi-Fi works while mobile data fails.

Subscription management, protocol parameters, and traffic routing

Subscriptions distribute configuration; routing determines which exit each type of traffic uses. Stable configuration depends on separating server-side parameters from local policy and avoiding repeated edits at the wrong layer.

The complete subscription update process

When a client updates a subscription, it requests the URL, reads the response, parses each server entry, and writes the results to a local group. A failure at any stage may appear as “update failed,” but each stage requires a different response. A timeout during the request points to the current network or URL reachability. An empty response points to the subscription status. A parsing error points to encoding, format, or client support. An empty list after writing points to group filters or filtering rules. Follow the six-step checklist for expired or unparseable subscription links to isolate the stage.

A subscription URL may contain access credentials and should not be shared publicly. When using one subscription across multiple devices, keep update frequency reasonable and avoid repeated refreshes in a short period. If scheduled updates are supported, choose an interval that matches actual needs, but do not confuse node testing with subscription updates. An update only synchronizes configuration; a latency test actively contacts servers. If the service removes an entry, the next update may remove it locally as well, so important manual configurations belong in a separate group.

Protocol and transport parameters must match as a set

VMess, VLESS, Trojan, and Shadowsocks describe different protocol systems. WebSocket, gRPC, and TCP are transport layers, while TLS and REALITY concern secure handshakes and server identity parameters. A connection works only when the complete parameter set matches the server, not merely when the protocol name is the same. Common VLESS fields include the user ID, transport, security type, server name, and flow control. Trojan requires matching password and TLS details; Shadowsocks requires matching encryption method and password.

A configuration generated correctly from a subscription normally does not require manual protocol edits. Change parameters only when the service explicitly provides instructions. Leaving the WebSocket path, gRPC service name, server name, or public key empty may cause connection failures. The server remark shown by the client is for identification only and is not part of the handshake; changing it does not change the connection. For a side-by-side protocol overview, see choosing between VMess, VLESS, Trojan, and Shadowsocks by scenario.

{
  "outbounds": [
    {
      "tag": "proxy",
      "protocol": "vless",
      "settings": {
        "vnext": [
          {
            "address": "server.example.com",
            "port": 443,
            "users": [
              {
                "id": "11111111-1111-4111-8111-111111111111",
                "encryption": "none"
              }
            ]
          }
        ]
      },
      "streamSettings": {
        "network": "ws",
        "security": "tls",
        "wsSettings": {
          "path": "/vless"
        }
      }
    }
  ]
}

This fragment illustrates field hierarchy; the example domain and user ID cannot be used for a real connection. A working configuration also needs the TLS server name, request headers, and other transport parameters that match the server. Graphical clients usually generate the complete structure from a subscription, so routine setup does not require editing JSON directly. Understanding these layers is useful when reading logs, checking fields, or migrating custom rules.

Routing rule order

Routing commonly matches domains, IPs, ports, network types, and process information to choose an exit. When rules are evaluated from top to bottom, specific rules should come first and the default rule should be last. Common exits are proxy, direct, and block. LAN and local addresses should be direct; domains that clearly require a remote exit should use the proxy; unwanted telemetry or malicious addresses can be blocked. Unmatched traffic follows the default exit, so the default determines the overall behavior.

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

IPIfNonMatch means that when no domain rule matches, the address is resolved for IP-rule evaluation. This increases DNS involvement, so DNS must be stable. With AsIs, routing relies more heavily on the original domain rules and does not proactively resolve every unmatched domain for IP matching. Available strategy names, rule-set sources, and update mechanisms vary across kernels and clients; use the options provided by the current client interface.

Choosing global, bypass, or custom rules

Global mode is useful for briefly testing whether a server works because nearly every target enters the proxy, minimizing variables. It is not the right default for every environment: LAN devices, local development addresses, and internal corporate services may become unreachable. A mainland-China bypass preset routes traffic using built-in domain and address rules, reducing maintenance, but its rule set must be updated with the client. Custom routing suits users with clear traffic boundaries. Start with a small number of rules, and record each rule’s purpose and expected exit as you add it.

Do not judge whether routing works solely by whether a webpage opens. Confirm the target domain, matched rule, and final exit in the client log. If an application resolves a domain to an address before connecting, the client may see only the IP. Sniffing can recover domain information from some connections, but it cannot reliably identify every protocol. Routing issues require considering the application’s request pattern, DNS response, and rule order together. Keep a copy of the default routing configuration so custom rules can be rolled back quickly.

System proxy and TUNworking with DNS

The system proxy determines whether an application actively connects to a local port, TUN takes over traffic at the network layer, and DNS determines how domains become addresses. Their responsibilities differ, but configuration errors can all look like “the webpage will not open.”

When is the system proxy appropriate?

The system proxy is easy to configure and suits browsers and desktop programs that follow the operating system’s proxy interface. The client usually listens locally on HTTP, SOCKS, or mixed ports, and the system proxy points to the loopback address. Once an application request reaches the local port, the kernel chooses a proxy or direct exit according to the routing rules. The system proxy does not cover every program by default: command-line tools, games, background services, and apps with their own networking stack may ignore it.

Before enabling the system proxy, confirm that the local port is listening. If another process occupies the port, the kernel may switch to another port or fail to start while the system still points to the old port. Clear the system proxy when exiting the client; after an abnormal exit causes total loss of connectivity, check for a leftover proxy first. The system proxy should point only to 127.0.0.1 or a local address explicitly supported by the client. Never enter a remote server address directly in the system proxy settings.

Why does TUN cover more traffic?

TUN creates a virtual network interface and receives packets sent by the system route, so it can cover programs that do not support HTTP or SOCKS proxies. The client converts those packets into connections the kernel can handle, then sends them to a direct or proxy exit according to the rules. TUN usually needs higher permissions and is more likely to conflict with other virtual networks, corporate security software, virtual machines, and container routes. Before enabling TUN, verify that the same server works normally in system proxy mode.

TUN configuration involves at least the interface address, route injection, DNS interception, MTU, and bypass scope. An MTU that is too large may allow a handshake but make large pages fail to load on some networks; one that is too small increases fragmentation and overhead. Defaults generally suit most networks and should not be changed without evidence. If the problem occurs only on a mobile hotspot, corporate network, or particular broadband connection, test by lowering the MTU gradually. Rebuild the connection and clear old sessions after each change.

Where does DNS resolution occur?

An application may pass domains to the system resolver or use its own encrypted DNS. In system proxy mode, a SOCKS request may carry the domain or only the IP already resolved by the application. TUN mode often intercepts DNS and sends queries through the client so routing rules can use domain information. If DNS goes direct while the target connection uses the proxy, it may return an address unsuitable for the current exit. If every DNS query is forced remotely, LAN names and corporate domains may be affected.

A stable approach usually handles public and internal domains separately: send LAN and corporate domains to local DNS, and choose other resolvers according to routing policy. For domain-based routing, ensure that the client can see the domain or use sniffing to supplement the information. Sniffing does not decrypt application content; it identifies visible target names from connection handshakes. With stronger encryption or non-standard traffic, identification may be limited.

When to use FakeDNS

FakeDNS returns virtual IPs from a reserved address pool and stores a mapping between each virtual address and its original domain inside the client. When an application then connects to the virtual IP, the client can restore the domain and apply domain routing in advance. It is useful in TUN scenarios that need stable domain-based routing but cannot obtain the domain directly from the connection. See how FakeDNS works and when to use it.

FakeDNS is not suitable for traffic that bypasses the client, and it may affect diagnostic tools that require real addresses, LAN discovery, or address validation in certain applications. If the system shows an address from a reserved range after enabling it, that is expected and does not prove DNS tampering. Check instead whether the client receives the virtual-address connection, whether the mapping exists, and whether the final exit can resolve and connect to the real target. After disabling FakeDNS, restart affected applications and flush the system DNS cache if necessary so old virtual addresses are not retained.

Recommended progressive setup

1. Verify the server with the system proxy firstConfirm that the subscription, protocol, TLS, and remote connection have no basic errors.
2. Keep default DNS while verifying domainsCheck regular webpages, LAN addresses, and the target app’s basic behavior.
3. Enable TUN separatelyDo not add complex routes yet; observe the virtual interface, default route, and application coverage.
4. Add direct rules for private addressesRestore access to routers, printers, network storage, and internal services.
5. Adjust DNS and FakeDNS lastChange one item at a time and use logs to confirm the relationship between domains, addresses, and exits.

To determine whether the configuration is complete, run four types of tests: a regular webpage loads, LAN resources remain directly reachable, a target program that ignores the system proxy enters TUN as expected, and direct connectivity returns after the client exits. Passing only one test does not prove that the whole path is correct. For complex networks, keep one baseline configuration with system proxy, default DNS, and default routing, plus a separate TUN configuration. This is more reliable than repeatedly editing parameters by hand when changing environments.

Common configuration issuesand layered troubleshooting

Troubleshoot from the outside inward along the data path: system network, client entry point, kernel startup, subscription parameters, remote connection, DNS, and routing. Every step should produce an observable result.

Layer 1: Confirm direct connectivity and system status

First stop client interception, disable TUN, and clear the system proxy. Confirm that the device can directly access a regular website on the current network. If direct access itself fails, fix Wi-Fi authentication, mobile data, the router, system time, or DNS before changing server settings. Public networks may require an authentication page; corporate networks may restrict unknown ports; after waking from sleep, the network adapter may not have obtained an address correctly. Later tests are meaningful only after the direct baseline works.

Also confirm that no other proxy client, virtual network program, or leftover environment variable is active. On Windows, check the system proxy and local listeners; on macOS, check the active network service and terminal variables; on Linux, check the desktop proxy, environment variables, and policy routes; on Android, check connection status and background restrictions. If the network remains intercepted after v2rayN or v2rayNG is closed, a system-level setting remains and must be restored first.

Layer 2: Confirm that the client and kernel actually started

An open window does not prove that the kernel is running. After choosing a server, check the status area and log to confirm that the configuration was generated, local ports started listening, and the process did not exit immediately. Configuration parsing errors usually identify a field, protocol, or JSON location. Port conflicts show a listening failure, while permission problems often appear when creating a TUN interface or network extension. Fix the first significant error in the log; later errors are often consequences of it.

If no local port is listening, pointing the system proxy at that port cannot produce a valid connection. After changing a port, update the system proxy, browser settings, and terminal environment variables together. When multiple clients start, the later one may fail to claim the default port. Exit every instance, confirm that the port is released, and start only the target client to eliminate contention directly.

Layer 3: Distinguish subscription failures from server failures

A successful subscription update only means that the configuration could be fetched and parsed; it does not mean every server in it works. Conversely, a failed update may not affect older servers already saved locally. Record two independent results during troubleshooting: whether the subscription URL updates and whether an existing server can connect. If all entries fail at once, first check the current network, a service-wide subscription change, the client kernel, or DNS. If only one entry fails, its parameters or remote status are more likely responsible.

When checking a configuration manually, verify the address, port, user ID, protocol, transport, TLS security type, server name, path, and service name. Do not randomly replace protocols or disable TLS in the hope of success; that only moves the configuration further from the server’s requirements. When the service provides a new subscription, update it and test the new entry instead of accumulating edits on an old one.

Layer 4: Use the log stage to choose a direction

“Connection timed out” does not prove that the server is unavailable. The current network, DNS response, IPv6 path, and firewall can all produce the same result. The most useful cross-test is to keep the server unchanged while switching networks, then keep the network unchanged while switching servers. If the same server works on another network, the issue likely concerns the current network path. If other servers work on the same network, the issue likely concerns that entry or the remote server. Change only one variable per test so the conclusion remains reliable.

Layer 5: Handle connections that work but are unusable

When the client shows connected but webpages do not open, first confirm whether application requests appear in the log. If there are no requests, check the system proxy, per-app proxy, or TUN routing. If requests appear but DNS fails, restore default DNS. If the domain resolves but the remote connection times out, check the server and network. If only some websites fail, check IPv6, MTU, routing rules, and target address selection. If only the browser fails, also check its built-in proxy, private DNS, extensions, and cache.

When webpages open but speed is abnormal, do not rely only on latency shown in the server list. Real-world speed depends on server load, route, target site, transport, and the current network. Disable batch latency tests, downloads, and other bandwidth-heavy programs, then compare using the same target. Mux does not improve performance in every environment; on mobile networks or unstable links it may amplify single-connection failures. If stalling persists, restore defaults and test again.

Layer 6: Recover, migrate, and provide useful logs

When a complex configuration makes the cause unclear, first export the subscription URLs and custom rules you need to keep, then build a minimal configuration: one subscription, one server, default DNS, default routing, and the system proxy. Once the minimal setup works, restore routing, TUN, DNS, FakeDNS, and per-app proxy one at a time. If the problem returns at one step, the scope is limited to that setting; reinstalling the client is not necessary.

When migrating between devices, do not copy active caches, lock files, or temporary configuration. Migrate subscription URLs, separate manual servers, routing-rule notes, and necessary DNS choices first. Platforms handle permissions, paths, and network interfaces differently, so copying the entire configuration directory may bring invalid paths or platform-specific state. After migration, complete system proxy or TUN authorization again according to the relevant platform section.

When sharing logs, describe the platform, client name, whether you use system proxy or TUN, whether the problem began after installation or a configuration change, whether direct access works, and the earliest significant error. Remove subscription URLs, complete server domains, user IDs, passwords, personal directory names in paths, and identifiable network information. Do not provide only the conclusion “it does not work”; reproducible steps and layered results are more useful than a large unredacted log.

• The installer matches the platform, processor architecture, and package system.
• Record subscription updates and server connections separately; do not treat them as one issue.
• Keep only the currently needed entry point: system proxy, TUN, or in-app proxy.
• LAN and internal services have explicit direct rules.
• Logs have been stripped of subscription, user ID, and sensitive server information.