v6 Migration Guide

Updates Since Initial Pre-Release

Since the initial pre-release (6.0.0-0) we've worked with our users and friends to iron out implementations in the most reasonable and usable way possible. As we proceed through the pre-release/testing phase for v6, further changes may be made. They will all be documented here prior to releases.

The majority of the trade-offs we've had to make have been for enhancements and meaningful features. While this update will require some users to rethink, or reconfigure, certain aspects of their setup or workflow to accommodate this; these changes were, unfortunately, unavoidable.

The enhancements we've added and changes we've made are outlined in this migration guide.

Be advised

Please read this guide thoroughly and keep in mind that it will be updated throughout the pre-release process, and after, as we fine-tune the details for clarity.

The latest pre-release versions can be installed by using the Docker tag :master or NPM tag of @next after cross-seed.

QBittorrent

While we previously advised qBittorrent users to hold off on the initial pre-release (6.0.0-0), we feel we now have cross-seed in a usable state for those users. There are some changes that should be noted before updating to help test. We recommend backing up your configuration directory before testing any pre-release versions.

Overview

There are several changes in cross-seed version 6.x. Most of them do not require any action on your part while some need to be addressed in both the configuration file (config.js) and potentially permissions or volumes/mounts.

This document outlines the changes made and the actions required to take advantage of all the new features and capabilities.

Please Note

This is currently a pre-release of v6. Your mileage may vary on behavior and performance. We always recommend that before updating you make a backup of your entire configuration directory.

Please let us know if you run into any issues via Discord

Breaking Changes (TLDR)

Scope or Area	Description
qBittorrent	Changes were necessary for linking enhancements made and compatibility with AutoTMM and qBittorrent. duplicateCategories previous behavior has migrated to .cross-seed appended category being tagged on the cross-seeded torrent. All cross-seeds will go to linkCategory when linked and injected. (Read More)
API authentication	apiAuth option was removed and the optional apiKey option was added. If unspecified, cross-seed will use an autogenerated API key. Use the API key when you make calls to the /api/webhook endpoint and the /api/announce endpoint.
Node	Minimum required version: v20

HEADS-UP!

cross-seed v6 requires Node 20 or greater. Check your Node version with node --version and update if needed.

Docker users can skip this step.

tip

You can grab the new config.template.js and simply go through and migrate your missing options over to your current config.js. Alternatively, you can add them yourself by referencing our documentation.

• dataCategory -> linkCategory

• apiAuth -> apiKey

• flatLinking

• blockList

Stricter config.js Validation

One of the biggest changes made in v6 is better config validation and error messaging. Each option in the config file is validated for formatting and proper syntax. If either is incorrect, a detailed error message will tell you where and how to fix each option.

The new error messages will also provide links to specific documentation for the option and point out bad paths or permission errors if you have any.

This is not going to automatically fix anything for you, but will give you a better starting point to try and solve the issue yourself before requiring outside assistance.

Linking Updates

We have made drastic changes to the way linking operates, both in its implementation and in expanding its capabilities. Not only is linking more versatile in what can be matched now (for instance, previously, files inside/outside a folder would not match to a torrent in the opposite folder structure - this has been fixed), but you can also take advantage of linking when searching .torrent files instead of solely applying to data-based matching.

To achieve torrent linking, you simply have to mount or give permission (if necessary) for cross-seed to read and write to the actual torrent data structure (downloaded files) your client uses. This will need to mirror (for docker) the mounts made in the client. Your client will also need to be able to read and write to the linkDir folder. You do not need to specify a dataDirs in your conig for this setup, but simply define a linkDir.

tip

You can still include a dataDirs if you wish to also index and search your data, but dataDirs isnt necessary to utilize linking behavior now.

The new default linking structure in v6 in your linkDir creates sub-folders for each indexer (for example, /link_dir/Indexer 1/Name.of.Torrent.File.mkv). This doesn't change or affect previously matched torrents, but if enabled will follow this new structure moving forward. Your Indexer 1 will be the name of the indexer in Prowlarr/Jackett or autobrr.

BE ADVISED

Auto Torrent Management in qBittorrent has presented some hurdles with implementing the new linking enhancements with qBittorrent.

Please read the next part of this section carefully to determine what settings you will require to achieve the best results.

During this transitional process, you can get support via Discord if you require assistance with any of the configurations.

qBittorrent

Due to the limitations in place with qBittorrent and Auto Torrent Management's behavior, we've introduced a new option in support of the feature-sets and changes we have added.

