moony/blinksocks
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

docs: update

Browse Source
This commit is contained in:
Micooz 2017-09-05 14:36:33 +08:00
parent 730db0f29f
commit 1be6d0f0e1
No known key found for this signature in database
GPG Key ID: 002FB5DD584D6CB1
7 changed files with 95 additions and 76 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
README.md
View File

@ -7,7 +7,6 @@
[![devDependencies](https://img.shields.io/david/dev/blinksocks/blinksocks.svg)](https://www.npmjs.com/package/blinksocks)
[![Travis](https://img.shields.io/travis/blinksocks/blinksocks.svg)](https://travis-ci.org/blinksocks/blinksocks)
[![Coverage](https://img.shields.io/codecov/c/github/blinksocks/blinksocks/master.svg)](https://codecov.io/gh/blinksocks/blinksocks)
[![%e2%9d%a4](https://img.shields.io/badge/made%20with-%e2%9d%a4-ff69b4.svg)](https://github.com/blinksocks/blinksocks)
A framework for building composable proxy protocol stack.
@ -16,13 +15,14 @@ A framework for building composable proxy protocol stack.
## Features
* Simple proxy interface for Socks5/Socks4/Socks4a and HTTP.
* Cross-platform: running on Linux, Windows and macOS.
* Transmit over TCP or [TLS](docs/config).
* Customizable protocols and middlewares: using [Presets](docs/presets).
* Customizable relay behaviours: using [Behaviours](docs/behaviours).
* Portable/Executable versions available. [Download Here](https://github.com/blinksocks/blinksocks/releases)
* Partially compatible with **shadowsocks**. [#27](https://github.com/blinksocks/blinksocks/issues/27)
* Simple proxy interface for Socks5/Socks4/Socks4a and HTTP.
* Transmit over TCP or [TLS](https://github.com/blinksocks/blinksocks/tree/master/docs/config#blinksocks-over-tls).
* Customizable protocols and functional middlewares: using [presets](docs/presets).
* Over **30+** built-in combinations with [benchmark](docs/benchmark).
* Easy and powerful Access Control([ACL](https://github.com/blinksocks/blinksocks/tree/master/docs/presets#access-control)): auto ban, speed limiter.
* Portable/Executable versions available: [download here](https://github.com/blinksocks/blinksocks/releases).
* Compatible with **shadowsocks**(partially). [#27](https://github.com/blinksocks/blinksocks/issues/27)
## GUI ready

1
docs/README.md
View File

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

27
docs/config/README.md
View File

@ -21,12 +21,10 @@ $ blinksocks init
| presets | preset list in order | - | - | see [presets] |
| presets[i].name | preset name | - | - | - |
| presets[i].params | preset params | - | - | - |
| behaviours | a list of behaviours | Yes | - | see [behaviours] |
| behaviours[i].name | behaviour name | - | - | - |
| behaviours[i].params | behaviour params | - | - | - |
| tls_key | private key for TLS | - | - | required on server if "transport" is "tls" |
| tls_cert | server certificate | - | - | required on both client and server if "transport" is "tls" |
| timeout | timeout for each connection | Yes | 600 | in seconds |
| redirect | target to redirect when preset fail | Yes | "" | <host or ip>:<port> |
| workers | the number of sub-process | Yes | 0 | cluster mode when workers > 0 |
| dns | an ip list of DNS server | Yes | [] | - |
| dns_expire | DNS cache expiration time | Yes | 3600 | in seconds |
@ -58,28 +56,6 @@ Blinksocks will detect which server is the fastest in intervals using [balancer.
For more information about presets, please check out [presets].
### Behaviours
Behaviours are customizable event handlers for Relay. `behaviours` is an object with several "events" which may occured in Socket.
You can specify a behaviour to different events using different handlers. The following config shows when any preset failed, socket should close the connection in a random timeout picked from 10 to 40 seconds:
```json
{
"behaviours": {
"on-preset-failed": {
"name": "random-timeout",
"params": {
"min": 10,
"max": 40
}
}
},
}
```
For more information about behaviours, please check out [behaviours].
### blinksocks over TLS
By default, blinksocks use "tcp" as transport, but you can also take advantage of TLS technology to protect your data. To use blinksocks over TLS, you should:
@ -178,5 +154,4 @@ You can enable cluster mode by setting `workers` greater than zero, cluster mode
[balancer.js]: ../../src/core/balancer.js
[presets]: ../presets
[behaviours]: ../behaviours
[winston]: https://github.com/winstonjs/winston

5
docs/development/architecture/README.md
View File

@ -270,7 +270,10 @@ export default class CustomPreset extends IPreset {
| \_\_PRESETS\_\_ |
| \_\_DNS\_\_ |
| \_\_DNS_EXPIRE\_\_ |
| \_\_BEHAVIOURS\_\_ |
| \_\_TLS_CERT\_\_ |
| \_\_TLS_KEY\_\_ |
| \_\_TIMEOUT\_\_ |
| \_\_REDIRECT\_\_ |
| \_\_LOG_PATH\_\_ |
| \_\_LOG_LEVEL\_\_ |
| \_\_WORKERS\_\_ |

18
docs/development/steps/README.md
View File

@ -18,14 +18,14 @@ Prepare your configurations(**blinksocks.client.json** and **blinksocks.server.j
### Debug Mode(Use Chrome Developer Tool)
Debug in Chrome requires Node.js v6 and Chrome 57 or later.
Debug in Chrome requires Node.js v6.x and Chrome 57 or later.
```
$ npm run debug:client
$ npm run debug:server
```
Then open **chrome://inspect/#devices** in Chrome. Click **inspect** under **bin/cli-client.js** or **bin/cli-server.js**.
Then open **chrome://inspect/#devices** in Chrome, configure **Target discovery settings** then click **inspect** below **Remote Target**.
### Production Mode
@ -37,19 +37,9 @@ $ npm run server
This will run compiled code under **build/**.
Notice that you can change program behaviour using the following environment variants:
## Test
| NAME | VALUE |
| :-------- | :-------------------------- |
| NODE_ENV | "development", "production" |
| RUN_AS | "server", "client" |
If **RUN_AS** provided, log file name will be **blinksocks-[RUN_AS].log**, otherwise **blinksocks.log**. This is useful
to distinguish log files in different roles.
## Verify
Any application support HTTP/Socks5/Socks4/Socks4a can be used for verification.
Any application support HTTP/Socks5/Socks4/Socks4a can be used for testing.
For example(use curl):

105
docs/presets/README.md
View File

@ -10,6 +10,7 @@ Presets are chaining and composable, built-in presets are listed here. If you wa
* [tunnel](#tunnel)
* [stats](#stats)
* [tracker](#tracker)
* [access-control](#access-control)
**shadowsocks**
@ -71,7 +72,7 @@ $ curl -L --socks5-hostname localhost:1080 https://www.bing.com
This proxy does not use any proxy protocols, just proxy original traffic to a permanent destination.
| PARAMS | DESCRIPTION | DEFAULT |
| PARAMS | DESCRIPTION | DEFAULT |
| :------------- | :--------------- | :------ |
| host(optional) | destination host | - |
| port(optional) | destination port | - |
@ -109,7 +110,7 @@ In this case, it's useful to test network performance between client and server
This preset perform statistics among traffic via this preset, you can put it anywhere in preset list to obtain **summary/instant/process** information of specific preset traffic. This preset has no side-effect to the traffic through it.
| PARAMS | DESCRIPTION | DEFAULT |
| PARAMS | DESCRIPTION | DEFAULT |
| :-------------- | :--------------------------- | :------ |
| save_to | path to the result json file | - |
| sample_interval | sample interval in seconds | 30 |
@ -199,6 +200,57 @@ And you can get the track message in your terminal and log files:
[tracker] summary(out/in = 14/9, 5191b/3431b) abstract(127.0.0.1:55566 play.google.com:443 u 555 d 394 u 616 d 165 u 221 156 934 795 d 74 u 43 d 1201 u 51 174 531 d 51 573 u 51 172 841 d 51 854 u 51 d 68)
```
## [access-control]
Easy and powerful Access Control(ACL) to each connection.
> NOTE: This preset is for server use only.
| PARAMS | DESCRIPTION | DEFAULT |
| :-------- | :------------------------------------------------------------ | :------ |
| acl | A path to a text file which contains a list of rules in order | - |
| max_tries | The maximum tries from client | 60 |
> NOTE: you'd better put this preset to the last of the preset list.
```
"presets": [
...,
{
"name": "access-control",
"params": {
"acl": "acl.txt",
"max_tries": 60
}
}
]
```
**acl.txt** for example:
```
# [addr[/mask][:port]] [ban] [max_upload_speed(/s)] [max_download_speed(/s)]
example.com 1 # prevent access to example.com
example.com:* 1 # prevent access to example.com:*, equal to above
example.com:443 1 # prevent access to example.com:443 only
*:25 1 # prevent access to SMTP servers
*:* 1 # prevent all access from/to all endpoints
127.0.0.1 1 # ban localhost
192.168.0.0/16 1 # ban hosts in 192.168.*.*
172.27.1.100 0 120K # limit upload speed to 120KB/s
172.27.1.100 0 - 120K # limit download speed to 120KB/s
172.27.1.100 0 120K 120K # limit upload and download speed to 120KB/s
```
Rules in **acl.txt** has a priority from lower to higher.
If server fail to process client(**by host**) requests over **max_tries** times, client will be **baned immediately**, and a new rule will be appended to the **acl** file.
To recovery unwary ban, you can edit acl file, remove unwanted rule without restarting the program.
> NOTE: rules will take effect immediately each time **acl.txt** was updated.
## [ss-base]
This is a very basic preset which delivers the real destination address from client to server.
@ -213,9 +265,9 @@ This is a very basic preset which delivers the real destination address from cli
The shadowsocks's [stream cipher](https://shadowsocks.org/en/spec/Stream-Ciphers.html).
| PARAMS | DESCRIPTION | DEFAULT |
| :-------- | :------------------------------- | :------ |
| method | encryption and decryption method | - |
| PARAMS | DESCRIPTION | DEFAULT |
| :----- | :------------------------------- | :------ |
| method | encryption and decryption method | - |
`method` can be one of:
@ -233,7 +285,7 @@ camellia-128-cfb, camellia-192-cfb, camellia-256-cfb
{
"name": "ss-stream-cipher",
"params": {
"method": "camellia-256-cfb"
"method": "aes-256-ctr"
}
}
]
@ -243,10 +295,10 @@ camellia-128-cfb, camellia-192-cfb, camellia-256-cfb
The shadowsocks's [aead cipher](https://shadowsocks.org/en/spec/AEAD-Ciphers.html).
| PARAMS | DESCRIPTION | DEFAULT |
| :-------- | :------------------------------- | :------ |
| method | encryption and decryption method | - |
| info | a string to generate subkey | - |
| PARAMS | DESCRIPTION | DEFAULT |
| :----- | :------------------------------- | :------ |
| method | encryption and decryption method | - |
| info | a string to generate subkey | - |
`method` can be one of:
@ -297,9 +349,9 @@ A simple obfuscator to significantly randomize the length of each packet. It can
A http obfuscator, the first round after TCP handshake will wrap data within a random http header
selected from a text file.
| PARAMS | DESCRIPTION | DEFAULT |
| :-------- | :-------------------------------------------- | :------ |
| file | a text file which contains HTTP header paris. | - |
| PARAMS | DESCRIPTION | DEFAULT |
| :----- | :-------------------------------------------- | :------ |
| file | a text file which contains HTTP header paris. | - |
`file` for example:
@ -338,9 +390,9 @@ HTTP/1.1 200 OK
A TLS1.2 obfuscator, do TLS handshake using SessionTicket TLS mechanism, transfer data inside of Application Data.
| PARAMS | DESCRIPTION | DEFAULT |
| :-------- | :--------------------------------------------------------------- | :------ |
| sni | [Server Name Indication], a server name or a list of server name | - |
| PARAMS | DESCRIPTION | DEFAULT |
| :----- | :--------------------------------------------------------------- | :------ |
| sni | [Server Name Indication], a server name or a list of server name | - |
```
"presets": [
@ -363,9 +415,9 @@ It can prevent address from being tampered.
**NOTE**: Using [exp-base-with-padding] with non-cfb ciphers will lose protection.
| PARAMS | DESCRIPTION | DEFAULT |
| :-------- | :------------------------------ | :------ |
| salt | a string for generating padding | - |
| PARAMS | DESCRIPTION | DEFAULT |
| :----- | :------------------------------ | :------ |
| salt | a string for generating padding | - |
```
"presets": [{
@ -385,9 +437,9 @@ It can prevent address from being tampered.
An **experimental** preset combines HMAC and stream encryption. HMAC only guarantees integrity for addressing part.
| PARAMS | DESCRIPTION | DEFAULT |
| :-------- | :------------------------------- | :------ |
| method | encryption and decryption method | - |
| PARAMS | DESCRIPTION | DEFAULT |
| :----- | :------------------------------- | :------ |
| method | encryption and decryption method | - |
`method` can be one of:
@ -410,9 +462,9 @@ camellia-128-cfb, camellia-192-cfb, camellia-256-cfb
An **experimental** to do stream compression/decompression. **Use with caution.**
| PARAMS | DESCRIPTION | DEFAULT |
| :-------- | :----------------------------------- | :------ |
| method | compression and decompression method | - |
| PARAMS | DESCRIPTION | DEFAULT |
| :----- | :----------------------------------- | :------ |
| method | compression and decompression method | - |
`method` can be one of:
@ -430,7 +482,7 @@ gzip, deflate
This preset is based on **ss-aead-cipher**, but added random padding in the front of **each chunk**. This preset inherited
all features from **ss-aead-cipher** and prevent server from being detected by packet length statistics analysis.
| PARAMS | DESCRIPTION | DEFAULT |
| PARAMS | DESCRIPTION | DEFAULT |
| :--------------- | :--------------------------------------- | :------ |
| method | encryption and decryption method | - |
| info | a string to generate subkey | - |
@ -560,6 +612,7 @@ Make some cheat:
[tunnel]: ../../src/presets/tunnel.js
[stats]: ../../src/presets/stats.js
[tracker]: ../../src/presets/tracker.js
[access-control]: ../../src/presets/access-control.js
[exp-compress]: ../../src/presets/exp-compress.js
[ss-base]: ../../src/presets/ss-base.js
[exp-base-with-padding]: ../../src/presets/exp-base-with-padding.js

1
docs/usage/README.md
View File

@ -17,7 +17,6 @@ $ blinksocks --help
-v, --version output blinksocks version
-c, --config file with configuration, usually a json file
--list-presets list all built-in presets
--list-behaviours list all built-in behaviours
-m, --minimal generate minimal json files
Examples: