Config Setup

Overview

The script utilizes a YAML config file to load information to connect to the various APIs you can connect with.

By default, the script looks at /config/config.yml for the Configuration File unless otherwise specified.

A template Configuration File can be found in the repo config/config.yml.sample.

WARNING

As this software is constantly evolving and this wiki might not be up to date the sample shown here might not might not be current. Please refer to the repo for the most current version.

Config File

Config Sample File

List of variables

commands:

This section will ignore any commands that are defined via environment variable or command line and use the ones defined in this yaml file instead. Useful if you want to run qbm with multiple configurations files that execute different commands for each qbt instance.

Variable	Definition	Required
`command`	The command that you want qbm to execute.	❌

qbt:

This section defines your qBittorrent instance.

Variable	Definition	Required
`host`	IP address of your qB installation.	✅
`user`	The user name of your qB's webUI.	❌
`pass`	Thee password of your qB's webUI.	❌

settings:

This section defines any settings defined in the configuration.

Variable	Definition	Required
`force_auto_tmm`	Will force qBittorrent to enable Automatic Torrent Management for each torrent.	❌
`tracker_error_tag`	Define the tag of any torrents that do not have a working tracker. (Used in `--rem-unregistered` and `--tag-tracker-error`)	❌
`ignoreTags_OnUpdate`	When running `--tag-update` function, it will update torrent tags for a given torrent even if the torrent has one or more of the tags defined here.	❌

directory:

This section defines the directories that qbit_manage will be looking into for various parts of the script.

Variable	Definition	Required
`cross_seed`	Output directory of cross-seed, originally the application cross-seed was incapable of injecting cross-seed torrent into qB, this was built to inject them for the application. This is no longer required if you're using injects with that software. However, you can find other uses for this as it is more of a watch directory now.	QBT_CROSS_SEED
`root_dir`	Root downloads directory used to check for orphaned files, noHL, and remove unregistered. This directory is where you place all your downloads. This will need to be how qB views the directory where it places the downloads. This is required if you're using qbit_managee and/or qBittorrent within a container.	QBT_REM_ORPHANED / QBT_TAG_NOHARDLINKS / QBT_REM_UNREGISTERED
`remote_dir`	Path of docker host mapping of root_dir, this must be set if you're running qbit_manage locally (not required if running qbit_manage in a container) and qBittorrent/cross_seed is in a docker. Essentially this is where your downloads are being kept on the host.	❌
`recycle_bin`	Path of the RecycleBin folder. Default location is set to `remote_dir/.RecycleBin`.	❌
`torrents_dir`	Path of the your qbittorrent torrents directory. Required for `save_torrents` attribute in recyclebin `/qbittorrent/data/BT_backup`.	❌
`orphaned_dir`	Path of the Orphaned Directory folder. Default location is set to `remote_dir/orphaned_data`.	❌

cat:

This section defines the categories that you are currently using and the path's that are associated with them.

NOTE ALL categories must be defined, if it is in your qBit, then it MUST be defined here, if not the script will throw errors.

Configuration	Definition	Required
`key`	Name of the category	✅
`value`	Save Path of the category	✅

The syntax for all the categories are as follows

category: <path>/<to>/category

cat_change:

This moves all the torrents from one category to another category if the torrents are marked as complete.

NOTE WARNING: if the paths are different and Default Torrent Management Mode is set to automatic the files could be moved !!!

Configuration	Definition	Required
`key`	Name of the original category	✅
`value`	Name of the new category	✅

The syntax for the categories are as follows

old_category_name: new_category_name

tracker:

This section defines the tags used based upon the tracker's URL.

Configuration	Definition	Required
`key`	Tracker URL Keyword	✅

Variable	Definition	Default Values	Required
`tag`	The tracker tag or additional list of tags defined	Tracker URL	✅
`max_ratio`	Will set the torrent Maximum share ratio until torrent is stopped from seeding/uploading. (`-2` : Global Limit , `-1` : No Limit)	None	❌
`max_seeding_time`	Will set the torrent Maximum seeding time (min) until torrent is stopped from seeding. (`-2` : Global Limit , `-1` : No Limit)	None	❌
`limit_upload_speed`	Will limit the upload speed KiB/s (KiloBytes/second) (`-1` : No Limit)	None	❌
`notifiarr`	Set this to the notifiarr react name. This is used to add indexer reactions to the notifications sent by Notifiarr	None	❌

