V2Ray Configuration File Structure and Parameters

02 / INBOUNDS

inbounds Inbound Settings

The listen address determines who can connect

An inbound is the entry point where local applications hand traffic to the core. The most common local entrances are SOCKS and HTTP proxies. listen determines the network address, port determines the port, and protocol determines which proxy protocol the application should use. For device-only access, use 127.0.0.1. This address accepts connections only from the same device, allowing browsers, the system proxy and other local programs to connect while preventing direct access from other devices on the LAN.

To let a desktop client serve a phone, TV or another computer on the same LAN, the inbound usually listens on 0.0.0.0 or a specific LAN address. You must also handle the firewall, network profile and access controls; changing only the listen address is not enough. Shared devices should use the LAN address of the computer running the core and the inbound port—not 127.0.0.1. See the v2rayN LAN proxy sharing setup guide for related steps.

{
  "inbounds": [
    {
      "tag": "socks-in",
      "listen": "127.0.0.1",
      "port": 10808,
      "protocol": "socks",
      "settings": {
        "auth": "noauth",
        "udp": true
      },
      "sniffing": {
        "enabled": true,
        "destOverride": [
          "http",
          "tls"
        ]
      }
    },
    {
      "tag": "http-in",
      "listen": "127.0.0.1",
      "port": 10809,
      "protocol": "http",
      "settings": {}
    }
  ]
}

The Boundary Between SOCKS, HTTP and Transparent Interception

A SOCKS inbound is suitable for applications that explicitly support SOCKS and can carry TCP, with UDP support when enabled. An HTTP inbound is intended for programs that connect through HTTP CONNECT or a standard HTTP proxy. Both require the application or system proxy to point to the correct port. An application configured for HTTP cannot point to a SOCKS port; even with the right port number, using the wrong protocol commonly causes an immediate disconnect, a browser proxy error or unrecognized handshake data in the logs.

TUN mode differs from an ordinary local proxy. It receives a wider range of system traffic through a virtual network interface and also requires routing-table, DNS-interception and permission settings. Do not treat TUN as simply adding another SOCKS inbound. v2rayN assembles runtime parameters from its TUN options, so enable it through the client interface first and then inspect the logs instead of inserting a complete TUN fragment from another environment. When the ordinary system proxy already covers browsers and common desktop programs, there is no need to enable multiple interception methods just to cover more traffic.

How sniffing Helps with Domain-Based Routing

sniffing recovers a destination domain from protocol characteristics in a connection. Some applications resolve a domain themselves and pass only the resulting IP address to the proxy; if routing contains only domain rules, the core cannot match those rules against a bare IP. With sniffing enabled, host information in an HTTP request or the server name in a TLS handshake can provide a domain to the routing module. In the example, destOverride allows the recognized HTTP or TLS destination to replace the original destination address for subsequent rule evaluation.

Sniffing is not a replacement for DNS, and not every connection reveals a domain. Protocols without recognizable host information still appear as IP addresses; encrypted handshakes and application behavior also affect the result. When a route is not matched, check whether the access log records a domain or an IP, then decide whether to adjust domainStrategy, add IP rules or inspect sniffing. Do not repeatedly stack identical domain and IP conditions without first reviewing the logs; that only makes the rules harder to maintain.

Configuration Principles for Ports, Authentication and Tags

Two processes cannot occupy the same port on one address, and two inbounds cannot listen on the same address and port. If the client immediately reports that an address is already in use, close duplicate instances and check other proxy tools or old core processes. Changing the port alone solves only half the conflict: the system proxy, browser extensions and LAN devices must use the new port too. Keeping SOCKS and HTTP ports adjacent can reduce confusion, but never infer the protocol from a fixed port number.

auth: "noauth" is suitable for a local SOCKS inbound that listens only on the loopback address. When listening on a LAN address, assess authentication support and firewall restrictions together, and allow access only from trusted networks. Give each inbound its own tag so inboundTag can apply different routes to different entry points—for example, normal split routing for local traffic and restricted ports for a shared LAN entry. After renaming a tag, search the entire configuration for routing references so no rule still points to the old name.

04 / ROUTING

routing Routing Rules

Rules are checked from top to bottom; the first match wins

The routing module selects an outbound using the connection’s destination domain, IP, port, network type, protocol characteristics or inbound tag. The key behavior is rule order: rules are normally checked from top to bottom, and once one matches, its outboundTag is used while later rules are ignored. Put specific rules first and broad rules later. If “all TCP traffic goes through the proxy” is the first rule, later direct-domain rules can never take effect.

