Dynamix File Recycle Bin

Chinese documentation: README.zh.md

A guarded recycle bin for Unraid's official built-in Dynamix File Manager (DFM). It adds a selection-aware Recycle action immediately before DFM's native Delete button and atomically renames selected files or directories into each owning volume's .RecycleBin.

This plugin only handles operations started with its separate Recycle button in the built-in file browser. DFM's native Delete button remains a permanent delete. Deletion through SMB/NFS, a terminal, Docker containers, applications, scripts, or third-party file managers is not intercepted.

The current release deliberately supports only simple, verifiable storage layouts. The server checks every selected item before confirmation and shows a specific reason and advice when any path is unsupported.

Supported scope

• Ordinary files and directories on Unraid array mounts such as /mnt/disk1.
• Local ZFS datasets whose backing devices can be verified as non-USB and non-removable. Each dataset gets its own .RecycleBin and SQLite database.
• Atomic, same-filesystem rename only.

The following are intentionally rejected:

• /mnt/user and /mnt/user0 virtual user-share paths.
• /mnt/cache* cache paths. Independently mounted local ZFS pools remain eligible when their backing devices pass the normal safety checks.
• /mnt/disks (Unassigned Devices), /mnt/remotes, remote filesystems and arbitrary external mounts.
• /boot, including the Unraid boot USB device.
• USB-backed or removable storage, symbolic links, nested mount points and any storage topology that cannot be verified safely.
• Cross-filesystem copy-and-delete operations.

Linux cannot always identify the physical enclosure of a disk. For example, an eSATA enclosure may present exactly like an internal SATA disk. The plugin therefore uses mount ownership, transport, removable flags and sysfs topology; unknown layouts are blocked, but physical placement cannot be guaranteed from software alone.

Requirements

Install

Unraid Community Applications

After the plugin is accepted into Community Applications, open Apps and search for Dynamix File Recycle Bin.

Unraid Plugin Manager

Open Plugins -> Install Plugin and paste:

https://raw.githubusercontent.com/xO-ox-ai/dynamix.file.recycle/main/dynamix.file.recycle.plg

The Plugin Manager downloads the versioned package, verifies its SHA-256 digest and runs the install hook. Open Settings -> User Programs -> Dynamix File Recycle Bin to review the master switch and maintenance policy. Open Tools -> Disk Utilities -> Recycle Bin to view, restore or permanently delete tracked recycle items.

Command-line installation uses the same official Plugin Manager path:

/usr/local/emhttp/plugins/dynamix.plugin.manager/scripts/plugin install \
  https://raw.githubusercontent.com/xO-ox-ai/dynamix.file.recycle/main/dynamix.file.recycle.plg

Basic usage

1. Open a physical disk or supported ZFS dataset in DFM.
2. Select one or more files or directories with DFM's checkboxes.
3. Click Recycle immediately to the left of the native Delete button.
4. The server checks every selected path, mount, filesystem and backing device.
5. After every check succeeds, review the scrollable confirmation list showing each source path and its destination .RecycleBin folder. Nothing moves until you explicitly confirm.
6. Open Tools -> Disk Utilities -> Recycle Bin to restore or permanently purge tracked items.

The Settings page lists every volume that currently passes the backend safety checks. All are selected on first install. Saving converts that initial policy to an explicit allowlist: unchecked volumes remain visible in history, but new recycle, restore, purge and automatic maintenance actions are blocked there. Array disks and ZFS datasets are displayed as separate trees; ZFS entries keep their native pool/dataset hierarchy. When a ZFS dataset is nested below an array disk or another local pool, files are always recycled into that exact dataset's .RecycleBin; the parent volume is never used as a fallback.

Important behavior

• .RecycleBin is created on demand under the exact enabled disk or ZFS dataset only when its first recycle operation reaches database setup. Installing the plugin or enabling a volume does not pre-create the folder.
• Every child ZFS dataset is an independent management boundary. Enabling its parent disk or pool does not implicitly enable the child dataset.
• Disabling a volume blocks recycle, restore, purge and maintenance there; it does not delete existing recycled files or history.
• Restored history rows link back to their existing location in Unraid's built-in file browser. A missing original path remains plain text.
• The list supports current-page batch selection, server-side paging, and name/time/size sorting. Historical rows cannot be selected for mutation.
• Do not manually move, rename, delete or edit anything inside .RecycleBin. This includes recycled items and the hidden SQLite, -wal and -shm files. Manual changes can detach files from their records or damage recovery history. Use the plugin's Recycle Bin page for every restore and permanent deletion.

Example layout:

For ZFS, /mnt/tank in the example must be the dataset's actual mount point; pool aliases and parent filesystems are not substituted.

Persistence and diagnostics

• Recycled data and history: <volume>/.RecycleBin/ and its SQLite database.
• Persistent settings: /boot/config/plugins/dynamix.file.recycle/.
• Runtime log: /usr/local/emhttp/state/plugins/dynamix.file.recycle/logs/dynamix.file.recycle.log.
• Reboot-surviving error audit: /boot/config/plugins/dynamix.file.recycle/logs/audit.log.

Set Log level to DEBUG, save, reproduce an operation failure, then use Download diagnostic logs in Settings. The temporary .tar.gz contains plugin logs and bounded storage/PHP/SQLite snapshots, but never recycled file contents; the server-side archive is deleted immediately after download.

The runtime log is stored in RAM and is lost on reboot. Errors are also copied to the bounded persistent audit log, while operation records live in each volume's SQLite database.

If this warning is ignored, manually deleting a dataset's .RecycleBin permanently loses every contained item and that dataset's SQLite history. The plugin has no daemon holding the deleted database; a later recycle operation recreates an empty directory and schema and continues normally. Deleting it concurrently with an operation can make that request fail, but the failure remains inside the plugin request.

No independent hourly or daily maintenance task is installed. Entering a scheduled-cleanup cron expression in Settings creates the plugin's only automatic task through Unraid's update_cron; leaving it empty creates no cron entry. At the selected time the enabled bins are emptied and database/history maintenance runs in the same job.

Uninstall

Open Plugins, select Dynamix File Recycle Bin, and click Remove. From a terminal, the equivalent Plugin Manager command is:

/usr/local/emhttp/plugins/dynamix.plugin.manager/scripts/plugin remove \
  dynamix.file.recycle.plg

Uninstall removes plugin code, scheduled tasks and volatile logs. It preserves settings, the persistent audit log, and every .RecycleBin directory with its SQLite database. Inspect those directories manually before deleting them if a complete data wipe is required.

Reinstalling after removal therefore reuses the previous allowlist and other settings; it is not treated as a first installation with every supported volume selected.

Security

• Every API action requires an authenticated Unraid administrator session.
• Every request is POST-only and uses Unraid's native CSRF validation.
• A short-lived signed inspection token binds confirmation to the same path, inode and metadata that the server checked immediately before the move.
• Symlink aliases, path traversal, volume roots and nested mounts are rejected.
• Recycle, restore and purge transitions are recorded before and after the filesystem operation so interrupted operations can be recovered.

Support

GitHub Issues

License

MIT, see LICENSE.