V2Ray Configuration Files: Complete Reference

listen, port, and exposure scope

The first fields to check in an inbound object are listen and port. When a desktop client provides a proxy for local applications, it usually listens on 127.0.0.1, meaning only the current device can connect. Changing the listen address to an external network interface expands the reachable scope and requires consideration of the local network boundary, system firewall, and authentication. If the proxy is only for a browser, terminal, or local application, there is no need to widen the listen scope.

The port must not already be occupied by another process. Two inbounds in the same configuration also cannot listen on the same port at the same address. Common clients create separate SOCKS and HTTP inbounds, or use an implementation with a mixed entry point. System proxy settings generally use an HTTP entry, while applications that explicitly support SOCKS can use the SOCKS port directly. If an application sends HTTP requests to a SOCKS port, logs may show an unrecognized handshake, a closed connection, or an invalid request format. This is not a remote-node failure; the local inbound protocol is wrong.

SOCKS inbounds and UDP

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

auth controls authentication for a SOCKS entry; when listening only on the loopback address, noauth is commonly used. udp determines whether SOCKS UDP requests are accepted. Enabling it does not mean every application will automatically send UDP through the proxy. The application must support SOCKS UDP, and the remote protocol and transport chain must also handle the traffic. When ip is used for the return address in a UDP association, it should match the actual reachability requirements. A loopback address is intuitive for a local entry; if the entry serves other devices, verify that the address is reachable by the requesting device.

HTTP inbounds and system proxy settings

{
  "tag": "http-in",
  "listen": "127.0.0.1",
  "port": 10809,
  "protocol": "http",
  "settings": {
    "allowTransparent": false
  },
  "sniffing": {
    "enabled": true,
    "destOverride": ["http", "tls"],
    "routeOnly": true
  }
}

An HTTP inbound handles standard proxy requests and CONNECT tunnels, making it suitable for browsers and software that follows system proxy settings. It is not the same as the HTTP service used by a website server: the application must know explicitly that this is a proxy port. Terminal commands, development tools, and background services may not read the desktop system proxy, so a working browser does not prove that every program uses this inbound. If “web pages work but the command line connects directly,” check the target program's proxy options or environment variables before examining the V2Ray configuration.

The role and limits of sniffing

Traffic sniffing recovers the destination domain from some connections, allowing domain-based routing rules to match. With a TLS connection, for example, an application may resolve a domain locally before connecting to an IP address; if the inbound sees only the IP, a domain-only rule may not match. With sniffing enabled, the core can identify the destination domain from handshake information. destOverride specifies the protocol types that may be identified, while routeOnly means the result is primarily used for routing decisions rather than forcibly replacing the final connection target.

Sniffing is not general-purpose decryption, and it cannot guarantee that every connection exposes an identifiable domain. Non-standard protocols, changing encrypted handshakes, application-level encapsulation, or direct IP access may leave only an IP condition. Routing should account for both domain and IP rules rather than relying entirely on sniffing results. If an application behaves abnormally with sniffing enabled, disable it for that inbound or split the traffic into separate inbound tags so routing can handle each entry independently.

How multiple inbounds work together

The most useful purpose of multiple inbounds is separating traffic sources. For example, keep http-in for a browser and socks-in for development tools, then use inboundTag to apply different routes. This is more reliable than guessing an application's source from its domain. Each entry should have a clear tag, and its port should remain consistent across the client interface, system proxy, and application settings. After changing v2rayN's local port, the old system proxy value or terminal environment variable will not necessarily update automatically; check both the listener logs and the application's configuration.

Rules are matched from top to bottom

routing.rules is an ordered array. When a request reaches the router, rules are generally checked from top to bottom, and the first match determines the destination outbound. Put narrow, clearly intended rules first and broad rules later. For example, direct LAN traffic should precede a broad proxy rule, and a specific domain block should precede a general domain-proxy rule. If a rule proxying every port comes first, a later direct-LAN rule will never take effect.

The rule type is usually field, followed by conditions such as domain, ip, port, network, protocol, and inboundTag. When one rule contains several types of conditions, the combined conditions must be satisfied for a match; multiple values in the same field usually mean that any one of them may match. Packing unrelated conditions into one rule can make it narrower than expected. A clearer approach is to split them into several rules with one purpose per rule.

A common basic traffic-splitting structure

