omv8:omv8_plugins:snapraid-aio [omv-extras.org]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
\\
<html><center><b>SnapRAID AIO Plugin For OMV8</b></center></html>
\\
{{ :omvextras_logo4.jpg?400 |}}

====== SnapRAID AIO Plugin for OMV8 ======
===== Summary =====

SnapRAID AIO is an OpenMediaVault 8 plugin that wraps the popular
[[https://github.com/auanasgheps/snapraid-aio-script|snapraid-aio-script]]
around your SnapRAID arrays. It lets you configure, schedule, and monitor
one or more arrays independently from the OMV web interface, with support
for email, Apprise, and Healthchecks.io notifications, Docker container
management, sync/scrub thresholds, and custom hooks.

This plugin **requires** the [[omv8:omv8_plugins:snapraid|openmediavault-snapraid]]
plugin to be installed first. That plugin provides the SnapRAID binary and
the array configuration that this plugin reads.

SnapRAID AIO is a **full replacement for the built-in diff script** included
in the openmediavault-snapraid plugin. It covers everything the diff script
does (sync, scrub, notifications) and adds significantly more control.

<html>
<body>
  <table width="100%" border="0">
    <tr>
      <td colspan="2" style="background-color:#69A5FF;height:30px;">
        <strong><span style="color:#FFFFFF;font-size:110%;">&#160; Note</span></strong>
      </td>
    </tr>
    <tr>
      <td style="background-color:#E6FEFF;height:25px;width:380px;">
If you are currently using the built-in diff script, disable its schedule
before enabling SnapRAID AIO. Running both against the same array at the
same time will cause conflicts.
    </tr>
  </table>
</body>
</html>

> SnapRAID AIO is third-party software. For questions about the underlying
> script, see the [[https://github.com/auanasgheps/snapraid-aio-script|upstream repository]].

===== Prerequisites =====

  * **openmediavault-snapraid** installed and at least one array configured.
  * **omv-extras** installed (required to install this plugin).
  * Email notifications configured under //System → Notification// if you want email alerts.
  * For disk spindown: **hd-idle** installed manually.
  * For Docker management: Docker running on the same host.
  * For Apprise notifications: internet access (Apprise is installed automatically via pipx on first run).

===== Installation =====

  - Navigate to //System → Plugins//.
  - Search for **snapraid-aio**.
  - Click **Install**.

===== Quick Start =====

After installation a new entry **SnapRAID AIO** appears in the **Services** menu.

The recommended workflow for a new array:

  - In the SnapRAID plugin, create and configure your array (parity, data disks).
  - Run an initial **sync** from the SnapRAID plugin so the parity is established.
  - Open **Services → SnapRAID AIO**.
  - Click **Create** and select your array.
  - Configure notifications, thresholds, and scrub settings.
  - Click **Schedule** to set up the automated run.

<html>
<body>
  <table width="100%" border="0">
    <tr>
      <td colspan="2" style="background-color:#FFB663;height:30px;">
        <strong><span style="color:#FFFFFF;font-size:110%;">&#160; Warning </span></strong>
      </td>
    </tr>
    <tr>
      <td style="background-color:#FFE4A6;height:25px;width:380px;">
Always run an initial sync before scheduling SnapRAID AIO.
The AIO script expects parity to already exist and will not create it from scratch.
You can run the initial sync from SnaRAID plugin or from AIO itself using "Sync" feature.
    </tr>
  </table>
</body>
</html>

===== Config List =====

The main view shows a table of all AIO configurations.

{{:omv8:omv8_plugins:snapraid-aio8-1.png?800|}}

^ Column ^ Description ^
| Array | Human-readable name of the SnapRAID array |
| Scheduled | Check mark if an automated schedule is configured |
| Last Run | Timestamp and outcome of the last script execution (OK / WARNING / Started) |
| Config File | Path to the underlying SnapRAID .conf file |

==== Toolbar Actions ====

^ Action ^ Description ^
| **Create** | Add a new AIO configuration |
| **Edit** | Modify the selected configuration |
| **Schedule** | Configure or change the cron schedule for this configuration |
| **Delete** | Remove the configuration, its generated config file, and its cron entry |

==== Tools Menu ====

Each row has a **Tools** submenu with the following actions:

^ Tool ^ Description ^
| **Run Now** | Execute the AIO script immediately for this array |
| **Force Sync** | Run the AIO script bypassing delete and update thresholds (use with caution) |
| **Sync** | Run a raw `snapraid sync` — useful after initial array setup before the first AIO run |
| **Last Log** | Display the most recent log file produced by this array's script run |

{{:omv8:omv8_plugins:snapraid-aio8-2.png?200|}}

===== Configuration Form =====

The configuration form is divided into several sections.

{{:omv8:omv8_plugins:snapraid-aio8-3.png?600|}}

==== Array Selection ====

The top of the form contains a single required field:

  * **SnapRAID array** — select the array this configuration applies to. Each array can have only one AIO configuration. The dropdown is populated from arrays defined in the SnapRAID plugin.

==== Email Notifications ====

  * **Enable email notifications** — sends a report email after each run using OMV's configured notification address (//System → Notification//). When enabled, the sender and receiver addresses are shown read-only, pulled directly from the OMV system configuration.

==== Healthchecks.io ====

  * **Enable Healthchecks.io** — reports script completion or failure to a [[https://healthchecks.io|Healthchecks.io]] ping URL. Any warning in the script run counts as a failure.
  * **Healthchecks UUID** — the UUID portion of your ping URL (not the full URL).
  * **Healthchecks URL** — override for self-hosted instances. Must end with a trailing slash. Defaults to https://hc-ping.com/.

==== Apprise Notifications ====

[[https://github.com/caronc/apprise|Apprise]] is a unified notification library supporting Telegram, Discord, Slack, Gotify, Ntfy, Pushover, and dozens of other services. It is installed automatically via `pipx` on the first run if enabled.

<html>
<body>
  <table width="100%" border="0">
    <tr>
      <td colspan="2" style="background-color:#69A5FF;height:30px;">
        <strong><span style="color:#FFFFFF;font-size:110%;">&#160; Note</span></strong>
      </td>
    </tr>
    <tr>
      <td style="background-color:#E6FEFF;height:25px;width:380px;">
Apprise is installed automatically via `pipx` the first time the script runs with Apprise enabled. No manual installation is needed, but internet access is required on that first run.
    </tr>
  </table>
</body>
</html>

{{:omv8:omv8_plugins:snapraid-aio8-4.png?800|}}
  * **Enable Apprise** — master toggle for Apprise notifications.
  * **Apprise URLs** — one or more service URLs in Apprise format <nowiki>(e.g. `tgram://token/chatid`)</nowiki>. Enter each URL and press Enter to add it as a chip. Multiple services are supported. Service documentation and configuration instructions can be found [[https://appriseit.com/services/|here]].
  * **Attach report on warnings** — attaches the full run report to the notification when a warning is issued. Not all services support attachments.
  * **Test Apprise** button — sends a test notification immediately using the saved URLs. Only available after saving the configuration. It is located at the bottom of the configuration page.

==== Apprise Email ====

Apprise can also send email directly via SMTP or provider-specific URLs, independently of OMV's built-in notification system.

  * **Enable Apprise email** — toggle for Apprise-based email.
  * **Apprise Email URL** — SMTP or provider URL in Apprise format (e.g. <nowiki>`mailtos://user:pass@smtp.example.com`</nowiki>).
  * **Attach report on warnings** — same as above.
  * **Test Apprise email** button — sends a test email using the configured URL. It is located at the bottom of the configuration page.

==== Sync Thresholds ====

Thresholds prevent accidental mass deletions or updates from being synced to parity. The script aborts and issues a warning when a threshold is exceeded, unless the warning count reaches the configured limit.

{{:omv8:omv8_plugins:snapraid-aio8-5.png?800|}}

  * **Delete threshold** — abort sync if more than N files were deleted since the last run. Set to `0` to disable. Default: 500.
  * **Update threshold** — abort sync if more than N files were updated since the last run. Set to `0` to disable. Default: 500.
  * **Add/Delete ratio threshold** — allow sync despite the delete threshold if a sufficient proportion of deletes are accompanied by matching adds (e.g. a large rename operation). Value is a ratio between 0.0 and 1.0. Set to `0` to disable.
  * **Sync warning threshold** — how many times a threshold warning fires before the sync is forced anyway. `0` = always force sync past thresholds. `-1` = never force (always require manual override). Default: -1.

==== Scrub Settings ====

SnapRAID scrub verifies stored parity data against your files to detect silent bit-rot.

  * **Scrub percentage** — percentage of the array to verify per run. Lower values spread verification over many runs. Default: 5%.
  * **Scrub age (days)** — only scrub blocks that have not been verified within the last N days. Default: 10.
  * **Scrub new blocks after sync** — immediately scrub any blocks newly added during this sync run.
  * **Scrub every N runs** — run a scrub only every N script executions (e.g. `7` = weekly if you run daily). `0` = scrub every run.

==== SnapRAID Options ====
{{:omv8:omv8_plugins:snapraid-aio8-6.png?800|}}

  * **Pre-hash data** — read data twice before syncing to detect silent read errors before they reach parity. Recommended. Default: enabled.
  * **Sync zero-sized files** — SnapRAID skips empty files by default; enable this to include them.
  * **Spin down disks when done** — spin down drives after the script completes using `hd-idle`. Requires hd-idle to be installed separately, see [[https://forum.openmediavault.org/index.php?thread/37438-how-to-spin-down-hard-drives-with-hd-idle/|this guide]] for more information and how to install it.

<html>
<body>
  <table width="100%" border="0">
    <tr>
      <td colspan="2" style="background-color:#FFB663;height:30px;">
        <strong><span style="color:#FFFFFF;font-size:110%;">&#160; Warning </span></strong>
      </td>
    </tr>
    <tr>
      <td style="background-color:#FFE4A6;height:25px;width:380px;">
Disk spindown requires hd-idle to be installed on the system. It is not installed automatically. Without it, the setting has no effect.
    </tr>
  </table>
</body>
</html>
  * **Verbose output in notification** — include full SnapRAID command output in notification messages. Not recommended for large arrays — produces very large messages.
  * **Log retention (days)** — delete log files older than N days. `0` = keep forever.
  * **SnapRAID log directory** — directory where per-run log files (`SnapRAID-*.txt`) are written. Leave empty to use `/root`. Also used by the **Last Log** tool action.
  * **Log SMART data** — include SMART drive health data in the run log. Default: enabled.
  * **Include SMART data in notification** — include SMART output in notification messages.
  * **Log SnapRAID status** — run `snapraid status` and include the output in the log.
  * **Include status in notification** — include the status output in notification messages.
  * **Ignore pattern** — space-separated glob patterns to exclude from diff counts only (files matching these patterns are not counted against the delete/update thresholds). This does not affect SnapRAID itself.

==== Docker and Service Management ====

{{:omv8:omv8_plugins:snapraid-aio8-7.png?800|}}

When enabled, the script pauses or stops your Docker containers before running SnapRAID operations and restores them afterward, preventing open-file conflicts.

  * **Manage Docker containers / services** — master toggle for Docker management.
  * **Docker mode** — `Pause/unpause` (faster, less disruptive) or `Stop/restart` (full stop, needed for some containers).
  * **Docker containers** — select which containers to manage. The list is populated from currently running containers.
  * **Service start delay (seconds)** — seconds to wait after restarting services before the script continues.

==== Custom Hooks ====

Custom hooks let you run arbitrary shell commands or scripts before and after the SnapRAID operations.

  * **Enable custom hooks** — master toggle.
  * **Before hook name** — display name shown in the log output.
  * **Before hook command** — shell command or script path executed before SnapRAID runs. Runs as root.
  * **After hook name** — display name shown in the log output.
  * **After hook command** — shell command or script path executed after SnapRAID completes. Runs as root.
  * **Execute after hook before spindown** — when disk spindown is enabled, run the after hook before spinning down the disks instead of after.

===== Scheduling =====

Each configuration has its own independent schedule. Click the **Schedule** button on a row to open the schedule form.

{{:omv8:omv8_plugins:snapraid-aio8-8.png?800|}}

^ Field ^ Description ^
| Enable | Enable or disable this schedule without deleting it |
| Time of execution | Preset intervals (Hourly, Daily, Weekly, etc.) or Custom for full cron control |
| Minute / Hour / Day of month / Month / Day of week | Active when Time of execution is set to Custom |
| Send email on completion | OMV-level cron email (separate from AIO script notifications) |
| Comment | Label shown in the OMV cron list; auto-filled with the array name |

The cron job runs as root and calls:
<code>
/usr/sbin/snapraid-aio-script.sh --config /etc/snapraid-aio-<uuid>.conf
</code>

===== Notes =====

==== Log Files ====

Each script run produces a dated log file (`SnapRAID-YYYY-MM-DD_HH-MM-SS.txt`) in the configured log directory. These are the files shown by the **Last Log** tool. A central summary log at `/var/log/snapraid.log` is also maintained and is used to populate the **Last Run** column in the config list.

==== Per-Array State Files ====

The plugin stores two counter files per configuration in `/var/lib/snapraidaio/`:

  * `<uuid>.warnCount` — tracks how many consecutive threshold warnings have fired, used against the Sync warning threshold.
  * `<uuid>.scrubCount` — tracks run count for the Scrub every N runs feature.

These files are removed when the configuration is deleted.

==== Force Sync ====

<html>
<body>
  <table width="100%" border="0">
    <tr>
      <td colspan="2" style="background-color:#69A5FF;height:30px;">
        <strong><span style="color:#FFFFFF;font-size:110%;">&#160; Note</span></strong>
      </td>
    </tr>
    <tr>
      <td style="background-color:#E6FEFF;height:25px;width:380px;">
Force Sync bypasses all delete and update thresholds and syncs unconditionally.
Only use this when you are certain the changes are intentional (e.g. after a large
planned deletion or reorganization). You will be asked to confirm before the action runs.
    </tr>
  </table>
</body>
</html>

===== Troubleshooting =====

^ Symptom ^ Likely cause ^ Resolution ^
| No arrays appear in the selector | SnapRAID plugin not installed or no arrays configured | Install openmediavault-snapraid and create at least one array |
| Last Run shows WARNING | Threshold exceeded, or SnapRAID reported an error | Check the run log via Tools → Last Log |
| Apprise test fails | Apprise not yet installed, or URL incorrect | Verify the URL format against the Apprise documentation; check that pipx is available |
| Schedule shows "not scheduled" after saving | Schedule was not yet created | Click Schedule on the row and configure a time |
| Docker containers not being managed | Wrong mode, or containers not running when config was saved | Refresh the container list by editing the config |

===== Source Code =====

  * [[https://github.com/auanasgheps/openmediavault-snapraid-aio|openmediavault-snapraid-aio on GitHub]]
  * [[https://github.com/auanasgheps/snapraid-aio-script|snapraid-aio-script on GitHub]]