docs: update
This commit is contained in:
Micooz
parent
47c2455b1a
commit
d359644428
32
README.md
32
README.md
@ -10,31 +10,37 @@
|
||||
[](https://codecov.io/gh/blinksocks/blinksocks)
|
||||
[](https://github.com/blinksocks/blinksocks)
|
||||
|
||||
A framework for building composable proxy protocol stack. Inspired by [Shadowsocks](https://shadowsocks.org),
|
||||
and [ShadowsocksR](https://github.com/shadowsocksr/shadowsocksr).
|
||||
A framework for building composable proxy protocol stack.
|
||||
|
||||
## Features
|
||||
|
||||
* HTTP/Socks5/Socks4/Socks4a using the same port
|
||||
* Customizable Protocols([presets](docs/presets)): simple, composable, and flexible
|
||||
* Simple proxy interfaces for Socks5/Socks4/Socks4a and HTTP
|
||||
* Customizable Protocols(using [presets](docs/presets)): simple, composable, and flexible
|
||||
* Cross-platform: running on Linux based, Windows and macOS
|
||||
* Portable/Executable versions available
|
||||
* Partially compatible with **shadowsocks** [#27](https://github.com/blinksocks/blinksocks/issues/27)
|
||||
* Dynamic server switch
|
||||
|
||||
## GUI ready
|
||||
|
||||
For desktop use, you can download official [blinksocks-desktop](https://github.com/blinksocks/blinksocks-desktop),
|
||||
a cross-platform GUI for blinksocks.
|
||||
|
||||
## Executables ready(Not GUI)
|
||||
|
||||
You can download precompiled executables for different platforms and use it directly without having Node.js installed:
|
||||
|
||||
[Download](https://github.com/blinksocks/blinksocks/releases).
|
||||
|
||||
## Getting Started
|
||||
|
||||
### Requirements
|
||||
|
||||
blinksocks is built on top of [Node.js](https://nodejs.org), so please install Node.js(**greater than v6.x**) 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
|
||||
|
||||
You can get the latest pre-compiled library(including executables) of blinksocks from **yarn** or **npm**.
|
||||
You can get the latest blinksocks via package manager **yarn** or **npm**.
|
||||
|
||||
> NOTE: Node.js comes with npm installed so you don't have to install npm individually.
|
||||
|
||||
@ -42,7 +48,7 @@ You can get the latest pre-compiled library(including executables) of blinksocks
|
||||
$ npm install -g blinksocks
|
||||
```
|
||||
|
||||
### Without Install?
|
||||
### Without yarn or npm?
|
||||
|
||||
If you hate to install and want to get a even more portable version, we have one:
|
||||
|
||||
@ -52,18 +58,24 @@ $ wget https://raw.githubusercontent.com/blinksocks/blinksocks/master/build/blin
|
||||
|
||||
## Run blinksocks
|
||||
|
||||
**installed version**
|
||||
**installed version(require Node.js)**
|
||||
|
||||
```
|
||||
$ blinksocks client -c blinksocks.client.json
|
||||
```
|
||||
|
||||
**portable version**
|
||||
**portable version(require Node.js)**
|
||||
|
||||
```
|
||||
$ node blinksocks.js -c blinksocks.client.json
|
||||
```
|
||||
|
||||
**executable version(~~Node.js~~)**
|
||||
|
||||
```
|
||||
$ ./blinksocks(.exe) --help
|
||||
```
|
||||
|
||||
For configuring blinksocks, please refer to [Configuration](docs/config).
|
||||
|
||||
## Documents
|
||||
|
||||
@ -71,20 +71,22 @@ These two presets act as two middlewares, processing data from the bottom to the
|
||||
+-----------+
|
||||
```
|
||||
|
||||
Ordinarily, `DST.ADDR` and `DST.PORT` is required to be sent to server(like "origin" preset),
|
||||
Ordinarily, `DST.ADDR` and `DST.PORT` is required to be sent to server(like "ss-base" preset),
|
||||
otherwise server cannot figure out where to send data to.
|
||||
|
||||
Blinksocks will pass **target address** to the first preset once a connection between application
|
||||
and blinksocks client was constructed, so you can obtain that address in your frame preset.
|
||||
The framework will prepend `proxy` preset to the preset list on client side. Action(PROXY_HANDSHAKE_DONE) is fired
|
||||
once this preset resolved the target address. Other presets(such as "ss-base") who want to use the address should implement
|
||||
`onNotified(action)` method, the address is stored in `action.payload.targetAddress`.
|
||||
|
||||
```js
|
||||
// core/socket.js
|
||||
const presets = __PRESETS__.map(
|
||||
(preset, i) => createMiddleware(preset.name, {
|
||||
...preset.params,
|
||||
...(i === 0 ? addr : {})
|
||||
})
|
||||
);
|
||||
let presets = __PRESETS__;
|
||||
// prepend "proxy" preset to the top of presets on client side
|
||||
if (__IS_CLIENT__ && presets[0].name !== 'proxy') {
|
||||
presets = [{name: 'proxy'}].concat(presets);
|
||||
}
|
||||
// create middlewares and pipe
|
||||
const middlewares = presets.map((preset) => createMiddleware(preset.name, preset.params || {}));
|
||||
```
|
||||
|
||||
Store target address for further use:
|
||||
@ -93,21 +95,20 @@ Store target address for further use:
|
||||
// presets/ss-base.js
|
||||
import {IPreset} from './defs';
|
||||
|
||||
export default class SSBasePreset extends IPreset {
|
||||
export default class SsBasePreset extends IPreset {
|
||||
|
||||
_atyp = ATYP_V4;
|
||||
|
||||
_addr = null; // buffer
|
||||
_host = null; // buffer
|
||||
|
||||
_port = null; // buffer
|
||||
|
||||
constructor(addr) {
|
||||
super();
|
||||
if (__IS_CLIENT__) {
|
||||
const {type, host, port} = addr;
|
||||
onNotified(action) {
|
||||
if (__IS_CLIENT__ && action.type === PROXY_HANDSHAKE_DONE) {
|
||||
const {type, host, port} = action.payload.targetAddress;
|
||||
this._atyp = type;
|
||||
this._addr = host;
|
||||
this._port = port;
|
||||
this._port = numberToBuffer(port);
|
||||
this._host = type === ATYP_DOMAIN ? Buffer.from(host) : ip.toBuffer(host);
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
@ -78,16 +78,27 @@ Compilation of blinksocks is ultra easy:
|
||||
$ npm run compile
|
||||
```
|
||||
|
||||
This will compile `src` to `build`.
|
||||
This will compile `src/*` to `build/*`.
|
||||
|
||||
## Bundle
|
||||
|
||||
For portable use, we use **webpack** to compile, bundle and compress `src` into `build/blinksocks.js`:
|
||||
|
||||
```
|
||||
$ npm run bundle
|
||||
```
|
||||
|
||||
## Pack
|
||||
|
||||
For users don't have Node.js installed, we use **zeit/pkg** to prepare compiled executables:
|
||||
|
||||
```
|
||||
$ npm run pack
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
## Profile
|
||||
|
||||
By adding `--profile` option in the command line, you will get a report named `blinksocks.profile.log` after
|
||||
|
||||
@ -8,14 +8,36 @@ If you want custom a preset, feel free to read [this](../development/architectur
|
||||
> You **MUST** put [ss-base] or [exp-base-with-padding] or [exp-base-auth-stream] to the first in presets list if you
|
||||
want to relay data to blinksocks server.
|
||||
|
||||
## [proxy]
|
||||
|
||||
This preset turns blinksocks to a proxy server, works on both client and server side.
|
||||
|
||||
* For client side, this preset is added by default on **client side**, so you don't have to put it into preset list.
|
||||
* For server side, this preset is useful to setup a network middleware(act as Man-in-the-middle) to do traffic analysis.
|
||||
|
||||
For example, setup a local proxy server using **blinksocks server** at 1080:
|
||||
|
||||
> applications ---Socks5/HTTP---> **[blinksocks server]** ------> destinations
|
||||
|
||||
```json
|
||||
// blinksocks.server.json
|
||||
{
|
||||
"host": "localhost",
|
||||
"port": 1080,
|
||||
"presets": [{
|
||||
"name": "proxy"
|
||||
}],
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
## [ss-base]
|
||||
|
||||
This is a very basic preset which delivers the real destination address from blinksocks client to blinksocks server.
|
||||
|
||||
```json
|
||||
"presets": [{
|
||||
"name": "ss-base",
|
||||
"params": {}
|
||||
"name": "ss-base"
|
||||
}]
|
||||
```
|
||||
|
||||
@ -211,31 +233,6 @@ A TLS obfuscator, do TLS handshake using SessionTicket TLS mechanism, transfer d
|
||||
]
|
||||
```
|
||||
|
||||
# Special Presets
|
||||
|
||||
## [proxy]
|
||||
|
||||
This preset turns blinksocks to a proxy server. This is useful to setup a network middleware(act as Man-in-the-middle) to do traffic analysis.
|
||||
|
||||
For example, setup a local proxy server using **blinksocks server** at 1080:
|
||||
|
||||
> applications ---Socks5/HTTP---> **[blinksocks server]** ------> destinations
|
||||
|
||||
```json
|
||||
// blinksocks.server.json
|
||||
{
|
||||
"host": "localhost",
|
||||
"port": 1080,
|
||||
"presets": [
|
||||
{
|
||||
"name": "proxy",
|
||||
"params": {}
|
||||
}
|
||||
],
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
# Recommended Combinations
|
||||
|
||||
## Work with shadowsocks
|
||||
@ -246,8 +243,7 @@ To work with **shadowsocks**, please choose one of the following configuration:
|
||||
|
||||
```json
|
||||
"presets": [{
|
||||
"name": "ss-base",
|
||||
"params": {}
|
||||
"name": "ss-base"
|
||||
}, {
|
||||
"name": "ss-stream-cipher",
|
||||
"params": {
|
||||
@ -260,8 +256,7 @@ To work with **shadowsocks**, please choose one of the following configuration:
|
||||
|
||||
```json
|
||||
"presets": [{
|
||||
"name": "ss-base",
|
||||
"params": {}
|
||||
"name": "ss-base"
|
||||
}, {
|
||||
"name": "ss-aead-cipher",
|
||||
"params": {
|
||||
@ -279,8 +274,7 @@ You can use **http** or **tls** obfuscator to avoid bad [QoS], **tls** is recomm
|
||||
|
||||
```json
|
||||
"presets": [{
|
||||
"name": "ss-base",
|
||||
"params": {}
|
||||
"name": "ss-base"
|
||||
}, {
|
||||
"name": "ss-aead-cipher",
|
||||
"params": {
|
||||
@ -297,8 +291,7 @@ You can use **http** or **tls** obfuscator to avoid bad [QoS], **tls** is recomm
|
||||
|
||||
```json
|
||||
"presets": [{
|
||||
"name": "ss-base",
|
||||
"params": {}
|
||||
"name": "ss-base"
|
||||
}, {
|
||||
"name": "ss-aead-cipher",
|
||||
"params": {
|
||||
@ -321,8 +314,7 @@ The fastest one:
|
||||
|
||||
```json
|
||||
"presets": [{
|
||||
"name": "ss-base",
|
||||
"params": {}
|
||||
"name": "ss-base"
|
||||
}]
|
||||
```
|
||||
|
||||
@ -330,8 +322,7 @@ Make some cheat:
|
||||
|
||||
```json
|
||||
"presets": [{
|
||||
"name": "ss-base",
|
||||
"params": {}
|
||||
"name": "ss-base"
|
||||
}, {
|
||||
"name": "obfs-tls1.2-ticket",
|
||||
"params": {
|
||||
|
||||
Loading…
Reference in New Issue
Block a user