Xray Configuration Best Practice

Background and History

In China, due to Great Firewall, proxy is a required for developers.

Here are some requirements for proxy software:

  1. Flexible. sometimes all netflow need to be proxied, sometimes just need to proxy oversea netflow.
  2. Run everywhere. It needs to run at macOS, Windows, Linux, Android, OpenWRT.
  3. Proxy protocols. It should support encryped proxy protocol, obfuscated, and should support obfuscate as websocket.

Here are some of the agent software in history, ordered by time:

  1. ‮etageerF‬. At the time, I just using Windows, the standalone browser by ‮etageerF‬ is a good fit for me. I was just use it to visit some website.
  2. GoAgent. I was using Firefox, so deploy GoAgent over GAE. But GoAgent is built over web, is not a real proxy, so have to add a fake cert.
  3. shadowsocks(Python version). bought a VPS, deploying a real proxy, which provide proxy over a socks port.
  4. shadowsocks-libev. For use on Android, start using shadowsocks client.
  5. shadowsocks+simple-obfs. Later, found that shadowsocks protocol was too badly banned, so start use shadowsocks/simple-obfs. Of course, during the configuration process, it was also noted that CloudFlare can proxy the websocket protocol, so this CloudFlare was added.
    1. Proxy flow is masqueraded as websocket netflow, which is not easily recognized.
    2. Websocket netflow is also could forward by CloudFlare, for some VPS with bad net route with china, there is a certain improvement for speed and latency.
    3. Also, VPS’s real IP is hidden. So real IP is not banned easily.
  6. clash. shadowsocks has almost no traffic splitting/routing capabilities. Either all traffic goes through the proxy, or the traffic splitting ability is achieved through browser extensions.

Clash is still quite good. It can set forwarding rules according to IP addresses and domain names, and it can run on OpenWRT. There is also a wide range of client support.

However, the routing ability of Clash is not flexible enough. The main problem is that it doesn’t have a relatively clear “routing chain”.

For example, for the traffic from port 27890, all of it should go through the proxy. And for the traffic from port 17890, the overseas traffic should go through the proxy while the domestic traffic should be directly connected. Such a configuration is difficult to achieve through Clash.

Speaking of which, isn’t it somewhat similar to iptables?
Iptables forwards traffic based on the source address, destination address, and kernel markings of IP packets.
What we need is to forward traffic according to IP addresses, ports, and traffic domain names.

  1. V2Ray can meet these requirements very well.
  2. Xray. As I discovered some bugs in V2Ray and noticed that the V2Ray community wasn’t very active, while the Xray community seemed quite vibrant, I decided to switch to Xray.

And there might be some better proxy software, why don’t using xxx software?

Well, what will replace Xray definitely won’t be another Xray. I think the next proxy software has additional capabilty, such as 2x faster, mesh-network.

Xray’s config logic

Here is a brief introduction to the logic of Xray configuration:

  1. Define inbound rules for traffic reception
    • SOCKS traffic inbound: It is most suitable as the proxy for browsers.
    • HTTP traffic inbound: Some tools do not support the SOCKS5 proxy protocol and will use the HTTP proxy protocol instead.
    • Dokodemo-door: It can be used as a transparent proxy. The traffic from the entire LAN exit can be redirected here and then forwarded through the proxy.
  2. Define outbound rules as traffic exits
    • Some outbounds forward traffic directly, some use a secondary proxy, and some simply drop the traffic.
  3. Define routing rules for traffic forwarding
    The logic of this part is as follows:
    • Direct connection for specific domains: Domains that require direct connection, such as mainland Chinese domains and the domains of underlying proxies, are sent directly.
    • Direct connection for specific IPs: IPs that need direct connection, like mainland Chinese IP addresses and internal network domains, follow the “direct” logic.
    • Proxy for remaining traffic: The remaining traffic is sent through the proxy.
  4. Define DNS functions
    • Non-Chinese domains: For non-Chinese domains, queries are made through Google Public DNS via the proxy.
    • Chinese domains and whitelisted domain: For Chinese domains or some whitelisted domain, such as company - internal domains, queries are made directly within the internal network.

Xray config example

Xray-server

Just receive the proxy traffic disguised as the WebSocket protocol and then forward it.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
{
  "log": {
    "dnsLog": true,
    "loglevel": "warning"
  },
  "inbounds": [
    {
      "port": 8000,
      "listen": "0.0.0.0",
      "protocol": "vmess",
      "settings": {
        "clients": [
          {
            "id": "12345678-1234-1234-1234-123456789012"
          }
        ]
      },
      "streamSettings": {
        "network": "ws",
        "wsSettings": {
          "path": "/ws"
        }
      }
    }
  ],
  "dns": {
    "queryStrategy": "UseIP"
  },
  "outbounds": [
    {
      "protocol": "freedom",
      "settings": {
        "domainStrategy": "UseIP"
      }
    }
  ]
}

Nginx config

In order to better obfuscate the traffic, you can choose to set up both a proxy and a website on the same domain name. For proxy traffic, Nginx needs to parse the WSS traffic into WS traffic and forward it to the Xray server.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
location /ws {
    # if it't not websocket traffic, return 404
    if ($http_upgrade = "") {
        return 404;
    }
    proxy_redirect off;
    keepalive_timeout 12000s;
    # pass traffic to Xray-server
    proxy_pass http://127.0.0.1:8000;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Host $host;
    proxy_set_header Connection "upgrade";
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_intercept_errors on;
    # For debug, pass all header to Xray
    proxy_pass_request_headers on;
}

Xray-client config

Xray-client will start http&socks proxy. Browser need to set up proxy, such as set proxy of Chrome as socks5://127.0.0.1:17891.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
{
  "log": {
    "dnsLog": true,
    "loglevel": "debug"
  },
  "inbounds": [
    {
      // http proxy, traffic split
      "tag": "http-inbound",
      "port": 17890,
      "listen": "127.0.0.1",
      "protocol": "http"
    },
    {
      // socks proxy, traffic split
      "tag": "socks-inbound",
      "port": 17891,
      "listen": "127.0.0.1",
      "protocol": "socks",
      "sniffing": {
        "enabled": true,
        "destOverride": [
          "http",
          "tls"
        ]
      },
      "settings": {
        "auth": "noauth",
        "udp": true,
        "ip": "127.0.0.1"
      }
    },
    {
      // http proxy, proxy all traffic
      "tag": "http-inbound-all",
      "port": 27890,
      "listen": "127.0.0.1",
      "protocol": "http"
    },
    {
      // socks proxy, proxy all traffic
      "tag": "socks-inbound-all",
      "port": 27891,
      "listen": "127.0.0.1",
      "protocol": "socks",
      "sniffing": {
        "enabled": true,
        "destOverride": [
          "http",
          "tls"
        ]
      },
      "settings": {
        "auth": "noauth",
        "udp": true,
        "ip": "127.0.0.1"
      }
    }
  ],
  "outbounds": [
    {
      "tag": "proxy",
      "protocol": "vmess",
      "settings": {
        "vnext": [
          {
            "address": "proxy.net",
            "port": 443,
            "users": [
              {
                "id": "12345678-1234-1234-1234-123456789012"
              }
            ]
          }
        ]
      },
      "streamSettings": {
        "network": "ws",
        "security": "tls",
        "wsSettings": {
          "headers": {
            "User-Agent": "some identifiler"
          },
          "path": "/ws"
        },
        "tlsSettings": {
          "allowInsecure": false
        },
        "sockopt": {
          "mark": 255
        }
      }
    },
    {
      "protocol": "freedom",
      "domainStrategy": "UseIP",
      "tag": "direct",
      "streamSettings": {
        "sockopt": {
          "mark": 255
        }
      }
    }
  ],
  "routing": {
    "domainMatcher": "mph",
    "domainStrategy": "IPOnDemand",
    "rules": [
      {
        // if traffic is from all-proxy port, then pass all to proxy
        "type": "field",
        "inboundTag": [
          "http-inbound-all",
          "socks-inbound-all"
        ],
        "outboundTag": "proxy"
      },
      {
        // if it's to private IP, chinese IP, then go to direct
        "type": "field",
        "ip": [
          "geoip:private",
          "geoip:cn"
        ],
        "outboundTag": "direct"
      },
      {
        // if it's under our proxy domain, go direct.
        // those traffic is proxied, it's no need to proxy again.
        "type": "field",
        "domains": [
          "domain:proxy.net"
        ],
        "outboundTag": "direct"
      },
      {
        // remaining traffic, go through proxy
        "type": "field",
        "outboundTag": "proxy",
        "network": "tcp,udp"
      }
    ]
  },
  "dns": {
    "servers": [
      {
        // for non-chinese domain, or blacklisted domain, reslove via proxy.
        "address": "dns.google",
        "port": 53,
        "domains": [
          "geosite:geolocation-!cn",
          "domain:v2fly.org",
          "domain:cnbeta.com.tw"
        ],
        "skipFallback": false
      },
      {
        // for chinese domain, or whitelisted domain, reslove locally.
        "address": "localhost",
        "port": 53,
        "domains": [
          "geosite:geolocation-cn",
          "regexp:.*\\.cn-.*\\.aliyuncs.com$"
        ],
        "skipFallback": false
      }
    ]
  },
  // for traffic stats
  "policy": {
    "system": {
      "statsInboundUplink": true,
      "statsInboundDownlink": true,
      "statsOutboundUplink": true,
      "statsOutboundDownlink": true
    }
  },
  "stats": {}
}

