The manager of the torrent is the bear 🐻, got it? 🥹

torrentManager

🦄 Automagically 🪄 manage your qBittorent client.

torrentManager can be used to automatically perform operations like:

• stop seeding process once download of a specific tag or category has completed
• remove torrents (metadata & files) of a specific tag or category group
• attach a specific TAG to specific torrents (e.g. private trackers)
• apply qBittorrent ratio and seeding-time limits to torrents by tag or tracker

The core has been developed in a quick and easy manner, on purpose to be easily extendible, using the very well documented qBittorrent API.

I am using a simple polling strategy and a local persistent key-value storage mechanism, both of this choices can be easily tweaked or swapped with different components and choices really easily.

Docker

The container expects to load the configuration file from /config/configuration.toml so mount a volume accordingly.

$ docker run -itd \
             --rm \
             -v /path/to/my/configuration/file:/config/file \
             tatoalo/torrent-manager

Docker Compose

version: '3.8'
services:
  torrentmanager:
    image: tatoalo/torrent-manager
    restart: unless-stopped
    volumes:
      - /path/to/my/configuration/file:/config/file

Configuration

The configuration file allows the authentication mechanism towards the qBittorrent instance, download/upload limits, interested categories and their respective save paths (NOT all sections are mandatory).

[qbt]
host = "host"
port = 6942
username = "username"
password = "password"

# B/s
[qbt_config]
dl_limit = -1
up_limit = -1

[qbt_categories]
categories = ["cat", "cat2"]

[targets]
dir_targets = { "cat" = "path", "cat2" = "path" }

[trackers]
trackers_tags = { "tracker_endpoint" = "tag" }

[[share_limits]]
name = "private tracker"
tags = ["tag"]
trackers = ["tracker_endpoint"]
ratio_limit = 2.0
seeding_time_limit = 10080
inactive_seeding_time_limit = -2
share_limit_action = "RemoveWithContent"

Custom Scheduling

The default scheduling mechanism is stored in torrent-manager-cron, although a custom schedule can be introduced in one of two ways:

• Edit torrent-manager-cron accordingly and rebuild the image
• Edit the environment variables directly in the docker run command or docker compose file, namely. It is possible to just customize a single mechanism (launcher or cleaner) or even both in the same context, these are the env variables:
  • LAUNCHER_CRON for when the main launcher is executed
  • CLEANER_CRON for when the cleaning mechanism is executed

Both variables are to be assigned a cron-valid schedule pattern.

Monitoring

Another couple of environment variables can be set in order to monitor the health of the cron jobs, namely:

• HC_UUID_LAUNCHER
• HC_UUID_CLEANER

Their value must be an healthchecks-compatible uuid (or slug). I've been a fan of cronitor but healtchecks's free offering is more convenient in my opinion.

Similarly to the Custom Scheduling, both environment variables can be set at the same time, you can decide to activate only one or not have monitoring in place at all, up to you :)

Tagging Private Trackers

In the configuration.toml file, a section trackers can be specified such as:

[trackers]
trackers_tags = { "tracker_endpoint" = "tag" }

so that if a torrent is found to possess a tracker like tracker.tracker_endpoint.forreal, it will be tagged with tag.

Share Limit Rules

Share limit rules apply qBittorrent's per-torrent seeding limits to torrents matched by tag, tracker, or both.

[[share_limits]]
name = "private tracker"
tags = ["tag"]
trackers = ["tracker_endpoint"]
ratio_limit = 2.0
seeding_time_limit = 10080
inactive_seeding_time_limit = -2
share_limit_action = "RemoveWithContent"

Within one rule, multiple tags are matched as OR conditions and multiple trackers are matched as OR conditions. If both selector groups are present, a torrent must match both groups. Tracker selectors are substring matches against qBittorrent tracker URLs. Rules are applied in file order, so a later matching rule can overwrite values from an earlier matching rule.

Torrents matched by a share limit rule are skipped by torrentManager's automatic pause and cleaner deletion flows. This lets qBittorrent enforce the configured ratio or seed-time rule first. Use share_limit_action = "RemoveWithContent" when the share limit rule should delete the torrent and its files after the limit is reached.

The supported share limit values mirror qBittorrent:

• ratio_limit: max seed ratio; -2 uses the global value and -1 disables the ratio limit.
• seeding_time_limit: minutes to seed; -2 uses the global value and -1 disables the time limit.
• inactive_seeding_time_limit: inactive minutes; -2 uses the global value and -1 disables the inactive time limit.
• share_limit_action: one of Stop, Remove, RemoveWithContent, or EnableSuperSeeding.

License

Copyright 2024 Alessandro Pogliaghi

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.