# qbt-clean

A tool for cleaning up torrents in qBittorrent. The defining feature is that it attempts to identify groups of torrents that are the same content. For example torrents that are likely hard-linked or ref-linked to the same underlying data.

> [!warning]
> This is a tool to delete data, it will do so. It is highly recommended to run in dry-run (the default) first and validate that it is deleting what you expect.
>
> Additionally this tool is very new and not particularly well tested. Additionally the configuration is constantly changing at these early stages.
>
> **USE AT YOUR OWN RISK**

## Commands

### simulate

Simulate is equivalent to `clean` except that it doesn't actually modify anything. Use it to see what would be cleaned.

```sh
qbt-clean --config=config.scfg simulate
```

### clean

Clean torrents until space target is reached. Unpinned groups will be cleaned from highest score to lowest until the free space target is met.

```sh
qbt-clean --config=config.scfg clean
```

### group

Show groups as well as info about them such as if they are pinned or not and what rank they are in the cleaning order. Use `--help` for more options.

```sh
qbt-clean --config=config.scfg group
```

## Grouping

The current grouping is incredibly simple. It just sums up the size of substantial files in each torrent. Any files that share the exact same total size are considered a group.

## Config

The configuration is read from a file passed via `--config <path>` (in [scfg](https://crates.io/crates/simple_config) format) or `--json <path>` (in JSON format). Exactly one must be provided. This documentation displays scfg format.

An example simple config looks like this:

```yaml
# Operational Config
qbt-url: https://admin:yohn0daeV6eeth4bieyahqu1ogohMaiz@qbttorrent.example
target-free: 0.8 TiB

# Requirements
last-activity-min: 7d
seed-time-min: 30d

# Ranking
seeder-count-weight: 1

categories-allowed:
	cross-seed
	other
```

### Operational Config

#### `target-free`

Clean up torrents until this much space is free on the filesystem.

Note: This assumes that each deleted group frees up the amount of the space of the torrent size. This can underestimate (if the backing blocks are still used by other files) or overestimate (if the torrents in the group did not share data).

```yaml
target-free: 100 GiB
```

##### Risk if Free Space Doesn't React to Deletions

For general safety, qbt-clean will only free the apparent difference between the filesystem's reported free space and `target-free` each invocation. So for example if `target-free: 250 GiB` and only 230 GiB is available qbt-clean will attempt to clean 20 GiB of content, then stop, even if the reported free space may not be >=250 GiB at that time.

However, if qbt-clean is run multiple times this can have disastrous behaviour should the filesystem's reported space not actually change as torrents are deleted. Notably the difference in reported/target free space will be deleted **on every invocation**.

For example: if you take a filesystem snapshot of all of your torrent data, then run qbt-clean every 10 minutes, if you are 100 GiB short of the `target-free` value each invocation will delete 100 GiB of torrents. This can very quickly delete all of your unpinned data.

A non-exhaustive list of cases where the actual free space may not update as torrents are removed:

- Filesystem snapshots keeping all (or some) torrent data alive.
- Hardlinks or reflinks that keep the data alive.
- Filesystem free space reporting delay.
- Processes holding the files open and keeping the data alive.

So please consider this risk and consider running qbt-clean relatively infrequently compared to anything that keeps the files alive. Also consider using `delete-limit-data` and/or `delete-limit-groups` to limit the maximum deletion rate.

#### `delete-limit-data`

An optional limit on how much data is deleted in a single run. Deletion stops once this amount is exceeded, though the last deleted group may add more. By default there is no limit.

```yaml
delete-limit-data: 50 GiB
```

#### `delete-limit-groups`

An optional limit on the total number of groups deleted. Deletion stops once this count is reached. By default there is no limit.

```yaml
delete-limit-groups: 10
```

#### `qbt-url`

The URL to interact with qBittorrent at. This should also contain the username and password for authentication.

```yaml
qbt-url: http://localhost:8080
```

#### `qbt-headers`

These headers will be passed to qBittorrent on every HTTP request. This is most useful for proxy forward authentication. For example basic auth or other credentials can be passed.

```yaml
qbt-headers:
	Authorization: Basic QXp1cmVEaWFtb25kOmh1bnRlcjI=
```

#### `parallelism`

The parallelism to use. This roughly corresponds to the number of concurrent requests to qBittorrent.

The default is currently 16 which strikes a balance between performing reasonably in high-latency environments and not unnecessarily loading qBittorrent. Local users can probably use a much lower number, especially if total execution time isn't very important.

### Requirements

These requirements prevent cleaning up torrents that shouldn't be. They are applied to each torrent in a group individually. Any torrent in a group that fails to satisfy a requirement will prevent the entire group from being removed.

The default values are being shown.

#### `categories-allowed`

The torrent must be in one of these categories to be cleaned up.

There are no defaults (meaning that if this isn't set no torrents will match).

#### `last-activity-min`

If the torrent was active within this period it won't be cleaned up.

```yaml
last-activity-min: 7d
```

#### `seed-time-min`

If the total torrent seed time is less than this it won't be cleaned up.

```yaml
seed-time-min: 14d
```

#### `seeder-count-min`

If a torrent has less than this many seeders it won't be cleaned up.

```yaml
seeder-count-min: 3
```

#### `state-allowed`

If the torrent isn't in one of these states it won't be cleaned up. These can be specified with either the identifiers that qBittorrent uses or more consistent kebab-case versions.

```yaml
state-allowed:
	error
	missing-files
	stopped-downloading
	stopped-uploading
	uploading-forced
	uploading-queued
	uploading-stalled
```

If this field is empty, then any state is allowed.

### Rules

Rules allow you to override the requirements for specific torrents. For example the following rule will avoid cleaning up Archive.org torrents unless they have at least a year of seed time. Note that this applies only to the specific torrent. Other torrents in the group may have less seed time when cleaned up.

```yaml
rules:
	:
		match:
			tracker-url:
				http://bt\d+.archive.org:6969/announce
		seed-time-min: 365d
```

Rules consist of a `match:` block which contains filters and then a set of requirements to override when the filters match. Later overrides supersede earlier overrides.

#### Effects

##### Global Requirements

All global requirements can be modified with an attribute of the same name.

##### `pin`

There is a special `pin` requirement that overrides any other requirement. So a filter that applies `pin: true` will prevent a torrent (and it's group) from ever being deleted. `pin: false` will prevent a torrent from ever holding a group alive (but other torrents in the group may keep it alive). Just like other requirements only the **last** `pin` rule that matches applies.

> [!warning]
> Be very careful with `pin: false`. It overrides **all** requirements and is very easy to delete more than you intended. For example do you have an "Important Never Delete" category? It won't be protected by the `categories-allowed` requirement anymore. So be very careful that all rules that apply `pin: false` are very particular about what you want to never pin.

##### `pin-reason`

An optional human-readable string that explains why a `pin` rule applies. This value is purely informational to help you understand which rules are affecting the cleaning decisions.

```yaml
rules:
	:
		match:
			categories:
				trash
		pin: false
		pin-reason: Trash category, always cleanable.
```

##### `include-in-score`

This value is a boolean that allows excluding torrents from the group score. This is commonly used with `pin: false`. Additionally consider configuring the `no-scored-torrents-weight` to influence the score of groups containing only `include-in-score: false` torrents.

#### Matchers

##### any

The `any` filter takes a list of filters and matches if any of them match.

This example will set the minimum seeder count if either a specific tracker is on the torrent or it is in the `favourites` category.

```yaml
rules:
	:
		match:
			any:
				:
					tracker-url:
						https://tracker.example
				:
					categories:
						favourites
			seeder-count-min: 10
```

##### categories

The `categories` filter matches torrents that are in the given categories.

```yaml
rules:
	match:
		categories:
			Favourites
			Keep Forever
```

Note: There is also a `categories-allowed` requirement.

##### is-private

Match based on if the torrent is marked as private or not.

```yaml
rules:
	:
		match:
			is-private: true
```

##### last-activity

Match based on when the torrent was last active.

```yaml
rules:
	:
		match:
			last-activity:
				lt: 1d
```

##### leech-count

Match the number of leechers.

```yaml
rules:
	match:
		leech-count:
			gt: 10
```

##### name

Match any torrents who's name matches the regex.

```yaml
rules:
	:
		match:
			name:
				Arch.*\.iso
```

##### none

Match if none of the given filters match:

```yaml
rules:
	match:
		# Match if not (seed-count and leech-count less than 10) AND not name matches the regex.
		none:
			:
				seed-count:
					lt: 10
				leech-count:
					lt: 10
			:
				name:
					Arch.*\.iso
```

##### seed-time

Match based on the seed time for the torrent.

```yaml
rules:
	:
		match:
			seed-time:
				gt: 1h
```

##### ratio

Match based on the ratio of the torrent.

```yaml
rules:
	match:
		ratio:
			ge: 8
```

##### seed-count

Match the number of seeders.

```yaml
rules:
	match:
		seed-count:
			ge: 10
```

##### state

Match if the torrent state is in any of the listed states.

```yaml
rules:
	:
		match:
			state:
				stopped-downloading
				uploading-forced
```

##### tracker-msg

Match if any of the tracker's tracker messages matches any of the given regexes.

```
rules:
	:
		match:
			tracker-msg:
				[Uu]nregistered torrent
				Torrent has been deleted.
```

##### tracker-status

Match if any of the tracker's trackers' statuses matches any of the given states.

```
rules:
	:
		match:
			tracker-status:
				tracker-error
				unreachable
```

Supported statuses:

- `disabled`
- `not-contacted`
- `not-working`
- `other`
- `tracker-error`
- `unreachable`
- `updating`
- `working`

> [!warning]
> Setting this can make your cleaning slightly unpredictable as tracker status regularly changes (notably to and from `updating`).

##### tracker-url

Match if any of the tracker URLs match any of the given regexes.

```
rules:
	:
		match:
			tracker-url:
				http://bt\d+.archive.org:6969/announce
```

### Ranking

Ranking determines which torrents to delete first. The highest ranked torrents will be deleted until the desired space is reclaimed.

All ranking parameters take a floating point number and default to zero. If all ranking parameters are zero `seeder-count-weight: 1.0` will be applied.

#### `age-d-max-weight`

Rank based on the age of the oldest torrent in the group.

Note: If you want to prefer keeping older torrents the weight should be negative.

#### `age-d-min-weight`

Rank based on the age of the newest torrent in the group.

Note: If you want to prefer keeping older torrents the weight should be negative.

#### `copies-weight`

Rank based on number of torrents in the group.

Note: If you want to prefer keeping larger groups the weight should be negative.

#### `last-activity-d-weight`

Rank based on the last activity in the group.

#### `no-scored-torrents-weight`

If a group has no scored torrents, apply this weight. (See [`include-in-score`](#include-in-score))

#### `seeder-count-weight`

Rank based on total seeder count.

#### `size-weight`

Rank based on the size expected to be freed by deleting.

Note: This is roughly the size of a torrent in the group.
