V2Ray Configuration File Explained: inbounds, outbounds, and routing

Follow the data flow: how the configuration works together

A V2Ray configuration is not a collection of independent switches. An application first hands a request to an inbound. The routing module reads the destination domain, IP, port, and inbound tag, then sends the request to the selected outbound. If no routing rule matches, V2Ray normally uses the first item in the outbounds array, so the order of outbounds matters too.

inbounds answer “where does traffic enter?”, outbounds answer “where does it leave?”, and routing connects the two. A configuration starting successfully only proves that its JSON structure and fields are broadly parseable. To confirm traffic is split as intended, also check tag references, rule order, and DNS results.

Minimal configuration skeleton: start with complete JSON

The example uses a local SOCKS inbound, a VMess proxy outbound, a direct outbound, and a blocked outbound. The server domain, port, user ID, and transport are structural examples only; in real use, each must match the server-side parameters. JSON does not allow comments, so explanatory text must not be placed in a production configuration file.

{
  "log": {
    "loglevel": "warning"
  },
  "dns": {
    "servers": [
      "1.1.1.1",
      "localhost"
    ]
  },
  "inbounds": [
    {
      "tag": "local-socks",
      "listen": "127.0.0.1",
      "port": 10808,
      "protocol": "socks",
      "settings": {
        "auth": "noauth",
        "udp": true
      }
    }
  ],
  "outbounds": [
    {
      "tag": "proxy",
      "protocol": "vmess",
      "settings": {
        "vnext": [
          {
            "address": "server.example.com",
            "port": 443,
            "users": [
              {
                "id": "11111111-2222-3333-4444-555555555555",
                "security": "auto"
              }
            ]
          }
        ]
      },
      "streamSettings": {
        "network": "tcp",
        "security": "none"
      }
    },
    {
      "tag": "direct",
      "protocol": "freedom"
    },
    {
      "tag": "block",
      "protocol": "blackhole"
    }
  ],
  "routing": {
    "domainStrategy": "IPIfNonMatch",
    "rules": [
      {
        "type": "field",
        "protocol": [
          "bittorrent"
        ],
        "outboundTag": "block"
      },
      {
        "type": "field",
        "ip": [
          "geoip:private"
        ],
        "outboundTag": "direct"
      },
      {
        "type": "field",
        "domain": [
          "geosite:cn"
        ],
        "outboundTag": "direct"
      },
      {
        "type": "field",
        "ip": [
          "geoip:cn"
        ],
        "outboundTag": "direct"
      }
    ]
  }
}

This configuration sends requests that match no rule to the first outbound, proxy. Private addresses, domains in mainland China, and IP addresses in mainland China go to direct, while selected protocols go to block. If direct is moved to the first outbound without adding an explicit proxy rule, unmatched traffic will become direct.

• tag is an internal configuration name. It can be customized, but every reference must match exactly, including letter case.
• When listen is 127.0.0.1, the inbound accepts connections only from the local machine, making it suitable for a typical desktop proxy.
• port is a number, not quoted text. No other program may already be using the same port on that address.
• streamSettings must match the server-side transport parameters; the protocol name alone is not enough to determine them.

inbounds: how applications hand traffic to the core

An inbound is the receiving endpoint V2Ray opens locally. The example listens on 127.0.0.1:10808 using SOCKS. Once a browser, download tool, or system proxy points its SOCKS address to this port, requests can enter V2Ray. Starting the core without directing applications to the inbound port will not automatically capture ordinary application traffic.

settings.auth set to noauth means this SOCKS endpoint requires no username or password, so it should remain bound to the local machine. udp: true allows SOCKS UDP requests to enter, but the outbound protocol, server, and network must also support them. Enabling this field alone does not guarantee that all UDP traffic will work.

Multiple inbounds can run at the same time. For example, keep 10808 for SOCKS and add 10809 for HTTP. Give each inbound a distinct tag so routing rules can distinguish their sources with inboundTag. To change v2rayN’s local ports, open “Settings” → “Parameter Settings” and check the SOCKS and HTTP ports; the proxy ports in the application must be updated as well.