{
  "routing": {
    "domainStrategy": "IPIfNonMatch",
    "domainMatcher": "hybrid",
    "rules": [
      {
        "type": "field",
        "ip": ["geoip:private"],
        "outboundTag": "direct"
      },
      {
        "type": "field",
        "domain": ["geosite:private"],
        "outboundTag": "direct"
      },
      {
        "type": "field",
        "protocol": ["bittorrent"],
        "outboundTag": "direct"
      },
      {
        "type": "field",
        "domain": [
          "domain:example.net",
          "full:status.example.org"
        ],
        "outboundTag": "proxy"
      }
    ]
  }
}

geoip:private matches common private address ranges and helps keep router, printer, and LAN service traffic from taking a remote route. geosite:private handles the corresponding private-domain set. GeoIP and GeoSite come from different data sources: the former classifies IP ranges, while the latter classifies domain collections. If the data files are outdated, classifications may lag behind; see How to update GeoIP and GeoSite data files.

domain: matches a specified domain and its subdomains, full: matches only the complete hostname, and keyword: matches by keyword. Prefer full: for an exact service, and use domain: for a site and its subdomains. Keyword matching is broad and can accidentally match unrelated domains with similar names, so use it only when the scope is clear and logs have confirmed the result. Plain strings in rules may have different default interpretations depending on the core and configuration context; prefixes reduce ambiguity in hand-written configurations.

How domainStrategy affects domain and IP rules

AsIs means the routing stage handles the original destination as much as possible. When a request arrives with a domain, domain rules can participate; when it contains only an IP, a domain rule generally cannot recover the name on its own. IPIfNonMatch resolves the domain and tries IP rules only after domain rules fail to match. IPOnDemand may trigger resolution earlier when an IP-based rule requires it. These strategies affect DNS timing, route matches, and connection latency, so do not choose one by name alone.

If you want domain sets to take priority and IP geolocation rules to act as a fallback, IPIfNonMatch is usually easier to understand: check the domain first, then resolve it and check the IP if nothing matches. If the configuration contains many IP rules and needs an address early, consider IPOnDemand. If you do not want the router to resolve domains proactively for matching, use AsIs and ensure that inbound sniffing or the application request provides enough destination information.

Split traffic by port, network, and inbound tag

{
  "type": "field",
  "inboundTag": ["socks-in"],
  "network": "tcp",
  "port": "443",
  "outboundTag": "proxy"
}

Ports can be a single value or a range, such as 80,443 or 10000-20000. A port describes the target service port, not a specific website or application; many services share port 443, so port-only routing is usually broad. network can distinguish TCP from UDP, while inboundTag routes based on the local entry through which the request arrived. Creating separate entries for different types of software and routing by inbound tag is often more general than guessing process names.

No match and unintended matches

When no rule matches, the request uses the default outbound. Confirm the default behavior from the configuration structure and core implementation; do not assume it is always direct or always proxied. For troubleshooting, enable an appropriate runtime log level and record the request target, inbound tag, and final outbound tag. If a rule does not match, check whether the request contains a domain or IP, whether sniffing works, whether Geo data exists, and whether the rule prefix is correct. If the wrong rule matches, scan down from the top of the array to find the first rule that covers the target.

After adjusting routing, test a few explicit targets separately: one LAN address, one domain intended to connect directly, one domain intended to use the proxy, and one blocked target. Do not use “most pages open” as proof that traffic splitting is correct, because the default outbound may conceal rule errors. Node latency tests only describe the result of specific test requests and cannot replace rule-by-rule verification. For cases where system proxy and terminal traffic differ, continue with Troubleshooting browsers and command-line terminals separately.

levels and user-level references

policy.levels uses user levels as keys and applies policies to connections at each level. User objects in some inbound or outbound protocols may include a level, which is then used to find the corresponding policy. A level is not a speed rating or an automatically ordered permission rank; it is simply a numeric key for referencing a policy set. If no level is explicitly assigned, the default level is usually used, but confirm the exact behavior from the current configuration and core implementation.

A single level can consistently control handshake time, idle connection time, and upload/download statistics. Do not create many unreferenced levels just to make the configuration look complete. For a client-generated single-user outbound, it is usually enough to understand whether the default level enables statistics or changes timeouts. Multi-user servers use levels more often for differentiation, but this page focuses on reading client configurations, so pay particular attention to policies that may unintentionally shorten normal connections.

Policy object example

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