If either max_ratio or max_seeding_time is set to -2 then the the global share limits will be used, -1 then no share limits will be used.

If you are unsure what key word to use. Simply select a torrent within qB and down at the bottom you should see a tab that says Trackers within the list that is populated there are ea list of trackers that are associated with this torrent, select a key word from there and add it to the config file. Make sure this key word is unique enough that the script will not get confused with any other tracker.

nohardlinks:

Hardlinking data allows you to have your data in both the torrent directory and your media direectory at the same time without using double the amount of data.

If you're needing information regarding hardlinks here are some excellent resources.

Mandatory to fill out directory parameter above to use this function (root_dir/remote_dir) Beyond this you'll need to use one of the categories above as the key, and should be pointed to the completed- directory of your torrents.

Configuration	Definition	Required
`key`	Category name of your completed movies/completed series in qbit.	✅

Variable	Definition	Default Values	Required
`cleanup`	True = Remove the non-hardlinked torrent data/contents once share limits have been met, False = Use (Automatic Torrent Management) to handle seeding limits	False	✅
`max_ratio`	Will set the torrent Maximum share ratio until torrent is stopped from seeding/uploading. (`-2` : Global Limit , `-1` : No Limit)	None	❌
`max_seeding_time`	Will set the torrent Maximum seeding time (min) until torrent is stopped from seeding. (`-2` : Global Limit , `-1` : No Limit) (The `max_seeding_time` will count from the moment the NoHL tag is set)	None	❌
`limit_upload_speed`	Will limit the upload speed KiB/s (KiloBytes/second) (`-1` : No Limit)	None	❌
`min_seeding_time`	Will ensure that torrent is not deleted by cleanup variable if torrent does not meet minimum seeding time (min).	None	❌
`exclude_tags`	List of tags to exclude from the check. Torrents with any of these tags will not be processed. This is useful to exclude certain trackers from being scanned for hardlinking purposes	None	❌

recyclebin:

Recycle Bin method of deletion will move files into the recycle bin (Located in /root_dir/.RecycleBin) instead of directly deleting them in qbit.

This is very useful if you're hesitant about using this script to delete information off your system hingswithout first checking it. Plus with the ability of this script to remove trumped/unregistered torrents there is a very small chance that something may happen to cause the script to go to town on your library. With the recycling bin in place your data is secure (unless the bin is emptied before this issue is caught). All you'd need to do to recover would be to place the data back into the correct directory, redownload the torrent file from the tracker and recheck the torrent with the tracker from the UI.

Variable	Definition	Default Values	Required
`enable`	`true` or `false`	`true`	✅
`empty_after_x_days`	Will delete Recycle Bin contents if the files have been in the Recycle Bin for more than x days. (Uses date modified to track the time)	None	❌
`save_torrents`	This will save a copy of your .torrent and .fastresume file in the recycle bin before deleting it from qbittorrent. This requires the torrents_dir to be defined	False	❌
`split_by_category`	This will split the recycle bin folder by the save path defined in the cat attribute and add the base folder name of the recycle bin that was defined in recycle_bin	False	❌

Note: The more time you place for the empty_after_x_days: variable the better, allowing you more time to catch any mistakes by the script. If the variable is set to 0 it will delete contents immediately after every script run. If the variable is not set it will never delete the contents of the Recycle Bin.

orphaned:

This section allows for the exclusion of certain files from being considered "Orphaned"

This is handy when you have automatically generated files that certain OSs decide to make. .DS_Store Is a primary example, for those who use MacOS.

Variable	Definition	Default Values	Required
`empty_after_x_days`	Will delete Orphaned data contents if the files have been in the Orphaned data for more than x days. (Uses date modified to track the time)	None	❌
`exclude_patterns`	List of patterns to exclude certain files from orphaned	None	❌

Note: The more time you place for the empty_after_x_days: variable the better, allowing you more time to catch any mistakes by the script. If the variable is set to 0 it will delete contents immediately after every script run. If the variable is not set it will never delete the contents of the Orphaned Data.

apprise:

Apprise integration is used in conjunction with webhooks to allow notifications via apprise-api.

Variable	Definition	Default Values	Required
`api_url`	Apprise API Endpoint URL	N/A	✅
`notify_url`	Notification Services URL	N/A	✅

