Xray

https://xtls.github.io/en
Admin
Xray is a versatile network utility featuring high-speed VLESS and XTLS protocols, powerful routing...
Tokens:224,216
Snippets:1,803
Trust Score:8.3
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install dependencies and run the documentation dev server

Source: https://xtls.github.io/en/document/document.html

Install dependencies and start the local development server to preview the documentation site.

```bash
pnpm install
pnpm run docs:dev
```

--------------------------------

### Install wgcf-cli

Source: https://xtls.github.io/en/document/level-2/warp.html

Run this command to install wgcf-cli. It downloads and executes the installation script from wgcf-cli.vercel.app.

```bash
bash -c "$(curl -L wgcf-cli.vercel.app)"
```

--------------------------------

### Install Xray via yay (AUR helper)

Source: https://xtls.github.io/en/document/install.html

Install Xray from the Arch User Repository using the yay helper. Requires yay to be installed.

```bash
yay -S xray
```

--------------------------------

### BuildIPMatcher example

Source: https://xtls.github.io/en/development/lua/reference/module-geodata.html

Example of building an IPMatcher with IP rules. Supports IPs, CIDR, geoip:, ext:, and ! reverse rules.

```lua
local privateIPsObj = geodata.BuildIPMatcher(
    "10.0.0.0/8", "192.168.0.0/16", "fc00::/7"
)
```

--------------------------------

### Start Xray service with sudo systemctl start xray

Source: https://xtls.github.io/en/document/level-0/ch07-xray-server.html

Starts the Xray service. Requires proper permissions for log and certificate files to avoid common pitfalls.

```shell
sudo systemctl start xray
```

--------------------------------

### Start WireGuard Tunnel (wg-quick up)

Source: https://xtls.github.io/en/document/level-2/redirect.html

Starts the WireGuard tunnel using the wg0 configuration.

```bash
wg-quick up wg0
```

--------------------------------

### Install HAProxy

Source: https://xtls.github.io/en/document/level-2/nginx_or_haproxy_tls_tunnel.html

Install HAProxy using either pacman or apt package manager.

```bash
pacman -Su haproxy
```

```bash
apt install haproxy
```

--------------------------------

### Sockopt JSON configuration example

Source: https://xtls.github.io/en/config/transports/sockopt.html

Example of a SockoptObject within an outbound streamSettings, showing all available fields. This configuration applies to outbound connections and also to inbound. The example includes settings for mark, TCP options, transparent proxy, domain strategy, and more.

```json
{
  // outbound example; also applies to inbound
  "outbounds": [
    {
      // ...
      "streamSettings": {
        "sockopt": {
          "mark": 0,
          "tcpMaxSeg": 1440,
          "tcpFastOpen": false,
          "tproxy": "off",
          "domainStrategy": "AsIs",
          "happyEyeballs": {},
          "dialerProxy": "",
          "acceptProxyProtocol": false,
          "trustedXForwardedFor": [],
          "tcpKeepAliveInterval": 0,
          "tcpKeepAliveIdle": 300,
          "tcpUserTimeout": 10000,
          "tcpcongestion": "bbr",
          "interface": "wg0",
          "V6Only": false,
          "tcpWindowClamp": 600,
          "tcpMptcp": false,
          "addressPortStrategy": "",
          "customSockopt": []
        }
      }
    }
  ]
}
```

--------------------------------

### VLESS inbound with fallback to port 8080

Source: https://xtls.github.io/en/document/level-1/fallbacks-lv1.html

Example Xray configuration for a VLESS inbound on port 443 with a fallback to port 8080. The fallback forwards non-VLESS traffic to a subsequent program (e.g., Nginx) listening on that port. This is the simplest fallback setup from the Beginner's Guide.

```json
{
  "inbounds": [
    {
      "port": 443,
      "protocol": "vless",
      "settings": {
        "users": [
          // ... ...
        ],
        "decryption": "none",
        "fallbacks": [
          {
            "dest": 8080 // Default fallback to the probe-resistant proxy/service
          }
        ]
      },
      "streamSettings": {
        // ... ...
      }
    }
  ]
}
```

--------------------------------

### Example: run Xray with xray_tproxy user

Source: https://xtls.github.io/en/document/level-2/iptables_gid.html

