mirror of
https://github.com/XTLS/Xray-docs-next.git
synced 2026-09-29 18:38:02 +03:00
Wiregurad: Simplify
We only explain in detail the concepts we've introduced and the things people often confuse, rather than over-explaining every single field. (wireguard official doc already has these for advance user)
This commit is contained in:
Fangliding
@@ -1,6 +1,6 @@
|
||||
# WireGuard
|
||||
|
||||
User-space WireGuard protocol implementation for establishing a WireGuard tunnel with a peer and receiving traffic through the tunnel.
|
||||
User-space WireGuard protocol implementation for establishing a WireGuard tunnel with a peer, converting received TCP and UDP packets into internal Xray proxy requests for processing and response.
|
||||
|
||||
::: danger
|
||||
**The WireGuard protocol is not designed specifically for bypassing firewalls. If used as the outer layer to cross the firewall, its distinct characteristics may lead to the server being blocked.**
|
||||
@@ -40,21 +40,11 @@ User-space WireGuard protocol implementation for establishing a WireGuard tunnel
|
||||
|
||||
Server private key. Required.
|
||||
|
||||
You can generate a server key pair with the `xray wg` command. Enter the generated `PrivateKey` here; the accompanying `Password (PublicKey)` is the server public key. When using Xray as a WireGuard client, enter the server public key in `outbounds[].settings.peers[].publicKey`.
|
||||
When generating a server key pair using the command `xray wg`, this corresponds to the output `PrivateKey`.
|
||||
|
||||
> `peers`: \[ [PeersObject](#peersobject) \]
|
||||
|
||||
List of WireGuard clients, where each item is a client configuration. When multiple clients are configured, Xray matches the source address of each decrypted inner IP packet against the clients' `allowedIPs` to identify which client the traffic belongs to.
|
||||
|
||||
::: details Network model of an Xray WireGuard inbound
|
||||
A conventional WireGuard network—including point-to-point, point-to-site, and site-to-site configurations—requires both endpoints to participate in IP routing through Layer 3 network interfaces.
|
||||
|
||||
In contrast, an Xray WireGuard inbound does not create a TUN interface on the system, nor does the server need an in-tunnel IP address. The built-in network stack processes the decrypted inner IP packets, converts their TCP and UDP traffic into proxy connections, and passes those connections to the Xray routing system instead of forwarding the original IP packets.
|
||||
|
||||
A client can send its own traffic or act as a gateway for networks behind it. The Xray server does not act as a Layer 3 node that clients can access inside the tunnel, and it does not pass the original IP packets to the system kernel for further forwarding or NAT.
|
||||
|
||||
`allowedIPs` participates in packet processing in both directions: when receiving packets, WireGuard verifies the source address of the decrypted inner IP packet and Xray uses that address to identify the client; when sending response packets, WireGuard selects the corresponding client based on the inner destination address.
|
||||
:::
|
||||
List of WireGuard client peers.
|
||||
|
||||
> `mtu`: int
|
||||
|
||||
@@ -93,7 +83,7 @@ The structure of a WireGuard packet is as follows:
|
||||
|
||||
Client public key used for verification. Required.
|
||||
|
||||
When using Xray as a WireGuard client, enter the `Password (PublicKey)` paired with the client's `outbounds[].settings.secretKey` here.
|
||||
When generating a key pair using `xray wg`, this corresponds to the output `Password (PublicKey)`.
|
||||
|
||||
> `preSharedKey`: string
|
||||
|
||||
@@ -105,13 +95,9 @@ Interval, in seconds, at which the server sends persistent keepalive packets to
|
||||
|
||||
> `allowedIPs`: \[ string \]
|
||||
|
||||
Specifies the source IP addresses or networks that this client is allowed to send, with each item expressed in CIDR notation.
|
||||
Specifies the source IP addresses or networks that this client is allowed to send, using CIDR notation. The default value is `["0.0.0.0/0", "::/0"]`, meaning all IPv4 and IPv6 source addresses are allowed.
|
||||
|
||||
The client's outbound `address` must be included in the corresponding server peer's `allowedIPs`. For example, if the client's `outbounds[].settings.address` is `["10.0.0.2"]`, this field can be set to `["10.0.0.2/32"]`.
|
||||
|
||||
`allowedIPs` can contain not only the client's in-tunnel IP address, but also networks routed through that peer. For example, if a third-party WireGuard client acts as a gateway for `192.168.10.0/24`, that network can be included here; the client must also configure routing and enable IP forwarding itself.
|
||||
|
||||
This field can be omitted when only one client is configured; the default is `["0.0.0.0/0", "::/0"]`. When multiple clients are configured, explicitly specify non-overlapping `allowedIPs`; otherwise, Xray cannot reliably distinguish between clients.
|
||||
Can be omitted when only one client is configured, with a default value of `["0.0.0.0/0", "::/0"]`. When configuring multiple clients, unlike the client-side `allowedIPs`, the `allowedIPs` here should not overlap; at best it prevents properly matching the client peer, and at worst it may prevent properly routing return packets.
|
||||
|
||||
> `email`: string
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# WireGuard
|
||||
|
||||
User-space WireGuard protocol implementation for establishing a WireGuard tunnel with a peer and sending outbound traffic through the tunnel.
|
||||
User-space WireGuard protocol implementation for establishing a WireGuard tunnel with a peer, encapsulating TCP/UDP requests routed to this outbound into IP packets and sending them through the WireGuard tunnel.
|
||||
|
||||
::: danger
|
||||
**The WireGuard protocol is not designed specifically for bypassing firewalls. If used as the outer layer to cross the firewall, its distinct characteristics may lead to the server being blocked.**
|
||||
@@ -16,20 +16,15 @@ User-space WireGuard protocol implementation for establishing a WireGuard tunnel
|
||||
{
|
||||
// ...
|
||||
"protocol": "wireguard",
|
||||
// [!code focus:25]
|
||||
// [!code focus:20]
|
||||
"settings": {
|
||||
"secretKey": "CLIENT_PRIVATE_KEY",
|
||||
"address": [
|
||||
"10.0.0.1",
|
||||
"fd59:7153:2388:b5fd:0000:0000:0000:0001",
|
||||
"and more..."
|
||||
],
|
||||
"address": ["10.0.0.1", "fd59:7153:2388:b5fd:0000:0000:0000:0001"],
|
||||
"peers": [
|
||||
{
|
||||
"endpoint": "SERVER_ADDR",
|
||||
"endpoint": "example.com:2408",
|
||||
"publicKey": "SERVER_PUBLIC_KEY",
|
||||
"allowedIPs": ["0.0.0.0/0", "::/0"]
|
||||
// ...
|
||||
}
|
||||
],
|
||||
"noKernelTun": false,
|
||||
@@ -51,28 +46,26 @@ User-space WireGuard protocol implementation for establishing a WireGuard tunnel
|
||||
|
||||
Client private key. Required.
|
||||
|
||||
You can generate a client key pair with the `xray wg` command. Enter the generated `PrivateKey` here; the accompanying `Password (PublicKey)` is the client public key. When using Xray as a WireGuard server, enter the client public key in `inbounds[].settings.peers[].publicKey`.
|
||||
When generating a client key pair using the command `xray wg`, this corresponds to the output `PrivateKey`.
|
||||
|
||||
> `address`: \[ string \]
|
||||
|
||||
Specifies the local source addresses used in the inner IP packets generated by the WireGuard outbound—that is, the client's in-tunnel IP addresses. One or more IPv4 or IPv6 addresses can be configured.
|
||||
List of local IP addresses for the WireGuard interface. When multiple addresses are specified, it is automatically selected based on the peer.
|
||||
|
||||
The default is `["10.0.0.1", "fd59:7153:2388:b5fd:0000:0000:0000:0001"]`.
|
||||
|
||||
Xray automatically selects a source address from the appropriate address family based on the destination address. If multiple addresses from the same family are configured, it selects a suitable address according to its internal rules.<br>
|
||||
The WireGuard server's inbound configuration must allow these addresses, and each address must be unique in the server's WireGuard inbound configuration.
|
||||
|
||||
> `noKernelTun`: true | false
|
||||
|
||||
Whether to disable TUN. The default is `false`; you may need to set it to `true` in LXC or Docker environments.
|
||||
Whether to forcibly disable system TUN regardless of automatic detection. The default is `false`; you may need to set it to `true` in LXC or Docker environments.
|
||||
|
||||
::: details Do I need to enable `noKernelTun`?
|
||||
When set to `false`, Xray automatically selects how to process inner IP packets: on Linux, if the Xray process has the `CAP_NET_ADMIN` capability, it creates a TUN interface and uses the kernel network stack; on other platforms or when permissions are insufficient, it uses the in-process gVisor network stack. When set to `true`, only the gVisor network stack is used and no TUN interface is created. Using TUN generally provides better performance.
|
||||
::: details About kernel TUN
|
||||
The way Xray restores WireGuard IP packets back into TCP/UDP payloads.
|
||||
By default, Xray automatically detects: on Linux, if the Xray process has the `CAP_NET_ADMIN` capability, it creates a TUN interface and uses the kernel network stack; on other platforms or when permissions are insufficient, it uses the in-process gVisor network stack. When set to `true`, only the gVisor network stack is used and no TUN interface is created. Using TUN generally provides better performance.
|
||||
|
||||
The automatic detection described above is not always accurate. For example, some LXC environments may be unable to use TUN even when they have the `CAP_NET_ADMIN` capability, causing the outbound to fail; in this case, setting `noKernelTun` to `true` solves the problem.
|
||||
|
||||
This option only selects how inner IP packets are processed. The WireGuard protocol itself is still handled by Xray's user-space implementation and is unrelated to the kernel WireGuard module.
|
||||
|
||||
The automatic detection described above is not always accurate. For example, some LXC environments may be unable to use TUN even when they have the `CAP_NET_ADMIN` capability, causing the outbound to fail. In this case, set this option to `true`.
|
||||
|
||||
When TUN is used, it occupies IPv6 routing table 10230. Each additional WireGuard outbound uses the next routing table in sequence; for example, the second one uses routing table 10231, and so on.
|
||||
|
||||
If a second Xray instance is started on the same machine, it does not continue allocating routing table numbers. Instead, it also tries to use routing table 10230. Because that table is already occupied by the first Xray instance, the second instance cannot connect. If multiple instances are necessary, use this option to disable TUN.
|
||||
@@ -104,43 +97,19 @@ The three WireGuard reserved bytes. All three default to 0; set them as needed.
|
||||
|
||||
> `peers`: \[ [PeersObject](#peersobject) \]
|
||||
|
||||
List of WireGuard servers, where each item is a server configuration. When multiple servers are configured, Xray prefix-matches the destination IP address against each server's `allowedIPs` and routes the traffic to the matching server, allowing different destination networks to be forwarded through different WireGuard servers.
|
||||
|
||||
::: details Packet model of an Xray WireGuard outbound
|
||||
TCP and UDP connections entering the WireGuard outbound are converted by the network stack into inner IP packets. The inner source address is selected from `address`, while the inner destination address is the destination IP of the proxied traffic.
|
||||
|
||||
Xray prefix-matches the inner destination address against each peer's `allowedIPs`. The matching peer encrypts and encapsulates the packet, and Xray sends the resulting outer UDP packet to that peer's `endpoint`. Therefore, `address` specifies the inner source addresses used by the client, `allowedIPs` acts as the destination routing table used to select a peer, and `endpoint` is the server address used by the outer connection.
|
||||
:::
|
||||
|
||||
::: tip
|
||||
Each WireGuard server must allow all addresses in `address` that belong to the same address family as its `allowedIPs`: if `allowedIPs` contains only IPv4 networks, allow all IPv4 addresses listed in `address`; if it contains only IPv6 networks, the same rule applies to the IPv6 addresses; if it contains both IPv4 and IPv6 networks, allow all listed addresses.
|
||||
|
||||
When using Xray as the WireGuard server, list these addresses in `inbounds[].settings.peers[].allowedIPs`.
|
||||
:::
|
||||
List of remote WireGuard peers to connect to.
|
||||
|
||||
> `remoteDNS`: \[ string \]
|
||||
|
||||
Used to resolve proxied target domain names. Each item must be an IP address. The default is `["1.1.1.1", "1.0.0.1", "2606:4700:4700::1111", "2606:4700:4700::1001"]`.
|
||||
|
||||
DNS queries are sent through the WireGuard tunnel; every server IP must be included in a peer's `allowedIPs` and reachable through the tunnel.
|
||||
|
||||
::: details `remoteDNS` and `targetStrategy`
|
||||
Unlike other outbounds, targets inside a WireGuard tunnel must be IP addresses. When the proxied target is a domain name, the outbound's [`targetStrategy`](../outbound.md#outboundobject) determines which DNS is used to resolve it:
|
||||
|
||||
- `AsIs`: uses `remoteDNS`.
|
||||
- `UseIP*`: tries Xray's built-in DNS first and falls back to `remoteDNS` if resolution fails.
|
||||
- `ForceIP*`: uses Xray's built-in DNS and fails immediately if resolution fails.
|
||||
|
||||
The results returned by `UseIP*` or `ForceIP*` must contain at least one IP whose address family matches an address in `address`; otherwise, the connection fails. An address-family mismatch is not treated as a resolution failure and does not trigger any fallback.
|
||||
|
||||
Which should you choose? `remoteDNS` works out of the box and sends queries through the WireGuard tunnel, usually producing CDN resolution results suited to the tunnel's exit location. Achieving the same result with [Xray's built-in DNS](../dns.md) usually requires additional DNS server and routing rules. However, if the built-in DNS resolved the target domain earlier—for example, when using a RealIP setup with TUN/TProxy, or when sniffing is enabled and `routing.domainStrategy` is not `AsIs`—using Xray's built-in DNS is recommended to avoid the additional RTT of a second resolution.
|
||||
:::
|
||||
Unlike other outbounds, targets inside a WireGuard tunnel must be IP addresses. When a proxied target is a domain name, a DNS server is required to convert the domain name into an IP address. These DNS servers are configured here and **send DNS requests directly through this WireGuard tunnel**. If you wish to integrate this with Xray's built-in DNS system, consider resolving in advance via the outbound's [`targetStrategy`](../outbound.md#outboundobject).
|
||||
|
||||
### PeersObject
|
||||
|
||||
```json
|
||||
{
|
||||
"endpoint": "SERVER_ADDR",
|
||||
"endpoint": "example.com:2408",
|
||||
"publicKey": "SERVER_PUBLIC_KEY",
|
||||
"preSharedKey": "PRE_SHARED_KEY",
|
||||
"keepAlive": 0,
|
||||
@@ -150,16 +119,13 @@ Which should you choose? `remoteDNS` works out of the box and sends queries thro
|
||||
|
||||
> `endpoint`: address
|
||||
|
||||
Server address. Required.
|
||||
|
||||
URL:Port format, for example, `engage.cloudflareclient.com:2408`<br>
|
||||
IP:Port format, for example, `162.159.192.1:2408` or `[2606:4700:d0::a29f:c001]:2408`
|
||||
Server address and port, can be an IP or a domain name. Required.
|
||||
|
||||
> `publicKey`: string
|
||||
|
||||
Server public key used for verification. Required.
|
||||
Peer public key used for verification. Required.
|
||||
|
||||
When using Xray as a WireGuard server, enter the `Password (PublicKey)` paired with the server's `inbounds[].settings.secretKey` here.
|
||||
When generating a key pair using `xray wg`, this corresponds to the output `Password (PublicKey)`.
|
||||
|
||||
> `preSharedKey`: string
|
||||
|
||||
@@ -171,4 +137,4 @@ Interval, in seconds, at which the client sends persistent keepalive packets to
|
||||
|
||||
> `allowedIPs`: \[ string \]
|
||||
|
||||
Specifies the destination IP networks forwarded by this server, with each item expressed in CIDR notation. This field can be omitted when only one server is configured because the default is `["0.0.0.0/0", "::/0"]`, meaning that the server forwards all IPv4 and IPv6 destination traffic. When multiple servers are configured, explicitly set `allowedIPs` for each server to assign different destination networks to the appropriate server; Xray selects the server by prefix-matching the destination IP address.
|
||||
Requests that should be forwarded using this peer, represented in CIDR notation. The default value is `["0.0.0.0/0", "::/0"]`, meaning all IPv4 and IPv6 destination traffic is forwarded by this server. When multiple peers match, the longest prefix match rule is used.
|
||||
|
||||
Reference in New Issue
Block a user