When designing rules, define the default policy first, then list exceptions. If the proxy is the default outbound, place block conditions and explicit direct conditions first, letting everything else fall through to the proxy. If direct is the default, list the destinations that need the proxy first. Do not express one policy simultaneously through array order, complex domain lists and multiple fallback rules. Choose one clear default and use rules only for exceptions; future maintenance becomes much easier.

{
  "routing": {
    "domainStrategy": "IPIfNonMatch",
    "rules": [
      {
        "type": "field",
        "protocol": [
          "bittorrent"
        ],
        "outboundTag": "direct"
      },
      {
        "type": "field",
        "domain": [
          "domain:intranet.example.com",
          "full:printer.example.net"
        ],
        "outboundTag": "direct"
      },
      {
        "type": "field",
        "ip": [
          "geoip:private"
        ],
        "outboundTag": "direct"
      },
      {
        "type": "field",
        "network": "tcp,udp",
        "outboundTag": "proxy"
      }
    ]
  }
}

Domain Matching Determines Rule Boundaries

Common domain conditions include exact matches, a domain and its subdomains, keyword matches and built-in domain sets. full:printer.example.net matches only that complete hostname and suits one clearly bounded service. domain:example.com generally covers the domain and its subdomains and suits a related group of hosts. A string without a prefix may be interpreted differently depending on context, so explicit match types are easier to maintain and preserve the original intent.

Keyword matching is broad, so a short string may unexpectedly match unrelated domains. Unless classification by a name fragment is intentional, prefer full or domain. When a rule does not match, first check whether the core sees a domain or an IP address. If the application resolved the destination locally and inbound sniffing did not recover the domain, even a precise domain rule will not run. Check access logs, enable suitable sniffing or add IP conditions for known ranges.

domainStrategy Connects Domain Rules with IP Rules

domainStrategy controls when the routing module resolves a domain in order to match IP rules. AsIs emphasizes the form received, so the domain is not actively converted to an IP solely for routing; IPIfNonMatch generally resolves the address only after domain rules fail and then tries IP rules. Other strategies may resolve more aggressively. The more active the strategy, the more domain traffic can participate in IP classification, but the tighter the coupling between DNS behavior and routing results.

Before choosing a strategy, ask whether the rules mainly depend on domains or IPs. If most rules use explicit domains and only a few networks need additional checks, IPIfNonMatch is easier to understand. If every domain must first be classified by address, DNS must match the intended outbound. Otherwise different resolvers, caches or address families can produce different results and change routing. After changing domainStrategy, test domain rules, IP rules and unmatched destinations rather than judging success from one webpage.

IP, Port, Network and Inbound Tags Can Be Combined

IP conditions can specify a single address, a CIDR range or a built-in set supported by the core. Private addresses should usually go direct so routers, printers and LAN services are not sent to a remote server. Port conditions suit a defined service range, such as 53 or 80,443, and can also express intervals. Common network values are tcp, udp or both. Different fields in one rule generally must all match; multiple values in one field array usually mean that any value can match.

inboundTag is useful for separating traffic sources. For example, socks-in can use normal split routing while lan-in is limited to a designated outbound. This avoids running multiple core instances for different sources. Confirm that the inbound tags actually exist, and put source restrictions near the beginning of the rules so broader destination rules do not win first. Be conservative when blocking ports and protocols: an overly broad range may let an application open its home page but prevent playback, login or synchronization.

Verify Rules with Logs, Not Guesswork

The most effective way to verify routing is to prepare a few clear test cases: an internal domain that should go direct, a target that should use the proxy and a condition that should be blocked. Then inspect the outbound tag in the access log. If the log shows the target but not the expected tag, temporarily increase logging detail and restore a restrained level afterward to prevent unbounded growth. Reload or restart the core after changing rules, and confirm that the client is not still using an old runtime configuration.

As the rule set grows, keep maintenance notes outside the configuration explaining why each group exists; this is more useful than recording only a domain list. Standard JSON cannot contain comments, so store the notes in a separate document. Subscription updates generally affect nodes and proxy outbounds and should not overwrite manual routing. If rules disappear after every update, you are probably editing a temporary generated file; use the client’s routing configuration entry point instead.

06 / POLICY

policy Policy and Statistics

policy controls runtime behavior, not routing direction

policy is often mistaken for an extension of routing, but it mainly controls session timeouts, idle detection and statistics switches. Whether traffic uses a proxy or direct access is still determined by routing and the outbound. Policies are usually organized by user level, and the level in an outbound user object can link to the corresponding level; most configurations use the default level unless a special behavior is required. Add multiple levels only when different session behavior is genuinely needed.

