Mousehole, a Seedbox IP Updater for MAM

A background service to update a seedbox IP for MAM and web app to manage it.

This can be helpful if you are using a host/VPN/seedbox to seed and its IP address is not stable.

Features:

• Background service that automatically keeps MAM up to date with your host's IP
• Frontend website to manage the service
• API for programmatic access

Getting Started

To use Mousehole, you need to:

1. Run the service
2. Set your MAM cookie

Step 1: Run the service

Docker Compose (recommended)

Starter Docker Compose examples:

• ⭐ Gluetun + qBittorrent
• Wireguard + qBittorrent
• hotio/qBittorrent
• binhex/arch-qbittorrentvpn
• Non-VPN Example

Any Docker Compose setup can be adapted to include Mousehole as a sidecar.

Unraid

See the Unraid Installation Guide for instructions.

(Mousehole has no affiliated app in the Community Apps catalog of Unraid.)

From Source

Mousehole runs on Bun. After installing bun and cloning the repository, run:

cd /path/to/mousehole
bun install
bun run build
bun run start  # See environment variables section below

Step 2: Set Your MAM Cookie

Navigate to the Mousehole web UI at http://localhost:5010 and paste in your MAM cookie. See Getting Your Cookie Value for a full walkthrough of how to obtain the cookie from MAM.

Troubleshooting

Despite following the above steps, things can still go wrong that cannot be fixed automatically.

• For MAM-specific errors (ASN mismatch or Last Change Too Recent), see the MAM error documentation.
• For network errors, see the network troubleshooting guide.
• For errors related to Host and Origin headers, see the security guide.

Security

Mousehole has security features to protect the cookie credential. Most are enabled by default. If you are running Mousehole on a custom domain or through a proxy, the defaults will not be sufficient. See the security guide for common setups and detailed information.

Docker Images

Mousehole publishes Alpine-based images for amd64 and arm64 to Docker Hub.

Tags

Several tags are published throughout the lifecycle of the project:

• Released SemVer versions (0, 0.1, 0.1.11, etc)
• latest, the latest release
• edge, the tip of master branch
• Pull requests targeting master for testing, tagged as pr-<number>

Healthcheck

The Dockerfile includes a default healthcheck that hits the http://localhost:5010/health endpoint (see API Documentation). A 200 status code indicates the service is live, and therefore, it is suitable for use in container orchestration.

If you change the port on which Mousehole listens with the MOUSEHOLE_PORT environment variable, make sure to override the healthcheck command accordingly.

How It Works

On a schedule, Mousehole contacts MAM. If Mousehole has your cookie, it makes a request to the dynamic-seedbox API to update your IP with MAM. If without your cookie, Mousehole gets your current IP for reference while you get your cookie.

You can trigger an immediate update from the web UI with Update Now.

Environment Variables

Commonly set

• MOUSEHOLE_AUTH_PASSWORD: Enables browser login via the web UI login page. Set this to a strong password. Supports the _FILE variant. See Authentication.
• TZ: (Default Etc/UTC) The timezone identifier for displaying local times. Use the "TZ identifier" column from this list of tz database time zones for valid values. (Not every city is listed! Use one that follows the same rules as your location.)

When hosting beyond localhost

• MOUSEHOLE_ALLOWED_HOSTS: Comma-separated allowlist of Host header values. Defaults to localhost,127.0.0.1,[::1]. See Host Allowlist.
• MOUSEHOLE_ALLOWED_ORIGINS: Comma-separated allowlist of Origin header values. Defaults to same-origin only. See Origin Allowlist.

Other tuning

• MOUSEHOLE_PORT: (Default 5010) The port on which the HTTP server will listen.
• MOUSEHOLE_LOG_LEVEL: (Default info) Log verbosity. Valid values: error, warn, info, debug.
• MOUSEHOLE_HTTPS_ONLY_COOKIES: (Default false) Set to true to add the Secure flag to session cookies, preventing browsers from sending them over plain HTTP. See HTTPS-Only Cookies.
• MOUSEHOLE_INSECURE_ALLOW_NO_AUTH: Set to true to turn off all authentication. Do not use in mixed-trust environments. Mutually exclusive with MOUSEHOLE_AUTH_PASSWORD and MOUSEHOLE_AUTH_TOKEN; setting it alongside either makes Mousehole refuse to start.
• MOUSEHOLE_UPDATE_INTERVAL_SECONDS: (Default 300 (5 minutes)) The interval in seconds between automatic updates.
• MOUSEHOLE_AUTH_TOKEN: Enables Bearer token authentication for API clients. Only needed if you're writing/integrating code against the API. Clients can send HTTP headers in the format Authorization: Bearer <token> when accessing API endpoints. Supports the _FILE variant. See Authentication.
• MOUSEHOLE_MAM_REQUEST_TIMEOUT_SECONDS: (Default 10) How long to wait for a response from MAM before aborting the request. Can prevent Mousehole from waiting too long in certain situations (e.g. before the VPN is up).
• MOUSEHOLE_SESSION_DURATION_SECONDS: (Default 604800 (1 week)) How long a browser login session remains valid before expiring. See Session Duration.
• MOUSEHOLE_STATE_DIR_PATH: (Default /var/lib/mousehole) The directory where the service will store its internal data.

Docker Secrets

As an alternative to placing a credential in an environment variable, you can specify a file that contains it with the _FILE variant. This enables use of Docker secrets. The contents are whitespace-trimmed, and the _FILE variant takes precedence when both are set. If the file can't be read, Mousehole fails to start.

Supported for MOUSEHOLE_AUTH_PASSWORD and MOUSEHOLE_AUTH_TOKEN:

services:
  mousehole:
    image: tmmrtn/mousehole:latest
    environment:
      MOUSEHOLE_AUTH_PASSWORD_FILE: /run/secrets/mousehole-auth-password
    secrets:
      - mousehole-auth-password

secrets:
  mousehole-auth-password:
    file: mousehole-auth-password.txt

Contributing

Want to contribute, or run Mousehole locally for development? Check out the contribution guidelines.

There is also a contrib directory with community-contributed work, maintained on a best-effort basis.

Links

• Repository
• Docker Hub image
• Forum post

Attribution

• Commissioner, Copyright 2019 The Commissioner Project Authors, licensed under OFL-1.1
• IBM Plex Mono, Copyright 2017 IBM Corp., licensed under OFL-1.1
• Mouse Hole, Sergey Demushkin on the Noun Project, licensed under CC BY 3.0

Support the Project

If my project has helped you out, you can ensure it stays maintained.

• Sponsor me on GitHub
• Send BTC to 3NbDsq9mhLAf7mRQ5UqnC5z1UXS8YGJBok
• Sign up for AirVPN with my referral link

AirVPN

Are you looking for a VPN? I use and recommend AirVPN, which is compatible with Gluetun. (AirVPN did not contact to me to say this, I just like them!)

• Fast servers in many locations
• Diverse payment options
• Port forwards (for other providers, this isn't guaranteed!)
• No rotating exit-IP nonsense, less chance of hitting "Last Change Too Recent" error

If you use my referral link, I get a commission which supports the project.