notifiarr:

Notifiarr integration is used in conjunction with webhooks to allow discord notifications via Notifiarr.

Variable	Definition	Default Values	Required
`apikey`	Notifiarr API Key	N/A	✅
`instance`	Optional unique value used to identify your instance. (could be your username on notifiarr for example)	N/A	❌

webhooks:

Provide webhook notifications based on event triggers

Variable	Notification Sent	Default Values	Required
error	When errors occur during the run	N/A	❌
run_start	At the beginning of every run	N/A	❌
run_end	At the end of every run	N/A	❌
cross_seed	During the cross-seed function	N/A	❌
recheck	During the recheck function	N/A	❌
cat_update	During the category update function	N/A	❌
tag_update	During the tag update function	N/A	❌
rem_unregistered	During the removing unregistered torrents function	N/A	❌
tag_tracker_error	During the removing unregistered torrents/tag tracker error function	N/A	❌
rem_orphaned	During the removing orphaned function	N/A	❌
tag_nohardlinks	During the tag no hardlinks function	N/A	❌
cleanup_dirs	When files are deleted from certain directories	N/A	❌

Error Notifications

Payload will be sent on any errors

{
  "function": "run_error",     // Webhook Trigger keyword
  "title": str,                // Title of the Payload
  "body": str,                 // Error Message of the Payload
  "critical": bool,            // Critical Error
  "type": str                  // severity of error
}

Run Start Notifications

Payload will be sent at the start of the run

{
  "function": "run_start",     // Webhook Trigger keyword
  "title": str,                // Title of the Payload
  "body": str,                 // Message of the Payload
  "start_time": str,           // Time Run is started Format "YYYY-mm-dd HH:MM:SS"
  "dry_run": bool              // Dry-Run
}

Run End Notifications

Payload will be sent at the end of the run

{
  "function": "run_end",                      // Webhook Trigger keyword
  "title": str,                               // Title of the Payload
  "body": str,                                // Message of the Payload
  "start_time": str,                          // Time Run started Format "YYYY-mm-dd HH:MM:SS"
  "end_time": str,                            // Time Run ended Format "YYYY-mm-dd HH:MM:SS"
  "next_run": str,                            // Time Next Run Format "YYYY-mm-dd HH:MM:SS"
  "run_time": str,                            // Total Run Time "H:MM:SS"
  "torrents_added": int,                      // Total Torrents Added
  "torrents_deleted": int,                    // Total Torrents Deleted
  "torrents_deleted_and_contents_count": int, // Total Torrents + Contents Deleted
  "torrents_resumed": int,                    // Total Torrents Resumed
  "torrents_rechecked": int,                  // Total Torrents Rechecked
  "torrents_categorized": int,                // Total Torrents Categorized
  "torrents_tagged": int,                     // Total Torrents Tagged
  "remove_unregistered": int,                 // Total Unregistered Torrents Removed
  "torrents_tagged_tracker_error": int,       // Total Tracker Error Torrents Tagged
  "torrents_untagged_tracker_error": int,     // Total Tracker Error Torrents untagged
  "orphaned_files_found": int,                // Total Orphaned Files Found
  "torrents_tagged_no_hardlinks": int,        // Total noHL Torrents Tagged
  "torrents_untagged_no_hardlinks": int,      // Total noHL Torrents untagged
  "files_deleted_from_recyclebin": int,       // Total Files Deleted from Recycle Bin
  "files_deleted_from_orphaned": int          // Total Files Deleted from Orphaned Data
}

Cross-Seed Notifications

Payload will be sent when adding a cross-seed torrent to qBittorrent if the original torrent is complete

{
  "function": "cross_seed",             // Webhook Trigger keyword
  "title": str,                         // Title of the Payload
  "body": str,                          // Message of the Payload
  "torrent_name": str,                  // Torrent Name
  "torrent_category": str,              // Torrent Category
  "torrent_save_path": str,             // Torrent Download directory
  "torrent_tag": "cross-seed",          // Total Torrents Added
  "torrent_tracker": str                // Torrent Tracker
}

Payload will be sent when there are existing torrents found that are missing the cross-seed tag