handshake limits how long the connection setup phase may wait. If it is too short, network fluctuations, name resolution, or a slightly slow remote handshake may be terminated prematurely; if it is too long, unreachable connections take longer to report failure. connIdle describes how long a connection may remain open without data transfer. Long-lived applications, push messaging, remote terminals, and continuous-transfer tools are more sensitive to idle time, so do not tune it based only on web browsing.

uplinkOnly and downlinkOnly control how long a connection is kept after only one direction of data remains. They manage connection lifetime and do not limit bandwidth. bufferSize affects the data-buffering strategy for each connection; increasing it blindly may raise memory use, while reducing it too far may hurt throughput. Most client users should keep the defaults provided by the core or client and adjust them only when logs and reproducible tests show a connection-lifecycle problem.

Understand statistics switches in pairs

statsUserUplink and statsUserDownlink control per-user statistics, while the entries in policy.system control inbound and outbound statistics. Writing only "stats": {} does not necessarily collect every metric automatically; the corresponding policy switches must also be enabled. Conversely, enabling statistics without any interface or API reading the values only creates extra recording work. Whether a desktop client displays traffic statistics also depends on how it starts the core and reads the statistics API.

Statistics are useful for observing traffic direction in the current running instance, but they should not be treated as an authoritative source for subscription quotas, billing records, or remote-server traffic. Restarting the client, reloading the configuration, or switching cores may reset local statistics. When troubleshooting missing traffic numbers in the interface, first confirm whether the client is designed to read core statistics, then check the stats object and system switches rather than changing protocol parameters.

How policy relates to timeout errors

A timeout in the logs may occur during name resolution, a TCP connection, TLS or REALITY handshake, proxy-protocol handshake, or application read/write. policy explains only some session timeouts. If a connection consistently stops after a short interval, check handshake and connIdle; if the logs explicitly say that the remote address timed out, check the network and outbound first; if only one application's long-lived connection drops periodically, compare its idle interval with the policy values.

Before changing timeouts, record the stage and timing pattern of the error. Simply making every value very large delays failure feedback and keeps dead connections consuming resources longer. Making every value smaller harms slow networks and long-lived connections. Keep the default policy as a baseline, change one item only for a reproducible case, and retest the same target after restarting the client.

System policies and configuration portability

Different clients and core families may support different policy fields or defaults. The core used by v2rayN, the Xray core commonly used by v2rayNG, and the v2fly core associated with v2flyNG may behave differently even where their fields are compatible. Before copying a complete configuration to another client, check whether the target client permits a fully custom configuration and whether it rewrites policy at startup.

Portable configuration is not about using as few fields as possible; it is about clearly separating standard structure, core extensions, and client-generated content. Inbound ports, log paths, and TUN parameters often depend on the platform; server protocol parameters are usually portable; interface state and runtime configuration may not correspond one-to-one. When moving between platforms, establish a working baseline by importing the subscription first, then migrate routing, DNS, and policy item by item instead of replacing the entire file.

Startup failure: check syntax, ports, and references first

When the core exits immediately after startup, check three categories first. The first is JSON syntax, including missing commas, mismatched brackets, and incorrect data types. The second is local resource conflicts, such as a listen port occupied by another process, an unwritable log directory, or a TUN device that cannot be created. The third is configuration-reference errors, such as a nonexistent routing target tag, missing required protocol fields, or an extension unsupported by the current core.

Follow the order shown in the logs. A parsing error occurs while reading, so fix the file first; an address conflict occurs while listening, so check duplicate clients and local ports; a missing outbound occurs while building routes, so verify tags. Only after the core clearly reaches a running state should you investigate remote connections. A client interface showing “not connected” is not enough to identify the layer; inspect the final portion of the error log.

The local port exists, but the application has no traffic

First confirm that the application uses the correct proxy type and port. HTTP and SOCKS proxies are different entries, and a system proxy does not guarantee that terminals or background services use it. Then check whether the application bypasses local addresses, has its own resolver or proxy settings, and whether the request actually reaches the access log. If this request is completely absent from the log, the problem lies between the application and the inbound; an inbound record means the traffic has entered V2Ray.

If only some applications fail, configure an explicit SOCKS or HTTP entry for the affected application as a comparison. If a manual entry works but the system proxy does not, check the operating system's proxy state and exclusion list. If a browser works through the system proxy but the terminal does not, configure a proxy option supported by the terminal tool. Do not change the remote-node protocol just because one application bypasses the system proxy.

