docs(arr-chain): Prowlarr feed contract cracked, qB PBKDF2 persistence recipe, chain proof

2026-08-30 00:38:09 -07:00
1 parent a04c9d7d02
commit 3626c7f40d
@@ -1,6 +1,8 @@
 # Prowlarr

-Prowlarr is the indexer management layer for the *arr stack. It aggregates indexers (torrent and Usenet) and exposes a unified API that Sonarr, Radarr, Lidarr, and Readarr consume.
+Prowlarr is the indexer management layer for the *arr stack. It hosts the
+indexer definitions and exposes them as Torznab feeds and downloads;
+Sonarr, Radarr, Lidarr, and Readarr query those feeds and receive results.

 **Host:** Dankserver — **Hostname:** `prowlarr.dankserver.local` — **Docs:** https://wiki.servarr.com/prowlarr

@@ -11,14 +13,35 @@ Prowlarr is the indexer management layer for the *arr stack. It aggregates index
 | Image | `lscr.io/linuxserver/prowlarr:latest` |
 | Port | 9696 (host) → 9696 (container) |
 | Min RAM | 256 MB |
-| Auth | API key (Settings → General) |
+| Auth | Forms (web UI) + API key (`/api/v1/...` and feed routes) |

-## Configuration
+## Live wiring (verified end-to-end 2026-08-30)

-1. Add indexers: Settings → Indexers → Add.
-2. Test each indexer with the **Test** button.
-3. Assign tags (e.g., `movies`, `tv`, `music`) to indexers for routing.
-4. Add download client: Settings → Download Clients → Add qBittorrent.
+Indexer queries flow **through** Prowlarr; a grab hands off to the querying
+app's own qBittorrent download client. Feeds are per-indexer:
+
+```
+http://prowlarr:9696/{indexerId}/api?apikey={GLOBAL_KEY}&t=caps|search|tvsearch|movie|music|book&...
+http://prowlarr:9696/{indexerId}/download?link=...&file=...   (torrent handoff)
+```
+
+| App | Indexer row | Prowlarr id | Categories | Status |
+|---|---|---|---|---|
+| Radarr | Prowlarr-YTS | 7 | [2000] | ✅ grabbed + imported 2160p Dark Knight 2026-08-30 |
+| Sonarr | Prowlarr-Nyaa | 4 | [5000] | ✅ connection validated (202) |
+| Lidarr | Prowlarr-Nyaa | 4 | [3000] | ✅ connection validated (202) |
+| Readarr | Prowlarr-Byrutor | 3 | [7000] | indexer valid; download client parked |
+
+The global API key is in `config.xml` (`<ApiKey>`); per-application keys are
+only used by Prowlarr's own sync calls, NOT by the feeds. The arr download
+clients authenticate to qBittorrent with the permanent WebUI password stored
+in `/home/dank/.qbpass` (mode 600) on Dankserver.
+
+**Readarr caveat:** Readarr is abandoned upstream (last release 0.4.x); its
+qBittorrent client cannot authenticate against qB 5 (`Authentication
+failure` on the connection test while Sonarr/Lidarr/Radarr pass with the
+same credentials). The books pipeline is parked pending a Readarr successor;
+the indexer row itself is healthy.

 ## Docker Compose

@@ -40,11 +63,38 @@ prowlarr:
  networks: [appnet]
 ```

-## Gotchas
+## Gotchas (all verified live 2026-08-30)

- Prowlarr database grows with indexer data. Set up periodic vacuum/backup.
- Indexer sync has a 15–60 minute delay. Search results may lag.
- Rotate API key: update it in every arr app.
+- **The feed route is `/{indexerId}/api`.** There is no `/torznab/{id}/feed`
+  — that path (and any other unmatched path) hits the Forms-auth catch-all
+  and gets `302 → /login?returnUrl=…`. An arr following the redirect parses
+  the login HTML and fails with a cryptic
+  `'/' is an unexpected token … Line 54` XML error that looks like an auth
+  problem. It is a path typo. Source: `NewznabController`
+  (`[HttpGet("{id:int}/api")]` + absolute
+  `/api/v1/indexer/{id}/newznab`).
+- **The arr's Torznab joiner is `TrimEnd(baseUrl,'/') + apiPath` with NO
+  separator.** `baseUrl="…/7/" + apiPath="api"` silently becomes `…/7api`.
+  Either keep the leading slash on `apiPath` (`"/api"`) or end the baseUrl
+  with `/api`.
+- Categories in the indexer row must be a subset of what the feed's `caps`
+  advertises; extras log "does not support the following categories" and
+  some feeds reject them.
+- The v1 API collection is `/api/v1/applications` (not `/api/v1/app`);
+  GET responses carry `fields: []` — real settings values live in
+  `prowlarr.db` → `Applications.Settings` JSON (read-only inspection).
+- Instance name/`InstanceName=Prowlarr` in `config.xml` does NOT prefix the
+  API/feed routes on this build (they answer at root; the `/Prowlarr/...`
+  prefix 302s to the SPA).
+- **Application auto-sync cannot manage these rows** (they carry
+  `SyncLevel=2`): `POST /api/v1/applications/test` fails with
+  `Unable to cast object of type 'NzbDrone.Core.Thing…'` — Prowlarr v1
+  cannot deserialize Radarr 6.3's newer response types. The manual Torznab
+  rows above are therefore the real integration; sync neither duplicates
+  nor clobbers them.
+- Prowlarr runs `AuthenticationMethod=Forms` + `AuthenticationRequired=Enabled`
+  healthily — the DryIoc crash combo was `None`+`Enabled` only (see
+  [[radarr]] auth notes).

 ## See Also