black-internet-days-ahead/sing-box
1
0
Fork 0
mirror of https://github.com/SagerNet/sing-box.git synced 2025-02-16 14:24:31 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update documentation

Browse source
This commit is contained in:
世界 2022-07-27 12:03:07 +08:00
parent f008d0bde3
commit aa074a2063
No known key found for this signature in database
GPG key ID: CD109927C34A63C4
17 changed files with 382 additions and 47 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

11
common/dialer/tls.go
View file

@ -99,16 +99,7 @@ func NewTLS(dialer N.Dialer, serverAddress string, options option.OutboundTLSOpt
certificate = content certificate = content
} }
if len(certificate) > 0 { if len(certificate) > 0 {
var certPool *x509.CertPool certPool := x509.NewCertPool()
if options.DisableSystemRoot {
certPool = x509.NewCertPool()
} else {
var err error
certPool, err = x509.SystemCertPool()
if err != nil {
return nil, E.Cause(err, "load system cert pool")
}
}
if !certPool.AppendCertsFromPEM([]byte(options.Certificate)) { if !certPool.AppendCertsFromPEM([]byte(options.Certificate)) {
return nil, E.New("failed to parse certificate:\n\n", options.Certificate) return nil, E.New("failed to parse certificate:\n\n", options.Certificate)
} }

85
docs/configuration/dns/rule.md
View file

@ -9,7 +9,7 @@
"mixed-in" "mixed-in"
], ],
"network": "tcp", "network": "tcp",
"user": [ "auth_user": [
"usera", "usera",
"userb" "userb"
], ],
@ -42,20 +42,45 @@
"source_port": [ "source_port": [
12345 12345
], ],
"source_port_range": [
"1000:2000",
":3000",
"4000:"
],
"port": [ "port": [
80, 80,
443 443
], ],
"port_range": [
"1000:2000",
":3000",
"4000:"
],
"process_name": [
"curl"
],
"package_name": [
"com.termux"
],
"user": [
"sekai"
],
"user_id": [
1000
],
"invert": false,
"outbound": [ "outbound": [
"direct" "direct"
], ],
"server": "local" "server": "local",
"disable_cache": false
}, },
{ {
"type": "logical", "type": "logical",
"mode": "and", "mode": "and",
"rules": [], "rules": [],
"server": "local" "server": "local",
"disable_cache": false
} }
] ]
} }
@ -124,18 +149,64 @@ Match source ip cidr.
Match source port. Match source port.
#### source_port_range
Match source port range.
#### port #### port
Match port. Match port.
#### port_range
Match port range.
#### process_name
!!! error ""
Only supported on Linux, Windows, and macOS.
Match process name.
#### package_name
Match android package name.
#### user
!!! error ""
Only supported on Linux with CGO enabled.
Match user name.
#### user_id
!!! error ""
Only supported on Linux.
Match user id.
#### invert
Invert match result.
#### outbound #### outbound
Match outbound. Match outbound.
#### server #### server
==Required==
Tag of the target dns server. Tag of the target dns server.
#### disable_cache
Disable cache and save cache in this query.
### Logical Fields ### Logical Fields
#### type #### type
@ -150,8 +221,16 @@ Tag of the target dns server.
Included default rules. Included default rules.
#### invert
Invert match result.
#### server #### server
==Required== ==Required==
Tag of the target dns server. Tag of the target dns server.
#### disable_cache
Disable cache and save cache in this query.

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

