mirror of
https://github.com/unshackle-dl/unshackle.git
synced 2026-11-14 21:15:06 +00:00
Deployed d9b2122 with MkDocs version: 1.6.1
This commit is contained in:
@@ -2285,6 +2285,12 @@ is the <a href="../../../dev/rest-api/">REST API</a> section. These are the conf
|
||||
<td>Permit clients to supply credentials per job.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>server_accounts</code></td>
|
||||
<td>dict</td>
|
||||
<td><code>{}</code></td>
|
||||
<td>Services whose remote sessions use the server's own <code>credentials</code> and cookie files instead of the client's (see below).</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>devices</code></td>
|
||||
<td>list</td>
|
||||
<td><em>(auto)</em></td>
|
||||
@@ -2310,6 +2316,47 @@ client configured with <code>server_cdm: true</code> to license with its own loc
|
||||
client that asks anyway gets a <code>FORBIDDEN</code> error. Because a download job always licenses with the server's CDM,
|
||||
an API key without <code>server_cdm</code> for that service also cannot submit or retry <code>/api/download</code>
|
||||
jobs. Keys that have no <code>users</code> entry, such as <code>api_secret</code>, keep server CDM access.</p>
|
||||
<p><code>server_accounts</code> lists, per service, the accounts the server lends to remote sessions. A remote
|
||||
session for a listed service ignores the credentials, cookies, and cache the client sends and
|
||||
uses one of the server's own profiles from <code>credentials</code>. For a service that is not listed the
|
||||
server never uses its own accounts: a client that sends nothing authenticates with nothing.</p>
|
||||
<div class="language-yaml highlight"><pre><span></span><code><span id="__span-2-1"><a id="__codelineno-2-1" name="__codelineno-2-1" href="#__codelineno-2-1"></a><span class="nt">credentials</span><span class="p">:</span>
|
||||
</span><span id="__span-2-2"><a id="__codelineno-2-2" name="__codelineno-2-2" href="#__codelineno-2-2"></a><span class="w"> </span><span class="nt">EXAMPLE1</span><span class="p">:</span>
|
||||
</span><span id="__span-2-3"><a id="__codelineno-2-3" name="__codelineno-2-3" href="#__codelineno-2-3"></a><span class="w"> </span><span class="nt">ca_main</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">user1@example.com:pw1</span>
|
||||
</span><span id="__span-2-4"><a id="__codelineno-2-4" name="__codelineno-2-4" href="#__codelineno-2-4"></a><span class="w"> </span><span class="nt">eu_box</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">user2@example.com:pw2</span>
|
||||
</span><span id="__span-2-5"><a id="__codelineno-2-5" name="__codelineno-2-5" href="#__codelineno-2-5"></a><span class="w"> </span><span class="nt">shared</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">user3@example.com:pw3</span>
|
||||
</span><span id="__span-2-6"><a id="__codelineno-2-6" name="__codelineno-2-6" href="#__codelineno-2-6"></a>
|
||||
</span><span id="__span-2-7"><a id="__codelineno-2-7" name="__codelineno-2-7" href="#__codelineno-2-7"></a><span class="nt">serve</span><span class="p">:</span>
|
||||
</span><span id="__span-2-8"><a id="__codelineno-2-8" name="__codelineno-2-8" href="#__codelineno-2-8"></a><span class="w"> </span><span class="nt">server_accounts</span><span class="p">:</span>
|
||||
</span><span id="__span-2-9"><a id="__codelineno-2-9" name="__codelineno-2-9" href="#__codelineno-2-9"></a><span class="w"> </span><span class="nt">EXAMPLE1</span><span class="p">:</span>
|
||||
</span><span id="__span-2-10"><a id="__codelineno-2-10" name="__codelineno-2-10" href="#__codelineno-2-10"></a><span class="w"> </span><span class="nt">ca_main</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">ca</span><span class="w"> </span><span class="c1"># one country</span>
|
||||
</span><span id="__span-2-11"><a id="__codelineno-2-11" name="__codelineno-2-11" href="#__codelineno-2-11"></a><span class="w"> </span><span class="nt">eu_box</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="nv">gb</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="nv">fr</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="nv">de</span><span class="p p-Indicator">]</span><span class="w"> </span><span class="c1"># a list of countries</span>
|
||||
</span><span id="__span-2-12"><a id="__codelineno-2-12" name="__codelineno-2-12" href="#__codelineno-2-12"></a><span class="w"> </span><span class="nt">shared</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">global</span><span class="w"> </span><span class="c1"># any region</span>
|
||||
</span><span id="__span-2-13"><a id="__codelineno-2-13" name="__codelineno-2-13" href="#__codelineno-2-13"></a><span class="w"> </span><span class="nt">EXAMPLE2</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span><span class="w"> </span><span class="c1"># every profile (or the single credential), any region</span>
|
||||
</span></code></pre></div>
|
||||
<p>Each entry under a service names a profile from <code>credentials</code>, or a cookie file
|
||||
<code>cookies/<TAG>/<profile>.txt</code> for a service that has no credentials. Its value is the region or
|
||||
regions that account works in: a two-letter country code, a list of them, or <code>global</code>. Quote
|
||||
<code>no</code> (Norway), because YAML reads the bare word as <code>false</code>.</p>
|
||||
<p>The region of a remote session is the country the client asked for with <code>--proxy</code> (<code>ca</code>, <code>ca1</code>,
|
||||
<code>provider:ca</code>), the server's own region with <code>--no-proxy</code>, or the client's own region otherwise.
|
||||
A full proxy URI carries no country, so with one only a <code>global</code> account matches. The server
|
||||
picks the profiles that cover that region (or are <code>global</code>) and rotates through them
|
||||
round-robin, one account per remote session. With no matching account it rejects the remote
|
||||
session. These services ignore the client's <code>-p/--profile</code>.</p>
|
||||
<p>Cookies come only from the profile's own file (<code>cookies/EXAMPLE1/ca_main.txt</code>; the server does
|
||||
not read a bare <code>cookies/EXAMPLE1.txt</code>), and each account keeps its own persistent cache under
|
||||
<code>cache/_accounts/EXAMPLE1/<profile>/</code>, so refreshed tokens survive the remote session but never
|
||||
cross accounts. <code>serve</code> refuses to start when a listed profile has neither an entry under
|
||||
<code>credentials</code> nor a cookie file.
|
||||
<code>/api/search</code>, <code>/api/list-titles</code> and <code>/api/list-tracks</code> use the same pool, matched on the
|
||||
client's reported region, and return <code>FORBIDDEN</code> to an API key without the opt-in. Rotation is
|
||||
per process and does not track which accounts are in use, so concurrent remote sessions can
|
||||
share one account.</p>
|
||||
<p>A <code>users</code> entry opts in to those accounts with <code>server_accounts: true</code> (every listed service)
|
||||
or a list of service tags. It is off unless set: an API key without it authenticates with the
|
||||
credentials the client sends, as for any other service, and <code>/api/services</code> does not advertise
|
||||
the server's accounts to it. API keys with no <code>users</code> entry, such as <code>api_secret</code>, keep access.</p>
|
||||
<p><code>server_proxy</code> decides whether that API key may use the proxy providers the server has
|
||||
configured. There is no implicit access: only the boolean <code>true</code> on the API key's <code>users</code> entry
|
||||
grants it, and an API key without a <code>users</code> entry has no access either. Without the opt-in the
|
||||
@@ -2320,23 +2367,24 @@ full proxy URI, or <code>no_proxy</code> to accept the server's own connection.
|
||||
to let that API key send a country code or a <code>provider:country</code> value, and to let the server
|
||||
pick a proxy for the client's region and for a service geofence. The client reports its own
|
||||
region; a client that reports none is not blocked.</p>
|
||||
<div class="language-yaml highlight"><pre><span></span><code><span id="__span-2-1"><a id="__codelineno-2-1" name="__codelineno-2-1" href="#__codelineno-2-1"></a><span class="nt">serve</span><span class="p">:</span>
|
||||
</span><span id="__span-2-2"><a id="__codelineno-2-2" name="__codelineno-2-2" href="#__codelineno-2-2"></a><span class="w"> </span><span class="nt">api_secret</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">change-me</span>
|
||||
</span><span id="__span-2-3"><a id="__codelineno-2-3" name="__codelineno-2-3" href="#__codelineno-2-3"></a><span class="w"> </span><span class="nt">remote_only</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
|
||||
</span><span id="__span-2-4"><a id="__codelineno-2-4" name="__codelineno-2-4" href="#__codelineno-2-4"></a><span class="w"> </span><span class="nt">services</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="nv">EXAMPLE1</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="nv">EXAMPLE2</span><span class="p p-Indicator">]</span>
|
||||
</span><span id="__span-2-5"><a id="__codelineno-2-5" name="__codelineno-2-5" href="#__codelineno-2-5"></a><span class="w"> </span><span class="nt">services_refresh_interval</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">3600</span><span class="w"> </span><span class="c1"># pull the service repositories hourly and reload what changed</span>
|
||||
</span><span id="__span-2-6"><a id="__codelineno-2-6" name="__codelineno-2-6" href="#__codelineno-2-6"></a><span class="w"> </span><span class="c1"># server-wide download defaults (same keys as the `dl:` block)</span>
|
||||
</span><span id="__span-2-7"><a id="__codelineno-2-7" name="__codelineno-2-7" href="#__codelineno-2-7"></a><span class="w"> </span><span class="nt">downloads</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">3</span>
|
||||
</span><span id="__span-2-8"><a id="__codelineno-2-8" name="__codelineno-2-8" href="#__codelineno-2-8"></a><span class="w"> </span><span class="nt">best_available</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
|
||||
</span><span id="__span-2-9"><a id="__codelineno-2-9" name="__codelineno-2-9" href="#__codelineno-2-9"></a><span class="w"> </span><span class="nt">users</span><span class="p">:</span>
|
||||
</span><span id="__span-2-10"><a id="__codelineno-2-10" name="__codelineno-2-10" href="#__codelineno-2-10"></a><span class="w"> </span><span class="nt">a1b2c3d4</span><span class="p">:</span><span class="w"> </span><span class="c1"># this user's API key</span>
|
||||
</span><span id="__span-2-11"><a id="__codelineno-2-11" name="__codelineno-2-11" href="#__codelineno-2-11"></a><span class="w"> </span><span class="nt">services</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="nv">EXAMPLE1</span><span class="p p-Indicator">]</span><span class="w"> </span><span class="c1"># may only use EXAMPLE1</span>
|
||||
</span><span id="__span-2-12"><a id="__codelineno-2-12" name="__codelineno-2-12" href="#__codelineno-2-12"></a><span class="w"> </span><span class="nt">e5f6a7b8</span><span class="p">:</span>
|
||||
</span><span id="__span-2-13"><a id="__codelineno-2-13" name="__codelineno-2-13" href="#__codelineno-2-13"></a><span class="w"> </span><span class="nt">server_cdm</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span><span class="w"> </span><span class="c1"># this key may have the server do the licensing</span>
|
||||
</span><span id="__span-2-14"><a id="__codelineno-2-14" name="__codelineno-2-14" href="#__codelineno-2-14"></a><span class="w"> </span><span class="nt">c9d0e1f2</span><span class="p">:</span>
|
||||
</span><span id="__span-2-15"><a id="__codelineno-2-15" name="__codelineno-2-15" href="#__codelineno-2-15"></a><span class="w"> </span><span class="nt">services</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="nv">EXAMPLE1</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="nv">EXAMPLE2</span><span class="p p-Indicator">]</span>
|
||||
</span><span id="__span-2-16"><a id="__codelineno-2-16" name="__codelineno-2-16" href="#__codelineno-2-16"></a><span class="w"> </span><span class="nt">server_cdm</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="nv">EXAMPLE1</span><span class="p p-Indicator">]</span><span class="w"> </span><span class="c1"># the server licenses only EXAMPLE1; EXAMPLE2 needs a local CDM</span>
|
||||
</span><span id="__span-2-17"><a id="__codelineno-2-17" name="__codelineno-2-17" href="#__codelineno-2-17"></a><span class="w"> </span><span class="nt">server_proxy</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span><span class="w"> </span><span class="c1"># this key may also use the server's proxy providers</span>
|
||||
<div class="language-yaml highlight"><pre><span></span><code><span id="__span-3-1"><a id="__codelineno-3-1" name="__codelineno-3-1" href="#__codelineno-3-1"></a><span class="nt">serve</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="w"> </span><span class="nt">api_secret</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">change-me</span>
|
||||
</span><span id="__span-3-3"><a id="__codelineno-3-3" name="__codelineno-3-3" href="#__codelineno-3-3"></a><span class="w"> </span><span class="nt">remote_only</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
|
||||
</span><span id="__span-3-4"><a id="__codelineno-3-4" name="__codelineno-3-4" href="#__codelineno-3-4"></a><span class="w"> </span><span class="nt">services</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="nv">EXAMPLE1</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="nv">EXAMPLE2</span><span class="p p-Indicator">]</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">services_refresh_interval</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">3600</span><span class="w"> </span><span class="c1"># pull the service repositories hourly and reload what changed</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="c1"># server-wide download defaults (same keys as the `dl:` block)</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">downloads</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">3</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">best_available</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</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">users</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">a1b2c3d4</span><span class="p">:</span><span class="w"> </span><span class="c1"># this user's API key</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">services</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="nv">EXAMPLE1</span><span class="p p-Indicator">]</span><span class="w"> </span><span class="c1"># may only use EXAMPLE1</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="nt">e5f6a7b8</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">server_cdm</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span><span class="w"> </span><span class="c1"># this key may have the server do the licensing</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">c9d0e1f2</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">services</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="nv">EXAMPLE1</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="nv">EXAMPLE2</span><span class="p p-Indicator">]</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">server_cdm</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="nv">EXAMPLE1</span><span class="p p-Indicator">]</span><span class="w"> </span><span class="c1"># the server licenses only EXAMPLE1; EXAMPLE2 needs a local CDM</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">server_accounts</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="nv">EXAMPLE1</span><span class="p p-Indicator">]</span><span class="w"> </span><span class="c1"># may authenticate EXAMPLE1 with one of the server's own accounts</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">server_proxy</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span><span class="w"> </span><span class="c1"># this key may also use the server's proxy providers</span>
|
||||
</span></code></pre></div>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title"><code>dl</code> keys inside <code>serve</code></p>
|
||||
|
||||
Reference in New Issue
Block a user