pjandro/3x-ui
1
0
Fork 0
mirror of https://github.com/MHSanaei/3x-ui.git synced 2026-10-30 09:45:00 +03:00
Code Issues Packages Projects Releases Wiki Activity
Files
d7d591259e1f4e7dca62919d60a75352276784df
3x-ui/docs/content/docs/en/config/transports.mdx
T
MHSanaei 61b129d5b3 feat(xray): update xray-core to v26.10.21 and adapt panel 
Bump xtls/xray-core to 1b1647cd9ddf (v26.10.21) and move the three
binary pins (DockerInit.sh, both release.yml fetches) in lockstep. The
v26.10.10 release was pulled upstream, so the old pins already 404.

XDRIVE (#7182): the core now runs XDRIVE only for VLESS inside VLESS
encryption, with no flow, and an outbound only over Mux; it refuses the
whole config otherwise. The panel offers XDRIVE only for VLESS, refuses
to save an inbound without decryption, never emits a client flow on an
XDRIVE stream (config, JSON subscription, forms), and turns Mux on when
an outbound picks XDRIVE. An inbound or template outbound stored before
the upgrade that the core would refuse is left out of the generated
config with a warning, so it no longer stops every other inbound. The
service "Google Drive" is now "google-drive" (old name read as a
deprecated alias); saves, the schema and both form adapters store the
new name. XDRIVE and MASQUE gain a client xmux; both schemas keep it
instead of stripping it on an inbound save.

Lua scripts (#7124, #7136): the core refuses a routing script beside
rules or domainStrategy, and a dns script beside the fallback/parallel
switches or a domain-scoped server. The panel always keeps its api
routing rule, so a template save now refuses any routing script and a
dns script in a refused combination, and a stored one is dropped from
the generated config so the core still starts. Noise masks gain a Lua
script that the loader compiles inside Build: the in-process build
(template save check, hot add) now resolves a relative script the way
the xray child does, beside the xray binary, instead of failing it. The
mask editor gets a Script field that replaces the noise list.

XDNS (#7140): a resolver takes https:// DoH addresses with worker,
tlsConfig and quicConfig. The mask editor registered only addrs, so a
save dropped the rest; it now edits all four.

Finalmask filter (#7206): a new TCP/UDP mask screens an inbound's source
IPs. The inbound mask editor offers it with its allow and block lists;
it is a no-op on a dialer and an older client core refuses the type, so
the share link and JSON subscription drop it like the Go link already
does.
2026-10-22 17:10:11 +02:00

242 lines
15 KiB
Plaintext
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
title: Transports & Security
description: Every transport 3x-ui exposes — TCP, mKCP, WebSocket, gRPC, HTTPUpgrade, XHTTP, Hysteria, XDRIVE, MASQUE — with their settings, plus FinalMask obfuscation, sockopt, TLS/REALITY, XTLS-Vision, and VLESS encryption.
icon: Network
---
A **transport** decides how packets are carried between client and server, a
**security** layer decides how they're encrypted and disguised, and **FinalMask**
can obfuscate what's left. The panel only offers valid combinations; this page
lists every transport's settings and the rules the panel enforces.
## Transports
Pick the transport (the inbound's `network`) in the inbound/outbound form. Each
network writes its own settings key on the wire (`tcpSettings`, `kcpSettings`, …).
| Transport | Settings key | When to use it |
| --------------- | --------------------- | ---------------------------------------------------------------------- |
| **TCP (Raw)** | `tcpSettings` | Lowest overhead. The basis for REALITY + XTLS-Vision and fallbacks; optional HTTP/1.1 header camouflage. |
| **mKCP** | `kcpSettings` | Reliable protocol over **UDP** — trades bandwidth for lower latency on lossy links. Carries no TLS/REALITY. |
| **WebSocket** | `wsSettings` | Works through CDNs and HTTP reverse proxies; very compatible. |
| **gRPC** | `grpcSettings` | HTTP/2-based; multiplexes well and proxies cleanly through Nginx. |
| **HTTPUpgrade** | `httpupgradeSettings` | CDN-friendly HTTP/1.1 `Upgrade`; lighter than full WebSocket. |
| **XHTTP** | `xhttpSettings` | Modern stream-multiplexed HTTP transport; CDN-friendly and REALITY-capable. |
| **Hysteria** | `hysteriaSettings` | QUIC-based transport — only for the **Hysteria2** protocol. |
| **XDRIVE** | `xdriveSettings` | Tunnels the stream through files in shared cloud storage (Google Drive, a local folder or any HTTP storage API). |
| **MASQUE** | `masqueSettings` | CONNECT-IP over HTTP/3 or HTTP/2 — only for the **MASQUE** protocol. See [MASQUE](/docs/config/masque). |
<Callout type="info">
**WireGuard** and **Tunnel** (dokodemo-door) inbounds expose no transport
selector — their stream carries only security/sockopt. Earlier panels also
exposed a raw **HTTP/2 (`http`)** transport; it has been superseded by **XHTTP**
and is no longer selectable.
</Callout>
### TCP (Raw) — `tcpSettings`
| Field | Default | Meaning |
| ------------------------------ | ------- | ----------------------------------------------------------------------- |
| `acceptProxyProtocol` | `false` | Accept the PROXY protocol from an upstream proxy so the real client IP is preserved. |
| `header.type` | `none` | `none`, or `http` for HTTP/1.1 camouflage. |
| `header.request` / `response` | — | When `type: http`: method, path, version and a header map that mimic a normal HTTP exchange. |
### mKCP — `kcpSettings`
| Field | Default | Meaning |
| ------------------ | ----------- | ---------------------------------------------------------------- |
| `mtu` | `1350` | Maximum transmission unit, in bytes (576–1460). |
| `tti` | `20` | Transmission time interval, in ms (10–100). Lower = more responsive, more overhead. |
| `uplinkCapacity` | `5` | Upload bandwidth budget, in **MB/s**. |
| `downlinkCapacity` | `20` | Download bandwidth budget, in **MB/s**. |
| `cwndMultiplier` | `1` | Congestion-window multiplier; raise to push harder on good links. |
| `maxSendingWindow` | `2097152` | Upper bound on in-flight packets. |
<Callout type="info">
mKCP can't carry TLS or REALITY. To disguise it, add a **FinalMask** UDP mask —
the `mkcp-legacy` mask reproduces the classic header obfuscation that older Xray
stored in `kcpSettings.header`/`seed` (those fields no longer exist here).
</Callout>
### WebSocket — `wsSettings`
| Field | Default | Meaning |
| --------------------- | ------- | ---------------------------------------------------------------- |
| `path` | `/` | Request path — route on it when several services share one host. |
| `host` | _(none)_| `Host` header override (useful behind a CDN). |
| `headers` | `{}` | Extra request headers. |
| `heartbeatPeriod` | `0` | Seconds between keepalive pings; `0` disables them. |
| `acceptProxyProtocol` | `false` | Accept the PROXY protocol from an upstream. |
### gRPC — `grpcSettings`
| Field | Default | Meaning |
| ------------- | ------- | --------------------------------------------------------- |
| `serviceName` | _(none)_| gRPC service path; acts like a secret route. |
| `authority` | _(none)_| `:authority` pseudo-header override. |
| `multiMode` | `false` | Multiplex several streams over one connection. |
### HTTPUpgrade — `httpupgradeSettings`
| Field | Default | Meaning |
| --------------------- | ------- | --------------------------------------------- |
| `path` | `/` | Request path. |
| `host` | _(none)_| `Host` header override. |
| `headers` | `{}` | Extra request headers. |
| `acceptProxyProtocol` | `false` | Accept the PROXY protocol from an upstream. |
HTTPUpgrade is a one-shot HTTP/1.1 `Upgrade` with no WebSocket framing — there's
no heartbeat field.
### XHTTP — `xhttpSettings`
XHTTP (SplitHTTP) has a large field set; the panel fills sensible defaults. The
ones you'll usually touch:
| Field | Default | Meaning |
| ---------------------- | ----------- | ---------------------------------------------------------------------- |
| `path` | `/` | Request path. |
| `host` | _(none)_ | `Host` header override. |
| `mode` | `auto` | `auto`, `packet-up`, `stream-up`, or `stream-one`. `packet-up` is the most CDN-compatible; `stream-*` are lower latency. |
| `xPaddingBytes` | `100-1000` | Random padding range that blurs packet sizes. |
| `scMaxBufferedPosts` | `30` | Server-side buffer for uploaded POSTs. |
| `scStreamUpServerSecs` | `20-80` | Stream-up server window (dash range). |
| `xmux` (`enableXmux`) | _(off)_ | Connection multiplexing — `maxConcurrency` `16-32`, `maxConnections` `6`, … Turn on for high concurrency. |
Session-ID fields (`sessionIDPlacement`, `sessionIDKey`, `sessionIDTable`,
`sessionIDLength`) and the `scMin/MaxEachPostBytes` knobs are advanced; leave them
empty unless you're matching a specific upstream.
### Hysteria — `hysteriaSettings`
Only valid when the protocol is **Hysteria2**.
| Field | Default | Meaning |
| ---------------- | ------- | ----------------------------------------------------------------------- |
| `version` | `2` | Hysteria protocol version. |
| `auth` | _(none)_| Shared authentication string. |
| `udpIdleTimeout` | `60` | Seconds (2–600) before idle UDP sessions are dropped. |
| `masquerade` | — | Disguise as an HTTP/3 server: `type` `proxy`/`file`/`string` with `url`/`dir`/`content`, plus `headers` and `statusCode`. |
### XDRIVE — `xdriveSettings`
XDRIVE carries the stream as files in a folder both ends can reach: the server polls
that folder instead of accepting connections on its port. Both sides must use the
**same** service, folder and secrets, so the JSON subscription ships them to every
client; XDRIVE inbounds get no share link or Clash entry.
Since Xray 26.10.17 XDRIVE carries only **VLESS** inside **VLESS encryption**, with
no flow: an inbound needs a `decryption` value, an outbound its `encryption` and Mux
enabled. The panel offers XDRIVE only for VLESS, refuses to save an inbound without
`decryption`, and leaves one stored before the upgrade out of the running config.
| Field | Default | Meaning |
| -------------- | -------------- | ----------------------------------------------------------------------- |
| `service` | `google-drive` | `google-drive`, `local` (a folder on disk) or `template` (any HTTP storage API). The old `Google Drive` spelling is still read. |
| `remoteFolder` | — | Folder that holds the session files. |
| `secrets` | — | Google Drive: ClientID, ClientSecret, RefreshToken — exactly three, in that order. Template: values read as `{secret0}`, `{secret1}`, …. |
| `template` | — | Template service only: the storage API's `auth`, `put`, `get`, `list` and `delete` operations. |
| tuning | core defaults | `segmentBytes` (512 KiB), `flushIntervalMs` (20), `pollIntervalMs`/`maxPollIntervalMs` (50/500), `eagerWindowMs` (2000), `holeTimeoutMs` (30000), `sessionTtlSeconds` (300), `concurrency` (8). |
The optional **Front address/port** (the stream-level `address`/`port`) is a domain
front the storage API is dialed through; TLS still names the API host. XDRIVE has
no TLS/REALITY layer of its own — its traffic is the storage API's HTTPS. On an
outbound, **TLS** security shapes that HTTPS connection: its SNI, uTLS fingerprint
and ALPN are what the storage API sees.
## FinalMask — late-layer obfuscation
**FinalMask** wraps traffic **after** the transport and security layers, so it can
disguise transports that don't carry TLS (like mKCP) or add a second skin on top of
TLS. Masks are configured per direction:
- **TCP masks** — `fragment`, `sudoku`, `header-custom`, `xmc` (disguises the
stream as Minecraft protocol traffic; requires a password, with optional
hostname and player usernames), plus the inbound-only `filter`.
- **UDP masks** — `salamander`, `mkcp-legacy`, `header-custom`, `xdns`, `xicmp`,
`noise`, `sudoku`, `realm`, plus the client-only `udphop` and the inbound-only
`filter`. (`mkcp-legacy`
reproduces the old mKCP header obfuscation; `udphop` rotates the remote port —
and optionally the remote IP — on an interval or per connection to dodge port
blocking.)
- **QUIC params** — congestion control (`reno`, `bbr`, `brutal`, `force-brutal`),
Brutal up/down rates, and receive-window tuning. On an inbound, **UDP Hop** sets
the port range advertised to clients (the share link's `mport` and the JSON
subscription's `udphop` mask); the server still listens on its own port. Since
Xray 26.9.9 a client hops only through the `udphop` mask, so the panel converts
an older client `quicParams.udpHop` to it.
`filter` (Xray 26.10.21) drops an inbound's connections by source IP:
`allowedSourceIPs` admits only the listed sources, `blockedSourceIPs` drops its
sources, and a blocked match wins. Both take CIDRs or `geoip:` entries. Share links
and JSON subscriptions leave it out, since it only acts on the listener.
FinalMask replaces the per-transport `header`/`seed` obfuscation that older Xray
builds exposed.
## sockopt — low-level socket options
`sockopt` rides alongside any transport and tunes the underlying socket. The most
useful fields:
| Field | Default | Meaning |
| --------------------- | ------- | ---------------------------------------------------------------- |
| `tcpFastOpen` | `false` | Enable TCP Fast Open. |
| `tcpcongestion` | `bbr` | Congestion control: `bbr`, `cubic`, or `reno`. |
| `tproxy` | `off` | Transparent proxy mode: `off`, `redirect`, or `tproxy`. |
| `domainStrategy` | `AsIs` | How addresses resolve (`UseIP`, `ForceIPv4`, …). |
| `dialerProxy` | _(none)_| Chain this outbound's dialing through another outbound tag. |
| `interface` | _(none)_| Bind to a specific network interface. |
| `mark` | `0` | SO_MARK for policy routing (`0` = unset). |
Numeric fields left at `0` are omitted on the wire so Xray keeps OS defaults.
Advanced entries (`happyEyeballs`, `customSockopt[]`, keepalive timers) are
available for special cases.
## Security
The security layer is one of **`none`**, **`tls`**, or **`reality`**, with these
eligibility rules:
| Security | Eligible transports | Eligible protocols |
| ----------- | -------------------------------------------- | --------------------------------------------------- |
| **TLS** | `tcp`, `ws`, `grpc`, `httpupgrade`, `xhttp` | VLESS, VMess, Trojan, Shadowsocks (Hysteria2 is always TLS) |
| **REALITY** | `tcp`, `grpc`, `xhttp` | VLESS, Trojan |
mKCP and Hysteria don't take a separate TLS/REALITY layer — mKCP runs plaintext
(obfuscate with FinalMask), and Hysteria is QUIC/TLS by design. REALITY disguises
your server as a real TLS site and needs no certificate — see
[REALITY](/docs/config/reality).
## XTLS-Vision flow
The `xtls-rprx-vision` flow is fast and DPI-resistant. It's available for
**VLESS** when either:
- the transport is raw **TCP** with **TLS** or **REALITY** security (classic
XTLS-Vision), or
- VLESS encryption is enabled, on any transport (see below).
Set the flow on the VLESS **client**, not the inbound. With classic Vision on
TCP, the panel can also offer a **Vision seed** once a client uses the flow.
## VLESS encryption (ML-KEM)
VLESS supports post-quantum **encryption** (ML-KEM / `mlkem768x25519`), stored in
the inbound's `decryption` (server) and clients' `encryption` (for link
generation). When enabled, it unlocks the Vision flow on any transport. Generate the
keys from the panel's VLESS settings.
## Shadowsocks ciphers
Shadowsocks inbounds support both classic ciphers and **Shadowsocks-2022**
(method names starting with `2022-blake3-`). `2022-blake3-chacha20-poly1305` is not
offered for inbounds: Xray-core supports it only without users, and every panel
inbound has clients. Outbounds can still use it.
<Callout type="info">
Transports and security must match on both ends. The client's share link
encodes them (`type=ws`, `security=reality`, `flow=xtls-rprx-vision`, …) —
decode any link with the [share-link inspector](/docs/config/share-links).
</Callout>
Reference in New Issue View Git Blame Copy Permalink