Example command to set max open files and run Xray with the xray_tproxy user, using the config file /etc/xray/config.json in the background.

```bash
ulimit -SHn 1000000
sudo -u xray_tproxy xray -c /etc/xray/config.json &
```

--------------------------------

### GetAttributes: Example using :method attribute

Source: https://xtls.github.io/en/development/lua/reference/hook-routing.html

Example that retrieves attributes and checks if the :method attribute equals GET, returning routing directives "direct" and "lua-get".

```lua
local attributes = ctx:GetAttributes()
if attributes[":method"] == "GET" then
    return "direct", "lua-get"
end
```

--------------------------------

### ReflectionService grpcurl list example

Source: https://xtls.github.io/en/config/api.html

Shows how to use grpcurl to list available APIs on the server. The output includes reflection and service names.

```bash
$ grpcurl -plaintext localhost:10085 list
grpc.reflection.v1alpha.ServerReflection
v2ray.core.app.proxyman.command.HandlerService
v2ray.core.app.stats.command.StatsService
xray.app.proxyman.command.HandlerService
xray.app.stats.command.StatsService
```

--------------------------------

### Load Balancer Configuration Example

Source: https://xtls.github.io/en/config/routing.html

Complete configuration example showing a round-robin balancer. The routing rule uses 'balancerTag' to reference the balancer, which selects from outbounds with tags starting with 'out'. Inbound and outbound configs are placeholders.

```json
{
  "routing": {
    "rules": [
      {
        "inboundTag": ["in"],
        "balancerTag": "round"
      }
    ],
    "balancers": [
      {
        "selector": ["out"],
        "strategy": {
          "type": "roundRobin"
        },
        "tag": "round"
      }
    ]
  },

  "inbounds": [
    {
      // Inbound config
      "tag": "in"
    }
  ],

  "outbounds": [
    {
      // Outbound config
      "tag": "out1"
    },
    {
      // Outbound config
      "tag": "out2"
    }
  ]
}
```

--------------------------------

### Convert typed message to JSON using xray convert json

Source: https://xtls.github.io/en/document/command.html

Pipe a base64-encoded typed message to xray convert json to get the JSON representation. The example shows a Shadowsocks account conversion and its output.

```bash
# Usage: xray convert json [-type] [stdin:] [typedMessage file]

tmsg='{
  "type": "xray.proxy.shadowsocks.Account",
  "value": "CgMxMTEQBg=="
}'

echo ${tmsg} | xray convert json stdin:

# The output of the above command is:
'{
  "cipherType": "AES_256_GCM",
  "password": "111"
}'

# Detailed instructions
xray help convert json
```

--------------------------------

### DomainMatcher:Match example

Source: https://xtls.github.io/en/development/lua/reference/module-geodata.html

Shows how to call Match on a domain matcher object and iterate over the returned indices. Rule indices start at 0, so use rules[ruleNumber + 1] to access the original rule in a Lua array.

```lua
local indices = sitesObj:Match("www.example.com")
if indices ~= nil then
    for i = 1, #indices do
        local ruleNumber = indices[i]
    end
end
```

--------------------------------

### BuildDomainMatcher example

Source: https://xtls.github.io/en/development/lua/reference/module-geodata.html

Example of building a DomainMatcher with domain rules. Supports prefixes like domain:, full:, keyword:, regexp:, dotless:, geosite:, and ext:.

```lua
local sitesObj = geodata.BuildDomainMatcher(
    "example.com", "full:other.example"
)
```

--------------------------------

### AI prompt for Xray configuration assistance (Markdown)

Source: https://xtls.github.io/en/config

A copyable prompt to send to an AI assistant at the start of a conversation to get reliable Xray-core configuration help. It instructs the AI to use only the official documentation, avoid inventing fields, and output JSONC with comments by default.

