black-internet-days-ahead/sing-box
1
0
Fork 0
mirror of https://github.com/SagerNet/sing-box.git synced 2024-11-25 10:01:30 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update documentation

Browse source
This commit is contained in:
世界 2022-08-23 23:15:56 +08:00
parent 88469d4aaa
commit 22aa0c2f40
No known key found for this signature in database
GPG key ID: CD109927C34A63C4
26 changed files with 452 additions and 243 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

9
docs/changelog.md
View file

@ -1,3 +1,12 @@
#### 2022/08/23
* Add [V2Ray Transport](/configuration/shared/v2ray-transport) support for VMess and Trojan
* Allow plain http request in Naive inbound (It can now be used with nginx)
* Add proxy protocol support
* Free memory after start
* Parse X-Forward-For in HTTP requests
* Handle SIGHUP signal
#### 2022/08/22
* Add strategy setting for each [DNS server](/configuration/dns/server)

2
docs/configuration/dns/server.md
View file

@ -47,7 +47,7 @@ The address of the dns server.
!!! warning ""
QUIC and HTTP3 transport is not included by default, see [Installation](/#Installation).
QUIC and HTTP3 transport is not included by default, see [Installation](/#installation).
!!! info ""

2
docs/configuration/experimental.md
View file

@ -16,7 +16,7 @@
!!! error ""
Clash API is not included by default, see [Installation](/#Installation).
Clash API is not included by default, see [Installation](/#installation).
!!! note ""

35
docs/configuration/inbound/direct.md
View file

@ -8,7 +8,6 @@
{
"type": "direct",
"tag": "direct-in",
"listen": "::",
"listen_port": 5353,
"tcp_fast_open": false,
@ -16,8 +15,8 @@
"sniff_override_destination": false,
"domain_strategy": "prefer_ipv6",
"udp_timeout": 300,
"network": "udp",
"proxy_protocol": false,
"override_address": "1.0.0.1",
"override_port": 53
}
@ -25,6 +24,22 @@
}
```
### Direct Fields
#### network
Listen network, one of `tcp` `udp`.
Both if empty.
#### override_address
Override the connection destination address.
#### override_port
Override the connection destination port.
### Listen Fields
#### listen
@ -67,18 +82,6 @@ If `sniff_override_destination` is in effect, its value will be taken as a fallb
UDP NAT expiration time in seconds, default is 300 (5 minutes).
### Direct Fields
#### proxy_protocol
#### network
Listen network, one of `tcp` `udp`.
Both if empty.
#### override_address
Override the connection destination address.
#### override_port
Override the connection destination port.
Parse [Proxy Protocol](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt) in the connection header.

43
docs/configuration/inbound/http.md
View file

@ -1,5 +1,3 @@
`socks` inbound is a http server.
### Structure
```json
@ -15,6 +13,7 @@
"sniff": false,
"sniff_override_destination": false,
"domain_strategy": "prefer_ipv6",
"proxy_protocol": false,
"users": [
{
@ -29,6 +28,26 @@
}
```
### HTTP Fields
#### tls
TLS configuration, see [TLS inbound structure](/configuration/shared/tls/#inbound-structure).
#### users
HTTP users.
No authentication required if empty.
#### set_system_proxy
!!! error ""
Only supported on Linux, Android, Windows, and macOS.
Automatically set system proxy configuration when start and clean up when stop.
### Listen Fields
#### listen
@ -67,22 +86,6 @@ If set, the requested domain name will be resolved to IP before routing.
If `sniff_override_destination` is in effect, its value will be taken as a fallback.
#### set_system_proxy
#### proxy_protocol
!!! error ""
Only supported on Linux, Android, Windows, and macOS.
Automatically set system proxy configuration when start and clean up when stop.
### HTTP Fields
#### tls
TLS configuration, see [TLS inbound structure](/configuration/shared/tls/#inbound-structure).
#### users
HTTP users.
No authentication required if empty.
Parse [Proxy Protocol](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt) in the connection header.

75
docs/configuration/inbound/hysteria.md
View file

@ -6,13 +6,11 @@
{
"type": "hysteria",
"tag": "hysteria-in",
"listen": "::",
"listen_port": 443,
"sniff": false,
"sniff_override_destination": false,
"domain_strategy": "prefer_ipv6",
"up": "100 Mbps",
"up_mbps": 100,
"down": "100 Mbps",
@ -32,41 +30,7 @@
!!! warning ""
QUIC, which is required by hysteria is not included by default, see [Installation](/#Installation).
### Listen Fields
#### listen
==Required==
Listen address.
#### listen_port
==Required==
Listen port.
#### sniff
Enable sniffing.
See [Sniff](/configuration/route/sniff/) for details.
#### sniff_override_destination
Override the connection destination address with the sniffed domain.
If the domain name is invalid (like tor), this will not work.
#### domain_strategy
One of `prefer_ipv4` `prefer_ipv6` `ipv4_only` `ipv6_only`.
If set, the requested domain name will be resolved to IP before routing.
If `sniff_override_destination` is in effect, its value will be taken as a fallback.
QUIC, which is required by hysteria is not included by default, see [Installation](/#installation).
### Hysteria Fields
@ -87,7 +51,8 @@ Supported units (case sensitive, b = bits, B = bytes, 8b=1B):
Gbps (gigabits per second)
GBps (gigabytes per second)
Tbps (terabits per second)
TBps (terabytes per second)
TBps (terabytes per`socks` inbound is a http server.
second)
#### up_mbps, down_mbps
@ -136,3 +101,37 @@ Force enabled on for systems other than Linux and Windows (according to upstream
==Required==
TLS configuration, see [TLS inbound structure](/configuration/shared/tls/#inbound-structure).
### Listen Fields
#### listen
==Required==
Listen address.
#### listen_port
==Required==
Listen port.
#### sniff
Enable sniffing.
See [Sniff](/configuration/route/sniff/) for details.
#### sniff_override_destination
Override the connection destination address with the sniffed domain.
If the domain name is invalid (like tor), this will not work.
#### domain_strategy
One of `prefer_ipv4` `prefer_ipv6` `ipv4_only` `ipv6_only`.
If set, the requested domain name will be resolved to IP before routing.
If `sniff_override_destination` is in effect, its value will be taken as a fallback.

26
docs/configuration/inbound/mixed.md
View file

@ -15,6 +15,7 @@
"sniff": false,
"sniff_override_destination": false,
"domain_strategy": "prefer_ipv6",
"proxy_protocol": false,
"users": [
{
@ -22,13 +23,28 @@
"password": "admin"
}
],
"set_system_proxy": false
}
]
}
```
### Mixed Fields
#### users
SOCKS and HTTP users.
No authentication required if empty.
#### set_system_proxy
!!! error ""
Only supported on Linux, Android, Windows, and macOS.
Automatically set system proxy configuration when start and clean up when stop.
### Listen Fields
#### listen
@ -74,11 +90,3 @@ If `sniff_override_destination` is in effect, its value will be taken as a fallb
Only supported on Linux, Android, Windows, and macOS.
Automatically set system proxy configuration when start and clean up when stop.
### Mixed Fields
#### users
Socks and HTTP users.
No authentication required if empty.

41
docs/configuration/inbound/naive.md
View file

@ -13,6 +13,7 @@
"sniff": false,
"sniff_override_destination": false,
"domain_strategy": "prefer_ipv6",
"proxy_protocol": false,
"network": "udp",
"users": [
@ -29,7 +30,25 @@
!!! warning ""
HTTP3 transport is not included by default, see [Installation](/#Installation).
HTTP3 transport is not included by default, see [Installation](/#installation).
### Naive Fields
#### tls
TLS configuration, see [TLS inbound structure](/configuration/shared/tls/#inbound-structure).
#### users
==Required==
Naive users.
#### network
Listen network, one of `tcp` `udp`.
Both if empty.
### Listen Fields
@ -69,22 +88,6 @@ If set, the requested domain name will be resolved to IP before routing.
If `sniff_override_destination` is in effect, its value will be taken as a fallback.
### Naive Fields
#### proxy_protocol
#### tls
==Required==
TLS configuration, see [TLS inbound structure](/configuration/shared/tls/#inbound-structure).
#### users
==Required==
Naive users.
#### network
Listen network, one of `tcp` `udp`.
Both if empty.
Parse [Proxy Protocol](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt) in the connection header.

2
docs/configuration/inbound/redirect.md
View file

@ -1,4 +1,4 @@
`redirect` inbound is a linux redirect server.
`redirect` inbound is a Linux redirect server.
### Structure

153
docs/configuration/inbound/shadowsocks.md
View file

@ -15,6 +15,7 @@
"domain_strategy": "prefer_ipv6",
"udp_timeout": 300,
"network": "udp",
"proxy_protocol": false,
"method": "2022-blake3-aes-128-gcm",
"password": "8JCsPssfgS8tiRwiMlhARg=="
@ -23,6 +24,82 @@
}
```
### Multi-User Structure
```json
{
"inbounds": [
{
"type": "shadowsocks",
"method": "2022-blake3-aes-128-gcm",
"password": "8JCsPssfgS8tiRwiMlhARg==",
"users": [
{
"name": "sekai",
"password": "PCD2Z4o12bKUoFa3cC97Hw=="
}
]
}
]
}
```
### Relay Structure
```json
{
"inbounds": [
{
"type": "shadowsocks",
"method": "2022-blake3-aes-128-gcm",
"password": "8JCsPssfgS8tiRwiMlhARg==",
"destinations": [
{
"name": "test",
"server": "example.com",
"server_port": 8080,
"password": "PCD2Z4o12bKUoFa3cC97Hw=="
}
]
}
]
}
```
### Shadowsocks Fields
#### network
Listen network, one of `tcp` `udp`.
Both if empty.
#### method
==Required==
| Method | Key Length |
|-------------------------------|------------|
| 2022-blake3-aes-128-gcm | 16 |
| 2022-blake3-aes-256-gcm | 32 |
| 2022-blake3-chacha20-poly1305 | 32 |
| none | / |
| aes-128-gcm | / |
| aes-192-gcm | / |
| aes-256-gcm | / |
| chacha20-ietf-poly1305 | / |
| xchacha20-ietf-poly1305 | / |
#### password
==Required==
| Method | Password Format |
|---------------|-------------------------------------|
| none | / |
| 2022 methods | `openssl rand -base64 <Key Length>` |
| other methods | any string |
### Listen Fields
#### listen
@ -65,78 +142,6 @@ If `sniff_override_destination` is in effect, its value will be taken as a fallb
UDP NAT expiration time in seconds, default is 300 (5 minutes).
### Shadowsocks Fields
#### proxy_protocol
#### network
Listen network, one of `tcp` `udp`.
Both if empty.
#### method
==Required==
| Method | Key Length |
|-------------------------------|------------|
| 2022-blake3-aes-128-gcm | 16 |
| 2022-blake3-aes-256-gcm | 32 |
| 2022-blake3-chacha20-poly1305 | 32 |
| none | / |
| aes-128-gcm | / |
| aes-192-gcm | / |
| aes-256-gcm | / |
| chacha20-ietf-poly1305 | / |
| xchacha20-ietf-poly1305 | / |
#### password
==Required==
| Method | Password Format |
|---------------|-------------------------------------|
| none | / |
| 2022 methods | `openssl rand -base64 <Key Length>` |
| other methods | any string |
### Multi-User Structure
```json
{
"inbounds": [
{
"type": "shadowsocks",
"method": "2022-blake3-aes-128-gcm",
"password": "8JCsPssfgS8tiRwiMlhARg==",
"users": [
{
"name": "sekai",
"password": "PCD2Z4o12bKUoFa3cC97Hw=="
}
]
}
]
}
```
### Relay Structure
```json
{
"inbounds": [
{
"type": "shadowsocks",
"method": "2022-blake3-aes-128-gcm",
"password": "8JCsPssfgS8tiRwiMlhARg==",
"destinations": [
{
"name": "test",
"server": "example.com",
"server_port": 8080,
"password": "PCD2Z4o12bKUoFa3cC97Hw=="
}
]
}
]
}
```
Parse [Proxy Protocol](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt) in the connection header.

17
docs/configuration/inbound/socks.md
View file

@ -15,6 +15,7 @@
"sniff": false,
"sniff_override_destination": false,
"domain_strategy": "prefer_ipv6",
"proxy_protocol": false,
"users": [
{
@ -27,6 +28,14 @@
}
```
### Socks Fields
#### users
SOCKS users.
No authentication required if empty.
### Listen Fields
#### listen
@ -65,10 +74,6 @@ If set, the requested domain name will be resolved to IP before routing.
If `sniff_override_destination` is in effect, its value will be taken as a fallback.
### Socks Fields
#### proxy_protocol
#### users
Socks users.
No authentication required if empty.
Parse [Proxy Protocol](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt) in the connection header.

16
docs/configuration/inbound/tproxy.md
View file

@ -20,6 +20,14 @@
}
```
### TProxy Fields
#### network
Listen network, one of `tcp` `udp`.
Both if empty.
### Listen Fields
#### listen
@ -57,11 +65,3 @@ If `sniff_override_destination` is in effect, its value will be taken as a fallb
#### udp_timeout
UDP NAT expiration time in seconds, default is 300 (5 minutes).
### TProxy Fields
#### network
Listen network, one of `tcp` `udp`.
Both if empty.

44
docs/configuration/inbound/trojan.md
View file

@ -13,6 +13,7 @@
"sniff": false,
"sniff_override_destination": false,
"domain_strategy": "prefer_ipv6",
"proxy_protocol": false,
"users": [
{
@ -24,12 +25,35 @@
"fallback": {
"server": "127.0.0.0.1",
"server_port": 8080
}
},
"transport": {}
}
]
}
```
### Trojan Fields
#### users
Trojan users.
#### tls
TLS configuration, see [TLS inbound structure](/configuration/shared/tls/#inbound-structure).
#### fallback
!!! error ""
There is no evidence that GFW detects and blocks Trojan servers based on HTTP responses, and opening the standard http/s port on the server is a much bigger signature.
Fallback server configuration. Disabled if empty.
#### transport
V2Ray Transport configuration, see [V2Ray Transport](/configuration/shared/v2ray-transport).
### Listen Fields
#### listen
@ -68,20 +92,6 @@ If set, the requested domain name will be resolved to IP before routing.
If `sniff_override_destination` is in effect, its value will be taken as a fallback.
### Trojan Fields
#### proxy_protocol
#### users
Trojan users.
#### tls
TLS configuration, see [TLS inbound structure](/configuration/shared/tls/#inbound-structure).
#### fallback
!!! error ""
There is no evidence that GFW detects and blocks Trojan servers based on HTTP responses, and opening the standard http/s port on the server is a much bigger signature.
Fallback server configuration. Disabled if empty.
Parse [Proxy Protocol](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt) in the connection header.

2
docs/configuration/inbound/tun.md
View file

@ -107,7 +107,7 @@ TCP/IP stack.
!!! warning ""
The LWIP stack is not included by default, see [Installation](/#Installation).
The LWIP stack is not included by default, see [Installation](/#installation).
#### include_uid

46
docs/configuration/inbound/vmess.md
View file

@ -13,6 +13,7 @@
"sniff": false,
"sniff_override_destination": false,
"domain_strategy": "prefer_ipv6",
"proxy_protocol": false,
"users": [
{
@ -21,12 +22,36 @@
"alterId": 0
}
],
"tls": {}
"tls": {},
"transport": {}
}
]
}
```
### VMess Fields
#### users
VMess users.
| Alter ID | Description |
|----------|-------------------------|
| 0 | Disable legacy protocol |
| > 0 | Enable legacy protocol |
!!! warning ""
Legacy protocol support (VMess MD5 Authentication) is provided for compatibility purposes only, use of alterId > 1 is not recommended.
#### tls
TLS configuration, see [TLS inbound structure](/configuration/shared/tls/#inbound-structure).
#### transport
V2Ray Transport configuration, see [V2Ray Transport](/configuration/shared/v2ray-transport).
### Listen Fields
#### listen
@ -65,21 +90,6 @@ If set, the requested domain name will be resolved to IP before routing.
If `sniff_override_destination` is in effect, its value will be taken as a fallback.
### VMess Fields
#### proxy_protocol
#### users
VMess users.
| Alter ID | Description |
|----------|-------------------------|
| 0 | Disable legacy protocol |
| > 0 | Enable legacy protocol |
!!! warning ""
Legacy protocol support (VMess MD5 Authentication) is provided for compatibility purposes only, use of alterId > 1 is not recommended.
#### tls
TLS configuration, see [TLS inbound structure](/configuration/shared/tls/#inbound-structure).
Parse [Proxy Protocol](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt) in the connection header.

7
docs/configuration/outbound/direct.md
View file

@ -11,6 +11,7 @@
"override_address": "1.0.0.1",
"override_port": 53,
"proxy_protocol": 0,
"detour": "upstream-out",
"bind_interface": "en0",
@ -36,6 +37,12 @@ Override the connection destination address.
Override the connection destination port.
#### proxy_protocol
Write [Proxy Protocol](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt) in the connection header.
Protocol value can be `1` or `2`.
### Dial Fields
#### detour

2
docs/configuration/outbound/hysteria.md
View file

@ -38,7 +38,7 @@
!!! warning ""
QUIC, which is required by hysteria is not included by default, see [Installation](/#Installation).
QUIC, which is required by hysteria is not included by default, see [Installation](/#installation).
### Hysteria Fields

2
docs/configuration/outbound/tor.md
View file

@ -30,7 +30,7 @@
!!! info ""
Embedded tor is not included by default, see [Installation](/#Installation).
Embedded tor is not included by default, see [Installation](/#installation).
### Tor Fields

5
docs/configuration/outbound/trojan.md
View file

@ -13,6 +13,7 @@
"network": "tcp",
"tls": {},
"multiplex": {},
"transport": {},
"detour": "upstream-out",
"bind_interface": "en0",
@ -64,6 +65,10 @@ TLS configuration, see [TLS outbound structure](/configuration/shared/tls/#outbo
Multiplex configuration, see [Multiplex structure](/configuration/shared/multiplex).
#### transport
V2Ray Transport configuration, see [V2Ray Transport](/configuration/shared/v2ray-transport).
### Dial Fields
#### detour

5
docs/configuration/outbound/vmess.md
View file

@ -17,6 +17,7 @@
"network": "tcp",
"tls": {},
"multiplex": {},
"transport": {},
"detour": "upstream-out",
"bind_interface": "en0",
@ -98,6 +99,10 @@ TLS configuration, see [TLS outbound structure](/configuration/shared/tls/#outbo
Multiplex configuration, see [Multiplex structure](/configuration/shared/multiplex).
#### transport
V2Ray Transport configuration, see [V2Ray Transport](/configuration/shared/v2ray-transport).
### Dial Fields
#### detour

2
docs/configuration/outbound/wireguard.md
View file

@ -35,7 +35,7 @@
!!! warning ""
WireGuard is not included by default, see [Installation](/#Installation).
WireGuard is not included by default, see [Installation](/#installation).
### WireGuard Fields

5
docs/configuration/shared/tls.md
View file

@ -28,7 +28,7 @@
!!! warning ""
ACME is not included by default, see [Installation](/#Installation).
ACME is not included by default, see [Installation](/#installation).
### Outbound Structure
@ -41,7 +41,6 @@
"min_version": "",
"max_version": "",
"cipher_suites": [],
"disable_system_root": false,
"certificate": "",
"certificate_path": ""
}
@ -182,7 +181,7 @@ The ACME CA provider to use.
| Value | Provider |
|-------------------------|---------------|
| `letsenctypt (default)` | Let's Encrypt |
| `letsencrypt (default)` | Let's Encrypt |
| `zerossl` | ZeroSSL |
| `https://...` | Custom |

131
docs/configuration/shared/v2ray-transport.md Normal file
View file

@ -0,0 +1,131 @@
V2Ray Transport is a set of private protocols invented by v2ray, and has contaminated the names of other protocols, such
as `trojan-grpc` in clash.
### Structure
```json
{
"type": ""
}
```
Available transports:
* HTTP
* WebSocket
* QUIC
* gRPC
!!! warning "Difference from v2ray-core"
* No TCP transport, plain HTTP is merged into the HTTP transport.
* No mKCP transport.
* No DomainSocket transport.
!!! note
You can ignore the JSON Array [] tag when the content is only one item
### HTTP
```json
{
"type": "http",
"host": [],
"path": "",
"method": "",
"headers": {}
}
```
!!! warning "Difference from v2ray-core"
TLS is not enforced. If TLS is not configured, plain HTTP 1.1 is used.
#### host
List of host domain.
The client will choose randomly and the server will verify if not empty.
#### path
Path of HTTP request.
The server will verify if not empty.
#### method
Method of HTTP request.
The server will verify if not empty.
#### headers
Extra headers of HTTP request.
The server will write in response if not empty.
### WebSocket
```json
{
"type": "ws",
"path": "",
"headers": {},
"max_early_data": 0,
"early_data_header_name": ""
}
```
#### path
Path of HTTP request.
The server will verify if not empty.
#### headers
Extra headers of HTTP request.
#### max_early_data
Allowed payload size is in the request. Enabled if not zero.
#### early_data_header_name
Early data is sent in path instead of header by default.
To be compatible with Xray-core, set this to `Sec-WebSocket-Protocol`.
It needs to be consistent with the server.
### QUIC
```json
{
"type": "quic"
}
```
!!! warning "Difference from v2ray-core"
No additional encryption support:
It's basically duplicate encryption. And Xray-core is not compatible with v2ray-core in here.
### gRPC
!!! warning ""
gRPC is not included by default, see [Installation](/#installation).
```json
{
"type": "grpc",
"service_name": "TunService"
}
```
#### service_name
Service name of gRPC.

7
docs/faq/known-issues.md
View file

@ -2,12 +2,17 @@
##### on macOS
`auto-route` cannot automatically hijack DNS requests sent to the LAN, so it's need to manually set DNS to servers on the public internet.
`auto-route` cannot automatically hijack DNS requests sent to the LAN, so it's need to manually set DNS to servers on
the public internet.
##### on Android
`auto-route` cannot automatically hijack DNS requests when Android's `Private DNS` is enabled.
##### on Linux
`auto-route` cannot automatically hijack DNS requests with `systemd-resoled` enabled, you can switch to NetworkManager.
#### System proxy
##### on Linux

1
docs/index.md
View file

@ -21,6 +21,7 @@ go install -v -tags with_clash_api github.com/sagernet/sing-box/cmd/sing-box@lat
| Build Tag | Description |
|------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `with_quic` | Build with QUIC support, see [QUIC and HTTP3 dns transports](./configuration/dns/server), [Naive inbound](./configuration/inbound/naive), [Hysteria Inbound](./configuration/inbound/hysteria) and [Hysteria Outbound](./configuration/outbound/hysteria). |
| `with_grpc` | Build with gRPC support, see [V2Ray Transport#gRPC](/configuration/shared/v2ray-transport#grpc). |
| `with_wireguard` | Build with WireGuard support, see [WireGuard outbound](./configuration/outbound/wireguard). |
| `with_acme` | Build with ACME TLS certificate issuer support, see [TLS](./configuration/shared/tls). |
| `with_clash_api` | Build with Clash api support, see [Experimental](./configuration/experimental#clash-api-fields). |

1
mkdocs.yml
View file

@ -81,6 +81,7 @@ nav:
- Shared:
- TLS: configuration/shared/tls.md
- Multiplex: configuration/shared/multiplex.md
- V2Ray Transport: configuration/shared/v2ray-transport.md
- FAQ:
- faq/index.md
- Known Issues: faq/known-issues.md