outbounds: the roles of proxy, direct, and block

An outbound defines how a request leaves V2Ray. A proxy outbound usually contains the server address, server port, user credentials, and transport settings; a direct outbound uses freedom; and a blocked outbound uses blackhole. The routing module does not establish remote connections itself; it selects an outbound tag according to the rules.

In the VMess example, vnext is a list of servers, and each server can contain a set of users. address and port must match the server’s listening details, while id must be a user identifier accepted by the server. Also verify the transport layer, including TCP, WebSocket, and TLS. A single mismatch between client and server can cause an immediate disconnect after connection or repeated timeouts.

routing: rule order determines the final exit

routing.rules is an array checked from top to bottom. Once a request matches a rule, V2Ray uses that rule’s outboundTag and stops processing later rules for that request. Put narrower, higher-priority rules first and broader rules later.

domainStrategy: IPIfNonMatch first tries domain-based rules. If no domain rule matches, it resolves the IP and continues checking IP rules. This allows geosite:cn and geoip:cn to work together, but it also means DNS results affect IP-rule decisions.

1. Handle protocols or destinations that must be blocked first, so a broad direct rule later cannot take over too early.
2. Next, process geoip:private so local-network and private addresses connect directly.
3. Then match geosite:cn and choose a direct connection for domains in that category.
4. If the domain does not match, use geoip:cn to check the resolved destination IP.
5. Remaining traffic falls through to the first outbound, proxy, when no rule matches.

The outboundTag in a rule is not a protocol name; it is the tag of an outbound object. If the outbound tag is proxy but the rule says Proxy, they are not the same tag. When deleting or renaming an outbound, search the entire file and update every reference.

DNS and logs: why traffic can split incorrectly even when the configuration is valid

DNS does more than translate domains into IP addresses. When domain and IP matching are combined, resolution results participate in routing decisions. The example places 1.1.1.1 and localhost in the server list, allowing either a specified DNS server or the local resolver; on a real network, choose based on reachability, resolution results, and routing goals.

Set loglevel to warning for everyday use to see warnings and errors. Temporarily switch to info when troubleshooting rules for more complete runtime details, then switch back after confirming the issue to prevent rapid log growth. JSON strings must use double quotes, and the final array item or object field must not have a trailing comma.

{
  "log": {
    "access": "access.log",
    "error": "error.log",
    "loglevel": "info"
  },
  "dns": {
    "hosts": {
      "domain:internal.example.com": "192.168.1.20"
    },
    "servers": [
      "1.1.1.1",
      "localhost"
    ]
  }
}

• For messages such as failed to listen, check the listen address and port usage first.
• If an outbound tag cannot be found, compare every outboundTag with the outbound tag.
• When a connection to the remote server times out, check the address, port, transport, and reachability on the current network.
• If direct connections for domains do not behave as expected, check rule order, domainStrategy, and the addresses returned by DNS.

Common editing problems: infer the field from the error

Manual edits usually cause three types of problems: broken JSON syntax, fields placed at the wrong level, and broken tag references. Syntax errors usually prevent the core from starting; misplaced fields may trigger an unknown-field error; tag errors may appear only when a request actually matches the rule. Validate the file first, then check the entry point, and finally trace the request path.

For v2rayNG and v2flyNG, subscriptions or share links likewise generate the configuration required by the client. v2rayNG uses the Xray core, while v2flyNG uses the v2fly core, so field names and supported transports may differ by core. Do not overwrite one core’s environment with a complete configuration exported by another without first checking protocol, transport fields, and routing resources for compatibility.

1. Back up the working config.json and record the local inbound port.
2. Change one section at a time, and run a configuration test after saving.
3. Start the core and confirm that 127.0.0.1:10808 is listening successfully.
4. Test the proxy outbound with a single destination, then test direct and blocked rules.
5. Watch the destination address, match result, and connection errors in the logs before making the next change.