From a460b7abfb98fa76d2a746bbaae5609fe286dad1 Mon Sep 17 00:00:00 2001 From: Micooz Date: Fri, 15 Jun 2018 14:38:46 +0800 Subject: [PATCH] docs: add examples --- README.md | 15 +- docs/README.md | 1 + docs/config/README.md | 136 -------------- docs/examples/README.md | 3 + docs/examples/multiplexing/README.md | 31 ++++ .../multiplexing/blinksocks.client.json | 23 +++ .../multiplexing/blinksocks.server.json | 19 ++ docs/examples/obfs-random-padding/README.md | 23 +++ .../blinksocks.client.json | 21 +++ .../blinksocks.server.json | 18 ++ .../obfs-tls-session-ticket/README.md | 7 + .../blinksocks.client.json | 26 +++ .../blinksocks.server.json | 23 +++ docs/examples/shadowsocks/README.md | 23 +++ .../shadowsocks/blinksocks.client.json | 18 ++ .../shadowsocks/blinksocks.server.json | 15 ++ docs/examples/shadowsocksr/README.md | 42 +++++ .../shadowsocksr/blinksocks.client.json | 21 +++ .../shadowsocksr/blinksocks.server.json | 18 ++ docs/examples/tls/README.md | 40 +++++ docs/examples/tls/blinksocks.client.json | 17 ++ docs/examples/tls/blinksocks.server.json | 14 ++ docs/examples/v2ray-vmess/README.md | 67 +++++++ .../v2ray-vmess/blinksocks.client.json | 16 ++ .../v2ray-vmess/blinksocks.server.json | 13 ++ docs/examples/websocket-caddy-tls/Caddyfile | 9 + docs/examples/websocket-caddy-tls/README.md | 20 +++ .../blinksocks.client.json | 15 ++ .../blinksocks.server.json | 12 ++ docs/examples/websocket-tls/README.md | 20 +++ .../websocket-tls/blinksocks.client.json | 17 ++ .../websocket-tls/blinksocks.server.json | 14 ++ docs/examples/websocket/README.md | 13 ++ .../examples/websocket/blinksocks.client.json | 21 +++ .../examples/websocket/blinksocks.server.json | 18 ++ docs/presets/README.md | 2 +- docs/presets/RECOMMENDATIONS.md | 167 ------------------ 37 files changed, 667 insertions(+), 311 deletions(-) create mode 100644 docs/examples/README.md create mode 100644 docs/examples/multiplexing/README.md create mode 100644 docs/examples/multiplexing/blinksocks.client.json create mode 100644 docs/examples/multiplexing/blinksocks.server.json create mode 100644 docs/examples/obfs-random-padding/README.md create mode 100644 docs/examples/obfs-random-padding/blinksocks.client.json create mode 100644 docs/examples/obfs-random-padding/blinksocks.server.json create mode 100644 docs/examples/obfs-tls-session-ticket/README.md create mode 100644 docs/examples/obfs-tls-session-ticket/blinksocks.client.json create mode 100644 docs/examples/obfs-tls-session-ticket/blinksocks.server.json create mode 100644 docs/examples/shadowsocks/README.md create mode 100644 docs/examples/shadowsocks/blinksocks.client.json create mode 100644 docs/examples/shadowsocks/blinksocks.server.json create mode 100644 docs/examples/shadowsocksr/README.md create mode 100644 docs/examples/shadowsocksr/blinksocks.client.json create mode 100644 docs/examples/shadowsocksr/blinksocks.server.json create mode 100644 docs/examples/tls/README.md create mode 100644 docs/examples/tls/blinksocks.client.json create mode 100644 docs/examples/tls/blinksocks.server.json create mode 100644 docs/examples/v2ray-vmess/README.md create mode 100644 docs/examples/v2ray-vmess/blinksocks.client.json create mode 100644 docs/examples/v2ray-vmess/blinksocks.server.json create mode 100644 docs/examples/websocket-caddy-tls/Caddyfile create mode 100644 docs/examples/websocket-caddy-tls/README.md create mode 100644 docs/examples/websocket-caddy-tls/blinksocks.client.json create mode 100644 docs/examples/websocket-caddy-tls/blinksocks.server.json create mode 100644 docs/examples/websocket-tls/README.md create mode 100644 docs/examples/websocket-tls/blinksocks.client.json create mode 100644 docs/examples/websocket-tls/blinksocks.server.json create mode 100644 docs/examples/websocket/README.md create mode 100644 docs/examples/websocket/blinksocks.client.json create mode 100644 docs/examples/websocket/blinksocks.server.json delete mode 100644 docs/presets/RECOMMENDATIONS.md diff --git a/README.md b/README.md index 3cad643..3bbbb2e 100644 --- a/README.md +++ b/README.md @@ -64,6 +64,7 @@ For configuring blinksocks, please refer to [Configuration](docs/config). 1. [Usage](docs/usage) 2. [Configuration](docs/config) 3. [Presets](docs/presets) +4. [Examples](docs/examples) ### For Developers @@ -80,12 +81,12 @@ See [contributors](https://github.com/blinksocks/blinksocks/graphs/contributors) Apache License 2.0 -[TLS]: docs/config#blinksocks-over-tls -[WebSocket]: docs/config#blinksocks-over-websocket -[WebSocket/TLS]: docs/config#blinksocks-over-websockettls -[multiplexing]: docs/config#multiplexing [customization]: docs/development/api [ACL]: docs/config#access-control-list -[shadowsocks]: docs/presets/RECOMMENDATIONS.md#work-with-shadowsocks -[shadowsocksR]: docs/presets/RECOMMENDATIONS.md#work-with-shadowsocksr -[v2ray vmess]: docs/presets/RECOMMENDATIONS.md#work-with-v2ray-vmess +[TLS]: docs/examples/tls +[WebSocket]: docs/examples/websocket +[WebSocket/TLS]: docs/examples/websocket-tls +[multiplexing]: docs/examples/multiplexing +[shadowsocks]: docs/examples/shadowsocks +[shadowsocksR]: docs/examples/shadowsocksr +[v2ray vmess]: docs/examples/v2ray-vmess diff --git a/docs/README.md b/docs/README.md index 2477962..855059d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -5,6 +5,7 @@ 1. [Usage](usage) 2. [Configuration](config) 3. [Presets](presets) +4. [Examples](examples) ## For Developers diff --git a/docs/config/README.md b/docs/config/README.md index a320904..141bcfc 100644 --- a/docs/config/README.md +++ b/docs/config/README.md @@ -183,112 +183,6 @@ In this case, it uses [iperf](https://en.wikipedia.org/wiki/Iperf) to test netwo For more information about presets, please check out [presets]. -### blinksocks over TLS - -By default, blinksocks use "tcp" as transport, but you can take advantage of TLS technology to protect your data well. - -To enable blinksocks over TLS, you can: - -1. Generate `key.pem` and `cert.pem` on server - -``` -// Generate self-signed certificate -$ openssl req -x509 -newkey rsa:4096 -nodes -sha256 -subj '/CN=localhost' \ - -keyout key.pem -out cert.pem -``` - -> NOTE: Remember the **Common Name(CN)** you typed in the command line. - -2. Server config - -Change `tcp://` to `tls://`, then provide `tls_key` and `tls_cert`: - -``` -{ - "service": "tls://:", - "tls_key": "key.pem", - "tls_cert": "cert.pem", - ... -} -``` - -3. Client config - -Change server's `tcp://` to `tls://`, then provide `tls_cert`: - -``` -{ - ... - "server": { - "service": "tls://:", // take care of - "tls_cert": "cert.pem", - "tls_cert_self_signed": true - ... - }, - ... -} -``` - -> NOTE: You don't have to set `"tls_cert_self_signed": true` if your certificate is NOT self-signed. - -### blinksocks over WebSocket - -Like blinksocks over TLS, it's much easier to setup a websocket tunnel: - -1. Server config - -``` -{ - "service": "ws://:", - ... -} -``` - -2. Client config - -``` -{ - ... - "server": { - "service": "ws://:", - ... - }, - ... -} -``` - -### blinksocks over WebSocket/TLS - -Similar to `blinksocks over TLS`, but the protocol part is become `wss` other than `tls`: - -1. Server config - -``` -{ - "service": "wss://:", - "tls_key": "key.pem", - "tls_cert": "cert.pem", - ... -} -``` - -2. Client config - -``` -{ - ... - "server": { - "service": "wss://:", - "tls_cert": "cert.pem", - "tls_cert_self_signed": true - ... - }, - ... -} -``` - -> NOTE: You don't have to set `"tls_cert_self_signed": true` if your certificate is NOT self-signed. - ### Access Control List You can enable ACL on **server** by setting **acl: true** and provide a acl configuration file in **acl_conf**: @@ -322,36 +216,6 @@ Rules in **acl.txt** has a priority from lower to higher. > NOTE: acl requires a restart each time you updated **acl_conf**. -### Multiplexing - -Since blinksocks v2.9.0, blinksocks supports TCP/TLS/WS multiplexing. - -You can enable this feature easily by setting `mux: true` on both client and server, and set `mux_concurrency: ` on client. - -1. Server config - -``` -{ - "mux": true, - ... -} -``` - -2. Client config - -``` -{ - ... - "server": { - ... - "mux": true, - "mux_concurrency": 10 - ... - }, - ... -} -``` - ### Log Path Specify a relative or absolute path to store log file, if no `log_path` provided, log file named `bs-[type].log` will be stored in the working directory. diff --git a/docs/examples/README.md b/docs/examples/README.md new file mode 100644 index 0000000..b6ff855 --- /dev/null +++ b/docs/examples/README.md @@ -0,0 +1,3 @@ +# Examples + +Here I post some particle configuration of blinksocks, please enter each directory for more details. diff --git a/docs/examples/multiplexing/README.md b/docs/examples/multiplexing/README.md new file mode 100644 index 0000000..4964769 --- /dev/null +++ b/docs/examples/multiplexing/README.md @@ -0,0 +1,31 @@ +# Multiplexing + +**Minimal Version Required: v2.9.x** + +blinksocks supports TCP/TLS/WS multiplexing. + +You can enable this feature easily by setting `"mux": true` on both client and server, and set `"mux_concurrency": ` on client. + +1. Client config + +``` +{ + ... + "server": { + ... + "mux": true, + "mux_concurrency": 10 + ... + }, + ... +} +``` + +2. Server config + +``` +{ + "mux": true, + ... +} +``` diff --git a/docs/examples/multiplexing/blinksocks.client.json b/docs/examples/multiplexing/blinksocks.client.json new file mode 100644 index 0000000..e574c05 --- /dev/null +++ b/docs/examples/multiplexing/blinksocks.client.json @@ -0,0 +1,23 @@ +{ + "service": "socks5://127.0.0.1:1080", + "server": { + "service": "tcp://example.com:17720", + "key": "#{N-^!6{SExKTQ|b", + "presets": [ + { + "name": "ss-base" + }, + { + "name": "obfs-random-padding" + }, + { + "name": "ss-stream-cipher", + "params": { + "method": "aes-128-ctr" + } + } + ], + "mux": true, + "mux_concurrency": 10 + } +} diff --git a/docs/examples/multiplexing/blinksocks.server.json b/docs/examples/multiplexing/blinksocks.server.json new file mode 100644 index 0000000..002f645 --- /dev/null +++ b/docs/examples/multiplexing/blinksocks.server.json @@ -0,0 +1,19 @@ +{ + "service": "tcp://0.0.0.0:17720", + "key": "#{N-^!6{SExKTQ|b", + "presets": [ + { + "name": "ss-base" + }, + { + "name": "obfs-random-padding" + }, + { + "name": "ss-stream-cipher", + "params": { + "method": "aes-128-ctr" + } + } + ], + "mux": true +} diff --git a/docs/examples/obfs-random-padding/README.md b/docs/examples/obfs-random-padding/README.md new file mode 100644 index 0000000..6a1938b --- /dev/null +++ b/docs/examples/obfs-random-padding/README.md @@ -0,0 +1,23 @@ +# obfs-random-padding + +`obfs-random-padding` provides ability to prevent traffic analysis(based on sequence of round trip packet length between client and server): + +## To prevent traffic analysis + +``` +"presets": [ + {"name": "ss-base"}, + {"name": "obfs-random-padding"}, + {"name": "ss-stream-cipher","params": {"method": "aes-128-ctr"}} +] +``` + +## To prevent traffic analysis and ensure integrity as well + +``` +"presets": [ + {"name": "ss-base"}, + {"name": "obfs-random-padding"}, + {"name": "ss-aead-cipher","params": {"method": "aes-128-gcm"}} +] +``` diff --git a/docs/examples/obfs-random-padding/blinksocks.client.json b/docs/examples/obfs-random-padding/blinksocks.client.json new file mode 100644 index 0000000..31b466b --- /dev/null +++ b/docs/examples/obfs-random-padding/blinksocks.client.json @@ -0,0 +1,21 @@ +{ + "service": "socks5://127.0.0.1:1080", + "server": { + "service": "tcp://example.com:50102", + "key": "&8[j;(>fjLGm,db]", + "presets": [ + { + "name": "ss-base" + }, + { + "name": "obfs-random-padding" + }, + { + "name": "ss-stream-cipher", + "params": { + "method": "aes-128-ctr" + } + } + ] + } +} diff --git a/docs/examples/obfs-random-padding/blinksocks.server.json b/docs/examples/obfs-random-padding/blinksocks.server.json new file mode 100644 index 0000000..5bc8cbb --- /dev/null +++ b/docs/examples/obfs-random-padding/blinksocks.server.json @@ -0,0 +1,18 @@ +{ + "service": "tcp://0.0.0.0:50102", + "key": "&8[j;(>fjLGm,db]", + "presets": [ + { + "name": "ss-base" + }, + { + "name": "obfs-random-padding" + }, + { + "name": "ss-stream-cipher", + "params": { + "method": "aes-128-ctr" + } + } + ] +} \ No newline at end of file diff --git a/docs/examples/obfs-tls-session-ticket/README.md b/docs/examples/obfs-tls-session-ticket/README.md new file mode 100644 index 0000000..cbc7427 --- /dev/null +++ b/docs/examples/obfs-tls-session-ticket/README.md @@ -0,0 +1,7 @@ +# obfs-tls-session-ticket + +**Minimal Version Required: v2.x** + +You can append a **http** or **tls** obfuscator to preset list to avoid bad [QoS], **obfs-tls1.2-ticket** is recommended. + +[QoS]: https://en.wikipedia.org/wiki/Quality_of_service diff --git a/docs/examples/obfs-tls-session-ticket/blinksocks.client.json b/docs/examples/obfs-tls-session-ticket/blinksocks.client.json new file mode 100644 index 0000000..2f29a7f --- /dev/null +++ b/docs/examples/obfs-tls-session-ticket/blinksocks.client.json @@ -0,0 +1,26 @@ +{ + "service": "socks5://127.0.0.1:1080", + "server": { + "service": "tcp://example.com:14938", + "key": "had2a8#(kVKA2&gx", + "presets": [ + { + "name": "ss-base" + }, + { + "name": "ss-aead-cipher", + "params": { + "method": "aes-256-gcm" + } + }, + { + "name": "obfs-tls1.2-ticket", + "params": { + "sni": [ + "example.com" + ] + } + } + ] + } +} diff --git a/docs/examples/obfs-tls-session-ticket/blinksocks.server.json b/docs/examples/obfs-tls-session-ticket/blinksocks.server.json new file mode 100644 index 0000000..209318b --- /dev/null +++ b/docs/examples/obfs-tls-session-ticket/blinksocks.server.json @@ -0,0 +1,23 @@ +{ + "service": "tcp://0.0.0.0:14938", + "key": "had2a8#(kVKA2&gx", + "presets": [ + { + "name": "ss-base" + }, + { + "name": "ss-aead-cipher", + "params": { + "method": "aes-256-gcm" + } + }, + { + "name": "obfs-tls1.2-ticket", + "params": { + "sni": [ + "example.com" + ] + } + } + ] +} diff --git a/docs/examples/shadowsocks/README.md b/docs/examples/shadowsocks/README.md new file mode 100644 index 0000000..2d331d6 --- /dev/null +++ b/docs/examples/shadowsocks/README.md @@ -0,0 +1,23 @@ +# shadowsocks + +**Minimal Version Required: v1.x** + +To work with **shadowsocks**, you can just add two presets: + +**AEAD Ciphers(Newer Versions), Recommend** + +``` +"presets": [ + {"name": "ss-base"}, + {"name": "ss-aead-cipher", "params": {"method": "aes-256-gcm"}} +] +``` + +**Steam Ciphers(Older Versions)** + +``` +"presets": [ + {"name": "ss-base"}, + {"name": "ss-stream-cipher", "params": {"method": "aes-256-cfb"}} +] +``` diff --git a/docs/examples/shadowsocks/blinksocks.client.json b/docs/examples/shadowsocks/blinksocks.client.json new file mode 100644 index 0000000..e799897 --- /dev/null +++ b/docs/examples/shadowsocks/blinksocks.client.json @@ -0,0 +1,18 @@ +{ + "service": "socks5://127.0.0.1:1080", + "server": { + "service": "tcp://example.com:49849", + "key": "XyDw&JndtwhV?m<6", + "presets": [ + { + "name": "ss-base" + }, + { + "name": "ss-aead-cipher", + "params": { + "method": "aes-256-gcm" + } + } + ] + } +} diff --git a/docs/examples/shadowsocks/blinksocks.server.json b/docs/examples/shadowsocks/blinksocks.server.json new file mode 100644 index 0000000..1820bbc --- /dev/null +++ b/docs/examples/shadowsocks/blinksocks.server.json @@ -0,0 +1,15 @@ +{ + "service": "tcp://0.0.0.0:49849", + "key": "XyDw&JndtwhV?m<6", + "presets": [ + { + "name": "ss-base" + }, + { + "name": "ss-stream-cipher", + "params": { + "method": "aes-256-gcm" + } + } + ] +} diff --git a/docs/examples/shadowsocksr/README.md b/docs/examples/shadowsocksr/README.md new file mode 100644 index 0000000..350594f --- /dev/null +++ b/docs/examples/shadowsocksr/README.md @@ -0,0 +1,42 @@ +# shadowsocksr + +**Minimal Version Required: v2.x** + +> NOTE: To work with shadowsocksR, you must add both "ss-base" and "ss-stream-cipher". + +
+ Notice in shadowsocksR config + + ``` + { + ... + "method": "aes-128-ctr", + "protocol": "auth_aes128_md5", + "protocol_param": "", // protocol_param must be empty + "obfs": "plain", // obfs must be "plain" + "obfs_param": "", + ... + } + ``` + +
+ +**auth_aes128_md5 / auth_aes128_sha1** + +``` +"presets": [ + {"name": "ss-base"}, + {"name": "ssr-auth-aes128-md5"}, + {"name": "ss-stream-cipher", "params": {"method": "aes-256-ctr"}} +] +``` + +**auth_chain_a / auth_chain_b** + +``` +"presets": [ + {"name": "ss-base"}, + {"name": "ssr-auth-chain-a"}, + {"name": "ss-stream-cipher", "params": {"method": "none"}} +] +``` diff --git a/docs/examples/shadowsocksr/blinksocks.client.json b/docs/examples/shadowsocksr/blinksocks.client.json new file mode 100644 index 0000000..9be7f8f --- /dev/null +++ b/docs/examples/shadowsocksr/blinksocks.client.json @@ -0,0 +1,21 @@ +{ + "service": "socks5://127.0.0.1:1080", + "server": { + "service": "tcp://example.com:24045", + "key": "?4H}vrE_[WQj9[>F", + "presets": [ + { + "name": "ss-base" + }, + { + "name": "ssr-auth-chain-a" + }, + { + "name": "ss-stream-cipher", + "params": { + "method": "none" + } + } + ] + } +} diff --git a/docs/examples/shadowsocksr/blinksocks.server.json b/docs/examples/shadowsocksr/blinksocks.server.json new file mode 100644 index 0000000..c33b6cf --- /dev/null +++ b/docs/examples/shadowsocksr/blinksocks.server.json @@ -0,0 +1,18 @@ +{ + "service": "tcp://0.0.0.0:24045", + "key": "?4H}vrE_[WQj9[>F", + "presets": [ + { + "name": "ss-base" + }, + { + "name": "ssr-auth-chain-a" + }, + { + "name": "ss-stream-cipher", + "params": { + "method": "none" + } + } + ] +} diff --git a/docs/examples/tls/README.md b/docs/examples/tls/README.md new file mode 100644 index 0000000..48da9df --- /dev/null +++ b/docs/examples/tls/README.md @@ -0,0 +1,40 @@ +# tls + +**Minimal Version Required: v2.x** + +blinksocks can transfer data using `tls`: + +``` ++-------------+ +-------------+ +------------+ +| | tls://site.com/path | | tcp:// | | +| bs-client <-----------------------> bs-server <-----------> Target | +| | | | | | ++-------------+ +-------------+ +------------+ +``` + +When use `tls://` as transport, make sure both `tls_cert` and `tls_key` is provided to `bs-server`. + +> If your are using self-signed certificate on server, please also provide the same `tls_cert` on client and also set `"tls_cert_self_signed": true`. + +Make sure you provide **Common Name** of certificate NOT IP in client config: + +``` +{ + ... + "server": { + "service": "tls://:", + "tls_cert": "cert.pem", + "tls_cert_self_signed": true + ... + }, + ... +} +``` + +## Generate key.pem and cert.pem + +``` +// self-signed certificate +$ openssl req -x509 -newkey rsa:4096 -nodes -sha256 -subj '/CN=example.com' \ + -keyout key.pem -out cert.pem +``` diff --git a/docs/examples/tls/blinksocks.client.json b/docs/examples/tls/blinksocks.client.json new file mode 100644 index 0000000..81280b6 --- /dev/null +++ b/docs/examples/tls/blinksocks.client.json @@ -0,0 +1,17 @@ +{ + "service": "socks5://127.0.0.1:1080", + "server": { + "service": "tls://example.com:11902", + "key": "NdFCdXFK/TTP2GdU", + "presets": [ + { + "name": "ss-base" + }, + { + "name": "obfs-random-padding" + } + ], + "tls_cert": "cert.pem", + "tls_cert_self_signed": true + } +} diff --git a/docs/examples/tls/blinksocks.server.json b/docs/examples/tls/blinksocks.server.json new file mode 100644 index 0000000..447d673 --- /dev/null +++ b/docs/examples/tls/blinksocks.server.json @@ -0,0 +1,14 @@ +{ + "service": "tls://0.0.0.0:11902", + "key": "NdFCdXFK/TTP2GdU", + "presets": [ + { + "name": "ss-base" + }, + { + "name": "obfs-random-padding" + } + ], + "tls_key": "key.pem", + "tls_cert": "cert.pem" +} diff --git a/docs/examples/v2ray-vmess/README.md b/docs/examples/v2ray-vmess/README.md new file mode 100644 index 0000000..d9256c4 --- /dev/null +++ b/docs/examples/v2ray-vmess/README.md @@ -0,0 +1,67 @@ +# v2ray-vmess + +**Minimal Version Required: v2.x** + +> NOTE: To work with v2ray vmess, you should only provide "v2ray-vmess" in preset list. + +
+ v2ray client + + ``` + "outbound": { + "protocol": "vmess", + "settings": { + "vnext": [ + { + "address": "127.0.0.1", + "port": 10086, + "users": [ + { + "id": "c2485913-4e9e-41eb-8cc5-b2e7db8d3bc7", + "security": "aes-128-gcm", + "alterId": 0 // [must be the default value: 0] + } + ] + } + ] + }, + "mux": { + "enabled": false // [must be false] + } + }, + ``` + +
+ +
+ v2ray server + +``` + "inbound": { + "port": 10086, + "protocol": "vmess", + "settings": { + "clients": [ + { + "id": "c2485913-4e9e-41eb-8cc5-b2e7db8d3bc7", + "level": 1, + "alterId": 0 // [must be the default value: 0] + } + ] + } + }, +``` + +
+ +``` +"presets": [ + { + "name": "v2ray-vmess", + "params": { + "id": "c2485913-4e9e-41eb-8cc5-b2e7db8d3bc7", + "security": "aes-128-gcm" + } + } +] +``` diff --git a/docs/examples/v2ray-vmess/blinksocks.client.json b/docs/examples/v2ray-vmess/blinksocks.client.json new file mode 100644 index 0000000..b62a189 --- /dev/null +++ b/docs/examples/v2ray-vmess/blinksocks.client.json @@ -0,0 +1,16 @@ +{ + "service": "socks5://127.0.0.1:1080", + "server": { + "service": "tcp://example.com:65282", + "key": "z{]5AWaxEFCMTKA,", + "presets": [ + { + "name": "v2ray-vmess", + "params": { + "id": "c2485913-4e9e-41eb-8cc5-b2e7db8d3bc7", + "security": "aes-128-gcm" + } + } + ] + } +} diff --git a/docs/examples/v2ray-vmess/blinksocks.server.json b/docs/examples/v2ray-vmess/blinksocks.server.json new file mode 100644 index 0000000..34697bf --- /dev/null +++ b/docs/examples/v2ray-vmess/blinksocks.server.json @@ -0,0 +1,13 @@ +{ + "service": "tcp://0.0.0.0:65282", + "key": "z{]5AWaxEFCMTKA,", + "presets": [ + { + "name": "v2ray-vmess", + "params": { + "id": "c2485913-4e9e-41eb-8cc5-b2e7db8d3bc7", + "security": "aes-128-gcm" + } + } + ] +} diff --git a/docs/examples/websocket-caddy-tls/Caddyfile b/docs/examples/websocket-caddy-tls/Caddyfile new file mode 100644 index 0000000..6279445 --- /dev/null +++ b/docs/examples/websocket-caddy-tls/Caddyfile @@ -0,0 +1,9 @@ +example.com { + proxy / 127.0.0.1:59463 { + websocket + header_upstream Host {host} + header_upstream X-Real-IP {remote} + header_upstream X-Forwarded-For {remote} + header_upstream X-Forwarded-Proto {scheme} + } +} diff --git a/docs/examples/websocket-caddy-tls/README.md b/docs/examples/websocket-caddy-tls/README.md new file mode 100644 index 0000000..e80ddf7 --- /dev/null +++ b/docs/examples/websocket-caddy-tls/README.md @@ -0,0 +1,20 @@ +# websocket-caddy-tls + +**Minimal Version Required: v3.3.1** + +blinksocks can transfer data through [caddy] proxy server using [WebSocket/TLS]: + +``` + +--------------------------------------------------+ + | Caddy Server | ++-------------+ | +-----------+ | +------------+ +| | wss://site.com/path | :433 ws://127.0.0.1:1234 | | | tcp:// | | +| bs-client <-----------------------> proxy /path +--------------------> bs-server <-------------> Target | +| | (encrypted) | (encrypted) | | | (raw) | | ++-------------+ | +-----------+ | +------------+ + | | + +--------------------------------------------------+ +``` + +[caddy]: https://caddyserver.com +[WebSocket/TLS]: ../websocket-tls diff --git a/docs/examples/websocket-caddy-tls/blinksocks.client.json b/docs/examples/websocket-caddy-tls/blinksocks.client.json new file mode 100644 index 0000000..430c7af --- /dev/null +++ b/docs/examples/websocket-caddy-tls/blinksocks.client.json @@ -0,0 +1,15 @@ +{ + "service": "socks5://127.0.0.1:1080", + "server": { + "service": "wss://example.com:443/your-custom-path", + "key": "8;:2%]zTbPc[2g-%", + "presets": [ + { + "name": "ss-base" + }, + { + "name": "obfs-random-padding" + } + ] + } +} diff --git a/docs/examples/websocket-caddy-tls/blinksocks.server.json b/docs/examples/websocket-caddy-tls/blinksocks.server.json new file mode 100644 index 0000000..36b748e --- /dev/null +++ b/docs/examples/websocket-caddy-tls/blinksocks.server.json @@ -0,0 +1,12 @@ +{ + "service": "ws://0.0.0.0:59463/your-custom-path", + "key": "8;:2%]zTbPc[2g-%", + "presets": [ + { + "name": "ss-base" + }, + { + "name": "obfs-random-padding" + } + ] +} diff --git a/docs/examples/websocket-tls/README.md b/docs/examples/websocket-tls/README.md new file mode 100644 index 0000000..eee265f --- /dev/null +++ b/docs/examples/websocket-tls/README.md @@ -0,0 +1,20 @@ +# websocket-tls + +**Minimal Version Required: v3.3.1** + +blinksocks can transfer data using [WebSocket/TLS]: + + +``` ++-------------+ +-------------+ +------------+ +| | wss://site.com/path | | tcp:// | | +| bs-client <-----------------------> bs-server <-----------> Target | +| | (encrypted) | | (raw) | | ++-------------+ +-------------+ +------------+ +``` + +When use `wss://` as transport, make sure both `tls_cert` and `tls_key` is provided to `bs-server`. + +> If your are using self-signed certificate on server, please also provide the same `tls_cert` on client and set `"tls_cert_self_signed": true`. + +[WebSocket/TLS]: ../websocket-tls diff --git a/docs/examples/websocket-tls/blinksocks.client.json b/docs/examples/websocket-tls/blinksocks.client.json new file mode 100644 index 0000000..ae99748 --- /dev/null +++ b/docs/examples/websocket-tls/blinksocks.client.json @@ -0,0 +1,17 @@ +{ + "service": "socks5://127.0.0.1:1080", + "server": { + "service": "wss://example.com:48079", + "key": "98{U64+Z4bX#d,Ra", + "presets": [ + { + "name": "ss-base" + }, + { + "name": "obfs-random-padding" + } + ], + "tls_cert": "cert.pem", + "tls_cert_self_signed": true + } +} diff --git a/docs/examples/websocket-tls/blinksocks.server.json b/docs/examples/websocket-tls/blinksocks.server.json new file mode 100644 index 0000000..d9c5b41 --- /dev/null +++ b/docs/examples/websocket-tls/blinksocks.server.json @@ -0,0 +1,14 @@ +{ + "service": "wss://0.0.0.0:48079", + "key": "98{U64+Z4bX#d,Ra", + "presets": [ + { + "name": "ss-base" + }, + { + "name": "obfs-random-padding" + } + ], + "tls_key": "key.pem", + "tls_cert": "cert.pem" +} diff --git a/docs/examples/websocket/README.md b/docs/examples/websocket/README.md new file mode 100644 index 0000000..0233849 --- /dev/null +++ b/docs/examples/websocket/README.md @@ -0,0 +1,13 @@ +# websocket + +**Minimal Version Required: v2.6.2** + +blinksocks can transfer data using `websocket`: + +``` ++-------------+ +-------------+ +------------+ +| | ws://site.com/path | | tcp:// | | +| bs-client <----------------------> bs-server <-----------> Target | +| | | | | | ++-------------+ +-------------+ +------------+ +``` diff --git a/docs/examples/websocket/blinksocks.client.json b/docs/examples/websocket/blinksocks.client.json new file mode 100644 index 0000000..0496edf --- /dev/null +++ b/docs/examples/websocket/blinksocks.client.json @@ -0,0 +1,21 @@ +{ + "service": "socks5://127.0.0.1:1080", + "server": { + "service": "ws://127.0.0.1:6336", + "key": "?B4-y[tsFQCV/zK%", + "presets": [ + { + "name": "ss-base" + }, + { + "name": "obfs-random-padding" + }, + { + "name": "ss-stream-cipher", + "params": { + "method": "aes-128-ctr" + } + } + ] + } +} diff --git a/docs/examples/websocket/blinksocks.server.json b/docs/examples/websocket/blinksocks.server.json new file mode 100644 index 0000000..a4e76c4 --- /dev/null +++ b/docs/examples/websocket/blinksocks.server.json @@ -0,0 +1,18 @@ +{ + "service": "ws://0.0.0.0:6336", + "key": "?B4-y[tsFQCV/zK%", + "presets": [ + { + "name": "ss-base" + }, + { + "name": "obfs-random-padding" + }, + { + "name": "ss-stream-cipher", + "params": { + "method": "aes-128-ctr" + } + } + ] +} diff --git a/docs/presets/README.md b/docs/presets/README.md index 6d84ab9..e671f4d 100644 --- a/docs/presets/README.md +++ b/docs/presets/README.md @@ -326,7 +326,7 @@ all features from **ss-aead-cipher** and prevent server from being detected by p ## Have trouble in choosing presets? -Here is a [list](./RECOMMENDATIONS.md) of recommended conbinations. +Here is a [list](../examples) of recommended conbinations. [base-auth]: ../../src/presets/base-auth.js [ss-base]: ../../src/presets/ss-base.js diff --git a/docs/presets/RECOMMENDATIONS.md b/docs/presets/RECOMMENDATIONS.md deleted file mode 100644 index ea0d017..0000000 --- a/docs/presets/RECOMMENDATIONS.md +++ /dev/null @@ -1,167 +0,0 @@ -# Recommended Combinations - -## Work with shadowsocks - -To work with **shadowsocks**, please choose one of the following configurations: - -**Steam Ciphers(Older Versions)** - -``` -"presets": [ - {"name": "ss-base"}, - {"name": "ss-stream-cipher", "params": {"method": "aes-256-cfb"}} -] -``` - -**AEAD Ciphers(Newer Versions)** - -``` -"presets": [ - {"name": "ss-base"}, - {"name": "ss-aead-cipher", "params": {"method": "aes-256-gcm"}} -] -``` - -## Work with shadowsocksR - -> NOTE: To work with shadowsocksR, you must add both "ss-base" and "ss-stream-cipher". - -
- Notice in shadowsocksR config - - ``` - { - ... - "method": "aes-128-ctr", - "protocol": "auth_aes128_md5", - "protocol_param": "", // protocol_param must be empty - "obfs": "plain", // obfs must be "plain" - "obfs_param": "", - ... - } - ``` - -
- -**auth_aes128_md5 / auth_aes128_sha1** - -``` -"presets": [ - {"name": "ss-base"}, - {"name": "ssr-auth-aes128-md5"}, - {"name": "ss-stream-cipher", "params": {"method": "aes-256-ctr"}} -] -``` - -**auth_chain_a / auth_chain_b** - -``` -"presets": [ - {"name": "ss-base"}, - {"name": "ssr-auth-chain-a"}, - {"name": "ss-stream-cipher", "params": {"method": "none"}} -] -``` - -## Work with v2ray vmess - -> Notice in v2ray configs: - -
- v2ray client - - ``` - "outbound": { - "protocol": "vmess", - "settings": { - "vnext": [ - { - "address": "127.0.0.1", - "port": 10086, - "users": [ - { - "id": "c2485913-4e9e-41eb-8cc5-b2e7db8d3bc7", - "security": "aes-128-gcm", - "alterId": 0 // [must be the default value: 0] - } - ] - } - ] - }, - "mux": { - "enabled": false // [must be false] - } - }, - ``` - -
- -
- v2ray server - -``` - "inbound": { - "port": 10086, - "protocol": "vmess", - "settings": { - "clients": [ - { - "id": "c2485913-4e9e-41eb-8cc5-b2e7db8d3bc7", - "level": 1, - "alterId": 0 // [must be the default value: 0] - } - ] - } - }, -``` - -
- -``` -"presets": [ - { - "name": "v2ray-vmess", - "params": { - "id": "c2485913-4e9e-41eb-8cc5-b2e7db8d3bc7", - "security": "aes-128-gcm" - } - } -] -``` - -## Avoid Bad QoS - -You can use **http** or **tls** obfuscator to avoid bad [QoS], **tls** is recommended. - -``` -"presets": [ - {"name": "ss-base"}, - {"name": "ss-aead-cipher", "params": {"method": "aes-256-gcm"}}, - {"name": "obfs-tls1.2-ticket", "params": {"sni": ["example.com"]}} -] -``` - -## To prevent traffic analysis - -``` -"presets": [ - {"name": "ss-base"}, - {"name": "obfs-random-padding"}, - {"name": "ss-stream-cipher","params": {"method": "aes-128-ctr"}} -] -``` - -## To prevent traffic analysis and ensure integrity as well - -``` -"presets": [ - {"name": "ss-base"}, - {"name": "obfs-random-padding"}, - {"name": "ss-aead-cipher","params": {"method": "aes-128-gcm"}} -] -``` - -> You can also check out [benchmark] to choose a combination you prefer. - -[QoS]: https://en.wikipedia.org/wiki/Quality_of_service -[benchmark]: ../benchmark/README.md