yanistyle/sing-box-extended
1
0
Fork 0
mirror of https://github.com/shtorm-7/sing-box-extended.git synced 2026-06-12 06:18:16 +03:00
Code Issues Packages Projects Releases Wiki Activity

documentation: Bump version & Refactor docs

Browse Source
This commit is contained in:
世界
2023-11-09 17:04:08 +08:00
parent 18dfbd1cef
commit 3c5f658863
105 changed files with 2061 additions and 1767 deletions
Download Patch File Download Diff File Expand all files Collapse all files

211
docs/manual/proxy-protocol/hysteria2.md Normal file
View File

@@ -0,0 +1,211 @@
---
icon: material/lightning-bolt
---
# Hysteria 2
The most popular Chinese-made simple protocol based on QUIC, the selling point is Brutal,
a congestion control algorithm that can resist packet loss by manually specifying the required rate by the user.
!!! warning
Even though GFW rarely blocks UDP-based proxies, such protocols actually have far more characteristics than TCP based proxies.
| Specification | Binary Characteristics | Active Detect Hiddenness |
|---------------------------------------------------------------------------|------------------------|--------------------------|
| [hysteria.network](https://v2.hysteria.network/docs/developers/Protocol/) | :material-alert: | :material-check: |
## :material-text-box-check: Password Generator
| Generate Password | Action |
|----------------------------|-----------------------------------------------------------------|
| <code id="password"><code> | <button class="md-button" onclick="generate()">Refresh</button> |
<script>
function generate() {
const array = new Uint8Array(16);
window.crypto.getRandomValues(array);
document.getElementById("password").textContent = btoa(String.fromCharCode.apply(null, array));
}
generate();
</script>
## :material-alert: Difference from official Hysteria
The official program supports an authentication method called **userpass**,
which essentially uses a combination of `<username>:<password>` as the actual password,
while sing-box does not provide this alias.
To use sing-box with the official program, you need to fill in that combination as the actual password.
## :material-server: Server Example
!!! info ""
Replace `up_mbps` and `down_mbps` values with the actual bandwidth of your server.
=== ":material-harddisk: With local certificate"
```json
{
"inbounds": [
{
"type": "hysteria2",
"listen": "::",
"listen_port": 8080,
"up_mbps": 100,
"down_mbps": 100,
"users": [
{
"name": "sekai",
"password": "<password>"
}
],
"tls": {
"enabled": true,
"server_name": "example.org",
"key_path": "/path/to/key.pem",
"certificate_path": "/path/to/certificate.pem"
}
}
]
}
```
=== ":material-auto-fix: With ACME"
```json
{
"inbounds": [
{
"type": "hysteria2",
"listen": "::",
"listen_port": 8080,
"up_mbps": 100,
"down_mbps": 100,
"users": [
{
"name": "sekai",
"password": "<password>"
}
],
"tls": {
"enabled": true,
"server_name": "example.org",
"acme": {
"domain": "example.org",
"email": "admin@example.org"
}
}
}
]
}
```
=== ":material-cloud: With ACME and Cloudflare API"
```json
{
"inbounds": [
{
"type": "hysteria2",
"listen": "::",
"listen_port": 8080,
"up_mbps": 100,
"down_mbps": 100,
"users": [
{
"name": "sekai",
"password": "<password>"
}
],
"tls": {
"enabled": true,
"server_name": "example.org",
"acme": {
"domain": "example.org",
"email": "admin@example.org",
"dns01_challenge": {
"provider": "cloudflare",
"api_token": "my_token"
}
}
}
}
]
}
```
## :material-cellphone-link: Client Example
!!! info ""
Replace `up_mbps` and `down_mbps` values with the actual bandwidth of your client.
=== ":material-web-check: With valid certificate"
```json
{
"outbounds": [
{
"type": "hysteria2",
"server": "127.0.0.1",
"server_port": 8080,
"up_mbps": 100,
"down_mbps": 100,
"password": "<password>",
"tls": {
"enabled": true,
"server_name": "example.org"
}
}
]
}
```
=== ":material-check: With self-sign certificate"
!!! info "Tip"
Use `sing-box merge` command to merge configuration and certificate into one file.
```json
{
"outbounds": [
{
"type": "hysteria2",
"server": "127.0.0.1",
"server_port": 8080,
"up_mbps": 100,
"down_mbps": 100,
"password": "<password>",
"tls": {
"enabled": true,
"server_name": "example.org",
"certificate_path": "/path/to/certificate.pem"
}
}
]
}
```
=== ":material-alert: Ignore certificate verification"
```json
{
"outbounds": [
{
"type": "hysteria2",
"server": "127.0.0.1",
"server_port": 8080,
"up_mbps": 100,
"down_mbps": 100,
"password": "<password>",
"tls": {
"enabled": true,
"server_name": "example.org",
"insecure": true
}
}
]
}
```

126
docs/manual/proxy-protocol/shadowsocks.md Normal file
View File

@@ -0,0 +1,126 @@
---
icon: material/send
---
# Shadowsocks
As the most well-known Chinese-made proxy protocol,
Shadowsocks exists in multiple versions,
but only AEAD 2022 ciphers TCP with multiplexing is recommended.
| Ciphers | Specification | Cryptographic Security | Binary Characteristics | Active Detect Hiddenness |
|----------------|------------------------------------------------------------|------------------------|------------------------|--------------------------|
| Stream Ciphers | [shadowsocks.org](https://shadowsocks.org/doc/stream.html) | :material-alert: | :material-alert: | :material-alert: |
| AEAD | [shadowsocks.org](https://shadowsocks.org/doc/aead.html) | :material-check: | :material-alert: | :material-alert: |
| AEAD 2022 | [shadowsocks.org](https://shadowsocks.org/doc/sip022.html) | :material-check: | :material-check: | :material-help: |
## :material-text-box-check: Password Generator
| For `2022-blake3-aes-128-gcm` cipher | For other ciphers | Action |
|--------------------------------------|-------------------------------|-----------------------------------------------------------------|
| <code id="password_16"><code> | <code id="password_32"><code> | <button class="md-button" onclick="generate()">Refresh</button> |
<script>
function generatePassword(element, length) {
const array = new Uint8Array(length);
window.crypto.getRandomValues(array);
document.getElementById(element).textContent = btoa(String.fromCharCode.apply(null, array));
}
function generate() {
generatePassword("password_16", 16);
generatePassword("password_32", 32);
}
generate();
</script>
## :material-server: Server Example
!!! info ""
Password of cipher `2022-blake3-aes-128-gcm` can be generated by command `sing-box generate rand 16 --base64`
=== ":material-account: Single-user"
```json
{
"inbounds": [
{
"type": "shadowsocks",
"listen": "::",
"listen_port": 8080,
"network": "tcp",
"method": "2022-blake3-aes-128-gcm",
"password": "<password>",
"multiplex": {
"enabled": true
}
}
]
}
```
=== ":material-account-multiple: Multi-user"
```json
{
"inbounds": [
{
"type": "shadowsocks",
"listen": "::",
"listen_port": 8080,
"network": "tcp",
"method": "2022-blake3-aes-128-gcm",
"password": "<server_password>",
"users": [
{
"name": "sekai",
"password": "<user_password>"
}
],
"multiplex": {
"enabled": true
}
}
]
}
```
## :material-cellphone-link: Client Example
=== ":material-account: Single-user"
```json
{
"outbounds": [
{
"type": "shadowsocks",
"server": "127.0.0.1",
"server_port": 8080,
"method": "2022-blake3-aes-128-gcm",
"password": "<pasword>",
"multiplex": {
"enabled": true
}
}
]
}
```
=== ":material-account-multiple: Multi-user"
```json
{
"outbounds": [
{
"type": "shadowsocks",
"server": "127.0.0.1",
"server_port": 8080,
"method": "2022-blake3-aes-128-gcm",
"password": "<server_pasword>:<user_password>",
"multiplex": {
"enabled": true
}
}
]
}
```

214
docs/manual/proxy-protocol/trojan.md Normal file
View File

@@ -0,0 +1,214 @@
---
icon: material/horse
---
# Trojan
As the most commonly used TLS proxy made in China, Trojan can be used in various combinations,
but only the combination of uTLS and multiplexing is recommended.
| Protocol and implementation combination | Specification | Binary Characteristics | Active Detect Hiddenness |
|-----------------------------------------|----------------------------------------------------------------------|------------------------|--------------------------|
| Origin / trojan-gfw | [trojan-gfw.github.io](https://trojan-gfw.github.io/trojan/protocol) | :material-check: | :material-check: |
| Basic Go implementation | / | :material-alert: | :material-check: |
| with privates transport by V2Ray | No formal definition | :material-alert: | :material-alert: |
| with uTLS enabled | No formal definition | :material-help: | :material-check: |
## :material-text-box-check: Password Generator
| Generate Password | Action |
|----------------------------|-----------------------------------------------------------------|
| <code id="password"><code> | <button class="md-button" onclick="generate()">Refresh</button> |
<script>
function generate() {
const array = new Uint8Array(16);
window.crypto.getRandomValues(array);
document.getElementById("password").textContent = btoa(String.fromCharCode.apply(null, array));
}
generate();
</script>
## :material-server: Server Example
=== ":material-harddisk: With local certificate"
```json
{
"inbounds": [
{
"type": "trojan",
"listen": "::",
"listen_port": 8080,
"users": [
{
"name": "example",
"password": "password"
}
],
"tls": {
"enabled": true,
"server_name": "example.org",
"key_path": "/path/to/key.pem",
"certificate_path": "/path/to/certificate.pem"
},
"multiplex": {
"enabled": true
}
}
]
}
```
=== ":material-auto-fix: With ACME"
```json
{
"inbounds": [
{
"type": "trojan",
"listen": "::",
"listen_port": 8080,
"users": [
{
"name": "example",
"password": "password"
}
],
"tls": {
"enabled": true,
"server_name": "example.org",
"acme": {
"domain": "example.org",
"email": "admin@example.org"
}
},
"multiplex": {
"enabled": true
}
}
]
}
```
=== ":material-cloud: With ACME and Cloudflare API"
```json
{
"inbounds": [
{
"type": "trojan",
"listen": "::",
"listen_port": 8080,
"users": [
{
"name": "example",
"password": "password"
}
],
"tls": {
"enabled": true,
"server_name": "example.org",
"acme": {
"domain": "example.org",
"email": "admin@example.org",
"dns01_challenge": {
"provider": "cloudflare",
"api_token": "my_token"
}
}
},
"multiplex": {
"enabled": true
}
}
]
}
```
## :material-cellphone-link: Client Example
=== ":material-web-check: With valid certificate"
```json
{
"outbounds": [
{
"type": "trojan",
"server": "127.0.0.1",
"server_port": 8080,
"password": "password",
"tls": {
"enabled": true,
"server_name": "example.org",
"utls": {
"enabled": true,
"fingerprint": "firefox"
}
},
"multiplex": {
"enabled": true
}
}
]
}
```
=== ":material-check: With self-sign certificate"
!!! info "Tip"
Use `sing-box merge` command to merge configuration and certificate into one file.
```json
{
"outbounds": [
{
"type": "trojan",
"server": "127.0.0.1",
"server_port": 8080,
"password": "password",
"tls": {
"enabled": true,
"server_name": "example.org",
"certificate_path": "/path/to/certificate.pem",
"utls": {
"enabled": true,
"fingerprint": "firefox"
}
},
"multiplex": {
"enabled": true
}
}
]
}
```
=== ":material-alert: Ignore certificate verification"
```json
{
"outbounds": [
{
"type": "trojan",
"server": "127.0.0.1",
"server_port": 8080,
"password": "password",
"tls": {
"enabled": true,
"server_name": "example.org",
"insecure": true,
"utls": {
"enabled": true,
"fingerprint": "firefox"
}
},
"multiplex": {
"enabled": true
}
}
]
}
```

208
docs/manual/proxy-protocol/tuic.md Normal file
View File

@@ -0,0 +1,208 @@
---
icon: material/alpha-t-box
---
# TUIC
A recently popular Chinese-made simple protocol based on QUIC, the selling point is the BBR congestion control algorithm.
!!! warning
Even though GFW rarely blocks UDP-based proxies, such protocols actually have far more characteristics than TCP based proxies.
| Specification | Binary Characteristics | Active Detect Hiddenness |
|-----------------------------------------------------------|------------------------|--------------------------|
| [Github](https://github.com/EAimTY/tuic/blob/dev/SPEC.md) | :material-alert: | :material-check: |
## Password Generator
| Generated UUID | Generated Password | Action |
|------------------------|----------------------------|-----------------------------------------------------------------|
| <code id="uuid"><code> | <code id="password"><code> | <button class="md-button" onclick="generate()">Refresh</button> |
<script>
function generateUUID() {
const uuid = 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function(c) {
let r = Math.random() * 16 | 0,
v = c === 'x' ? r : (r & 0x3 | 0x8);
return v.toString(16);
});
document.getElementById("uuid").textContent = uuid;
}
function generatePassword() {
const array = new Uint8Array(16);
window.crypto.getRandomValues(array);
document.getElementById("password").textContent = btoa(String.fromCharCode.apply(null, array));
}
function generate() {
generateUUID();
generatePassword();
}
generate();
</script>
## :material-server: Server Example
=== ":material-harddisk: With local certificate"
```json
{
"inbounds": [
{
"type": "tuic",
"listen": "::",
"listen_port": 8080,
"users": [
{
"name": "sekai",
"uuid": "<uuid>",
"password": "<password>"
}
],
"congestion_control": "bbr",
"tls": {
"enabled": true,
"server_name": "example.org",
"key_path": "/path/to/key.pem",
"certificate_path": "/path/to/certificate.pem"
}
}
]
}
```
=== ":material-auto-fix: With ACME"
```json
{
"inbounds": [
{
"type": "tuic",
"listen": "::",
"listen_port": 8080,
"users": [
{
"name": "sekai",
"uuid": "<uuid>",
"password": "<password>"
}
],
"congestion_control": "bbr",
"tls": {
"enabled": true,
"server_name": "example.org",
"acme": {
"domain": "example.org",
"email": "admin@example.org"
}
}
}
]
}
```
=== ":material-cloud: With ACME and Cloudflare API"
```json
{
"inbounds": [
{
"type": "tuic",
"listen": "::",
"listen_port": 8080,
"users": [
{
"name": "sekai",
"uuid": "<uuid>",
"password": "<password>"
}
],
"congestion_control": "bbr",
"tls": {
"enabled": true,
"server_name": "example.org",
"acme": {
"domain": "example.org",
"email": "admin@example.org",
"dns01_challenge": {
"provider": "cloudflare",
"api_token": "my_token"
}
}
}
}
]
}
```
## :material-cellphone-link: Client Example
=== ":material-web-check: With valid certificate"
```json
{
"outbounds": [
{
"type": "tuic",
"server": "127.0.0.1",
"server_port": 8080,
"uuid": "<uuid>",
"password": "<password>",
"congestion_control": "bbr",
"tls": {
"enabled": true,
"server_name": "example.org"
}
}
]
}
```
=== ":material-check: With self-sign certificate"
!!! info "Tip"
Use `sing-box merge` command to merge configuration and certificate into one file.
```json
{
"outbounds": [
{
"type": "tuic",
"server": "127.0.0.1",
"server_port": 8080,
"uuid": "<uuid>",
"password": "<password>",
"congestion_control": "bbr",
"tls": {
"enabled": true,
"server_name": "example.org",
"certificate_path": "/path/to/certificate.pem"
}
}
]
}
```
=== ":material-alert: Ignore certificate verification"
```json
{
"outbounds": [
{
"type": "tuic",
"server": "127.0.0.1",
"server_port": 8080,
"uuid": "<uuid>",
"password": "<password>",
"congestion_control": "bbr",
"tls": {
"enabled": true,
"server_name": "example.org",
"insecure": true
}
}
]
}
```

287
docs/manual/proxy/client.md Normal file
View File

@@ -0,0 +1,287 @@
---
icon: material/cellphone-link
---
# Client
### :material-ray-start: Introduction
For a long time, the modern usage and principles of proxy clients
for graphical operating systems have not been clearly described.
However, we can categorize them into three types:
system proxy, firewall redirection, and virtual interface.
### :material-web-refresh: System Proxy
Almost all graphical environments support system-level proxies,
which are essentially ordinary HTTP proxies that only support TCP.
| Operating System / Desktop Environment | System Proxy | Application Support |
|:---------------------------------------------|:-------------------------------------|:--------------------|
| Windows | :material-check: | :material-check: |
| macOS | :material-check: | :material-check: |
| GNOME/KDE | :material-check: | :material-check: |
| Android | ROOT or adb (permission) is required | :material-check: |
| Android/iOS (with sing-box graphical client) | via `tun.platform.http_proxy` | :material-check: |
As one of the most well-known proxy methods, it has many shortcomings:
many TCP clients that are not based on HTTP do not check and use the system proxy.
Moreover, UDP and ICMP traffics bypass the proxy.
```mermaid
flowchart LR
dns[DNS query] -- Is HTTP request? --> proxy[HTTP proxy]
dns --> leak[Leak]
tcp[TCP connection] -- Is HTTP request? --> proxy
tcp -- Check and use HTTP CONNECT? --> proxy
tcp --> leak
udp[UDP packet] --> leak
```
### :material-wall-fire: Firewall Redirection
This type of usage typically relies on the firewall or hook interface provided by the operating system,
such as Windows’ WFP, Linux’s redirect, TProxy and eBPF, and macOS’s pf.
Although it is intrusive and cumbersome to configure,
it remains popular within the community of amateur proxy open source projects like V2Ray,
due to the low technical requirements it imposes on the software.
### :material-expansion-card: Virtual Interface
All L2/L3 proxies (seriously defined VPNs, such as OpenVPN, WireGuard) are based on virtual network interfaces,
which is also the only way for all L4 proxies to work as VPNs on mobile platforms like Android, iOS.
The sing-box inherits and develops clash-premium’s TUN inbound (L3 to L4 conversion)
as the most reasonable method for performing transparent proxying.
```mermaid
flowchart TB
packet[IP Packet]
packet --> windows[Windows / macOS]
packet --> linux[Linux]
tun[TUN interface]
windows -. route .-> tun
linux -. iproute2 route/rule .-> tun
tun --> gvisor[gVisor TUN stack]
tun --> system[system TUN stack]
assemble([L3 to L4 assemble])
gvisor --> assemble
system --> assemble
assemble --> conn[TCP and UDP connections]
conn --> router[sing-box Router]
router --> direct[Direct outbound]
router --> proxy[Proxy outbounds]
router -- DNS hijack --> dns_out[DNS outbound]
dns_out --> dns_router[DNS router]
dns_router --> router
direct --> adi([auto detect interface])
proxy --> adi
adi --> default[Default network interface in the system]
default --> destination[Destination server]
default --> proxy_server[Proxy server]
proxy_server --> destination
```
## :material-cellphone-link: Examples
### Basic TUN usage for Chinese users
=== ":material-numeric-4-box: IPv4 only"
```json
{
"dns": {
"servers": [
{
"tag": "google",
"address": "tls://8.8.8.8"
},
{
"tag": "local",
"address": "223.5.5.5",
"detour": "direct"
}
],
"rules": [
{
"outbound": "any",
"server": "local"
}
],
"strategy": "ipv4_only"
},
"inbounds": [
{
"type": "tun",
"inet4_address": "172.19.0.1/30",
"auto_route": true,
"strict_route": false
}
],
"outbounds": [
// ...
{
"type": "direct",
"tag": "direct"
},
{
"type": "dns",
"tag": "dns-out"
}
],
"route": {
"rules": [
{
"protocol": "dns",
"outbound": "dns-out"
},
{
"geoip": [
"private"
],
"outbound": "direct"
}
],
"auto_detect_interface": true
}
}
```
=== ":material-numeric-6-box: IPv4 & IPv6"
```json
{
"dns": {
"servers": [
{
"tag": "google",
"address": "tls://8.8.8.8"
},
{
"tag": "local",
"address": "223.5.5.5",
"detour": "direct"
}
],
"rules": [
{
"outbound": "any",
"server": "local"
}
]
},
"inbounds": [
{
"type": "tun",
"inet4_address": "172.19.0.1/30",
"inet6_address": "fdfe:dcba:9876::1/126",
"auto_route": true,
"strict_route": false
}
],
"outbounds": [
// ...
{
"type": "direct",
"tag": "direct"
},
{
"type": "dns",
"tag": "dns-out"
}
],
"route": {
"rules": [
{
"protocol": "dns",
"outbound": "dns-out"
},
{
"geoip": [
"private"
],
"outbound": "direct"
}
],
"auto_detect_interface": true
}
}
```
=== ":material-domain-switch: FakeIP"
```json
{
"dns": {
"servers": [
{
"tag": "google",
"address": "tls://8.8.8.8"
},
{
"tag": "local",
"address": "223.5.5.5",
"detour": "direct"
},
{
"tag": "remote",
"address": "fakeip"
}
],
"rules": [
{
"outbound": "any",
"server": "local"
},
{
"query_type": [
"A",
"AAAA"
],
"server": "remote"
}
],
"fakeip": {
"enabled": true,
"inet4_range": "198.18.0.0/15",
"inet6_range": "fc00::/18"
},
"independent_cache": true
},
"inbounds": [
{
"type": "tun",
"inet4_address": "172.19.0.1/30",
"inet6_address": "fdfe:dcba:9876::1/126",
"auto_route": true,
"strict_route": true
}
],
"outbounds": [
// ...
{
"type": "direct",
"tag": "direct"
},
{
"type": "dns",
"tag": "dns-out"
}
],
"route": {
"rules": [
{
"protocol": "dns",
"outbound": "dns-out"
},
{
"geoip": [
"private"
],
"outbound": "direct"
}
],
"auto_detect_interface": true
}
}
```

10
docs/manual/proxy/server.md Normal file
View File

@@ -0,0 +1,10 @@
---
icon: material/server
---
# Server
To use sing-box as a proxy protocol server, you pretty much only need to configure the inbound for that protocol.
The Proxy Protocol menu below contains descriptions and configuration examples
of recommended protocols for bypassing GFW.

66
docs/manual/proxy/tun.md Normal file
View File

@@ -0,0 +1,66 @@
# :material-expansion-card: TUN
## :material-text-box: Definition
Refers to TUNnel, a virtual network device supported by the kernel.
It’s also used in sing-box to denote the extensive functionality surrounding TUN inbound:
including traffic assembly, automatic routing, and network and default interface monitoring.
The following flow chart describes the minimal TUN-based transparent proxy process in sing-box:
``` mermaid
flowchart LR
subgraph inbound [Inbound]
direction TB
packet[IP Packet]
packet --> windows[Windows / macOS]
packet --> linux[Linux]
tun[TUN interface]
windows -. route .-> tun
linux -. iproute2 route/rule .-> tun
tun --> gvisor[gVisor TUN stack]
tun --> system[system TUN stack]
assemble([L3 to L4 assemble])
gvisor --> assemble
system --> assemble
assemble --> conn[TCP and UDP connections]
conn --> router[sing-box Router]
end
subgraph outbound [Outbound]
direction TB
direct[Direct outbound]
proxy[Proxy outbounds]
direct --> adi([auto detect interface])
proxy --> adi
adi --> default[Default network interface in the system]
default --> destination[Destination server]
default --> proxy_server[Proxy server]
proxy_server --> destination
end
inbound --> outbound
```
## :material-help-box: How to
A basic TUN-based transparent proxy configuration file includes: an TUN inbound, `route.auto_detect_interface`, like:
```json
{
"inbounds": [
{
"type": "tun",
"inet4_address": "172.19.0.1/30",
"inet6_address": "fdfe:dcba:9876::1/126",
"auto_route": true,
"strict_route": true
}
],
"route": {
"auto_detect_interface": true
}
}
```
TODO: finish this wiki