@ -36,11 +36,30 @@ The address of the dns server.
| `UDP` | `8.8.8.8` `udp://8.8.4.4` | | `UDP` | `8.8.8.8` `udp://8.8.4.4` |
| `TLS` | `tls://dns.google` | | `TLS` | `tls://dns.google` |
| `HTTPS` | `https://1.1.1.1/dns-query` | | `HTTPS` | `https://1.1.1.1/dns-query` |
| `QUIC` | `quic://dns.adguard.com` |
| `HTTP3` | `h3://8.8.8.8/dns-query` |
| `RCode` | `rcode://refused` |
!!! warning "" !!! warning ""
To ensure that system DNS is in effect, rather than go's built-in default resolver, enable CGO at compile time. To ensure that system DNS is in effect, rather than go's built-in default resolver, enable CGO at compile time.
!!! warning ""
QUIC and HTTP3 transport is not included by default, see [Installation](/#Installation).
!!! info ""
the RCode transport is often used to block queries. Use with rules and the `disable_cache` rule option.
| RCode | Description |
|-------------------|-----------------------|
| `success` | `No error` |
| `format_error` | `Format error` |
| `server_failure` | `Server failure` |
| `name_error` | `Non-existent domain` |
| `not_implemented` | `Not implemented` |
#### address_resolver #### address_resolver
==Required if address contains domain== ==Required if address contains domain==

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

@ -15,14 +15,14 @@
"sniff": false, "sniff": false,
"sniff_override_destination": false, "sniff_override_destination": false,
"domain_strategy": "prefer_ipv6", "domain_strategy": "prefer_ipv6",
"tls": {},
"users": [ "users": [
{ {
"username": "admin", "username": "admin",
"password": "admin" "password": "admin"
} }
], ],
"set_system_proxy": false "set_system_proxy": false
} }
] ]
@ -77,6 +77,10 @@ Automatically set system proxy configuration when start and clean up when stop.
### HTTP Fields ### HTTP Fields
#### tls
TLS configuration, see [TLS inbound structure](/configuration/shared/tls/#inbound-structure).
#### users #### users
HTTP users. HTTP users.

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

@ -10,12 +10,12 @@
{ {
"type": "tun", "type": "tun",
"tag": "tun-in", "tag": "tun-in",
"inet4_address": "172.19.0.1/30", "inet4_address": "172.19.0.1/30",
"inet6_address": "fdfe:dcba:9876::1/128", "inet6_address": "fdfe:dcba:9876::1/128",
"mtu": 1500, "mtu": 1500,
"auto_route": true, "auto_route": true,
"endpoint_independent_nat": false,
"udp_timeout": 300,
"sniff": true, "sniff": true,
"sniff_override_destination": false, "sniff_override_destination": false,
"domain_strategy": "prefer_ipv4" "domain_strategy": "prefer_ipv4"
@ -48,6 +48,16 @@ Set the default route to the Tun.
To avoid traffic loopback, set `route.auto_detect_interface` or `route.default_interface` or `outbound.bind_interface` To avoid traffic loopback, set `route.auto_detect_interface` or `route.default_interface` or `outbound.bind_interface`
#### endpoint_independent_nat
Enabled endpoint-independent NAT.
Performance may degrade slightly, so it is not recommended to enable on when it is not needed.
#### udp_timeout
UDP NAT expiration time in seconds, default is 300 (5 minutes).
### Listen Fields ### Listen Fields
#### sniff #### sniff

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

@ -49,9 +49,11 @@ The network interface to bind to.
#### routing_mark #### routing_mark
The iptables routing mark. !!! error ""
Only available in linux. Linux only
The iptables routing mark.
#### reuse_addr #### reuse_addr

11
docs/configuration/outbound/http.md
View file

@ -13,6 +13,7 @@
"server_port": 1080, "server_port": 1080,
"username": "sekai", "username": "sekai",
"password": "admin", "password": "admin",
"tls": {},
"detour": "upstream-out", "detour": "upstream-out",
"bind_interface": "en0", "bind_interface": "en0",
@ -49,6 +50,10 @@ Basic authorization username.
Basic authorization password. Basic authorization password.
#### tls
TLS configuration, see [TLS outbound structure](/configuration/shared/tls/#outbound-structure).
### Dial Fields ### Dial Fields
#### detour #### detour
@ -63,9 +68,11 @@ The network interface to bind to.
#### routing_mark #### routing_mark
The iptables routing mark. !!! error ""
Only available in linux. Linux only
The iptables routing mark.
#### reuse_addr #### reuse_addr

6
docs/configuration/outbound/shadowsocks.md
View file

@ -98,9 +98,11 @@ The network interface to bind to.
#### routing_mark #### routing_mark
The iptables routing mark. !!! error ""
Only available in linux. Linux only
The iptables routing mark.
#### reuse_addr #### reuse_addr

8
docs/configuration/outbound/socks.md
View file

@ -8,14 +8,12 @@
{ {
"type": "socks", "type": "socks",
"tag": "socks-out", "tag": "socks-out",
"server": "127.0.0.1", "server": "127.0.0.1",
"server_port": 1080, "server_port": 1080,
"version": "5", "version": "5",
"username": "sekai", "username": "sekai",
"password": "admin", "password": "admin",
"network": "udp", "network": "udp",
"detour": "upstream-out", "detour": "upstream-out",
"bind_interface": "en0", "bind_interface": "en0",
"routing_mark": 1234, "routing_mark": 1234,
@ -79,9 +77,11 @@ The network interface to bind to.
#### routing_mark #### routing_mark
The iptables routing mark. !!! error ""
Only available in linux. Linux only
The iptables routing mark.
#### reuse_addr #### reuse_addr

13
docs/configuration/route/index.md
View file

@ -8,7 +8,8 @@
"rules": [], "rules": [],
"final": "", "final": "",
"auto_detect_interface": false, "auto_detect_interface": false,
"default_interface": "en0" "default_interface": "en0",
"default_mark": 233
} }
} }
``` ```
@ -44,3 +45,13 @@ Takes no effect if `outbound.bind_interface` is set.
Bind outbound connections to the specified NIC by default to prevent routing loops under Tun. Bind outbound connections to the specified NIC by default to prevent routing loops under Tun.
Takes no effect if `auto_detect_interface` is set. Takes no effect if `auto_detect_interface` is set.
#### default_mark
!!! error ""
Linux only
Set iptables routing mark by default.
Takes no effect if `outbound.routing_mark` is set.

76
docs/configuration/route/rule.md
View file

@ -9,7 +9,7 @@
"mixed-in" "mixed-in"
], ],
"network": "tcp", "network": "tcp",
"user": [ "auth_user": [
"usera", "usera",
"userb" "userb"
], ],
@ -48,16 +48,40 @@
"source_port": [ "source_port": [
12345 12345
], ],
"source_port_range": [
"1000:2000",
":3000",
"4000:"
],
"port": [ "port": [
80, 80,
443 443
], ],
"port_range": [
"1000:2000",
":3000",
"4000:"
],
"process_name": [
"curl"
],
"package_name": [
"com.termux"
],
"user": [
"sekai"
],
"user_id": [
1000
],
"invert": false,
"outbound": "direct" "outbound": "direct"
}, },
{ {
"type": "logical", "type": "logical",
"mode": "and", "mode": "and",
"rules": [], "rules": [],
"invert": false,
"outbound": "direct" "outbound": "direct"
} }
] ]
@ -83,7 +107,7 @@
Tags of [inbound](../inbound). Tags of [inbound](../inbound).
#### user #### auth_user
Username, see each inbound for details. Username, see each inbound for details.
@ -135,12 +159,54 @@ Match ip cidr.
Match source port. Match source port.
#### source_port_range
Match source port range.
#### port #### port
Match port. Match port.
#### port_range
Match port range.
#### process_name
!!! error ""
Only supported on Linux, Windows, and macOS.
Match process name.
#### package_name
Match android package name.
#### user
!!! error ""
Only supported on Linux with CGO enabled.
Match user name.
#### user_id
!!! error ""
Only supported on Linux.
Match user id.
#### invert
Invert match result.
#### outbound #### outbound
==Required==
Tag of the target outbound. Tag of the target outbound.
### Logical Fields ### Logical Fields
@ -157,6 +223,12 @@ Tag of the target outbound.
Included default rules. Included default rules.
#### invert
Invert match result.
#### outbound #### outbound
==Required==
Tag of the target outbound. Tag of the target outbound.

