Skip to content

Xray-decoy v26.11.9

Latest

Choose a tag to compare

@YrustPd YrustPd released this 10 Nov 19:16

Decoy burns traffic on the server side while the user's data plan only sees
tiny requests. It is a tool: you tell it how much traffic to use and it does
the rest by itself.


What Decoy does

Every decoy session sends one small DNS request through the proxy and closes
itself before the answer arrives. The answer is a big one, because it is the
record of your own domain, and it is transferred by the remote end of the
proxy chain: the server receives it and throws it away.

your phone  --tiny request-->  Xray server  -->  public DNS resolver
your phone  <--nothing--       Xray server  <--  big answer (discarded)

The answer never reaches the phone. The server transferred it, so it counts as
server traffic, but the user's link only carried the tiny request.


Where to configure it

The decoy section goes in the client config file, on the same level as
inbounds and outbounds. Nothing on the server changes.

On Android, open your app's custom config (Xray JSON) and add the same
section next to your outbounds.


Easy mode

One block is enough. Everything else is measured and tuned at runtime.

"decoy": {
  "target": "500GB"
}

What happens automatically:

  • a pool of public DNS resolvers is selected and health checked
  • the largest answer among a few well known records is found
  • the answer size is learned from the wire
  • the close timing of every resolver is tuned by feedback
  • the query rate grows to whatever the resolvers allow
  • resolvers that stop answering, or answer too fast for any safe timing, are dropped

target accepts plain bytes or a human readable size: "500MB", "1TB", "50GB".

Leave target out and the engine keeps running at its steady rate forever.


Advanced mode

"decoy": {
  "target": "1TB",
  "records": ["d1.example.com", "d2.example.com"],
  "resolvers": ["77.88.8.8", "77.88.8.1", "77.88.8.88"],
  "transitProbe": "vpn.example.com:8080",
  "maxQps": 2000,
  "maxConcurrent": 256
}
Option Meaning When empty
target How much decoy traffic to generate, in bytes runs forever
record One large TXT record to query well known records are probed
records Several large TXT records; queries rotate and small answers are dropped same as above
resolvers DNS servers to query over TCP, "host" or "host:port" a built in pool is used
transitProbe Address of the proxy server itself, to measure the path conservative timing is used
maxQps Hard cap of the query rate the engine decides
maxConcurrent Hard cap of concurrent decoy sessions 128

record and records can be used together; all of them are probed and the
weak ones are dropped from the rotation automatically.


Working example: a real client config with Decoy

A stock v2rayNG-style client, VLESS with post quantum encryption over an HTTP
camo transport, mux enabled, socks and http inbounds. The only additions are
the decoy block at the end and nothing else:

{
  "dns": {
    "servers": ["1.1.1.1", "8.8.8.8"]
  },
  "inbounds": [
    {
      "listen": "127.0.0.1",
      "port": 10808,
      "protocol": "socks",
      "settings": {
        "allowTransparent": false,
        "auth": "noauth",
        "udp": true
      },
      "sniffing": {
        "destOverride": ["http", "tls"],
        "enabled": true,
        "routeOnly": false
      },
      "tag": "socks"
    },
    {
      "listen": "127.0.0.1",
      "port": 10809,
      "protocol": "http",
      "settings": {
        "allowTransparent": false,
        "udp": true
      },
      "sniffing": {
        "destOverride": ["http", "tls"],
        "enabled": true,
        "routeOnly": false
      },
      "tag": "http"
    }
  ],
  "log": {
    "access": "",
    "error": "",
    "loglevel": "warning"
  },
  "meta": null,
  "outbounds": [
    {
      "mux": {
        "enabled": true,
        "xudpProxyUDP443": "reject"
      },
      "protocol": "vless",
      "settings": {
        "vnext": [
          {
            "address": "server.example.com",
            "port": 443,
            "users": [
              {
                "encryption": "mlkem768x25519plus.random.0rtt.<your-encryption-key>",
                "id": "00000000-0000-0000-0000-000000000000"
              }
            ]
          }
        ]
      },
      "streamSettings": {
        "network": "tcp",
        "tcpSettings": {
          "header": {
            "request": {
              "headers": {
                "Accept-Encoding": ["gzip, deflate"],
                "Connection": ["keep-alive"],
                "Host": ["camo.example-cdn.com"],
                "Pragma": "no-cache"
              },
              "method": "GET",
              "path": ["/"],
              "version": "1.1"
            },
            "response": {
              "headers": {
                "Connection": ["keep-alive"],
                "Content-Type": [
                  "application/octet-stream",
                  "video/mpeg"
                ],
                "Pragma": "no-cache",
                "Transfer-Encoding": ["chunked"]
              },
              "reason": "OK",
              "status": "200",
              "version": "1.1"
            },
            "type": "http"
          }
        }
      },
      "tag": "proxy"
    },
    {
      "protocol": "freedom",
      "tag": "DIRECT"
    },
    {
      "protocol": "blackhole",
      "tag": "BLOCK"
    },
    {
      "protocol": "dns",
      "tag": "dns-out"
    }
  ],
  "policy": {
    "levels": {
      "8": {
        "connIdle": 300,
        "downlinkOnly": 1,
        "handshake": 4,
        "uplinkOnly": 1
      }
    },
    "system": {
      "statsOutboundDownlink": true,
      "statsOutboundUplink": true
    }
  },
  "remarks": "Xray-Decoy example",
  "routing": {
    "domainStrategy": "IPIfNonMatch",
    "rules": [
      {
        "inboundTag": ["socks", "http"],
        "outboundTag": "dns-out",
        "port": "53",
        "type": "field"
      },
      {
        "ip": ["198.18.0.2", "fd6e:a81b:704f:1211::2"],
        "outboundTag": "dns-out",
        "type": "field"
      },
      {
        "domain": [
          "domain:filimo.com",
          "domain:ip.me",
          "domain:namava.ir",
          "domain:filmnet.ir",
          "domain:gapfilm.ir"
        ],
        "outboundTag": "proxy",
        "type": "field"
      },
      {
        "domain": ["domain:.ir", "regexp:.*\\.ir"],
        "outboundTag": "DIRECT",
        "type": "field"
      },
      {
        "ip": ["geoip:ir"],
        "outboundTag": "DIRECT",
        "type": "field"
      }
    ]
  },
  "decoy": {
    "target": "500GB",
    "resolvers": ["8.8.8.8:53", "1.1.1.1:53"],
    "transitProbe": "server.example.com:8080"
  }
}