If you are using Auto Torrent Management (AutoTMM) in any capacity, we strongly recommend that you enable flatLinking to acheive the matching and linking behavior we've added to v6. You will still be able to take advantage of the matching enhancements in v6 with your searches.

cross-seed will inject all linked torrents directly to the linkCategory if linking is possible, otherwise direct torrent matches will behave the same as they did in v5.

autobrr Update

If you're using flatLinking: false, when receiving announces with the old data payload in your cross-seed autobrr filter, you might notice inconsistencies in the folders created from ones created with a search.

To address this, autobrr's macros and documentation have been updated. There is now a new macro to accommodate the new linking structure. By updating your data payload with the provided code, autobrr will now send the indexer's name from Settings -> Indexers instead of the "indexer identifier".

{
    "name": "{{ .TorrentName }}",
    "guid": "{{ .TorrentUrl }}",
    "link": "{{ .TorrentUrl }}",
    "tracker": "{{ .IndexerName | js}}"
}

Simply ensure that you've updated your data and the indexer's name in autobrr matches the one in Prowlarr/Jackett, and everything will align correctly in your linkDir.

Updated torrentDir Option

Previously, our recommendation if you wanted to strictly search only dataDirs for matches was to point torrentDir at an empty folder. This is no longer necessary. You can now set torrentDir to null to achieve a data-only search.

New blockList Option

Another new option added is called blockList. This option takes an array of strings (e.g. ["example", "example2"] ) and will block any matching strings contained in both the release name as well as exact matches.

You can include strings for the full, exact name of a torrent or file (e.g., "The.Best.Movie.Ever.2024.DV.HDR.Atmos.mkv"), partial name/keywords (e.g., best.movie.ever), or the infoHash from a torrent you wish to block.

apiAuth (removed) and apiKey (added) Options

cross-seed endpoints (announce and webhook) now require API authentication. There are two ways to set up API authentication in v6:

1. Generated Key: By setting apiKey to undefined, cross-seed will continue to use a generated key. You can find this key by running cross-seed api-key.

   This is recommended for most users.

2. Designated Key: You can now set a designated API key for cross-seed. Setting apiKey: "YOURkeyHereMak3It@good1", in the config file will tell cross-seed to always use that key.

The apiAuth option in previous versions of cross-seed has been removed.

danger

While we provide this option, we strongly urge you to use a generated key. If you are specifying a key, please make sure this is a secure and safe key. You are responsible for your security.

Searching Improvements

caution

Currently, only Movies, TV Series, and Anime are officially supported.

Anime Support (experimental)

Anime is now supported in a somewhat limited capacity. Please note that this is our first attempt at accommodating this content, so your experience may vary depending on your indexers and content.

We've aimed to cover the inconsistent and unconventional naming conventions that prevail in anime content, but there may be certain naming styles, from specific groups or indexers, that we haven't accounted for.

HELP

If you come across any anime naming schemes (not ONE "edge-case" release) that we've missed, please let us know via Discord.

Partial Matching

We've introduced a new mode for matchMode named partial.

This mode is similar to risky but doesn't necessitate all files to be present. The minimum required "match size" is determined by 1 - fuzzySizeThreshold. For instance, with a fuzzySizeThreshold of 0.05, potential cross-seeds containing only 95% of the original size will match. This mode is designed to identify cross-seeds missing small files such as nfo, srt, or sample files.

BE ADVISED

Torrents matched and added via a partial match will always recheck and pause. It's advised not to set fuzzySizeThreshold above 0.1 to avoid triggering excessive snatches.

Failing to consider your settings and their impact could lead to the banning or disabling of your account on trackers.

Other Miscellaneous Changes

Here is a short list of other changes made in v6. These are all behind-the-scenes updates made to improve cross-seed.

• Updated to Node v20, ES2022, and TypeScript v5
• Any indexer failures not related to rate limiting (status code: 429) will be cleared from the database when cross-seed is restarted.
• Regex improvements. Some trackers rename search results or have non-standard naming conventions. The updated regex takes more of those into account and should find more matches.
• Improved logging messages, specifically around matching decisions.
• There are now lists of files/folders integrated into cross-seed that are blocked during prefiltering at startup. These include folders present inside full-disc Bluray/DVD releases (BDMV/CERTIFICATE), individual music files, RAR archives, and season folders (e.g. "Season 01") in Sonarr libraries. Excluding these from the cross-seed index (for data-based searches) will result in fewer "bad" searches that would otherwise yield no viable results.
• New recommended defaults in config.template.js. These settings are what we consider to be the best starting options when setting up cross-seed.