initial commit

2026-07-12 10:17:17 -04:00
commit dab5a4ebc6
1424 changed files with 330463 additions and 0 deletions
@@ -0,0 +1,108 @@
+# MAM (MyAnonaMouse) Troubleshooting Reference
+
+## Tracker Error: "Unrecognized host/PassKey"
+
+**Full error from MAM's tracker detail page:**
+```
+ip          port   agent                 error
+181.214.x.x 36590  -qB5230- / 5.2.3     Unrecognized host/PassKey. (181.214.x.x)
+```
+
+**Root cause:** Browser IP ≠ torrent client IP. MAM compares the IP you're browsing
+from against the IP your torrent client is announcing from. When they don't match
+(e.g., browser on home connection, torrent client on VPN), the passkey is rejected
+even though the passkey itself and the client version are valid.
+
+**MAM FAQ reference:**
+> *"If you are running your client over a VPN, but not your browser (or browser is
+> on a different vpn tunnel), such as a docker container that also runs the vpn,
+> you'll first need to be approved to use a VPN by staff (per rule 1.2). Then
+> you'll want to use the Dynamic Seedbox endpoint to manage the client on a
+> non-matching IP."*
+
+**Resolution:**
+1. Get staff approval via MAM ticket system
+2. Set up [Mousehole](https://github.com/t-mart/mousehole) to call the Dynamic
+   Seedbox API: `https://www.myanonamouse.net/api/endpoint.php/3/json/dynamicSeedbox.php`
+
+## Tracker Error: "Non-Whitelisted client or version"
+
+**Bencoded tracker response:**
+```
+d8:intervali86400e12:min intervali86400e8:retry ini86400e14:failure reason58:Non-Whitelisted client or version https://s.mrd.ninja/CLNTe
+```
+
+**Check the allowed clients page:** https://s.mrd.ninja/CLNTe
+
+**qBittorrent status on MAM:**
+- Allowed: from 5.0.1 to latest 5.2.x line (confirmed as of 2026-07-09)
+- qBittorrent Anonymous Mode IS rejected by MAM
+- Peer ID format: `-qB5230-` for 5.2.3 on non-Windows
+- User-agent: `qBittorrent/5.2.3`
+
+**Known caveat:** The tracker-level whitelist filter may lag behind the web page.
+If a new version is on the web whitelist but still getting rejected, there may be
+a propagation delay.
+
+## Fastresume Fields (via `strings`)
+
+Key fields in `.fastresume` files that matter for troubleshooting:
+
+| Field | Meaning |
+|---|---|
+| `paused` | 0 = active, 1 = paused |
+| `disable_dht` | 0 = DHT enabled (should be 1 for private trackers) |
+| `num_complete` | seeders count, 16777215 = sentinel (unknown) |
+| `num_incomplete` | leechers count, 16777215 = sentinel (unknown) |
+| `total_downloaded` | bytes downloaded so far |
+| `active_time` | seconds the torrent has been active |
+| `last_seen_complete` | 0 = never seen a complete copy |
+| `last_download` | 0 = no downloads |
+
+Ben code sentinel value 16777215 (0xFFFFFF) means "no data" — the tracker hasn't
+returned peer information.
+
+## Dynamic Seedbox API
+
+- **Endpoint:** `https://www.myanonamouse.net/api/endpoint.php/3/json/dynamicSeedbox.php`
+- **Requires:** Valid MAM session cookie
+- **Purpose:** Registers the current IP of the calling client as an authorized
+  seedbox IP for the user's account
+- **Frequency:** Called periodically by Mousehole (handled automatically once
+  configured)
+
+### Docker Compose Patterns
+
+### Adding Mousehole as a sidecar to existing gluetun + qBittorrent
+
+Required changes to an existing docker-compose.yml:
+
+1. **Gluetun ports:** add `- 127.0.0.1:5010:5010` (or `- 5010:5010` for LAN/KasmVNC access)
+2. **Gluetun environment:** add `,5010` to `FIREWALL_VPN_INPUT_PORTS`
+3. **New service:** add the mousehole service with `network_mode: "service:gluetun"`
+4. **New volume:** add a `mousehole:` volume for cookie persistence
+
+The mousehole service does NOT need to communicate with qBittorrent — it only
+talks to the MAM API. It shares gluetun's network stack so outbound traffic goes
+through the VPN tunnel.
+
+### Docker Port Binding
+
+When `docker compose restart` doesn't pick up compose file changes:
+
+```
+# This restarts with OLD config:
+docker compose restart gluetun
+
+# This recreates with NEW config:
+docker compose up -d gluetun
+```
+
+To verify what ports are actually bound:
+```
+docker port gluetun
+```
+
+`127.0.0.1:5010` binding means host-only. If accessing from KasmVNC or another
+Docker container, the port must bind to 0.0.0.0 (specify just `5010:5010` in
+compose without an IP prefix).