# Trackers — schema, IP-pinning, ratio notes

Single source of truth for what trackers feed this pipeline, and what their
quirks are. Per-tracker entries get added by the operator; the schema is
below.

## IP-pinning risk

Many private trackers **pin sessions to a single source IP**. Switching
from onyx public IP → Proton exit IP (via gluetun) will trip them: tracker
returns `unauthorized: source IP mismatch` on announce, the torrent stops
announcing → seeding stats halt → ratio decays.

Mitigations, ordered cheapest → most invasive:

1. **Read the tracker's FAQ first.** Most private trackers have a documented
   policy: "1 IP, change requires staff" / "rolling IP allowed, contact us
   after change" / "IP locked to account, no exceptions".
2. **Request an IP update** from staff before migrating that torrent.
   Provide the new Proton exit IP (gluetun reports current exit via
   `docker exec gluetun cat /tmp/gluetun/ip`).
3. **Hot-swap manually:** announce on onyx, immediately re-add on nullstone,
   force-announce. Some trackers' anti-abuse is rate-limited and won't catch
   the swap.
4. **Multiple exit profiles.** Run two gluetun containers with different
   Proton server selections (one for tracker A, one for tracker B). Heavy.

If a tracker rejects all of the above, **leave that torrent on onyx**. The
migration is not all-or-nothing; some seedboxes will live forever on the
old host. Document the exception in the table below.

## Per-tracker schema

Use this table format in this file. **Sort alphabetically by tracker name.**

| Tracker            | URL                          | Type    | IP-Pinning            | Ratio Required | Notes                          |
|--------------------|------------------------------|---------|-----------------------|----------------|--------------------------------|
| _example.tracker_  | https://_example.tracker_/   | private | locked, request swap  | 1.0 over 30d   | Staff respond on IRC in < 24h. |
| _public.example_   | http://_public.example_/     | public  | n/a                   | n/a            | No account, no ratio.          |

(Replace the example rows with real trackers as they are onboarded.)

## Onboarding a new tracker

When adding a new private tracker:

1. Read the tracker's FAQ / rules. Record IP-pinning + ratio policy in the
   table above.
2. Run `scripts/add-tracker.sh <name> <url>` to push it into Prowlarr. The
   script prompts for cookies / API key as needed.
3. Add a row to the per-tracker table above. Commit.
4. Monitor first 24h: check Prowlarr → Indexer → Stats for failed-query rate.
   > 10% failures → recheck the IP-pinning column.

## Public trackers

Public trackers (e.g. open BitTorrent indexers) have no IP-pinning concerns
but generally bad quality + slow speeds. List them sparingly; prefer private
trackers for the long tail of niche media.