Configuration Reference · Core & Client
V2Ray Configuration Reference
Follow a connection from the local inbound to outbound selection, with parameter guidance and troubleshooting clues at each step.
For a first install, subscription import, or connection check, start with Getting started with v2rayN. This reference is for looking up specific fields: the first six chapters cover JSON read by the core, while the final two explain how the desktop client selects a core, manages subscriptions, and handles traffic. Examples focus on fields commonly shared by V2Fly and Xray. Whether a feature works depends on the core currently in use.
JSON Structure and Connection Processing Order
First, confirm which file the core reads
In v2rayN, server entries, subscription data, and interface preferences are managed by the client; the core reads the configuration passed to it when it starts. If an entry can be saved in the interface, that only means the client accepted the input—not that the core accepted the generated result. When troubleshooting, first check the selected entry, the running core, and the startup time shown in the relevant logs. If you edit a temporary generated file, selecting another entry or restarting may regenerate it. To keep changes, put them in a setting location supported by the client or save them in a configuration copy you maintain yourself.
Minimal configuration: local access, direct outbound
{
"log": { "loglevel": "warning" },
"inbounds": [
{
"tag": "local-socks",
"listen": "127.0.0.1",
"port": 10808,
"protocol": "socks",
"settings": { "auth": "noauth", "udp": false }
}
],
"outbounds": [
{ "tag": "direct", "protocol": "freedom", "settings": {} }
]
}
This standalone example provides a baseline for comparison. An application sends connections to the local SOCKS listener, and the core uses the freedom outbound to connect directly to the destination without a remote server. Before testing, make sure the example port is free; if a running v2rayN instance already uses it, starting another process will cause a conflict. Also verify that the test application is actually using this SOCKS endpoint. A webpage loading does not by itself prove the configuration works, since the application may not be using a proxy at all. Conversely, if an existing process owns the listening port, a successful connection does not mean it reached the process you just started.
Distinguish field levels and value types
The top level is an object. inbounds and outbounds are arrays, with each item describing an inbound or outbound. routing, dns, and policy are objects that may contain arrays or named child objects. The meaning of settings depends on the protocol of the item it belongs to: even though the field has the same name, the authentication structure for a SOCKS inbound cannot be copied unchanged to another protocol. Write ports as numbers, switches as unquoted Boolean values, and tags as strings. When merging by hand, add items to an existing array instead of writing another array with the same name at the top level. A duplicate key may be overwritten by a later value, making an earlier part of the configuration appear present but ineffective.
Use standard JSON when saving a configuration: enclose keys and strings in double quotes, omit the trailing comma after the last item in an array or object, and do not add comments. An editor with strict validation can catch these issues early, but valid syntax only means the text can be parsed. Protocol support, tag resolution, and port binding still depend on core loading and the actual connection result. When several errors appear, start with the first error from the initial startup failure; later connection failures, retries, and shutdown messages are often consequences.
Record each change as an experiment you can review: note the inbound port, test application, destination domain, expected outbound, and observed result. If it fails, revert that single change and retry with the same destination. This helps avoid mistaking an intermittent destination service issue for a configuration regression. Do not treat a “running” icon as proof that the entire path works: it usually cannot tell you whether a request reached the core or whether it took the expected route.
inbounds: Listening and Application Access
The listen address determines who can connect
listen determines the local address where the core accepts connections. If only local applications need access, explicitly bind to 127.0.0.1. This is not the same as binding to all IPv4 interfaces, nor is it the same as binding to the IPv6 loopback address. If an application resolves localhost to IPv6 while the core listens only on IPv4, the application may report that the connection was refused. For comparison, set the application to the same loopback address as the listener. Do not widen the listening scope just to make a local test work. If controlled LAN access is genuinely needed, consider interface scope, access restrictions, and authentication separately; do not copy the local-only example below as-is.
"inbounds": [
{
"tag": "local-socks",
"listen": "127.0.0.1",
"port": 10808,
"protocol": "socks",
"settings": { "auth": "noauth", "udp": false }
},
{
"tag": "local-http",
"listen": "127.0.0.1",
"port": 10809,
"protocol": "http",
"settings": {}
}
]
Use this to replace the inbounds field in the overview example. The two port numbers are illustrative and do not necessarily match the current client settings. Use the settings and startup logs to confirm the actual ports. To provide both listeners on the same address, assign separate ports and different tag values. An application cannot identify the proxy protocol from the port number alone: pointing an HTTP proxy at a SOCKS port may establish a connection, but the subsequent handshake will fail.
| Field | Example | What to check |
|---|---|---|
| listen | 127.0.0.1 | The address matches the proxy destination set in the test application. |
| port | 10808 | No other instance is using the port. |
| protocol | socks | The protocol matches the type selected in the application. |
| tag | local-socks | Used to identify logs and reference the inbound in routing rules. |
Why system proxy and UDP need separate checks
The system proxy is a setting that the operating system makes available to applications; it does not mean the OS forcibly routes all traffic through it. After enabling automatic configuration, check that the target application follows the system proxy and is not excluded by the system's exception list. Some tools prefer their own proxy settings or environment variables, while browser extensions or management policies may override the system setting. If one application works and another does not, first verify the listener with an application that lets you specify the proxy type and port manually. Then check the settings the affected application actually received instead of changing the server first.
The SOCKS example above explicitly disables UDP. Even if SOCKS UDP is enabled for a suitable use case, the application must use the corresponding SOCKS association method, and the outbound and rest of the path must support that traffic. A standard HTTP proxy test only shows that the tested HTTP request or TCP tunnel works; it cannot prove that real-time calls or other connectionless traffic also works. Record tests by application, protocol, and inbound to avoid using one successful result to explain every symptom.
Before exiting, check that any system proxy settings you changed manually have been restored as expected. A leftover loopback address may look like a valid proxy, but no process is listening for connections. If the browser cannot connect after closing the client, check the system proxy and local listener clues in the troubleshooting FAQ to determine whether the application failed to reach the inbound or whether the problem occurred farther along the path.
outbounds: Protocols, Tags, and Transport
Establish a baseline with verifiable outbounds
"outbounds": [
{ "tag": "direct", "protocol": "freedom", "settings": {} },
{ "tag": "block", "protocol": "blackhole", "settings": {} }
]
freedom establishes a direct external connection, while blackhole can terminate requests that match a specified rule. These are protocol values; direct and block are custom tags referenced by rules, not semantic switches built into the client. Adding block to the outbound array alone does not block all requests; you also need a matching routing rule to send specific traffic to it. If no rule matches, a typical configuration uses the first outbound. Changing the list order may therefore change the default behavior, so put the default outbound somewhere easy to identify at a glance.
Check remote outbound parameters in three layers
After importing connection details you are authorized to use, read the generated result in three layers. The first is the application protocol, including the remote address, port, and required identity information. The second is the transport that carries the protocol data. The third is the security configuration for the selected transport. The remote address tells you where the connection goes; the server name used in the security handshake satisfies the peer's naming requirement. They may be the same or different. A name in a subscription may only be a convenient label, so do not copy it as the server address or handshake name without checking.
protocol and settings describe the outbound protocol itself; applicable transport and security parameters are usually placed in streamSettings. For example, seeing a transport method for a connection in the interface does not mean you can copy the path from another connection. The actual service determines its requirements for paths, names, or handshakes. Do not turn off verification to get around a certificate error: check the system time, peer name, and certificate chain, then confirm that the client is using the correct transport. Similar protocol fields or transport types in two cores do not mean every combination is interchangeable.
Read logs and test results by failure stage
If the local inbound has received a request but the log says no outbound was found, check the tags used in routing, especially capitalization, leading or trailing spaces, duplicate names, and stale references after updates. If the log shows an attempt to connect to a remote address, distinguish a DNS resolution failure from a connection timeout or handshake failure. Resolution fails before a usable address is obtained; a timeout may involve the route, network conditions, or the remote listener; a handshake failure is a reason to check whether the protocol parameters match the service. A generic “connection failed” message alone cannot identify the stage that failed.
When testing a remote outbound, use the same request to verify the inbound first, then compare it with a full connection test. A reachable port only shows that the corresponding connection was established at the time of the probe; it does not guarantee the protocol handshake will succeed or indicate download speed. How Tcping, real connection latency, and speed tests differ explains what each test covers. If the test destination is unstable, add a comparable destination as a control, but do not change the outbound parameters at the same time or it will be hard to attribute the result.
When using multiple outbounds, give each one a stable, unique tag that describes its purpose rather than recording a one-time speed test result. After updating outbound details, check all references, especially manually written routing rules. Before sharing logs with a colleague, remove remote identity details, subscription addresses, and request details. The error category, inbound tag, and outbound tag are usually enough to indicate which layer to investigate next.
routing: Match Order and Target Types
Read from top to bottom; stop at the first match
"routing": {
"domainStrategy": "AsIs",
"rules": [
{
"type": "field",
"inboundTag": ["local-http"],
"domain": ["full:example.org"],
"outboundTag": "block"
},
{
"type": "field",
"domain": ["domain:example.org"],
"outboundTag": "direct"
}
]
}
Use this with the inbound and outbound examples in the previous chapters; the example domain illustrates rule order. The first rule requires the request to come from local-http and its routing target name to be exactly example.org. Both conditions must match for it to use block. If the same domain comes from local-socks, the first rule will not match, but the second may. The second rule also matches subdomains. If you swap the rules, the broader domain rule will take precedence over the exact match, changing the result.
Distinguish exact domains, suffixes, and address ranges
full: matches an exact domain. domain: matches the specified domain and its subdomains; it does not mean an arbitrary substring match. Use regexp: when you need a regular expression, but first list examples that should and should not match. Some backslashes also need escaping in JSON strings. geosite: references a domain data set, while geoip: references an IP data set. Whether either is available depends on the data and corresponding tags provided by the runtime. Check the data source before copying rules so that a loading failure is not mistaken for a rule-order problem.
ip can match a literal destination IP or a CIDR range. Before writing address rules, find out whether the application passes a domain name or an already-resolved address to the inbound. If the application has already resolved it, routing may no longer see the original domain. The same address may also be shared by multiple names, so it cannot reliably identify which site was requested. Conversely, when the inbound receives a domain, whether its resolved address can be used to match an IP rule also depends on domainStrategy and whether core DNS works.
How domainStrategy affects when resolution is attempted
AsIs does not resolve the target domain for routing matches. IPIfNonMatch can resolve the domain and try matching again if the current target does not match. As a result, an earlier rule that matches or a catch-all rule that captures all traffic on the first pass may prevent the expected address match from being reached. IPOnDemand triggers resolution when a rule needs address information. Before choosing a strategy, decide whether you really need to make decisions based on resolved addresses. Extra resolution adds another step that can time out, and may not explain why an existing domain rule failed to match.
For a combined rule, multiple candidates within the same field are generally alternatives, while different conditions in one rule must all be satisfied. If you want one outbound to handle both certain domains and an IP range, it is usually clearer to write two separate rules that reference the same outbound. Do not assume domain and address conditions in one rule mean “or.” Reload and verify the actual outbound after making changes. For more syntax examples, see Matching syntax and priority for custom routing rules.
dns Configuration: Query Sources, Static Mappings, and Fallbacks
Browser, core, and system resolution are different
System resolution typically provides results to programs that use the system resolver interface. Browsers and other applications may keep their own caches or use a separate resolver. The core's dns configuration is used when the core itself needs to resolve a name, for example when a routing strategy needs a resolved address to evaluate an IP rule. Its presence in the configuration does not make it take over queries for the whole machine. If the test application passes only an IP to the inbound, the earlier resolution may already have happened in the application or system; changing core DNS will not make that request a domain target again.
"dns": {
"hosts": {
"example.org": "192.0.2.10"
},
"servers": ["localhost"],
"queryStrategy": "UseIP"
}
This is a standalone example of the top-level dns field. hosts demonstrates a static mapping used by the core itself. The example address is reserved for documentation and is not for connectivity tests. While this mapping remains, do not expect core queries for that name to return a real service address. Remove it for ordinary testing. Here, localhost is a special value that uses local resolution; it is not shorthand for sending DNS packets to the loopback address. UseIP does not restrict queries to one address family or guarantee that both types of address will be returned. The result depends on the upstream response and the destination's records.
Confirm the query path for each scenario
The address obtained for a routing decision is not necessarily the address used by the final outbound connection. The former may be used only to evaluate an IP rule, while the outbound may still resolve the original domain itself or pass it to another endpoint. For example, a freedom outbound's own domain handling options and routing.domainStrategy belong to two different stages; do not treat them as one global switch. To determine which layer resolved a name, isolate other test traffic and compare the target received by the inbound, the matched rule, and the outbound logs.
When using multiple resolution sources, do not assume they are simply a list tried in array order. Some configurations let you restrict which domains a DNS server applies to or whether it can be used as a fallback. A domain failing to match the expected DNS server, that server timing out, and an empty response are different cases. For advanced options, verify behavior against fields recognized by the current core rather than copying settings from another core. Start with one known-good source and verify basic queries before adding domain conditions and comparing matching and non-matching results.
Check caches, address families, and startup dependencies
If a configuration change appears to have no effect, check whether the test application or core still has an old cache or is reusing an established connection. When testing the same name, establish a new application connection and record when the query and connection occur. If an IPv6 address is returned but cannot be reached, DNS may be correct; the outbound may lack IPv6 connectivity. Verify separately that the address resolves, routing selects the expected path, and the address is reachable before deciding whether to restrict the query's address family.
Another common issue occurs during startup: an upstream or remote endpoint is specified by domain, but resolving it depends on a connection that has not been established yet. Adding more DNS addresses will not necessarily solve this. Map the dependencies to identify which query must complete before the connection is established and whether it has an independent usable path. Recheck this when enabling Tun mode, since it may change which interface the query actually uses. The resolver address shown in system settings alone is not enough to determine the path.
policy: Timeouts, User Levels, and Statistics
Set connection lifetimes by level
"policy": {
"levels": {
"0": {
"handshake": 4,
"connIdle": 300,
"uplinkOnly": 2,
"downlinkOnly": 5
}
}
}
This is an example of the top-level policy, not an outbound's settings. levels uses string keys for levels; this example shows level zero, with values in seconds, to explain the fields—not to recommend universal tuning values. Different protocols may specify the user's level in different places. If changing a level appears to have no effect, first confirm that the connection being tested uses that level and that the running core applies the policy to the relevant stage. Policy mainly constrains connection lifetimes and statistics; it does not select an outbound or grant users access.
| Field | Applies to | Common misreading |
|---|---|---|
handshake | The handshake stage for the relevant protocol. | Not a total timeout covering resolution, dialing, and page loading. |
connIdle | A period when the connection has no data activity. | Not the total duration a connection can remain open. |
uplinkOnly | Downlink has ended; only uplink remains. | Not an uplink rate limit. |
downlinkOnly | Uplink has ended; only downlink remains. | Not the size of the downlink buffer. |
Distinguish handshake failure, idle timeout, and one-way traffic
An occasional failure on the first connection is not necessarily the same issue as a connection that drops after working for a while. Record when data activity stops, whether uplink or downlink continues, and whether reconnecting restores service immediately. If the issue occurs after a nearly fixed idle period, it may involve the core's idle policy, or the application, remote service, or an intermediary may be closing the connection. Extending a local policy changes only the local layer; it cannot change timeout behavior on the peer or network equipment. Conversely, an earlier disconnect after shortening the timeout can support a diagnosis, but first confirm that the network did not change and the configuration was not updated during the test.
For applications that remain idle for a long time, first check whether they are supposed to have a keepalive mechanism before changing the policy. Keeping idle connections open consumes resources; increasing every timeout can also delay detection of a failed connection. Rather than copying someone else's values, run a controlled comparison: use the same application on the same network to establish a new connection, record a baseline, then change only the field related to the symptom. Existing connections may retain their earlier state, so reload and establish a new session before comparing.
Configure statistics collection separately from reading statistics
To diagnose traffic direction, distinguish the per-user-level statistics options in policy.levels from the system options in policy.system that control inbound or outbound statistics. Enabling statistics does not guarantee that the graphical interface will show numbers: the core must enable the relevant mechanism, and the client must read it in a compatible way. Empty tags, observing the wrong target, or counters resetting after a restart can all produce unexpected readings. Some interfaces aggregate multiple connections, so an increasing number alone does not prove which application request used which outbound.
Keep the scope of local diagnostics limited to what is needed. Retaining detailed access logs for a long time just to inspect one connection can accumulate unnecessary destination and timing information. If you use a management interface to read statistics, do not expose an inadequately isolated management endpoint to external networks. After troubleshooting, restore the usual log level, remove temporary statistics settings, and keep a brief record of the symptoms, changes, and conclusions for easier reference next time.
Core Selection and Subscription Boundaries
Check the core actually running, not just the client name
For desktop use, start with the v2rayN installer and choose the option that matches your operating system and processor architecture. The client provides the interface, subscription management, and saved settings; the core handles protocol configuration and connections after loading. On Android, v2rayNG uses the Xray core, while v2flyNG is an alternative client that uses the V2Fly core. Project V is a starting point for understanding this ecosystem. V2Fly continues the V2Ray community maintenance path, while Xray developed from related code into its own project. Field names may be the same, but supported protocol combinations, transports, and additional options are not always synchronized across cores.
The most useful evidence for distinguishing an interface selection issue from a core loading issue is the startup record for the current run. First confirm the log corresponds to the selected configuration, then verify that the expected core is running. If switching cores produces an unknown protocol, unknown transport, or field type error, do not immediately delete the field and try again. Some fields are necessary to connect to the remote service; removing them may turn a startup failure into a later handshake failure. A safer approach is to restore a known-working core and entry first, then check compatibility one item at a time.
Use shared fields for a local comparison
"log": { "loglevel": "warning" },
"outbounds": [
{ "tag": "direct", "protocol": "freedom", "settings": {} }
]
This core-level snippet describes only logging and a direct outbound; a complete test also needs the local inbound from the overview. Use it in a separate test configuration to verify common fields and local listening first, then return to the actual entry to investigate differences. Do not append the example to an existing configuration and create duplicate fields, or use it to overwrite the actual outbound list generated by the graphical client. For desktop interface choices, see Choosing between the v2rayN desktop and WPF editions. The interface framework and core protocol capabilities are separate choices.
Subscription groups, refreshes, and local changes
Subscription groups organize sources and entries in the client; they are not top-level core configuration fields. Refreshing a subscription means the client retrieves content from a source you are authorized to use and attempts to import it. A refresh has several stages: retrieving content, parsing entries, and updating the list in the interface. A failure at any stage may make the list appear unchanged. A successful refresh only means this retrieval and import path works; it does not mean every entry can connect. Likewise, an imported entry that connects for now does not prove the subscription address can still be refreshed.
After manually changing a subscription entry, the next refresh may overwrite the local changes with source data, depending on how the client merges updates. For comparison, keep entries you are authorized to use in a clearly separated local test copy and record your changes. If an update connects to the wrong entry, first check the group, selected state, and actual startup record. Do not rely on the display name alone, since different sources may use the same name. Before sharing a screenshot for troubleshooting, hide the full subscription address, identity parameters, and remote details for each entry.
For the first import, follow the import steps in Getting started; there is no need to write protocol fields by hand first. If the problem is with a new subscription while an older one works, verify source availability and whether the client recognizes its content separately. Do not change routing and the core at the same time. Once you know whether the issue is in retrieving data, parsing and importing it, generating the configuration, or establishing the connection, consult the relevant chapter of this reference.
Tun Mode: Virtual Interfaces, System Routes, and Verification
Distinguish interface capture from core routing
The system proxy depends on applications using the proxy settings provided by the OS. Tun mode uses a virtual network interface and system routes to send selected traffic into the processing path. The system first decides which interface receives a packet; only after traffic enters the relevant component can the core select an outbound using its rules. These two decisions are not interchangeable: changing a core rule to direct does not prevent a packet from passing through a virtual interface first. If the system does not send traffic to the virtual interface, changing core rules may not affect it either.
Isolate capture issues with a known inbound
"routing": {
"rules": [
{
"type": "field",
"inboundTag": ["local-socks"],
"outboundTag": "direct"
}
]
}
This is a core routing example that references the local-socks and direct tags defined earlier; it is not Tun configuration. Put it in a separate configuration to verify routing through a controlled local inbound, then compare the result with traffic entering through the virtual interface. If both access methods use the same default outbound, destination reachability alone cannot prove this rule matched; check the inbound and outbound in the logs. Do not assume traffic captured by a virtual interface is also named local-socks. Use the client-generated configuration and records to confirm the actual processing path.
Observe before, during, and after enabling
Before enabling, make sure no other traffic-capture tool is active that could affect the same test. Record the normal connection behavior and confirm you can turn the new mode off. If authorization fails or the virtual interface cannot be created, check the current user's permissions, system restrictions, and client startup records. A switch shown as enabled only reflects the interface state; also confirm that the virtual interface appears and the required routes are established. If the system proxy is still enabled, the test application may connect to a loopback proxy instead of going directly through system routing. A successful test in that case does not independently prove the Tun path is active.
After enabling, split tests into two groups: requests that should be handled by the new interface, and LAN or work network resources that should remain reachable. If the first group fails, check whether the client outbound can connect over the physical network and whether its traffic is being recaptured by the Tun path. If the second group fails, check interface priority, overlapping subnets, and existing network policies. If access by name fails but access by address works, return to the DNS chapter and find out who initiates the query, whether it is also captured, and whether it depends on a connection that has not yet been established.
After turning it off, confirm that virtual-interface routes and proxy settings have returned to the expected state. If issues appear after switching networks, waking from sleep, or updating the client, check the actual interfaces and routes again rather than assuming the previous result still applies. On a managed work device, do not use elevated privileges or system route changes to bypass restrictions. You can first test with an approved application proxy and, if needed, ask the administrator to check the policy.
Traffic capture on Android clients is managed through the system VPN authorization mechanism; do not map its per-app selection directly to desktop settings. To check authorization, background restrictions, or per-app scope, start with the Android getting started guide, then see v2rayNG VPN permissions, battery optimization, and per-app settings. On any platform, troubleshooting starts with two questions: did the request enter the expected interface, and which outbound did the core select afterward?