```markdown
# Role

You are an assistant specialized in Xray-core configuration.

Your task is to help me understand Xray-core settings and generate usable Xray-core configuration files based on the official documentation.

# Source of truth

Use the following official Xray-core full documentation as the only source of truth:

https://xtls.github.io/llms-full.txt

The documentation is written mainly in Chinese. You must still read and understand the Chinese documentation, then explain it in the response language. Do not change the meaning of fields, values, defaults, restrictions, or configuration structures during translation.

Do not rely on memory, prior knowledge, community templates, V2Ray configuration habits, GitHub issues, blog posts, or common examples to decide whether a field is valid.

# Language

By default, answer in English.

If I clearly ask in another language or request another output language, follow my requested language.

Do not translate Xray-core field names, protocol names, enum values, JSON keys, file paths, or literal configuration values.

# Most important rule

Do not invent configuration fields.

Only use fields, values, defaults, restrictions, and configuration structures that are explicitly mentioned in the official documentation.

If the official documentation does not mention a field, value, default, restriction, or combination rule, say:

“Not mentioned in the documentation; cannot confirm.”

Do not guess, do not complete missing parts from memory, and do not add unsupported fields just to make the configuration look complete.

# If you cannot access the documentation

If you cannot open or read the official documentation link, say:

“I cannot access the official documentation link, so I cannot guarantee a hallucination-free answer. Please manually download https://xtls.github.io/llms-full.txt and upload it here. I will then answer only based on the uploaded document.”

When the official documentation is unavailable, do not generate Xray-core configuration files from memory, and do not explain configuration details from memory.

# Answering workflow

For any configuration-related question, follow this workflow:

1. First read the relevant parts of the official documentation.
2. Identify the relevant configuration objects, fields, values, and restrictions.
3. Answer only with information explicitly confirmed by the documentation.
4. If something is not confirmed by the documentation, mark it as “Not mentioned in the documentation; cannot confirm.”

When generating a configuration, follow this workflow:

1. First confirm which fields you plan to use.
2. Generate the configuration using only fields confirmed by the official documentation.
3. Before outputting the final configuration, review it and remove any field that cannot be confirmed by the documentation.
4. If part of my request cannot be confirmed by the documentation, put it under “Unconfirmed items”.

# Output format

By default, output JSONC, meaning JSON-style configuration with `//` comments.

Comments should help regular users understand:

- what the field does;
- whether the user needs to change it;
- what to be careful about when changing it.

Comments must not introduce behavior that is not confirmed by the official documentation.

If I explicitly ask for “pure JSON”, output valid JSON without comments.

Do not use `_comment` fields unless the official documentation explicitly says they are supported.

# When generating a configuration

Use this format:

## Documentation basis

Briefly list the official documented configuration objects and key fields used in this answer.

## Configuration file