{
  "function": "tag_cross_seed",         // Webhook Trigger keyword
  "title": str,                         // Title of the Payload
  "body": str,                          // Message of the Payload
  "torrent_name": str,                  // Torrent Name
  "torrent_category": str,              // Torrent Category
  "torrent_tag": "cross-seed",          // Tag Added
  "torrent_tracker": str                // Torrent Tracker
}

Recheck Notifications

Payload will be sent when rechecking/resuming a torrent that is paused

{
  "function": "recheck",             // Webhook Trigger keyword
  "title": str,                      // Title of the Payload
  "body": str,                       // Message of the Payload
  "torrent_name": str,               // Torrent Name
  "torrent_category": str,           // Torrent Category
  "torrent_tracker": str,            // Torrent Tracker URL
  "notifiarr_indexer": str,          // Notifiarr React name/id for indexer
}

Category Update Notifications

Payload will be sent when updating torrents with missing category

{
  "function": "cat_update",          // Webhook Trigger keyword
  "title": str,                      // Title of the Payload
  "body": str,                       // Message of the Payload
  "torrent_name": str,               // Torrent Name
  "torrent_category": str,           // New Torrent Category
  "torrent_tracker": str,            // Torrent Tracker URL
  "notifiarr_indexer": str,          // Notifiarr React name/id for indexer
}

Tag Update Notifications

Payload will be sent when updating torrents with missing tag

{
  "function": "tag_update",                 // Webhook Trigger keyword
  "title": str,                             // Title of the Payload
  "body": str,                              // Message of the Payload
  "torrent_name": str,                      // Torrent Name
  "torrent_category": str,                  // Torrent Category
  "torrent_tag": str,                       // New Torrent Tag
  "torrent_tracker": str,                   // Torrent Tracker URL
  "notifiarr_indexer": str,                 // Notifiarr React name/id for indexer
  "torrent_max_ratio": float,               // Set the Max Ratio Share Limit
  "torrent_max_seeding_time": int,          // Set the Max Seeing Time (min) Share Limit
  "torrent_limit_upload_speed": int         // Set the the torrent upload speed limit
}

Remove Unregistered Torrents Notifications

Payload will be sent when Unregistered Torrents are found

{
  "function": "rem_unregistered",          // Webhook Trigger keyword
  "title": str,                            // Title of the Payload
  "body": str,                             // Message of the Payload
  "torrent_name": str,                     // Torrent Name
  "torrent_category": str,                 // Torrent Category
  "torrent_status": str,                   // Torrent Tracker Status message
  "torrent_tracker": str,                  // Torrent Tracker URL
  "notifiarr_indexer": str,                // Notifiarr React name/id for indexer
  "torrents_deleted_and_contents": bool,   // Deleted Torrents and contents or Deleted just the torrent
}

Tag Tracker Error Notifications

Payload will be sent when trackers with errors are tagged/untagged

{
  "function": "tag_tracker_error",                   // Webhook Trigger keyword
  "title": str,                                      // Title of the Payload
  "body": str,                                       // Message of the Payload
  "torrent_name": str,                               // Torrent Name
  "torrent_category": str,                           // Torrent Category
  "torrent_tag": "issue",                            // Tag Added
  "torrent_status": str,                             // Torrent Tracker Status message
  "torrent_tracker": str,                            // Torrent Tracker URL
  "notifiarr_indexer": str,                          // Notifiarr React name/id for indexer
}

{
  "function": "untag_tracker_error",                 // Webhook Trigger keyword
  "title": str,                                      // Title of the Payload
  "body": str,                                       // Message of the Payload
  "torrent_name": str,                               // Torrent Name
  "torrent_category": str,                           // Torrent Category
  "torrent_tag": str,                                // Tag Added
  "torrent_tracker": str,                            // Torrent Tracker URL
  "notifiarr_indexer": str,                          // Notifiarr React name/id for indexer
}

Remove Orphaned Files Notifications

Payload will be sent when Orphaned Files are found and moved into the orphaned folder

{
  "function": "rem_orphaned",          // Webhook Trigger keyword
  "title": str,                        // Title of the Payload
  "body": str,                         // Message of the Payload
  "orphaned_files": list,              // List of orphaned files
  "orphaned_directory": str,           // Folder path where orphaned files will be moved to
  "total_orphaned_files": int,         // Total number of orphaned files found
}

Tag No Hardlinks Notifications

