.. | ||
README.md |
Configuration
Auto Generate Configs
You can use the following command to generate blinksocks.client.json
and blinksocks.server.json
:
$ blinksocks init
blinksocks.client.json
{
"service": "socks5://127.0.0.1:1080",
"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",
"tls_cert_self_signed": false,
"mux": false,
"mux_concurrency": 10
},
"dns": [],
"dns_expire": 3600,
"timeout": 221,
"log_path": "bs-client.log",
"log_level": "info",
"log_max_days": 30
}
blinksocks.server.json
{
"service": "tcp://0.0.0.0:19997",
"key": "<=p(^tr;DpEfVe<m",
"presets": [
{
"name": "ss-base"
},
{
"name": "obfs-random-padding"
},
{
"name": "ss-stream-cipher",
"params": {
"method": "aes-128-ctr"
}
}
],
"tls_key": "key.pem",
"tls_cert": "cert.pem",
"mux": false,
"dns": [],
"dns_expire": 3600,
"timeout": 221,
"redirect": "",
"log_path": "bs-server.log",
"log_level": "info",
"log_max_days": 30
}
KEY | DESCRIPTION | DEFAULT | REMARKS |
---|---|---|---|
service | local service address | - | a WHATWG URL 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" |
tls_cert_self_signed | whether "tls_cert" is self-signed or not |
false | - |
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 WHATWG URL that includes what kind of service should be created locally.
The <protocol>
should be:
- On client side:
tcp
,socks
/socks5
/socks4
/socks4a
orhttp
. - On server side:
tcp
,tls
,ws
orwss
.
Service Authentication
- Create a http service with Basic Authentication.
// blinksocks.client.json
{
"service": "http://user:pass@localhost:1080",
...
}
- Create a socks5 service with Username/Password Authentication.
// blinksocks.client.json
{
"service": "socks5://user:pass@localhost:1080",
...
}
Service Params
?forward=:
When use tcp://
protocol, you can proxy application data to a permanent destination via server by providing ?forward parameter:
// blinksocks.client.json
{
"service": "tcp://localhost:1080?forward=localhost:1082",
"server": {
"service": "tcp://localhost:1081",
"presets": [...],
...
},
...
}
Then it built:
applications <----> [blinksocks client] <----> [blinksocks server] <----> localhost:1082
(iperf -c) localhost:1080 localhost:1081 (iperf -s)
In this case, it uses 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.
Presets
presets
is a list of procedures which builds a specific protocol stack, each preset must be defined as:
{
"name": "preset-name",
"params": {
"key": "value"
}
}
presets
process data stream from the first to the last. You can add/remove/modify them freely.
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:
- Generate
key.pem
andcert.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.
- 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",
...
}
- 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:
- Server config
{
"service": "ws://<host>:<port>",
...
}
- 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
:
- Server config
{
"service": "wss://<host>:<port>",
"tls_key": "key.pem",
"tls_cert": "cert.pem",
...
}
- 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:
{
"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 set mux_concurrency: <number>
on client.
- Server config
{
"mux": true,
...
}
- 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.
Log Levels
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 }
DNS servers
If you encounter ENOTFOUND every now and then, you can custom dns servers via dns
options:
{
...
"dns": ["8.8.8.8", "4.4.4.4"]
...
}
If no dns
option or no ip provided in dns
, blinksocks use system dns settings as usual.
See: https://github.com/blinksocks/blinksocks/issues/66
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.
Note that Socks5 requires to relay UDP message over UDP, so does blinksocks:
apps <--SOCKS5--> [blinksocks client] <--UDP--> [blinksocks server] <--UDP--> dests