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

docs: update

Browse Source
This commit is contained in:
Micooz 2018-02-27 12:08:32 +08:00
parent f3e235ca0a
commit 232d470c92
9 changed files with 225 additions and 436 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

45
README.md
View File

@ -17,23 +17,20 @@
## Features
* Cross-platform: running on Linux, Windows and macOS.
* Lightweight proxy interface for Socks5/Socks4/Socks4a and HTTP(S).
* Transmit data over TCP/UDP, [TLS] or [WebSocket].
* [Multiplexing](docs/config#multiplexing) over TCP/TLS/WS.
* A variety of customizable protocols and functional middlewares: using [presets](docs/presets).
* [External preset import].
* Easy and powerful Access Control([ACL]) and Traffic Control([TC]).
* Support [shadowsocks], [shadowsocksR], [v2ray vmess] protocols.
* **Out of the box** distribution and deployment.
* **Experimental**: [dynamic protocol stack](suites).
* Portable versions are available: [download here](https://github.com/blinksocks/blinksocks/releases).
* Lightweight proxy interfaces: Socks5/Socks4/Socks4a and HTTP.
* Multiple Transport Layers: TCP, UDP, [TLS] and [WebSocket].
* TLS/TLS/WebSocket [multiplexing].
* Convenient protocol [customization].
* Access Control List([ACL]) support.
* Built-In [shadowsocks], [shadowsocksR], [v2ray vmess] protocols.
* Out of the box distribution and deployment.
* [Dynamic Protocol Stack]\(**experimental**\).
## Getting Started
### Requirements
blinksocks is built on top of [Node.js](https://nodejs.org), if you want to use it in an ordinary way or do some hacking,
please install Node.js(**v6.x and above**) on your operating system.
blinksocks is built on top of [Node.js](https://nodejs.org), if you want to use it in an ordinary way or do some hacking, please install **Node.js(v6.x and above)** on your operating system.
### Install or Upgrade
@ -61,19 +58,14 @@ $ blinksocks --help
**executable version(~~Node.js~~, not GUI)**
Tips: You can [download](https://github.com/blinksocks/blinksocks/releases) precompiled executables for different platforms and launch it directly without having Node.js installed.
```
$ ./blinksocks --help // Linux and macOS
$ blinksocks.exe --help // Windows
```
You can [download](https://github.com/blinksocks/blinksocks/releases) precompiled executables for different platforms and launch it directly without having Node.js installed.
> For configuring blinksocks, please refer to [Configuration](docs/config).
## GUI ready(out-of-date)
For desktop use, you can download official [blinksocks-desktop](https://github.com/blinksocks/blinksocks-desktop),
a cross-platform GUI for blinksocks.
For configuring blinksocks, please refer to [Configuration](docs/config).
## Documents
@ -86,7 +78,7 @@ a cross-platform GUI for blinksocks.
### For Developers
1. [Preparation](docs/development/preparation)
2. [Guideline](docs/development/guideline)
2. [Architecture](docs/development/architecture)
3. [Custom Preset](docs/development/custom-preset)
4. [Benchmark](docs/benchmark)
@ -98,11 +90,12 @@ See [contributors](https://github.com/blinksocks/blinksocks/graphs/contributors)
Apache License 2.0
[TLS]: https://github.com/blinksocks/blinksocks/tree/master/docs/config#blinksocks-over-tls
[WebSocket]: https://github.com/blinksocks/blinksocks/tree/master/docs/config#blinksocks-over-websocket
[ACL]: https://github.com/blinksocks/blinksocks/tree/master/docs/presets#access-control
[TC]: https://github.com/blinksocks/blinksocks/tree/master/docs/presets#access-control
[External preset import]: https://github.com/blinksocks/blinksocks/tree/master/docs/presets#use-external-preset
[TLS]: docs/config#blinksocks-over-tls
[WebSocket]: docs/config#blinksocks-over-websocket
[multiplexing]: docs/config#multiplexing
[customization]: docs/development/custom-preset
[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
[Dynamic Protocol Stack]: suites

2
docs/README.md
View File

@ -9,6 +9,6 @@
## For Developers
1. [Preparation](development/preparation)
2. [Guideline](development/guideline)
2. [Architecture](development/architecture)
3. [Custom Preset](development/custom-preset)
4. [Benchmark](benchmark)

214
docs/config/README.md
View File

@ -13,34 +13,30 @@ $ blinksocks init
```
{
"service": "socks5://127.0.0.1:1080",
"servers": [
{
"enabled": true,
"service": "tcp://127.0.0.1:19997",
"key": "<=p(^tr;DpEfVe<m",
"presets": [
{
"name": "ss-base"
},
{
"name": "obfs-random-padding"
},
{
"name": "ss-stream-cipher",
"params": {
"method": "aes-128-ctr"
}
"server": {
"service": "tcp://127.0.0.1:19997",
"key": "<=p(^tr;DpEfVe<m",
"presets": [
{
"name": "ss-base"
},
{
"name": "obfs-random-padding"
},
{
"name": "ss-stream-cipher",
"params": {
"method": "aes-128-ctr"
}
],
"tls_cert": "cert.pem",
"mux": false,
"mux_concurrency": 10
}
],
}
],
"tls_cert": "cert.pem",
"mux": false,
"mux_concurrency": 10
},
"dns": [],
"dns_expire": 3600,
"timeout": 221,
"workers": 0,
"log_path": "bs-client.log",
"log_level": "info",
"log_max_days": 30
@ -74,58 +70,59 @@ $ blinksocks init
"dns_expire": 3600,
"timeout": 221,
"redirect": "",
"workers": 0,
"log_path": "bs-server.log",
"log_level": "info",
"log_max_days": 30
}
```
| KEY | DESCRIPTION | OPTIONAL | DEFAULT | REMARKS |
| :----------------- | :----------------------------------------------------------- | :------- | :-------------- | :------------------------------------------------------------------------- |
| service | local service address | * | - | \<protocol\>://\<host\>:\<port\>\[?params\], e.g, "socks://127.0.0.1:1080" |
| servers | a list of server | Yes | - | **CLIENT ONLY** |
| servers[i].enabled | allow to use this server or not | - | - | - |
| servers[i].service | see service above | - | - | - |
| servers[i].key | server key for encryption | - | - | - |
| presets | preset list in order | - | - | see [presets] |
| presets[i].name | preset name | - | - | - |
| presets[i].params | preset params | - | - | - |
| tls_key | private key for TLS | - | - | required on server if \<protocol\> is "tls" |
| tls_cert | server certificate | - | - | required on both client and server if \<protocol\> is "tls" |
| timeout | timeout for each connection | Yes | 600 | in seconds |
| mux | enable multiplexing over TCP/TLS/WS | Yes | false | - |
| mux_concurrency | the max mux connection established between client and server | Yes | 10 | **CLIENT ONLY** |
| redirect | target to redirect when preset fail | Yes | "" | **SERVER ONLY** \<host\>:\<port\> |
| workers | the number of sub-process | Yes | 0 | enable cluster mode when workers > 0 |
| dns | an ip list of DNS server | Yes | [] | - |
| dns_expire | DNS cache expiration time | Yes | 3600 | in seconds |
| log_path | log file path | Yes | "bs-[type].log" | a relative/absolute directory or file to put logs in |
| log_level | log level | Yes | "info" | ['error', 'warn', 'info', 'verbose', 'debug', 'silly'] |
| log_max_days | the max of days a log file will be saved | Yes | 30 | remove this option if you want to keep all log files |
| KEY | DESCRIPTION | DEFAULT | REMARKS |
| :----------------- | :----------------------------------------------------------- | :-------------- | :------------------------------------------------------------------------- |
| service | local service address | - | `<protocol>://<host>:<port>[?params]`, e.g, "socks://127.0.0.1:1080" |
| server | remote server config | - | **CLIENT ONLY** |
| server.service | remote service address | - | `<protocol>://<host>:<port>` |
| server.key | remote server master key | - | - |
| presets | an ordered list of presets to build a protocol stack | - | see [presets] |
| presets[i].name | preset name | - | - |
| presets[i].params | preset params | - | - |
| tls_key | private key for TLS | - | required on server if `<protocol>` is "tls" |
| tls_cert | certificate for TLS | - | required on both client and server if `<protocol>` is "tls" |
| acl | enable access control list or not | false | **SERVER ONLY** |
| acl_conf | access control list configuration file | - | **SERVER ONLY**, see below |
| timeout | timeout for each connection | 600 | in seconds |
| mux | enable multiplexing or not | false | - |
| mux_concurrency | the max mux connection established between client and server | 10 | **CLIENT ONLY** |
| redirect | target address to redirect when preset fail to process | "" | **SERVER ONLY** `<host>:<port>` |
| dns | a list of DNS server IPs | [] | - |
| dns_expire | in-memory DNS cache expiration time | 3600 | in seconds |
| log_path | log file path | "bs-[type].log" | a relative/absolute directory or a file to put logs in |
| log_level | log level | "info" | ['error', 'warn', 'info', 'verbose', 'debug', 'silly'] |
| log_max_days | the max of days a log file will be saved | 30 | remove this option if you want to keep all log files |
### Service
`service` is a convenient way to specify what kind of service should be created **locally**.
The `<protocol>` should be `tcp`, `socks`(aliases: `socks5`, `socks4`, `socks4a`), `http`(aliases: `https`) on client side, or `tcp`, `tls`, `ws` on server side.
The `<protocol>` should be:
* On client side: `tcp`, `socks`/`socks5`/`socks4`/`socks4a` or `http`/`https`
* On server side: `tcp`, `tls` or `ws`.
#### Service Params
**?forward=\<host\>:\<port\>**
**?forward=<host>:<port>**
You can proxy application data to a **permanent destination** via server by providing **?forward** parameter:
You can proxy application data to a **permanent destination** via server by providing **?forward** parameter along with **tcp://** protocol:
```
// blinksocks.client.json
{
"service": "tcp://localhost:1080?forward=localhost:1082",
"servers": [{
"enabled": true,
"server": {
"service": "tcp://localhost:1081",
"presets": [...],
...
}],
},
...
}
```
@ -137,21 +134,13 @@ applications <----> [blinksocks client] <----> [blinksocks server] <----> localh
(iperf -c) localhost:1080 localhost:1081 (iperf -s)
```
In this case, it's useful to use [iperf](https://en.wikipedia.org/wiki/Iperf) to test network performance between client and server through different presets.
In this case, it uses [iperf](https://en.wikipedia.org/wiki/Iperf) to test network performance between client and server through different protocol stack.
> Note that on client side, `tcp://` cannot obtain proxy destination by itself, so you MUST provide **?forward** in service as well.
### Servers(Client Side Only)
`servers` is a list of blinksocks/shadowsocks servers. Each server consists at least `enabled`, `service`, `key` and `presets`.
You can temporary disable a server by setting `enabled: false`.
blinksocks will detect which server is the fastest in intervals using [balancer.js].
### Presets
`presets` is a list of procedures, each preset is defined as:
`presets` is a list of procedures which builds a specific protocol stack, each preset must be defined as:
```json
{
@ -162,13 +151,15 @@ blinksocks will detect which server is the fastest in intervals using [balancer.
}
```
`presets` are chaining from the first to the last, and are almost free to compose.
`presets` process data stream from the first to the last. You can add/remove/modify them freely.
For usage about presets, please check out [presets].
For more information about presets, please check out [presets].
### 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:
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 should:
1. Generate `key.pem` and `cert.pem` on server
@ -181,6 +172,8 @@ $ openssl req -x509 -newkey rsa:4096 -nodes -keyout key.pem -out cert.pem -days
2. Server config
Change `tcp://` to `tls://`, then provide `tls_key` and `tls_cert`:
```
{
"service": "tls://<host>:<port>",
@ -192,29 +185,20 @@ $ openssl req -x509 -newkey rsa:4096 -nodes -keyout key.pem -out cert.pem -days
3. Client config
Change server's `tcp://` to `tls://`, then provide `tls_cert`:
```
{
...
"servers": [{
...
"service": "tls://<Common Name>:<port>", // note here
"server": {
"service": "tls://<Common Name>:<port>", // take care of <Common Name>
"tls_cert": "cert.pem",
...
}],
},
...
}
```
4. How about presets?
You don't have to use extra encryption when transport is "tls", your data is already protected by TLS, so just set "base" preset:
```
{
"presets": [{"name": "ss-base"}]
}
```
### blinksocks over WebSocket
Like blinksocks over TLS, it's much easier to setup a websocket tunnel:
@ -233,22 +217,52 @@ Like blinksocks over TLS, it's much easier to setup a websocket tunnel:
```
{
...
"servers": [{
...
"server": {
"service": "ws://<host>:<port>",
...
}],
},
...
}
```
3. How about presets?
### Access Control List
Although data sent from client is masked(according to [RFC-6455]), you should add cipher presets to ensure confidentiality because websocket server will transfer your data in plain text by default.
You can enable ACL on **server** by setting **acl: true** and provide a acl configuration file in **acl_conf**:
```
{
"acl": true,
"acl_conf": "acl.txt",
...
}
```
**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.
> 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 specify the max concurrency in `mux_concurrency: <number>` on client.
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
@ -264,12 +278,12 @@ Since blinksocks v2.9.0, blinksocks supports TCP/TLS/WS multiplexing. You can en
```
{
...
"servers": [{
"server": {
...
"mux": true,
"mux_concurrency": 10
...
}],
},
...
}
```
@ -280,20 +294,20 @@ Specify a relative or absolute path to store log file, if no `log_path` provided
### Log Levels
The logging library [winston] use npm logging levels by default, you can choose one of them demand:
The logging library [winston] use npm logging levels by default, you can choose one of them on demand:
```
{ error: 0, warn: 1, info: 2, verbose: 3, debug: 4, silly: 5 }
```
### Custom DNS servers
### DNS servers
If you encounter **ENOTFOUND** every now and then, you would better custom dns servers via `dns` options:
If you encounter **ENOTFOUND** every now and then, you can custom dns servers via `dns` options:
```
{
...
"dns": ["8.8.8.8"]
"dns": ["8.8.8.8", "4.4.4.4"]
...
}
```
@ -302,20 +316,6 @@ If no `dns` option or no ip provided in `dns`, blinksocks use system dns setting
See: https://github.com/blinksocks/blinksocks/issues/66
### Cluster Mode
You can enable cluster mode by setting `workers` greater than zero, cluster mode can take advantage of multi-core systems to handle the load.
`workers` is usually set to the number of cpu cores:
```
{
...
"workers": 2
...
}
```
### UDP Relay
UDP relay is supported since blinksocks v2.8.0, and it's enabled by default on client and server. UDP relay is prepared only for applications who support Socks5 [UDP ASSOCIATE].
@ -326,8 +326,6 @@ Note that Socks5 requires to relay UDP message over UDP, so does blinksocks:
apps <--SOCKS5--> [blinksocks client] <--UDP--> [blinksocks server] <--UDP--> dests
```
[balancer.js]: ../../src/core/balancer.js
[presets]: ../presets
[winston]: https://github.com/winstonjs/winston
[RFC-6455]: https://tools.ietf.org/html/rfc6455
[UDP ASSOCIATE]: https://tools.ietf.org/html/rfc1928#section-4

2
docs/development/README.md
View File

@ -1,5 +1,5 @@
# Development Overview
1. [Preparation](preparation)
2. [Guideline](guideline)
2. [Architecture](architecture)
3. [Custom Preset](custom-preset)

4
docs/development/guideline/README.md → docs/development/architecture/README.md
View File

@ -1,4 +1,4 @@
# Guideline
# Architecture
## Proxy Application Data
@ -109,4 +109,4 @@ Pipe process application data from `ss-base` to `ss-stream-cipher`:
## Preset
Like the graph above, each preset implements a specific protocol, for examples you can check out [src/presets](../../../src/presets).
Like the graph above, each preset implements specific protocol or a part of protocol, for examples you can check out [src/presets](../../../src/presets).

79
docs/development/custom-preset/README.md
View File

@ -27,22 +27,22 @@ const blinksocks = require('blinksocks');
class MyCustomPreset extends blinksocks.IPreset {
constructor(params) {
super();
console.log('hello from my custom preset', params);
constructor(props) {
super(props);
console.log('hello from my custom preset');
}
// implement some of the methods you need
}
// static methods
// implement static methods
MyCustomPreset.checkParams = function checkParams(params) {
MyCustomPreset.onCheckParams = function onCheckParams(params) {
};
MyCustomPreset.onInit = function onInit(params) {
MyCustomPreset.onCache = function onCache(params, store) {
};
@ -51,7 +51,7 @@ module.exports = MyCustomPreset;
### Hooks
You can implement some of the following methods to interpret data flow:
You can implement some of the following methods to interact with data stream:
| METHODS | DESCRIPTION |
| :-------- | :-------------------------------------------------------------------------------- |
@ -85,7 +85,7 @@ clientOut({buffer, next, broadcast, direct, fail}) {
### Presets Decoupling
When communicate with other presets, you can pass an action to **broadcast(action)**.
When communicate with other presets, you can emit an action by **broadcast(action)**.
**Action** is a plain object which only requires a `type` field:
@ -97,7 +97,7 @@ When communicate with other presets, you can pass an action to **broadcast(actio
}
```
After broadcast, **all** other presets will receive the action in **onNotified(action)** immediately:
After broadcast, **all** other presets will receive the action in **onNotified(action)** synchronously:
```js
const blinksocks = require('blinksocks');
@ -117,8 +117,6 @@ class MyCustomPreset extends blinksocks.IPreset {
module.exports = MyCustomPreset;
```
> NOTE: `onNotified` is called **synchronous** when broadcast().
### Handle Address
You are probably want to know the target host and port when write your own preset, an action:
@ -170,23 +168,20 @@ module.exports = MyCustomPreset;
### Check Parameters
Your presets may require several parameters, and you can validate them in `constructor(params)`(every time a connection created)
or `checkParams(params)`(only once):
Your presets may require several parameters, and you can validate them in:
* `constructor({ config, params })`(every time a connection created)
* `onCheckParams(params)`(only once, recommended)
```js
const blinksocks = require('blinksocks');
class MyCustomPreset extends blinksocks.IPreset {
constructor(params) {
super();
// here
}
}
// check params passed to the preset, if any errors, should throw directly
MyCustomPreset.checkParams = function checkParams(params) {
MyCustomPreset.onCheckParams = function onCheckParams(params) {
// or here
};
@ -195,7 +190,7 @@ module.exports = MyCustomPreset;
### Improve Performance
You can initialize some shared/immutable data among connections in `onInit(params)` to improve performance:
You can initialize some shared/immutable data among connections in `onCache(params)` to improve performance:
```js
const blinksocks = require('blinksocks');
@ -204,26 +199,32 @@ class MyCustomPreset extends blinksocks.IPreset {
}
// you can make some cache in this function
MyCustomPreset.onInit = function onInit(params) {
/**
* you can make some cache in store or just return something
* you want to put in store, then access store later in other
* hook functions via this.getStore()
* @param params
* @param store
*/
MyCustomPreset.onCache = function onCache(params, store) {
// or return something
};
module.exports = MyCustomPreset;
```
### Access User Configuration
### Access Configuration
You can access user configuration directly from the `global` object anywhere in your preset class:
You can access configuration from `this._config` in your preset:
```js
const blinksocks = require('blinksocks');
class MyCustomPreset extends blinksocks.IPreset {
constructor() {
super();
console.log(__KEY__);
constructor(props) {
super(props);
console.log(this._config.key);
}
}
@ -231,21 +232,7 @@ class MyCustomPreset extends blinksocks.IPreset {
module.exports = MyCustomPreset;
```
**Available Items**
| NAME | NAME |
| :--------------------- | :------------------- |
| \_\_IS_SERVER\_\_ | \_\_DNS\_\_ |
| \_\_IS_CLIENT\_\_ | \_\_DNS_EXPIRE\_\_ |
| \_\_LOCAL_HOST\_\_ | \_\_TRANSPORT\_\_ |
| \_\_LOCAL_PORT\_\_ | \_\_TLS_CERT\_\_ |
| \_\_LOCAL_PROTOCOL\_\_ | \_\_TLS_KEY\_\_ |
| \_\_SERVER_HOST\_\_ | \_\_TIMEOUT\_\_ |
| \_\_SERVER_PORT\_\_ | \_\_REDIRECT\_\_ |
| \_\_SERVERS\_\_ | \_\_LOG_PATH\_\_ |
| \_\_KEY\_\_ | \_\_LOG_LEVEL\_\_ |
| \_\_PRESETS\_\_ | \_\_LOG_MAX_DAYS\_\_ |
| \_\_WORKERS\_\_ | |
For full items you can access to, please read [Config](../../../src/core/config.js).
### Helper Functions
@ -265,4 +252,8 @@ The same as `fail` parameter in each hook function.
**this.readProperty(presetName, propertyName)**
Direclty read a property from other presets, this is useful when your logic have to depend on other presets.
Directly read a property from other presets, this is useful when your logic have to depend on other presets.
**this.getStore()**
Returns the store you modified in or returned from `onCache(params, store)`.

46
docs/development/preparation/README.md
View File

@ -1,6 +1,6 @@
# Preparation
## Get the source
## Get source code
```
$ git clone https://github.com/blinksocks/blinksocks
@ -14,7 +14,7 @@ $ cd blinksocks && npm install
## Start blinksocks
Prepare your configurations(**blinksocks.client.json** and **blinksocks.server.json**) in the project root folder, then start to test:
Before start blinksocks, you should prepare two configurations(**blinksocks.client.json** and **blinksocks.server.json**) in the **project root folder**.
### Debug Mode(Use Chrome Developer Tool)
@ -25,41 +25,32 @@ $ npm run debug:client
$ npm run debug:server
```
Then open **chrome://inspect/#devices** in Chrome, configure **Target discovery settings** then click **inspect** below **Remote Target**.
Then open **chrome://inspect/#devices**, configure **Target discovery settings** then click **inspect** below **Remote Target**.
### Production Mode
First compile **src** to **lib**:
```
$ npm run compile
```
Then run:
```
$ npm run client
$ npm run server
```
This will run compiled code under **lib/**.
## Unit Test & e2e Test
## Test
Any application support HTTP/Socks5/Socks4/Socks4a can be used for testing.
For example(use curl):
You should run unit test and e2e test as following and make sure all tests pass before `git commit`:
```
# Socks5
$ curl -L --socks5 localhost:1080 https://www.google.com
$ curl -L --socks5-hostname localhost:1080 https://www.google.com
# Socks4
$ curl -L --socks4 localhost:1080 https://www.google.com
# Socks4a
$ curl -L --socks4a localhost:1080 https://www.google.com
# HTTP(S)
$ curl -L -x localhost:1080 https://www.google.com
$ curl -L -p localhost:1080 https://www.google.com
$ npm run test
```
## Compile
## Publish
For production use, we are running our code under `lib` not `src`, so compilation is necessary.
@ -69,7 +60,11 @@ Compilation of blinksocks is ultra easy:
$ npm run compile
```
This will compile `src/*` to `lib/*`.
After compile, we can change version in `package.json` then publish a package to npm registry:
```
$ npm publish
```
## Package
@ -79,5 +74,4 @@ For users don't have Node.js installed, we use [zeit/pkg](https://github.com/zei
$ npm run pkg
```
This will generate compressed executables for different platforms named `blinksocks-{platform}-${arch}-${version}.gz`.
And can be distribute to target platform and architecture at once.
This will generate compressed executables for different platforms named `blinksocks-{platform}-${arch}-${version}.gz`. And can be distribute to target platform at once.

216
docs/presets/README.md
View File

@ -1,15 +1,6 @@
# Presets
Presets are chaining and composable, built-in presets are listed here. If you want to customize a new preset, feel free to read [this](../development/guideline#preset) first.
## Built-In Presets
**functional**
* [stats](#stats)
* [tracker](#tracker)
* [access-control](#access-control)
* [auto-conf](#auto-conf)
Presets are chaining and composable, built-in presets are listed here.
**basic**
@ -40,15 +31,14 @@ Presets are chaining and composable, built-in presets are listed here. If you wa
**others**
* [auto-conf](#auto-conf)*
* [aead-random-cipher](#aead-random-cipher)
> You **MUST** put preset signed with (*) to the presets list if you want to relay application data to multiple destinations.
> You **MUST** provide one and only one preset signed with (*) to the presets list if you want to relay application data to dynamic destinations.
## Use External Preset
## Import External Preset
If you installed blinksocks via **npm install -g blinksocks**, you are free to use external presets.
To use external presets, you can:
If you have installed blinksocks by **npm install -g blinksocks**, you are free to use external presets:
**Use public npm package:**
@ -60,7 +50,7 @@ $ npm install -g blinksocks-preset-demo
"presets": [{"name": "blinksocks-preset-demo"}]
```
**Use private custom module:**
**Use private package:**
```
"presets": [{"name": "/path/to/your/preset.js"}]
@ -68,176 +58,10 @@ $ npm install -g blinksocks-preset-demo
> When use external preset, make sure that preset meets the requirements of the current Node.js environment.
To write your own preset, please refer to [Custom Preset](../development/custom-preset).
To customize your own preset, please refer to [Custom Preset](../development/custom-preset).
----
## [stats]
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 |
| :-------------- | :--------------------------- | :------ |
| save_to | path to the result json file | - |
| sample_interval | sample interval in seconds | 30 |
| save_interval | save interval in seconds | 60 |
```
"presets": [{
"name": "ss-base"
}, {
"name": "ss-stream-cipher",
"params": {
"method": "aes-256-cfb"
}
}, {
"name": "stats",
"params": {
"save_to": "stats.json",
"sample_interval": 1,
"save_interval": 10
}
}]
```
```
// stats.json
{
"sample": {
"from": 1503920985192,
"to": 1503921026263,
"duration": 41071
},
"summary": {
"maxOutSpeed": 105254,
"maxInSpeed": 158,
"maxConnections": 2,
"totalOutBytes": 130360,
"totalOutPackets": 34,
"totalInBytes": 314,
"totalInPackets": 2,
"totalBytes": 130674,
"totalPackets": 36,
"totalErrors": 0
},
"instant": {
"outSpeed": 0,
"inSpeed": 0,
"totalConnections": 0,
"errorRate": 0,
"outBytesPerSecond": 3174.0157288597798,
"outPacketsPerSecond": 0.8278347252319155,
"inBytesPerSecond": 7.645297168318279,
"inPacketsPerSecond": 0.04869616030775974,
"totalBytesPerSecond": 3181.6610260280977,
"totalPacketsPerSecond": 0.8765308855396753
},
"process": {
"upTime": 42.067,
"cpuUsage": {
"user": 1219598,
"system": 96237
},
"memoryUsage": {
"rss": 54575104,
"heapTotal": 28311552,
"heapUsed": 21701240,
"external": 3688374
}
}
}
```
## [tracker]
Track data send/receive events via this preset, and print a part of them after connection closed.
```
"presets": [
...
{"name": "tracker"},
...
]
```
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.
## [auto-conf]
An **experimental** preset used for auto-configure preset list. It will randomly choose a suite from `suites` for each connection.
| PARAMS | DESCRIPTION | DEFAULT |
| :----- | :------------------------------------------------ | :------ |
| suites | A json file includes a set of preset combinations | - |
```
"presets": [
{
"name": "auto-conf",
"params": {
"suites": "suites.json"
}
}
]
```
> You can custom `suites.json` or just use one of the [official versions](../../suites).
## [base-auth]
A preset based on "ss-base" and provides a HMAC to ensure integrity for addressing part.
@ -469,6 +293,27 @@ A TLS1.2 obfuscator, do TLS handshake using SessionTicket TLS mechanism, transfe
]
```
## [auto-conf]
An **experimental** preset used for auto-configure preset list. It will randomly choose a suite from `suites` for each connection.
| PARAMS | DESCRIPTION | DEFAULT |
| :----- | :------------------------------------------------ | :------ |
| suites | A json file includes a set of preset combinations | - |
```
"presets": [
{
"name": "auto-conf",
"params": {
"suites": "suites.json"
}
}
]
```
> You can custom `suites.json` or just use one of the [official versions](../../suites).
## [aead-random-cipher]
This preset is based on **ss-aead-cipher**, but added random padding in the front of **each chunk**. This preset inherited
@ -503,10 +348,6 @@ all features from **ss-aead-cipher** and prevent server from being detected by p
Here is a [list](./RECOMMENDATIONS.md) of recommended conbinations.
[stats]: ../../src/presets/stats.js
[tracker]: ../../src/presets/tracker.js
[access-control]: ../../src/presets/access-control.js
[auto-conf]: ../../src/presets/auto-conf.js
[base-auth]: ../../src/presets/base-auth.js
[ss-base]: ../../src/presets/ss-base.js
[ss-stream-cipher]: ../../src/presets/ss-stream-cipher.js
@ -519,5 +360,6 @@ Here is a [list](./RECOMMENDATIONS.md) of recommended conbinations.
[obfs-random-padding]: ../../src/presets/obfs-random-padding.js
[obfs-http]: ../../src/presets/obfs-http.js
[obfs-tls1.2-ticket]: ../../src/presets/obfs-tls1.2-ticket.js
[auto-conf]: ../../src/presets/auto-conf.js
[aead-random-cipher]: ../../src/presets/aead-random-cipher.js
[Server Name Indication]: https://en.wikipedia.org/wiki/Server_Name_Indication

53
docs/usage/README.md
View File

@ -5,7 +5,7 @@ Once installed, you can access blinksocks via CLI:
```
$ blinksocks --help
blinksocks v2.7.0
blinksocks v2.9.0
Usage: blinksocks [command] [options] ...
@ -37,20 +37,20 @@ $ blinksocks --help
```
`blinksocks init` will generate `blinksocks.client.json` and `blinksocks.server.json` with a random key/port/timeout and default settings.
`blinksocks init` will generate `blinksocks.client.json` and `blinksocks.server.json` with some random and default settings.
After init, you should edit `blinksocks.client.json` to tell blinksocks client where is the server:
```
{
"servers": [{
"server": {
"service": "tcp://<server_address>:<server_port>",
...
}]
}
}
```
> You may also want to change default protocol stack(presets) or other settings, please check out [--config](../config) for explanation of every option.
You can also check out [Configuration](../config) for explanation of every option.
## Run in production
@ -58,9 +58,9 @@ After init, you should edit `blinksocks.client.json` to tell blinksocks client w
> NOTE: you can only use pm2 on Linux/macOS due to a bug of pm2 on Windows. [#93](https://github.com/blinksocks/blinksocks/issues/93)
You can take advantages of [pm2](https://github.com/unitech/pm2) to run blinksocks in the production.
You can take advantages of [pm2](https://github.com/unitech/pm2) to run blinksocks in production.
Install `pm2` before running blinksocks in the production:
Install `pm2` before running blinksocks in production:
```
$ npm install -g pm2
@ -81,7 +81,7 @@ $ pm2 start blinksocks -i 2 -- -c blinksocks.server.json
### Using executables
```
// download archive
// download archive from releases page
$ wget https://github.com/blinksocks/blinksocks/releases/download/v2.5.3/blinksocks-linux-x64-v2.5.3.gz
// you'd better check sha256sum listed in sha256sum.txt
@ -97,39 +97,10 @@ $ chmod +x blinksocks-linux-x64-v2.5.3
$ ./blinksocks-linux-x64-v2.5.3 --help
```
## For Firefox/Google Chrome and more...
## Work with browsers
You may want to use blinksocks to surf the Internet with **browsers**, so I give an advise here.
Most of the time, you are surfing the Internet via web browsers such as Firefox or Google Chrome.
For Google Chrome, [SwitchyOmega](https://github.com/FelisCatus/SwitchyOmega) extension is a great approach to proxy your connections by rules to blinksocks via socks5/socks4(a)/http.
You can now make use of [SwitchyOmega](https://github.com/FelisCatus/SwitchyOmega) to proxy your connections by rules to blinksocks via socks5/socks4(a)/http protocols.
For FireFox, you can configure proxy at `Preferences - Advanced - Network - Settings`.
## Deploy(Using Docker)
We can use Docker to auto-deploy a blinksocks **server**.
### 1. Get image
You can build an image manually or pull it from docker hub:
* Build an image
```
$ cd <project-folder>/deploy
$ docker build --tag <user>/blinksocks:<version> --no-cache .
```
* Pull from docker hub
```
$ docker pull blinksocks:<version>
```
### 2. Run in a container
Container will expose `1080` port, so you must map a host port to `1080` via `-p`.
```
$ docker run -d -p 7777:1080 blinksocks:<version>
```
For FireFox, you can also configure proxy in `Preferences - Advanced - Network - Settings`.