Xray-router config

For Xray runs on client, router will pass all traffic to xray via tproxy, the proxy protocol is dokodemo-door.

The special point here is that if the traffic is on port 53, it should be treated as DNS traffic and forwarded to the DNS module. Other traffic can be processed according to the original path.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
{
  "log": {
    "loglevel": "warning"
  },
  "inbounds": [
    {
      "port": 12345,
      "protocol": "dokodemo-door",
      "settings": {
        "followRedirect": true,
        "network": "tcp,udp"
      },
      "streamSettings": {
        "sockopt": {
          "tproxy": "tproxy"
        }
      },
      "tag": "transparent",
      "sniffing": {
        "enabled": true,
        "destOverride": [
          "http",
          "tls"
        ]
      }
    }
  ],
  "outbounds": [
    {
      "tag": "proxy",
      "protocol": "vmess",
      "settings": {
        "vnext": [
          {
            "address": "proxy.net",
            "port": 443,
            "users": [
              {
                "id": "12345678-1234-1234-1234-123456789012"
              }
            ]
          }
        ]
      },
      "streamSettings": {
        "network": "ws",
        "security": "tls",
        "wsSettings": {
          "headers": {
            "User-Agent": "router"
          },
          "path": "/ws"
        },
        "tlsSettings": {
          "allowInsecure": false
        },
        "sockopt": {
          "mark": 255
        }
      }
    },
    {
      "protocol": "freedom",
      "settings": {
        "domainStrategy": "UseIP"
      },
      "streamSettings": {
        "sockopt": {
          "mark": 255
        }
      },
      "tag": "direct"
    },
    {
      // this outbund just means pass to dns module
      "tag": "dns_out",
      "protocol": "dns",
      "streamSettings": {
        "sockopt": {
          "mark": 255
        }
      }
    }
  ],
  "routing": {
    "domainMatcher": "mph",
    "domainStrategy": "IPOnDemand",
    "rules": [
      {
        // if this traffic is on port 53, treat as DNS traffic.
        "type": "field",
        "inboundTag": [
          "transparent"
        ],
        "port": 53,
        "network": "udp,tcp",
        "outboundTag": "dns_out"
      },
      {
        "type": "field",
        "domains": [
          "geosite:tld-cn",
          "domain:proxy.net",
        ],
        "outboundTag": "direct"
      },
      {
        "type": "field",
        "ip": [
          "geoip:private",
          "geoip:cn"
        ],
        "outboundTag": "direct"
      },
      {
        "type": "field",
        "network": "tcp,udp",
        "outboundTag": "proxy"
      }
    ]
  },
  "dns": {
    "queryStrategy": "UseIP",
    "servers": [
      {
        "address": "2001:4860:4860::8888",
        "port": 53,
        "domains": [
          "geosite:geolocation-!cn",
          "domain:v2fly.org",
          "domain:cnbeta.com.tw"
        ],
        "skipFallback": false
      },
      {
        "address": "localhost",
        "port": 53,
        "domains": [
          "geosite:geolocation-cn",
          "regexp:.*\\.cn-.*\\.aliyuncs.com$"
        ],
        "skipFallback": false
      }
    ]
  }
}
Tips
#Proxy
Xray Configuration Best Practice
http://boblu.net/xray-config-best-practice/
Author
Bob
Posted on
March 16, 2025
Licensed under