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
Use the bypass parameter to specify the requested target address matching rule list. The rules are IP, IP range, CIDR, domain name or domain name wildcard separated by commas.
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:
- 127.0.0.1
- 172.20.0.1-172.30.0.255
- 172.10.0.0/16
- localhost
- '*.example.com'
- .example.org
Use the bypass option 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 whitelist 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 whitelist 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
Port Matching¶
For IP, domain name and domain name wildcard rules can also contain ports or port ranges, CIDR rules do not support port matching.
Network Protocol Filtering¶
3.3.0
Bypass can be configured with the network parameter to restrict matching to a specific network protocol type (e.g., tcp or udp). When the network protocol does not match, the bypass rule is not applied.
bypasses:
# Blacklist mode: all TCP connections are bypassed
- name: skip-tcp
network: tcp
# Whitelist mode: only UDP connections use the proxy, others are bypassed
- name: proxy-udp
network: udp
whitelist: true
# Network + address combination: bypassed only when TCP and address matches
- name: bypass-tcp-local
network: tcp
matchers:
- 192.168.1.0/24
- 10.0.0.0/8
- '*.example.com'
- .example.org
When only network is set (without matchers):
- Blacklist mode: matching network connections are bypassed (do not go through the proxy).
- Whitelist mode: matching network connections use the proxy, all others are bypassed.
When both network and matchers are set, the network protocol acts as a pre-filter:
- Network mismatch → bypass rule is not applied, the connection proceeds normally.
- Network match → continue to evaluate the
matchersrules for address matching.
Typical Use Case: TCP/UDP Routing¶
In network proxying, TCP and UDP often require different routing paths. For example, route TCP traffic through an encrypted proxy while UDP traffic goes direct or through a different proxy:
chains:
- name: chain-0
hops:
- name: hop-0
bypasses:
- skip-udp
nodes:
- name: node-tcp
addr: :8443
bypass: skip-udp
connector:
type: http
dialer:
type: tls
- name: node-udp
addr: :8443
bypass: skip-tcp
connector:
type: relay
dialer:
type: tls
bypasses:
- name: skip-tcp
network: tcp
- name: skip-udp
network: udp
whitelist: true
Backward Compatibility
By default, network is empty and the bypass behaves exactly the same as in previous versions.
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
username: user
password: 123456
key: gost:bypasses:bypass-0
addr(string, required)- redis server address
db(int, default=0)- database name
username(string)- username
password(string)- password
key(string, default=gost)- redis key
> SMEMBERS gost:bypasses:bypass-0
1) "127.0.0.1"
2) "172.10.0.0/16"
3) "localhost"
4) "*.example.com"
5) ".example.org"
HTTP¶
Specify the HTTP service as the data source. For the requested URL, if HTTP returns a 200 status code, it is considered valid, and the returned data format is the same as the file data source.
url(string, required)- request URL
timeout(duration, default=0)- request timeout
Hot Reload¶
File, redis and HTTP data sources support hot reloading. Enable hot loading by setting the reload property, which specifies the period for synchronizing the data source data.
bypasses:
- name: bypass-0
reload: 10s
file:
path: /path/to/auth/file
redis:
addr: 127.0.0.1:6379
db: 1
password: 123456
key: gost:bypasses:bypass-0
Plugin¶
Bypass can be configured to use an external plugin service, and it will forward the request to the plugin server for processing. Other parameters are invalid when using plugin.
bypasses:
- name: bypass-0
plugin:
type: grpc
addr: 127.0.0.1:8000
tls:
secure: false
serverName: example.com
type(string, default=grpc)- plugin type:
grpc,http. addr(string, required)- plugin server address.
tls(object, default=null)- TLS encryption will be used for transmission, TLS encryption is not used by default.
HTTP Plugin¶
Example¶
curl -XPOST http://127.0.0.1:8000/bypass -d '{"network":"tcp","addr":"example.com:80","path":"/index.html","client": "gost"}'
network(string)- network type.
addr(string)- target address.
host(string)- target host name.
path(string)- HTTP request path.
client(string)- user ID, generated by Authenticator.
Bypass Based On Client ID
The GOST internal Bypass does not handle the logic for specific clients. If you need to implement this function, you can use an Authenticator and a Bypass plugin in combination.
The Authenticator returns the client ID after successful authentication. GOST will pass this client ID information to the Bypass plugin service again, and the Bypass plugin server can implement different strategies based on the client ID.
Geo IP Bypass¶
3.3.0
GOST's built-in bypass supports both IP CIDR and domain matching, but the two are independent — domain rules only match against domain names and will not resolve domain names to IP addresses for CIDR matching. In other words, when you configure 203.0.113.0/24 as a CIDR rule, even if example.com resolves to 203.0.113.1, GOST will not bypass example.com.
gost-geo-plugin is a gRPC-based bypass plugin specifically designed to address this limitation. It features a built-in high-performance IP trie that matches DNS-resolved IP addresses against CIDR rules, enabling fine-grained Geo/ASN routing similar to a routing table.
Running the Plugin¶
gost-geo-plugin requires a CIDR list file, with one CIDR per line:
The CIDR list can be loaded from a local file or a URL:
# Load from local file
gost-geo-plugin --list-file /path/to/geoip.txt --listen-addr 127.0.0.1:8000
# Load from URL (supports HTTP/HTTPS)
gost-geo-plugin --list-url https://example.com/geoip.txt --listen-addr 127.0.0.1:8000
Optional flags:
--prefer-ipv6— Prefer IPv6 addresses for matching.--port— Plugin server port, default 8000.--refresh— CIDR list refresh interval, e.g.,24h. Disabled by default.
Configuring the Bypass¶
After the plugin is running, configure GOST to use it as a plugin bypass:
services:
- name: service-0
addr: ":8080"
bypass: bypass-geo
handler:
type: http
listener:
type: tcp
With this configuration, all proxy traffic through GOST will first be checked by gost-geo-plugin, which resolves domain names to IP addresses and matches them against the CIDR list. Traffic with IP addresses matching the whitelist rules will be bypassed accordingly.
Combining with Local Bypass Rules
gost-geo-plugin only resolves domains to IPs for CIDR matching — the actual bypass decision is still made by GOST's bypass controller. You can combine domain-based rules with Geo IP rules using Bypass Groups to implement more flexible traffic control strategies.