V2Ray Configuration Reference

The main V2Ray and Xray configuration can be viewed as a JSON object describing a traffic-processing pipeline: inbounds accept connections, routing determines where they go, outbounds establish connections, and DNS and policy objects add name resolution and resource controls.

The top-level object is not a list of execution steps

The outermost configuration is a single JSON object. Common keys include log, dns, inbounds, outbounds, routing, policy and stats. Their order in the file usually does not determine execution order: JSON objects describe structure by key names, not workflow by writing position. Order matters mainly inside arrays. For example, routing.rules is checked from top to bottom, and the first matching rule selects the outbound. Multiple inbounds and outbounds are referenced by their respective tag values.

When reading a configuration, a reliable approach is to list every tag first, then follow the references between them. An inbound tag may be used by a routing rule's inboundTag; an outbound tag may be selected through outboundTag; and a DNS server may connect to routing rules through its tag. A tag is only an internal configuration identifier and does not create routing behavior by itself. If a rule names a tag that does not exist, startup may fail, or traffic may have nowhere to go when that path is reached. The exact behavior depends on the core and the field involved.

{
  "log": {
    "loglevel": "warning"
  },
  "dns": {
    "servers": ["1.1.1.1", "localhost"]
  },
  "inbounds": [
    {
      "tag": "socks-in",
      "listen": "127.0.0.1",
      "port": 10808,
      "protocol": "socks",
      "settings": {
        "udp": true
      }
    }
  ],
  "outbounds": [
    {
      "tag": "direct",
      "protocol": "freedom"
    },
    {
      "tag": "blocked",
      "protocol": "blackhole"
    }
  ],
  "routing": {
    "domainStrategy": "AsIs",
    "rules": [
      {
        "type": "field",
        "ip": ["geoip:private"],
        "outboundTag": "direct"
      }
    ]
  }
}

Arrays, objects and value types

inbounds, outbounds and routing.rules are arrays, so they use square brackets. A single inbound, outbound or rule is an object and uses curly braces. Ports are numbers, not strings with units. Boolean values must be true or false. An omitted field is not equivalent to a field set to null: omission lets the core apply its default behavior, while an explicit null value matters only where the field definition allows it. Many startup failures are caused not by protocol problems but by mismatched brackets, missing commas between objects, Chinese quotation marks around strings, or an array field written as a single string.

Standard JSON does not allow comments or a trailing comma after the last member. Online examples often use // comments for explanation, but remove them before copying a core configuration. v2rayN, v2rayNG and v2flyNG may maintain their own configuration layer outside the graphical interface; nodes, subscriptions and routing settings are converted before being passed to the core. Before editing by hand, confirm whether you are changing a client-managed file, a generated runtime configuration or a configuration read directly by a standalone core. Similar filenames do not make these the same object.

Increase complexity gradually from a minimal configuration

When troubleshooting, keep one local inbound, one clearly working outbound and the smallest possible routing set, then add DNS, sniffing, multiple transports and statistics policies step by step. Adding several modules at once can hide the source of an error. A failed connection might be caused by remote parameters, a domain resolved through the wrong DNS path, or an earlier rule sending traffic to blocked. Minimizing the configuration does not mean deleting required security fields; it means shortening the chain of variables. Keep the server-required address, port, user ID, transport and security parameters unchanged, and temporarily remove only optional rules that do not affect connectivity.

Before saving, confirm that the text is UTF-8 encoded, the file contains one root object, and key casing matches the field definitions. outboundTag and outboundtag are different names, and protocol names should not be inferred from translated interface labels. After checking the structure, validate the inbound, outbound and routing sections one at a time. This is easier to interpret than repeatedly changing ports inside a large configuration.

An outbound sends a connection selected by routing to its destination. It may connect to a remote protocol server, access the destination directly, reject the connection, or hand the traffic to another outbound for further processing.

Check the protocol fields as one complete set

A remote outbound is usually defined jointly by protocol, settings and streamSettings. For VLESS, for example, the server address and port are under vnext, while the user ID is under users. The transport, security layer, server name and related parameters are in streamSettings. Matching only the address, port and user ID does not prove that the configuration is consistent. The client and server must also agree on transport, TLS-related security settings, path, hostname and applicable extensions.

Configuration interfaces often spread these fields across pages such as “Address,” “User,” “Transport” and “Security,” while JSON places them in neighboring objects. When subscription import behaves unexpectedly, inspect each field on the client's details page instead of relying on the displayed node name. A node name is usually a local note and is not part of the protocol handshake; structured fields determine the connection. When migrating parameters manually, do not treat URI-encoded text as its raw JSON value, and do not turn an empty interface value meaning “default” into the string "default".