Domains fail while IPs work

Prioritize the resolution path. Confirm whether the application submits a domain or an already resolved IP, whether built-in DNS receives the query, whether the server returns a usable address, and whether queryStrategy selects an address family reachable on the current network. If the domain rule depends on sniffing, check whether the inbound can identify the destination name. With Fake DNS, verify that the reserved address is restored by the same running instance.

If DNS has already returned an address but the connection times out during the outbound phase, the problem is no longer “no resolution result”; it is the address's connection path, routing, or remote service. If expectIPs rejects the returned address, check the Geo data and server groups. If only a recently changed domain still uses the old address, consider application, system, and built-in caches; restart the relevant processes or test a new domain to rule out caching.

The rule looks correct but does not match

Start with the request's actual form: does the router receive a complete domain, a subdomain, or an IP? Does the rule use full:, domain:, or a keyword? Is a broader rule above it matching first? Are the Geo data files available? Similar-looking rule text and targets do not guarantee identical matching semantics. full:example.com does not match other subdomains, while an overly broad keyword may match several unrelated targets.

Temporarily moving the problem rule toward the top of the array can show whether another rule is masking it, but review the overall order again after testing. A more reliable method is to enable routing logs and record the outbound tag ultimately selected for the request. If the request contains only an IP, a domain rule naturally cannot match; check sniffing, the application's resolution behavior, or add a suitable IP rule instead of repeatedly rewriting the same domain string.

Node parameters are correct, but the handshake fails

Confirm that the server address and port are reachable, then check protocol identity parameters, transport, and the security layer. For TLS, check the server name, system time, and certificate errors. For REALITY, check the server name, public key, short ID, fingerprint, and flow-control parameters. Other protocols likewise require every client parameter to correspond to the server. Do not combine transport fields from different nodes into one configuration, because each layer may depend on the others.

If failure begins immediately after a subscription update, keep the old node for comparison and check whether the address, port, transport, or identity parameters changed. Do not guess missing fields manually. If every node fails at once, check the local network, system time, core startup, and routing first; if only one node fails, its parameters or remote state are more likely to be responsible.

Organization principles for growing configurations

Over time, configurations accumulate dead tags, duplicate domain rules, overlapping Geo rules, and unused inbounds. When cleaning up, map the current processing chain first: list every inbound tag, outbound tag, each rule's target, and the purpose of every DNS server. Delete objects only after confirming that nothing references them. Rules with the same target and outbound can be merged, but do not pack different purposes into one opaque rule just to reduce line count.

Use a stable naming convention for tags and order routes as “special blocks, direct LAN traffic, specific proxies, default handling.” Group DNS server objects by applicable domain scope, and keep only levels that policy actually uses. When the configuration format does not support comments, maintain a separate record describing each tag's purpose, the last verified scenario, and how the client generates the file. This makes future changes safer.

Client updates and configuration migration

Before updating the client, save the currently working configuration, routing presets, and subscription settings. After updating, run a minimal connection test with an existing node before checking advanced features. If the client changes its core, watch startup logs for unknown fields and deprecation notices. Do not delete underlying configuration just because interface labels changed; export the newly generated runtime file and compare its top-level sections with the old configuration.

When moving from one desktop platform to another, server protocol parameters can usually be restored through the subscription, but local listen ports, system proxy settings, TUN permissions, and log paths must be configured again for the new platform. When moving to v2rayNG or v2flyNG on Android, import the subscription first, then restore routing and DNS for the target core. Platform differences mainly concern system takeover and file locations; do not add platform-specific guesses to the server outbound.

Build a fixed troubleshooting checklist

Recording every failure in these four layers prevents repeated work. When the logs show rejected, determine whether the rejection occurred at the local entry, in routing, or remotely. For timeout, identify the timeout stage. For identity or handshake errors, return to the corresponding outbound parameters. If the cause is still unclear, visit Troubleshooting and continue by category: fundamentals, installation and configuration, Advanced, and Troubleshooting.

The goal of configuration maintenance is not to fill every optional field, but to give each section a clear purpose and prove its result through logs. Keep a simple, reproducible baseline first, then add routing, DNS, TUN, and policy. When something breaks, restoring each layer from the baseline is more reliable than randomly deleting fields from a complex configuration.