Shorter timeouts are not automatically better. A brief period without data does not mean a connection is dead. Long polling, intermittent file transfers, remote terminals and persistent applications can all have idle periods. A very low idle value causes frequent reconnects; an excessively high value delays cleanup of dead connections. Start with the client or core defaults and adjust only when logs and application behavior demonstrate a need.

{
  "policy": {
    "levels": {
      "0": {
        "handshake": 4,
        "connIdle": 300,
        "uplinkOnly": 2,
        "downlinkOnly": 5,
        "statsUserUplink": false,
        "statsUserDownlink": false
      }
    },
    "system": {
      "statsInboundUplink": false,
      "statsInboundDownlink": false,
      "statsOutboundUplink": false,
      "statsOutboundDownlink": false
    }
  }
}

handshake and connIdle Handle Different Stages

handshake limits how long the connection may wait during establishment. It applies to a handshake that has not completed, not to the total time required to load a webpage. If it is too short, network fluctuation or a slow remote response can cause premature failure; if too long, clearly impossible connections consume resources longer. For handshake timeouts, check the server address, port, transport layer and local network before simply increasing the value.

connIdle controls how long a connection is kept when there is no data activity. After an idle connection closes, the application will usually reconnect, though some programs show this as a session interruption. During debugging, check whether the failure occurs after a consistent interval: repeated disconnects after a similar idle period point to policy; random timing with remote resets is more likely a network or server behavior.

uplinkOnly and downlinkOnly handle connections with activity in only one direction. They are not upload or download speed limits and do not allocate bandwidth to an application. Without understanding the existing connection behavior, do not shorten them casually as an “optimization.” Defaults generated by a graphical client are generally suitable for ordinary use; long-lived connections, resource constraints or a clearly defined service are reasons for separate evaluation.

Statistics Switches Only Grant Collection Permission

statsUserUplink, statsUserDownlink and the inbound and outbound statistics fields under system allow the core to record traffic in the corresponding directions. Enabling these Boolean values does not necessarily create visible charts or interface counters; a supported statistics module and query method are also required. If the client does not consume the data, enabling every statistics item only adds unnecessary state maintenance.

Do not use statistics as a connection-success test. Bytes in one direction only show that some data passed through the relevant counter; they do not prove that the destination content returned completely or that routing matched expectations. Judge connection quality from access results and error logs as well. Client traffic figures may come from a system interface, core interface or client-side counter, so their definition may not match every policy switch exactly.

Multiple User Levels Need an Explicit Link

When a configuration contains several user objects, assign different level values and define the corresponding policies under levels in policy. Level keys appear as strings in JSON, such as "0" and "1". If a user references an undefined level, the core may use default behavior or report an error, depending on the implementation. Check user levels and policy levels together rather than copying only half of the relationship.

Ordinary client outbounds rarely need a complex level hierarchy. The identity supplied by a node subscription is mainly for remote protocol authentication; it does not mean that every node needs its own local policy level. Multiple levels are more common when the configuration serves inbound users with different session policies. This page focuses on client configuration, so a single default level is usually best—put the effort into inbound security, outbound parameters and readable routing.

Use Log Levels Alongside Policy Troubleshooting

Policy issues often look like “the connection is established, then drops,” so logs need to provide a timeline. For everyday operation, use a restrained level such as warning; during troubleshooting, temporarily increase detail and record the start time and reproduction steps. If the log path points to a directory without write permission, the core may fail to start or leave no diagnostic information. Graphical clients usually handle log locations; check file paths carefully when running a standalone core.

After reproducing the issue, compare three times: connection start, last data activity and connection close. If the close follows a policy threshold, change one setting and test again. If the log clearly shows a remote close or lower-level connection failure, policy is not the main lead. Restore a reasonable log level after debugging and remove statistics switches enabled only for testing.

08 / TROUBLESHOOTING

Troubleshooting Configuration Errors and Connection Failures

Startup Fails Immediately: Find the First Clear Error

When the core fails to start, the log may contain several cascading messages. The real cause is usually near the earliest clear error. Common types include JSON parsing failures, unknown fields, invalid data types, port conflicts, inaccessible file paths and missing tags referenced by routing. Fix the first error and restart; do not modify several areas at once based on later messages, because they may only be consequences of the initial failure.

A JSON parsing error usually includes a line number or character position. Check for a missing comma, a trailing comma, an unclosed quote or full-width punctuation around that location. The position may indicate where the parser noticed the problem while the actual omission is on the previous line. In a long file, temporarily remove the entire recently added object, confirm that the base configuration works, then restore the fragment one level at a time.

