socks
The socks
directive is used to forward matching requests through a specified SOCKS5 proxy server.
Rule Syntax
pattern socks://ipOrDomain[:port] [filters...]
port
is optional. If left blank, the default port443
will be used.
Parameters | Description | Detailed Documentation |
---|---|---|
pattern | An expression to match the request URL | Match Pattern Documentation |
value | IP + optional port or domain name + optional port ⚠️ Loading data from files/remote URLs is not supported | Operation Instruction Documentation |
filters | Optional filters. Supports matching: • Request URL/Method/Headers/Content • Response Status Code/Headers | Filters Documentation |
Configuration Example
# Proxy requests to a SOCKS5 proxy: `127.0.0.1:443`
www.example.com/path socks://127.0.0.1 # Default port 443
# Proxy all requests for the current domain to the SOCKS5 proxy: `127.0.0.1:8080`
www.example.com socks://127.0.0.1:8080
# You can also use a domain name.
www.example.com/path socks://test.proxy.com # Default port 443
www.example.com socks://test.proxy.com:8080
Advanced Usage
By default, the upstream proxy resolves the requested domain name. However, in some scenarios, you may want to force the proxy to access a specific target IP directly (skipping DNS resolution), for example:
- Bypassing DNS poisoning
- Directly accessing a specific backend IP
- Testing services in different environments
# Using query parameters
www.example.com socks://127.0.0.1:8080?host=1.1.1.1
www.example.com socks://127.0.0.1:8080?host=1.1.1.1:8080
# Enabling via directives
www.example.com socks://127.0.0.1:8080 1.1.1.1 enable://proxyHost
www.example.com socks://127.0.0.1:8080 1.1.1.1:8080 enable://proxyHost
1.1.1.1
is equivalent tohost://1.1.1.1
Notes
The socks
protocol only applies to the substituted URL (i.e., the Final URL
shown in the Overview). If the Final URL
is empty, it will take effect on the original request URL.
For example, with the rule:
www.example.com/api www.example.com proxy://127.0.0.1:1234
When a request is made to https://www.example.com/api/path
, Whistle processes it and changes the URL to https://www.example.com/path
(this becomes the Final URL
). Although the intention is to proxy this request to 127.0.0.1:1234
, the proxy
rule only matches the original domain www.example.com/api
before substitution. Since the converted Final URL
is now www.example.com/path
, this rule will not be triggered.
To ensure the rule also applies to the substituted request, you can break it into two separate rules:
www.example.com/api www.example.com
www.example.com proxy://127.0.0.1:1234
This way, the original request is first rewritten by the first rule, generating a new Final URL
. Then, the second proxy
rule matches this new URL and successfully proxies the request to 127.0.0.1:1234
.