mirror of
https://github.com/unshackle-dl/unshackle.git
synced 2026-11-12 12:05:07 +00:00
216 lines
8.6 KiB
Markdown
216 lines
8.6 KiB
Markdown
# Network & Proxy Configuration
|
|
|
|
This document covers network and proxy configuration options for bypassing geofencing and managing connections.
|
|
|
|
## proxy_providers (dict)
|
|
|
|
Enable external proxy provider services. These proxies will be used automatically where needed as defined by the
|
|
Service's GEOFENCE class property, but can also be explicitly used with `--proxy`. You can specify which provider
|
|
to use by prefixing it with the provider key name, e.g., `--proxy basic:de` or `--proxy nordvpn:de`. Some providers
|
|
support specific query formats for selecting a country/server.
|
|
|
|
### basic (dict[str, str|list])
|
|
|
|
Define a mapping of country to proxy to use where required.
|
|
The keys are region Alpha 2 Country Codes. Alpha 2 Country Codes are `[a-z]{2}` codes, e.g., `us`, `gb`, and `jp`.
|
|
Don't get this mixed up with language codes like `en` vs. `gb`, or `ja` vs. `jp`.
|
|
|
|
Do note that each key's value can be a list of strings, or a string. For example,
|
|
|
|
```yaml
|
|
us:
|
|
- "http://john%40email.tld:password123@proxy-us.domain.tld:8080"
|
|
- "http://jane%40email.tld:password456@proxy-us.domain2.tld:8080"
|
|
de: "https://127.0.0.1:8080"
|
|
```
|
|
|
|
Note that if multiple proxies are defined for a region, then by default one will be randomly chosen.
|
|
You can choose a specific one by specifying it's number, e.g., `--proxy basic:us2` will choose the
|
|
second proxy of the US list.
|
|
|
|
### nordvpn (dict)
|
|
|
|
Set your NordVPN Service credentials with `username` and `password` keys to automate the use of NordVPN as a Proxy
|
|
system where required.
|
|
|
|
You can also specify specific servers to use per-region with the `server_map` key.
|
|
Sometimes a specific server works best for a service than others, so hard-coding one for a day or two helps.
|
|
|
|
You can also select servers by city using the format `--proxy nordvpn:us:seattle` or `--proxy nordvpn:ca:calgary`.
|
|
|
|
For example,
|
|
|
|
```yaml
|
|
username: zxqsR7C5CyGwmGb6KSvk8qsZ # example of the login format
|
|
password: wXVHmht22hhRKUEQ32PQVjCZ
|
|
server_map:
|
|
us: 12 # force US server #12 for US proxies
|
|
```
|
|
|
|
The username and password should NOT be your normal NordVPN Account Credentials.
|
|
They should be the `Service credentials` which can be found on your Nord Account Dashboard.
|
|
|
|
Once set, you can also specifically opt in to use a NordVPN proxy by specifying `--proxy nordvpn:gb` or such.
|
|
You can even set a specific server number this way, e.g., `--proxy nordvpn:gb2366`.
|
|
|
|
Note that `gb` is used instead of `uk` to be more consistent across regional systems.
|
|
|
|
### protonvpn (dict)
|
|
|
|
Enable Proton VPN as a proxy provider. Proton mints short-lived HTTPS proxy credentials per session, so
|
|
authentication reuses an exported `account.proton.me` browser session rather than static credentials.
|
|
|
|
Export the cookies for `account.proton.me` (Netscape `cookies.txt` or a JSON cookie list) — they must include
|
|
the `AUTH-<UID>` and `REFRESH-<UID>` cookies — and save them at `<cookies>/vpn/protonvpn.txt`. **No yaml is
|
|
required**: the provider auto-loads when that file exists. Exporting straight from the logged-in web page is
|
|
fine; cookies for other Proton apps (e.g. `mail.proton.me`) are ignored automatically. The session refreshes on
|
|
its own when the access token expires, so you only re-export if it is fully revoked. **Free Proton accounts
|
|
work**, limited to the free-tier exit countries.
|
|
|
|
Configuration is optional — only add a block to override defaults:
|
|
|
|
```yaml
|
|
proxy_providers:
|
|
protonvpn:
|
|
cookie_path: /path/to/protonvpn.txt # optional; defaults to <cookies>/vpn/protonvpn.txt
|
|
server_map:
|
|
stream-us: us:ny # optional alias -> country / country:city / countryNN
|
|
```
|
|
|
|
Query formats (after the provider prefix). City uses the NordVPN-style colon, like `nordvpn:us:seattle`:
|
|
|
|
- `--proxy protonvpn:us` — random server in the country (the chosen server name is logged)
|
|
- `--proxy protonvpn:us:ny` / `protonvpn:ca:vancouver` — by city (name or initials)
|
|
- `--proxy protonvpn:de203` — pin Proton server **#203** (the number shown in the log, e.g. `DE#203`)
|
|
|
|
Use `uk` (Proton's code for the United Kingdom); `gb` is accepted and mapped to `uk` automatically. Proton's
|
|
server numbers are not sequential (a country may have `#203`, `#813`, …), so pick the number from a previous
|
|
run's log line rather than guessing.
|
|
|
|
Selection only offers servers your plan can use (paid accounts are detected automatically) and **prefers paid
|
|
servers over the free pool**, falling back to free only when no paid server is available — a pinned `#NN` always
|
|
wins. **Tor and Secure Core servers are excluded** (both are slow for a plain proxy). Secure Core servers use
|
|
port 443, all others 4443 — handled automatically.
|
|
|
|
### surfsharkvpn (dict)
|
|
|
|
Enable Surfshark VPN proxy service using Surfshark Service credentials (not your login password).
|
|
You may pin specific server IDs per region using `server_map`.
|
|
|
|
You can also select servers by city using the format `--proxy surfsharkvpn:us:seattle`.
|
|
|
|
```yaml
|
|
username: your_surfshark_service_username # https://my.surfshark.com/vpn/manual-setup/main/openvpn
|
|
password: your_surfshark_service_password # service credentials, not account password
|
|
server_map:
|
|
us: 3844 # force US server #3844
|
|
gb: 2697 # force GB server #2697
|
|
au: 4621 # force AU server #4621
|
|
```
|
|
|
|
### hola
|
|
|
|
Enable Hola VPN proxy service. Requires the `hola-proxy` binary to be installed and available in your PATH.
|
|
No configuration is needed under `proxy_providers`. Hola is loaded automatically when the `hola-proxy` binary
|
|
is detected.
|
|
|
|
Once available, use `--proxy hola:us` or similar to connect through Hola.
|
|
|
|
### windscribevpn (dict)
|
|
|
|
Enable Windscribe VPN proxy service using static OpenVPN service credentials.
|
|
|
|
Use the service credentials from https://windscribe.com/getconfig/openvpn (not your account login credentials).
|
|
|
|
```yaml
|
|
proxy_providers:
|
|
windscribevpn:
|
|
username: openvpn_username # From https://windscribe.com/getconfig/openvpn
|
|
password: openvpn_password # Service credentials, NOT your account password
|
|
```
|
|
|
|
#### Server Mapping
|
|
|
|
You can optionally pin specific servers using `server_map`:
|
|
|
|
```yaml
|
|
proxy_providers:
|
|
windscribevpn:
|
|
username: openvpn_username
|
|
password: openvpn_password
|
|
server_map:
|
|
us: us-central-096.totallyacdn.com # Force specific US server
|
|
gb: uk-london-001.totallyacdn.com # Force specific UK server
|
|
```
|
|
|
|
Once configured, use `--proxy windscribevpn:us` or `--proxy windscribevpn:gb` etc. to connect through Windscribe.
|
|
|
|
You can also select specific servers by number (e.g., `--proxy windscribevpn:sg007`) or filter by city
|
|
(e.g., `--proxy windscribevpn:ca:toronto`).
|
|
|
|
### gluetun (dict)
|
|
|
|
Docker-managed VPN proxy supporting 50+ VPN providers via Gluetun. See [GLUETUN.md](GLUETUN.md) for full
|
|
configuration and usage details.
|
|
|
|
```yaml
|
|
proxy_providers:
|
|
gluetun:
|
|
providers:
|
|
windscribe:
|
|
vpn_type: openvpn
|
|
credentials:
|
|
username: "YOUR_OPENVPN_USERNAME"
|
|
password: "YOUR_OPENVPN_PASSWORD"
|
|
```
|
|
|
|
Usage: `--proxy gluetun:windscribe:us`
|
|
|
|
---
|
|
|
|
## headers (dict)
|
|
|
|
Case-Insensitive dictionary of headers that all Services begin their Request Session state with.
|
|
All requests will use these unless changed explicitly or implicitly via a Server response.
|
|
These should be sane defaults and anything that would only be useful for some Services should not
|
|
be put here.
|
|
|
|
Avoid headers like 'Accept-Encoding' as that would be a compatibility header that the underlying
|
|
HTTP backend (rnet) will set for you as part of its browser impersonation profile.
|
|
|
|
I recommend using,
|
|
|
|
```yaml
|
|
Accept-Language: "en-US,en;q=0.8"
|
|
User-Agent: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/128.0.0.0 Safari/537.36"
|
|
```
|
|
|
|
---
|
|
|
|
## HTTP Session Backend
|
|
|
|
unshackle uses [`rnet`](https://github.com/0x676e67/rnet) (Rust + BoringSSL) for HTTP with TLS
|
|
fingerprinting. `RnetSession` is a drop-in `requests.Session` replacement and is what
|
|
`self.session` exposes to services. It supports:
|
|
|
|
- Browser/app impersonation via named `rnet.Impersonate` presets (Chrome, Edge, Firefox, Safari,
|
|
OkHttp, etc.) — picks JA3, ALPN, HTTP/2 SETTINGS and header order to match the chosen client.
|
|
- Native rnet proxy support (HTTP, HTTPS, SOCKS5) — used by all proxy providers below.
|
|
- Cookie-jar and `requests`-style `data=` / `json=` / `headers=` kwargs for compatibility.
|
|
|
|
The legacy `curl_cffi` backend has been removed. The config key is still spelled
|
|
`curl_impersonate` for backward compatibility, but its value now selects an rnet preset.
|
|
|
|
### curl_impersonate (dict)
|
|
|
|
```yaml
|
|
curl_impersonate:
|
|
browser: Chrome131 # exact rnet.Impersonate preset name
|
|
```
|
|
|
|
`browser` must be an exact `rnet.Impersonate` preset name (e.g. `Chrome131`, `Chrome124`,
|
|
`Edge101`, `Firefox133`, `Safari18`, `OkHttp4_12`). See the rnet README for the full list.
|
|
Default when unset: `Chrome131`.
|
|
|
|
---
|