Skip to main content

v6 Migration Guide

Please Note

With all these changes and improvements in v6, it might be tempting to delete your database and perform a "fresh search". THIS IS UNCESSARY and only serves to create more load for indexers. With v6 and onwards, performing a "fresh search" is NEVER needed or required to take advantage of your config changes or features we add. Please be kind to your indexers. "Read More"

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.

DANGER

It may be tempting as we go through pre-release and release 6.0.0 stable to take advantage of these searching improvements with "full" searches. While this idea is understandable, we must caution you to not disrespect your indexers by slamming them with API queries.

We recommend if you are going to conduct searches to find what you've "missed" previously, set a higher than normal delay and a searchLimit to smooth out the load on indexers.

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 AreaDescription
qBittorrentChanges 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 authenticationapiAuth 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.
NodeMinimum required version: v20
webhook APIname has been removed and should be replaced with infoHash.

Valid parameter are now ONLY infoHash and path.

(Examples can be found here.)
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.

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.

note

We have implemented specific "ratio-based" ranges for the excludeOlder, excludeRecentSearch, and searchCadence options. These ratios are meant to ensure that you appropriately utilize the intended functionality of these options.

Examples of implementations can be seen in the daemon section of the documentation.

If you encounter problems with these restrictions which you feel are invalid, please reach out to us on Discord to discuss this further.

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 an external program or script, such as qbit_manage, to force Auto Torrent Management (AutoTMM) on your existing torrents, you must enable flatLinking for cross-seed linking to work. If the program/script can ignore modifying AutoTMM on torrents with the cross-seed tag, then you should enable that feature and set flatLinking: false.

If you are not using an external tool to modify AutoTMM on your torrents, then you should use flatLinking: false. The AutoTMM settings in qBittorrent are all safe to use as they don't modify existing torrents. They only apply as a default for newly added torrents (which cross-seed ignores).

Even with flatLinking: true, you can still take advantage of the matching enhancements in v6 with your searches. However we strongly recommend that you consider your AutoTMM usage and make changes in your config and workflow to support flatLinking: false to prevent cross-seeds from conflicting.

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.

include Option Changes

Removed includeEpisodes

In cross-seed version 5, includeSingleEpisodes was added as it allowed searching for episodes while excluding ones from season packs. In v6, includeSingleEpisodes will be the only option for searching episodes as includeEpisodes is likely to produce searches for trumped/dead episode torrents.

Updated includeSingleEpisodes Behavior

Previously in version 5, includeSingleEpisodes: false would ignore searching episode torrents in addition to matching ones from rss and announce. includeSingleEpisodes will now only affect searching. Episodes matched from rss and announce will ALWAYS be matched, if possible, even if includeSingleEpisodes: false.

This serves the purpose of preventing searching for episodes that trackers will usually have trumped in favor of season packs. If you're currently using includeSingleEpisodes: true, please consider switching to false if it now meets your needs as it will reduce unecessary load on trackers.

Updated includeNonVideos Behavior

Previously in version 5, cross-seed would exclude torrents or folders for searching based on the presence of any non-video files irregardless of their size (think nfo or srt) when this was set to false. This behavior could result in you using this option to exclude music, games, or apps but losing out on searches of a movie due to a nfo, text, or srt file being included in the torrent.

includeNonVideos will now, while set to false, exclude based on HOW MUCH of the torrent or folder is comprised of video files. For instance, when set to false, if you have a 100MB torrent and your fuzzySizeThreshold is set to 0.02, then you can have up to 2MB of non-video files before it is excluded from searching.

tip

For some configurations, particularly when searching media libraries from Sonarr or Radarr with subs or metadata/cover images in the media folders, it may be necessary to enable partial matching in order to take advantage of these searches at all.

This option will now be able to effectively exclude the actual non-video BASED searches, rather than merely a "yes" or "no" for a search containing a non-video file.

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 .torrent itself or the file/folder name of a path found during data indexing, 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"), a folder itself for data-based exclusions - but not the full path, partial names/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

DANGER

It may be tempting as we go through pre-release and release 6.0.0 stable to take advantage of these searching improvements with "full" searches. While this idea is understandable, we must caution you to not disrespect your indexers by slamming them with API queries.

We recommend if you are going to conduct searches to find what you've "missed" previously, set a higher than normal delay and a searchLimit to smooth out the load on indexers.

caution

Currently, only Movies, Episodes, Seasons, and Anime are officially supported. If includeNonVideos is enabled, cross-seed can and will find matches for ANY torrent, not just the ones explicitly supported. However these will likely need to be a perfect MATCH as it does not optimize for these.

Usage of torrentDir and dataDirs

