Delete Protection

Delete Protection guards your server against a rare but severe failure: a whole-server freeze that can happen when a media server or download app deletes a very large file. It is an opt-in feature — off by default — that a server admin turns on with a single switch. This page explains what it is, why it works, how to choose a threshold, and how to enable and manage it.

Overview

On a server with a lot of RAM, deleting a very large file that is fully cached in memory can make the system spend a long time clearing that memory. While it does, the whole server can lock up — unreachable, and often only recoverable with a manual hard reboot. The deletes that trigger this are usually automated: an app’s own library maintenance, a database rebuild, or a quality upgrade replacing a big file — not something you did by hand.

When you enable it, Delete Protection puts a small, targeted safeguard in place that clears a large file’s memory in small, quick steps right before it is deleted. The delete stays fast, and no single step can lock up the server. It covers media servers (Emby, Jellyfin, Plex) and download apps (Radarr, Sonarr, SABnzbd, torrent clients, and more).

Key features

What causes the freeze

Deleting a file forces the operating system to release the memory that was caching that file’s contents. For a small file this is instant. For a very large file — several gigabytes — that is fully resident in RAM, the work grows with the file’s size, and on a high-memory server it can take long enough that the machine stops responding to everything else. Because one part of the system is stuck, the rest waits on it, and the server has to be hard-rebooted to recover.

The symptom is unmistakable and confusing: the server freezes for no obvious reason, nothing in the app logs points at a cause, and only a hard reboot brings it back — sometimes weeks apart. The trigger is almost always an automated delete of a large file: a media server rebuilding or replacing its own large database, or a download app removing or upgrading a large media file.

Delete Protection removes the cause. Instead of the delete releasing all of that memory in one long operation, the safeguard releases it in small, quick steps first, then performs the delete. The total work is the same, but no single step is ever long enough to lock up the server.

Who it’s for

What’s protected

Delete Protection applies to the media servers and download apps that routinely delete large files. Only apps you actually have installed are affected; anything not installed is skipped.

Beyond this built-in list, a server admin can opt any other app into the same protection — including custom or third-party apps QuickBox does not manage. See Add a custom or third-party app below.

Manage from the Dashboard

The dashboard is the recommended way to enable and manage Delete Protection. Because it is off by default, the first step is to turn it on.

Step 1 — Turn Delete Protection on

In your server’s dashboard, open Settings > General > Feature Flags and turn on the Delete Protection toggle. This single switch is the master on/off: enabling it applies the safeguard to your installed media and download apps and reveals the Delete Protection page in the System area (and its QuickNav shortcut). Turning it back off removes the safeguard and hides the page.

Step 2 — Open the Delete Protection page

Once it is on, open System → Delete Protection from the sidebar (or its QuickNav shortcut). This is a system settings page on the default dashboard — it is an admin surface. There you get:

• Large deletes safely handled — a complete, all-time total of protected deletes. It is a permanent record that survives log rotation and updates, so it only ever climbs.
• Server-wide protection — a master switch to turn protection on or off for the whole server.
• Server default threshold — a set of presets (all inside the 16 MiB to 1 TiB range the server enforces) that decide how large a file must be before protection engages. The default is 256 MiB, and it is the floor every app inherits unless you give that app its own threshold.
• Protected apps table — each installed media/download app with its own on/off switch and its own editable threshold, so you can opt a single app out, or raise or lower just that app’s threshold, without touching the others. An Add custom app button here also lets you opt any other app — including custom or third-party apps QuickBox does not manage — into protection.
• Recent protected deletes — a sortable, filterable, selectable table of the deletes the safeguard has handled, with controls to remove logged entries you no longer need.

Every choice you make here — a disabled app, a custom threshold, a per-app override, a registered custom app, a whole-server opt-out — is remembered and survives future updates.

Set a threshold for just one app

Most servers are fine on the single server default. But some apps routinely delete much larger files than others — SABnzbd, for example, removes big usenet downloads as part of normal cleanup — and you may want protection to engage at a higher floor for those while smaller-delete apps stay on the default.

In the Protected apps table, each protected app’s Threshold column is a dropdown. It shows Server default (256 MiB) while the app is inheriting the global floor. Pick any other size to give that app its own threshold — the app then shows a Custom marker, meaning it no longer follows the server default. To hand the app back to the global floor, choose Server default again from the same dropdown.

Add a custom or third-party app

Delete Protection is not limited to the built-in media and download apps. From the Delete Protection page, a server admin can opt any other app on the server — including custom or third-party apps QuickBox does not manage — into the same safeguard. In the Protected apps section, click Add custom app, give the app a short name, then choose how it runs:

