v6 Migration Guide

Updates Since Initial

• qBittorrent users should stick with v5.9.2 for the time being if you use Auto Torrent Management in ANY capacity.

  Updated: 4/21/24 @ 10:40 GMT -6

• autobrr addition and linking section update

  Updated: 4/21/24 @ 09:25 GMT -6

Overview

There are several changes in cross-seed version 6.x. Most of them do not require any action on your part, but 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.

Breaking Changes (TLDR)

Scope/Area	Description
qBittorrent	Pending.
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.

• legacyLinking

• apiKey

• 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.

The new folder structure in v6 for the linkDir creates sub-folders for each indexer (for example, /link_dir/Indexer 1/Name.of.Torrent.File.mkv). This doesn't change previously matched torrents, but if enabled will follow this new structure.

There is, however, a new option introduced into config.js named legacyLinking; mainly to attempt accommodate some cases of users of qBittorrent who want to utilize Auto Torrent Management and possibly cat_change features with qbit_manage. This has not proven to be effective after testing has been performed by our pre-release testers.

All that said, setting legacyLinking to true will tell cross-seed to use the same style of linking as v5, but support torrent-based linking in addition to data; one folder with all the linked torrent data directly inside.

autobrr Update

If you're using legacyLinking: 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 update 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 (["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.

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 just ONE release) that we've missed, please let us know.

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.

Torrents will be added in a paused state if skipRecheck is false (recommended), and unpaused if skipRecheck is true. It's advised not to set fuzzySizeThreshold above 0.1 to avoid triggering excessive snatches, which could lead to the banning or disabling of your account on your 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 in full-disc Bluray/DVD releases, music files, RAR archives, and season folders 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.