[Plugin] USB Guardian - Safe USB Eject for Unraid

Safely eject supported USB storage devices managed by Unassigned Devices directly from the Unraid web UI.

USB Guardian does not treat an ordinary unmount as permission to unplug. It verifies device identity and usage, performs a strict normal unmount, flushes caches, requests logical USB removal, and checks shfs health before it displays Safe to unplug.

## Install

### Unraid Community Applications

In Unraid, go to Apps and search for:

```text

USB Guardian

```

### Unraid Plugin Manager

In Unraid, go to Plugins > Install Plugin and paste:

```text

https://raw.githubusercontent.com/xO-ox-ai/unraid-usb-guardian/main/usb.guardian.plg

```

USB Guardian requires Unraid 7.2.4 or newer and the Unassigned Devices plugin.

## Basic Usage

1. Open Main > Unassigned Devices and mount a supported USB drive normally.

2. Click the eject icon next to the device name.

3. If a yellow warning is shown, open it to see the exact blocking reason and suggested action.

4. Leave the device connected while the guarded eject transaction is running.

5. Physically unplug the device only after the green Safe to unplug message appears.

> Important: An unmounted status by itself is not permission to unplug. USB Guardian never uses forced or lazy unmounting and never kills processes automatically. If safety cannot be proven, it stops and leaves the device connected.

The current beta supports only USB mass-storage devices whose complete identity and state can be verified. Unsupported layouts, active shares or scripts, busy files, passthrough assignments, multiple active mounts, and other unsafe states are blocked with an explanation.

## Uninstall

Make sure no safe-eject job is running. Open USB Guardian on the Unraid Plugins page and click Remove, or run:

```bash

removeplg /boot/config/plugins/usb.guardian.plg

```

Configuration and forensic logs are retained under /boot/config/plugins/usb.guardian/ after a normal uninstall.

## Troubleshooting

If the eject icon does not appear, confirm that the device is a mounted USB mass-storage device supported by the current beta, then refresh the Main page.

If USB Guardian refuses to eject a device, open the yellow warning and resolve the reported process, share, script, mount, passthrough, or device-layout condition. Do not work around the refusal with a forced or lazy unmount.

If the UI looks stale after an update, perform a hard refresh with Ctrl+Shift+R.

For crashes, hangs, or unexpected reboots, enable flash-mirrored or remote syslog before testing. Download the USB Guardian diagnostics bundle from Settings > USB Guardian > Download diagnostics after the system returns.

Persistent plugin logs are stored at:

```text

/boot/config/plugins/usb.guardian/logs/

```

USB Guardian is beta software. It does not modify or claim to fix shfs, libfuse, the Linux kernel, or the Unassigned Devices unmount implementation.

## Support

- Issues: [GitHub Issues](https://github.com/xO-ox-ai/unraid-usb-guardian/issues)

- Documentation: [GitHub repository](https://github.com/xO-ox-ai/unraid-usb-guardian)

- Release:(https://github.com/xO-ox-ai/unraid-usb-guardian/releases/tag/v0.1.0-beta3)

Edited July 17Jul 17 by caeser2