{
  "outbounds": [
    {
      "tag": "remote-vless",
      "protocol": "vless",
      "settings": {
        "vnext": [
          {
            "address": "server.example.com",
            "port": 443,
            "users": [
              {
                "id": "11111111-1111-4111-8111-111111111111",
                "encryption": "none"
              }
            ]
          }
        ]
      },
      "streamSettings": {
        "network": "ws",
        "security": "tls",
        "tlsSettings": {
          "serverName": "server.example.com"
        },
        "wsSettings": {
          "path": "/example-path",
          "headers": {
            "Host": "server.example.com"
          }
        }
      }
    },
    {
      "tag": "direct",
      "protocol": "freedom"
    },
    {
      "tag": "blocked",
      "protocol": "blackhole"
    }
  ]
}

direct and blocked are explicit handling paths

A freedom outbound is normally used to connect directly to the destination and is often tagged direct. A blackhole outbound terminates connections selected by a rule and is often tagged blocked. These tags are conventional names and can be changed, but every routing reference must be updated. Adding freedom to the outbound array does not automatically make local addresses direct; a routing rule must send the relevant traffic to it. Likewise, defining blackhole does not block any domain until a matching rule references it.

When no rule matches, the core usually selects the default outbound, although the exact behavior depends on the configuration and core implementation. To keep large configurations understandable, write explicit rules for important traffic and use readable outbound tags. Names for remote, direct and blocked outbounds should describe their purpose instead of using confusing consecutive numbers. Clear names also make outbound identifiers easier to match in logs.

Outbound chains, proxy settings and loops

Some cores allow an outbound to establish its connection through another outbound using proxySettings or a similar mechanism. This is useful for deliberately designed chained exits, but it adds layers to DNS, handshakes and fault diagnosis. Every segment needs a unique tag, and the chain must not form a loop such as A pointing to B while B points back to A. Consider how the remote server's domain is resolved as well: if the DNS lookup needed for the first connection depends on an outbound that has not yet been established, the configuration can enter a persistent timeout loop.

When troubleshooting a chained configuration, first make the single outbound responsible for the final physical connection work independently, then add earlier segments one at a time. If the log only says “connection closed,” use the outbound tag to identify the failing layer. Remote rejection, DNS failure, a mismatched TLS server name and a local route selecting the wrong outbound can all appear as an application unable to open a page. Layer-by-layer testing preserves more evidence than replacing every protocol parameter at once.

On desktop, use v2rayN to manage nodes and core configuration. On Android, choose v2rayNG or v2flyNG according to the core you need. To compare the roles of Xray and V2Fly, read Xray and V2Fly Core Differences. Supported fields may vary between core branches, so confirm which core the target client actually uses before migrating a complex configuration.

DNS configuration determines which servers the core queries when it needs to resolve a domain and which resolution path should take priority for specific domains. It is separate from OS DNS, application-level resolution and resolution performed during routing.

First identify who initiates the query

An application may resolve a name through the operating system and pass only the destination IP to the proxy. It may instead pass the original domain to a SOCKS or HTTP inbound, or use its own encrypted DNS mechanism. Only queries that enter and are resolved by the core are directly controlled by the top-level dns object. If a configuration change has no visible effect, first confirm whether the inbound receives a domain or an IP, and whether sniffing recovered the domain. Changing dns.servers cannot force every system program to abandon its own resolution path.

servers may contain simple addresses or objects with properties such as address, domains, expectIPs and skipFallback. A simple array suits one path; object form suits server selection by domain. A server list does not always behave like the traditional fallback model where the second server is used only after the first fails. Domain filters, fallback settings and the core implementation jointly determine which server is queried. Before designing complex DNS, validate two clearly assigned servers first, then add domain scopes and fallback restrictions.

{
  "dns": {
    "hosts": {
      "router.example": "192.168.1.1"
    },
    "servers": [
      {
        "address": "localhost",
        "domains": [
          "full:router.example",
          "domain:internal.example"
        ],
        "skipFallback": true
      },
      {
        "address": "1.1.1.1",
        "domains": [
          "domain:public.example"
        ]
      },
      "8.8.8.8"
    ],
    "queryStrategy": "UseIP"
  }
}

hosts, domains and expected results

hosts provides static mappings for explicit names and is suitable for a small number of stable local services, not a large dynamic domain table. Static mappings usually have high priority; if an address changes and the mapping is not updated, one name may continue pointing to the old address. Check the operating system hosts file, host overrides in the client interface and dns.hosts in the core configuration together to avoid conflicts between layers.

domains in a server object filters the domains sent to that server. Its syntax resembles routing domain conditions, but the purpose differs: the former selects a resolver, while the latter selects a connection outbound. expectIPs can constrain the range of expected returned addresses to test whether a result matches expectations; it does not rewrite arbitrary responses into that range. A constraint that is too narrow may exclude valid responses and trigger fallback. skipFallback affects how the server participates in fallback. Before combining these options, map the four steps: domain selection, server query, result check and connection routing.

How DNS queries select an outbound