Notes on this example:

  • everything but the decoy block is a plain working client: substitute your
    own server address, user id, encryption key and spoofed Host header
  • the decoy queries are routed like any other traffic: nothing in the rules
    matches the resolver IPs, so they follow the first outbound, the proxy -
    exactly what Decoy needs. Keep it that way in your own configs: no rule may
    send the resolvers to a direct outbound
  • transitProbe points at a plain HTTP endpoint of the server (web panel,
    dashboard), never at the proxy port itself. If the server has no such port,
    delete the line: the engine still works, it just uses conservative timing
    on jumpy paths
  • Decoy works with mux enabled or disabled; this example keeps it enabled
  • set "loglevel": "info" to watch the engine: its resolvers, the learned
    answer size, the query rate, and the final "target reached" line
  • this burns 500 GB at the server; the client link pays the few MB of
    requests for it

Creating the DNS records

The bigger the record, the better the result: the answer size is the amount of
server traffic per query, while the query itself is only a few dozen bytes.

  1. Pick a domain you own, e.g. example.com.

  2. Create a TXT record named decoy.example.com whose value is a long random
    string. Most providers split long values into 255 character chunks
    automatically. On Cloudflare a set of TXT records with the same name works
    too: about 30 chunks of 255 characters give an answer of roughly 8 KB.

  3. Check the answer size with dig:

    dig +tcp TXT decoy.example.com @8.8.8.8 | grep "MSG SIZE"
    
  4. Put the name in the config. There is nothing to calculate: the engine
    measures the answer size by itself.

Notes:

  • the record content can be random garbage; only its size matters
  • DNS over TCP is used, so answers are not limited by the UDP size cap
  • a bigger record means fewer queries for the same burn: 8 KB gives about
    100:1 in theory measured roughly 60 to 90:1, 60 KB gives about 770:1 of
    server traffic per byte of the user's plan

transitProbe: the one line that makes it leak free

A decoy answer must arrive at the server after the session is closed and never
reach the phone. The safe window lives on the server side of the chain, so the
engine subtracts the time the path itself takes. On mobile connections,
especially behind a VPN, that path swings between tens and thousands of
milliseconds; measuring it is the difference between 0.3% and 20% of leaked
answers.

Set transitProbe to any address of the proxy server that answers immediately:
an HTTP port is perfect (the web panel, port 8080 or 443).

"transitProbe": "vpn.example.com:8080"

What the numbers look like

Measured against a stock server and three public resolvers, with a record
whose answers are 8.4 KB:

Metric Result
Server traffic per run exactly the configured target
User plan consumption roughly 0.7 to 1 MB of tunnel traffic per 50 MB of burn (about 1 to 2 percent; ambient phone traffic rides the same tunnel)
Leaked answers under 1 percent at the tuned steady rate; a few percent only when pushing the maximum rate on a jumpy path
Ratio about 60 to 90 to 1 with an 8.4 KB record; larger records go far higher
Speed 300 to 1000+ sessions per second, auto tuned
CPU a few percent of one core
Memory about 40 MB

Leaked answers happen when the network path jitters inside the timing window;
the engine halves the window on the spot and pauses its growth, so the damage
stays in the first seconds of a run.


Does it count against the user's data plan or the panel quota?

The panel counts the traffic of the tunnel. The decoy answers are dropped at
the server before entering the tunnel, so only the tiny requests are counted:
roughly 1 percent of the burned volume, measured at about 0.8 MB of tunnel
traffic per 50 MB. The server bandwidth of course shows the full amount - that
is the point of the tool.


Install

After publishing, the Assets of this release carry builds for Windows, Linux,
macOS and Android with checksums. Download the zip that matches your platform,
replace your client's xray binary with its content, and add the decoy
section of the example above to the config.


Compatibility

  • any protocol: VLESS, VMess, Trojan, Shadowsocks and others
  • any transport: TCP, REALITY, WebSocket, XHTTP and others
  • works with mux enabled or disabled
  • the server side needs no change at all: stock Xray is enough
  • mobile clients with custom Xray configs (v2rayNG and friends) run it as is

Tips and troubleshooting

  • set "loglevel": "info" to see the engine status: resolvers, answer size,
    query rate and the final "target reached" line
  • if the engine reports that no resolver answered, the resolver list or the
    record name is wrong; check the record first with dig
  • keep maxQps at or below the number of resolvers times a few hundred; the
    engine already adapts to what they allow and backs off when answers shrink
  • to trade speed for an even smaller leak, lower maxQps; to trade the other
    way, raise it
  • for the lowest possible traffic cost per byte burned, use the largest record
    you can: the cost of one session is fixed, the answer size is not

Merging upstream Xray-core

The feature lives in its own app/decoy package. Shared files only gain a
JSON config field and a one line version identifier, so rebasing onto future
Xray-core releases stays trivial.