mirror of
https://github.com/unshackle-dl/unshackle.git
synced 2026-11-15 21:45:10 +00:00
Compare commits
9
Commits
7f155aacba
...
0432f3aee2
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
0432f3aee2 | ||
|
|
45f076eac8 | ||
|
|
76df4106d3 | ||
|
|
d514fbc2d5 | ||
|
|
d799b1039b | ||
|
|
6eeec7ad97 | ||
|
|
f5a17df145 | ||
|
|
82cbad5c3e | ||
|
|
c2abfcd84b |
@@ -2450,6 +2450,11 @@ Click <code>cli</code> entry point plus three abstract methods.</p>
|
||||
<td>IP region codes the service requires. Empty = no geofence. unshackle treats the <strong>first</strong> entry as the main region for auto-proxy.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>GEOBLOCK</code></td>
|
||||
<td><code>tuple[str, ...]</code></td>
|
||||
<td>IP region codes where the service refuses to work. Every other region is allowed. Default <code>()</code>.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>VAULT_TAG</code></td>
|
||||
<td><code>Optional[str]</code></td>
|
||||
<td>Overrides the key-vault namespace so sibling services can share one vault. Default <code>None</code> (use the service's own tag).</td>
|
||||
@@ -2486,10 +2491,17 @@ subtitle work for services that never carry subtitles. Leave it off otherwise.</
|
||||
<p><code>GEOFENCE</code> drives an automatic proxy: on startup, if you did not pass an
|
||||
explicit <code>--proxy</code>, the base class does a live IP check and, if your region is
|
||||
blocked, fetches a proxy to <code>GEOFENCE[0]</code> from your configured proxy providers.</p>
|
||||
<p><code>GEOBLOCK</code> is the negative form: the service works everywhere except the listed
|
||||
regions. With no <code>GEOFENCE</code> to name a main region, a <code>GEOBLOCK</code> hit stops the run
|
||||
with a "not available in your region" error; pass <code>--proxy</code> yourself.</p>
|
||||
<div class="language-python 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="k">class</span><span class="w"> </span><span class="nc">EXAMPLE</span><span class="p">(</span><span class="n">Service</span><span class="p">):</span>
|
||||
</span><span id="__span-3-2"><a id="__codelineno-3-2" name="__codelineno-3-2" href="#__codelineno-3-2"></a> <span class="n">ALIASES</span> <span class="o">=</span> <span class="p">(</span><span class="s2">"EX"</span><span class="p">,</span> <span class="s2">"DOMAIN"</span><span class="p">)</span>
|
||||
</span><span id="__span-3-3"><a id="__codelineno-3-3" name="__codelineno-3-3" href="#__codelineno-3-3"></a> <span class="n">GEOFENCE</span> <span class="o">=</span> <span class="p">(</span><span class="s2">"US"</span><span class="p">,</span> <span class="s2">"UK"</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="n">VAULT_TAG</span> <span class="o">=</span> <span class="s2">"DIFFERENT_NAME"</span>
|
||||
</span><span id="__span-3-5"><a id="__codelineno-3-5" name="__codelineno-3-5" href="#__codelineno-3-5"></a>
|
||||
</span><span id="__span-3-6"><a id="__codelineno-3-6" name="__codelineno-3-6" href="#__codelineno-3-6"></a>
|
||||
</span><span id="__span-3-7"><a id="__codelineno-3-7" name="__codelineno-3-7" href="#__codelineno-3-7"></a><span class="k">class</span><span class="w"> </span><span class="nc">WORLDWIDE</span><span class="p">(</span><span class="n">Service</span><span class="p">):</span>
|
||||
</span><span id="__span-3-8"><a id="__codelineno-3-8" name="__codelineno-3-8" href="#__codelineno-3-8"></a> <span class="n">GEOBLOCK</span> <span class="o">=</span> <span class="p">(</span><span class="s2">"GB"</span><span class="p">,)</span>
|
||||
</span></code></pre></div>
|
||||
<h3 id="what-service__init__-wires-up">What <code>Service.__init__</code> wires up<a class="headerlink" href="#what-service__init__-wires-up" title="Permanent link">¶</a></h3>
|
||||
<p>When you call <code>super().__init__(ctx)</code>, the base class sets up the attributes you
|
||||
|
||||
@@ -2428,13 +2428,13 @@ limit never applies to the dashboard key, and never to <code>/api/health</code>.
|
||||
</span><span id="__span-6-2"><a id="__codelineno-6-2" name="__codelineno-6-2" href="#__codelineno-6-2"></a>[{"tag": "EXAMPLE", "state": "staged", "error": null,
|
||||
</span><span id="__span-6-3"><a id="__codelineno-6-3" name="__codelineno-6-3" href="#__codelineno-6-3"></a> "commit": "9cc230c98f13b83f6c6fe831595b9702d3ba2786", "staged_commit": "5f0aa17...",
|
||||
</span><span id="__span-6-4"><a id="__codelineno-6-4" name="__codelineno-6-4" href="#__codelineno-6-4"></a> "staged_since": 1756908900.0, "sessions": 1, "jobs": 1,
|
||||
</span><span id="__span-6-5"><a id="__codelineno-6-5" name="__codelineno-6-5" href="#__codelineno-6-5"></a> "aliases": ["EXMPL"], "geofence": ["US"]}]
|
||||
</span><span id="__span-6-5"><a id="__codelineno-6-5" name="__codelineno-6-5" href="#__codelineno-6-5"></a> "aliases": ["EXMPL"], "geofence": ["US"], "geoblock": []}]
|
||||
</span></code></pre></div>
|
||||
<p><code>state</code> is <code>loaded</code>, <code>staged</code> or <code>failed</code>. A service that failed to import keeps its error
|
||||
here instead of disappearing, and <code>/status</code> still counts it in the service total - count the
|
||||
<code>state</code> values here for the number that loaded.</p>
|
||||
<p>A <code>staged</code> service has an update on disk that a busy service blocks from the import: the repo
|
||||
pull already happened, so <code>commit</code> (what runs now) and <code>staged_commit</code> (what waits) differ. It swaps in when the last job for that tag finishes. Both commits are <code>null</code>
|
||||
pull already happened, so <code>commit</code> (what runs now) and <code>staged_commit</code> (what waits) differ. It swaps in when the last job and the last remote session for that tag finish. Both commits are <code>null</code>
|
||||
for a service from a plain local directory rather than a git repo.</p>
|
||||
<p>Watch the <code>service</code> event rather than polling for the swap.</p>
|
||||
<h2 id="health">Health<a class="headerlink" href="#health" title="Permanent link">¶</a></h2>
|
||||
@@ -2448,8 +2448,10 @@ missing or a vault's credentials expired. This finds that before a job does.</p>
|
||||
<p><code>status</code> is <code>ok</code>, <code>degraded</code> (an optional dependency is missing) or <code>failing</code> (a required one
|
||||
is). Player binaries are not checked: a headless server never has one and it plays nothing.
|
||||
Each check is <code>ok</code>, <code>warn</code> or <code>fail</code>. Check ids are the binary names, <code>cdm</code>,
|
||||
<code>vault:<name></code> (the vault's configured <code>name</code>, so two vaults of the same type stay apart), and
|
||||
<code>proxies</code>.</p>
|
||||
<code>vault:<name></code> (the vault's configured <code>name</code>, so two vaults of the same type stay apart),
|
||||
<code>bad_keys</code> and <code>proxies</code>. <code>bad_keys</code> warns when the vaults hold no <code>SQLite</code> entry, because only
|
||||
that backend stores the flag for a content key a remote client proved wrong; without it the
|
||||
server serves the same bad pair again.</p>
|
||||
<p>The server caches the result for 30 seconds and keeps every probe shallow: a vault answers one
|
||||
lookup that should miss, and no probe allocates anything. A failing probe's <code>detail</code> has the
|
||||
vault's password or token masked. This is a panel, not a liveness probe - do not poll it faster
|
||||
|
||||
@@ -1996,6 +1996,17 @@
|
||||
</span>
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#post-apisessionsession_idkeysbad" class="md-nav__link">
|
||||
<span class="md-ellipsis">
|
||||
|
||||
POST /api/session/{session_id}/keys/bad
|
||||
|
||||
</span>
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
@@ -2839,6 +2850,17 @@
|
||||
</span>
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#post-apisessionsession_idkeysbad" class="md-nav__link">
|
||||
<span class="md-ellipsis">
|
||||
|
||||
POST /api/session/{session_id}/keys/bad
|
||||
|
||||
</span>
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
@@ -2993,7 +3015,7 @@
|
||||
</tbody>
|
||||
</table>
|
||||
<h3 id="get-apiservices"><code>GET /api/services</code><a class="headerlink" href="#get-apiservices" title="Permanent link">¶</a></h3>
|
||||
<p>Show the streaming services available on this server, filtered by your allowlist. Each entry gives the service's tag, matching rules, capability flags, and its CLI parameters (useful when you make a UI that accepts service-specific options). <code>load_errors</code> lists the services the server skipped because they failed to import, at startup or after a service repository refresh; the server also writes each one to its log. An entry marked <code>pending_update</code> has newer code staged: it keeps its current code until its running or queued jobs finish.</p>
|
||||
<p>Show the streaming services available on this server, filtered by your allowlist. Each entry gives the service's tag, matching rules, capability flags, and its CLI parameters (useful when you make a UI that accepts service-specific options). <code>load_errors</code> lists the services the server skipped because they failed to import, at startup or after a service repository refresh; the server also writes each one to its log. An entry marked <code>pending_update</code> has newer code staged: it keeps its current code until its running or queued jobs and its live remote sessions finish.</p>
|
||||
<div class="tabbed-set tabbed-alternate" data-tabs="2:2"><input checked="checked" id="__tabbed_2_1" name="__tabbed_2" type="radio" /><input id="__tabbed_2_2" name="__tabbed_2" type="radio" /><div class="tabbed-labels"><label for="__tabbed_2_1">Request</label><label for="__tabbed_2_2">Response <code>200</code></label></div>
|
||||
<div class="tabbed-content">
|
||||
<div class="tabbed-block">
|
||||
@@ -3007,30 +3029,31 @@
|
||||
</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">"tag"</span><span class="p">:</span><span class="w"> </span><span class="s2">"EXAMPLE"</span><span class="p">,</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">"aliases"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"EX"</span><span class="p">],</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">"geofence"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"US"</span><span class="p">],</span>
|
||||
</span><span id="__span-3-7"><a id="__codelineno-3-7" name="__codelineno-3-7" href="#__codelineno-3-7"></a><span class="w"> </span><span class="nt">"title_regex"</span><span class="p">:</span><span class="w"> </span><span class="s2">"^https?://example\\.com/.+"</span><span class="p">,</span>
|
||||
</span><span id="__span-3-8"><a id="__codelineno-3-8" name="__codelineno-3-8" href="#__codelineno-3-8"></a><span class="w"> </span><span class="nt">"url"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://example.com"</span><span class="p">,</span>
|
||||
</span><span id="__span-3-9"><a id="__codelineno-3-9" name="__codelineno-3-9" href="#__codelineno-3-9"></a><span class="w"> </span><span class="nt">"help"</span><span class="p">:</span><span class="w"> </span><span class="s2">"EXAMPLE\nAuthorization: Cookies\nSecurity: FHD@L3"</span><span class="p">,</span>
|
||||
</span><span id="__span-3-10"><a id="__codelineno-3-10" name="__codelineno-3-10" href="#__codelineno-3-10"></a><span class="w"> </span><span class="nt">"cli_params"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span>
|
||||
</span><span id="__span-3-11"><a id="__codelineno-3-11" name="__codelineno-3-11" href="#__codelineno-3-11"></a><span class="w"> </span><span class="p">{</span><span class="nt">"name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"title"</span><span class="p">,</span><span class="w"> </span><span class="nt">"kind"</span><span class="p">:</span><span class="w"> </span><span class="s2">"argument"</span><span class="p">,</span><span class="w"> </span><span class="nt">"required"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">},</span>
|
||||
</span><span id="__span-3-12"><a id="__codelineno-3-12" name="__codelineno-3-12" href="#__codelineno-3-12"></a><span class="w"> </span><span class="p">{</span>
|
||||
</span><span id="__span-3-13"><a id="__codelineno-3-13" name="__codelineno-3-13" href="#__codelineno-3-13"></a><span class="w"> </span><span class="nt">"name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"movie"</span><span class="p">,</span>
|
||||
</span><span id="__span-3-14"><a id="__codelineno-3-14" name="__codelineno-3-14" href="#__codelineno-3-14"></a><span class="w"> </span><span class="nt">"kind"</span><span class="p">:</span><span class="w"> </span><span class="s2">"option"</span><span class="p">,</span>
|
||||
</span><span id="__span-3-15"><a id="__codelineno-3-15" name="__codelineno-3-15" href="#__codelineno-3-15"></a><span class="w"> </span><span class="nt">"opts"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"-m"</span><span class="p">,</span><span class="w"> </span><span class="s2">"--movie"</span><span class="p">],</span>
|
||||
</span><span id="__span-3-16"><a id="__codelineno-3-16" name="__codelineno-3-16" href="#__codelineno-3-16"></a><span class="w"> </span><span class="nt">"is_flag"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||||
</span><span id="__span-3-17"><a id="__codelineno-3-17" name="__codelineno-3-17" href="#__codelineno-3-17"></a><span class="w"> </span><span class="nt">"default"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>
|
||||
</span><span id="__span-3-18"><a id="__codelineno-3-18" name="__codelineno-3-18" href="#__codelineno-3-18"></a><span class="w"> </span><span class="nt">"help"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Title is a movie."</span><span class="p">,</span>
|
||||
</span><span id="__span-3-19"><a id="__codelineno-3-19" name="__codelineno-3-19" href="#__codelineno-3-19"></a><span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"boolean"</span><span class="p">,</span>
|
||||
</span><span id="__span-3-20"><a id="__codelineno-3-20" name="__codelineno-3-20" href="#__codelineno-3-20"></a><span class="w"> </span><span class="nt">"multiple"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span>
|
||||
</span><span id="__span-3-21"><a id="__codelineno-3-21" name="__codelineno-3-21" href="#__codelineno-3-21"></a><span class="w"> </span><span class="p">}</span>
|
||||
</span><span id="__span-3-22"><a id="__codelineno-3-22" name="__codelineno-3-22" href="#__codelineno-3-22"></a><span class="w"> </span><span class="p">],</span>
|
||||
</span><span id="__span-3-23"><a id="__codelineno-3-23" name="__codelineno-3-23" href="#__codelineno-3-23"></a><span class="w"> </span><span class="nt">"needs_auth"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||||
</span><span id="__span-3-24"><a id="__codelineno-3-24" name="__codelineno-3-24" href="#__codelineno-3-24"></a><span class="w"> </span><span class="nt">"has_search"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||||
</span><span id="__span-3-25"><a id="__codelineno-3-25" name="__codelineno-3-25" href="#__codelineno-3-25"></a><span class="w"> </span><span class="nt">"has_drm"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||||
</span><span id="__span-3-26"><a id="__codelineno-3-26" name="__codelineno-3-26" href="#__codelineno-3-26"></a><span class="w"> </span><span class="nt">"auth_methods"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"cookies"</span><span class="p">]</span>
|
||||
</span><span id="__span-3-27"><a id="__codelineno-3-27" name="__codelineno-3-27" href="#__codelineno-3-27"></a><span class="w"> </span><span class="p">}</span>
|
||||
</span><span id="__span-3-28"><a id="__codelineno-3-28" name="__codelineno-3-28" href="#__codelineno-3-28"></a><span class="w"> </span><span class="p">],</span>
|
||||
</span><span id="__span-3-29"><a id="__codelineno-3-29" name="__codelineno-3-29" href="#__codelineno-3-29"></a><span class="w"> </span><span class="nt">"load_errors"</span><span class="p">:</span><span class="w"> </span><span class="p">[]</span>
|
||||
</span><span id="__span-3-30"><a id="__codelineno-3-30" name="__codelineno-3-30" href="#__codelineno-3-30"></a><span class="p">}</span>
|
||||
</span><span id="__span-3-7"><a id="__codelineno-3-7" name="__codelineno-3-7" href="#__codelineno-3-7"></a><span class="w"> </span><span class="nt">"geoblock"</span><span class="p">:</span><span class="w"> </span><span class="p">[],</span>
|
||||
</span><span id="__span-3-8"><a id="__codelineno-3-8" name="__codelineno-3-8" href="#__codelineno-3-8"></a><span class="w"> </span><span class="nt">"title_regex"</span><span class="p">:</span><span class="w"> </span><span class="s2">"^https?://example\\.com/.+"</span><span class="p">,</span>
|
||||
</span><span id="__span-3-9"><a id="__codelineno-3-9" name="__codelineno-3-9" href="#__codelineno-3-9"></a><span class="w"> </span><span class="nt">"url"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://example.com"</span><span class="p">,</span>
|
||||
</span><span id="__span-3-10"><a id="__codelineno-3-10" name="__codelineno-3-10" href="#__codelineno-3-10"></a><span class="w"> </span><span class="nt">"help"</span><span class="p">:</span><span class="w"> </span><span class="s2">"EXAMPLE\nAuthorization: Cookies\nSecurity: FHD@L3"</span><span class="p">,</span>
|
||||
</span><span id="__span-3-11"><a id="__codelineno-3-11" name="__codelineno-3-11" href="#__codelineno-3-11"></a><span class="w"> </span><span class="nt">"cli_params"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span>
|
||||
</span><span id="__span-3-12"><a id="__codelineno-3-12" name="__codelineno-3-12" href="#__codelineno-3-12"></a><span class="w"> </span><span class="p">{</span><span class="nt">"name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"title"</span><span class="p">,</span><span class="w"> </span><span class="nt">"kind"</span><span class="p">:</span><span class="w"> </span><span class="s2">"argument"</span><span class="p">,</span><span class="w"> </span><span class="nt">"required"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">},</span>
|
||||
</span><span id="__span-3-13"><a id="__codelineno-3-13" name="__codelineno-3-13" href="#__codelineno-3-13"></a><span class="w"> </span><span class="p">{</span>
|
||||
</span><span id="__span-3-14"><a id="__codelineno-3-14" name="__codelineno-3-14" href="#__codelineno-3-14"></a><span class="w"> </span><span class="nt">"name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"movie"</span><span class="p">,</span>
|
||||
</span><span id="__span-3-15"><a id="__codelineno-3-15" name="__codelineno-3-15" href="#__codelineno-3-15"></a><span class="w"> </span><span class="nt">"kind"</span><span class="p">:</span><span class="w"> </span><span class="s2">"option"</span><span class="p">,</span>
|
||||
</span><span id="__span-3-16"><a id="__codelineno-3-16" name="__codelineno-3-16" href="#__codelineno-3-16"></a><span class="w"> </span><span class="nt">"opts"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"-m"</span><span class="p">,</span><span class="w"> </span><span class="s2">"--movie"</span><span class="p">],</span>
|
||||
</span><span id="__span-3-17"><a id="__codelineno-3-17" name="__codelineno-3-17" href="#__codelineno-3-17"></a><span class="w"> </span><span class="nt">"is_flag"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||||
</span><span id="__span-3-18"><a id="__codelineno-3-18" name="__codelineno-3-18" href="#__codelineno-3-18"></a><span class="w"> </span><span class="nt">"default"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="p">,</span>
|
||||
</span><span id="__span-3-19"><a id="__codelineno-3-19" name="__codelineno-3-19" href="#__codelineno-3-19"></a><span class="w"> </span><span class="nt">"help"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Title is a movie."</span><span class="p">,</span>
|
||||
</span><span id="__span-3-20"><a id="__codelineno-3-20" name="__codelineno-3-20" href="#__codelineno-3-20"></a><span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"boolean"</span><span class="p">,</span>
|
||||
</span><span id="__span-3-21"><a id="__codelineno-3-21" name="__codelineno-3-21" href="#__codelineno-3-21"></a><span class="w"> </span><span class="nt">"multiple"</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span>
|
||||
</span><span id="__span-3-22"><a id="__codelineno-3-22" name="__codelineno-3-22" href="#__codelineno-3-22"></a><span class="w"> </span><span class="p">}</span>
|
||||
</span><span id="__span-3-23"><a id="__codelineno-3-23" name="__codelineno-3-23" href="#__codelineno-3-23"></a><span class="w"> </span><span class="p">],</span>
|
||||
</span><span id="__span-3-24"><a id="__codelineno-3-24" name="__codelineno-3-24" href="#__codelineno-3-24"></a><span class="w"> </span><span class="nt">"needs_auth"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||||
</span><span id="__span-3-25"><a id="__codelineno-3-25" name="__codelineno-3-25" href="#__codelineno-3-25"></a><span class="w"> </span><span class="nt">"has_search"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||||
</span><span id="__span-3-26"><a id="__codelineno-3-26" name="__codelineno-3-26" href="#__codelineno-3-26"></a><span class="w"> </span><span class="nt">"has_drm"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||||
</span><span id="__span-3-27"><a id="__codelineno-3-27" name="__codelineno-3-27" href="#__codelineno-3-27"></a><span class="w"> </span><span class="nt">"auth_methods"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"cookies"</span><span class="p">]</span>
|
||||
</span><span id="__span-3-28"><a id="__codelineno-3-28" name="__codelineno-3-28" href="#__codelineno-3-28"></a><span class="w"> </span><span class="p">}</span>
|
||||
</span><span id="__span-3-29"><a id="__codelineno-3-29" name="__codelineno-3-29" href="#__codelineno-3-29"></a><span class="w"> </span><span class="p">],</span>
|
||||
</span><span id="__span-3-30"><a id="__codelineno-3-30" name="__codelineno-3-30" href="#__codelineno-3-30"></a><span class="w"> </span><span class="nt">"load_errors"</span><span class="p">:</span><span class="w"> </span><span class="p">[]</span>
|
||||
</span><span id="__span-3-31"><a id="__codelineno-3-31" name="__codelineno-3-31" href="#__codelineno-3-31"></a><span class="p">}</span>
|
||||
</span></code></pre></div>
|
||||
</div>
|
||||
</div>
|
||||
@@ -3057,6 +3080,10 @@
|
||||
<td>Region codes the service is geofenced to (may be empty).</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>geoblock</code></td>
|
||||
<td>Region codes where the service refuses to work (may be empty).</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>title_regex</code></td>
|
||||
<td>URL/ID pattern the service matches, as a string or list of strings (or <code>null</code>).</td>
|
||||
</tr>
|
||||
@@ -3774,10 +3801,10 @@ ignore it safely. See <a href="../../creating-a-service/#split-episodes">Split e
|
||||
<td>Force CDM-only (<code>true</code>) or vault-only (<code>false</code>) key retrieval.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>proxy</code> / <code>no_proxy</code> / <code>no_proxy_download</code></td>
|
||||
<td>string / bool / bool</td>
|
||||
<td><code>null</code> / <code>false</code> / <code>false</code></td>
|
||||
<td>Proxy controls. <code>proxy</code> must be a full proxy URI unless the API key has <code>server_proxy</code>.</td>
|
||||
<td><code>proxy</code> / <code>no_proxy</code> / <code>no_proxy_download</code> / <code>proxy_download</code></td>
|
||||
<td>string / bool / bool / string</td>
|
||||
<td><code>null</code> / <code>false</code> / <code>false</code> / <code>null</code></td>
|
||||
<td>Proxy controls. <code>proxy</code> and <code>proxy_download</code> must be full proxy URIs unless the API key has <code>server_proxy</code>.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>no_folder</code> / <code>no_source</code> / <code>no_mux</code></td>
|
||||
@@ -4529,7 +4556,7 @@ an HTTP caller would be remote code execution. You configure post-scripts only i
|
||||
<p class="admonition-title">Developer feature</p>
|
||||
<p>The <code>/api/session/*</code> endpoints power unshackle's <strong>remote download</strong> mode. A thin local client authenticates once against a remote server, then fetches titles, tracks, and segments, and proxies DRM licensing back through it. The server mounts these endpoints in <code>--remote-only</code> mode, and they are what the built-in <code>RemoteService</code> client drives. Most end users never call them directly.</p>
|
||||
</div>
|
||||
<p>The server holds remote sessions in memory. They expire after <code>serve.session_ttl</code> (default 300s), except while awaiting interactive authentication input, which uses a 600s window. A remote session binds to the IP that made it, so the server rejects a request from a different IP with <code>403 FORBIDDEN</code>.</p>
|
||||
<p>The server holds remote sessions in memory. They expire after <code>serve.session_ttl</code> (default 300s) without a request, except while awaiting interactive authentication input, which uses a 600s window. A remote session binds to the IP that made it, so the server rejects a request from a different IP with <code>403 FORBIDDEN</code>.</p>
|
||||
<h3 id="remote-session-lifecycle-overview">Remote session lifecycle overview<a class="headerlink" href="#remote-session-lifecycle-overview" title="Permanent link">¶</a></h3>
|
||||
<div class="language-text highlight"><pre><span></span><code><span id="__span-28-1"><a id="__codelineno-28-1" name="__codelineno-28-1" href="#__codelineno-28-1"></a>POST /api/session/create → returns session_id, status "authenticating"
|
||||
</span><span id="__span-28-2"><a id="__codelineno-28-2" name="__codelineno-28-2" href="#__codelineno-28-2"></a>GET /api/session/{id}/prompt → poll until authenticated (submit answers via POST)
|
||||
@@ -4538,7 +4565,8 @@ an HTTP caller would be remote code execution. You configure post-scripts only i
|
||||
</span><span id="__span-28-5"><a id="__codelineno-28-5" name="__codelineno-28-5" href="#__codelineno-28-5"></a>POST /api/session/{id}/segments → resolve segment URLs / DRM / headers per track
|
||||
</span><span id="__span-28-6"><a id="__codelineno-28-6" name="__codelineno-28-6" href="#__codelineno-28-6"></a>POST /api/session/{id}/segment_filter → HLS segments the service drops (ads, bumpers)
|
||||
</span><span id="__span-28-7"><a id="__codelineno-28-7" name="__codelineno-28-7" href="#__codelineno-28-7"></a>POST /api/session/{id}/license → proxy or server-CDM DRM licensing
|
||||
</span><span id="__span-28-8"><a id="__codelineno-28-8" name="__codelineno-28-8" href="#__codelineno-28-8"></a>DELETE /api/session/{id} → tear down, harvest updated cache
|
||||
</span><span id="__span-28-8"><a id="__codelineno-28-8" name="__codelineno-28-8" href="#__codelineno-28-8"></a>POST /api/session/{id}/keys/bad → report a server-vault content key that did not decrypt
|
||||
</span><span id="__span-28-9"><a id="__codelineno-28-9" name="__codelineno-28-9" href="#__codelineno-28-9"></a>DELETE /api/session/{id} → tear down, harvest updated cache
|
||||
</span></code></pre></div>
|
||||
<h3 id="post-apisessioncreate"><code>POST /api/session/create</code><a class="headerlink" href="#post-apisessioncreate" title="Permanent link">¶</a></h3>
|
||||
<p>Make a remote session for a service and title. Authentication runs asynchronously in the background. This call returns immediately with <code>status: "authenticating"</code>, and you then poll the prompt endpoint. The body accepts <code>service</code> and <code>title_id</code> (both required). It also accepts a broad set of optional keys, because the body allows <code>additionalProperties</code>. These are <code>credentials</code> (<code>{username, password, extra?}</code>), <code>cookies</code> (base64 of zlib-compressed Netscape cookie file), <code>proxy</code>, <code>no_proxy</code>, <code>profile</code>, <code>cache</code> (map of forwarded cache files), <code>client_region</code>, <code>proxy_region</code>, <code>cdm_type</code>, <code>range_</code>, <code>vcodec</code>, <code>quality</code>, <code>best_available</code>, <code>client</code>, and any service CLI options. <code>proxy_region</code> is the country code the client resolved <code>proxy</code> from; the server matches it against its own accounts. <code>client</code> is a freeform object the dashboard shows as sent (the CLI puts <code>version</code>, <code>code_hash</code>, <code>platform</code> and a redacted <code>argv</code> in it); the server ignores it above 4096 bytes of JSON.</p>
|
||||
@@ -4557,7 +4585,7 @@ an HTTP caller would be remote code execution. You configure post-scripts only i
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<p><code>server_account</code> is <code>true</code> when the server authenticated with one of its own accounts (<code>serve.server_accounts</code>). Otherwise the server uses only what the client sent, and never falls back to its own credentials. Only a client that sent its own cookies or credentials gets cookies, auth headers, and the remote session cache back. For any other remote session (a server account, or an anonymous login through the server's proxy) the tracks and segments responses carry no cookies and no auth headers. The server also drops secret-looking keys from track data, and the cache stays on the server. A server-account service also refuses a client proxy URI, because the server's login would pass through it.</p>
|
||||
<p><code>server_account</code> is <code>true</code> when the server authenticated with one of its own accounts (<code>serve.server_accounts</code>). Otherwise the server uses only what the client sent, and never falls back to its own credentials. Only a client that sent its own cookies, credentials, or cache files gets cookies, auth headers, and the remote session cache back. A client that answered a login prompt (a device code or an OTP) gets them too. This applies only when the login then succeeds and the remote session does not use a server account. For any other remote session (a server account, or an anonymous login through the server's proxy) the tracks and segments responses carry no cookies and no auth headers. The server also drops secret-looking keys from track data, and the cache stays on the server. A server-account service also refuses a client proxy URI, because the server's login would pass through it.</p>
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
@@ -4870,11 +4898,11 @@ an HTTP caller would be remote code execution. You configure post-scripts only i
|
||||
<div class="tabbed-set tabbed-alternate" data-tabs="28:2"><input checked="checked" id="__tabbed_28_1" name="__tabbed_28" type="radio" /><input id="__tabbed_28_2" name="__tabbed_28" type="radio" /><div class="tabbed-labels"><label for="__tabbed_28_1">Single: Response <code>200</code></label><label for="__tabbed_28_2">Batch: Response <code>200</code></label></div>
|
||||
<div class="tabbed-content">
|
||||
<div class="tabbed-block">
|
||||
<div class="language-json highlight"><pre><span></span><code><span id="__span-42-1"><a id="__codelineno-42-1" name="__codelineno-42-1" href="#__codelineno-42-1"></a><span class="p">{</span><span class="w"> </span><span class="nt">"keys"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"<kid_hex>"</span><span class="p">:</span><span class="w"> </span><span class="s2">"<key_hex>"</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="p">}</span>
|
||||
<div class="language-json highlight"><pre><span></span><code><span id="__span-42-1"><a id="__codelineno-42-1" name="__codelineno-42-1" href="#__codelineno-42-1"></a><span class="p">{</span><span class="w"> </span><span class="nt">"keys"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"<kid_hex>"</span><span class="p">:</span><span class="w"> </span><span class="s2">"<key_hex>"</span><span class="w"> </span><span class="p">},</span><span class="w"> </span><span class="nt">"vault_keys"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"<kid_hex>"</span><span class="p">]</span><span class="w"> </span><span class="p">}</span>
|
||||
</span></code></pre></div>
|
||||
</div>
|
||||
<div class="tabbed-block">
|
||||
<div class="language-json highlight"><pre><span></span><code><span id="__span-43-1"><a id="__codelineno-43-1" name="__codelineno-43-1" href="#__codelineno-43-1"></a><span class="p">{</span><span class="w"> </span><span class="nt">"keys"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"v-1"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"<kid_hex>"</span><span class="p">:</span><span class="w"> </span><span class="s2">"<key_hex>"</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="p">},</span><span class="w"> </span><span class="nt">"drm_type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"widevine"</span><span class="w"> </span><span class="p">}</span>
|
||||
<div class="language-json highlight"><pre><span></span><code><span id="__span-43-1"><a id="__codelineno-43-1" name="__codelineno-43-1" href="#__codelineno-43-1"></a><span class="p">{</span><span class="w"> </span><span class="nt">"keys"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"v-1"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"<kid_hex>"</span><span class="p">:</span><span class="w"> </span><span class="s2">"<key_hex>"</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="p">},</span><span class="w"> </span><span class="nt">"vault_keys"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"<kid_hex>"</span><span class="p">],</span><span class="w"> </span><span class="nt">"drm_type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"widevine"</span><span class="w"> </span><span class="p">}</span>
|
||||
</span></code></pre></div>
|
||||
</div>
|
||||
</div>
|
||||
@@ -4907,6 +4935,10 @@ an HTTP caller would be remote code execution. You configure post-scripts only i
|
||||
<td><code>mode</code></td>
|
||||
<td><code>proxy</code> (default) or <code>server_cdm</code>.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>vault_keys</code> (response)</td>
|
||||
<td>KIDs whose content key came from a server vault, not the CDM. The client proves such a content key with a decode before it trusts it; the field is absent when every content key came from the CDM.</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<table>
|
||||
@@ -4950,19 +4982,49 @@ an HTTP caller would be remote code execution. You configure post-scripts only i
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<h3 id="post-apisessionsession_idkeysbad"><code>POST /api/session/{session_id}/keys/bad</code><a class="headerlink" href="#post-apisessionsession_idkeysbad" title="Permanent link">¶</a></h3>
|
||||
<p>Report a content key from <code>vault_keys</code> that did not decrypt the track. The server flags the pair in its local vaults and reports it to the vault that served it, and the next licence for that KID reaches the CDM. The client never learns the server vault names.</p>
|
||||
<div class="language-json highlight"><pre><span></span><code><span id="__span-44-1"><a id="__codelineno-44-1" name="__codelineno-44-1" href="#__codelineno-44-1"></a><span class="p">{</span><span class="w"> </span><span class="nt">"kid"</span><span class="p">:</span><span class="w"> </span><span class="s2">"<kid_hex>"</span><span class="p">,</span><span class="w"> </span><span class="nt">"key"</span><span class="p">:</span><span class="w"> </span><span class="s2">"<key_hex>"</span><span class="w"> </span><span class="p">}</span>
|
||||
</span></code></pre></div>
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Status</th>
|
||||
<th>Error code</th>
|
||||
<th>Meaning</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code>200</code></td>
|
||||
<td>-</td>
|
||||
<td>The pair is flagged.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>400</code></td>
|
||||
<td><code>INVALID_INPUT</code></td>
|
||||
<td>This remote session was not served that pair.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>404</code></td>
|
||||
<td><code>SESSION_NOT_FOUND</code></td>
|
||||
<td>Unknown remote session.</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<h3 id="get-apisessionsession_id"><code>GET /api/session/{session_id}</code><a class="headerlink" href="#get-apisessionsession_id" title="Permanent link">¶</a></h3>
|
||||
<p>Return remote session metadata and validity.</p>
|
||||
<div class="tabbed-set tabbed-alternate" data-tabs="29:1"><input checked="checked" id="__tabbed_29_1" name="__tabbed_29" type="radio" /><div class="tabbed-labels"><label for="__tabbed_29_1">Response <code>200</code></label></div>
|
||||
<div class="tabbed-content">
|
||||
<div class="tabbed-block">
|
||||
<div class="language-json highlight"><pre><span></span><code><span id="__span-44-1"><a id="__codelineno-44-1" name="__codelineno-44-1" href="#__codelineno-44-1"></a><span class="p">{</span>
|
||||
</span><span id="__span-44-2"><a id="__codelineno-44-2" name="__codelineno-44-2" href="#__codelineno-44-2"></a><span class="w"> </span><span class="nt">"session_id"</span><span class="p">:</span><span class="w"> </span><span class="s2">"d4e5f6a7-..."</span><span class="p">,</span>
|
||||
</span><span id="__span-44-3"><a id="__codelineno-44-3" name="__codelineno-44-3" href="#__codelineno-44-3"></a><span class="w"> </span><span class="nt">"service"</span><span class="p">:</span><span class="w"> </span><span class="s2">"EXAMPLE"</span><span class="p">,</span>
|
||||
</span><span id="__span-44-4"><a id="__codelineno-44-4" name="__codelineno-44-4" href="#__codelineno-44-4"></a><span class="w"> </span><span class="nt">"valid"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||||
</span><span id="__span-44-5"><a id="__codelineno-44-5" name="__codelineno-44-5" href="#__codelineno-44-5"></a><span class="w"> </span><span class="nt">"expires_in"</span><span class="p">:</span><span class="w"> </span><span class="mi">300</span><span class="p">,</span>
|
||||
</span><span id="__span-44-6"><a id="__codelineno-44-6" name="__codelineno-44-6" href="#__codelineno-44-6"></a><span class="w"> </span><span class="nt">"track_count"</span><span class="p">:</span><span class="w"> </span><span class="mi">4</span><span class="p">,</span>
|
||||
</span><span id="__span-44-7"><a id="__codelineno-44-7" name="__codelineno-44-7" href="#__codelineno-44-7"></a><span class="w"> </span><span class="nt">"title_count"</span><span class="p">:</span><span class="w"> </span><span class="mi">10</span>
|
||||
</span><span id="__span-44-8"><a id="__codelineno-44-8" name="__codelineno-44-8" href="#__codelineno-44-8"></a><span class="p">}</span>
|
||||
<div class="language-json highlight"><pre><span></span><code><span id="__span-45-1"><a id="__codelineno-45-1" name="__codelineno-45-1" href="#__codelineno-45-1"></a><span class="p">{</span>
|
||||
</span><span id="__span-45-2"><a id="__codelineno-45-2" name="__codelineno-45-2" href="#__codelineno-45-2"></a><span class="w"> </span><span class="nt">"session_id"</span><span class="p">:</span><span class="w"> </span><span class="s2">"d4e5f6a7-..."</span><span class="p">,</span>
|
||||
</span><span id="__span-45-3"><a id="__codelineno-45-3" name="__codelineno-45-3" href="#__codelineno-45-3"></a><span class="w"> </span><span class="nt">"service"</span><span class="p">:</span><span class="w"> </span><span class="s2">"EXAMPLE"</span><span class="p">,</span>
|
||||
</span><span id="__span-45-4"><a id="__codelineno-45-4" name="__codelineno-45-4" href="#__codelineno-45-4"></a><span class="w"> </span><span class="nt">"valid"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||||
</span><span id="__span-45-5"><a id="__codelineno-45-5" name="__codelineno-45-5" href="#__codelineno-45-5"></a><span class="w"> </span><span class="nt">"expires_in"</span><span class="p">:</span><span class="w"> </span><span class="mi">300</span><span class="p">,</span>
|
||||
</span><span id="__span-45-6"><a id="__codelineno-45-6" name="__codelineno-45-6" href="#__codelineno-45-6"></a><span class="w"> </span><span class="nt">"track_count"</span><span class="p">:</span><span class="w"> </span><span class="mi">4</span><span class="p">,</span>
|
||||
</span><span id="__span-45-7"><a id="__codelineno-45-7" name="__codelineno-45-7" href="#__codelineno-45-7"></a><span class="w"> </span><span class="nt">"title_count"</span><span class="p">:</span><span class="w"> </span><span class="mi">10</span>
|
||||
</span><span id="__span-45-8"><a id="__codelineno-45-8" name="__codelineno-45-8" href="#__codelineno-45-8"></a><span class="p">}</span>
|
||||
</span></code></pre></div>
|
||||
</div>
|
||||
</div>
|
||||
@@ -4973,27 +5035,27 @@ an HTTP caller would be remote code execution. You configure post-scripts only i
|
||||
<div class="tabbed-set tabbed-alternate" data-tabs="30:1"><input checked="checked" id="__tabbed_30_1" name="__tabbed_30" type="radio" /><div class="tabbed-labels"><label for="__tabbed_30_1">Response <code>200</code></label></div>
|
||||
<div class="tabbed-content">
|
||||
<div class="tabbed-block">
|
||||
<div class="language-json highlight"><pre><span></span><code><span id="__span-45-1"><a id="__codelineno-45-1" name="__codelineno-45-1" href="#__codelineno-45-1"></a><span class="p">{</span>
|
||||
</span><span id="__span-45-2"><a id="__codelineno-45-2" name="__codelineno-45-2" href="#__codelineno-45-2"></a><span class="w"> </span><span class="nt">"status"</span><span class="p">:</span><span class="w"> </span><span class="s2">"ok"</span><span class="p">,</span>
|
||||
</span><span id="__span-45-3"><a id="__codelineno-45-3" name="__codelineno-45-3" href="#__codelineno-45-3"></a><span class="w"> </span><span class="nt">"cache"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"tokens.json"</span><span class="p">:</span><span class="w"> </span><span class="s2">"<base64 zlib bytes>"</span><span class="w"> </span><span class="p">}</span>
|
||||
</span><span id="__span-45-4"><a id="__codelineno-45-4" name="__codelineno-45-4" href="#__codelineno-45-4"></a><span class="p">}</span>
|
||||
<div class="language-json highlight"><pre><span></span><code><span id="__span-46-1"><a id="__codelineno-46-1" name="__codelineno-46-1" href="#__codelineno-46-1"></a><span class="p">{</span>
|
||||
</span><span id="__span-46-2"><a id="__codelineno-46-2" name="__codelineno-46-2" href="#__codelineno-46-2"></a><span class="w"> </span><span class="nt">"status"</span><span class="p">:</span><span class="w"> </span><span class="s2">"ok"</span><span class="p">,</span>
|
||||
</span><span id="__span-46-3"><a id="__codelineno-46-3" name="__codelineno-46-3" href="#__codelineno-46-3"></a><span class="w"> </span><span class="nt">"cache"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"tokens.json"</span><span class="p">:</span><span class="w"> </span><span class="s2">"<base64 zlib bytes>"</span><span class="w"> </span><span class="p">}</span>
|
||||
</span><span id="__span-46-4"><a id="__codelineno-46-4" name="__codelineno-46-4" href="#__codelineno-46-4"></a><span class="p">}</span>
|
||||
</span></code></pre></div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<p>The <code>cache</code> field is present only if the remote session produced cache files. <code>404 SESSION_NOT_FOUND</code> if the remote session does not exist.</p>
|
||||
<p>The <code>cache</code> field is present only if the remote session produced cache files and the login belongs to the client. <code>404 SESSION_NOT_FOUND</code> if the remote session does not exist.</p>
|
||||
<hr />
|
||||
<h2 id="error-responses">Error responses<a class="headerlink" href="#error-responses" title="Permanent link">¶</a></h2>
|
||||
<p>The server serialises every structured error raised inside a handler to the same JSON envelope:</p>
|
||||
<div class="language-json highlight"><pre><span></span><code><span id="__span-46-1"><a id="__codelineno-46-1" name="__codelineno-46-1" href="#__codelineno-46-1"></a><span class="p">{</span>
|
||||
</span><span id="__span-46-2"><a id="__codelineno-46-2" name="__codelineno-46-2" href="#__codelineno-46-2"></a><span class="w"> </span><span class="nt">"status"</span><span class="p">:</span><span class="w"> </span><span class="s2">"error"</span><span class="p">,</span>
|
||||
</span><span id="__span-46-3"><a id="__codelineno-46-3" name="__codelineno-46-3" href="#__codelineno-46-3"></a><span class="w"> </span><span class="nt">"error_code"</span><span class="p">:</span><span class="w"> </span><span class="s2">"INVALID_PARAMETERS"</span><span class="p">,</span>
|
||||
</span><span id="__span-46-4"><a id="__codelineno-46-4" name="__codelineno-46-4" href="#__codelineno-46-4"></a><span class="w"> </span><span class="nt">"message"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Invalid video codec: XYZ"</span><span class="p">,</span>
|
||||
</span><span id="__span-46-5"><a id="__codelineno-46-5" name="__codelineno-46-5" href="#__codelineno-46-5"></a><span class="w"> </span><span class="nt">"timestamp"</span><span class="p">:</span><span class="w"> </span><span class="s2">"2026-07-03T12:00:00+00:00"</span><span class="p">,</span>
|
||||
</span><span id="__span-46-6"><a id="__codelineno-46-6" name="__codelineno-46-6" href="#__codelineno-46-6"></a><span class="w"> </span><span class="nt">"details"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"field"</span><span class="p">:</span><span class="w"> </span><span class="s2">"vcodec"</span><span class="w"> </span><span class="p">},</span>
|
||||
</span><span id="__span-46-7"><a id="__codelineno-46-7" name="__codelineno-46-7" href="#__codelineno-46-7"></a><span class="w"> </span><span class="nt">"retryable"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||||
</span><span id="__span-46-8"><a id="__codelineno-46-8" name="__codelineno-46-8" href="#__codelineno-46-8"></a><span class="w"> </span><span class="nt">"debug_info"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"exception_type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"APIError"</span><span class="p">,</span><span class="w"> </span><span class="nt">"traceback"</span><span class="p">:</span><span class="w"> </span><span class="s2">"..."</span><span class="w"> </span><span class="p">}</span>
|
||||
</span><span id="__span-46-9"><a id="__codelineno-46-9" name="__codelineno-46-9" href="#__codelineno-46-9"></a><span class="p">}</span>
|
||||
<div class="language-json highlight"><pre><span></span><code><span id="__span-47-1"><a id="__codelineno-47-1" name="__codelineno-47-1" href="#__codelineno-47-1"></a><span class="p">{</span>
|
||||
</span><span id="__span-47-2"><a id="__codelineno-47-2" name="__codelineno-47-2" href="#__codelineno-47-2"></a><span class="w"> </span><span class="nt">"status"</span><span class="p">:</span><span class="w"> </span><span class="s2">"error"</span><span class="p">,</span>
|
||||
</span><span id="__span-47-3"><a id="__codelineno-47-3" name="__codelineno-47-3" href="#__codelineno-47-3"></a><span class="w"> </span><span class="nt">"error_code"</span><span class="p">:</span><span class="w"> </span><span class="s2">"INVALID_PARAMETERS"</span><span class="p">,</span>
|
||||
</span><span id="__span-47-4"><a id="__codelineno-47-4" name="__codelineno-47-4" href="#__codelineno-47-4"></a><span class="w"> </span><span class="nt">"message"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Invalid video codec: XYZ"</span><span class="p">,</span>
|
||||
</span><span id="__span-47-5"><a id="__codelineno-47-5" name="__codelineno-47-5" href="#__codelineno-47-5"></a><span class="w"> </span><span class="nt">"timestamp"</span><span class="p">:</span><span class="w"> </span><span class="s2">"2026-07-03T12:00:00+00:00"</span><span class="p">,</span>
|
||||
</span><span id="__span-47-6"><a id="__codelineno-47-6" name="__codelineno-47-6" href="#__codelineno-47-6"></a><span class="w"> </span><span class="nt">"details"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"field"</span><span class="p">:</span><span class="w"> </span><span class="s2">"vcodec"</span><span class="w"> </span><span class="p">},</span>
|
||||
</span><span id="__span-47-7"><a id="__codelineno-47-7" name="__codelineno-47-7" href="#__codelineno-47-7"></a><span class="w"> </span><span class="nt">"retryable"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||||
</span><span id="__span-47-8"><a id="__codelineno-47-8" name="__codelineno-47-8" href="#__codelineno-47-8"></a><span class="w"> </span><span class="nt">"debug_info"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"exception_type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"APIError"</span><span class="p">,</span><span class="w"> </span><span class="nt">"traceback"</span><span class="p">:</span><span class="w"> </span><span class="s2">"..."</span><span class="w"> </span><span class="p">}</span>
|
||||
</span><span id="__span-47-9"><a id="__codelineno-47-9" name="__codelineno-47-9" href="#__codelineno-47-9"></a><span class="p">}</span>
|
||||
</span></code></pre></div>
|
||||
<ul>
|
||||
<li><code>details</code> appears only when non-empty.</li>
|
||||
|
||||
@@ -2553,7 +2553,7 @@ The classification is keyword-based, checked in order:</p>
|
||||
<td>yes</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>geofence</code>, <code>region</code>, <code>not available in</code>, <code>territory</code></td>
|
||||
<td><code>geofence</code>, <code>geoblock</code>, <code>region</code>, <code>not available in</code>, <code>territory</code></td>
|
||||
<td><code>GEOFENCE</code> (403)</td>
|
||||
<td>no</td>
|
||||
</tr>
|
||||
|
||||
@@ -2470,6 +2470,11 @@ request and response in full.</p>
|
||||
<td>Proxy or server-side DRM licensing.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>POST</code></td>
|
||||
<td><code>/api/session/{session_id}/keys/bad</code></td>
|
||||
<td>Report a server-vault content key that did not decrypt.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>GET</code></td>
|
||||
<td><code>/api/session/{session_id}/logs</code></td>
|
||||
<td>Drain the service's server-side log output.</td>
|
||||
|
||||
@@ -2408,17 +2408,18 @@
|
||||
</span><span id="__span-10-4"><a id="__codelineno-10-4" name="__codelineno-10-4" href="#__codelineno-10-4"></a><span class="w"> </span><span class="nt">"tag"</span><span class="p">:</span><span class="w"> </span><span class="s2">"EXAMPLE"</span><span class="p">,</span>
|
||||
</span><span id="__span-10-5"><a id="__codelineno-10-5" name="__codelineno-10-5" href="#__codelineno-10-5"></a><span class="w"> </span><span class="nt">"aliases"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"EX"</span><span class="p">],</span>
|
||||
</span><span id="__span-10-6"><a id="__codelineno-10-6" name="__codelineno-10-6" href="#__codelineno-10-6"></a><span class="w"> </span><span class="nt">"geofence"</span><span class="p">:</span><span class="w"> </span><span class="p">[],</span>
|
||||
</span><span id="__span-10-7"><a id="__codelineno-10-7" name="__codelineno-10-7" href="#__codelineno-10-7"></a><span class="w"> </span><span class="nt">"title_regex"</span><span class="p">:</span><span class="w"> </span><span class="kc">null</span><span class="p">,</span>
|
||||
</span><span id="__span-10-8"><a id="__codelineno-10-8" name="__codelineno-10-8" href="#__codelineno-10-8"></a><span class="w"> </span><span class="nt">"url"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://example.com"</span><span class="p">,</span>
|
||||
</span><span id="__span-10-9"><a id="__codelineno-10-9" name="__codelineno-10-9" href="#__codelineno-10-9"></a><span class="w"> </span><span class="nt">"help"</span><span class="p">:</span><span class="w"> </span><span class="s2">"EXAMPLE service documentation..."</span><span class="p">,</span>
|
||||
</span><span id="__span-10-10"><a id="__codelineno-10-10" name="__codelineno-10-10" href="#__codelineno-10-10"></a><span class="w"> </span><span class="nt">"needs_auth"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||||
</span><span id="__span-10-11"><a id="__codelineno-10-11" name="__codelineno-10-11" href="#__codelineno-10-11"></a><span class="w"> </span><span class="nt">"has_search"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||||
</span><span id="__span-10-12"><a id="__codelineno-10-12" name="__codelineno-10-12" href="#__codelineno-10-12"></a><span class="w"> </span><span class="nt">"has_drm"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||||
</span><span id="__span-10-13"><a id="__codelineno-10-13" name="__codelineno-10-13" href="#__codelineno-10-13"></a><span class="w"> </span><span class="nt">"auth_methods"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"cookies"</span><span class="p">,</span><span class="w"> </span><span class="s2">"credentials"</span><span class="p">],</span>
|
||||
</span><span id="__span-10-14"><a id="__codelineno-10-14" name="__codelineno-10-14" href="#__codelineno-10-14"></a><span class="w"> </span><span class="nt">"cli_params"</span><span class="p">:</span><span class="w"> </span><span class="p">[]</span>
|
||||
</span><span id="__span-10-15"><a id="__codelineno-10-15" name="__codelineno-10-15" href="#__codelineno-10-15"></a><span class="w"> </span><span class="p">}</span>
|
||||
</span><span id="__span-10-16"><a id="__codelineno-10-16" name="__codelineno-10-16" href="#__codelineno-10-16"></a><span class="w"> </span><span class="p">]</span>
|
||||
</span><span id="__span-10-17"><a id="__codelineno-10-17" name="__codelineno-10-17" href="#__codelineno-10-17"></a><span class="p">}</span>
|
||||
</span><span id="__span-10-7"><a id="__codelineno-10-7" name="__codelineno-10-7" href="#__codelineno-10-7"></a><span class="w"> </span><span class="nt">"geoblock"</span><span class="p">:</span><span class="w"> </span><span class="p">[],</span>
|
||||
</span><span id="__span-10-8"><a id="__codelineno-10-8" name="__codelineno-10-8" href="#__codelineno-10-8"></a><span class="w"> </span><span class="nt">"title_regex"</span><span class="p">:</span><span class="w"> </span><span class="kc">null</span><span class="p">,</span>
|
||||
</span><span id="__span-10-9"><a id="__codelineno-10-9" name="__codelineno-10-9" href="#__codelineno-10-9"></a><span class="w"> </span><span class="nt">"url"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://example.com"</span><span class="p">,</span>
|
||||
</span><span id="__span-10-10"><a id="__codelineno-10-10" name="__codelineno-10-10" href="#__codelineno-10-10"></a><span class="w"> </span><span class="nt">"help"</span><span class="p">:</span><span class="w"> </span><span class="s2">"EXAMPLE service documentation..."</span><span class="p">,</span>
|
||||
</span><span id="__span-10-11"><a id="__codelineno-10-11" name="__codelineno-10-11" href="#__codelineno-10-11"></a><span class="w"> </span><span class="nt">"needs_auth"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||||
</span><span id="__span-10-12"><a id="__codelineno-10-12" name="__codelineno-10-12" href="#__codelineno-10-12"></a><span class="w"> </span><span class="nt">"has_search"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||||
</span><span id="__span-10-13"><a id="__codelineno-10-13" name="__codelineno-10-13" href="#__codelineno-10-13"></a><span class="w"> </span><span class="nt">"has_drm"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span>
|
||||
</span><span id="__span-10-14"><a id="__codelineno-10-14" name="__codelineno-10-14" href="#__codelineno-10-14"></a><span class="w"> </span><span class="nt">"auth_methods"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"cookies"</span><span class="p">,</span><span class="w"> </span><span class="s2">"credentials"</span><span class="p">],</span>
|
||||
</span><span id="__span-10-15"><a id="__codelineno-10-15" name="__codelineno-10-15" href="#__codelineno-10-15"></a><span class="w"> </span><span class="nt">"cli_params"</span><span class="p">:</span><span class="w"> </span><span class="p">[]</span>
|
||||
</span><span id="__span-10-16"><a id="__codelineno-10-16" name="__codelineno-10-16" href="#__codelineno-10-16"></a><span class="w"> </span><span class="p">}</span>
|
||||
</span><span id="__span-10-17"><a id="__codelineno-10-17" name="__codelineno-10-17" href="#__codelineno-10-17"></a><span class="w"> </span><span class="p">]</span>
|
||||
</span><span id="__span-10-18"><a id="__codelineno-10-18" name="__codelineno-10-18" href="#__codelineno-10-18"></a><span class="p">}</span>
|
||||
</span></code></pre></div>
|
||||
<p>If the API key is missing or wrong, you get a <code>401</code> with a plain body:</p>
|
||||
<div class="language-json highlight"><span class="filename">401 Unauthorized</span><pre><span></span><code><span id="__span-11-1"><a id="__codelineno-11-1" name="__codelineno-11-1" href="#__codelineno-11-1"></a><span class="p">{</span><span class="w"> </span><span class="nt">"status"</span><span class="p">:</span><span class="w"> </span><span class="mi">401</span><span class="p">,</span><span class="w"> </span><span class="nt">"message"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Secret Key is Invalid."</span><span class="w"> </span><span class="p">}</span>
|
||||
|
||||
@@ -2554,10 +2554,16 @@ and return the content keys directly. See
|
||||
<a href="#server-side-vs-proxied-cdm">Server-side vs. proxied CDM</a> below.</p>
|
||||
</div>
|
||||
<div class="tabbed-block">
|
||||
<p>The client downloads, decrypts, and muxes locally. On completion it deletes
|
||||
the remote session. If the server has updated cache files (for example a refreshed
|
||||
token), the delete returns them and the client saves them locally, so the <strong>next</strong>
|
||||
remote session can skip interactive auth.</p>
|
||||
<p>The client downloads, decrypts, and muxes locally. While it works, it sends a
|
||||
keep-alive request to the remote session at an interval of one third of
|
||||
<code>session_ttl</code>, so a long download does not let the remote session expire. On
|
||||
completion, and also when <code>dl</code> exits early (<code>--list</code>, Ctrl+C, an error), it
|
||||
deletes the remote session. If the login belongs to the client, the <code>DELETE</code>
|
||||
request returns the updated cache files (for example a refreshed token) and the
|
||||
client saves them locally, so the <strong>next</strong> remote session can skip interactive
|
||||
authentication. The login belongs to the client when the client sent
|
||||
cookies, credentials, or cache files, or answered a login prompt (a device code
|
||||
or an OTP) that led to a successful login. A server-account login never does.</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
@@ -2595,6 +2601,17 @@ CDM.</p>
|
||||
<li>Enable with <code>server_cdm: true</code> in the server entry.</li>
|
||||
<li>The server tells the client which DRM type it used
|
||||
(<code>widevine</code> or <code>playready</code>).</li>
|
||||
<li>A content key the server took from its own vault is unproven. The response
|
||||
lists its KID in <code>vault_keys</code>, the client decrypts and checks that the output
|
||||
decodes, and a wrong pair goes back to <code>POST /api/session/{id}/keys/bad</code>. The
|
||||
server flags the pair in every local vault it holds, reports it to the vault
|
||||
that served it, and the next licence for that KID skips the pair and reaches
|
||||
the CDM. A server with no local SQLite vault cannot store the flag. The
|
||||
server accepts a report only for a pair it served to that remote session. The
|
||||
client never learns the server vault names.</li>
|
||||
<li>A content key in the client's own vaults goes first, even when the server
|
||||
already answered. The client proves it, and a server key waits as the next
|
||||
candidate.</li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
@@ -2723,6 +2740,11 @@ from a browser origin, not when you want only the local HTTP API.</p>
|
||||
<td>DRM licensing (proxy or server CDM)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>POST</code></td>
|
||||
<td><code>/api/session/{id}/keys/bad</code></td>
|
||||
<td>Report a server-vault content key that did not decrypt</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>GET</code></td>
|
||||
<td><code>/api/session/{id}/logs</code></td>
|
||||
<td>Drain the service's server-side log output</td>
|
||||
@@ -2861,9 +2883,10 @@ returns <code>{ "status": "accepted" }</code>. A post with no pending prompt is
|
||||
<div class="language-text highlight"><pre><span></span><code><span id="__span-8-1"><a id="__codelineno-8-1" name="__codelineno-8-1" href="#__codelineno-8-1"></a>_sessions/<pbkdf2_hmac(sha256, X-Secret-Key, "unshackle-session-ns", 100000)[:12]>/<session_id>/<service>
|
||||
</span></code></pre></div>
|
||||
<p>The handler writes forwarded <code>cache</code> files into that directory before authentication.
|
||||
On <code>DELETE</code>, the handler harvests updated cache files (compressing each with zlib
|
||||
and base64-encoding, <strong>excluding</strong> <code>titles_*</code> files) and returns them under a
|
||||
<code>cache</code> field, so the client can keep refreshed tokens:</p>
|
||||
On <code>DELETE</code>, when the login belongs to the client (<code>client_auth</code>), the handler
|
||||
harvests updated cache files (compressing each with zlib and base64-encoding,
|
||||
<strong>excluding</strong> <code>titles_*</code> files) and returns them under a <code>cache</code> field, so the
|
||||
client can keep refreshed tokens:</p>
|
||||
<div class="language-json 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="p">{</span><span class="w"> </span><span class="nt">"status"</span><span class="p">:</span><span class="w"> </span><span class="s2">"ok"</span><span class="p">,</span><span class="w"> </span><span class="nt">"cache"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nt">"tokens"</span><span class="p">:</span><span class="w"> </span><span class="s2">"...base64(zlib(bytes))..."</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="p">}</span>
|
||||
</span></code></pre></div>
|
||||
<h3 id="remote-session-info-response">Remote session info response<a class="headerlink" href="#remote-session-info-response" title="Permanent link">¶</a></h3>
|
||||
|
||||
@@ -2689,6 +2689,11 @@ Two kinds of members matter: <strong>class variables</strong> that give the deta
|
||||
<td>ISO region codes the service requires; empty means no geofence. unshackle treats the first entry as the "main region" for automatic proxy selection.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>GEOBLOCK</code></td>
|
||||
<td><code>tuple[str, ...]</code></td>
|
||||
<td>ISO region codes where the service refuses to work; every other region is allowed. Use it for a service that works worldwide except in its home market.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>VAULT_TAG</code></td>
|
||||
<td><code>Optional[str]</code></td>
|
||||
<td>Overrides the key-vault namespace; defaults to the service's own tag.</td>
|
||||
@@ -2787,7 +2792,10 @@ up the objects your methods rely on:</p>
|
||||
<p>The constructor also resolves proxies: it reads <code>--proxy</code> and the <code>proxy_query</code> and
|
||||
<code>proxy_provider</code> context params that <code>dl</code> derives from it, consults the per-service
|
||||
<code>proxy_map</code>, and, if <code>GEOFENCE</code> is set and you did not give an explicit proxy, does a live
|
||||
IP check and auto-fetches a proxy to <code>GEOFENCE[0]</code> when it detects a geoblock.
|
||||
IP check and auto-fetches a proxy to <code>GEOFENCE[0]</code> when it detects a geoblock. A
|
||||
<code>GEOBLOCK</code> hit with no <code>GEOFENCE</code> stops the run with a "not available in your region"
|
||||
error, because there is no main region to fetch a proxy for; pass <code>--proxy</code> yourself.
|
||||
A proxy whose exit is in a <code>GEOBLOCK</code> region stops the run the same way.
|
||||
See <a href="../../guide/proxies-and-vpn/">Proxies and VPN</a>.</p>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title"><code>TrackRequest</code></p>
|
||||
|
||||
@@ -3221,7 +3221,7 @@ configuration file.</p>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>--merge-video</code></td>
|
||||
<td>Mux all selected video tracks into one file. Defaults to config <code>muxing.merge_video</code>.</td>
|
||||
<td>Mux video tracks that share a height, range, and codec into one file, so only language varies inside a file. Defaults to config <code>muxing.merge_video</code>.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>-o</code>, <code>--output</code></td>
|
||||
@@ -3364,6 +3364,10 @@ and keeps the service's numbering unchanged. Pick an order that covers the whole
|
||||
<td>Bypass the proxy for <strong>all downloads</strong> (manifest, licence, and auth stay proxied).</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>--proxy-download</code></td>
|
||||
<td>Use a different proxy for <strong>all downloads</strong>, in the same forms as <code>--proxy</code> (manifest, licence, and auth stay on <code>--proxy</code>).</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>--remote</code></td>
|
||||
<td>Use a remote unshackle server.</td>
|
||||
</tr>
|
||||
|
||||
@@ -3905,12 +3905,15 @@ configured proxy providers), or a <code>provider:region</code> form.</p>
|
||||
</span><span id="__span-39-2"><a id="__codelineno-39-2" name="__codelineno-39-2" href="#__codelineno-39-2"></a>unshackle<span class="w"> </span>dl<span class="w"> </span>--proxy<span class="w"> </span>nordvpn:ca<span class="w"> </span>EXAMPLE<span class="w"> </span><span class="m">81234567</span>
|
||||
</span><span id="__span-39-3"><a id="__codelineno-39-3" name="__codelineno-39-3" href="#__codelineno-39-3"></a>unshackle<span class="w"> </span>dl<span class="w"> </span>--proxy<span class="w"> </span><span class="s1">'http://user:pass@host:8080'</span><span class="w"> </span>EXAMPLE<span class="w"> </span><span class="m">81234567</span>
|
||||
</span></code></pre></div>
|
||||
<p>Two related flags:</p>
|
||||
<p>Three related flags:</p>
|
||||
<ul>
|
||||
<li><code>--no-proxy</code>: force-disable all proxy use for this run.</li>
|
||||
<li><code>--no-proxy-download</code>: bypass the proxy for <strong>all downloads</strong>. The manifest,
|
||||
license, and authentication requests still go through the proxy. This is useful when you
|
||||
need the proxy only to satisfy geo-checks, not to move the bulk of the data.</li>
|
||||
<li><code>--proxy-download</code>: use a different proxy for <strong>all downloads</strong>. The manifest,
|
||||
license, and authentication requests still go through <code>--proxy</code>. Takes the same forms
|
||||
as <code>--proxy</code>.</li>
|
||||
</ul>
|
||||
<h2 id="performance-and-caching">Performance and caching<a class="headerlink" href="#performance-and-caching" title="Permanent link">¶</a></h2>
|
||||
<table>
|
||||
@@ -3963,7 +3966,7 @@ configured proxy providers), or a <code>provider:region</code> form.</p>
|
||||
<p>By default, unshackle checks your <strong>key vaults</strong> first and only asks a <strong>CDM</strong> to license
|
||||
a content key when the vault misses. You can force one side or the other:</p>
|
||||
<ul>
|
||||
<li><code>--cdm-only</code>: only use the CDM (skip vaults).</li>
|
||||
<li><code>--cdm-only</code>: only use the CDM (skip vaults). Over a <code>server_cdm</code> remote session the flag does not reach the server, whose vault shortcut still runs; it only skips the client's decode check on a server key.</li>
|
||||
<li><code>--cdm <name></code>: use the named CDM device for this run, ignoring the <code>cdm</code> config mapping (including its quality and Widevine/PlayReady sub-entries).</li>
|
||||
<li><code>--vaults-only</code>: only use key vaults and never license through the CDM. A missing
|
||||
content key fails.</li>
|
||||
@@ -4322,7 +4325,7 @@ authoritative list.</p>
|
||||
<td>Run a command after each output file, or run none.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>--proxy</code> / <code>--no-proxy</code> / <code>--no-proxy-download</code></td>
|
||||
<td><code>--proxy</code> / <code>--no-proxy</code> / <code>--no-proxy-download</code> / <code>--proxy-download</code></td>
|
||||
<td></td>
|
||||
<td>Proxy control.</td>
|
||||
</tr>
|
||||
|
||||
@@ -3024,7 +3024,7 @@ control this trade-off on the <code>dl</code> command:</p>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>--cdm-only</code></td>
|
||||
<td>Ignore vaults for sourcing keys and always perform a fresh license request.</td>
|
||||
<td>Ignore vaults for sourcing keys and always perform a fresh license request. Over a <code>server_cdm</code> remote session the server still reads its own vaults; the flag only skips the client's decode check on the key it gets back.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>--cdm <name></code></td>
|
||||
|
||||
@@ -836,6 +836,17 @@
|
||||
</span>
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#-proxy-download" class="md-nav__link">
|
||||
<span class="md-ellipsis">
|
||||
|
||||
--proxy-download
|
||||
|
||||
</span>
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
</ul>
|
||||
@@ -2232,6 +2243,17 @@
|
||||
</span>
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#-proxy-download" class="md-nav__link">
|
||||
<span class="md-ellipsis">
|
||||
|
||||
--proxy-download
|
||||
|
||||
</span>
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
</ul>
|
||||
@@ -2501,7 +2523,7 @@ the config keys inside it map directly onto that proxy provider's settings. See
|
||||
file lives and how unshackle loads it.</p>
|
||||
</div>
|
||||
<h2 id="the-proxy-flag">The <code>--proxy</code> flag<a class="headerlink" href="#the-proxy-flag" title="Permanent link">¶</a></h2>
|
||||
<p>Three options on the <code>dl</code> command control proxying at download time:</p>
|
||||
<p>Four options on the <code>dl</code> command control proxying at download time:</p>
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
@@ -2522,6 +2544,10 @@ file lives and how unshackle loads it.</p>
|
||||
<td><code>--no-proxy-download</code></td>
|
||||
<td>Use the proxy for the manifest, licence, and authentication, but bypass it for the <strong>downloads</strong> themselves.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>--proxy-download</code></td>
|
||||
<td>Use <code>--proxy</code> for the manifest, licence, and authentication, and a different proxy for the <strong>downloads</strong>. Takes the same forms as <code>--proxy</code>.</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<div class="language-shell highlight"><span class="filename">Explicit proxy URI</span><pre><span></span><code><span id="__span-0-1"><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a>unshackle<span class="w"> </span>dl<span class="w"> </span>--proxy<span class="w"> </span>http://user:pass@1.2.3.4:8080<span class="w"> </span>EXAMPLE<span class="w"> </span><span class="m">81234567</span>
|
||||
@@ -2550,6 +2576,16 @@ region as the manifest. On those services, bypassing the proxy for downloads wil
|
||||
cause segment fetches to fail or return the wrong region. If downloads break with
|
||||
<code>--no-proxy-download</code>, remove it.</p>
|
||||
</div>
|
||||
<h3 id="-proxy-download"><code>--proxy-download</code><a class="headerlink" href="#-proxy-download" title="Permanent link">¶</a></h3>
|
||||
<p><code>--proxy-download</code> is the middle ground: the manifest, licence, and authentication go through
|
||||
<code>--proxy</code>, and the downloads go through a second proxy. Use it when one proxy passes the
|
||||
geo-check and another one is faster for bulk traffic. The value takes the same forms as
|
||||
<code>--proxy</code>, so a country code or <code>provider:region</code> resolves against the same providers.</p>
|
||||
<div class="language-shell highlight"><span class="filename">Manifest and licence over NordVPN, downloads over Windscribe</span><pre><span></span><code><span id="__span-4-1"><a id="__codelineno-4-1" name="__codelineno-4-1" href="#__codelineno-4-1"></a>unshackle<span class="w"> </span>dl<span class="w"> </span>--proxy<span class="w"> </span>nordvpn:us<span class="w"> </span>--proxy-download<span class="w"> </span>windscribevpn:us<span class="w"> </span>EXAMPLE<span class="w"> </span>10a1234
|
||||
</span></code></pre></div>
|
||||
<p><code>--no-proxy</code> and <code>--no-proxy-download</code> both override <code>--proxy-download</code>. The same
|
||||
region warning applies: if the service ties segment delivery to the manifest region, keep
|
||||
both proxies in that region.</p>
|
||||
<h2 id="how-proxy-resolution-works">How proxy resolution works<a class="headerlink" href="#how-proxy-resolution-works" title="Permanent link">¶</a></h2>
|
||||
<p>unshackle interprets the value you pass to <code>--proxy</code> in one of three ways. It tries
|
||||
them in this order.</p>
|
||||
@@ -2619,12 +2655,12 @@ when you query that country. This is the right choice when you already have prox
|
||||
seller, your own servers, or a corporate gateway).</p>
|
||||
<p>Under each two-letter country code you can put either a single proxy string or a list of
|
||||
them:</p>
|
||||
<div class="language-yaml highlight"><span class="filename">unshackle.yaml</span><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">basic</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">us</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">http://user:pass@1.2.3.4:8080</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">de</span><span class="p">:</span>
|
||||
</span><span id="__span-4-5"><a id="__codelineno-4-5" name="__codelineno-4-5" href="#__codelineno-4-5"></a><span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">http://a.example:8080</span>
|
||||
</span><span id="__span-4-6"><a id="__codelineno-4-6" name="__codelineno-4-6" href="#__codelineno-4-6"></a><span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">socks5://b.example:1080</span>
|
||||
<div class="language-yaml highlight"><span class="filename">unshackle.yaml</span><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">basic</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">us</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">http://user:pass@1.2.3.4:8080</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">de</span><span class="p">:</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="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">http://a.example:8080</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="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">socks5://b.example:1080</span>
|
||||
</span></code></pre></div>
|
||||
<p><strong>Query forms:</strong></p>
|
||||
<table>
|
||||
@@ -2652,7 +2688,7 @@ them:</p>
|
||||
<li>unshackle normalises each URL (a missing scheme defaults to <code>http</code>) and validates it,
|
||||
so it rejects a malformed URI up front and does not fail mid-download.</li>
|
||||
</ul>
|
||||
<div class="language-shell highlight"><pre><span></span><code><span id="__span-5-1"><a id="__codelineno-5-1" name="__codelineno-5-1" href="#__codelineno-5-1"></a>unshackle<span class="w"> </span>dl<span class="w"> </span>--proxy<span class="w"> </span>de2<span class="w"> </span>EXAMPLE<span class="w"> </span><span class="m">81234567</span>
|
||||
<div class="language-shell highlight"><pre><span></span><code><span id="__span-6-1"><a id="__codelineno-6-1" name="__codelineno-6-1" href="#__codelineno-6-1"></a>unshackle<span class="w"> </span>dl<span class="w"> </span>--proxy<span class="w"> </span>de2<span class="w"> </span>EXAMPLE<span class="w"> </span><span class="m">81234567</span>
|
||||
</span></code></pre></div>
|
||||
<h2 id="gluetun">Gluetun<a class="headerlink" href="#gluetun" title="Permanent link">¶</a></h2>
|
||||
<p>Gluetun is unshackle's most flexible proxy backend, and the one to reach for if you want
|
||||
@@ -2683,11 +2719,11 @@ to <code>/dev/net/tun</code> to bring up the tunnel. unshackle requests both aut
|
||||
<h3 id="query-format">Query format<a class="headerlink" href="#query-format" title="Permanent link">¶</a></h3>
|
||||
<p>Gluetun uses a nested selector: the proxy provider prefix picks Gluetun, and the rest names the
|
||||
<strong>VPN provider</strong> and the <strong>region</strong>.</p>
|
||||
<div class="language-text highlight"><pre><span></span><code><span id="__span-6-1"><a id="__codelineno-6-1" name="__codelineno-6-1" href="#__codelineno-6-1"></a>gluetun:<vpn-provider>:<region>
|
||||
<div class="language-text highlight"><pre><span></span><code><span id="__span-7-1"><a id="__codelineno-7-1" name="__codelineno-7-1" href="#__codelineno-7-1"></a>gluetun:<vpn-provider>:<region>
|
||||
</span></code></pre></div>
|
||||
<div class="language-shell highlight"><span class="filename">A Windscribe US exit via Gluetun</span><pre><span></span><code><span id="__span-7-1"><a id="__codelineno-7-1" name="__codelineno-7-1" href="#__codelineno-7-1"></a>unshackle<span class="w"> </span>dl<span class="w"> </span>--proxy<span class="w"> </span>gluetun:windscribe:us<span class="w"> </span>EXAMPLE<span class="w"> </span><span class="m">81234567</span>
|
||||
<div class="language-shell highlight"><span class="filename">A Windscribe US exit via Gluetun</span><pre><span></span><code><span id="__span-8-1"><a id="__codelineno-8-1" name="__codelineno-8-1" href="#__codelineno-8-1"></a>unshackle<span class="w"> </span>dl<span class="w"> </span>--proxy<span class="w"> </span>gluetun:windscribe:us<span class="w"> </span>EXAMPLE<span class="w"> </span><span class="m">81234567</span>
|
||||
</span></code></pre></div>
|
||||
<div class="language-shell highlight"><span class="filename">A NordVPN Germany exit via Gluetun</span><pre><span></span><code><span id="__span-8-1"><a id="__codelineno-8-1" name="__codelineno-8-1" href="#__codelineno-8-1"></a>unshackle<span class="w"> </span>dl<span class="w"> </span>--proxy<span class="w"> </span>gluetun:nordvpn:de<span class="w"> </span>EXAMPLE<span class="w"> </span><span class="m">81234567</span>
|
||||
<div class="language-shell highlight"><span class="filename">A NordVPN Germany exit via Gluetun</span><pre><span></span><code><span id="__span-9-1"><a id="__codelineno-9-1" name="__codelineno-9-1" href="#__codelineno-9-1"></a>unshackle<span class="w"> </span>dl<span class="w"> </span>--proxy<span class="w"> </span>gluetun:nordvpn:de<span class="w"> </span>EXAMPLE<span class="w"> </span><span class="m">81234567</span>
|
||||
</span></code></pre></div>
|
||||
<p>After unshackle strips the leading <code>gluetun:</code>, the proxy provider receives exactly
|
||||
<code>provider:region</code>. It must be two colon-separated parts, and anything else is an error.
|
||||
@@ -2697,36 +2733,36 @@ unshackle normalises friendly names to Gluetun's identifiers (for example <code>
|
||||
<h3 id="configuration">Configuration<a class="headerlink" href="#configuration" title="Permanent link">¶</a></h3>
|
||||
<p>Each VPN provider you want to use gets an entry under <code>providers:</code>, carrying its VPN type,
|
||||
credentials, and how your region aliases map onto Gluetun's server selectors.</p>
|
||||
<div class="language-yaml highlight"><span class="filename">unshackle.yaml</span><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">proxy_providers</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">gluetun</span><span class="p">:</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">providers</span><span class="p">:</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="nt">windscribe</span><span class="p">:</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="nt">vpn_type</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">wireguard</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="nt">credentials</span><span class="p">:</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="nt">private_key</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">YOUR_WIREGUARD_PRIVATE_KEY</span>
|
||||
</span><span id="__span-9-8"><a id="__codelineno-9-8" name="__codelineno-9-8" href="#__codelineno-9-8"></a><span class="w"> </span><span class="nt">addresses</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">YOUR_WIREGUARD_ADDRESS</span>
|
||||
</span><span id="__span-9-9"><a id="__codelineno-9-9" name="__codelineno-9-9" href="#__codelineno-9-9"></a><span class="w"> </span><span class="nt">preshared_key</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">YOUR_PRESHARED_KEY</span>
|
||||
</span><span id="__span-9-10"><a id="__codelineno-9-10" name="__codelineno-9-10" href="#__codelineno-9-10"></a><span class="w"> </span><span class="nt">server_countries</span><span class="p">:</span>
|
||||
</span><span id="__span-9-11"><a id="__codelineno-9-11" name="__codelineno-9-11" href="#__codelineno-9-11"></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</span>
|
||||
</span><span id="__span-9-12"><a id="__codelineno-9-12" name="__codelineno-9-12" href="#__codelineno-9-12"></a><span class="w"> </span><span class="nt">uk</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">GB</span>
|
||||
</span><span id="__span-9-13"><a id="__codelineno-9-13" name="__codelineno-9-13" href="#__codelineno-9-13"></a><span class="w"> </span><span class="nt">server_cities</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">{}</span>
|
||||
</span><span id="__span-9-14"><a id="__codelineno-9-14" name="__codelineno-9-14" href="#__codelineno-9-14"></a><span class="w"> </span><span class="nt">server_hostnames</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">{}</span>
|
||||
</span><span id="__span-9-15"><a id="__codelineno-9-15" name="__codelineno-9-15" href="#__codelineno-9-15"></a><span class="w"> </span><span class="nt">extra_env</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">{}</span>
|
||||
</span><span id="__span-9-16"><a id="__codelineno-9-16" name="__codelineno-9-16" href="#__codelineno-9-16"></a><span class="w"> </span><span class="nt">nordvpn</span><span class="p">:</span>
|
||||
</span><span id="__span-9-17"><a id="__codelineno-9-17" name="__codelineno-9-17" href="#__codelineno-9-17"></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">wireguard</span>
|
||||
</span><span id="__span-9-18"><a id="__codelineno-9-18" name="__codelineno-9-18" href="#__codelineno-9-18"></a><span class="w"> </span><span class="nt">credentials</span><span class="p">:</span>
|
||||
</span><span id="__span-9-19"><a id="__codelineno-9-19" name="__codelineno-9-19" href="#__codelineno-9-19"></a><span class="w"> </span><span class="nt">private_key</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">YOUR_WIREGUARD_PRIVATE_KEY</span>
|
||||
</span><span id="__span-9-20"><a id="__codelineno-9-20" name="__codelineno-9-20" href="#__codelineno-9-20"></a><span class="w"> </span><span class="nt">server_countries</span><span class="p">:</span>
|
||||
</span><span id="__span-9-21"><a id="__codelineno-9-21" name="__codelineno-9-21" href="#__codelineno-9-21"></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</span>
|
||||
</span><span id="__span-9-22"><a id="__codelineno-9-22" name="__codelineno-9-22" href="#__codelineno-9-22"></a><span class="w"> </span><span class="nt">de</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">DE</span>
|
||||
</span><span id="__span-9-23"><a id="__codelineno-9-23" name="__codelineno-9-23" href="#__codelineno-9-23"></a>
|
||||
</span><span id="__span-9-24"><a id="__codelineno-9-24" name="__codelineno-9-24" href="#__codelineno-9-24"></a><span class="w"> </span><span class="c1"># Global settings (all optional)</span>
|
||||
</span><span id="__span-9-25"><a id="__codelineno-9-25" name="__codelineno-9-25" href="#__codelineno-9-25"></a><span class="w"> </span><span class="nt">base_port</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">8888</span>
|
||||
</span><span id="__span-9-26"><a id="__codelineno-9-26" name="__codelineno-9-26" href="#__codelineno-9-26"></a><span class="w"> </span><span class="nt">auto_cleanup</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
|
||||
</span><span id="__span-9-27"><a id="__codelineno-9-27" name="__codelineno-9-27" href="#__codelineno-9-27"></a><span class="w"> </span><span class="nt">container_prefix</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">unshackle-gluetun</span>
|
||||
</span><span id="__span-9-28"><a id="__codelineno-9-28" name="__codelineno-9-28" href="#__codelineno-9-28"></a><span class="w"> </span><span class="nt">auth_user</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">null</span>
|
||||
</span><span id="__span-9-29"><a id="__codelineno-9-29" name="__codelineno-9-29" href="#__codelineno-9-29"></a><span class="w"> </span><span class="nt">auth_password</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">null</span>
|
||||
</span><span id="__span-9-30"><a id="__codelineno-9-30" name="__codelineno-9-30" href="#__codelineno-9-30"></a><span class="w"> </span><span class="nt">verify_ip</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
|
||||
<div class="language-yaml highlight"><span class="filename">unshackle.yaml</span><pre><span></span><code><span id="__span-10-1"><a id="__codelineno-10-1" name="__codelineno-10-1" href="#__codelineno-10-1"></a><span class="nt">proxy_providers</span><span class="p">:</span>
|
||||
</span><span id="__span-10-2"><a id="__codelineno-10-2" name="__codelineno-10-2" href="#__codelineno-10-2"></a><span class="w"> </span><span class="nt">gluetun</span><span class="p">:</span>
|
||||
</span><span id="__span-10-3"><a id="__codelineno-10-3" name="__codelineno-10-3" href="#__codelineno-10-3"></a><span class="w"> </span><span class="nt">providers</span><span class="p">:</span>
|
||||
</span><span id="__span-10-4"><a id="__codelineno-10-4" name="__codelineno-10-4" href="#__codelineno-10-4"></a><span class="w"> </span><span class="nt">windscribe</span><span class="p">:</span>
|
||||
</span><span id="__span-10-5"><a id="__codelineno-10-5" name="__codelineno-10-5" href="#__codelineno-10-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">wireguard</span>
|
||||
</span><span id="__span-10-6"><a id="__codelineno-10-6" name="__codelineno-10-6" href="#__codelineno-10-6"></a><span class="w"> </span><span class="nt">credentials</span><span class="p">:</span>
|
||||
</span><span id="__span-10-7"><a id="__codelineno-10-7" name="__codelineno-10-7" href="#__codelineno-10-7"></a><span class="w"> </span><span class="nt">private_key</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">YOUR_WIREGUARD_PRIVATE_KEY</span>
|
||||
</span><span id="__span-10-8"><a id="__codelineno-10-8" name="__codelineno-10-8" href="#__codelineno-10-8"></a><span class="w"> </span><span class="nt">addresses</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">YOUR_WIREGUARD_ADDRESS</span>
|
||||
</span><span id="__span-10-9"><a id="__codelineno-10-9" name="__codelineno-10-9" href="#__codelineno-10-9"></a><span class="w"> </span><span class="nt">preshared_key</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">YOUR_PRESHARED_KEY</span>
|
||||
</span><span id="__span-10-10"><a id="__codelineno-10-10" name="__codelineno-10-10" href="#__codelineno-10-10"></a><span class="w"> </span><span class="nt">server_countries</span><span class="p">:</span>
|
||||
</span><span id="__span-10-11"><a id="__codelineno-10-11" name="__codelineno-10-11" href="#__codelineno-10-11"></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</span>
|
||||
</span><span id="__span-10-12"><a id="__codelineno-10-12" name="__codelineno-10-12" href="#__codelineno-10-12"></a><span class="w"> </span><span class="nt">uk</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">GB</span>
|
||||
</span><span id="__span-10-13"><a id="__codelineno-10-13" name="__codelineno-10-13" href="#__codelineno-10-13"></a><span class="w"> </span><span class="nt">server_cities</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">{}</span>
|
||||
</span><span id="__span-10-14"><a id="__codelineno-10-14" name="__codelineno-10-14" href="#__codelineno-10-14"></a><span class="w"> </span><span class="nt">server_hostnames</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">{}</span>
|
||||
</span><span id="__span-10-15"><a id="__codelineno-10-15" name="__codelineno-10-15" href="#__codelineno-10-15"></a><span class="w"> </span><span class="nt">extra_env</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">{}</span>
|
||||
</span><span id="__span-10-16"><a id="__codelineno-10-16" name="__codelineno-10-16" href="#__codelineno-10-16"></a><span class="w"> </span><span class="nt">nordvpn</span><span class="p">:</span>
|
||||
</span><span id="__span-10-17"><a id="__codelineno-10-17" name="__codelineno-10-17" href="#__codelineno-10-17"></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">wireguard</span>
|
||||
</span><span id="__span-10-18"><a id="__codelineno-10-18" name="__codelineno-10-18" href="#__codelineno-10-18"></a><span class="w"> </span><span class="nt">credentials</span><span class="p">:</span>
|
||||
</span><span id="__span-10-19"><a id="__codelineno-10-19" name="__codelineno-10-19" href="#__codelineno-10-19"></a><span class="w"> </span><span class="nt">private_key</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">YOUR_WIREGUARD_PRIVATE_KEY</span>
|
||||
</span><span id="__span-10-20"><a id="__codelineno-10-20" name="__codelineno-10-20" href="#__codelineno-10-20"></a><span class="w"> </span><span class="nt">server_countries</span><span class="p">:</span>
|
||||
</span><span id="__span-10-21"><a id="__codelineno-10-21" name="__codelineno-10-21" href="#__codelineno-10-21"></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</span>
|
||||
</span><span id="__span-10-22"><a id="__codelineno-10-22" name="__codelineno-10-22" href="#__codelineno-10-22"></a><span class="w"> </span><span class="nt">de</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">DE</span>
|
||||
</span><span id="__span-10-23"><a id="__codelineno-10-23" name="__codelineno-10-23" href="#__codelineno-10-23"></a>
|
||||
</span><span id="__span-10-24"><a id="__codelineno-10-24" name="__codelineno-10-24" href="#__codelineno-10-24"></a><span class="w"> </span><span class="c1"># Global settings (all optional)</span>
|
||||
</span><span id="__span-10-25"><a id="__codelineno-10-25" name="__codelineno-10-25" href="#__codelineno-10-25"></a><span class="w"> </span><span class="nt">base_port</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">8888</span>
|
||||
</span><span id="__span-10-26"><a id="__codelineno-10-26" name="__codelineno-10-26" href="#__codelineno-10-26"></a><span class="w"> </span><span class="nt">auto_cleanup</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
|
||||
</span><span id="__span-10-27"><a id="__codelineno-10-27" name="__codelineno-10-27" href="#__codelineno-10-27"></a><span class="w"> </span><span class="nt">container_prefix</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">unshackle-gluetun</span>
|
||||
</span><span id="__span-10-28"><a id="__codelineno-10-28" name="__codelineno-10-28" href="#__codelineno-10-28"></a><span class="w"> </span><span class="nt">auth_user</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">null</span>
|
||||
</span><span id="__span-10-29"><a id="__codelineno-10-29" name="__codelineno-10-29" href="#__codelineno-10-29"></a><span class="w"> </span><span class="nt">auth_password</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">null</span>
|
||||
</span><span id="__span-10-30"><a id="__codelineno-10-30" name="__codelineno-10-30" href="#__codelineno-10-30"></a><span class="w"> </span><span class="nt">verify_ip</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
|
||||
</span></code></pre></div>
|
||||
<p><strong>Per-provider keys:</strong></p>
|
||||
<table>
|
||||
@@ -2902,22 +2938,22 @@ device-login flow, obtains proxy-capable locations from Express's API, and retur
|
||||
authenticated HTTPS proxy. The device login runs once. After that, the cached refresh
|
||||
token keeps you signed in headlessly.</p>
|
||||
<p>Enable it and do a download interactively once:</p>
|
||||
<div class="language-yaml highlight"><span class="filename">unshackle.yaml</span><pre><span></span><code><span id="__span-10-1"><a id="__codelineno-10-1" name="__codelineno-10-1" href="#__codelineno-10-1"></a><span class="nt">proxy_providers</span><span class="p">:</span>
|
||||
</span><span id="__span-10-2"><a id="__codelineno-10-2" name="__codelineno-10-2" href="#__codelineno-10-2"></a><span class="w"> </span><span class="nt">expressvpn</span><span class="p">:</span>
|
||||
</span><span id="__span-10-3"><a id="__codelineno-10-3" name="__codelineno-10-3" href="#__codelineno-10-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>
|
||||
<div class="language-yaml highlight"><span class="filename">unshackle.yaml</span><pre><span></span><code><span id="__span-11-1"><a id="__codelineno-11-1" name="__codelineno-11-1" href="#__codelineno-11-1"></a><span class="nt">proxy_providers</span><span class="p">:</span>
|
||||
</span><span id="__span-11-2"><a id="__codelineno-11-2" name="__codelineno-11-2" href="#__codelineno-11-2"></a><span class="w"> </span><span class="nt">expressvpn</span><span class="p">:</span>
|
||||
</span><span id="__span-11-3"><a id="__codelineno-11-3" name="__codelineno-11-3" href="#__codelineno-11-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></code></pre></div>
|
||||
<p>With <code>enable: true</code> and an interactive terminal, unshackle prints a code and a URL to
|
||||
enter it at. Once you approve it, unshackle caches the tokens and reuses them
|
||||
automatically, so later runs need no terminal. ExpressVPN also <strong>auto-loads</strong> once its token cache exists, so you can
|
||||
drop <code>enable</code> after the first login, but you can keep a YAML block to pin regions or
|
||||
servers:</p>
|
||||
<div class="language-yaml highlight"><span class="filename">unshackle.yaml (optional)</span><pre><span></span><code><span id="__span-11-1"><a id="__codelineno-11-1" name="__codelineno-11-1" href="#__codelineno-11-1"></a><span class="nt">proxy_providers</span><span class="p">:</span>
|
||||
</span><span id="__span-11-2"><a id="__codelineno-11-2" name="__codelineno-11-2" href="#__codelineno-11-2"></a><span class="w"> </span><span class="nt">expressvpn</span><span class="p">:</span>
|
||||
</span><span id="__span-11-3"><a id="__codelineno-11-3" name="__codelineno-11-3" href="#__codelineno-11-3"></a><span class="w"> </span><span class="nt">region_map</span><span class="p">:</span>
|
||||
</span><span id="__span-11-4"><a id="__codelineno-11-4" name="__codelineno-11-4" href="#__codelineno-11-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">ny-02</span><span class="w"> </span><span class="c1"># prefer New York, server 02 for the US</span>
|
||||
</span><span id="__span-11-5"><a id="__codelineno-11-5" name="__codelineno-11-5" href="#__codelineno-11-5"></a><span class="w"> </span><span class="nt">gb</span><span class="p">:</span><span class="w"> </span><span class="c1"># empty = smart random location</span>
|
||||
</span><span id="__span-11-6"><a id="__codelineno-11-6" name="__codelineno-11-6" href="#__codelineno-11-6"></a><span class="w"> </span><span class="nt">server_map</span><span class="p">:</span>
|
||||
</span><span id="__span-11-7"><a id="__codelineno-11-7" name="__codelineno-11-7" href="#__codelineno-11-7"></a><span class="w"> </span><span class="nt">myserver</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">usny-newyork-2</span>
|
||||
<div class="language-yaml highlight"><span class="filename">unshackle.yaml (optional)</span><pre><span></span><code><span id="__span-12-1"><a id="__codelineno-12-1" name="__codelineno-12-1" href="#__codelineno-12-1"></a><span class="nt">proxy_providers</span><span class="p">:</span>
|
||||
</span><span id="__span-12-2"><a id="__codelineno-12-2" name="__codelineno-12-2" href="#__codelineno-12-2"></a><span class="w"> </span><span class="nt">expressvpn</span><span class="p">:</span>
|
||||
</span><span id="__span-12-3"><a id="__codelineno-12-3" name="__codelineno-12-3" href="#__codelineno-12-3"></a><span class="w"> </span><span class="nt">region_map</span><span class="p">:</span>
|
||||
</span><span id="__span-12-4"><a id="__codelineno-12-4" name="__codelineno-12-4" href="#__codelineno-12-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">ny-02</span><span class="w"> </span><span class="c1"># prefer New York, server 02 for the US</span>
|
||||
</span><span id="__span-12-5"><a id="__codelineno-12-5" name="__codelineno-12-5" href="#__codelineno-12-5"></a><span class="w"> </span><span class="nt">gb</span><span class="p">:</span><span class="w"> </span><span class="c1"># empty = smart random location</span>
|
||||
</span><span id="__span-12-6"><a id="__codelineno-12-6" name="__codelineno-12-6" href="#__codelineno-12-6"></a><span class="w"> </span><span class="nt">server_map</span><span class="p">:</span>
|
||||
</span><span id="__span-12-7"><a id="__codelineno-12-7" name="__codelineno-12-7" href="#__codelineno-12-7"></a><span class="w"> </span><span class="nt">myserver</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">usny-newyork-2</span>
|
||||
</span></code></pre></div>
|
||||
<p><strong>Default file location:</strong></p>
|
||||
<table>
|
||||
@@ -2977,13 +3013,13 @@ token is never briefly world-readable.</p>
|
||||
<p>NordVPN uses your <strong>Service Credentials</strong>, not your normal NordVPN login. Make them
|
||||
from the <a href="https://my.nordaccount.com/dashboard/nordvpn/">NordVPN dashboard</a> under manual
|
||||
setup. They are a long random username/password pair, not your email and password.</p>
|
||||
<div class="language-yaml highlight"><span class="filename">unshackle.yaml</span><pre><span></span><code><span id="__span-12-1"><a id="__codelineno-12-1" name="__codelineno-12-1" href="#__codelineno-12-1"></a><span class="nt">proxy_providers</span><span class="p">:</span>
|
||||
</span><span id="__span-12-2"><a id="__codelineno-12-2" name="__codelineno-12-2" href="#__codelineno-12-2"></a><span class="w"> </span><span class="nt">nordvpn</span><span class="p">:</span>
|
||||
</span><span id="__span-12-3"><a id="__codelineno-12-3" name="__codelineno-12-3" href="#__codelineno-12-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">YOUR_SERVICE_USERNAME</span>
|
||||
</span><span id="__span-12-4"><a id="__codelineno-12-4" name="__codelineno-12-4" href="#__codelineno-12-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">YOUR_SERVICE_PASSWORD</span>
|
||||
</span><span id="__span-12-5"><a id="__codelineno-12-5" name="__codelineno-12-5" href="#__codelineno-12-5"></a><span class="w"> </span><span class="nt">server_map</span><span class="p">:</span><span class="w"> </span><span class="c1"># optional: pin specific server IDs</span>
|
||||
</span><span id="__span-12-6"><a id="__codelineno-12-6" name="__codelineno-12-6" href="#__codelineno-12-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">1234</span>
|
||||
</span><span id="__span-12-7"><a id="__codelineno-12-7" name="__codelineno-12-7" href="#__codelineno-12-7"></a><span class="w"> </span><span class="nt">us:seattle</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">5678</span>
|
||||
<div class="language-yaml highlight"><span class="filename">unshackle.yaml</span><pre><span></span><code><span id="__span-13-1"><a id="__codelineno-13-1" name="__codelineno-13-1" href="#__codelineno-13-1"></a><span class="nt">proxy_providers</span><span class="p">:</span>
|
||||
</span><span id="__span-13-2"><a id="__codelineno-13-2" name="__codelineno-13-2" href="#__codelineno-13-2"></a><span class="w"> </span><span class="nt">nordvpn</span><span class="p">:</span>
|
||||
</span><span id="__span-13-3"><a id="__codelineno-13-3" name="__codelineno-13-3" href="#__codelineno-13-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">YOUR_SERVICE_USERNAME</span>
|
||||
</span><span id="__span-13-4"><a id="__codelineno-13-4" name="__codelineno-13-4" href="#__codelineno-13-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">YOUR_SERVICE_PASSWORD</span>
|
||||
</span><span id="__span-13-5"><a id="__codelineno-13-5" name="__codelineno-13-5" href="#__codelineno-13-5"></a><span class="w"> </span><span class="nt">server_map</span><span class="p">:</span><span class="w"> </span><span class="c1"># optional: pin specific server IDs</span>
|
||||
</span><span id="__span-13-6"><a id="__codelineno-13-6" name="__codelineno-13-6" href="#__codelineno-13-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">1234</span>
|
||||
</span><span id="__span-13-7"><a id="__codelineno-13-7" name="__codelineno-13-7" href="#__codelineno-13-7"></a><span class="w"> </span><span class="nt">us:seattle</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">5678</span>
|
||||
</span></code></pre></div>
|
||||
<p><strong>Required keys:</strong> <code>username</code>, <code>password</code>. unshackle validates them up front: the
|
||||
combined username and password must be exactly 48 alphanumeric characters (case-insensitive), and
|
||||
@@ -3028,7 +3064,7 @@ country-code confusion that <code>uk</code> invites.</p>
|
||||
</table>
|
||||
<p>The returned proxy is HTTPS on <strong>port 89</strong> (NordVPN disabled its plain-HTTP proxies on
|
||||
port 80 in 2021).</p>
|
||||
<div class="language-shell highlight"><pre><span></span><code><span id="__span-13-1"><a id="__codelineno-13-1" name="__codelineno-13-1" href="#__codelineno-13-1"></a>unshackle<span class="w"> </span>dl<span class="w"> </span>--proxy<span class="w"> </span>nordvpn:us:seattle<span class="w"> </span>EXAMPLE<span class="w"> </span><span class="m">81234567</span>
|
||||
<div class="language-shell highlight"><pre><span></span><code><span id="__span-14-1"><a id="__codelineno-14-1" name="__codelineno-14-1" href="#__codelineno-14-1"></a>unshackle<span class="w"> </span>dl<span class="w"> </span>--proxy<span class="w"> </span>nordvpn:us:seattle<span class="w"> </span>EXAMPLE<span class="w"> </span><span class="m">81234567</span>
|
||||
</span></code></pre></div>
|
||||
<h2 id="proton-vpn">Proton VPN<a class="headerlink" href="#proton-vpn" title="Permanent link">¶</a></h2>
|
||||
<p>Proton VPN supports two authentication methods, and unshackle can work with either. Note
|
||||
@@ -3039,9 +3075,9 @@ that free Proton accounts work, but Proton limits them to its free-tier exit cou
|
||||
<p>Proton's TV device-login flow gives a self-sustaining, refreshable sign-in. This is
|
||||
the only method that can refresh itself headlessly, so it keeps working without
|
||||
re-exporting anything. Enable it and do a download interactively once:</p>
|
||||
<div class="language-yaml highlight"><span class="filename">unshackle.yaml</span><pre><span></span><code><span id="__span-14-1"><a id="__codelineno-14-1" name="__codelineno-14-1" href="#__codelineno-14-1"></a><span class="nt">proxy_providers</span><span class="p">:</span>
|
||||
</span><span id="__span-14-2"><a id="__codelineno-14-2" name="__codelineno-14-2" href="#__codelineno-14-2"></a><span class="w"> </span><span class="nt">protonvpn</span><span class="p">:</span>
|
||||
</span><span id="__span-14-3"><a id="__codelineno-14-3" name="__codelineno-14-3" href="#__codelineno-14-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>
|
||||
<div class="language-yaml highlight"><span class="filename">unshackle.yaml</span><pre><span></span><code><span id="__span-15-1"><a id="__codelineno-15-1" name="__codelineno-15-1" href="#__codelineno-15-1"></a><span class="nt">proxy_providers</span><span class="p">:</span>
|
||||
</span><span id="__span-15-2"><a id="__codelineno-15-2" name="__codelineno-15-2" href="#__codelineno-15-2"></a><span class="w"> </span><span class="nt">protonvpn</span><span class="p">:</span>
|
||||
</span><span id="__span-15-3"><a id="__codelineno-15-3" name="__codelineno-15-3" href="#__codelineno-15-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></code></pre></div>
|
||||
<p>With <code>enable: true</code> and an interactive terminal, unshackle prints a code and asks you
|
||||
to enter it at <a href="https://account.proton.me/vpn/tv/code">account.proton.me/vpn/tv/code</a>.
|
||||
@@ -3134,7 +3170,7 @@ previous run's log line (e.g. <code>DE#203</code>) instead.</p>
|
||||
<a href="https://github.com/Snawoot/hola-proxy"><code>hola-proxy</code></a> binary, and <strong>auto-loads</strong> whenever
|
||||
that binary is found on your <code>PATH</code>. If you query Hola but the binary is missing, the
|
||||
proxy provider raises an error that tells you to install it.</p>
|
||||
<div class="language-shell highlight"><span class="filename">Install hola-proxy, then just query a country</span><pre><span></span><code><span id="__span-15-1"><a id="__codelineno-15-1" name="__codelineno-15-1" href="#__codelineno-15-1"></a>unshackle<span class="w"> </span>dl<span class="w"> </span>--proxy<span class="w"> </span>hola:us<span class="w"> </span>EXAMPLE<span class="w"> </span><span class="m">81234567</span>
|
||||
<div class="language-shell highlight"><span class="filename">Install hola-proxy, then just query a country</span><pre><span></span><code><span id="__span-16-1"><a id="__codelineno-16-1" name="__codelineno-16-1" href="#__codelineno-16-1"></a>unshackle<span class="w"> </span>dl<span class="w"> </span>--proxy<span class="w"> </span>hola:us<span class="w"> </span>EXAMPLE<span class="w"> </span><span class="m">81234567</span>
|
||||
</span></code></pre></div>
|
||||
<p><strong>Query forms:</strong> a two-letter country code (e.g. <code>us</code>, <code>gb</code>). unshackle asks <code>hola-proxy</code>
|
||||
for available proxies in that country and picks one at random, returning an HTTP proxy.</p>
|
||||
@@ -3147,12 +3183,12 @@ only datacenter proxies.</p>
|
||||
<h2 id="surfshark">Surfshark<a class="headerlink" href="#surfshark" title="Permanent link">¶</a></h2>
|
||||
<p>Surfshark, like NordVPN, uses <strong>Service Credentials</strong> rather than your login. Make
|
||||
them from the <a href="https://my.surfshark.com/vpn/manual-setup/main/openvpn">Surfshark manual-setup page</a>.</p>
|
||||
<div class="language-yaml highlight"><span class="filename">unshackle.yaml</span><pre><span></span><code><span id="__span-16-1"><a id="__codelineno-16-1" name="__codelineno-16-1" href="#__codelineno-16-1"></a><span class="nt">proxy_providers</span><span class="p">:</span>
|
||||
</span><span id="__span-16-2"><a id="__codelineno-16-2" name="__codelineno-16-2" href="#__codelineno-16-2"></a><span class="w"> </span><span class="nt">surfsharkvpn</span><span class="p">:</span>
|
||||
</span><span id="__span-16-3"><a id="__codelineno-16-3" name="__codelineno-16-3" href="#__codelineno-16-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">YOUR_SERVICE_USERNAME</span>
|
||||
</span><span id="__span-16-4"><a id="__codelineno-16-4" name="__codelineno-16-4" href="#__codelineno-16-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">YOUR_SERVICE_PASSWORD</span>
|
||||
</span><span id="__span-16-5"><a id="__codelineno-16-5" name="__codelineno-16-5" href="#__codelineno-16-5"></a><span class="w"> </span><span class="nt">server_map</span><span class="p">:</span><span class="w"> </span><span class="c1"># optional</span>
|
||||
</span><span id="__span-16-6"><a id="__codelineno-16-6" name="__codelineno-16-6" href="#__codelineno-16-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">1234</span>
|
||||
<div class="language-yaml highlight"><span class="filename">unshackle.yaml</span><pre><span></span><code><span id="__span-17-1"><a id="__codelineno-17-1" name="__codelineno-17-1" href="#__codelineno-17-1"></a><span class="nt">proxy_providers</span><span class="p">:</span>
|
||||
</span><span id="__span-17-2"><a id="__codelineno-17-2" name="__codelineno-17-2" href="#__codelineno-17-2"></a><span class="w"> </span><span class="nt">surfsharkvpn</span><span class="p">:</span>
|
||||
</span><span id="__span-17-3"><a id="__codelineno-17-3" name="__codelineno-17-3" href="#__codelineno-17-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">YOUR_SERVICE_USERNAME</span>
|
||||
</span><span id="__span-17-4"><a id="__codelineno-17-4" name="__codelineno-17-4" href="#__codelineno-17-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">YOUR_SERVICE_PASSWORD</span>
|
||||
</span><span id="__span-17-5"><a id="__codelineno-17-5" name="__codelineno-17-5" href="#__codelineno-17-5"></a><span class="w"> </span><span class="nt">server_map</span><span class="p">:</span><span class="w"> </span><span class="c1"># optional</span>
|
||||
</span><span id="__span-17-6"><a id="__codelineno-17-6" name="__codelineno-17-6" href="#__codelineno-17-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">1234</span>
|
||||
</span></code></pre></div>
|
||||
<p><strong>Required keys:</strong> <code>username</code>, <code>password</code>, validated with the same 48-character rule as
|
||||
NordVPN (combined username+password must be 48 alphanumeric characters, case-insensitive, no <code>@</code>).
|
||||
@@ -3185,13 +3221,13 @@ NordVPN (combined username+password must be 48 alphanumeric characters, case-ins
|
||||
<p>Windscribe uses <strong>Service Credentials</strong> from its
|
||||
<a href="https://windscribe.com/getconfig/openvpn">OpenVPN config page</a>. unshackle only makes
|
||||
sure that a username and a password are present (there is no 48-character rule).</p>
|
||||
<div class="language-yaml highlight"><span class="filename">unshackle.yaml</span><pre><span></span><code><span id="__span-17-1"><a id="__codelineno-17-1" name="__codelineno-17-1" href="#__codelineno-17-1"></a><span class="nt">proxy_providers</span><span class="p">:</span>
|
||||
</span><span id="__span-17-2"><a id="__codelineno-17-2" name="__codelineno-17-2" href="#__codelineno-17-2"></a><span class="w"> </span><span class="nt">windscribevpn</span><span class="p">:</span>
|
||||
</span><span id="__span-17-3"><a id="__codelineno-17-3" name="__codelineno-17-3" href="#__codelineno-17-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">YOUR_SERVICE_USERNAME</span>
|
||||
</span><span id="__span-17-4"><a id="__codelineno-17-4" name="__codelineno-17-4" href="#__codelineno-17-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">YOUR_SERVICE_PASSWORD</span>
|
||||
</span><span id="__span-17-5"><a id="__codelineno-17-5" name="__codelineno-17-5" href="#__codelineno-17-5"></a><span class="w"> </span><span class="nt">server_map</span><span class="p">:</span><span class="w"> </span><span class="c1"># optional: alias -> hostname</span>
|
||||
</span><span id="__span-17-6"><a id="__codelineno-17-6" name="__codelineno-17-6" href="#__codelineno-17-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-east.totallyacdn.com</span>
|
||||
</span><span id="__span-17-7"><a id="__codelineno-17-7" name="__codelineno-17-7" href="#__codelineno-17-7"></a><span class="w"> </span><span class="nt">us:seattle</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">us-seattle.totallyacdn.com</span>
|
||||
<div class="language-yaml highlight"><span class="filename">unshackle.yaml</span><pre><span></span><code><span id="__span-18-1"><a id="__codelineno-18-1" name="__codelineno-18-1" href="#__codelineno-18-1"></a><span class="nt">proxy_providers</span><span class="p">:</span>
|
||||
</span><span id="__span-18-2"><a id="__codelineno-18-2" name="__codelineno-18-2" href="#__codelineno-18-2"></a><span class="w"> </span><span class="nt">windscribevpn</span><span class="p">:</span>
|
||||
</span><span id="__span-18-3"><a id="__codelineno-18-3" name="__codelineno-18-3" href="#__codelineno-18-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">YOUR_SERVICE_USERNAME</span>
|
||||
</span><span id="__span-18-4"><a id="__codelineno-18-4" name="__codelineno-18-4" href="#__codelineno-18-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">YOUR_SERVICE_PASSWORD</span>
|
||||
</span><span id="__span-18-5"><a id="__codelineno-18-5" name="__codelineno-18-5" href="#__codelineno-18-5"></a><span class="w"> </span><span class="nt">server_map</span><span class="p">:</span><span class="w"> </span><span class="c1"># optional: alias -> hostname</span>
|
||||
</span><span id="__span-18-6"><a id="__codelineno-18-6" name="__codelineno-18-6" href="#__codelineno-18-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-east.totallyacdn.com</span>
|
||||
</span><span id="__span-18-7"><a id="__codelineno-18-7" name="__codelineno-18-7" href="#__codelineno-18-7"></a><span class="w"> </span><span class="nt">us:seattle</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">us-seattle.totallyacdn.com</span>
|
||||
</span></code></pre></div>
|
||||
<p><strong>Required keys:</strong> <code>username</code>, <code>password</code>. <code>server_map</code> optionally maps a region (or
|
||||
<code>region:city</code>) directly to a hostname.</p>
|
||||
|
||||
@@ -2593,6 +2593,11 @@
|
||||
<p><strong>Inspect:</strong> enable <code>debug_keys</code> and operate unshackle with <code>-d</code>. Then examine the JSON debug log's <code>drm_*</code> and <code>vault_*</code> operations to see which content keys unshackle fetched, and from where. Also make sure that shaka-packager (or <code>mp4decrypt</code>) shows a sane version in the <code>download_init</code> binary-versions entry. See <a href="../drm-and-cdm/">DRM & CDM</a>.</p>
|
||||
</div>
|
||||
<div class="admonition example">
|
||||
<p class="admonition-title">A vault served a wrong content key</p>
|
||||
<p><strong>Symptom:</strong> a warning names a content key and the vault it came from, either <code>was bad, trying other vaults</code> (the decode check failed) or <code>is flagged bad, skipping</code> (an earlier run flagged it). The download stops with <code>The content key from the vault did not decrypt the track; run again</code>, <code>was bad and no other source has the key</code>, or <code>No vault or CDM produced a content key that decrypts the track</code> when no source is left to try.</p>
|
||||
<p><strong>Inspect:</strong> while it decrypts a track whose content key came from a vault, unshackle keeps the ciphertext as a <code>.enc</code> sibling of the track file in the temp directory, and removes it afterwards; a leftover one is from a killed run and is safe to delete. Read the <code>bad_keys</code> table of your local SQLite vault to see which pairs are flagged and which vault each came from. See <a href="../vaults/#wrong-keys-from-a-poisoned-vault">Wrong keys from a poisoned vault</a>.</p>
|
||||
</div>
|
||||
<div class="admonition example">
|
||||
<p class="admonition-title">A network request fails at the connection or TLS layer</p>
|
||||
<p><strong>Symptom:</strong> timeouts, connection resets, or handshake errors, and unshackle's own logs do not give the full cause.</p>
|
||||
<p><strong>Inspect:</strong> set <code>debug_requests: true</code> and operate unshackle with <code>-d</code> to show the underlying <code>urllib3</code> / <code>rnet</code> / <code>httpx</code> logs. In the JSON debug log, filter for <code>service_call</code> operations to see which request failed. If you use a proxy, also read <a href="../proxies-and-vpn/">Proxies & VPN</a>.</p>
|
||||
|
||||
+48
-1
@@ -863,6 +863,23 @@
|
||||
</span>
|
||||
</a>
|
||||
|
||||
<nav class="md-nav" aria-label="How lookups and caching work">
|
||||
<ul class="md-nav__list">
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#wrong-keys-from-a-poisoned-vault" class="md-nav__link">
|
||||
<span class="md-ellipsis">
|
||||
|
||||
Wrong keys from a poisoned vault
|
||||
|
||||
</span>
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
</ul>
|
||||
</nav>
|
||||
|
||||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
@@ -2159,6 +2176,23 @@
|
||||
</span>
|
||||
</a>
|
||||
|
||||
<nav class="md-nav" aria-label="How lookups and caching work">
|
||||
<ul class="md-nav__list">
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#wrong-keys-from-a-poisoned-vault" class="md-nav__link">
|
||||
<span class="md-ellipsis">
|
||||
|
||||
Wrong keys from a poisoned vault
|
||||
|
||||
</span>
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
</ul>
|
||||
</nav>
|
||||
|
||||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
@@ -2366,6 +2400,17 @@
|
||||
<li>A vault marked <code>no_push: true</code> receives lookups, but unshackle never writes to it. This is useful for read-only or shared upstream vaults you do not own.</li>
|
||||
</ul>
|
||||
<p>unshackle pushes keys from every source, not only a local CDM. A run against a remote server that licenses with its own CDM (<code>--remote</code>) writes the keys the server returns, and <code>unshackle import</code> writes the keys it reads from an export file.</p>
|
||||
<h3 id="wrong-keys-from-a-poisoned-vault">Wrong keys from a poisoned vault<a class="headerlink" href="#wrong-keys-from-a-poisoned-vault" title="Permanent link">¶</a></h3>
|
||||
<p>A public vault can return the right KID with a wrong content key. The decrypters accept a wrong content key and write noise. unshackle therefore trusts a content key from a vault only after FFmpeg decodes the first seconds of the decrypted track with strict error detection. Content keys from a licence skip this check. A file this FFmpeg build cannot judge counts as a pass, never as a wrong content key: a codec it has no decoder for, or a header it cannot read. Without FFmpeg there is no check at all.</p>
|
||||
<p>When the decode fails, unshackle:</p>
|
||||
<ol>
|
||||
<li>Flags the KID:KEY in the <code>bad_keys</code> table of every local SQLite vault, with the service and the name of the vault it came from. The pair also goes out of the service table, except in a vault marked <code>no_push</code>, where only the flag is written.</li>
|
||||
<li>Restores the ciphertext from a hard link it made before decryption, then asks for the content key again. Every vault lookup skips a flagged pair, so the request reaches the remaining vaults and then the CDM. A remote answer that arrived after the winning one is reused instead of queried again.</li>
|
||||
<li>Removes the flag when the CDM returns the same content key, because then the decode check was wrong, not the content key. A content key from another vault is checked in its turn, and flagged as well if it also fails.</li>
|
||||
</ol>
|
||||
<p>The download stops with an error instead of writing noise when no ciphertext is left to retry with, or when every vault and the CDM are used up. Without a local SQLite vault nothing remembers a flag, so the same vault serves the same pair again and the download stops there.</p>
|
||||
<p>Per-segment decryption gives up the retry. With <code>decrypt_segments</code> on, and always with MonaLisa, the plaintext replaces each segment as it arrives, so no ciphertext is left. A failed decode then flags the pair and stops the download. The next run skips the flagged pair.</p>
|
||||
<p>unshackle copies a content key from one vault to the others only after this check passes, so a wrong content key does not spread. Without FFmpeg, a content key from a vault is not copied at all. To see or clear the flags, open the SQLite file and read or delete rows in <code>bad_keys</code>.</p>
|
||||
<div class="admonition tip">
|
||||
<p class="admonition-title">A good two-vault setup</p>
|
||||
<p>A common arrangement is a fast local <strong>SQLite</strong> vault plus a shared remote vault (<strong>MySQL</strong>, <strong>HTTP</strong>, or <strong>API</strong>). The local vault answers instantly and works offline; the remote vault lets you share keys across machines or with a group.</p>
|
||||
@@ -2434,6 +2479,7 @@
|
||||
</tbody>
|
||||
</table>
|
||||
<p>Each service gets its own table (named after the service tag), created on demand with <code>kid</code> and <code>key_</code> columns. Connections use WAL journaling with a 30-second busy timeout, so multiple threads can safely use the same database file.</p>
|
||||
<p>One more table, <code>bad_keys</code>, is created on demand and holds every KID:KEY that failed the decode check described in <a href="#wrong-keys-from-a-poisoned-vault">Wrong keys from a poisoned vault</a>, with the service, the vault it came from, and the time it was flagged. It is not a service table, and every command that walks the service tables skips it.</p>
|
||||
<div class="admonition warning">
|
||||
<p class="admonition-title">Moving the .db file silently forks your vault</p>
|
||||
<p>Because the file is created on demand, if you relocate an existing <code>.db</code> without updating <code>path</code> to match, unshackle will create a fresh empty database at the old location. That leaves you with two divergent vaults and no error to warn you. Always update the config path whenever you move the file.</p>
|
||||
@@ -2766,11 +2812,12 @@
|
||||
</tbody>
|
||||
</table>
|
||||
<p><code>--service</code> and <code>--local-only</code> are mutually exclusive.</p>
|
||||
<p>A pair the destination vault has flagged in <code>bad_keys</code> is left behind, so a copy does not undo a flag. <code>bad_keys</code> is never treated as a service, so its rows are never copied into a service table.</p>
|
||||
<h3 id="kv-sync-mirror-vaults-both-ways"><code>kv sync</code>: mirror vaults both ways<a class="headerlink" href="#kv-sync-mirror-vaults-both-ways" title="Permanent link">¶</a></h3>
|
||||
<p>Make each of two or more vaults hold every content key the others have. This is effectively a two-way <code>copy</code> between each pair, so afterwards all listed vaults hold the same set of keys.</p>
|
||||
<div class="language-console highlight"><pre><span></span><code><span id="__span-14-1"><a id="__codelineno-14-1" name="__codelineno-14-1" href="#__codelineno-14-1"></a><span class="gp">$ </span>unshackle<span class="w"> </span>kv<span class="w"> </span>sync<span class="w"> </span><span class="nb">local</span><span class="w"> </span>shared
|
||||
</span></code></pre></div>
|
||||
<p>It accepts the same <code>--service</code> and <code>--local-only</code> options as <code>copy</code>, and requires at least two vaults.</p>
|
||||
<p>It accepts the same <code>--service</code> and <code>--local-only</code> options as <code>copy</code>, and requires at least two vaults. It runs <code>copy</code> between each pair, so it skips flagged pairs and the <code>bad_keys</code> table in the same way.</p>
|
||||
<h3 id="kv-prepare-pre-create-service-tables"><code>kv prepare</code>: pre-create service tables<a class="headerlink" href="#kv-prepare-pre-create-service-tables" title="Permanent link">¶</a></h3>
|
||||
<p>Create the per-service tables on table-based vaults (<code>SQLite</code>, <code>MySQL</code>) ahead of time, for every service you have installed. Vaults that do not use tables (the network-backed <code>HTTP</code> and <code>API</code> backends) are skipped.</p>
|
||||
<div class="language-console highlight"><pre><span></span><code><span id="__span-15-1"><a id="__codelineno-15-1" name="__codelineno-15-1" href="#__codelineno-15-1"></a><span class="gp">$ </span>unshackle<span class="w"> </span>kv<span class="w"> </span>prepare<span class="w"> </span>shared
|
||||
|
||||
BIN
Binary file not shown.
@@ -1895,6 +1895,17 @@
|
||||
</ul>
|
||||
</nav>
|
||||
|
||||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#unshackle.core.config.restore_bool_languages" class="md-nav__link">
|
||||
<span class="md-ellipsis">
|
||||
|
||||
<code class="doc-symbol doc-symbol-toc doc-symbol-function"></code> restore_bool_languages
|
||||
|
||||
</span>
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
@@ -2115,6 +2126,17 @@
|
||||
</ul>
|
||||
</nav>
|
||||
|
||||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#unshackle.core.config.restore_bool_languages" class="md-nav__link">
|
||||
<span class="md-ellipsis">
|
||||
|
||||
<code class="doc-symbol doc-symbol-toc doc-symbol-function"></code> restore_bool_languages
|
||||
|
||||
</span>
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
@@ -2346,6 +2368,26 @@ between variables. Falls back to dot separator (scene-style) by default.</p>
|
||||
<div class="doc doc-object doc-function">
|
||||
|
||||
|
||||
<h2 id="unshackle.core.config.restore_bool_languages" class="doc doc-heading">
|
||||
<code class="doc-symbol doc-symbol-heading doc-symbol-function"></code> <span class="doc doc-object-name doc-function-name">restore_bool_languages</span>
|
||||
|
||||
|
||||
<a href="#unshackle.core.config.restore_bool_languages" class="headerlink" title="Permanent link">¶</a></h2>
|
||||
<div class="language-python doc-signature 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="nf">restore_bool_languages</span><span class="p">(</span><span class="n">data</span><span class="p">)</span>
|
||||
</span></code></pre></div>
|
||||
|
||||
<div class="doc doc-contents ">
|
||||
|
||||
<p>Put back the language tags <code>no</code> and <code>yes</code>, which YAML reads as booleans.</p>
|
||||
|
||||
|
||||
</div>
|
||||
|
||||
</div>
|
||||
|
||||
<div class="doc doc-object doc-function">
|
||||
|
||||
|
||||
<h2 id="unshackle.core.config.resolve_decryption" class="doc doc-heading">
|
||||
<code class="doc-symbol doc-symbol-heading doc-symbol-function"></code> <span class="doc doc-object-name doc-function-name">resolve_decryption</span>
|
||||
|
||||
|
||||
+940
-834
File diff suppressed because it is too large
Load Diff
@@ -4254,7 +4254,12 @@ If mime_type is not provided, it will try to guess it.</p>
|
||||
|
||||
|
||||
<a href="#unshackle.core.tracks.Attachment.download" class="headerlink" title="Permanent link">¶</a></h3>
|
||||
<div class="language-python doc-signature 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="nf">download</span><span class="p">(</span><span class="n">session</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="o">*</span><span class="p">,</span> <span class="n">no_proxy_download</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>
|
||||
<div class="language-python doc-signature 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="nf">download</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="n">session</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>
|
||||
</span><span id="__span-0-3"><a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a> <span class="o">*</span><span class="p">,</span>
|
||||
</span><span id="__span-0-4"><a id="__codelineno-0-4" name="__codelineno-0-4" href="#__codelineno-0-4"></a> <span class="n">no_proxy_download</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span>
|
||||
</span><span id="__span-0-5"><a id="__codelineno-0-5" name="__codelineno-0-5" href="#__codelineno-0-5"></a> <span class="n">proxy_download</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>
|
||||
</span><span id="__span-0-6"><a id="__codelineno-0-6" name="__codelineno-0-6" href="#__codelineno-0-6"></a><span class="p">)</span>
|
||||
</span></code></pre></div>
|
||||
|
||||
<div class="doc doc-contents ">
|
||||
@@ -6566,9 +6571,10 @@ than one DRM system but only one of them licenses this track.</p>
|
||||
</span><span id="__span-0-6"><a id="__codelineno-0-6" name="__codelineno-0-6" href="#__codelineno-0-6"></a> <span class="o">*</span><span class="p">,</span>
|
||||
</span><span id="__span-0-7"><a id="__codelineno-0-7" name="__codelineno-0-7" href="#__codelineno-0-7"></a> <span class="n">cdm</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>
|
||||
</span><span id="__span-0-8"><a id="__codelineno-0-8" name="__codelineno-0-8" href="#__codelineno-0-8"></a> <span class="n">no_proxy_download</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span>
|
||||
</span><span id="__span-0-9"><a id="__codelineno-0-9" name="__codelineno-0-9" href="#__codelineno-0-9"></a> <span class="n">adaptive_workers</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span>
|
||||
</span><span id="__span-0-10"><a id="__codelineno-0-10" name="__codelineno-0-10" href="#__codelineno-0-10"></a> <span class="n">download_processes</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span>
|
||||
</span><span id="__span-0-11"><a id="__codelineno-0-11" name="__codelineno-0-11" href="#__codelineno-0-11"></a><span class="p">)</span>
|
||||
</span><span id="__span-0-9"><a id="__codelineno-0-9" name="__codelineno-0-9" href="#__codelineno-0-9"></a> <span class="n">proxy_download</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>
|
||||
</span><span id="__span-0-10"><a id="__codelineno-0-10" name="__codelineno-0-10" href="#__codelineno-0-10"></a> <span class="n">adaptive_workers</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span>
|
||||
</span><span id="__span-0-11"><a id="__codelineno-0-11" name="__codelineno-0-11" href="#__codelineno-0-11"></a> <span class="n">download_processes</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span>
|
||||
</span><span id="__span-0-12"><a id="__codelineno-0-12" name="__codelineno-0-12" href="#__codelineno-0-12"></a><span class="p">)</span>
|
||||
</span></code></pre></div>
|
||||
|
||||
<div class="doc doc-contents ">
|
||||
|
||||
@@ -2320,6 +2320,14 @@ default. In other words, config only fills in options you did not set on the com
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title"><code>no</code> and <code>yes</code> are language tags</p>
|
||||
<p>YAML reads a bare <code>no</code> as <code>false</code> and a bare <code>yes</code> as <code>true</code>. unshackle puts both back to
|
||||
the tags <code>no</code> (Norwegian) and <code>yes</code> (Nyankpa) in every config key that takes a language: <code>lang</code>,
|
||||
<code>v_lang</code>, <code>a_lang</code>, <code>s_lang</code>, <code>forced_s_lang</code>, <code>require_audio</code>, <code>require_video</code>,
|
||||
<code>require_subs</code>, <a href="#subtitle"><code>language_priority</code></a>, <a href="#muxing"><code>muxing.default_language</code></a> and
|
||||
the <a href="#language_tags"><code>language_tags</code></a> rules. Quotes (<code>lang: "no"</code>) work as well.</p>
|
||||
</div>
|
||||
<div class="language-yaml highlight"><span class="filename">Global download defaults</span><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">dl</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="nt">lang</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="nv">en</span><span class="p p-Indicator">]</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="nt">quality</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="nv">1080</span><span class="p p-Indicator">]</span>
|
||||
@@ -2630,7 +2638,7 @@ bitrate alone, with those same Atmos/descriptive rules still applied.</p>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code>audio</code></td>
|
||||
<td>Matches against the audio track languages.</td>
|
||||
<td>At least one audio language matches.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>subs_contain</code></td>
|
||||
@@ -2638,16 +2646,41 @@ bitrate alone, with those same Atmos/descriptive rules still applied.</p>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>subs_contain_all</code></td>
|
||||
<td>Every listed language must be present (scalar or list).</td>
|
||||
<td>Every listed language must be present.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>dual</code> / <code>multi</code> / <code>dubbed</code></td>
|
||||
<td><code>true</code> matches when that filename variable is set, <code>false</code> when it is not.</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p>Each language condition takes one language tag or a list of them. A list matches when <strong>any</strong>
|
||||
entry matches, except <code>subs_contain_all</code>, which needs them all. An entry that is not a valid
|
||||
language tag (for example <code>japanese</code>) never matches. <code>dual</code>, <code>multi</code> and <code>dubbed</code> take a bare
|
||||
<code>true</code> or <code>false</code>, not a quoted string. unshackle skips a rule with a condition name it does
|
||||
not know, or with any other value in a boolean condition. It logs a warning in each of these
|
||||
cases and tries the next rule.</p>
|
||||
<p><code>dual</code>, <code>multi</code> and <code>dubbed</code> carry the same meaning as the
|
||||
<a href="#dual_multi_mode">filename variables of those names</a>. Pair one with a language to name a
|
||||
release yourself, in place of the fixed <code>DUAL</code>, <code>MULTi</code> and <code>DUBBED</code> text. A rule that names
|
||||
<code>dubbed: true</code> and a language tags a localized dub without tagging a native release the same way.</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">language_tags</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">rules</span><span class="p">:</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="p p-Indicator">-</span><span class="w"> </span><span class="nt">audio</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="nv">ja</span><span class="p p-Indicator">]</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="nt">subs_contain</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="nv">en</span><span class="p p-Indicator">]</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="nt">tag</span><span class="p">:</span><span class="w"> </span><span class="s">"SUBBED"</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="p p-Indicator">-</span><span class="w"> </span><span class="nt">audio</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">th</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="nt">dubbed</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
|
||||
</span><span id="__span-9-8"><a id="__codelineno-9-8" name="__codelineno-9-8" href="#__codelineno-9-8"></a><span class="w"> </span><span class="nt">tag</span><span class="p">:</span><span class="w"> </span><span class="s">"THAIDUB"</span>
|
||||
</span><span id="__span-9-9"><a id="__codelineno-9-9" name="__codelineno-9-9" href="#__codelineno-9-9"></a><span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">audio</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">th</span>
|
||||
</span><span id="__span-9-10"><a id="__codelineno-9-10" name="__codelineno-9-10" href="#__codelineno-9-10"></a><span class="w"> </span><span class="nt">dual</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
|
||||
</span><span id="__span-9-11"><a id="__codelineno-9-11" name="__codelineno-9-11" href="#__codelineno-9-11"></a><span class="w"> </span><span class="nt">tag</span><span class="p">:</span><span class="w"> </span><span class="s">"THAIDUAL"</span>
|
||||
</span></code></pre></div>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Put <code>{lang_tag}</code> where you want the name</p>
|
||||
<p>These rules fill <code>{lang_tag}</code>. To use your own name in place of the fixed text, keep
|
||||
<code>{lang_tag?}</code> in the template and leave out <code>{dual?}</code>, <code>{multi?}</code> and <code>{dubbed?}</code>.</p>
|
||||
</div>
|
||||
<h2 id="dual_multi_mode"><code>dual_multi_mode</code><a class="headerlink" href="#dual_multi_mode" title="Permanent link">¶</a></h2>
|
||||
<ul>
|
||||
<li><strong>Type:</strong> <code>str</code> · <strong>Default:</strong> <code>strict</code></li>
|
||||
|
||||
@@ -2246,7 +2246,7 @@ is the <a href="../../../dev/rest-api/">REST API</a> section. These are the conf
|
||||
<td><code>session_ttl</code></td>
|
||||
<td>int (s)</td>
|
||||
<td><code>300</code></td>
|
||||
<td>Lifetime of an interactive auth session.</td>
|
||||
<td>Seconds a remote session can stay idle before it expires. A remote client sends keep-alive requests to its remote session during a download, so the remote session does not expire during a long download.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>max_sessions</code></td>
|
||||
@@ -2270,7 +2270,7 @@ is the <a href="../../../dev/rest-api/">REST API</a> section. These are the conf
|
||||
<td><code>services_refresh_interval</code></td>
|
||||
<td>int (s)</td>
|
||||
<td><code>0</code></td>
|
||||
<td>How often the server pulls the git-backed service repositories in <code>directories.services</code> and hot-reloads the services that changed. <code>0</code> turns it off. A service with a running or queued job swaps to the new code as soon as its last job finishes.</td>
|
||||
<td>How often the server pulls the git-backed service repositories in <code>directories.services</code> and hot-reloads the services that changed. <code>0</code> turns it off. A service with a running or queued job, or a live remote session, swaps to the new code as soon as its last job and session finish.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>global_speed_limit</code></td>
|
||||
|
||||
@@ -2094,6 +2094,15 @@ name) and a <code>name</code>, plus backend-specific keys.</p>
|
||||
stores it.</li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Bad content keys</p>
|
||||
<p>A content key from a vault is proven by a short FFmpeg decode of the decrypted output.
|
||||
A content key that fails the decode is written to the <code>bad_keys</code> table of every <code>SQLite</code>
|
||||
vault with the name of the vault that supplied it, and every vault lookup skips a flagged
|
||||
pair from then on. Only the <code>SQLite</code> backend stores flags. A <code>serve</code> instance with
|
||||
<code>server_cdm</code> flags a pair the same way when a remote client reports it, so a server whose
|
||||
<code>key_vaults</code> hold no <code>SQLite</code> entry cannot remember a bad content key.</p>
|
||||
</div>
|
||||
<h2 id="vault_timeout"><code>vault_timeout</code><a class="headerlink" href="#vault_timeout" title="Permanent link">¶</a></h2>
|
||||
<ul>
|
||||
<li><strong>Type:</strong> <code>float</code> · <strong>Default:</strong> <code>10.0</code></li>
|
||||
|
||||
File diff suppressed because one or more lines are too long
+38
-38
@@ -2,154 +2,154 @@
|
||||
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
|
||||
<url>
|
||||
<loc>https://docs.unshackle.dev/</loc>
|
||||
<lastmod>2026-09-10</lastmod>
|
||||
<lastmod>2026-09-17</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://docs.unshackle.dev/dev/creating-a-service/</loc>
|
||||
<lastmod>2026-09-10</lastmod>
|
||||
<lastmod>2026-09-17</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://docs.unshackle.dev/dev/service-architecture/</loc>
|
||||
<lastmod>2026-09-10</lastmod>
|
||||
<lastmod>2026-09-17</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://docs.unshackle.dev/dev/rest-api/</loc>
|
||||
<lastmod>2026-09-10</lastmod>
|
||||
<lastmod>2026-09-17</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://docs.unshackle.dev/dev/rest-api/authentication/</loc>
|
||||
<lastmod>2026-09-10</lastmod>
|
||||
<lastmod>2026-09-17</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://docs.unshackle.dev/dev/rest-api/dashboard/</loc>
|
||||
<lastmod>2026-09-10</lastmod>
|
||||
<lastmod>2026-09-17</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://docs.unshackle.dev/dev/rest-api/endpoints/</loc>
|
||||
<lastmod>2026-09-10</lastmod>
|
||||
<lastmod>2026-09-17</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://docs.unshackle.dev/dev/rest-api/errors/</loc>
|
||||
<lastmod>2026-09-10</lastmod>
|
||||
<lastmod>2026-09-17</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://docs.unshackle.dev/dev/rest-api/job-lifecycle/</loc>
|
||||
<lastmod>2026-09-10</lastmod>
|
||||
<lastmod>2026-09-17</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://docs.unshackle.dev/dev/rest-api/quickstart/</loc>
|
||||
<lastmod>2026-09-10</lastmod>
|
||||
<lastmod>2026-09-17</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://docs.unshackle.dev/dev/rest-api/remote-sessions/</loc>
|
||||
<lastmod>2026-09-10</lastmod>
|
||||
<lastmod>2026-09-17</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://docs.unshackle.dev/getting-started/configuration-file/</loc>
|
||||
<lastmod>2026-09-10</lastmod>
|
||||
<lastmod>2026-09-17</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://docs.unshackle.dev/getting-started/installation/</loc>
|
||||
<lastmod>2026-09-10</lastmod>
|
||||
<lastmod>2026-09-17</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://docs.unshackle.dev/getting-started/quickstart/</loc>
|
||||
<lastmod>2026-09-10</lastmod>
|
||||
<lastmod>2026-09-17</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://docs.unshackle.dev/guide/cli-reference/</loc>
|
||||
<lastmod>2026-09-10</lastmod>
|
||||
<lastmod>2026-09-17</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://docs.unshackle.dev/guide/downloading/</loc>
|
||||
<lastmod>2026-09-10</lastmod>
|
||||
<lastmod>2026-09-17</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://docs.unshackle.dev/guide/drm-and-cdm/</loc>
|
||||
<lastmod>2026-09-10</lastmod>
|
||||
<lastmod>2026-09-17</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://docs.unshackle.dev/guide/output-and-naming/</loc>
|
||||
<lastmod>2026-09-10</lastmod>
|
||||
<lastmod>2026-09-17</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://docs.unshackle.dev/guide/proxies-and-vpn/</loc>
|
||||
<lastmod>2026-09-10</lastmod>
|
||||
<lastmod>2026-09-17</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://docs.unshackle.dev/guide/subtitles/</loc>
|
||||
<lastmod>2026-09-10</lastmod>
|
||||
<lastmod>2026-09-17</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://docs.unshackle.dev/guide/troubleshooting/</loc>
|
||||
<lastmod>2026-09-10</lastmod>
|
||||
<lastmod>2026-09-17</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://docs.unshackle.dev/guide/vaults/</loc>
|
||||
<lastmod>2026-09-10</lastmod>
|
||||
<lastmod>2026-09-17</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://docs.unshackle.dev/reference/api/config/</loc>
|
||||
<lastmod>2026-09-10</lastmod>
|
||||
<lastmod>2026-09-17</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://docs.unshackle.dev/reference/api/drm/</loc>
|
||||
<lastmod>2026-09-10</lastmod>
|
||||
<lastmod>2026-09-17</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://docs.unshackle.dev/reference/api/service/</loc>
|
||||
<lastmod>2026-09-10</lastmod>
|
||||
<lastmod>2026-09-17</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://docs.unshackle.dev/reference/api/titles/</loc>
|
||||
<lastmod>2026-09-10</lastmod>
|
||||
<lastmod>2026-09-17</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://docs.unshackle.dev/reference/api/tracks/</loc>
|
||||
<lastmod>2026-09-10</lastmod>
|
||||
<lastmod>2026-09-17</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://docs.unshackle.dev/reference/configuration/</loc>
|
||||
<lastmod>2026-09-10</lastmod>
|
||||
<lastmod>2026-09-17</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://docs.unshackle.dev/reference/configuration/directories/</loc>
|
||||
<lastmod>2026-09-10</lastmod>
|
||||
<lastmod>2026-09-17</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://docs.unshackle.dev/reference/configuration/download/</loc>
|
||||
<lastmod>2026-09-10</lastmod>
|
||||
<lastmod>2026-09-17</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://docs.unshackle.dev/reference/configuration/drm/</loc>
|
||||
<lastmod>2026-09-10</lastmod>
|
||||
<lastmod>2026-09-17</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://docs.unshackle.dev/reference/configuration/example/</loc>
|
||||
<lastmod>2026-09-10</lastmod>
|
||||
<lastmod>2026-09-17</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://docs.unshackle.dev/reference/configuration/misc/</loc>
|
||||
<lastmod>2026-09-10</lastmod>
|
||||
<lastmod>2026-09-17</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://docs.unshackle.dev/reference/configuration/network/</loc>
|
||||
<lastmod>2026-09-10</lastmod>
|
||||
<lastmod>2026-09-17</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://docs.unshackle.dev/reference/configuration/output/</loc>
|
||||
<lastmod>2026-09-10</lastmod>
|
||||
<lastmod>2026-09-17</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://docs.unshackle.dev/reference/configuration/post-scripts/</loc>
|
||||
<lastmod>2026-09-10</lastmod>
|
||||
<lastmod>2026-09-17</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://docs.unshackle.dev/reference/configuration/services/</loc>
|
||||
<lastmod>2026-09-10</lastmod>
|
||||
<lastmod>2026-09-17</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://docs.unshackle.dev/reference/configuration/vaults/</loc>
|
||||
<lastmod>2026-09-10</lastmod>
|
||||
<lastmod>2026-09-17</lastmod>
|
||||
</url>
|
||||
</urlset>
|
||||
Binary file not shown.
Reference in New Issue
Block a user