mirror of
https://github.com/unshackle-dl/unshackle.git
synced 2026-11-12 20:15:10 +00:00
imSp4rky
746bf184d2
A bare query skips a failing provider and errors when none answers; an unknown prefix such as us:seattle fails with a hint. The REST path now loads WindscribeVPN.
108 lines
5.4 KiB
Markdown
108 lines
5.4 KiB
Markdown
# Network & proxy { #network-proxy }
|
|
|
|
## `network`
|
|
|
|
- **Type:** `dict` · **Default:** `{}`
|
|
|
|
TLS-fingerprinting and HTTP client settings for the rnet-based HTTP session.
|
|
|
|
| Sub-key | Type | Default | Description |
|
|
|---------|------|---------|-------------|
|
|
| `browser` | str | `"Chrome131"` | Impersonation preset. Must be an exact preset name (e.g. `Chrome131`, `Firefox135`, `Edge101`, `Safari18`, `OkHttp4_12`, `OkHttp5`, `Opera118`); unknown names raise an error. |
|
|
| `http1_only` | bool | *(unset)* | Force HTTP/1.1. |
|
|
| `http2_only` | bool | *(unset)* | Force HTTP/2. |
|
|
| `connect_timeout` | int | `10` | Connect timeout in seconds. |
|
|
| `read_timeout` | int | `30` | Read timeout in seconds (max gap between response chunks). |
|
|
| `timeout` | int | *(unset)* | Total request timeout in seconds. |
|
|
| `allow_redirects` | bool | *(unset)* | Follow redirects automatically (rnet client default when unset). |
|
|
| `pool_idle_timeout` | int | `55` | Seconds an idle pooled connection is kept (default stays under typical ~60s CDN idle kills). |
|
|
| `pool_max_idle_per_host` | int | `64` | Max idle connections kept per host. |
|
|
| `pool_max_size` | int | *(unset)* | Max total connections in the pool. |
|
|
| `tcp_keepalive` | int | `30` | TCP keepalive time in seconds. |
|
|
| `tcp_keepalive_interval` | int | *(unset)* | TCP keepalive probe interval in seconds. |
|
|
| `tcp_keepalive_retries` | int | *(unset)* | TCP keepalive probe retry count. |
|
|
| `tcp_nodelay` | bool | *(unset)* | Disable Nagle's algorithm. |
|
|
|
|
```yaml
|
|
network:
|
|
browser: Firefox135
|
|
http2_only: true
|
|
```
|
|
|
|
!!! note "Measured effect of `http1_only`"
|
|
Both `http1_only` and `http2_only` are unset by default. In benchmarks, forcing HTTP/1.1
|
|
gained 30 to 50% on hosts that throttle per-connection or stall behind HTTP/2 flow control,
|
|
and **cost up to 27% on fast CDNs**.
|
|
|
|
!!! warning "Renamed from `curl_impersonate`"
|
|
The old `curl_impersonate` section is a deprecated alias. If you still use it, unshackle
|
|
honours it (only when `network` is absent) but emits a `DeprecationWarning`. Rename it to
|
|
`network`.
|
|
|
|
## `headers`
|
|
|
|
- **Type:** `dict` · **Default:** `{}`
|
|
|
|
Default HTTP headers merged into every HTTP session unshackle makes.
|
|
|
|
```yaml
|
|
headers:
|
|
Accept-Language: en-US,en;q=0.9
|
|
```
|
|
|
|
!!! warning "Don't set `Accept-Encoding` (and similar) here"
|
|
Compatibility headers such as `Accept-Encoding` are set by the rnet HTTP backend as part of
|
|
its browser-impersonation profile. If you override them, you break the impersonation
|
|
fingerprint. This block is for cross-service defaults only (for example `Accept-Language`,
|
|
`User-Agent`). Per-service headers belong in that service's own config.
|
|
|
|
## `proxy_providers`
|
|
|
|
- **Type:** `dict` · **Default:** `{}`
|
|
|
|
Proxy/VPN provider configuration. Each sub-key names a proxy provider, and unshackle passes its
|
|
block straight to that provider's constructor. See [Proxies & VPN](../../guide/proxies-and-vpn.md)
|
|
for the full proxy provider guide. Recognised proxy providers and their exit ports:
|
|
|
|
| Provider | Config key | Credentials | Proxy scheme/port |
|
|
|----------|-----------|-------------|-------------------|
|
|
| Basic (static) | `basic` | country → URI(s) | as specified |
|
|
| Control D | `controld` | Write API token (profile/resolver pairs optional) | `http://127.0.0.1:{port}` (local forwarder) |
|
|
| NordVPN | `nordvpn` | **service** credentials (48 chars combined) | `https://...:89` |
|
|
| Surfshark | `surfsharkvpn` | **service** credentials (48 chars combined) | `https://...:443` |
|
|
| Windscribe | `windscribevpn` | service credentials | `https://...:443` |
|
|
| ExpressVPN | `expressvpn` | device login (`enable: true`) / token cache | `https://cat:...@...:443` |
|
|
| ProtonVPN | `protonvpn` | TV login or exported cookies | `https://...:4443` (or `:443` Secure Core) |
|
|
| Gluetun | `gluetun` | per-VPN keys/creds | `http://localhost:{port}` (local Docker) |
|
|
| Hola | *(none, auto)* | none | `http://...:{peer}` |
|
|
|
|
```yaml
|
|
proxy_providers:
|
|
basic:
|
|
us: http://user:pass@1.2.3.4:8080
|
|
de:
|
|
- http://a.example:8080
|
|
- socks5://b.example:1080
|
|
nordvpn:
|
|
username: <service username>
|
|
password: <service password>
|
|
```
|
|
|
|
### `controld`
|
|
|
|
Config keys of the Control D proxy provider. See
|
|
[Control D](../../guide/proxies-and-vpn.md#control-d) for how unshackle uses them.
|
|
|
|
| Key | Type | Default | Meaning |
|
|
|---|---|---|---|
|
|
| `token` | `str` | required | A Control D API token of type *Write*. |
|
|
| `profile` | `str` | none | Optional. The ID of a profile you made for unshackle. Give it together with `resolver`. Without it, unshackle creates `unshackle-<region>` profiles itself. |
|
|
| `resolver` | `str` | none | Optional. The resolver ID of an endpoint that uses `profile`, or its DoH URL `https://dns.controld.com/<resolver>`. |
|
|
| `profiles` | `list` | `[]` | Optional. More pairs, each a mapping with `profile` and `resolver`. |
|
|
| `max_profiles` | `int` | `4` | The most profiles unshackle uses: your pairs plus the `unshackle-*` endpoints on the account. It must be 1 or more. unshackle creates an `unshackle-<region>` profile and endpoint only while the total is lower. |
|
|
|
|
!!! note "Provider loading differs between CLI and REST server"
|
|
The `dl` CLI loads all providers, including `gluetun`. The REST API / remote-client path
|
|
does **not** load `gluetun`, because it starts a local Docker container. ExpressVPN and ProtonVPN also auto-load when their cached session exists, and Hola
|
|
auto-loads whenever the `hola-proxy` binary is present.
|