136
docs/configuration/shared/tls.md Normal file
View file

@ -0,0 +1,136 @@
### Inbound Structure
```json
{
"enabled": true,
"server_name": "",
"alpn": [],
"min_version": "",
"max_version": "",
"cipher_suites": [],
"certificate": "",
"certificate_path": "",
"key": "",
"key_path": ""
}
```
### Outbound Structure
```json
{
"enabled": true,
"server_name": "",
"insecure": false,
"alpn": [],
"min_version": "",
"max_version": "",
"cipher_suites": [],
"disable_system_root": false,
"certificate": "",
"certificate_path": ""
}
```
TLS version values:
* `1.0`
* `1.1`
* `1.2`
* `1.3`
Cipher suite values:
* `TLS_RSA_WITH_AES_128_CBC_SHA`
* `TLS_RSA_WITH_AES_256_CBC_SHA`
* `TLS_RSA_WITH_AES_128_GCM_SHA256`
* `TLS_RSA_WITH_AES_256_GCM_SHA384`
* `TLS_AES_128_GCM_SHA256`
* `TLS_AES_256_GCM_SHA384`
* `TLS_CHACHA20_POLY1305_SHA256`
* `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA`
* `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA`
* `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA`
* `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA`
* `TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256`
* `TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384`
* `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256`
* `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384`
* `TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256`
* `TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256`
### Fields
#### enabled
Enabled TLS.
#### server_name
Used to verify the hostname on the returned certificates unless insecure is given.
It is also included in the client's handshake to support virtual hosting unless it is an IP address.
See [Server Name Indication](https://en.wikipedia.org/wiki/Server_Name_Indication).
#### insecure
==Client only==
Accepts any server certificate.
#### alpn
List of supported application level protocols, in order of preference.
If both peers support ALPN, the selected protocol will be one from this list, and the connection will fail if there is
no mutually supported protocol.
See [Application-Layer Protocol Negotiation](https://en.wikipedia.org/wiki/Application-Layer_Protocol_Negotiation).
#### min_version
The minimum TLS version that is acceptable.
By default, TLS 1.2 is currently used as the minimum when acting as a
client, and TLS 1.0 when acting as a server. TLS 1.0 is the minimum
supported by this package, both as a client and as a server.
The client-side default can temporarily be reverted to TLS 1.0 by
including the value "x509sha1=1" in the GODEBUG environment variable.
Note that this option will be removed in Go 1.19 (but it will still be
possible to set this field to VersionTLS10 explicitly).
#### max_version
The maximum TLS version that is acceptable.
By default, the maximum version supported by this package is used,
which is currently TLS 1.3.
#### cipher_suites
The elliptic curves that will be used in an ECDHE handshake, in preference order.
If empty, the default will be used. The client will use the first preference as the type for its key share in TLS 1.3.
This may change in the future.
#### certificate
The server certificate, in PEM format.
#### certificate_path
The path to the server certificate, in PEM format.
#### key
==Server only==
The server private key, in PEM format.
#### key_path
==Server only==
The path to the server private key, in PEM format.

9
docs/index.md
View file

@ -18,10 +18,11 @@ Install with options:
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,no_gvisor" github.com/sagernet/sing-box/cmd/sing-box@latest
``` ```
| Build Tag | Description | | Build Tag | Description |
|------------------|--------------------------------------------------------------------------------------------------| |------------------|---------------------------------------------------------------------------------------------------------|
| `with_clash_api` | Build with clash api support, see [Experimental](./configuration/experimental#clash-api-fields). | | `with_quic` | Build with quic support, which required by [QUIC and HTTP3](./configuration/dns/server) dns transports. |
| `no_gvisor` | Build without gVisor, which required by the [Tun](./configuration/inbound/tun) inbound. | | `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. |
The binary is built under $GOPATH/bin The binary is built under $GOPATH/bin

2
mkdocs.yml
View file

@ -65,6 +65,8 @@ nav:
- Route Rule: configuration/route/rule.md - Route Rule: configuration/route/rule.md
- Protocol Sniff: configuration/route/sniff.md - Protocol Sniff: configuration/route/sniff.md
- Experimental: configuration/experimental.md - Experimental: configuration/experimental.md
- Shared:
- TLS: configuration/shared/tls.md
- Examples: - Examples:
- examples/index.md - examples/index.md
- Shadowsocks Server: examples/ss-server.md - Shadowsocks Server: examples/ss-server.md

21
option/tls.go
View file

@ -20,17 +20,16 @@ type InboundTLSOptions struct {
} }
type OutboundTLSOptions struct { type OutboundTLSOptions struct {
Enabled bool `json:"enabled,omitempty"` Enabled bool `json:"enabled,omitempty"`
DisableSNI bool `json:"disable_sni,omitempty"` DisableSNI bool `json:"disable_sni,omitempty"`
ServerName string `json:"server_name,omitempty"` ServerName string `json:"server_name,omitempty"`
Insecure bool `json:"insecure,omitempty"` Insecure bool `json:"insecure,omitempty"`
ALPN []string `json:"alpn,omitempty"` ALPN []string `json:"alpn,omitempty"`
MinVersion string `json:"min_version,omitempty"` MinVersion string `json:"min_version,omitempty"`
MaxVersion string `json:"max_version,omitempty"` MaxVersion string `json:"max_version,omitempty"`
CipherSuites []string `json:"cipher_suites,omitempty"` CipherSuites []string `json:"cipher_suites,omitempty"`
DisableSystemRoot bool `json:"disable_system_root,omitempty"` Certificate string `json:"certificate,omitempty"`
Certificate string `json:"certificate,omitempty"` CertificatePath string `json:"certificate_path,omitempty"`
CertificatePath string `json:"certificate_path,omitempty"`
} }
func ParseTLSVersion(version string) (uint16, error) { func ParseTLSVersion(version string) (uint16, error) {

2
route/router.go
View file

@ -58,7 +58,7 @@ var warnFindProcessOnUnsupportedPlatform = warning.New(
func() bool { func() bool {
return !(C.IsLinux || C.IsWindows || C.IsDarwin) return !(C.IsLinux || C.IsWindows || C.IsDarwin)
}, },
"route option `find_process` is only supported on Linux, Windows, and Mac OS X", "route option `find_process` is only supported on Linux, Windows, and macOS",
) )
var _ adapter.Router = (*Router)(nil) var _ adapter.Router = (*Router)(nil)

2
route/rule_process.go
View file

@ -11,7 +11,7 @@ import (
var warnProcessNameOnNonSupportedPlatform = warning.New( var warnProcessNameOnNonSupportedPlatform = warning.New(
func() bool { return !(C.IsLinux || C.IsWindows || C.IsDarwin) }, func() bool { return !(C.IsLinux || C.IsWindows || C.IsDarwin) },
"rule item `process_item` is only supported on Linux, Windows, and Mac OS X", "rule item `process_item` is only supported on Linux, Windows, and macOS",
) )
var _ RuleItem = (*ProcessItem)(nil) var _ RuleItem = (*ProcessItem)(nil)