Files
unshackle/NETWORK_CONFIG/index.html
T
2026-07-02 15:20:50 +00:00

1997 lines
63 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!doctype html>
<html lang="en" class="no-js">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<meta name="description" content="Configuration reference for unshackle">
<link rel="canonical" href="https://docs.unshackle.dev/NETWORK_CONFIG/">
<link rel="prev" href="../DRM_CONFIG/">
<link rel="next" href="../GLUETUN/">
<link rel="icon" href="../assets/favicon.svg">
<meta name="generator" content="mkdocs-1.6.1, mkdocs-material-9.7.6">
<title>Network & Proxy - unshackle</title>
<link rel="stylesheet" href="../assets/stylesheets/main.484c7ddc.min.css">
<link rel="stylesheet" href="../assets/stylesheets/palette.ab4e12ef.min.css">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:300,300i,400,400i,700,700i%7CRoboto+Mono:400,400i,700,700i&display=fallback">
<style>:root{--md-text-font:"Roboto";--md-code-font:"Roboto Mono"}</style>
<script>__md_scope=new URL("..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script>
</head>
<body dir="ltr" data-md-color-scheme="default" data-md-color-primary="indigo" data-md-color-accent="indigo">
<input class="md-toggle" data-md-toggle="drawer" type="checkbox" id="__drawer" autocomplete="off">
<input class="md-toggle" data-md-toggle="search" type="checkbox" id="__search" autocomplete="off">
<label class="md-overlay" for="__drawer"></label>
<div data-md-component="skip">
<a href="#network-proxy-configuration" class="md-skip">
Skip to content
</a>
</div>
<div data-md-component="announce">
</div>
<header class="md-header" data-md-component="header">
<nav class="md-header__inner md-grid" aria-label="Header">
<a href=".." title="unshackle" class="md-header__button md-logo" aria-label="unshackle" data-md-component="logo">
<svg xmlns="http://www.w3.org/2000/svg" height="24" viewBox="0 -960 960 960" width="24"><path d="m800-274-80-80v-206H514l-80-80h166v-80q0-50-34.5-85T481-840q-50 0-84 34.5T363-720v9l-73-73q22-61 75-98.5T481-920q83 0 141 58.5T680-720v80h40q33 0 56.5 23.5T800-560v286Zm20 246-62-62q-11 5-20 7.5T720-80H240q-33 0-56.5-23.5T160-160v-400q0-25 14.5-46t37.5-30L28-820l56-56L876-84l-56 56ZM686-160 539-309q-11 11-25.5 17t-31.5 6q-33 0-56.5-23.5T402-366q0-17 6-31.5t17-25.5L286-560h-46v400h446ZM486-360Zm131-97Z"/></svg>
</a>
<label class="md-header__button md-icon" for="__drawer">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg>
</label>
<div class="md-header__title" data-md-component="header-title">
<div class="md-header__ellipsis">
<div class="md-header__topic">
<span class="md-ellipsis">
unshackle
</span>
</div>
<div class="md-header__topic" data-md-component="header-topic">
<span class="md-ellipsis">
Network & Proxy
</span>
</div>
</div>
</div>
<form class="md-header__option" data-md-component="palette">
<input class="md-option" data-md-color-media="(prefers-color-scheme)" data-md-color-scheme="default" data-md-color-primary="indigo" data-md-color-accent="indigo" aria-label="Switch to light mode" type="radio" name="__palette" id="__palette_0">
<label class="md-header__button md-icon" title="Switch to light mode" for="__palette_1" hidden>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M3.9 12c0-1.71 1.39-3.1 3.1-3.1h4V7H7a5 5 0 0 0-5 5 5 5 0 0 0 5 5h4v-1.9H7c-1.71 0-3.1-1.39-3.1-3.1M8 13h8v-2H8zm9-6h-4v1.9h4c1.71 0 3.1 1.39 3.1 3.1s-1.39 3.1-3.1 3.1h-4V17h4a5 5 0 0 0 5-5 5 5 0 0 0-5-5"/></svg>
</label>
<input class="md-option" data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme="default" data-md-color-primary="indigo" data-md-color-accent="indigo" aria-label="Switch to dark mode" type="radio" name="__palette" id="__palette_1">
<label class="md-header__button md-icon" title="Switch to dark mode" for="__palette_2" hidden>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M17 7H7a5 5 0 0 0-5 5 5 5 0 0 0 5 5h10a5 5 0 0 0 5-5 5 5 0 0 0-5-5m0 8a3 3 0 0 1-3-3 3 3 0 0 1 3-3 3 3 0 0 1 3 3 3 3 0 0 1-3 3"/></svg>
</label>
<input class="md-option" data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme="slate" data-md-color-primary="black" data-md-color-accent="indigo" aria-label="Switch to system preference" type="radio" name="__palette" id="__palette_2">
<label class="md-header__button md-icon" title="Switch to system preference" for="__palette_0" hidden>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M17 7H7a5 5 0 0 0-5 5 5 5 0 0 0 5 5h10a5 5 0 0 0 5-5 5 5 0 0 0-5-5M7 15a3 3 0 0 1-3-3 3 3 0 0 1 3-3 3 3 0 0 1 3 3 3 3 0 0 1-3 3"/></svg>
</label>
</form>
<script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script>
<label class="md-header__button md-icon" for="__search">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg>
</label>
<div class="md-search" data-md-component="search" role="dialog">
<label class="md-search__overlay" for="__search"></label>
<div class="md-search__inner" role="search">
<form class="md-search__form" name="search">
<input type="text" class="md-search__input" name="query" aria-label="Search" placeholder="Search" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck="false" data-md-component="search-query" required>
<label class="md-search__icon md-icon" for="__search">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg>
</label>
<nav class="md-search__options" aria-label="Search">
<a href="javascript:void(0)" class="md-search__icon md-icon" title="Share" aria-label="Share" data-clipboard data-clipboard-text="" data-md-component="search-share" tabindex="-1">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M18 16.08c-.76 0-1.44.3-1.96.77L8.91 12.7c.05-.23.09-.46.09-.7s-.04-.47-.09-.7l7.05-4.11c.54.5 1.25.81 2.04.81a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3c0 .24.04.47.09.7L8.04 9.81C7.5 9.31 6.79 9 6 9a3 3 0 0 0-3 3 3 3 0 0 0 3 3c.79 0 1.5-.31 2.04-.81l7.12 4.15c-.05.21-.08.43-.08.66 0 1.61 1.31 2.91 2.92 2.91s2.92-1.3 2.92-2.91A2.92 2.92 0 0 0 18 16.08"/></svg>
</a>
<button type="reset" class="md-search__icon md-icon" title="Clear" aria-label="Clear" tabindex="-1">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M19 6.41 17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12z"/></svg>
</button>
</nav>
<div class="md-search__suggest" data-md-component="search-suggest"></div>
</form>
<div class="md-search__output">
<div class="md-search__scrollwrap" tabindex="0" data-md-scrollfix>
<div class="md-search-result" data-md-component="search-result">
<div class="md-search-result__meta">
Initializing search
</div>
<ol class="md-search-result__list" role="presentation"></ol>
</div>
</div>
</div>
</div>
</div>
<div class="md-header__source">
<a href="https://github.com/unshackle-dl/unshackle" title="Go to repository" class="md-source" data-md-component="source">
<div class="md-source__icon md-icon">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><!--! Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M439.6 236.1 244 40.5c-5.4-5.5-12.8-8.5-20.4-8.5s-15 3-20.4 8.4L162.5 81l51.5 51.5c27.1-9.1 52.7 16.8 43.4 43.7l49.7 49.7c34.2-11.8 61.2 31 35.5 56.7-26.5 26.5-70.2-2.9-56-37.3L240.3 199v121.9c25.3 12.5 22.3 41.8 9.1 55-6.4 6.4-15.2 10.1-24.3 10.1s-17.8-3.6-24.3-10.1c-17.6-17.6-11.1-46.9 11.2-56v-123c-20.8-8.5-24.6-30.7-18.6-45L142.6 101 8.5 235.1C3 240.6 0 247.9 0 255.5s3 15 8.5 20.4l195.6 195.7c5.4 5.4 12.7 8.4 20.4 8.4s15-3 20.4-8.4l194.7-194.7c5.4-5.4 8.4-12.8 8.4-20.4s-3-15-8.4-20.4"/></svg>
</div>
<div class="md-source__repository">
GitHub
</div>
</a>
</div>
</nav>
</header>
<div class="md-container" data-md-component="container">
<nav class="md-tabs" aria-label="Tabs" data-md-component="tabs">
<div class="md-grid">
<ul class="md-tabs__list">
<li class="md-tabs__item">
<a href=".." class="md-tabs__link">
Home
</a>
</li>
<li class="md-tabs__item">
<a href="../CREATING_A_SERVICE/" class="md-tabs__link">
Creating a Service
</a>
</li>
<li class="md-tabs__item md-tabs__item--active">
<a href="../SERVICE_CONFIG/" class="md-tabs__link">
Configuration
</a>
</li>
<li class="md-tabs__item">
<a href="../API/" class="md-tabs__link">
REST API
</a>
</li>
<li class="md-tabs__item">
<a href="../DEBUG_LOGGING/" class="md-tabs__link">
Reference
</a>
</li>
</ul>
</div>
</nav>
<main class="md-main" data-md-component="main">
<div class="md-main__inner md-grid">
<div class="md-sidebar md-sidebar--primary" data-md-component="sidebar" data-md-type="navigation" >
<div class="md-sidebar__scrollwrap">
<div class="md-sidebar__inner">
<nav class="md-nav md-nav--primary md-nav--lifted" aria-label="Navigation" data-md-level="0">
<label class="md-nav__title" for="__drawer">
<a href=".." title="unshackle" class="md-nav__button md-logo" aria-label="unshackle" data-md-component="logo">
<svg xmlns="http://www.w3.org/2000/svg" height="24" viewBox="0 -960 960 960" width="24"><path d="m800-274-80-80v-206H514l-80-80h166v-80q0-50-34.5-85T481-840q-50 0-84 34.5T363-720v9l-73-73q22-61 75-98.5T481-920q83 0 141 58.5T680-720v80h40q33 0 56.5 23.5T800-560v286Zm20 246-62-62q-11 5-20 7.5T720-80H240q-33 0-56.5-23.5T160-160v-400q0-25 14.5-46t37.5-30L28-820l56-56L876-84l-56 56ZM686-160 539-309q-11 11-25.5 17t-31.5 6q-33 0-56.5-23.5T402-366q0-17 6-31.5t17-25.5L286-560h-46v400h446ZM486-360Zm131-97Z"/></svg>
</a>
unshackle
</label>
<div class="md-nav__source">
<a href="https://github.com/unshackle-dl/unshackle" title="Go to repository" class="md-source" data-md-component="source">
<div class="md-source__icon md-icon">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><!--! Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M439.6 236.1 244 40.5c-5.4-5.5-12.8-8.5-20.4-8.5s-15 3-20.4 8.4L162.5 81l51.5 51.5c27.1-9.1 52.7 16.8 43.4 43.7l49.7 49.7c34.2-11.8 61.2 31 35.5 56.7-26.5 26.5-70.2-2.9-56-37.3L240.3 199v121.9c25.3 12.5 22.3 41.8 9.1 55-6.4 6.4-15.2 10.1-24.3 10.1s-17.8-3.6-24.3-10.1c-17.6-17.6-11.1-46.9 11.2-56v-123c-20.8-8.5-24.6-30.7-18.6-45L142.6 101 8.5 235.1C3 240.6 0 247.9 0 255.5s3 15 8.5 20.4l195.6 195.7c5.4 5.4 12.7 8.4 20.4 8.4s15-3 20.4-8.4l194.7-194.7c5.4-5.4 8.4-12.8 8.4-20.4s-3-15-8.4-20.4"/></svg>
</div>
<div class="md-source__repository">
GitHub
</div>
</a>
</div>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href=".." class="md-nav__link">
<span class="md-ellipsis">
Home
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../CREATING_A_SERVICE/" class="md-nav__link">
<span class="md-ellipsis">
Creating a Service
</span>
</a>
</li>
<li class="md-nav__item md-nav__item--active md-nav__item--section md-nav__item--nested">
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3" checked>
<label class="md-nav__link" for="__nav_3" id="__nav_3_label" tabindex="">
<span class="md-ellipsis">
Configuration
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_3_label" aria-expanded="true">
<label class="md-nav__title" for="__nav_3">
<span class="md-nav__icon md-icon"></span>
Configuration
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../SERVICE_CONFIG/" class="md-nav__link">
<span class="md-ellipsis">
Service Integration & Auth
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../DOWNLOAD_CONFIG/" class="md-nav__link">
<span class="md-ellipsis">
Download & Processing
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../OUTPUT_CONFIG/" class="md-nav__link">
<span class="md-ellipsis">
Output & Naming
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../SUBTITLE_CONFIG/" class="md-nav__link">
<span class="md-ellipsis">
Subtitles
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../DRM_CONFIG/" class="md-nav__link">
<span class="md-ellipsis">
DRM & CDM
</span>
</a>
</li>
<li class="md-nav__item md-nav__item--active">
<input class="md-nav__toggle md-toggle" type="checkbox" id="__toc">
<label class="md-nav__link md-nav__link--active" for="__toc">
<span class="md-ellipsis">
Network & Proxy
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<a href="./" class="md-nav__link md-nav__link--active">
<span class="md-ellipsis">
Network & Proxy
</span>
</a>
<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
<label class="md-nav__title" for="__toc">
<span class="md-nav__icon md-icon"></span>
Table of contents
</label>
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
<li class="md-nav__item">
<a href="#proxy_providers-dict" class="md-nav__link">
<span class="md-ellipsis">
proxy_providers (dict)
</span>
</a>
<nav class="md-nav" aria-label="proxy_providers (dict)">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#basic-dictstr-strlist" class="md-nav__link">
<span class="md-ellipsis">
basic (dict[str, str|list])
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#nordvpn-dict" class="md-nav__link">
<span class="md-ellipsis">
nordvpn (dict)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#protonvpn-dict" class="md-nav__link">
<span class="md-ellipsis">
protonvpn (dict)
</span>
</a>
<nav class="md-nav" aria-label="protonvpn (dict)">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#tv-login-self-sustaining-recommended" class="md-nav__link">
<span class="md-ellipsis">
TV login (self-sustaining, recommended)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#cookie-export-easiest-to-collect-but-lapses" class="md-nav__link">
<span class="md-ellipsis">
Cookie export (easiest to collect, but lapses)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#resetting" class="md-nav__link">
<span class="md-ellipsis">
Resetting
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#troubleshooting" class="md-nav__link">
<span class="md-ellipsis">
Troubleshooting
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#configuration" class="md-nav__link">
<span class="md-ellipsis">
Configuration
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#surfsharkvpn-dict" class="md-nav__link">
<span class="md-ellipsis">
surfsharkvpn (dict)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#hola" class="md-nav__link">
<span class="md-ellipsis">
hola
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#windscribevpn-dict" class="md-nav__link">
<span class="md-ellipsis">
windscribevpn (dict)
</span>
</a>
<nav class="md-nav" aria-label="windscribevpn (dict)">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#server-mapping" class="md-nav__link">
<span class="md-ellipsis">
Server Mapping
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#gluetun-dict" class="md-nav__link">
<span class="md-ellipsis">
gluetun (dict)
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#headers-dict" class="md-nav__link">
<span class="md-ellipsis">
headers (dict)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#http-session-backend" class="md-nav__link">
<span class="md-ellipsis">
HTTP Session Backend
</span>
</a>
<nav class="md-nav" aria-label="HTTP Session Backend">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#network-dict" class="md-nav__link">
<span class="md-ellipsis">
network (dict)
</span>
</a>
</li>
</ul>
</nav>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="../GLUETUN/" class="md-nav__link">
<span class="md-ellipsis">
Gluetun VPN
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../ADVANCED_CONFIG/" class="md-nav__link">
<span class="md-ellipsis">
Advanced & System
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_4" >
<label class="md-nav__link" for="__nav_4" id="__nav_4_label" tabindex="0">
<span class="md-ellipsis">
REST API
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_4_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_4">
<span class="md-nav__icon md-icon"></span>
REST API
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../API/" class="md-nav__link">
<span class="md-ellipsis">
Overview
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../api/quick-start/" class="md-nav__link">
<span class="md-ellipsis">
Quick Start
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../api/authentication/" class="md-nav__link">
<span class="md-ellipsis">
Authentication
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../api/endpoints/" class="md-nav__link">
<span class="md-ellipsis">
Endpoints
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../api/endpoint-map/" class="md-nav__link">
<span class="md-ellipsis">
Endpoint Map
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../api/download-job-lifecycle/" class="md-nav__link">
<span class="md-ellipsis">
Download Job Lifecycle
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../api/remote-service-sessions/" class="md-nav__link">
<span class="md-ellipsis">
Remote Service Sessions
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../api/client-configuration/" class="md-nav__link">
<span class="md-ellipsis">
Client Configuration
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../api/error-responses/" class="md-nav__link">
<span class="md-ellipsis">
Error Responses
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_5" >
<label class="md-nav__link" for="__nav_5" id="__nav_5_label" tabindex="0">
<span class="md-ellipsis">
Reference
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_5_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_5">
<span class="md-nav__icon md-icon"></span>
Reference
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../DEBUG_LOGGING/" class="md-nav__link">
<span class="md-ellipsis">
Debug Logging
</span>
</a>
</li>
</ul>
</nav>
</li>
</ul>
</nav>
</div>
</div>
</div>
<div class="md-sidebar md-sidebar--secondary" data-md-component="sidebar" data-md-type="toc" >
<div class="md-sidebar__scrollwrap">
<div class="md-sidebar__inner">
<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
<label class="md-nav__title" for="__toc">
<span class="md-nav__icon md-icon"></span>
Table of contents
</label>
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
<li class="md-nav__item">
<a href="#proxy_providers-dict" class="md-nav__link">
<span class="md-ellipsis">
proxy_providers (dict)
</span>
</a>
<nav class="md-nav" aria-label="proxy_providers (dict)">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#basic-dictstr-strlist" class="md-nav__link">
<span class="md-ellipsis">
basic (dict[str, str|list])
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#nordvpn-dict" class="md-nav__link">
<span class="md-ellipsis">
nordvpn (dict)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#protonvpn-dict" class="md-nav__link">
<span class="md-ellipsis">
protonvpn (dict)
</span>
</a>
<nav class="md-nav" aria-label="protonvpn (dict)">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#tv-login-self-sustaining-recommended" class="md-nav__link">
<span class="md-ellipsis">
TV login (self-sustaining, recommended)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#cookie-export-easiest-to-collect-but-lapses" class="md-nav__link">
<span class="md-ellipsis">
Cookie export (easiest to collect, but lapses)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#resetting" class="md-nav__link">
<span class="md-ellipsis">
Resetting
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#troubleshooting" class="md-nav__link">
<span class="md-ellipsis">
Troubleshooting
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#configuration" class="md-nav__link">
<span class="md-ellipsis">
Configuration
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#surfsharkvpn-dict" class="md-nav__link">
<span class="md-ellipsis">
surfsharkvpn (dict)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#hola" class="md-nav__link">
<span class="md-ellipsis">
hola
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#windscribevpn-dict" class="md-nav__link">
<span class="md-ellipsis">
windscribevpn (dict)
</span>
</a>
<nav class="md-nav" aria-label="windscribevpn (dict)">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#server-mapping" class="md-nav__link">
<span class="md-ellipsis">
Server Mapping
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#gluetun-dict" class="md-nav__link">
<span class="md-ellipsis">
gluetun (dict)
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#headers-dict" class="md-nav__link">
<span class="md-ellipsis">
headers (dict)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#http-session-backend" class="md-nav__link">
<span class="md-ellipsis">
HTTP Session Backend
</span>
</a>
<nav class="md-nav" aria-label="HTTP Session Backend">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#network-dict" class="md-nav__link">
<span class="md-ellipsis">
network (dict)
</span>
</a>
</li>
</ul>
</nav>
</li>
</ul>
</nav>
</div>
</div>
</div>
<div class="md-content" data-md-component="content">
<article class="md-content__inner md-typeset">
<h1 id="network-proxy-configuration">Network &amp; Proxy Configuration<a class="headerlink" href="#network-proxy-configuration" title="Permanent link">&para;</a></h1>
<p>This document covers network and proxy configuration options for bypassing geofencing and managing connections.</p>
<h2 id="proxy_providers-dict">proxy_providers (dict)<a class="headerlink" href="#proxy_providers-dict" title="Permanent link">&para;</a></h2>
<p>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 <code>--proxy</code>. You can specify which provider
to use by prefixing it with the provider key name, e.g., <code>--proxy basic:de</code> or <code>--proxy nordvpn:de</code>. Some providers
support specific query formats for selecting a country/server.</p>
<h3 id="basic-dictstr-strlist">basic (dict[str, str|list])<a class="headerlink" href="#basic-dictstr-strlist" title="Permanent link">&para;</a></h3>
<p>Define a mapping of country to proxy to use where required.
The keys are region Alpha 2 Country Codes. Alpha 2 Country Codes are <code>[a-z]{2}</code> codes, e.g., <code>us</code>, <code>gb</code>, and <code>jp</code>.
Don't get this mixed up with language codes like <code>en</code> vs. <code>gb</code>, or <code>ja</code> vs. <code>jp</code>.</p>
<p>Do note that each key's value can be a list of strings, or a string. For example,</p>
<div class="language-yaml highlight"><pre><span></span><code><span id="__span-0-1"><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="nt">us</span><span class="p">:</span>
</span><span id="__span-0-2"><a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a><span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="s">&quot;http://john%40email.tld:password123@proxy-us.domain.tld:8080&quot;</span>
</span><span id="__span-0-3"><a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a><span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="s">&quot;http://jane%40email.tld:password456@proxy-us.domain2.tld:8080&quot;</span>
</span><span id="__span-0-4"><a id="__codelineno-0-4" name="__codelineno-0-4" href="#__codelineno-0-4"></a><span class="nt">de</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;https://127.0.0.1:8080&quot;</span>
</span></code></pre></div>
<p>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., <code>--proxy basic:us2</code> will choose the
second proxy of the US list.</p>
<h3 id="nordvpn-dict">nordvpn (dict)<a class="headerlink" href="#nordvpn-dict" title="Permanent link">&para;</a></h3>
<p>Set your NordVPN Service credentials with <code>username</code> and <code>password</code> keys to automate the use of NordVPN as a Proxy
system where required.</p>
<p>You can also specify specific servers to use per-region with the <code>server_map</code> key.
Sometimes a specific server works best for a service than others, so hard-coding one for a day or two helps.</p>
<p>You can also select servers by city using the format <code>--proxy nordvpn:us:seattle</code> or <code>--proxy nordvpn:ca:calgary</code>.</p>
<p>For example,</p>
<div class="language-yaml highlight"><pre><span></span><code><span id="__span-1-1"><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a><span class="nt">username</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">zxqsR7C5CyGwmGb6KSvk8qsZ</span><span class="w"> </span><span class="c1"># example of the login format</span>
</span><span id="__span-1-2"><a id="__codelineno-1-2" name="__codelineno-1-2" href="#__codelineno-1-2"></a><span class="nt">password</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">wXVHmht22hhRKUEQ32PQVjCZ</span>
</span><span id="__span-1-3"><a id="__codelineno-1-3" name="__codelineno-1-3" href="#__codelineno-1-3"></a><span class="nt">server_map</span><span class="p">:</span>
</span><span id="__span-1-4"><a id="__codelineno-1-4" name="__codelineno-1-4" href="#__codelineno-1-4"></a><span class="w"> </span><span class="nt">us</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">12</span><span class="w"> </span><span class="c1"># force US server #12 for US proxies</span>
</span></code></pre></div>
<p>The username and password should NOT be your normal NordVPN Account Credentials.
They should be the <code>Service credentials</code> which can be found on your Nord Account Dashboard.</p>
<p>Once set, you can also specifically opt in to use a NordVPN proxy by specifying <code>--proxy nordvpn:gb</code> or such.
You can even set a specific server number this way, e.g., <code>--proxy nordvpn:gb2366</code>.</p>
<p>Note that <code>gb</code> is used instead of <code>uk</code> to be more consistent across regional systems.</p>
<h3 id="protonvpn-dict">protonvpn (dict)<a class="headerlink" href="#protonvpn-dict" title="Permanent link">&para;</a></h3>
<p>Enable Proton VPN as a proxy provider. Proton mints short-lived HTTPS proxy credentials per session, so
authentication reuses a Proton account session (obtained via TV login or an exported browser session) rather than
static credentials. <strong>Free Proton accounts work</strong>, limited to the free-tier exit countries.</p>
<p>There are two ways to obtain that session — TV login or cookie export. You only need one. They can also coexist: a
cached or cookie session is always tried first, and TV login is only used as a fallback when no session is present.</p>
<h4 id="tv-login-self-sustaining-recommended">TV login (self-sustaining, recommended)<a class="headerlink" href="#tv-login-self-sustaining-recommended" title="Permanent link">&para;</a></h4>
<p>Set <code>enable: true</code> and run any command that uses the proxy. On first use, when no session is cached, unshackle
prints a code and pauses:</p>
<ol>
<li>Open <code>https://account.proton.me/vpn/tv/code</code> in a browser where you are signed in to Proton.</li>
<li>Enter the code shown in the terminal and approve it.</li>
<li>Return to the terminal and <strong>press Enter</strong> to continue.</li>
</ol>
<p>The minted refresh token is cached at <code>&lt;cache&gt;/vpn/protonvpn.json</code> and <strong>refreshes on its own forever after</strong>, so
this is genuinely a one-time step — later runs load straight from the cache without prompting. The prompt is <strong>off
by default</strong> (<code>enable: false</code>) so nobody is prompted unexpectedly, and it is skipped automatically when there is no
interactive terminal (e.g. under <code>serve</code>, cron, or piped input) — in those contexts, use a cookie export or run an
interactive command once to seed the cache first.</p>
<h4 id="cookie-export-easiest-to-collect-but-lapses">Cookie export (easiest to collect, but lapses)<a class="headerlink" href="#cookie-export-easiest-to-collect-but-lapses" title="Permanent link">&para;</a></h4>
<p>Export the cookies for <code>account.proton.me</code> <strong>or</strong> <code>account.protonvpn.com</code> (Netscape <code>cookies.txt</code> or a JSON cookie
list) and save them at <code>&lt;cookies&gt;/vpn/protonvpn.txt</code>. The provider auto-loads when that file exists (no YAML
required); cookies for other Proton apps (e.g. <code>mail.proton.me</code>) are ignored automatically.</p>
<ul>
<li>The export <strong>must include the <code>AUTH-&lt;UID&gt;</code> cookie</strong>. It is <strong>HttpOnly</strong> — many one-click cookie-export
extensions skip HttpOnly cookies by default, which is the most common reason an export "doesn't work". Use an
exporter that includes them.</li>
<li>A browser session <strong>cannot be refreshed headlessly</strong> — Proton rotates browser refresh tokens and ties them to
the live browser. unshackle therefore uses the cookie's access token only (it never tries to refresh it) and the
session works until that token expires (Proton's TTL, typically ~24h); after that you must re-export. For a
set-and-forget setup, prefer TV login.</li>
<li>Cookies are read fresh from the file on every run and are <strong>never written to the cache</strong>. If a TV-login cache
also exists, it is preferred unless the cookie file is newer — so to force the cookie session, just re-save
(re-export) the cookie file.</li>
</ul>
<h4 id="resetting">Resetting<a class="headerlink" href="#resetting" title="Permanent link">&para;</a></h4>
<p>To start clean, delete both <code>&lt;cookies&gt;/vpn/protonvpn.txt</code> and <code>&lt;cache&gt;/vpn/protonvpn.json</code>.</p>
<h4 id="troubleshooting">Troubleshooting<a class="headerlink" href="#troubleshooting" title="Permanent link">&para;</a></h4>
<ul>
<li><strong><code>Proton: no session available …</code></strong> — no cookies and no cache were found. Either export cookies, or set
<code>enable: true</code> and run from an interactive terminal (the prompt is skipped on non-tty stdin).</li>
<li><strong><code>Proton: session expired; re-export … cookies</code></strong> — a cookie session's access token lapsed and cannot be
refreshed (expected for cookie auth). Re-export the cookies, or switch to TV login.</li>
</ul>
<h4 id="configuration">Configuration<a class="headerlink" href="#configuration" title="Permanent link">&para;</a></h4>
<p>Configuration is optional — only add a block to enable TV login or override defaults:</p>
<div class="language-yaml highlight"><pre><span></span><code><span id="__span-2-1"><a id="__codelineno-2-1" name="__codelineno-2-1" href="#__codelineno-2-1"></a><span class="nt">proxy_providers</span><span class="p">:</span>
</span><span id="__span-2-2"><a id="__codelineno-2-2" name="__codelineno-2-2" href="#__codelineno-2-2"></a><span class="w"> </span><span class="nt">protonvpn</span><span class="p">:</span>
</span><span id="__span-2-3"><a id="__codelineno-2-3" name="__codelineno-2-3" href="#__codelineno-2-3"></a><span class="w"> </span><span class="nt">enable</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span><span class="w"> </span><span class="c1"># prompt the one-time TV login when no session is cached (default false)</span>
</span><span id="__span-2-4"><a id="__codelineno-2-4" name="__codelineno-2-4" href="#__codelineno-2-4"></a><span class="w"> </span><span class="nt">cookie_path</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">/path/to/protonvpn.txt</span><span class="w"> </span><span class="c1"># optional; defaults to &lt;cookies&gt;/vpn/protonvpn.txt</span>
</span><span id="__span-2-5"><a id="__codelineno-2-5" name="__codelineno-2-5" href="#__codelineno-2-5"></a><span class="w"> </span><span class="nt">cache_path</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">/path/to/protonvpn.json</span><span class="w"> </span><span class="c1"># optional; defaults to &lt;cache&gt;/vpn/protonvpn.json</span>
</span><span id="__span-2-6"><a id="__codelineno-2-6" name="__codelineno-2-6" href="#__codelineno-2-6"></a><span class="w"> </span><span class="nt">timeout</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">10</span><span class="w"> </span><span class="c1"># optional; per-request timeout in seconds (default 10)</span>
</span><span id="__span-2-7"><a id="__codelineno-2-7" name="__codelineno-2-7" href="#__codelineno-2-7"></a><span class="w"> </span><span class="nt">server_map</span><span class="p">:</span>
</span><span id="__span-2-8"><a id="__codelineno-2-8" name="__codelineno-2-8" href="#__codelineno-2-8"></a><span class="w"> </span><span class="nt">stream-us</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">us:ny</span><span class="w"> </span><span class="c1"># optional alias -&gt; country / country:city / countryNN</span>
</span></code></pre></div>
<p>Query formats (after the provider prefix). City uses the NordVPN-style colon, like <code>nordvpn:us:seattle</code>:</p>
<ul>
<li><code>--proxy protonvpn:us</code> — random server in the country (the chosen server name is logged)</li>
<li><code>--proxy protonvpn:us:ny</code> / <code>protonvpn:ca:vancouver</code> — by city (name or initials)</li>
<li><code>--proxy protonvpn:de203</code> — pin Proton server <strong>#203</strong> (the number shown in the log, e.g. <code>DE#203</code>)</li>
</ul>
<p>Use <code>uk</code> (Proton's code for the United Kingdom); <code>gb</code> is accepted and mapped to <code>uk</code> automatically. Proton's
server numbers are not sequential (a country may have <code>#203</code>, <code>#813</code>, …), so pick the number from a previous
run's log line rather than guessing.</p>
<p>Selection only offers servers your plan can use (paid accounts are detected automatically) and <strong>prefers paid
servers over the free pool</strong>, falling back to free only when no paid server is available — a pinned <code>#NN</code> always
wins. <strong>Tor and Secure Core servers are excluded</strong> (both are slow for a plain proxy). Secure Core servers use
port 443, all others 4443 — handled automatically.</p>
<h3 id="surfsharkvpn-dict">surfsharkvpn (dict)<a class="headerlink" href="#surfsharkvpn-dict" title="Permanent link">&para;</a></h3>
<p>Enable Surfshark VPN proxy service using Surfshark Service credentials (not your login password).
You may pin specific server IDs per region using <code>server_map</code>.</p>
<p>You can also select servers by city using the format <code>--proxy surfsharkvpn:us:seattle</code>.</p>
<div class="language-yaml highlight"><pre><span></span><code><span id="__span-3-1"><a id="__codelineno-3-1" name="__codelineno-3-1" href="#__codelineno-3-1"></a><span class="nt">username</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">your_surfshark_service_username</span><span class="w"> </span><span class="c1"># https://my.surfshark.com/vpn/manual-setup/main/openvpn</span>
</span><span id="__span-3-2"><a id="__codelineno-3-2" name="__codelineno-3-2" href="#__codelineno-3-2"></a><span class="nt">password</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">your_surfshark_service_password</span><span class="w"> </span><span class="c1"># service credentials, not account password</span>
</span><span id="__span-3-3"><a id="__codelineno-3-3" name="__codelineno-3-3" href="#__codelineno-3-3"></a><span class="nt">server_map</span><span class="p">:</span>
</span><span id="__span-3-4"><a id="__codelineno-3-4" name="__codelineno-3-4" href="#__codelineno-3-4"></a><span class="w"> </span><span class="nt">us</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">3844</span><span class="w"> </span><span class="c1"># force US server #3844</span>
</span><span id="__span-3-5"><a id="__codelineno-3-5" name="__codelineno-3-5" href="#__codelineno-3-5"></a><span class="w"> </span><span class="nt">gb</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">2697</span><span class="w"> </span><span class="c1"># force GB server #2697</span>
</span><span id="__span-3-6"><a id="__codelineno-3-6" name="__codelineno-3-6" href="#__codelineno-3-6"></a><span class="w"> </span><span class="nt">au</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">4621</span><span class="w"> </span><span class="c1"># force AU server #4621</span>
</span></code></pre></div>
<h3 id="hola">hola<a class="headerlink" href="#hola" title="Permanent link">&para;</a></h3>
<p>Enable Hola VPN proxy service. Requires the <code>hola-proxy</code> binary to be installed and available in your PATH.
No configuration is needed under <code>proxy_providers</code>. Hola is loaded automatically when the <code>hola-proxy</code> binary
is detected.</p>
<p>Once available, use <code>--proxy hola:us</code> or similar to connect through Hola.</p>
<h3 id="windscribevpn-dict">windscribevpn (dict)<a class="headerlink" href="#windscribevpn-dict" title="Permanent link">&para;</a></h3>
<p>Enable Windscribe VPN proxy service using static OpenVPN service credentials.</p>
<p>Use the service credentials from https://windscribe.com/getconfig/openvpn (not your account login credentials).</p>
<div class="language-yaml highlight"><pre><span></span><code><span id="__span-4-1"><a id="__codelineno-4-1" name="__codelineno-4-1" href="#__codelineno-4-1"></a><span class="nt">proxy_providers</span><span class="p">:</span>
</span><span id="__span-4-2"><a id="__codelineno-4-2" name="__codelineno-4-2" href="#__codelineno-4-2"></a><span class="w"> </span><span class="nt">windscribevpn</span><span class="p">:</span>
</span><span id="__span-4-3"><a id="__codelineno-4-3" name="__codelineno-4-3" href="#__codelineno-4-3"></a><span class="w"> </span><span class="nt">username</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">openvpn_username</span><span class="w"> </span><span class="c1"># From https://windscribe.com/getconfig/openvpn</span>
</span><span id="__span-4-4"><a id="__codelineno-4-4" name="__codelineno-4-4" href="#__codelineno-4-4"></a><span class="w"> </span><span class="nt">password</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">openvpn_password</span><span class="w"> </span><span class="c1"># Service credentials, NOT your account password</span>
</span></code></pre></div>
<h4 id="server-mapping">Server Mapping<a class="headerlink" href="#server-mapping" title="Permanent link">&para;</a></h4>
<p>You can optionally pin specific servers using <code>server_map</code>:</p>
<div class="language-yaml highlight"><pre><span></span><code><span id="__span-5-1"><a id="__codelineno-5-1" name="__codelineno-5-1" href="#__codelineno-5-1"></a><span class="nt">proxy_providers</span><span class="p">:</span>
</span><span id="__span-5-2"><a id="__codelineno-5-2" name="__codelineno-5-2" href="#__codelineno-5-2"></a><span class="w"> </span><span class="nt">windscribevpn</span><span class="p">:</span>
</span><span id="__span-5-3"><a id="__codelineno-5-3" name="__codelineno-5-3" href="#__codelineno-5-3"></a><span class="w"> </span><span class="nt">username</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">openvpn_username</span>
</span><span id="__span-5-4"><a id="__codelineno-5-4" name="__codelineno-5-4" href="#__codelineno-5-4"></a><span class="w"> </span><span class="nt">password</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">openvpn_password</span>
</span><span id="__span-5-5"><a id="__codelineno-5-5" name="__codelineno-5-5" href="#__codelineno-5-5"></a><span class="w"> </span><span class="nt">server_map</span><span class="p">:</span>
</span><span id="__span-5-6"><a id="__codelineno-5-6" name="__codelineno-5-6" href="#__codelineno-5-6"></a><span class="w"> </span><span class="nt">us</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">us-central-096.totallyacdn.com</span><span class="w"> </span><span class="c1"># Force specific US server</span>
</span><span id="__span-5-7"><a id="__codelineno-5-7" name="__codelineno-5-7" href="#__codelineno-5-7"></a><span class="w"> </span><span class="nt">gb</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">uk-london-001.totallyacdn.com</span><span class="w"> </span><span class="c1"># Force specific UK server</span>
</span></code></pre></div>
<p>Once configured, use <code>--proxy windscribevpn:us</code> or <code>--proxy windscribevpn:gb</code> etc. to connect through Windscribe.</p>
<p>You can also select specific servers by number (e.g., <code>--proxy windscribevpn:sg007</code>) or filter by city
(e.g., <code>--proxy windscribevpn:ca:toronto</code>).</p>
<h3 id="gluetun-dict">gluetun (dict)<a class="headerlink" href="#gluetun-dict" title="Permanent link">&para;</a></h3>
<p>Docker-managed VPN proxy supporting 50+ VPN providers via Gluetun. See <a href="../GLUETUN/">GLUETUN.md</a> for full
configuration and usage details.</p>
<div class="language-yaml highlight"><pre><span></span><code><span id="__span-6-1"><a id="__codelineno-6-1" name="__codelineno-6-1" href="#__codelineno-6-1"></a><span class="nt">proxy_providers</span><span class="p">:</span>
</span><span id="__span-6-2"><a id="__codelineno-6-2" name="__codelineno-6-2" href="#__codelineno-6-2"></a><span class="w"> </span><span class="nt">gluetun</span><span class="p">:</span>
</span><span id="__span-6-3"><a id="__codelineno-6-3" name="__codelineno-6-3" href="#__codelineno-6-3"></a><span class="w"> </span><span class="nt">providers</span><span class="p">:</span>
</span><span id="__span-6-4"><a id="__codelineno-6-4" name="__codelineno-6-4" href="#__codelineno-6-4"></a><span class="w"> </span><span class="nt">windscribe</span><span class="p">:</span>
</span><span id="__span-6-5"><a id="__codelineno-6-5" name="__codelineno-6-5" href="#__codelineno-6-5"></a><span class="w"> </span><span class="nt">vpn_type</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">openvpn</span>
</span><span id="__span-6-6"><a id="__codelineno-6-6" name="__codelineno-6-6" href="#__codelineno-6-6"></a><span class="w"> </span><span class="nt">credentials</span><span class="p">:</span>
</span><span id="__span-6-7"><a id="__codelineno-6-7" name="__codelineno-6-7" href="#__codelineno-6-7"></a><span class="w"> </span><span class="nt">username</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;YOUR_OPENVPN_USERNAME&quot;</span>
</span><span id="__span-6-8"><a id="__codelineno-6-8" name="__codelineno-6-8" href="#__codelineno-6-8"></a><span class="w"> </span><span class="nt">password</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;YOUR_OPENVPN_PASSWORD&quot;</span>
</span></code></pre></div>
<p>Usage: <code>--proxy gluetun:windscribe:us</code></p>
<hr />
<h2 id="headers-dict">headers (dict)<a class="headerlink" href="#headers-dict" title="Permanent link">&para;</a></h2>
<p>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.</p>
<p>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.</p>
<p>I recommend using,</p>
<div class="language-yaml highlight"><pre><span></span><code><span id="__span-7-1"><a id="__codelineno-7-1" name="__codelineno-7-1" href="#__codelineno-7-1"></a><span class="nt">Accept-Language</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;en-US,en;q=0.8&quot;</span>
</span><span id="__span-7-2"><a id="__codelineno-7-2" name="__codelineno-7-2" href="#__codelineno-7-2"></a><span class="nt">User-Agent</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;Mozilla/5.0</span><span class="nv"> </span><span class="s">(Windows</span><span class="nv"> </span><span class="s">NT</span><span class="nv"> </span><span class="s">10.0;</span><span class="nv"> </span><span class="s">Win64;</span><span class="nv"> </span><span class="s">x64)</span><span class="nv"> </span><span class="s">AppleWebKit/537.36</span><span class="nv"> </span><span class="s">(KHTML,</span><span class="nv"> </span><span class="s">like</span><span class="nv"> </span><span class="s">Gecko)</span><span class="nv"> </span><span class="s">Chrome/128.0.0.0</span><span class="nv"> </span><span class="s">Safari/537.36&quot;</span>
</span></code></pre></div>
<hr />
<h2 id="http-session-backend">HTTP Session Backend<a class="headerlink" href="#http-session-backend" title="Permanent link">&para;</a></h2>
<p>unshackle uses <a href="https://github.com/0x676e67/rnet"><code>rnet</code></a> (Rust + BoringSSL) for HTTP with TLS
fingerprinting. <code>RnetSession</code> is a drop-in <code>requests.Session</code> replacement and is what
<code>self.session</code> exposes to services. It supports:</p>
<ul>
<li>Browser/app impersonation via named <code>rnet.Impersonate</code> presets (Chrome, Edge, Firefox, Safari,
OkHttp, etc.) — picks JA3, ALPN, HTTP/2 SETTINGS and header order to match the chosen client.</li>
<li>Native rnet proxy support (HTTP, HTTPS, SOCKS5) — used by all proxy providers below.</li>
<li>Cookie-jar and <code>requests</code>-style <code>data=</code> / <code>json=</code> / <code>headers=</code> kwargs for compatibility.</li>
</ul>
<p>The legacy <code>curl_cffi</code> backend has been removed.</p>
<h3 id="network-dict">network (dict)<a class="headerlink" href="#network-dict" title="Permanent link">&para;</a></h3>
<p>HTTP session settings: which client to impersonate and how the underlying rnet
client behaves.</p>
<div class="language-yaml highlight"><pre><span></span><code><span id="__span-8-1"><a id="__codelineno-8-1" name="__codelineno-8-1" href="#__codelineno-8-1"></a><span class="nt">network</span><span class="p">:</span>
</span><span id="__span-8-2"><a id="__codelineno-8-2" name="__codelineno-8-2" href="#__codelineno-8-2"></a><span class="w"> </span><span class="nt">browser</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">Chrome131</span><span class="w"> </span><span class="c1"># exact rnet.Impersonate preset name</span>
</span></code></pre></div>
<p><code>browser</code> must be an exact <code>rnet.Impersonate</code> preset name (e.g. <code>Chrome131</code>, <code>Chrome124</code>,
<code>Edge101</code>, <code>Firefox133</code>, <code>Safari18</code>, <code>OkHttp4_12</code>). See the rnet README for the full list.
Default when unset: <code>Chrome131</code>.</p>
<p>The same section accepts optional rnet client tuning keys, forwarded verbatim:</p>
<div class="language-yaml highlight"><pre><span></span><code><span id="__span-9-1"><a id="__codelineno-9-1" name="__codelineno-9-1" href="#__codelineno-9-1"></a><span class="nt">network</span><span class="p">:</span>
</span><span id="__span-9-2"><a id="__codelineno-9-2" name="__codelineno-9-2" href="#__codelineno-9-2"></a><span class="w"> </span><span class="nt">browser</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">Chrome131</span>
</span><span id="__span-9-3"><a id="__codelineno-9-3" name="__codelineno-9-3" href="#__codelineno-9-3"></a><span class="w"> </span><span class="nt">http1_only</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span><span class="w"> </span><span class="c1"># force HTTP/1.1 instead of negotiated HTTP/2</span>
</span><span id="__span-9-4"><a id="__codelineno-9-4" name="__codelineno-9-4" href="#__codelineno-9-4"></a><span class="w"> </span><span class="c1"># http2_only: true</span>
</span><span id="__span-9-5"><a id="__codelineno-9-5" name="__codelineno-9-5" href="#__codelineno-9-5"></a><span class="w"> </span><span class="c1"># pool_max_size: 64 # max total connections in the pool</span>
</span><span id="__span-9-6"><a id="__codelineno-9-6" name="__codelineno-9-6" href="#__codelineno-9-6"></a><span class="w"> </span><span class="c1"># pool_max_idle_per_host: 32</span>
</span><span id="__span-9-7"><a id="__codelineno-9-7" name="__codelineno-9-7" href="#__codelineno-9-7"></a><span class="w"> </span><span class="c1"># tcp_nodelay: true</span>
</span></code></pre></div>
<div class="admonition note">
<p class="admonition-title">Renamed from <code>curl_impersonate</code></p>
<p>This section was previously named <code>curl_impersonate</code> (after the removed backend).
The old spelling still works but is deprecated; rename it to <code>network</code>.</p>
</div>
<div class="admonition tip">
<p class="admonition-title">When to force HTTP/1.1</p>
<p>HTTP/2 is the right default on large CDNs. Force <code>http1_only: true</code> when a host
throttles per connection or has a slow origin behind HTTP/2 flow control — in
benchmarks this gained 30–50% on such hosts, while costing up to 27% on fast
CDNs. Set it only when measurements support it.</p>
</div>
<hr />
</article>
</div>
<script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script>
</div>
<button type="button" class="md-top md-icon" data-md-component="top" hidden>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg>
Back to top
</button>
</main>
<footer class="md-footer">
<nav class="md-footer__inner md-grid" aria-label="Footer" >
<a href="../DRM_CONFIG/" class="md-footer__link md-footer__link--prev" aria-label="Previous: DRM &amp; CDM">
<div class="md-footer__button md-icon">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg>
</div>
<div class="md-footer__title">
<span class="md-footer__direction">
Previous
</span>
<div class="md-ellipsis">
DRM & CDM
</div>
</div>
</a>
<a href="../GLUETUN/" class="md-footer__link md-footer__link--next" aria-label="Next: Gluetun VPN">
<div class="md-footer__title">
<span class="md-footer__direction">
Next
</span>
<div class="md-ellipsis">
Gluetun VPN
</div>
</div>
<div class="md-footer__button md-icon">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg>
</div>
</a>
</nav>
<div class="md-footer-meta md-typeset">
<div class="md-footer-meta__inner md-grid">
<div class="md-copyright">
Made with
<a href="https://squidfunk.github.io/mkdocs-material/" target="_blank" rel="noopener">
Material for MkDocs
</a>
</div>
</div>
</div>
</footer>
</div>
<div class="md-dialog" data-md-component="dialog">
<div class="md-dialog__inner md-typeset"></div>
</div>
<script id="__config" type="application/json">{"annotate": null, "base": "..", "features": ["content.code.annotate", "content.code.copy", "content.tooltips", "navigation.footer", "navigation.indexes", "navigation.sections", "navigation.tabs", "navigation.top", "navigation.tracking", "search.highlight", "search.share", "search.suggest", "toc.follow"], "search": "../assets/javascripts/workers/search.2c215733.min.js", "tags": null, "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}, "version": null}</script>
<script src="../assets/javascripts/bundle.79ae519e.min.js"></script>
</body>
</html>