Previously in v5, there were many scenarios where using dataDirs would offer benefits over torrentDir. As such, it would be typical to have both enabled to get all possible matches. This is still allowed but no longer necessary. Aside from two execptions, we recommend all users of v6 to exclusively use torrentDir. These contain far more information to aide cross-seed in better and safer matching.

The first scenario where you should also use dataDirs is if you are downloading through usenet. This will always necessary if you want cross-seed to match against this content.

The second scenario is if you have content in your media directories not inside your torrent client. Here you only need to perform a search with dataDirs ONCE. You should never keep dataDirs enabled if the first scenario doesn't apply to you. At the most, you can add your media dataDirs and perform a search every few months but this is unlikely to yield any results and only puts undue stress on indexers.

Anime Support

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.

Note

Nearly all partial matches will have the existing files at 99.9% instead of 100%. This is expected and is due to how torrent piece hashing works.

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.

Also, please read the update FAQ entry on linking.

Torznab Categories

cross-seed will now check with Prowlarr or Jackett for the categories that that indexer supports. As a result, we no longer send searches for content that is not listed by Prowlarr/Jackett as available on the indexer.

This should reduce the number of searches made for content that does not have a chance of existing on the indexer.

Note

This requires no additional action to be taken on your part.

Sonarr and Radarr ID Lookup (searching)

DANGER

It may be tempting as we go through pre-release and release 6.0.0 stable to take advantage of these searching improvements with "full" searches. While this idea is understandable, we must caution you to not disrespect your indexers by slamming them with API queries.

We recommend if you are going to conduct searches to find what you've "missed" previously, set a higher than normal delay and a searchLimit to smooth out the load on indexers.

cross-seed now has the ability to, when configured, query instances of Sonarr or Radarr for the metadata - specifically the TVDB, TMDB, IMDB, and TVMAZE IDs. These can be used on supporting indexers to search more accurately and completely.

You do not have to do anything besides add your Sonarr and Radarr instances, with apikey (similar to the torznab URL from Prowlarr or Jackett), to the configuration options in config.js.

cross-seed will use IDs to search wherever it can.

INFO

The series or movie must be added in your instance of Sonarr or Radarr. You DO NOT need to have actual media imported, but the entry must exist

"Missing" status is valid.

We do not query any external metadata servers.

Expanded Caching System

cross-seed will now cache more aggressively and in more situations, not only speeding up the process but reducing uncessary load on indexers. When searching, torrents with identical torznab queries will have their results cached and shared. This most commonly applies to torrents of the same media but from different release groups, resolution, source, formats, etc. This will drastically reduce the number of unique queries that cross-seed makes to indexers.

Torrent snatches are now also cached in more scenarios and are used more aggresively during the decide stage. A torrent will only be snatched ONCE for the lifetime of cross-seed. Finally, past decisions will be reassessed as necessary, so any changes made to your config or future improvements we make to cross-seed will be applied to previously rejected cross seeds.

Please Note

cross-seed tries to use its cache as much as possible to reduce the burden it places on indexers. With all of the changes in v6, it will NEVER be necessary to delete your database or torrent_cache folder to perform a "fresh search". Doing so offers no benefits, is slower, and only puts undue stress on indexers. If you make changes to your config, please follow the steps listed here to take advantage.

Sonarr TV Library Searching

We always recommend, whenever possible, to feed original un-renamed data files or (preferably) .torrent files (using torrentDir) into cross-seed for searching. However, certain cases, primarily Usenet season pack downloads, could be searched using data-matching from a Sonarr TV Library but would not always perform searches "properly" due to the nested folder structures and lack of risky matching supporting multi-file searches.

My Show/
Season 1/
My Show.S01E01
My Show.S01E02

We have enhanced the search capabilities to correctly identify series and individual seasons, where possible, in Sonarr's organized libraries - and with matchMode: "risky" or "partial" - can match season packs previously downloaded and imported from your Sonarr Library.

tip

It is recommended that you use the TRaSH naming scheme to perserve as much irrecoverable metadata as possible. You can find this relevant naming schemes here for Sonarr and here for Radarr if you are not already using it.

It is also REQUIRED that you use "Season Folders" with your Sonarr Library.

This also opens up the possibility of effectively cross-seeding season packs downloaded from usenet post import/completion. We are awaiting a feature in Sonarr that will enable you to, with the bakerboy448 Arr Import script, replicate the immediate "search, match, and cross-seed" behavior you can achieve with torrent downloads.

info

We are working with both the Sonarr Team and bakerboy448 to get the supporting features ironed out for this to be as effective as possible, but in the mean time you can already match Sonarr Library seasons with a manual/scheduled search of the season folder.

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.
  • Better RSS/Announce parsing. This new method better handles different naming schemes and is much faster to process. If the reverse lookup does match, we also check against all valid matches instead of only the first.
  • 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, season (e.g. "Season 01") and main series/movie folders in Sonarr and Radarr 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.