Payload will be sent when no hard links are found for any files in a particular torrent

{
  "function": "tag_nohardlinks",            // Webhook Trigger keyword
  "title": str,                             // Title of the Payload
  "body": str,                              // Message of the Payload
  "torrent_name": str,                      // Torrent Name
  "torrent_category": str,                  // Torrent Category
  "torrent_tag": 'noHL',                    // Add `noHL` to Torrent Tags
  "torrent_tracker": str,                   // Torrent Tracker URL
  "notifiarr_indexer": str,                 // Notifiarr React name/id for indexer
  "torrent_max_ratio": float,               // Set the Max Ratio Share Limit
  "torrent_max_seeding_time": int,          // Set the Max Seeing Time (min) Share Limit
  "torrent_limit_upload_speed": int         // Set the the torrent upload speed limit
}

Payload will be sent when hard links are found for any torrents that were previously tagged with noHL

{
  "function": "untag_nohardlinks",          // Webhook Trigger keyword
  "title": str,                             // Title of the Payload
  "body": str,                              // Message of the Payload
  "torrent_name": str,                      // Torrent Name
  "torrent_category": str,                  // Torrent Category
  "torrent_tag": 'noHL',                    // Remove `noHL` from Torrent Tags
  "torrent_tracker": str,                   // Torrent Tracker URL
  "notifiarr_indexer": str,                 // Notifiarr React name/id for indexer
  "torrent_max_ratio": float,               // Set the Max Ratio Share Limit
  "torrent_max_seeding_time": int,          // Set the Max Seeing Time (min) Share Limit
  "torrent_limit_upload_speed": int         // Set the the torrent upload speed limit
}

Payload will be sent when cleanup flag is set to true and noHL torrent meets share limit criteria.

{
  "function": "cleanup_tag_nohardlinks",    // Webhook Trigger keyword
  "title": str,                             // Title of the Payload
  "body": str,                              // Message of the Payload
  "torrent_name": str,                      // Torrent Name
  "torrent_category": str,                  // Torrent Category
  "cleanup": True,                          // Cleanup flag
  "torrent_tracker": str,                   // Torrent Tracker URL
  "notifiarr_indexer": str,                 // Notifiarr React name/id for indexer
  "torrents_deleted_and_contents": bool,    // Deleted Torrents and contents or Deleted just the torrent
}

Cleanup directories Notifications

Payload will be sent when files are deleted/cleaned up from the various folders

{
  "function": "cleanup_dirs",             // Webhook Trigger keyword
  "location": str,                        // Location of the folder that is being cleaned
  "title": str,                           // Title of the Payload
  "body": str,                            // Message of the Payload
  "files": list,                          // List of files that were deleted from the location
  "empty_after_x_days": int,              // Number of days that the files will be kept in the location
  "size_in_bytes": int,                   // Total number of bytes deleted from the location
}

bhd:

BHD integration is used if you are on the private tracker BHD. (Used to identify any unregistered torrents from this tracker)

Variable	Definition	Default Values	Required
`apikey`	BHD API Key	N/A	✅

Want to contribute to this Wiki or have suggestions?

Fork it and send a pull request.

Submit a Docs request.

Home
- Installation
- Config Setup
  - Sample Config File
  - List of variables
    - commands
    - qbt
    - settings
    - directory
    - cat
    - cat_change
    - tracker
    - nohardlinks
    - share_limits
    - recyclebin
    - orphaned
    - apprise
    - notifiarr
    - webhooks
- Commands
- Web API
- Web UI
- Contributing & Building
- Extras
  - Standalone Scripts
  - V4 Migration Guide

Uh oh!

Uh oh!

Config Setup

Overview

Config File

Config Sample File

List of variables

commands:

qbt:

settings:

directory:

cat:

cat_change:

tracker:

nohardlinks:

recyclebin:

orphaned:

apprise:

notifiarr:

webhooks:

Error Notifications

Run Start Notifications

Run End Notifications

Cross-Seed Notifications

Recheck Notifications

Category Update Notifications

Tag Update Notifications

Remove Unregistered Torrents Notifications

Tag Tracker Error Notifications

Remove Orphaned Files Notifications

Tag No Hardlinks Notifications

Cleanup directories Notifications

bhd:

Want to contribute to this Wiki or have suggestions?

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally