Bypass¶
Dynamic configuration
Bypass supports dynamic configuration via Web API.
Bypass Controller¶
Bypass can be set on the service, the hop and the nodes of the forwarding chain respectively, during the data forwarding process, the target address is tested according to the rules in the bypass to decide whether to continue forwarding.
gost -L http://:8080?bypass=10.0.0.0/8 -F http://192.168.1.1:8080?bypass=172.10.0.0/16,127.0.0.1,localhost,*.example.com,.example.org
Specify a list of client address matching rules (comma-separated IP or CIDR) via the bypass option.
services:
- name: service-0
addr: ":8080"
bypass: bypass-0
handler:
type: http
chain: chain-0
listener:
type: tcp
chains:
- name: chain-0
hops:
- name: hop-0
# hop level
bypass: bypass-1
nodes:
- name: node-0
addr: 192.168.1.1:8080
# node level
# bypass: bypass-0
connector:
type: http
dialer:
type: tcp
bypasses:
- name: bypass-0
matchers:
- 10.0.0.0/8
- name: bypass-1
matchers:
- 172.10.0.0/16
- 127.0.0.1
- localhost
- '*.example.com'
- .example.org
Use the bypass property in node to use the specified bypass by referencing the bypass name.
Hop Level Bypass
Bypass can be set on hop or node, if not set on node, the bypass specified on hop will be used.
The bypass option in command line mode will be applied to the hop level.
Blacklist And Whitelist¶
Bypass defaults to blacklist mode. If the destination address matches the blacklist, the data forwarding will be terminated.
Bypass can also be set to whitelist mode, as opposed to blacklist, data forward will continue only if the destination address matches the rules in the bypass.
gost -L http://:8080 -F http://192.168.1.1:8080?bypass=~172.10.0.0/16,127.0.0.1,localhost,*.example.com,.example.org
Set the bypass to blacklist mode by adding the ~ prefix to the bypass opiton.
services:
- name: service-0
addr: ":8080"
handler:
type: http
chain: chain-0
listener:
type: tcp
chains:
- name: chain-0
hops:
- name: hop-0
bypass: bypass-0
nodes:
- name: node-0
addr: 192.168.1.1:8080
# bypass: bypass-0
connector:
type: http
dialer:
type: tcp
bypasses:
- name: bypass-0
whitelist: true
matchers:
- 172.10.0.0/16
- 127.0.0.1
- localhost
- '*.example.com'
- .example.org
Enable blacklist mode in bypasses by setting the whitelist property to true.
Bypass Group¶
Multiple bypasses are used by specifying a list of bypasses using the bypasses option. When any one of the bypass passes the rule test, it means the bypass is passed.
services:
- name: service-0
addr: ":8080"
handler:
type: http
chain: chain-0
listener:
type: tcp
chains:
- name: chain-0
hops:
- name: hop-0
bypasses:
- bypass-0
- bypass-1
nodes:
- name: node-0
addr: 192.168.1.1:8080
# bypasses:
# - bypass-0
# - bypass-1
connector:
type: http
dialer:
type: tcp
bypasses:
- name: bypass-0
whitelist: true
matchers:
- 172.10.0.0/16
- name: bypass-1
matchers:
- 127.0.0.1
- localhost
- '*.example.com'
- .example.org
Bypass Type¶
Service Level Bypass¶
When a bypass is set on the service, if the requested target address fails the rule test (does not match the whitelist rule or matches the blacklist rule), the request will be rejected.
The HTTP proxy service on port 8080 uses a blacklist bypass. The request of example.org will be processed normally, and the request of example.com will be rejected.
Hop Level Bypass¶
When a bypass is set on a hop, if the requested destination address fails the rule test (does not match the whitelist rule or matches the blacklist rule), the forwarding chain will terminate at this hop, and excluding this hop.
services:
- name: service-0
addr: ":8080"
handler:
type: http
chain: chain-0
listener:
type: tcp
chains:
- name: chain-0
hops:
- name: hop-0
bypass: bypass-0
nodes:
- name: node-0
addr: :8081
connector:
type: http
dialer:
type: tcp
- name: hop-1
bypass: bypass-1
nodes:
- name: node-0
addr: :8082
connector:
type: http
dialer:
type: tcp
bypasses:
- name: bypass-0
whitelist: true
matchers:
- example.com
- .example.org
- name: bypass-1
matchers:
- example.com
When a request to www.example.com does not go through the bypass (bypass-0) of the hop (hop-0), the request will not use the forwarding chain.
When requesting example.com, it passes the bypass (bypass-0) of the first hop (hop-0), but not the bypass (bypass-1) of the second hop (hop-1) , so the request will use the node(:8081) at the first level of the forwarding chain for data forwarding.
When requesting www.example.org, it goes through all bypasses, so the request will be forwarded using the full forwarding chain.
Chain Node Level Bypass¶
When the forwarding chain uses multiple nodes, the request can be fine-grained divided by setting bypasses on the nodes.
services:
- name: service-0
addr: ":8080"
handler:
type: http
chain: chain-0
listener:
type: tcp
chains:
- name: chain-0
hops:
- name: hop-0
nodes:
- name: node-0
addr: :8081
bypass: bypass-0
connector:
type: http
dialer:
type: tcp
- name: node-1
addr: :8082
bypass: bypass-1
connector:
type: http
dialer:
type: tcp
bypasses:
- name: bypass-0
matchers:
- example.org
- name: bypass-1
matchers:
- example.com
When requesting example.com, it passed the bypass bypass-0 on node node-0, but did not pass the bypass bypass-1 on node node-1, so the request will only be forwarded using node node-0.
When requesting example.org, it does not pass the bypass-0 on node node-0, but passes the bypass on node-1, so the request will only be forwarded using node-1.
Forwarder Node Level Bypass¶
This type of bypass is similar to the bypass on the chain node and currently only applies to the DNS proxy service.
Data Source¶
Bypass can configure multiple data sources, currently supported data sources are: inline, file, redis.
Inline¶
An inline data source means setting the data directly in the configuration file via the matchers property.
bypasses:
- name: bypass-0
matchers:
- 127.0.0.1
- 172.10.0.0/16
- localhost
- '*.example.com'
- .example.org
File¶
Specify an external file as the data source. Specify the file path via the file.path property.
The file format is a list of addresses separated by lines, and the part starting with # is the comment information.
Redis¶
Specify the redis service as the data source, and the redis data type must be Set.
bypasses:
- name: bypass-0
redis:
addr: 127.0.0.1:6379
db: 1
password: 123456
key: gost:bypasses:bypass-0
addr(string, required)- redis server address
db(int, default=0)- database name
password(string)- password
key(string, default=gost)- redis key
Hot Reload¶
File and redis data sources support hot reloading. Enable hot loading by setting the reload property, which specifies the period for synchronizing the data source data.