The Core Runs, but the Application Cannot Connect to the Local Proxy

Do not check the remote node first. Confirm that the application’s proxy address is 127.0.0.1, that the port matches the inbound and that the proxy type is correct. If using the system proxy, check that the client has enabled the corresponding mode; starting the core alone does not necessarily change system settings. Browser extensions, in-app proxies and the system proxy can coexist, creating duplicate paths or pointing to an old port. For testing, keep one clear path.

On Windows, macOS and Linux desktops, an old process occupying the port is common. Exit the client, confirm that the core process has ended, and then reopen it. If you changed the inbound port, update the system proxy too. Android clients use system-provided network interfaces to intercept application traffic, so troubleshooting differs from a desktop SOCKS port; first check that the client is connected and that the core started successfully in the runtime logs.

The Local Proxy Connects, but the Remote Handshake Fails

When logs show a refused connection, failed handshake or early remote close, check in this order: address and port → user identity → protocol → transport → security layer. A resolvable domain does not prove that the port serves the right service, and a successful TCP connection does not prove that the TLS name and application transport match. For subscription nodes, perform a normal update first and confirm that the current entry is not using old parameters; for manual nodes, compare each field with the original configuration.

An obviously incorrect system clock can break time-dependent secure connections, so restore the device time first. If switching networks makes the problem disappear, also check the current network, DNS and address family rather than changing only the protocol. Follow the node timeout troubleshooting checklist step by step instead of repeatedly editing the outbound object while skipping the local network and system time.

Only Some Websites or Applications Fail

Failures limited to certain targets usually mean the basic inbound and at least one outbound work; focus next on routing, DNS, UDP and destination characteristics. Compare which outbound a successful target uses with the one used by a failed target, then check whether the failed request entered the core as a domain or IP. If a mistaken rule sends a domain to direct, a healthy node will not participate. If domainStrategy resolves a different address family, the result may also differ from the domain rule’s intent.

Login, voice, video and synchronization features may use different domains, ports and network types. Opening the home page proves only that some requests succeeded. Do not assign an application’s entire domain to one broad rule based on the home page alone. During reproduction, record the logged destination for the failed feature and add only the necessary conditions. For UDP, check whether the SOCKS inbound allows it, whether the protocol and server support the path, and whether routing sends UDP to the correct outbound.

The Rule Looks Correct but Never Matches

First check the rule’s position. Is there a broader domain, IP, network or port condition above it? Next check the target form: does the log show a complete domain, a subdomain, an IP or a name recovered through sniffing? Then verify the prefix: full does not automatically cover every subdomain, while keywords may be too broad. Finally check the spelling of outboundTag and the active runtime file; you may have edited a backup while the client loads another configuration.

To verify a rule, temporarily move it near the top and restrict it to one explicit domain. Check the outbound tag in the log. If it still does not match, the problem is the target form or an unloaded configuration. If it matches only after being moved up, an earlier rule intercepted it. Once the cause is clear, reorganize the order instead of permanently piling every new rule at the top, which eventually causes specific rules to override one another.

The Connection Drops After Running for a While

First determine whether the disconnect occurs at a consistent interval. If it repeatedly happens near connIdle or a one-way connection policy threshold, inspect policy. If the timing is random, check remote resets, network changes, device sleep and address changes. When a laptop moves between networks, old connections becoming invalid is normal and the client usually needs to establish them again. Do not attribute a single post-sleep interruption directly to node parameters.

timeout, context canceled and connection reset in the logs represent different stages and initiators. Do not apply the same fix to every message containing “error.” For timeout, use the preceding record to determine whether the issue is DNS, dialing or the handshake. context canceled may mean that an upper-layer request ended deliberately; reset means one side reset the connection. Find the earliest anomaly on the timeline before treating later errors as cancellation or cleanup.

Keep Reproducible Troubleshooting Notes

For a complex configuration, keep a short record containing the client name, core family, inbound port, default outbound, recently changed areas and reproduction steps. Do not store sensitive node information; the structure is enough. For each test, write down what changed, what you expected and what the logs showed. After two or three rounds, most guesses can be eliminated. Switching many options without taking notes makes it hard to identify the cause even if the problem happens to disappear.

When recovery is needed, return to the minimal working configuration, then add DNS, split routing and policy one at a time. If the minimal setup still fails, the problem is more likely the client installation, local network or node itself; return to the quick-start path to recheck import and connection steps. If only custom rules fail, keep the verified node outbound and focus on routing and target logs instead of reinstalling the client.