• systemd service — for an app that runs as a systemd unit. Enter the unit’s base name (for example myapp, which covers both myapp.service and myapp@.service). QuickBox installs the same automatically-managed safeguard it uses for its built-in apps — there is no manual step. The app then appears in the Protected apps table as a normal protected row, marked custom, with its own threshold control and an option to remove it later.
• cron / manual — for an app that is not a systemd service: one launched from a user crontab, a login or autostart script, or by hand (an IPTV tool run from a crontab, for example). Because there is no service for QuickBox to attach to, the dashboard instead gives you a copy-ready recipe — an LD_PRELOAD=… prefix — to paste in front of the app’s launch command in its crontab or startup script. It takes effect on the app’s next run; no restart is needed. Reopen it any time from the row’s Show recipe button.

A registered custom app is remembered and survives updates, just like every other choice. To stop protecting one, remove it with the row’s unregister control (or qb manage delete-safety -o unregister —app <name>). Built-in apps cannot be unregistered — turn those off with their per-app switch instead.

Manage the recent-deletes log

The Recent protected deletes feed is a full, sortable, filterable, and selectable table of the large deletes the safeguard has handled. Sort by time, app or actor, UID, or size; search across the app, process name, and full file path; and narrow the list with three filters: a time window (last 24 hours, 7 days, or 30 days), an app or actor, and a size floor (256 MB, 1 GB, or 10 GB and up). It is always paginated, so the list never grows unwieldy.

Click any row to expand it into a per-delete detail panel: the full absolute file path, the exact size in bytes, the process name, PID, and UID behind the delete, the time it happened (both absolute and relative), and, when the process maps to a protected app, that app and the size threshold that was in effect for it.

If you want to tidy the log, you can remove entries you no longer need:

• Delete one entry — from that row directly.
• Delete a selection — tick the rows you want and choose Delete selected.
• Clear older entries — use Clear delete log to remove everything older than 7, 30, or 90 days, or the entire log.

Choosing a threshold

The threshold is the file-size floor: a file has to be at least this big before the safeguard engages, and anything smaller deletes normally. A common question is whether the 256 MiB default is too low. It is not — and lower is the safe direction, not the risky one.

A lower threshold means more files are protected, and 256 MiB already sits well below the size where these freezes begin. There is no downside to a low floor: files under it delete exactly as they always did, and files over it get the safeguard. So leave the server default where it is. The per-app override exists for the opposite reason — to raise a specific app’s floor when that app’s everyday deletes are already large, so that protection and the activity feed stay focused on the genuinely huge deletes that actually carry the freeze risk, instead of firing on routine churn.

You rarely need to change this. Raise a specific app’s floor to match the size its real large deletes actually hit — never above it, or you lose protection where it matters.

Manage from the CLI

Everything the dashboard does is available from the terminal through qb manage delete-safety. The same settings back both surfaces, so a change made in either place is reflected in the other.

# Show current protection status (human-readable table)
qb manage delete-safety -o status
 
# Machine-readable status (JSON)
qb manage delete-safety -o status --json
 
# Turn protection on for all installed apps
qb manage delete-safety -o enable
 
# Turn protection on for just one app
qb manage delete-safety -o enable --app radarr
 
# Turn protection off for the whole server
qb manage delete-safety -o disable
 
# Opt a single app out of protection
qb manage delete-safety -o disable --app sabnzbd
 
# Set the server default threshold (bytes) — here, 512 MiB
qb manage delete-safety -o threshold --bytes 536870912
 
# Give one app its own threshold — SABnzbd at 50 GiB
qb manage delete-safety -o threshold --app sabnzbd --bytes 53687091200
 
# Clear an app's override so it follows the server default again
qb manage delete-safety -o threshold --app sabnzbd --reset

Custom apps and the activity log are managed with the same command:

# Register a custom systemd app (auto-managed, exactly like a built-in)
qb manage delete-safety -o register --app myapp --kind systemd --unit myapp
 
# Register a custom cron / manually-launched app (recipe-based, no service)
qb manage delete-safety -o register --app iptvtool --kind manual
 
# Print the copy-ready LD_PRELOAD recipe to paste into the app's launch line
qb manage delete-safety -o recipe --app iptvtool
 
# Remove a custom app from protection
qb manage delete-safety -o unregister --app iptvtool
 
# List the protected-delete activity log (JSON)
qb manage delete-safety -o list-log --json
 
# Preview clearing log entries older than 30 days (removes nothing)
qb manage delete-safety -o prune-log --older-than-days 30 --dry-run
 
# Clear log entries older than 30 days
qb manage delete-safety -o prune-log --older-than-days 30

Reapply protection

If protection ever looks out of sync — for example after a manual change — reconcile every installed app back to your saved settings with:

qb fix delete-safety

This rebuilds the safeguard if needed and brings each app’s protection in line with your saved choices. It is the same reconcile step that runs automatically on every update, so it is always safe to run.

Configuration and files

Delete Protection stores its settings, its activity log, and the safeguard itself under standard QuickBox paths. You never need to edit these by hand — the dashboard and CLI manage them for you — but they are useful to know for support.

Troubleshooting

Best practices

FAQ

Related references