docs: add examples

This commit is contained in:
Micooz 2018-06-15 14:38:46 +08:00
parent 138636da69
commit a460b7abfb
37 changed files with 667 additions and 311 deletions

@ -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

@ -5,6 +5,7 @@
1. [Usage](usage)
2. [Configuration](config)
3. [Presets](presets)
4. [Examples](examples)
## For Developers

@ -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://<host>:<port>",
"tls_key": "key.pem",
"tls_cert": "cert.pem",
...
}
```
3. Client config
Change server's `tcp://` to `tls://`, then provide `tls_cert`:
```
{
...
"server": {
"service": "tls://<Common Name>:<port>", // take care of <Common Name>
"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://<host>:<port>",
...
}
```
2. Client config
```
{
...
"server": {
"service": "ws://<host>:<port>",
...
},
...
}
```
### blinksocks over WebSocket/TLS
Similar to `blinksocks over TLS`, but the protocol part is become `wss` other than `tls`:
1. Server config
```
{
"service": "wss://<host>:<port>",
"tls_key": "key.pem",
"tls_cert": "cert.pem",
...
}
```
2. Client config
```
{
...
"server": {
"service": "wss://<host>:<port>",
"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: <number>` 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.

3
docs/examples/README.md Normal file

@ -0,0 +1,3 @@
# Examples
Here I post some particle configuration of blinksocks, please enter each directory for more details.

@ -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": <number>` on client.
1. Client config
```
{
...
"server": {
...
"mux": true,
"mux_concurrency": 10
...
},
...
}
```
2. Server config
```
{
"mux": true,
...
}
```

@ -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
}
}

@ -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
}

@ -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"}}
]
```

@ -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"
}
}
]
}
}

@ -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"
}
}
]
}

@ -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

@ -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"
]
}
}
]
}
}

@ -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"
]
}
}
]
}

@ -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"}}
]
```

@ -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"
}
}
]
}
}

@ -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"
}
}
]
}

@ -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".
<details>
<summary>Notice in shadowsocksR config</summary>
```
{
...
"method": "aes-128-ctr",
"protocol": "auth_aes128_md5",
"protocol_param": "", // protocol_param must be empty
"obfs": "plain", // obfs must be "plain"
"obfs_param": "",
...
}
```
</details>
**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"}}
]
```

@ -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"
}
}
]
}
}

@ -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"
}
}
]
}

@ -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://<Common Name>:<port>",
"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
```

@ -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
}
}

@ -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"
}

@ -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.
<details>
<summary>v2ray client</summary>
```
"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]
}
},
```
</details>
<details>
<summary>v2ray server</summary>
```
"inbound": {
"port": 10086,
"protocol": "vmess",
"settings": {
"clients": [
{
"id": "c2485913-4e9e-41eb-8cc5-b2e7db8d3bc7",
"level": 1,
"alterId": 0 // [must be the default value: 0]
}
]
}
},
```
</details>
```
"presets": [
{
"name": "v2ray-vmess",
"params": {
"id": "c2485913-4e9e-41eb-8cc5-b2e7db8d3bc7",
"security": "aes-128-gcm"
}
}
]
```

@ -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"
}
}
]
}
}

@ -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"
}
}
]
}

@ -0,0 +1,9 @@
example.com {
proxy /<your-custom-path> 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}
}
}

@ -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

@ -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"
}
]
}
}

@ -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"
}
]
}

@ -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

@ -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
}
}

@ -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"
}

@ -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 |
| | | | | |
+-------------+ +-------------+ +------------+
```

@ -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"
}
}
]
}
}

@ -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"
}
}
]
}

@ -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

@ -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".
<details>
<summary>Notice in shadowsocksR config</summary>
```
{
...
"method": "aes-128-ctr",
"protocol": "auth_aes128_md5",
"protocol_param": "", // protocol_param must be empty
"obfs": "plain", // obfs must be "plain"
"obfs_param": "",
...
}
```
</details>
**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:
<details>
<summary>v2ray client</summary>
```
"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]
}
},
```
</details>
<details>
<summary>v2ray server</summary>
```
"inbound": {
"port": 10086,
"protocol": "vmess",
"settings": {
"clients": [
{
"id": "c2485913-4e9e-41eb-8cc5-b2e7db8d3bc7",
"level": 1,
"alterId": 0 // [must be the default value: 0]
}
]
}
},
```
</details>
```
"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