diff --git a/.github/workflows/mkdocs.yml b/.github/workflows/mkdocs.yml new file mode 100644 index 00000000..6af76fe8 --- /dev/null +++ b/.github/workflows/mkdocs.yml @@ -0,0 +1,18 @@ +name: Generate Documents +on: + push: + branches: + - dev + paths: + - docs + - .github/workflows/mkdocs.yml +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - uses: actions/setup-python@v2 + with: + python-version: 3.x + - run: pip install mkdocs-material + - run: mkdocs gh-deploy -m "{sha}" -b "docs" --force --ignore-version --no-history \ No newline at end of file diff --git a/.gitignore b/.gitignore index ce9c8fa5..238799ac 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,5 @@ /.idea/ /vendor/ /*.json -/*.db \ No newline at end of file +/*.db +/site/ \ No newline at end of file diff --git a/docs/CNAME b/docs/CNAME new file mode 100644 index 00000000..a4ffb2f2 --- /dev/null +++ b/docs/CNAME @@ -0,0 +1 @@ +sing-box.sagernet.org \ No newline at end of file diff --git a/docs/configuration/dns/index.md b/docs/configuration/dns/index.md new file mode 100644 index 00000000..693a070b --- /dev/null +++ b/docs/configuration/dns/index.md @@ -0,0 +1,40 @@ +### Structure + +```json +{ + "dns": { + "servers": [], + "rules": [], + "final": "", + "strategy": "prefer_ipv6", + "disable_cache": false, + "disable_expire": false + } +} + +``` + +### Fields + +| Key | Format | +|----------|--------------------------------| +| `server` | List of [DNS Server](./server) | +| `rules` | List of [DNS Rule](./rule) | + +#### final + +Default dns server tag, the first one will be used if it is empty. + +#### strategy + +Default domain strategy for resolving the domain names. + +One of `prefer_ipv4` `prefer_ipv6` `ipv4_only` `ipv6_only`. + +#### disable_cache + +Disable dns cache. + +#### disable_expire + +Disable dns cache expire. \ No newline at end of file diff --git a/docs/configuration/dns/rule.md b/docs/configuration/dns/rule.md new file mode 100644 index 00000000..27c03f8a --- /dev/null +++ b/docs/configuration/dns/rule.md @@ -0,0 +1,143 @@ +### Structure + +```json +{ + "dns": { + "rules": [ + { + "inbound": [ + "mixed-in" + ], + "network": "tcp", + "protocol": [ + "tls", + "http", + "quic" + ], + "domain": [ + "test.com" + ], + "domain_suffix": [ + ".cn" + ], + "domain_keyword": [ + "test" + ], + "domain_regex": [ + "^stun\\..+" + ], + "geosite": [ + "cn" + ], + "source_geoip": [ + "private" + ], + "source_ip_cidr": [ + "10.0.0.0/24" + ], + "source_port": [ + 12345 + ], + "port": [ + 80, + 443 + ], + "outbound": [ + "direct" + ], + "server": "local" + }, + { + "type": "logical", + "mode": "and", + "rules": [], + "server": "local" + } + ] + } +} + +``` + +!!! note "" + + You can ignore the JSON Array [] tag when the content is only one item + +### Default Fields + +!!! note "" + + The default rule uses the following matching logic: + (`domain` || `domain_suffix` || `domain_keyword` || `domain_regex` || `geosite`) && + (`source_geoip` || `source_ip_cidr`) && + `other fields` + +#### inbound + +Tags of [inbound](../inbound). + +#### network + +`tcp` or `udp`. + +#### domain + +Match full domain. + +#### domain_suffix + +Match domain suffix. + +#### domain_keyword + +Match domain using keyword. + +#### domain_regex + +Match domain using regular expression. + +#### geosite + +Match geosite. + +#### source_geoip + +Match source geoip. + +#### source_ip_cidr + +Match source ip cidr. + +#### source_port + +Match source port. + +#### port + +Match port. + +#### outbound + +Match outbound. + +#### server + +Tag of the target dns server. + +### Logical Fields + +#### type + +`logical` + +#### mode + +`and` or `or` + +#### rules + +Included default rules. + +#### server + +Tag of the target dns server. diff --git a/docs/configuration/dns/server.md b/docs/configuration/dns/server.md new file mode 100644 index 00000000..2f8fe2ca --- /dev/null +++ b/docs/configuration/dns/server.md @@ -0,0 +1,58 @@ +### Structure + +```json +{ + "dns": { + "servers": [ + { + "tag": "google", + "address": "tls://dns.google", + "address_resolver": "local", + "address_strategy": "prefer_ipv4", + "detour": "direct" + } + ] + } +} + +``` + +### Fields + +#### tag + +The tag of the dns server. + +#### address + +The address of the dns server. + +| Protocol | Format | +|----------|-----------------------------| +| `System` | `local` | +| `TCP` | `tcp://1.0.0.1` | +| `UDP` | `8.8.8.8` `udp://8.8.4.4` | +| `TLS` | `tls://dns.google` | +| `HTTPS` | `https://1.1.1.1/dns-query` | + +!!! warning "" + + To ensure that system DNS is in effect, rather than go's built-in default resolver, enable CGO at compile time. + +#### address_resolver + +Tag of a another server to resolve the domain name in the address. + +#### address_strategy + +The domain strategy for resolving the domain name in the address. + +One of `prefer_ipv4` `prefer_ipv6` `ipv4_only` `ipv6_only`. + +`dns.strategy` will be used if `address_strategy` is empty. + +#### detour + +Tag of an outbound for connecting to the dns server. + +Requests will be sent directly if the empty. \ No newline at end of file diff --git a/docs/configuration/inbound/index.md b/docs/configuration/inbound/index.md new file mode 100644 index 00000000..4d1f2ab1 --- /dev/null +++ b/docs/configuration/inbound/index.md @@ -0,0 +1,13 @@ +### Structure + +```json +{ + "inbounds": [ + { + "type": "", + "tag": "", + ... + } + ] +} +``` \ No newline at end of file diff --git a/docs/configuration/index.md b/docs/configuration/index.md new file mode 100644 index 00000000..0b8a54a5 --- /dev/null +++ b/docs/configuration/index.md @@ -0,0 +1,37 @@ +# Introduction + +sing-box uses JSON for configuration files. + +### Structure + +```json +{ + "log": {}, + "dns": {}, + "inbounds": {}, + "outbounds": {}, + "route": {} +} +``` + +### Fields + +| Key | Format | +|-------------|------------------------| +| `log` | [Log](./log) | +| `dns` | [DNS](./dns) | +| `inbounds` | [Inbound](./inbound) | +| `outbounds` | [Outbound](./outbound) | +| `route` | [Route](./route) | + +### Check + +```bash +$ sing-box check +``` + +### Format + +```bash +$ sing-box format -w +``` \ No newline at end of file diff --git a/docs/configuration/log.md b/docs/configuration/log.md new file mode 100644 index 00000000..ff45e165 --- /dev/null +++ b/docs/configuration/log.md @@ -0,0 +1,33 @@ +# Log + +### Structure + +```json +{ + "log": { + "disabled": false, + "level": "info", + "output": "box.log", + "timestamp": true + } +} + +``` + +### Fields + +#### disabled + +Disable logging, no output after start. + +#### level + +Log level. One of: `trace` `debug` `info` `warn` `error` `fatal` `panic`. + +#### output + +Output file path. Will not write log to console after enable. + +#### timestamp + +Add time to each line. \ No newline at end of file diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..9ff00dc9 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,5 @@ +# Home + +Welcome to the wiki page for the sing-box project. + +The universal proxy platform. \ No newline at end of file diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 00000000..a1c9288b --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,13 @@ +# Installation + +sing-box requires Golang 1.18 or a higher version. + +```bash +$ go install github.com/sagernet/sing-box@latest +``` + +The binary is built under $GOPATH/bin + +```bash +$ sing-box version +``` diff --git a/docs/license.md b/docs/license.md new file mode 100644 index 00000000..9e5712bc --- /dev/null +++ b/docs/license.md @@ -0,0 +1,18 @@ +# License + +``` +Copyright (C) 2022 by nekohasekai + +This program is free software: you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation, either version 3 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program. If not, see . +``` \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 00000000..05048a78 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,61 @@ +site_name: sing-box +site_author: nekohasekai +repo_url: https://github.com/SagerNet/sing-box +repo_name: SagerNet/sing-box +copyright: Copyright © 2021 nekohasekai +edit_uri: "" +theme: + name: material + icon: + logo: material/tools + palette: + - scheme: default + primary: white + toggle: + icon: material/brightness-7 + name: Switch to dark mode + - scheme: slate + primary: black + toggle: + icon: material/brightness-4 + name: Switch to light mode + features: + - navigation.instant + - navigation.tracking + - navigation.tabs + - navigation.indexes + - navigation.expand + - navigation.sections + - header.autohide +nav: + - Getting Started: + - index.md + - Installation: installation.md + - License: license.md + - Configuration: + - configuration/index.md + - Log: configuration/log.md + - DNS: + - configuration/dns/index.md + - DNS Server: configuration/dns/server.md + - DNS Rule: configuration/dns/rule.md + - Inbound: + - configuration/inbound/index.md +markdown_extensions: + - pymdownx.highlight: + anchor_linenums: true + - pymdownx.inlinehilite + - pymdownx.snippets + - pymdownx.superfences + - pymdownx.tabbed: + alternate_style: true + - admonition + - pymdownx.details + - attr_list + - md_in_html + - footnotes +extra: + social: + - icon: fontawesome/brands/github + link: https://github.com/SagerNet/sing-box + generator: false