The DNS server address itself also requires a connection. If it is a domain, that domain must first be resolved; if it is an IP, that layer is skipped, but routing still selects the network outbound. More complex configurations assign a tag to DNS traffic, then use routing to send it to a specific outbound by tag or protocol. Avoid loops: a remote outbound may depend on domain resolution while that resolution is required to use the remote outbound that has not yet been established.

To build an understandable path, first give the remote server address a stable base resolution path, then decide how ordinary destination domains should be routed. If domainStrategy and DNS rules are used together, routing may trigger DNS resolution while evaluating IP conditions. A problem that looks like routing may actually come from DNS server selection or fallback results. In logs, follow the sequence of query, returned address, outbound selection and connection target rather than looking only at the final timeout.

Caching and IPv4/IPv6 selection

queryStrategy limits or favors returned address families, with supported values varying by core. Forcing one address family may work around incomplete local connectivity, but it may also exclude a reachable destination. Check whether the operating system has connectivity for the family before restricting queries. The client, core and system resolver may all cache results, so retrying immediately after a DNS change may not issue a new query. You can restart the relevant client process and establish a new connection, but clearing caches should not be treated as a long-term configuration strategy.

For “the domain is unreachable but its IP works,” first verify that the query returns an address, then check whether the returned address is sent to the intended outbound by routing. For intermittent failures affecting some domains, compare the DNS server, address family and outbound tag selected during successful and failed attempts. Changing servers tests the resolver path but does not replace checking rule conditions. For the main client connection workflow and verification steps, return to Getting Started.

The remote protocol defines identity and request format, while streamSettings defines how that data is carried over the network connection. Even with matching protocol parameters, the connection cannot complete if the transport layer differs.

network determines the settings object that follows

streamSettings.network specifies the transport type. Common configurations may use TCP, WebSocket, gRPC or mKCP. After choosing a network, use its corresponding settings object, such as wsSettings for WebSocket or the service-name settings for gRPC. Keeping fields from another transport does not combine the two automatically and can make the configuration misleading. When migrating a node, confirm the transport type shown by the client, then check its dedicated fields one by one.

The transport type is not an option the client can optimize independently. The client must connect using the same transport, path or service name that the server is listening for. Repeatedly switching among TCP, WebSocket and gRPC usually only adds variables. A safer approach is to fix the transport from the source configuration, verify that the address resolves and the port is reachable, then check the path, host fields and security layer.

{
  "streamSettings": {
    "network": "grpc",
    "security": "tls",
    "tlsSettings": {
      "serverName": "edge.example.com",
      "allowInsecure": false,
      "alpn": ["h2"]
    },
    "grpcSettings": {
      "serviceName": "example-service",
      "multiMode": false
    },
    "sockopt": {
      "tcpKeepAliveIdle": 100
    }
  }
}

WebSocket path, Host and TLS name

In a WebSocket configuration, path is the HTTP handshake path. Whether it begins with a slash or includes a query string must match the server entry point. headers.Host is a WebSocket handshake header, while tlsSettings.serverName is used for TLS server-name verification. They may be the same or may differ because of the deployment design. Treating them as one field and replacing them together can make one layer pass while the other fails.

The server address determines the first host contacted, the TLS name determines the name used for certificate and handshake verification, and the WebSocket Host is handled at the HTTP layer. Troubleshoot them in connection order. If the address accepts a TCP connection but TLS fails, check the system clock, server name and security parameters. If TLS succeeds but WebSocket is rejected, check the path and Host. Loosening certificate verification merely reduces error visibility and should not be a routine fix.

gRPC, mKCP and transport-specific fields

A gRPC configuration usually requires an exact serviceName and depends on HTTP/2 negotiation. The service name is a configuration value, not a node note, and should not be turned into a URL-style path by adding slashes. If an intermediary does not support the required connection method, it may close the connection immediately after the handshake. mKCP is a UDP-based transport and depends on whether the current network can carry UDP reliably; TCP reachability does not prove that the UDP path works.

When there are many transport-specific parameters, start with the structure generated by the client from the node information, then modify only fields tied to a clear requirement. Internet examples may span different cores and releases and include renamed fields. v2rayN generally manages a desktop core, v2rayNG follows an Xray core path, and v2flyNG targets the V2Fly core. The basic concepts of a transport may be similar, but extension fields are not necessarily identical. If support is uncertain, remove nonessential extensions first and retain the core fields required by the server.

security, TLS and Reality layers

security selects the security layer, and its settings object must match that choice. TLS parameters belong in tlsSettings, while Reality uses the separate settings object defined by the core. You cannot switch only the security string and keep every old field. The server name, public-key parameters, short ID and fingerprint selection are handshake requirements for a specific security method and must come from the same valid configuration.

Security-layer errors and user-identity errors can both appear as a failed connection test in the interface, so logs must identify whether the failure occurred during DNS, TCP, TLS or protocol authentication. If the server port cannot be reached, changing the server name is pointless. If TCP is established but the security handshake fails, do not start by changing routing rules. Identify the failing layer before changing parameters to avoid altering the error message without fixing the cause.