```jsonc
{
  // Write the configuration here
}
```
```

--------------------------------

### Example usage of log.Info and log.Warning

Source: https://xtls.github.io/en/development/lua/reference/module-log.html

Example calls to log.Info and log.Warning, demonstrating how to log a query domain and an upstream query failure.

```lua
log.Info("Query domain: ", domain)
log.Warning("Upstream query failed: ", err)
```

--------------------------------

### DNS server configuration with query strategies

Source: https://xtls.github.io/en/config/dns.html

Example JSON configuration for the DNS object, defining multiple servers with specific domains and query strategies, and a global query strategy. The example shows how to use 'UseIPv4' for Netflix domains and 'UseIPv6' for OpenAI domains, with a global 'UseIP' strategy.

```json
{
  "dns": {
    "servers": [
      "https://1.1.1.1/dns-query",
      {
        "address": "https://8.8.8.8/dns-query",
        "domains": ["geosite:netflix"],
        "skipFallback": true,
        "queryStrategy": "UseIPv4" // netflix domain queries A record
      },
      {
        "address": "https://1.1.1.1/dns-query",
        "domains": ["geosite:openai"],
        "skipFallback": true,
        "queryStrategy": "UseIPv6" // openai domain queries AAAA record
      }
    ],
    "queryStrategy": "UseIP" // Globally query both A and AAAA records
  }
}
```

--------------------------------

### MetricsObject configuration example

Source: https://xtls.github.io/en/config/metrics.html

Configuration for the metrics item in the config file. The tag field is the outbound proxy tag, and listen is an address and port to provide the service. If listen is set and tag is empty, tag is automatically set to 'Metrics'. If neither is set, the core fails to start.

```json
{
  "metrics": {
    "tag": "Metrics",
    "listen": "127.0.0.1:11111"
  }
}
```

--------------------------------

### Execute Xray installation script with sudo bash

Source: https://xtls.github.io/en/document/level-0/ch07-xray-server.html

Runs the downloaded installation script with sudo to install Xray. This is the second step in the installation process.

```shell
sudo bash install-release.sh
```

--------------------------------

### Create website directory and index.html

Source: https://xtls.github.io/en/document/level-0/ch05-webpage.html

Creates the website folder ~/www/webpage/ and opens index.html in nano for editing. The folder is used for the camouflage site.

```shell
mkdir -p ~/www/webpage/ && nano ~/www/webpage/index.html
```

--------------------------------

### Install Xray locally on side router

Source: https://xtls.github.io/en/document/level-2/tproxy_ipv4_and_ipv6.html

Commands to manually install Xray on the side router if it is not already installed. Download the appropriate Xray binary, copy the install script, grant execute permission, and run the local installation.

```bash
# chmod 700 install-release.sh
```

```bash
# ./install-release.sh --local Xray-linux-64.zip
```

--------------------------------

### Install Xray via pacman (Arch Linux CN repository)

Source: https://xtls.github.io/en/document/install.html

Install Xray from the Arch Linux CN repository using pacman as root. Requires the repository to be added first.

```bash
pacman -S xray
```

--------------------------------

### Enable Nginx auto-start

Source: https://xtls.github.io/en/document/level-2/nginx_or_haproxy_tls_tunnel.html

Command to enable Nginx to start on boot.

```bash
systemctl enable nginx
```

--------------------------------

### Install Xray via Homebrew on macOS

Source: https://xtls.github.io/en/document/install.html

Use Homebrew package manager to install Xray on macOS. Requires Homebrew to be installed.

```bash
brew install xray
```

--------------------------------

### Install required programs: iptables, ip6tables, nftables

Source: https://xtls.github.io/en/document/level-2/tproxy_ipv4_and_ipv6.html

Commands to install the necessary firewall tools for TProxy configuration. Choose either iptables/ip6tables or nftables depending on your preference.

```bash
# sudo apt install iptables ip6tables
```

```bash
# sudo apt install nftables
```

--------------------------------

### Install sudo

Source: https://xtls.github.io/en/document/level-0/ch04-security.html

Run this command to update package lists and install the sudo package. The command uses && to chain two commands: apt update refreshes software version info, and apt install installs the sudo program.

```shell
apt update && apt install sudo
```

--------------------------------

### Download and Install Caddy with Proxy Protocol Module

Source: https://xtls.github.io/en/document/level-1/fallbacks-with-sni.html

Downloads a precompiled Caddy binary with the Proxy Protocol module and makes it executable. Replace the existing Caddy binary with this one.

```bash
sudo curl -o /usr/bin/caddy "https://caddyserver.com/api/download?os=linux&arch=amd64&p=github.com%2Fmastercactapus%2Fcaddy2-proxyprotocol&idempotency=79074247675458"
sudo chmod +x /usr/bin/caddy
```

--------------------------------

### UserObject Example

Source: https://xtls.github.io/en/config/inbounds/http.html

Example of a UserObject with username and password fields, both required.

```json
{
  "user": "my-username",
  "pass": "my-password"
}
```

--------------------------------

### Download Xray installation script with wget

Source: https://xtls.github.io/en/document/level-0/ch07-xray-server.html

Downloads the official Xray installation script to the current directory. This is the first step in installing Xray using the non-root user mode.

```shell
wget https://github.com/XTLS/Xray-install/raw/main/install-release.sh
```

--------------------------------

### Start xray with configuration file on Linux/macOS

Source: https://xtls.github.io/en/document/level-0/ch08-xray-clients.html

Command to start xray-core with a specified configuration file path. The -c parameter tells xray to use the config file at the given location.

```shell
/usr/local/bin/xray -c /usr/local/etc/xray/config.json
```

--------------------------------

### dns.Query example

Source: https://xtls.github.io/en/development/lua/reference/module-dns.html

Queries example.com with IPv4 and IPv6 allowed, FakeDNS disabled. On success, retrieves the first IP as a string.

```lua
local ips, ttl, err = dns.Query("example.com", true, true, false)
if err == nil and ips ~= nil and #ips > 0 then
    local firstIP = ips[1]:String()
end
```
Tokens:
Raw