From 55d9a0ef2fe03cccca079157d4a66eb066d9d4fe Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E4=B8=96=E7=95=8C?= Date: Mon, 8 Aug 2022 20:57:50 +0800 Subject: [PATCH] Update documentation --- docs/changelog.md | 3 + docs/configuration/inbound/index.md | 1 + docs/configuration/inbound/trojan.md | 75 ++++++++++++ docs/configuration/inbound/tun.md | 25 +++- docs/configuration/outbound/index.md | 1 + docs/configuration/outbound/trojan.md | 114 ++++++++++++++++++ docs/examples/index.md | 2 +- ...nstall.md => linux-server-installation.md} | 0 docs/index.md | 17 +-- mkdocs.yml | 8 +- 10 files changed, 235 insertions(+), 11 deletions(-) create mode 100644 docs/changelog.md create mode 100644 docs/configuration/inbound/trojan.md create mode 100644 docs/configuration/outbound/trojan.md rename docs/examples/{linux-server-install.md => linux-server-installation.md} (100%) diff --git a/docs/changelog.md b/docs/changelog.md new file mode 100644 index 00000000..d29a4794 --- /dev/null +++ b/docs/changelog.md @@ -0,0 +1,3 @@ +#### 2022/08/08 + +No changelog before. \ No newline at end of file diff --git a/docs/configuration/inbound/index.md b/docs/configuration/inbound/index.md index 4894ab71..1a6f5882 100644 --- a/docs/configuration/inbound/index.md +++ b/docs/configuration/inbound/index.md @@ -21,6 +21,7 @@ | `http` | [HTTP](./http) | | `shadowsocks` | [Shadowsocks](./shadowsocks) | | `vmess` | [VMess](./vmess) | +| `trojan` | [Trojan](./trojan) | | `tun` | [Tun](./tun) | | `redirect` | [Redirect](./redirect) | | `tproxy` | [TProxy](./tproxy) | diff --git a/docs/configuration/inbound/trojan.md b/docs/configuration/inbound/trojan.md new file mode 100644 index 00000000..d71d8259 --- /dev/null +++ b/docs/configuration/inbound/trojan.md @@ -0,0 +1,75 @@ +### Structure + +```json +{ + "inbounds": [ + { + "type": "trojan", + "tag": "trojan-in", + + "listen": "::", + "listen_port": 2080, + "tcp_fast_open": false, + "sniff": false, + "sniff_override_destination": false, + "domain_strategy": "prefer_ipv6", + + "users": [ + { + "name": "sekai", + "password": "8JCsPssfgS8tiRwiMlhARg==" + } + ], + "tls": {} + } + ] +} +``` + +### Listen Fields + +#### listen + +==Required== + +Listen address. + +#### listen_port + +==Required== + +Listen port. + +#### tcp_fast_open + +Enable tcp fast open for listener. + +#### 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. + +### Trojan Fields + +#### users + +Trojan users. + +#### tls + +TLS configuration, see [TLS inbound structure](/configuration/shared/tls/#inbound-structure). diff --git a/docs/configuration/inbound/tun.md b/docs/configuration/inbound/tun.md index 6de56ab5..6a040143 100644 --- a/docs/configuration/inbound/tun.md +++ b/docs/configuration/inbound/tun.md @@ -10,13 +10,15 @@ { "type": "tun", "tag": "tun-in", - + + "interface_name": "tun0", "inet4_address": "172.19.0.1/30", "inet6_address": "fdfe:dcba:9876::1/128", "mtu": 1500, "auto_route": true, "endpoint_independent_nat": false, "udp_timeout": 300, + "stack": "gvisor", "sniff": true, "sniff_override_destination": false, @@ -26,8 +28,16 @@ } ``` +!!! warning "" + + If tun is running in non-privileged mode, the address and MTU will not be configured automatically, please make sure the settings are accurate. + ### Tun Fields +#### interface_name + +Virtual device name, automatically selected if empty. + #### inet4_address ==Required== @@ -60,6 +70,19 @@ Performance may degrade slightly, so it is not recommended to enable on when it UDP NAT expiration time in seconds, default is 300 (5 minutes). +#### stack + +TCP/IP stack. + +| Stack | Upstream | Status | +|------------------|-----------------------------------------------------------------------|-------------------| +| gVisor (default) | [google/gvisor](https://github.com/google/gvisor) | recommended | +| LWIP | [eycorsican/go-tun2socks](https://github.com/eycorsican/go-tun2socks) | upstream archived | + +!!! warning "" + + The LWIP stack is not included by default, see [Installation](/#Installation). + ### Listen Fields #### sniff diff --git a/docs/configuration/outbound/index.md b/docs/configuration/outbound/index.md index 29928998..20956816 100644 --- a/docs/configuration/outbound/index.md +++ b/docs/configuration/outbound/index.md @@ -21,6 +21,7 @@ | `http` | [HTTP](./http) | | `shadowsocks` | [Shadowsocks](./shadowsocks) | | `vmess` | [VMess](./vmess) | + | `trojan` | [Trojan](./trojan) | | `dns` | [DNS](./dns) | | `selector` | [Selector](./selector) | diff --git a/docs/configuration/outbound/trojan.md b/docs/configuration/outbound/trojan.md new file mode 100644 index 00000000..fbee069e --- /dev/null +++ b/docs/configuration/outbound/trojan.md @@ -0,0 +1,114 @@ +### Structure + +```json +{ + "outbounds": [ + { + "type": "trojan", + "tag": "trojan-out", + + "server": "127.0.0.1", + "server_port": 1080, + "password": "8JCsPssfgS8tiRwiMlhARg==", + "network": "tcp", + "tls": {}, + "multiplex": {}, + + "detour": "upstream-out", + "bind_interface": "en0", + "routing_mark": 1234, + "reuse_addr": false, + "connect_timeout": "5s", + "tcp_fast_open": false, + "domain_strategy": "prefer_ipv6", + "fallback_delay": "300ms" + } + ] +} +``` + +### Trojan Fields + +#### server + +==Required== + +The server address. + +#### server_port + +==Required== + +The server port. + +#### password + +==Required== + +The Trojan password. + +#### network + +Enabled network + +One of `tcp` `udp`. + +Both is enabled by default. + +#### tls + +TLS configuration, see [TLS outbound structure](/configuration/shared/tls/#outbound-structure). + +#### multiplex + +Multiplex configuration, see [Multiplex structure](/configuration/shared/multiplex). + +### Dial Fields + +#### detour + +The tag of the upstream outbound. + +Other dial fields will be ignored when enabled. + +#### bind_interface + +The network interface to bind to. + +#### routing_mark + +!!! error "" + + Linux only + +The iptables routing mark. + +#### reuse_addr + +Reuse listener address. + +#### connect_timeout + +Connect timeout, in golang's Duration format. + +A duration string is a possibly signed sequence of +decimal numbers, each with optional fraction and a unit suffix, +such as "300ms", "-1.5h" or "2h45m". +Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h". + +#### domain_strategy + +One of `prefer_ipv4` `prefer_ipv6` `ipv4_only` `ipv6_only`. + +If set, the server domain name will be resolved to IP before connecting. + +`dns.strategy` will be used if empty. + +#### fallback_delay + +The length of time to wait before spawning a RFC 6555 Fast Fallback connection. +That is, is the amount of time to wait for IPv6 to succeed before assuming +that IPv6 is misconfigured and falling back to IPv4 if `prefer_ipv4` is set. +If zero, a default delay of 300ms is used. + +Only take effect when `domain_strategy` is `prefer_ipv4` or `prefer_ipv6`. \ No newline at end of file diff --git a/docs/examples/index.md b/docs/examples/index.md index 3c6d5686..49b0e81f 100644 --- a/docs/examples/index.md +++ b/docs/examples/index.md @@ -2,7 +2,7 @@ Configuration examples for sing-box. -* [Linux Server Install](./linux-server-install) +* [Linux Server Installation](./linux-server-installation) * [Shadowsocks Server](./ss-server) * [Shadowsocks Client](./ss-client) * [Shadowsocks Tun](./ss-tun) diff --git a/docs/examples/linux-server-install.md b/docs/examples/linux-server-installation.md similarity index 100% rename from docs/examples/linux-server-install.md rename to docs/examples/linux-server-installation.md diff --git a/docs/index.md b/docs/index.md index 92a8946f..bae698ef 100644 --- a/docs/index.md +++ b/docs/index.md @@ -6,7 +6,7 @@ The universal proxy platform. ## Installation -sing-box requires Golang 1.18 or a higher version. +sing-box requires Golang **1.18.5** or a higher version. ```bash go install -v github.com/sagernet/sing-box/cmd/sing-box@latest @@ -15,14 +15,15 @@ go install -v github.com/sagernet/sing-box/cmd/sing-box@latest Install with options: ```bash -go install -v -tags "with_clash_api,no_gvisor" github.com/sagernet/sing-box/cmd/sing-box@latest +go install -v -tags with_clash_api github.com/sagernet/sing-box/cmd/sing-box@latest ``` -| Build Tag | Description | -|------------------|---------------------------------------------------------------------------------------------------------| -| `with_quic` | Build with quic support, which required by [QUIC and HTTP3](./configuration/dns/server) dns transports. | -| `with_clash_api` | Build with clash api support, see [Experimental](./configuration/experimental#clash-api-fields). | -| `no_gvisor` | Build without gVisor, which required by the [Tun](./configuration/inbound/tun) inbound. | +| Build Tag | Description | +|----------------------------|--------------------------------------------------------------------------------------------------| +| `with_quic` | Build with QUIC support, see [QUIC and HTTP3](./configuration/dns/server) dns transports. | +| `with_clash_api` | Build with Clash api support, see [Experimental](./configuration/experimental#clash-api-fields). | +| `no_gvisor` | Build without gVisor tun stack support, see [Tun](./configuration/inbound/tun#stack). | +| `with_lwip` (CGO required) | Build with LWIP tun stack support, see [Tun](./configuration/inbound/tun#stack). | The binary is built under $GOPATH/bin @@ -30,6 +31,8 @@ The binary is built under $GOPATH/bin sing-box version ``` +It is also recommended to use systemd to manage sing-box service, see [Linux server installation example](./examples/linux-server-installation). + ## License ``` diff --git a/mkdocs.yml b/mkdocs.yml index 339e36e5..f1bfa8b3 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -30,7 +30,9 @@ theme: - navigation.sections - header.autohide nav: - - Getting Started: index.md + - Getting Started: + - index.md + - Change Log: changelog.md - Configuration: - configuration/index.md - Log: configuration/log.md @@ -46,6 +48,7 @@ nav: - HTTP: configuration/inbound/http.md - Shadowsocks: configuration/inbound/shadowsocks.md - VMess: configuration/inbound/vmess.md + - Trojan: configuration/inbound/trojan.md - Tun: configuration/inbound/tun.md - Redirect: configuration/inbound/redirect.md - TProxy: configuration/inbound/tproxy.md @@ -57,6 +60,7 @@ nav: - HTTP: configuration/outbound/http.md - Shadowsocks: configuration/outbound/shadowsocks.md - VMess: configuration/outbound/vmess.md + - Trojan: configuration/outbound/trojan.md - DNS: configuration/outbound/dns.md - Selector: configuration/outbound/selector.md - Route: @@ -71,7 +75,7 @@ nav: - Multiplex: configuration/shared/multiplex.md - Examples: - examples/index.md - - Linux Server Install: examples/linux-server-install.md + - Linux Server Installation: examples/linux-server-installation.md - Shadowsocks Server: examples/ss-server.md - Shadowsocks Client: examples/ss-client.md - Shadowsocks Tun: examples/ss-tun.md