snapraid/manual-daemon.html

2549 lines
100 KiB
HTML
Raw Normal View History

2026-02-14 09:40:46 +01:00
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="description" content="A backup program for disk arrays. It stores parity information of your data and it recovers from up to six disk failures">
<meta name="keywords" content="snapraid snapshot raid backup disk array redundancy parity">
<title>SnapRAID Daemon Manual</title>
<link rel="stylesheet" href="style.css">
2026-04-14 09:53:56 +02:00
<link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png">
<link rel="icon" type="image/png" sizes="32x32" href="/favicon-32x32.png">
<link rel="icon" type="image/png" sizes="16x16" href="/favicon-16x16.png">
<link rel="manifest" href="/site.webmanifest">
2026-02-14 09:40:46 +01:00
<script src="script.js"></script>
<!-- Google Analytics 4 -->
<!-- Google tag (gtag.js) -->
<script async src="https://www.googletagmanager.com/gtag/js?id=G-W1Z5FKHYQ4"></script>
<script>
window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());
gtag('config', 'G-W1Z5FKHYQ4');
</script>
<!-- Google Universal Analytics -->
<script type="text/javascript">
var _gaq = _gaq || [];
_gaq.push(['_setAccount', 'UA-21967501-1']);
_gaq.push(['_trackPageview']);
(function() {
var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
})();
</script>
</head>
<body>
<header>
<div class="container nav-container">
<a href="index" class="logo">
2026-02-24 00:06:55 +01:00
<img src="android-chrome-192x192.png" width="32" height="32"/>
2026-02-14 09:40:46 +01:00
SnapRAID
</a>
<nav>
<input type="checkbox" id="menu-toggle">
<label for="menu-toggle" class="menu-icon"><svg viewBox="0 0 24 24" width="24" height="24" fill="currentColor"><path d="M3 18h18v-2H3v2zm0-5h18v-2H3v2zm0-7v2h18V6H3z"/></svg></label>
<ul>
<li><a href="index" >Home</a></li>
<li><a href="ui" >UI & Daemon</a></li>
<li><a href="howitworks" >How it Works</a></li>
<li><a href="design" >Design</a></li>
<li><a href="compare" >Compare</a></li>
<li><a href="manual" class="active">Manual</a></li>
<li><a href="faq" >FAQ</a></li>
<li><a href="support" >Support</a></li>
<li><a href="download" class="nav-cta">Download</a></li>
2026-03-17 23:49:03 +01:00
<li>
<button class="theme-toggle" aria-label="Toggle theme">
<svg class="sun-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="5"></circle><line x1="12" y1="1" x2="12" y2="3"></line><line x1="12" y1="21" x2="12" y2="23"></line><line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line><line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line><line x1="1" y1="12" x2="3" y2="12"></line><line x1="21" y1="12" x2="23" y2="12"></line><line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line><line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line></svg>
<svg class="moon-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z"></path></svg>
</button>
</li>
2026-02-14 09:40:46 +01:00
</ul>
</nav>
</div>
</header>
<div class="container manual-layout">
<aside class="manual-sidebar">
2026-02-14 09:41:40 +01:00
<h4>Components</h4>
2026-02-14 09:40:46 +01:00
<select id="manual-selector" style="width: 100%; padding: 5px; background: var(--bg-surface); color: var(--text-primary); border: 1px solid var(--border-color); border-radius: 4px; margin-bottom: 2rem;">
2026-02-19 18:08:30 +01:00
<option value="manual">Command Line</option>
<option value="manual-daemon">Daemon</option>
<option value="manual-log">Log</option>
2026-02-14 09:40:46 +01:00
</select>
<h4>Contents</h4>
<ul id="manual-toc-list">
<!-- Populated by JavaScript -->
</ul>
</aside>
<main id="manual-container">
<div class="manual-doc">
<div class="manual-section-level-1">
<h1 id="sec1" class="manual-title-level-1">
Synopsis
</h1>
<pre>
2026-10-29 06:56:28 +01:00
snapraidd [-c, --conf CONFIG] [-C, --engine-conf FILE] [-i, --instance NAME]
&nbsp;&nbsp;&nbsp;&nbsp;[-f, --foreground] [-p, --pidfile FILE] [-N, --no-cache]
&nbsp;&nbsp;&nbsp;&nbsp;[-v, --verbose]
</pre>
<pre>
snapraidd [-i, --instance NAME] [--service-install] [--service-remove]
&nbsp;&nbsp;&nbsp;&nbsp;[--service-start-all] [--service-stop-all] [--service-remove-all]
&nbsp;&nbsp;&nbsp;&nbsp;[--service-list]
</pre>
<pre>
snapraidd [-g, --gen-auth USERNAME:PASSWORD]
2026-02-14 09:40:46 +01:00
</pre>
<pre>
snapraidd [-V, --version] [-H, --help]
</pre>
</div>
<div class="manual-section-level-1">
<h1 id="sec2" class="manual-title-level-1">
Description
</h1>
2026-03-01 13:22:36 +01:00
<p>SnapRAID Daemon is a specialized companion service designed to move SnapRAID
2026-03-08 17:40:50 +01:00
from a manual, command-line interface (CLI) workflow to an <b>always-on</b>
2026-02-14 09:40:46 +01:00
background service.
</p><p>Under the hood, the daemon uses the same SnapRAID CLI binary, providing the
same level of reliability.
</p><p>The daemon automates critical maintenance tasks, including the scheduling of
sync and scrub operations. It further enhances array reliability by monitoring
SMART values and providing a robust notification engine for real-time health
updates. For energy efficiency, it manages automatic disk spindown during
periods of inactivity.
</p><p>The daemon provides a modern REST API interface along with an integrated Web UI.
This allows you to monitor array health, trigger maintenance tasks, and
configure the daemon through a user-friendly browser interface or programmatically
via the API.
</p></div>
<div class="manual-section-level-1">
<h1 id="sec3" class="manual-title-level-1">
Options
</h1>
<p>The SnapRAID Daemon provides the following options:
</p><div class="manual-option-list">
<div class="manual-option-entry">
<div class="manual-option-name">
-c, --conf CONFIG
</div><div class="manual-option-description">
Specifies the path to the configuration file. Default:
2026-02-19 17:18:37 +01:00
<b>$PREFIX/etc/snapraidd.conf</b> and <b>/etc/snapraidd.conf</b> if
2026-02-14 09:40:46 +01:00
not found. The $PREFIX variable represents the installation
2026-02-19 17:18:37 +01:00
path chosen at build time (typically via the <b>--prefix</b>
2026-02-14 09:40:46 +01:00
argument to the configure script).
2026-02-19 17:18:37 +01:00
</div>
</div>
</div>
2026-02-14 09:40:46 +01:00
<div class="manual-option-list">
<div class="manual-option-entry">
<div class="manual-option-name">
2026-10-29 06:56:28 +01:00
-C, --engine-conf FILE
</div><div class="manual-option-description">
Specifies the path to the SnapRAID array configuration file.
If not specified, the SnapRAID engine's default configuration resolution is used.
</div>
</div>
</div>
<div class="manual-option-list">
<div class="manual-option-entry">
<div class="manual-option-name">
2026-02-14 09:40:46 +01:00
-f, --foreground
</div><div class="manual-option-description">
Runs the process in the foreground. This prevents the
daemon from detaching from the terminal (daemonizing).
2026-02-19 17:18:37 +01:00
</div>
</div>
</div>
2026-02-14 09:40:46 +01:00
<div class="manual-option-list">
<div class="manual-option-entry">
<div class="manual-option-name">
2026-10-29 06:56:28 +01:00
-i, --instance NAME
</div><div class="manual-option-description">
Specifies the daemon instance name. When running multiple
instances of the daemon, this option separates their namespaces
(e.g., config file suffix, PID file, logging identifiers, and
Windows service names). The name must only contain alphanumeric
characters, hyphens, and underscores, with a maximum length of 63
characters. On Windows, instance names are converted to lowercase
because Windows service names are case-insensitive. On Unix, the
supplied letter case is preserved.
</div>
</div>
</div>
<div class="manual-option-list">
<div class="manual-option-entry">
<div class="manual-option-name">
2026-02-14 09:40:46 +01:00
-p, --pidfile FILE
</div><div class="manual-option-description">
Overrides the default location for the PID file. Default:
2026-02-19 17:18:37 +01:00
<b>/run/snapraidd.pid</b>.
</div>
</div>
</div>
2026-02-14 09:40:46 +01:00
<div class="manual-option-list">
<div class="manual-option-entry">
<div class="manual-option-name">
-N, --no-cache
</div><div class="manual-option-description">
Forces the daemon to load web interface assets directly from the
filesystem for every request, bypassing internal memory caching.
This is intended for development environments to allow real-time
testing of UI changes.
2026-02-19 17:37:33 +01:00
This option is only effective when <b>net_web_root</b> is configured
to point to an expanded directory on the filesystem.
It has no effect if the web assets are being served from a
compressed .zip file, as the daemon must crawl and index the
archive's contents at startup regardless of this flag.
2026-02-14 09:40:46 +01:00
This option is not recommended for production use due to the
increased I/O overhead and for security reasons, as it could
potentially expose the system to directory traversal
vulnerabilities if not properly isolated.
2026-02-19 17:18:37 +01:00
</div>
</div>
</div>
2026-02-14 09:40:46 +01:00
<div class="manual-option-list">
<div class="manual-option-entry">
<div class="manual-option-name">
-v, --verbose
</div><div class="manual-option-description">
Verbose logging including all HTTP requests.
2026-02-19 17:18:37 +01:00
</div>
</div>
</div>
2026-02-14 09:40:46 +01:00
<div class="manual-option-list">
<div class="manual-option-entry">
<div class="manual-option-name">
2026-10-29 06:56:28 +01:00
-g, --gen-auth USERNAME:PASSWORD
</div><div class="manual-option-description">
Generates a secure Argon2id credential string for the configured
username and password, and prints the configuration line ready to
be added to the <b>snapraidd.conf</b> file.
</div>
</div>
</div>
<div class="manual-option-list">
<div class="manual-option-entry">
<div class="manual-option-name">
--service-install
</div><div class="manual-option-description">
[Windows Only] Installs and starts the current configuration as a Windows service.
If an instance name is specified using the <b>-i</b> option, a dedicated
service is created and started for that instance. This allows running
multiple instances of the daemon simultaneously.
</div>
</div>
</div>
<div class="manual-option-list">
<div class="manual-option-entry">
<div class="manual-option-name">
--service-remove
</div><div class="manual-option-description">
[Windows Only] Stops and removes the Windows service associated with the
current configuration. If an instance name is specified using <b>-i</b>,
only that specific instance service is stopped and removed.
</div>
</div>
</div>
<div class="manual-option-list">
<div class="manual-option-entry">
<div class="manual-option-name">
--service-start-all
</div><div class="manual-option-description">
[Windows Only] Starts all Windows services associated with SnapRAID Daemon
(i.e., all services starting with <b>snapraidd</b>).
</div>
</div>
</div>
<div class="manual-option-list">
<div class="manual-option-entry">
<div class="manual-option-name">
--service-stop-all
</div><div class="manual-option-description">
[Windows Only] Stops all Windows services associated with SnapRAID Daemon.
</div>
</div>
</div>
<div class="manual-option-list">
<div class="manual-option-entry">
<div class="manual-option-name">
--service-remove-all
</div><div class="manual-option-description">
[Windows Only] Stops and removes all Windows services associated with
SnapRAID Daemon.
</div>
</div>
</div>
<div class="manual-option-list">
<div class="manual-option-entry">
<div class="manual-option-name">
--service-list
</div><div class="manual-option-description">
[Windows Only] Lists all registered Windows services associated with
SnapRAID Daemon and their current execution status.
</div>
</div>
</div>
<div class="manual-option-list">
<div class="manual-option-entry">
<div class="manual-option-name">
2026-02-14 09:40:46 +01:00
-H, --help
</div><div class="manual-option-description">
Prints a short help screen.
2026-02-19 17:18:37 +01:00
</div>
</div>
</div>
2026-02-14 09:40:46 +01:00
<div class="manual-option-list">
<div class="manual-option-entry">
<div class="manual-option-name">
-V, --version
</div><div class="manual-option-description">
Prints the program version.
2026-02-19 17:18:37 +01:00
</div>
</div>
</div>
2026-02-14 09:40:46 +01:00
</div>
<div class="manual-section-level-1">
<h1 id="sec4" class="manual-title-level-1">
2026-03-01 12:11:35 +01:00
Getting Started
2026-02-14 09:40:46 +01:00
</h1>
2026-03-01 12:11:35 +01:00
<p>The daemon acts as a management layer for the SnapRAID CLI. Therefore,
2026-03-15 18:52:43 +01:00
SnapRAID CLI must be installed and fully configured before starting the
service.
2026-03-17 00:12:13 +01:00
</p><p>Because the daemon performs direct hardware-level telemetry probes
(such as reading SMART attributes and managing disk power states), it
requires elevated privileges to function correctly. On Linux systems,
the daemon must be run as the root user. On Windows, it must be
executed as a service with equivalent system access rights.
</p><p>It is important to note that the daemon never directly reads the
SnapRAID CLI configuration file <b>snapraid.conf</b>. Instead, it relies
entirely on the output and logs generated by the SnapRAID binary.
</p><p>By processing these logs, the daemon identifies the <b>data</b>, <b>parity</b>,
and <b>extra</b> disks and establishes the current state of the array.
2026-03-15 18:52:43 +01:00
</p><p>During the installation process of the daemon, a default configuration
file is provisioned to enable the REST API and the Web UI. For users
installing via binary packages, this file is typically placed at
<b>/etc/snapraidd.conf</b>. If you are installing from source, it is
2026-04-13 23:16:13 +02:00
recommended to run <b>./configure --prefix=/usr --sysconfdir=/etc</b>
during the build process to ensure the program is installed in the
standard <b>/usr</b> directory, and the configuration is placed in the
standard <b>/etc</b> directory.
2026-03-01 13:22:36 +01:00
</p><p>Using this default configuration file, the UI is accessible locally
via a web browser at the following address:
2026-03-15 18:52:43 +01:00
</p><p><a href="http://localhost:7627">http://localhost:7627</a>
2026-03-01 12:11:35 +01:00
<br>
</p><p>The default port, 7627, was chosen as a mnemonic, representing the
2026-03-17 00:12:13 +01:00
word <b>SNAP</b> as typed on a standard telephone keypad.
2026-03-01 12:11:35 +01:00
</p><p>At startup, the daemon parses historical logs from <b>/var/log/snapraid</b>
to reconstruct the current state of the array. These logs are
generated and saved by the daemon itself during the execution
of SnapRAID CLI commands. Consequently, on the very first run, this
directory will be empty.
</p><p>In this initial scenario, the daemon automatically triggers a SnapRAID
<b>read</b> command. This allows SnapRAID to process its internal <b>content</b>
files and provide the daemon with the necessary metadata to establish
the array's baseline state.
</p><p>Once the service is running, you should review <b>/etc/snapraidd.conf</b>
2026-03-01 13:22:36 +01:00
or use the <b>Settings</b> panel in the UI to tailor the behavior to your
2026-03-01 12:11:35 +01:00
environment.
</p><p>Typical post-installation steps include:
</p><ul>
<li>
Defining a <b>maintenance_schedule</b> for automated sync and scrub
operations.
</li>
<li>
Setting <b>spindown_idle_minutes</b> to optimize energy usage for
disks not in active use.
</li>
<li>
Configuring the <b>notify_result</b> system to receive alerts
regarding array health and task outcomes.
</li>
</ul>
2026-10-29 06:56:28 +01:00
<p>To make manual changes to runtime-reloadable options in the
<b>/etc/snapraidd.conf</b> file effective, send a <b>SIGHUP</b> signal to the
running process. Changes to <b>sys_*</b> options require a daemon restart.
2026-03-01 12:11:35 +01:00
</p><p>Example:
</p><pre>
sudo killall -HUP snapraidd
</pre>
2026-03-01 13:22:36 +01:00
<p>Unlike manual file edits, changes made through the UI are applied to
the running process and saved to the configuration file pressing the
<b>Save</b> button.
</p><p>By default, the daemon binds to the loopback interface, meaning the
2026-03-01 12:11:35 +01:00
UI is accessible only from the local machine and not from other devices
2026-03-01 13:22:36 +01:00
on the network. To allow access from other devices on the network,
you must modify the <b>net_*</b> options to bind the daemon to a reachable
network interface.
2026-03-01 12:11:35 +01:00
</p></div>
<div class="manual-section-level-1">
<h1 id="sec5" class="manual-title-level-1">
Health
</h1>
<p>The array's aggregate health is determined by evaluating historical log
data alongside real-time hardware telemetry.
2026-10-29 06:56:28 +01:00
</p><p>If the array transitions into a problematic health state, the daemon
issues an alert through the configured notification system.
The PENDING state is informational and does not by itself trigger an alert.
Note that the detection of such states is not instantaneous, it occurs
during the telemetry collection cycle, the frequency of which is determined
by the <b>probe_interval_minutes</b> option.
2026-03-01 13:22:36 +01:00
</p><p>In the REST API, the health state is reported by the <b>health</b> field.
2026-03-01 12:11:35 +01:00
Whenever the health is not PASSED, a supplementary <b>health_reason</b> field
is provided to give a discursive explanation of the specific condition or
failure detected.
</p><p>The Web UI also reflects these states by displaying a prominent top
banner across all pages if the health is in a problematic state. This
ensures that critical issues are visible regardless of the specific
dashboard view being accessed.
</p><p>The possible health states are:
2026-02-14 09:40:46 +01:00
</p><div class="manual-tag-list">
<div class="manual-tag-entry">
<div class="manual-tag-name">
2026-03-01 12:11:35 +01:00
PENDING
2026-02-14 09:40:46 +01:00
</div><div class="manual-tag-description">
2026-03-01 12:11:35 +01:00
The health has not yet been assessed. The daemon requires a
successful hardware probe where all disks are spinning at
least once to read SMART attributes.
Issuing an <b>up</b> command is sufficient to satisfy this.
2026-10-29 06:56:28 +01:00
PENDING is an informational state, not a problematic health
state, and does not by itself raise the severity of result
notifications.
2026-02-19 17:18:37 +01:00
</div>
</div>
2026-03-01 12:11:35 +01:00
<div class="manual-tag-entry">
<div class="manual-tag-name">
PASSED
</div><div class="manual-tag-description">
The array is fully healthy. All disks report positive SMART
status and the last scrub found no data corruption.
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
CORRUPT
</div><div class="manual-tag-description">
Silent errors (hash or parity mismatches) were detected, though
no physical hardware issues were identified.
In this state, scheduled maintenance remains active.
</div>
2026-02-19 17:18:37 +01:00
</div>
2026-02-14 09:40:46 +01:00
<div class="manual-tag-entry">
<div class="manual-tag-name">
2026-10-29 06:56:28 +01:00
DEGRADED
</div><div class="manual-tag-description">
The filesystem UUID does not match the UUID recorded in the
content file, or an associated physical device is currently disconnected.
This typically indicates that the expected filesystem might not be
present at the mount point (for example, if the disk is not mounted),
or that the storage configuration is incomplete (such as a missing member
of a multi-device volume), representing a serious array condition without
implying physical hardware failure.
Automated maintenance is suspended in this state, and manual
intervention is required.
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
2026-03-01 12:11:35 +01:00
PREFAIL
2026-02-14 09:40:46 +01:00
</div><div class="manual-tag-description">
2026-10-29 06:56:28 +01:00
The SMART telemetry reports a pre-failing condition, or a
task encountered input/output errors while accessing files.
2026-03-01 12:11:35 +01:00
Automated maintenance is suspended in this state, and manual
intervention is required.
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
FAILING
</div><div class="manual-tag-description">
The SMART telemetry reports a critical failing condition, or a
disk has disappeared from the system.
Automated maintenance is suspended in this state, and immediate
manual intervention is required.
</div>
</div>
</div>
2026-10-29 06:56:28 +01:00
<p>Physical Input/Output errors also affect disk health. Data and parity
I/O errors that SnapRAID can associate with a block, as well as I/O
errors associated with a concrete filesystem object, are tracked as
transient disk errors. Transient disk errors remain active until a later
scrub reports that no blocks are bad.
</p><p>By contrast, unlocalized data and parity I/O errors, such as close errors,
are still counted in the lifetime error_io counter but do not affect disk
health.
</p><p>Individual tasks also maintain a health state reflecting only the
2026-03-01 12:11:35 +01:00
problems identified during that specific operation.
For example, an array in a CORRUPT state may still produce a PASSED
result for a <b>probe</b> task if that operation encountered no specific
errors.
2026-10-29 06:56:28 +01:00
</p><p>In the DEGRADED, PREFAIL or FAILING state, the <b>Maintenance</b> button in the Web
2026-04-07 17:57:02 +02:00
UI is replaced with a <b>Refresh</b> button. This allows you to force the
daemon to re-scan the state of the array (by re-reading the content
file) after any manual fixes have been performed via the command line.
2026-10-29 06:56:28 +01:00
</p><p>If the array entered the PREFAIL state due to input/output errors,
and the content file loaded after clicking <b>Refresh</b> contains no
marked bad sectors, the input/output error counters for each disk
are automatically cleared, allowing the array to re-enter the
PASSED state.
</p><p>Note that clicking the <b>Refresh</b> button does not cause the daemon
to verify that the underlying input/output errors are resolved.
Instead, the daemon assumes that you have:
</p><ul>
<li>
Checked the log files manually to understand the cause of the failure.
</li>
<li>
Resolved the root cause of the input/output errors.
</li>
<li>
Re-run the command that failed to ensure that the errors are gone.
</li>
<li>
Used the <b>fix</b> and <b>scrub</b> commands to restore any files that needed
to be recovered to clear any marked bad sectors.
</li>
</ul>
<p>If the underlying cause of the input/output errors is not resolved,
the errors will eventually reappear.
2026-03-01 12:11:35 +01:00
</p></div>
<div class="manual-section-level-1">
<h1 id="sec6" class="manual-title-level-1">
Configuration
</h1>
2026-04-07 17:57:02 +02:00
<p>The SnapRAID Daemon is configured via a plain-text <b>.conf</b> file,
defaulting to <b>$PREFIX/etc/snapraidd.conf</b> and if not found to
<b>/etc/snapraidd.conf</b>. The $PREFIX variable represents the installation
2026-03-01 12:11:35 +01:00
path chosen at build time (typically via the <b>--prefix</b> argument to
the configure script).
</p><p>This file governs the behavior of the automation engine, network
accessibility, safety interlocks, and hardware monitoring parameters.
2026-03-17 00:12:13 +01:00
</p><p>The configuration system is designed with a <b>triple-tier</b> management
2026-03-01 12:11:35 +01:00
philosophy to balance operational convenience with rigorous system
security:
2026-03-01 13:22:36 +01:00
</p><p>Tier 1 Core Network (Immutable) - This tier includes critical security
</p><p>and networking parameters, such as the master API toggle, port
bindings, and access control lists. These settings are completely
inaccessible via the REST API.
To modify them, you must perform a manual file edit followed
by a SIGHUP signal to reload the configuration into memory.
2026-03-01 12:11:35 +01:00
</p><p>Tier 2 Protected Operations (Secured) - These parameters involve
</p><p>security-sensitive automation, such as system user assignments,
external script paths, and logging policies. By default, these
options are read-only via the REST API. They can only be
modified via API PATCH requests if the <b>net_config_full_access</b>
flag is manually enabled in this file.
</p><p>Tier 3 Dynamic Logic (Live) - This tier consists of standard
</p><p>operational settings like maintenance schedules, scrub intensities,
and disk monitoring intervals. These parameters are fully
accessible and can be modified in real-time via the API.
2026-10-29 06:56:28 +01:00
Changes made through the REST interface are applied to
the running process and written back to this file
while preserving all existing manual comments.
</p><p>Configuration changes are not applied atomically to all runtime components
and existing operations. A successful configuration update means that
the new configuration has been accepted, but does not guarantee that
every component or previously scheduled task has already switched to it.
</p><p>After manually editing <b>/etc/snapraidd.conf</b>, apply the change before
making configuration changes through the API to prevent the daemon from
overwriting the manual edit with its memory state. Runtime-reloadable
options can be applied with a SIGHUP signal. Changes to <b>sys_*</b> options
require a daemon restart because a SIGHUP that changes them is rejected.
2026-03-01 12:11:35 +01:00
</p><p>Example:
</p><pre>
sudo killall -HUP snapraidd
</pre>
<p>For a comprehensive view of how these settings are applied in a
real-world environment, refer to the comments in the <b>snapraidd.conf</b>
file installed.
2026-02-14 09:40:46 +01:00
</p><div class="manual-section-level-2">
2026-03-01 12:11:35 +01:00
<h2 id="sec6-1" class="manual-title-level-2">
2026-03-08 17:40:50 +01:00
System
</h2>
<p>These settings control the core execution environment and the
underlying daemon.
2026-10-29 06:56:28 +01:00
</p><p>These options are not visible or modifiable via the REST API.
All <b>sys_*</b> options are read at daemon startup and changing any
of them requires a daemon restart. A SIGHUP reload which changes
a <b>sys_*</b> option is rejected and the previous configuration
remains active.
2026-03-08 17:40:50 +01:00
</p><div class="manual-section-level-3">
<h3 id="sec6-1-1" class="manual-title-level-3">
sys_engine
</h3>
<p>Sets the absolute path to the SnapRAID executable. If omitted,
the daemon searches /usr/bin and /usr/local/bin on Linux, /usr/bin
in Wine, and the daemon's base directory on Windows.
</p></div>
<div class="manual-section-level-3">
<h3 id="sec6-1-2" class="manual-title-level-3">
sys_log_directory
</h3>
<p>Defines where the output of individual SnapRAID commands is stored.
If left unset, the daemon defaults to /var/log/snapraid in Linux
and /log in the installation directory in Windows.
</p><p>Setting this option to an empty value (sys_log_directory = ) will
explicitly disable the saving of command output to persistent files.
</p><p>IMPORTANT: While it is possible to leave this empty to avoid saving files,
these logs are used by the daemon to reconstruct the past state of the
array (e.g., tracking the last successful sync or scrub). If no log
2026-03-17 00:12:13 +01:00
directory is provided, the daemon will lose its <b>memory</b> of previous
2026-03-08 17:40:50 +01:00
task results every time it is restarted.
</p></div>
<div class="manual-section-level-3">
<h3 id="sec6-1-3" class="manual-title-level-3">
sys_log_retention_days
</h3>
<p>To prevent your storage from filling up, sys_log_retention_days sets the
age at which old command logs are deleted. Logs are kept indefinitely
if this is set to 0 or left unset.
</p></div>
2026-10-29 06:56:28 +01:00
<div class="manual-section-level-3">
<h3 id="sec6-1-4" class="manual-title-level-3">
sys_log_compression
</h3>
<p>Enables compression of individual SnapRAID task log files in gzip (.gz)
format.
</p><p>Setting this option to 1 enables gzip compression, saving files with the
.log.gz extension. If set to 0 or left empty (the default), log files are
saved as plain text with the .log extension.
</p><p>Gzip compression requires the daemon to be built with zlib support. If
compression is enabled on a build without zlib, the daemon logs an error
and falls back to uncompressed logs.
</p><p>Changing this option only affects newly created task logs. Existing logs
(whether uncompressed .log or compressed .log.gz) continue to be read
transparently by the daemon when reconstructing array history, and are
purged by sys_log_retention_days regardless of format.
</p></div>
<div class="manual-section-level-3">
<h3 id="sec6-1-5" class="manual-title-level-3">
sys_shutdown_on
</h3>
<p>A comma-separated list of events that trigger an automatic system shutdown.
</p><p>Supported events are:
</p><div class="manual-tag-list">
<div class="manual-tag-entry">
<div class="manual-tag-name">
maintenance
</div><div class="manual-tag-description">
Shuts down the host after scheduled maintenance finishes
its finalization. Post-hooks and Docker unpause operations
are executed, and the final report is sent, before initiating
the shutdown, even if intermediate dependent phases (such as
scrub) were canceled due to errors. If an emergency shutdown
is triggered by a prefail or failing health state, post-hooks
and Docker unpause operations are not executed.
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
prefail/failing
</div><div class="manual-tag-description">
Shuts down the host immediately when array health
transitions to prefail/failing.
</div>
</div>
</div>
<p>For both prefail and failing emergency shutdowns, if the daemon is still
able to process runner tasks, it first sends the emergency report.
Queued tasks and post-hooks are canceled, and paused Docker containers are
not unpaused, to prevent further disk activity. If daemon termination or
a fatal daemon failure is already in progress, the emergency shutdown
may proceed without sending the report.
</p><p>Spaces around commas are ignored.
</p><p>Health-based shutdowns (prefail and failing) trigger strictly on a
state transition from an established health state. If the array is
already in a prefail or failing state when the daemon starts,
shutdown is not triggered. This allows you to start the machine and
perform manual maintenance or recovery without triggering an
immediate shutdown.
</p></div>
<div class="manual-section-level-3">
<h3 id="sec6-1-6" class="manual-title-level-3">
sys_smartignore
</h3>
<p>Allows you to ignore specific SMART attributes for one or more disks.
Changes of ignored attributes are omitted from status reports and do not
generate warning notifications. The attributes continue to be collected
and are exported in the REST API as ignored. Typical attributes to ignore
are Spin_Up_Time and Raw_Read_Error_Rate. You can also use <b>Error_Protocol</b>
and <b>Error_Medium</b> to ignore device-level protocol or medium errors.
</p><p>Normalized-value degradations of critical PREFAIL SMART attributes generate
warning notifications. Normalized-value changes of non-critical PREFAIL
attributes are informational, even when not ignored. sys_smartignore can
still be used to hide noisy vendor-specific changes from reports and to
suppress warnings from actionable raw/error-counter changes.
</p><p>sys_smartignore does not affect SMART failure states reported by smartctl.
If an attribute is reported as currently failed, it will still trigger a
critical notification and degrade the array health.
</p><p>The option is a sequence of words separated by spaces.
The first word is a disk name or '*' for all disks.
The subsequent words are attribute numbers or names (case-insensitive).
</p><p>Examples:
</p><pre>
sys_smartignore=parity 188 Command_Timeout
sys_smartignore=d1 Error_Protocol
sys_smartignore=* Spin_Up_Time Raw_Read_Error_Rate
</pre>
</div>
2026-03-08 17:40:50 +01:00
</div>
<div class="manual-section-level-2">
<h2 id="sec6-2" class="manual-title-level-2">
2026-02-14 09:40:46 +01:00
Network &amp; REST API
</h2>
2026-10-29 06:56:28 +01:00
<p>These settings control the network interface.
</p><p>These options are not visible or modifiable via the REST API.
They require a manual edit of the configuration file and a
configuration reload (SIGHUP) or daemon restart to apply.
2026-02-14 09:40:46 +01:00
</p><div class="manual-section-level-3">
2026-03-08 17:40:50 +01:00
<h3 id="sec6-2-1" class="manual-title-level-3">
2026-02-14 09:40:46 +01:00
net_enabled
</h3>
2026-02-19 17:18:37 +01:00
<p>Acts as the master toggle for the network interface. When set to 1,
the daemon enables the REST API and prepares to serve the web dashboard.
If set to 0 or left blank, the daemon operates in a secure, local-only
mode, and no network ports are opened.
2026-02-14 09:40:46 +01:00
</p></div>
<div class="manual-section-level-3">
2026-03-08 17:40:50 +01:00
<h3 id="sec6-2-2" class="manual-title-level-3">
2026-02-14 09:40:46 +01:00
net_port
</h3>
2026-02-19 17:18:37 +01:00
<p>Defines the specific IP address and port(s) to which the daemon binds.
The format follows [IP_ADDRESS:]PORT[s].
</p><div class="manual-tag-list">
<div class="manual-tag-entry">
<div class="manual-tag-name">
2026-02-19 17:45:47 +01:00
IPv4/IPv6
2026-02-19 17:18:37 +01:00
</div><div class="manual-tag-description">
2026-03-01 12:11:35 +01:00
Bind to specific local addresses (e.g., 127.0.0.1:7627 or
[::1]:7627).
2026-02-19 17:18:37 +01:00
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
2026-03-01 12:11:35 +01:00
Port
2026-02-19 17:18:37 +01:00
</div><div class="manual-tag-description">
2026-03-01 12:11:35 +01:00
Providing only a port (e.g., 7627) binds to all available
2026-03-15 18:52:43 +01:00
IPv4 interfaces (0.0.0.0).
2026-02-19 17:18:37 +01:00
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
2026-02-19 17:45:47 +01:00
Multiple_Ports
2026-02-19 17:18:37 +01:00
</div><div class="manual-tag-description">
Multiple listeners can be configured by providing a
comma-separated list.
</div>
</div>
</div>
2026-03-15 18:52:43 +01:00
<p>If left unset, the daemon defaults to 127.0.0.1:7627,[::1]:7627
retrying with only 127.0.0.1:7627 if it fails.
2026-03-01 12:11:35 +01:00
</p><p>To export the service to a VPN like Tailscale or a local network, you
2026-03-01 13:22:36 +01:00
should bind to all interfaces by specifying only the port number.
2026-03-01 12:11:35 +01:00
</p><p>Examples:
</p><pre>
2026-03-15 18:52:43 +01:00
net_port=127.0.0.1:7627 - IPv4 loopback only (Recommended).
net_port=[::1]:7627 - IPv6 loopback only.
net_port=7627 - All IPv4 interfaces (Required for Tailscale/LAN).
net_port=[::]:7627 - All IPv6 interfaces.
net_port=127.0.0.1:7627,127.0.0.1:8080 - Listen on multiple ports on loopback.
2026-03-01 12:11:35 +01:00
</pre>
</div>
2026-02-14 09:40:46 +01:00
<div class="manual-section-level-3">
2026-03-08 17:40:50 +01:00
<h3 id="sec6-2-3" class="manual-title-level-3">
2026-02-14 09:40:46 +01:00
net_acl
</h3>
2026-02-19 17:18:37 +01:00
<p>Restricts API and dashboard access to specific client IP addresses or
subnets using a comma-separated Access Control List (ACL).
</p><p>The syntax uses + to allow and - to deny, supporting CIDR notation
2026-03-15 18:52:43 +01:00
(e.g., /24). The rules are processed sequentially, and the last
matching rule determines the outcome.
If unset, it defaults to accept everything. If any rules are defined,
2026-03-17 00:12:13 +01:00
the daemon adopts a <b>deny by default</b> stance.
2026-03-01 12:11:35 +01:00
</p><p>To allow access via Tailscale or similar services, ensure you add the
relevant network prefix (e.g., +100.0.0.0/8).
</p><p>Examples:
</p><pre>
net_acl=+127.0.0.1,+::1 - Allow IPv4 and IPv6 loopback.
2026-03-15 18:52:43 +01:00
net_acl=+100.0.0.0/8,+127.0.0.1 - Allow Tailscale and loopback.
2026-03-01 12:11:35 +01:00
net_acl=+192.168.1.0/24 - Allow local subnet only.
</pre>
</div>
2026-02-14 09:40:46 +01:00
<div class="manual-section-level-3">
2026-03-08 17:40:50 +01:00
<h3 id="sec6-2-4" class="manual-title-level-3">
2026-02-14 09:40:46 +01:00
net_security_headers
</h3>
2026-02-19 17:18:37 +01:00
<p>When enabled (1), the daemon injects several browser-level security
hardening headers into every HTTP response. These include
Content-Security-Policy (restricting resource loading),
X-Frame-Options (preventing clickjacking via iframes),
X-Content-Type-Options (disabling MIME-sniffing),
and Referrer-Policy.
</p><p>This should only be disabled (0) if the daemon is behind a reverse
proxy (like Nginx or Traefik) that is already configured to handle
these security headers.
2026-02-14 09:40:46 +01:00
</p></div>
<div class="manual-section-level-3">
2026-03-08 17:40:50 +01:00
<h3 id="sec6-2-5" class="manual-title-level-3">
2026-02-14 09:40:46 +01:00
net_allowed_origin
</h3>
2026-02-19 17:18:37 +01:00
<p>Configures Cross-Origin Resource Sharing (CORS) to determine which web
applications can interact with the API.
</p><div class="manual-tag-list">
<div class="manual-tag-entry">
<div class="manual-tag-name">
self
</div><div class="manual-tag-description">
2026-03-08 17:40:50 +01:00
(Default/Recommended) Dynamically reflects the <b>Host</b> header
2026-02-19 17:18:37 +01:00
of the request, allowing the built-in UI to work across various hostnames or IPs.
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
none
</div><div class="manual-tag-description">
Omits CORS headers entirely, blocking browser-based access from any origin.
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
URL
</div><div class="manual-tag-description">
Restricts access to a specific origin (e.g., http://192.168.1.50:3000).
</div>
</div>
</div>
</div>
2026-02-14 09:40:46 +01:00
<div class="manual-section-level-3">
2026-03-08 17:40:50 +01:00
<h3 id="sec6-2-6" class="manual-title-level-3">
2026-02-14 09:40:46 +01:00
net_config_full_access
</h3>
2026-02-19 17:18:37 +01:00
<p>A security flag that determines whether sensitive configuration parameters
can be modified via the REST API.
</p><p>By default (0), security-sensitive options are strictly read-only to
prevent unauthorized system modifications or privilege escalation
through the web interface.
</p><p>When set to 1, the following configuration options become accessible
for modification via PATCH requests:
</p><div class="manual-tag-list">
<div class="manual-tag-entry">
<div class="manual-tag-name">
2026-03-08 17:40:50 +01:00
hook_run_as_user
2026-02-19 17:18:37 +01:00
</div><div class="manual-tag-description">
2026-03-08 17:40:50 +01:00
The account used for executing hook_script.
2026-02-19 17:18:37 +01:00
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
2026-03-08 17:40:50 +01:00
hook_script
2026-02-19 17:18:37 +01:00
</div><div class="manual-tag-description">
2026-03-08 17:40:50 +01:00
The absolute path to the hook script.
2026-02-19 17:18:37 +01:00
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
2026-10-29 06:56:28 +01:00
hook_docker_pause
</div><div class="manual-tag-description">
The docker containers to pause.
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
2026-02-19 17:18:37 +01:00
notify_run_as_user
</div><div class="manual-tag-description">
The account used for notification commands.
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
notify_heartbeat
</div><div class="manual-tag-description">
The command used for health monitoring pings.
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
2026-10-29 06:56:28 +01:00
notify_start
</div><div class="manual-tag-description">
The command used to notify the start of maintenance, heal,
undelete, and refresh tasks.
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
2026-02-19 17:18:37 +01:00
notify_result
</div><div class="manual-tag-description">
The command used for sending task reports.
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
notify_result_level
</div><div class="manual-tag-description">
The severity threshold for sending notifications.
</div>
</div>
</div>
</div>
2026-02-14 09:40:46 +01:00
<div class="manual-section-level-3">
2026-03-08 17:40:50 +01:00
<h3 id="sec6-2-7" class="manual-title-level-3">
2026-02-14 09:40:46 +01:00
net_web_root
</h3>
2026-02-19 17:18:37 +01:00
<p>Specifies the source of the web dashboard assets. The daemon supports
both a standard directory and a single compressed ZIP file for asset
delivery.
2026-02-14 09:40:46 +01:00
</p><p>The daemon resolves the location of the assets based on the following
rules:
</p><div class="manual-tag-list">
<div class="manual-tag-entry">
<div class="manual-tag-name">
ZIP_Filename
</div><div class="manual-tag-description">
2026-10-29 06:56:28 +01:00
If a simple filename is provided (e.g., commander.zip or brutale.zip),
2026-02-19 17:18:37 +01:00
the daemon searches for it in $PREFIX/share/snapraidd/ or
/usr/share/snapraidd/.
</div>
</div>
2026-02-14 09:40:46 +01:00
<div class="manual-tag-entry">
<div class="manual-tag-name">
ZIP_Path
</div><div class="manual-tag-description">
If a path to a ZIP file is provided, it must be absolute
(e.g., /opt/snapraid/ui.zip). The daemon will attempt to use
this specific file exclusively and will not perform a search
in system directories.
2026-02-19 17:18:37 +01:00
</div>
</div>
2026-02-14 09:40:46 +01:00
<div class="manual-tag-entry">
<div class="manual-tag-name">
Directories
</div><div class="manual-tag-description">
If the target is a directory rather than a ZIP archive,
the path must be absolute (e.g., /var/www/snapraid-ui/).
2026-02-19 17:18:37 +01:00
</div>
</div>
</div>
2026-02-14 09:40:46 +01:00
<p>If the specified path or filename cannot be resolved, if a directory
path is not absolute, or if the ZIP archive is inaccessible or
malformed, the built-in HTTP server will be unable to serve the web
interface.
2026-03-01 13:22:36 +01:00
</p><p>The daemon recursively crawls the directory or archive at startup to
provide high-performance, compressed delivery of the UI.
</p><p>When a directory is specified, assets are cached in memory, as a result,
manual changes to asset files on the disk will not be reflected in the
UI until the daemon is restarted. This behavior can be bypassed by using
the -N, --no-cache option during daemon startup, which is recommended
for development environments only.
2026-02-14 09:40:46 +01:00
</p></div>
2026-10-29 06:56:28 +01:00
<div class="manual-section-level-3">
<h3 id="sec6-2-8" class="manual-title-level-3">
net_auth_credential
</h3>
<p>Specifies the credentials required to access the REST API and dashboard
via HTTP Basic Authentication. If empty or omitted, authentication is
disabled.
</p><p>The credentials must be formatted as:
</p><pre>
username:$argon2id$v=19$m=65536,t=3,p=1$salt_base64$hash_base64
</pre>
<p>This is calculated using Argon2id with 64MiB of memory cost (m=65536),
3 iterations (t=3), and 1 thread (p=1).
</p><p>A secure configuration line can be generated by running the daemon with
the <b>-g, --gen-auth</b> command line argument.
</p><p>Note that the <b>/metrics</b> endpoint is exempt from authentication to
support unauthenticated scraping by Prometheus or other monitoring tools.
</p><p>WARNING: Basic Authentication transmits credentials in plaintext (Base64)
over the network. Using this over unencrypted HTTP is NOT secure.
You should deploy an HTTPS encryption layer (such as a reverse proxy
like Caddy, Nginx, or Traefik) or restrict network access to a trusted,
secure network (e.g., using a VPN or Tailscale).
</p><p>This option is security-sensitive and cannot be modified via the REST
API. It requires a manual edit and a configuration reload (SIGHUP)
to apply.
</p></div>
2026-02-14 09:40:46 +01:00
</div>
<div class="manual-section-level-2">
2026-03-08 17:40:50 +01:00
<h2 id="sec6-3" class="manual-title-level-2">
2026-02-14 09:40:46 +01:00
Automation &amp; Maintenance
</h2>
<p>These settings control the automation and maintenance tasks run by
2026-03-01 13:22:36 +01:00
the SnapRAID Daemon.
2026-02-14 09:40:46 +01:00
</p><p>For security reasons, some of them can be set via the REST API only if the
net_config_full_access option is enabled.
</p><div class="manual-section-level-3">
2026-03-08 17:40:50 +01:00
<h3 id="sec6-3-1" class="manual-title-level-3">
2026-10-29 06:56:28 +01:00
check_updates
</h3>
<p>Enables (1) or disables (0) periodic check for daemon and engine updates
on GitHub via the curl CLI tool.
If enabled, the daemon queries the GitHub API every 12 hours in the
background. The WebUI displays the update status and alerts you when
new versions are available, and status reports include an update notice.
If missing or set to 0, update checking is disabled.
</p></div>
<div class="manual-section-level-3">
<h3 id="sec6-3-2" class="manual-title-level-3">
2026-02-14 09:40:46 +01:00
maintenance_schedule
</h3>
2026-02-19 17:18:37 +01:00
<p>Defines the timing for the automated maintenance sequence, which
consists of a sync, followed by a scrub, and concluding with a report.
2026-03-15 18:52:43 +01:00
Multiple schedules can be specified by separating them with commas.
2026-02-19 17:18:37 +01:00
If this option is unset, automated maintenance is disabled.
2026-03-01 13:22:36 +01:00
</p><p>The format must be either "HH:MM" or "Day HH:MM".
2026-02-19 17:18:37 +01:00
Hours are specified in a 24-hour format (00-23), and days are
represented by their short names (Mon, Tue, Wed, Thu, Fri, Sat, Sun).
2026-03-15 18:52:43 +01:00
</p><p>Examples:
"02:00" - Run every night at 2 AM.
"Mon 03:00, Thu 04:00" - Run every Monday at 3 AM and Thursday at 4 AM.
2026-02-14 09:40:46 +01:00
</p></div>
<div class="manual-section-level-3">
2026-10-29 06:56:28 +01:00
<h3 id="sec6-3-3" class="manual-title-level-3">
2026-02-14 09:40:46 +01:00
sync_threshold_deletes
</h3>
2026-04-23 12:57:38 +02:00
<p>Sets the number of deleted or missing files that will trigger an automatic
abort of a sync operation. The abort occurs when the number of deletions
is equal to or greater than this value. This serves as a safety mechanism
to prevent accidental parity loss; for example, setting this to 1 will
abort the operation if any single file is deleted. This check is
enforced during automated maintenance schedules and tasks initiated
through the Web UI.
2026-02-14 09:40:46 +01:00
</p></div>
<div class="manual-section-level-3">
2026-10-29 06:56:28 +01:00
<h3 id="sec6-3-4" class="manual-title-level-3">
2026-02-14 09:40:46 +01:00
sync_threshold_updates
</h3>
2026-04-23 12:57:38 +02:00
<p>Sets the number of modified or updated files that will trigger an
automatic abort of a sync operation. The abort occurs when the number
of updates is equal to or greater than this value. This prevents the
parity from being overwritten if an unexpected number of files have
changed. Similar to the delete threshold, setting this to 1 will abort
the operation if any single file is modified. This check is enforced
during automated maintenance schedules and tasks initiated through
the Web UI.
2026-02-14 09:40:46 +01:00
</p></div>
<div class="manual-section-level-3">
2026-10-29 06:56:28 +01:00
<h3 id="sec6-3-5" class="manual-title-level-3">
2026-02-14 09:40:46 +01:00
sync_prehash
</h3>
2026-02-19 17:18:37 +01:00
<p>If set to 1, the sync command is executed with the --prehash option.
2026-03-01 13:22:36 +01:00
This calculates the hash of all files before the synchronization process
begins. By hashing data before the system is subjected to the high
CPU and I/O load typical of a sync operation, it protects against
silent data corruption caused by faulty memory that may only trigger
under critical system stress.
2026-02-19 17:18:37 +01:00
If missing or set to 0, no pre-hashing is performed.
2026-02-14 09:40:46 +01:00
</p></div>
<div class="manual-section-level-3">
2026-10-29 06:56:28 +01:00
<h3 id="sec6-3-6" class="manual-title-level-3">
2026-03-15 18:52:43 +01:00
sync_prevent_truncations
</h3>
<p>If set to 1, the sync is halted to prevent overwriting
parity with empty file data. This provides a safety
2026-03-17 00:12:13 +01:00
barrier against truncated data, which may occur during system
crashes or filesystem errors.
2026-03-15 18:52:43 +01:00
If this is missing or set to 0, the sync is allowed
to proceed even if files have shrunk to zero size.
</p></div>
<div class="manual-section-level-3">
2026-10-29 06:56:28 +01:00
<h3 id="sec6-3-7" class="manual-title-level-3">
2026-03-15 18:52:43 +01:00
scrub_percentage
</h3>
<p>Determines the portion of the array verified after a successful sync.
You may use decimal points to specify fractions of a percent
(e.g., 0.7 to verify 0.7% of the array).
If missing or set to 0, the scrub phase is skipped entirely.
</p></div>
<div class="manual-section-level-3">
2026-10-29 06:56:28 +01:00
<h3 id="sec6-3-8" class="manual-title-level-3">
2026-03-15 18:52:43 +01:00
scrub_older_than
</h3>
<p>Specifies that only blocks older than the defined number of days
should be scrubbed. This allows the daemon to focus verification on
older data while skipping recently synced blocks.
If missing or set to 0, no age-based filtering is applied.
</p></div>
<div class="manual-section-level-3">
2026-10-29 06:56:28 +01:00
<h3 id="sec6-3-9" class="manual-title-level-3">
2026-03-15 18:52:43 +01:00
touch_zero_subseconds
2026-02-14 09:40:46 +01:00
</h3>
2026-03-15 18:52:43 +01:00
<p>If set to 1, a specific timestamp alignment pass is performed
immediately before the sync during the maintenance window.
If this is missing or set to 0, this pass is skipped.
</p><p>Many filesystems or file-copying utilities may leave file
timestamps with exactly zero nanoseconds. This lack of
precision can cause the synchronization engine to misidentify
moved or renamed files as entirely new content.
</p><p>Setting this to 1 triggers the touch command to update these
sub-second parts of the timestamps to a random value. This
ensures high-resolution tracking is available to correctly
identify relocated data without re-processing the underlying
file blocks.
2026-02-14 09:40:46 +01:00
</p></div>
2026-02-19 17:18:37 +01:00
</div>
<div class="manual-section-level-2">
2026-03-08 17:40:50 +01:00
<h2 id="sec6-4" class="manual-title-level-2">
2026-02-19 17:18:37 +01:00
Disk Monitoring &amp; Power
</h2>
2026-10-29 06:56:28 +01:00
<p>These settings manage how the daemon interacts with physical
2026-02-19 17:18:37 +01:00
hardware to monitor disk health and optimize energy consumption
</p><div class="manual-section-level-3">
2026-03-08 17:40:50 +01:00
<h3 id="sec6-4-1" class="manual-title-level-3">
2026-02-14 09:40:46 +01:00
probe_interval_minutes
</h3>
2026-02-19 17:18:37 +01:00
<p>Controls the frequency at which the daemon checks disk SMART attributes.
To prevent unnecessary disk wear, the daemon only performs this check
if the disks are already spinning.
If set to 0 or left blank, SMART monitoring is disabled.
2026-02-14 09:40:46 +01:00
</p></div>
<div class="manual-section-level-3">
2026-03-08 17:40:50 +01:00
<h3 id="sec6-4-2" class="manual-title-level-3">
2026-02-14 09:40:46 +01:00
spindown_idle_minutes
</h3>
2026-02-19 17:18:37 +01:00
<p>Manages power consumption by automatically spinning down disks after
the specified duration of inactivity.
2026-04-07 17:57:02 +02:00
</p><p>Note that this applies only to <b>data</b> and <b>parity</b> disks configured in
<b>snapraid.conf</b>. Any other disks, including <b>extra</b> disks, are not
subject to spindown.
2026-10-29 06:56:28 +01:00
</p><p>You can specify a single integer (e.g. 15) to apply the timeout to both
data and parity disks, or two comma-separated integers (e.g. 15, 30)
to set separate timeouts for data and parity disks respectively.
A value of 0 disables spindown for that specific disk type. For example,
<b>0, 30</b> disables spindown for data disks but spins down parity disks
after 30 idle minutes.
2026-03-01 13:22:36 +01:00
</p><p>This timer monitors the global activity of the disks across the entire
operating system. A disk will only be spun down if it has remained
completely idle for the specified period. If any other application,
service, or system process accesses the disk, the idle timer is reset.
2026-04-07 17:57:02 +02:00
</p><p>If set to 0 or left blank, the daemon will not manage disk power
states, relying instead on the OS or hardware controllers.
2026-02-14 09:40:46 +01:00
</p></div>
<div class="manual-section-level-3">
2026-03-08 17:40:50 +01:00
<h3 id="sec6-4-3" class="manual-title-level-3">
hook_script
2026-02-14 09:40:46 +01:00
</h3>
2026-03-08 17:40:50 +01:00
<p>Defines an absolute path to an executable script to be triggered by
daemon events.
</p><p>The script is executed with a single positional argument that
2026-10-29 06:56:28 +01:00
represents the current stage of a hook lifecycle. A hook lifecycle
is an uninterrupted session covering one or more consecutive tasks
that access the array:
2026-03-08 17:40:50 +01:00
</p><div class="manual-tag-list">
<div class="manual-tag-entry">
<div class="manual-tag-name">
task-begin
</div><div class="manual-tag-description">
2026-10-29 06:56:28 +01:00
Triggered immediately before the daemon begins an
array-access session (e.g., sync, scrub, or maintenance).
This starts a hook lifecycle, which may span multiple
consecutive task groups.
2026-03-08 17:40:50 +01:00
</div>
2026-02-19 17:32:30 +01:00
</div>
2026-03-08 17:40:50 +01:00
<div class="manual-tag-entry">
<div class="manual-tag-name">
task-end
</div><div class="manual-tag-description">
2026-10-29 06:56:28 +01:00
Triggered after the session has concluded successfully.
This closes the matching hook lifecycle and uses the same
hook configuration snapshot captured when <b>task-begin</b> was
executed.
2026-03-08 17:40:50 +01:00
</div>
</div>
2026-10-29 06:56:28 +01:00
<div class="manual-tag-entry">
<div class="manual-tag-name">
task-error
</div><div class="manual-tag-description">
Triggered if the session is aborted, interrupted, or
encounters an operational failure. This closes the active hook
lifecycle using the same hook configuration snapshot and
acquired-resource state captured when <b>task-begin</b> was executed.
</div>
</div>
</div>
<p>If <b>task-begin</b> fails, <b>task-error</b> is not invoked. The <b>task-begin</b>
handler is responsible for reverting any partial changes before
returning an error.
</p><p>Hook lifecycle boundaries do not necessarily match task group boundaries.
When consecutive array-access tasks can safely share the same paused
state (such as paused Docker containers and pre-hook preparations), the
daemon may postpone hook cleanup and keep that state active across the
boundary between two task groups. As a result, a <b>task-begin</b> event may
occur while processing one group and the corresponding <b>task-end</b> or
<b>task-error</b> event may occur only after tasks belonging to a subsequent
group have completed.
</p><p>The hook configuration is snapshotted when the hook lifecycle begins
and remains associated with that lifecycle until its cleanup attempt
completes.
Configuration reloads do not alter an already active hook lifecycle.
In particular, the corresponding <b>task-end</b> or <b>task-error</b> hook,
the post-script, and Docker cleanup always use the same hook configuration
and acquired-resource state established by the matching <b>task-begin</b>,
even if the daemon configuration changes in the meantime.
</p><p>A new configuration becomes effective for hooks when a new hook lifecycle
is started after the cleanup attempt for the previous lifecycle has
completed.
</p><p>Note that 'task-end' reflects only whether the hook lifecycle finished
its execution cycle successfully. It does not necessarily reflect
hardware or data integrity. For example, a sync command may return
'task-end' even if the array is technically in a corrupt state, provided
the sync process itself finished without crashing.
2026-03-08 17:40:50 +01:00
</p><p>Future versions of the daemon will introduce new event types that may
not relate to array access or follow the <b>task-</b> naming convention.
It is strongly recommended to implement a default handler to ignore
2026-10-29 06:56:28 +01:00
unrecognized events.
</p><p>The script is executed with several environment variables providing details
about the execution context:
</p><div class="manual-tag-list">
<div class="manual-tag-entry">
<div class="manual-tag-name">
SNAPRAID_EVENT
</div><div class="manual-tag-description">
The event type (<b>task-begin</b>, <b>task-end</b> or <b>task-error</b>).
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
SNAPRAID_NUMBER
</div><div class="manual-tag-description">
The unique sequential ID of the task.
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
SNAPRAID_COMMAND
</div><div class="manual-tag-description">
The specific command name (e.g. <b>sync</b>, <b>scrub</b>, <b>diff</b>).
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
SNAPRAID_HIGH_COMMAND
</div><div class="manual-tag-description">
The high-level command if part of a group (e.g.
<b>maintenance</b>, <b>heal</b> or <b>undelete</b>).
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
SNAPRAID_LOG_FILE
</div><div class="manual-tag-description">
Path to the task execution log file.
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
SNAPRAID_RUN_AS_USER
</div><div class="manual-tag-description">
The user account configured for running the hooks.
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
SNAPRAID_DAEMON_CONFIG
</div><div class="manual-tag-description">
Path to the daemon configuration file.
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
SNAPRAID_ENGINE_CONFIG
</div><div class="manual-tag-description">
Path to the SnapRAID engine configuration file.
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
SNAPRAID_INSTANCE
</div><div class="manual-tag-description">
The name of the daemon instance (if specified via -i).
</div>
</div>
</div>
<p>During <b>task-end</b> and <b>task-error</b> events, the following additional
variables are also available:
</p><div class="manual-tag-list">
<div class="manual-tag-entry">
<div class="manual-tag-name">
SNAPRAID_ARRAY_HEALTH
</div><div class="manual-tag-description">
The health classification of the array after the
task (<b>passed</b>, <b>prefail</b>, <b>failing</b>, <b>degraded</b>, <b>corrupt</b> or <b>pending</b>).
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
SNAPRAID_HEALTH
</div><div class="manual-tag-description">
The health classification of the task.
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
SNAPRAID_STATUS
</div><div class="manual-tag-description">
The exit status of the task (<b>terminated</b>, <b>signaled</b>, <b>canceled</b>).
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
SNAPRAID_EXIT_CODE
</div><div class="manual-tag-description">
The exit code of the task if <b>terminated</b>.
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
SNAPRAID_EXIT_SIGNAL
</div><div class="manual-tag-description">
The termination signal of task if <b>signaled</b>.
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
SNAPRAID_ELAPSED_SECONDS
</div><div class="manual-tag-description">
The total task execution time in seconds.
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
SNAPRAID_ERROR_IO
</div><div class="manual-tag-description">
Count of input/output errors during the task.
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
SNAPRAID_ERROR_DATA
</div><div class="manual-tag-description">
Count of data errors during the task.
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
SNAPRAID_ERROR_SOFT
</div><div class="manual-tag-description">
Count of soft errors during the task.
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
SNAPRAID_ERROR_RECOVERED
</div><div class="manual-tag-description">
Count of recovered blocks/errors during the task.
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
SNAPRAID_ERROR_UNRECOVERABLE
</div><div class="manual-tag-description">
Count of unrecoverable blocks/errors during the task.
</div>
</div>
</div>
<p>For <b>diff</b> and <b>sync</b> commands, modification metrics are also exposed:
</p><div class="manual-tag-list">
<div class="manual-tag-entry">
<div class="manual-tag-name">
SNAPRAID_DIFF_EQUAL
</div><div class="manual-tag-description">
Count of equal/unchanged files.
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
SNAPRAID_DIFF_ADDED
</div><div class="manual-tag-description">
Count of added files.
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
SNAPRAID_DIFF_REMOVED
</div><div class="manual-tag-description">
Count of removed files.
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
SNAPRAID_DIFF_UPDATED
</div><div class="manual-tag-description">
Count of updated/modified files.
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
SNAPRAID_DIFF_MOVED
</div><div class="manual-tag-description">
Count of moved files.
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
SNAPRAID_DIFF_COPIED
</div><div class="manual-tag-description">
Count of copied files.
</div>
</div>
</div>
<p>SECURITY REQUIREMENTS:
2026-04-03 12:54:33 +02:00
* The script path MUST be absolute (must start with /).
* The script AND the directory containing the script MUST be owned by
</p><p>the daemon's real UID, effective UID, or root (UID 0).
</p><ul>
<li>
The script AND directory containing the script MUST NOT be
group-writable, unless its group matches the daemon's GID/EGID
or is root.
</li>
<li>
The script AND directory containing the script MUST NOT be
world-writable (S_IWOTH).
</li>
<li>
The script MUST have at least one execute bit set (S_IXUSR, S_IXGRP, or S_IXOTH).
</li>
<li>
The script MUST NOT have the setuid or setgid bits set (S_ISUID or S_ISGID).
</li>
<li>
The script MUST NOT have multiple hard links (st_nlink == 1 only).
</li>
</ul>
<p>If the execution fails, check your syslog (EventLog in Windows) to get
the exact reason.
2026-03-08 17:40:50 +01:00
</p><p>This remains inactive if no path is defined.
</p></div>
2026-02-14 09:40:46 +01:00
<div class="manual-section-level-3">
2026-03-08 17:40:50 +01:00
<h3 id="sec6-4-4" class="manual-title-level-3">
2026-10-29 06:56:28 +01:00
hook_docker_pause
</h3>
<p>Specifies a comma-separated list of Docker containers to pause during
tasks that access the array (e.g., plex, transmission).
</p><p>At the start of a hook lifecycle (immediately before executing the
<b>task-begin</b> hook), the daemon pauses only the listed containers that
are running and not already paused. When the hook lifecycle concludes,
it attempts to unpause only those containers. Containers that were
already paused remain paused, and stopped containers remain stopped.
</p><p>If the unpause operation fails, the hook cleanup is reported as failed.
The daemon does not retry the unpause operation in a later hook lifecycle.
</p></div>
<div class="manual-section-level-3">
<h3 id="sec6-4-5" class="manual-title-level-3">
2026-03-08 17:40:50 +01:00
hook_run_as_user
2026-02-14 09:40:46 +01:00
</h3>
2026-03-08 17:40:50 +01:00
<p>Specifies the user account used to execute the hook_script.
If this is missing or blank, the script is executed with the
2026-10-29 06:56:28 +01:00
daemon's original startup privileges.
2026-04-23 12:57:38 +02:00
</p><p>On Linux, <b>nobody</b> is the standard choice for maximum isolation. Note that
using <b>nobody</b> may prevent certain tools, such as Docker, from functioning
correctly due to restricted permissions. Ensure you are aware of these
limitations before applying this setting.
</p><p>On Windows, <b>LocalService</b> is the preferred choice as it provides
2026-03-08 17:40:50 +01:00
minimal local access while maintaining network capabilities.
2026-03-17 00:12:13 +01:00
Alternatively, <b>NetworkService</b> can be used if the script specifically
2026-03-08 17:40:50 +01:00
requires the computer's network identity to access remote resources.
2026-02-14 09:40:46 +01:00
</p></div>
</div>
<div class="manual-section-level-2">
2026-03-08 17:40:50 +01:00
<h2 id="sec6-5" class="manual-title-level-2">
Notifications
2026-02-14 09:40:46 +01:00
</h2>
2026-03-08 17:40:50 +01:00
<p>These settings control the notification operations performed by the
daemon.
2026-02-14 09:40:46 +01:00
</p><div class="manual-section-level-3">
2026-03-08 17:40:50 +01:00
<h3 id="sec6-5-1" class="manual-title-level-3">
2026-02-14 09:40:46 +01:00
notify_syslog_enabled
</h3>
2026-02-19 17:18:37 +01:00
<p>When set to 1, daemon activity is sent to the operating system system
log (syslog/journald). While lifecycle events like starting and
stopping are always captured, task-related messages are filtered by
<b>notify_syslog_level</b>.
2026-02-14 09:40:46 +01:00
</p></div>
<div class="manual-section-level-3">
2026-03-08 17:40:50 +01:00
<h3 id="sec6-5-2" class="manual-title-level-3">
2026-02-14 09:40:46 +01:00
notify_syslog_level
</h3>
<p>Sets the minimum severity for syslog task entries.
2026-02-19 17:18:37 +01:00
Possible values are <b>info</b>, <b>warning</b>, <b>error</b>, and <b>critical</b>.
The default is <b>error</b>.
2026-02-14 09:40:46 +01:00
</p></div>
<div class="manual-section-level-3">
2026-03-08 17:40:50 +01:00
<h3 id="sec6-5-3" class="manual-title-level-3">
2026-02-14 09:40:46 +01:00
notify_heartbeat
</h3>
2026-02-19 17:18:37 +01:00
<p>Defines a command to run ONLY if the maintenance task was successful
(it is not triggered by other tasks, such as heal or undelete).
2026-03-17 00:12:13 +01:00
This is ideal for external monitoring services like <b>Dead Man's Snitch</b>
2026-02-19 17:18:37 +01:00
or Healthchecks.io. If this ping stops, it indicates the server is down
or the task is failing.
2026-02-14 09:40:46 +01:00
</p></div>
<div class="manual-section-level-3">
2026-03-08 17:40:50 +01:00
<h3 id="sec6-5-4" class="manual-title-level-3">
2026-10-29 06:56:28 +01:00
notify_start
</h3>
<p>Specifies a command triggered at the start of maintenance, heal,
undelete, and refresh tasks. The daemon pipes a simple plain-text start
message directly into the command's stdin.
</p></div>
<div class="manual-section-level-3">
<h3 id="sec6-5-5" class="manual-title-level-3">
2026-02-14 09:40:46 +01:00
notify_result
</h3>
2026-03-01 12:11:35 +01:00
<p>Specifies a command triggered after every report task generated by
high-level tasks or by a SMART telemetry change. The command is only
2026-03-01 13:22:36 +01:00
executed if the task's result matches the <b>notify_result_level</b>.
2026-03-01 12:11:35 +01:00
The daemon pipes a structured, plain-text task report directly into
the command's stdin.
2026-04-23 12:57:38 +02:00
</p><p>Examples of usage:
</p><div class="manual-tag-list">
<div class="manual-tag-entry">
<div class="manual-tag-name">
ntfy.sh
</div><div class="manual-tag-description">
(Modern Push Notifications) Uses curl to send the report as
a POST request that you can receive on your phone.
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
mail
</div><div class="manual-tag-description">
(Local System Mail) Uses the standard Linux 'mail' utility.
This is ideal if you have a local MTA (like Postfix or Exim) configured.
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
SMTP-over-SSL
</div><div class="manual-tag-description">
(Direct Delivery) Uses curl's built-in SMTP engine with
the --netrc option. This is the most secure method for direct
SMTP, as it keeps your login credentials out of persistent logs.
</div>
</div>
</div>
<p>The daemon automatically chooses a wide (80-col) or narrow (32-col)
2026-03-17 00:12:13 +01:00
report based on the command and arguments used (e.g., presence of <b>mail</b>
or <b>smtps</b> strings). Users can manually override this by adding --wide or
2026-02-19 17:18:37 +01:00
--narrow to the command string. These tags are stripped before execution.
</p><p>Before execution, the daemon scans the command string and replaces the
following tokens with dynamic values corresponding to the current
task's state and results:
</p><div class="manual-tag-list">
<div class="manual-tag-entry">
<div class="manual-tag-name">
%s
</div><div class="manual-tag-description">
Subject string (e.g., "[ERROR] SnapRAID Maintenance").
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
%l
</div><div class="manual-tag-description">
Task level (critical, error, warning, info, debug).
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
%n
</div><div class="manual-tag-description">
ntfy priority (urgent, high, default, low, min).
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
%t
</div><div class="manual-tag-description">
2026-03-01 12:11:35 +01:00
ntfy tag (rotating_light, warning, default, -1, +1, heavy_check_mark).
2026-02-19 17:18:37 +01:00
</div>
</div>
2026-10-29 06:56:28 +01:00
<div class="manual-tag-entry">
<div class="manual-tag-name">
%h
</div><div class="manual-tag-description">
high-level task name (maintenance, heal, undelete, refresh).
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
%c
</div><div class="manual-tag-description">
resulting task/group exit code; negative values are daemon-defined
failures (-1 execution/infrastructure, -2 pre-hook, -3 post-hook).
2026-02-19 17:18:37 +01:00
</div>
2026-10-29 06:56:28 +01:00
</div>
</div>
<p>The report contents are not available as a placeholder. They are passed
to the command through standard input (stdin).
</p><p>If the command contains --mail-from or --mail-rcpt, the daemon
2026-02-19 17:18:37 +01:00
automatically prepends standard email headers (From, To, Subject)
followed by a blank line to the report text. This ensures
compatibility with curl's SMTP engine.
</p><p>When using curl for SMTP, it is recommended to use the --netrc flag.
This allows curl to read credentials from a local file rather than
exposing passwords in the command line or process list.
2026-04-23 12:57:38 +02:00
</p><div class="manual-tag-list">
<div class="manual-tag-entry">
<div class="manual-tag-name">
Linux
</div><div class="manual-tag-description">
Curl looks for <b>.netrc</b> in the HOME directory of the executing
user. For a daemon running as root, place the file in: <b>/root/.netrc</b>
The <b>.netrc</b> file MUST have 600 permissions and be owned by the
executing user. Otherwise, curl will fail with error 55.
</div>
</div>
<div class="manual-tag-entry">
<div class="manual-tag-name">
Windows
</div><div class="manual-tag-description">
Curl looks for '_netrc' in the user profile. For a Windows
Service running as 'LocalSystem', place the file in:
<b>C:\Windows\System32\config\systemprofile\_netrc</b>
Ensure the <b>_netrc</b> file has permissions restricted to System and
Administrators.
</div>
</div>
</div>
<p>File format (.netrc or _netrc):
2026-02-19 17:18:37 +01:00
</p><pre>
machine smtp.gmail.com
login your_email@gmail.com
2026-04-23 12:57:38 +02:00
password your-16-char-app-password-without-spaces
2026-02-19 17:18:37 +01:00
</pre>
2026-04-23 12:57:38 +02:00
</div>
2026-02-14 09:40:46 +01:00
<div class="manual-section-level-3">
2026-10-29 06:56:28 +01:00
<h3 id="sec6-5-6" class="manual-title-level-3">
2026-02-14 09:40:46 +01:00
notify_result_level
</h3>
2026-02-19 17:18:37 +01:00
<p>Controls the filter for <b>notify_result</b>. The notification is sent only
2026-02-14 09:40:46 +01:00
if the task result is equal to or more severe than this level.
2026-02-19 17:18:37 +01:00
Valid values are <b>info</b> (always send), <b>warning</b>, <b>error</b>, and <b>critical</b>.
2026-10-29 06:56:28 +01:00
The default is <b>warning</b>.
</p><p>Note that SMART attribute changes are rated as <b>warning</b>.
Problematic array health states (<b>CORRUPT</b>, <b>DEGRADED</b>, <b>PREFAIL</b>, and
<b>FAILING</b>) are rated as <b>critical</b>. The <b>PENDING</b> state is informational
and does not by itself increase the notification severity.
2026-02-14 09:40:46 +01:00
</p></div>
<div class="manual-section-level-3">
2026-10-29 06:56:28 +01:00
<h3 id="sec6-5-7" class="manual-title-level-3">
2026-03-08 17:40:50 +01:00
notify_run_as_user
</h3>
2026-10-29 06:56:28 +01:00
<p>The user account used for notify_heartbeat, notify_start, notify_result and mail
2026-03-08 17:40:50 +01:00
notifications. If missing or left blank, the task runs with the
2026-10-29 06:56:28 +01:00
daemon's original startup privileges.
2026-04-23 12:57:38 +02:00
</p><p>On Linux, <b>nobody</b> is the standard choice for maximum isolation. However,
while sufficient for simple <b>curl</b> commands, it may cause failures for
mailers (like sendmail or postfix) that require specific group memberships
or access to mail queues. Verify that your notification tools can operate
without a home directory or write access to system logs.
</p><p>On Windows, <b>LocalService</b> is the preferred choice as it provides
2026-03-08 17:40:50 +01:00
minimal local access while maintaining network capabilities.
2026-03-17 00:12:13 +01:00
Alternatively, <b>NetworkService</b> can be used if the script specifically
2026-03-08 17:40:50 +01:00
requires the computer's network identity to access remote resources.
</p></div>
<div class="manual-section-level-3">
2026-10-29 06:56:28 +01:00
<h3 id="sec6-5-8" class="manual-title-level-3">
2026-02-14 09:40:46 +01:00
notify_differences
</h3>
2026-02-19 17:18:37 +01:00
<p>If set to 1, the daemon logs a detailed list of file changes discovered
before a sync begins. If set to 0 or missing, no difference report is
generated.
2026-02-14 09:40:46 +01:00
</p></div>
</div>
2026-02-19 17:32:30 +01:00
<div class="manual-section-level-2">
2026-03-08 17:40:50 +01:00
<h2 id="sec6-6" class="manual-title-level-2">
2026-03-01 12:11:35 +01:00
Notification Examples
2026-02-19 17:32:30 +01:00
</h2>
<p>The following examples demonstrate common notification and heartbeat
configurations
</p><div class="manual-section-level-3">
2026-03-08 17:40:50 +01:00
<h3 id="sec6-6-1" class="manual-title-level-3">
2026-02-19 17:32:30 +01:00
External Heartbeat Monitoring (Healthchecks.io)
</h3>
<p>To monitor that automated maintenance is running successfully, use a service
like Healthchecks.io.
</p><p>In this example, curl sends a simple GET request to a unique monitoring URL.
The flags ensure that curl fails silently on server errors (-f), does not hang
indefinitely (--max-time), and attempts to overcome transient network issues (--retry).
</p><pre>
notify_heartbeat = curl -f --max-time 30 --retry 3 <a href="https://hc-ping.com/your_private_uuid">https://hc-ping.com/your_private_uuid</a>
</pre>
</div>
<div class="manual-section-level-3">
2026-03-08 17:40:50 +01:00
<h3 id="sec6-6-2" class="manual-title-level-3">
2026-02-19 17:32:30 +01:00
Push Notifications (ntfy.sh)
</h3>
<p>This uses curl to send the report as a POST request to a push notification service.
It utilizes the --narrow flag to ensure the report is readable on mobile devices
and maps SnapRAID status to ntfy titles, priorities, and emojis via placeholders.
</p><pre>
2026-04-03 12:54:33 +02:00
notify_result = curl --narrow -f --max-time 30 --retry 3 -H "Title: %s" -H "Priority: %n" -H "Tag: %t" --data-binary @- <a href="https://ntfy.sh/your_private_topic">https://ntfy.sh/your_private_topic</a>
2026-02-19 17:32:30 +01:00
</pre>
2026-04-03 12:54:33 +02:00
<p>If you want to also send an email, you can add '-H "Email: your_email@example.com"'
but you also need to authenticate by sending an authentication token. See:
</p><p><a href="https://docs.ntfy.sh/publish/#authentication">https://docs.ntfy.sh/publish/#authentication</a>
<br>
</p></div>
2026-02-19 17:32:30 +01:00
<div class="manual-section-level-3">
2026-03-08 17:40:50 +01:00
<h3 id="sec6-6-3" class="manual-title-level-3">
2026-02-19 17:32:30 +01:00
Local System Mail (mail)
</h3>
<p>A traditional approach using the standard Linux mail utility. This is
ideal if you have a local Mail Transfer Agent (MTA) like Postfix or
Exim already configured on your system.
</p><pre>
notify_result = mail -s "%s" your_user@localhost
</pre>
</div>
<div class="manual-section-level-3">
2026-03-08 17:40:50 +01:00
<h3 id="sec6-6-4" class="manual-title-level-3">
2026-02-19 17:32:30 +01:00
Direct Delivery (SMTP-over-SSL)
</h3>
<p>This leverages curl's built-in SMTP engine for direct delivery to an
external provider. By using the --netrc option, login credentials
remain secured in a separate file rather than being exposed in the
process list or logs.
</p><pre>
notify_result = curl --netrc --url smtps://smtp.gmail.com:465 --ssl-reqd --mail-from your_email@gmail.com --mail-rcpt your_email@gmail.com --upload-file -
</pre>
</div>
</div>
2026-02-14 09:40:46 +01:00
</div>
<div class="manual-section-level-1">
2026-03-01 12:11:35 +01:00
<h1 id="sec7" class="manual-title-level-1">
2026-02-19 17:45:47 +01:00
REST API
2026-02-14 09:40:46 +01:00
</h1>
<p>The SnapRAID Daemon provides a comprehensive RESTful JSON interface
for monitoring and controlling the parity array.
</p><p>For complete technical documentation, including request schemas and
2026-02-19 17:18:37 +01:00
specific error codes, please refer to the <b>snapraidd.yaml</b> OpenAPI
specification file typically located in the documentation directory of
the installation.
2026-10-29 06:56:28 +01:00
</p><p>All state-changing API requests require the <b>Content-Type</b> header to be
set to <b>application/json</b>, even when the request body is empty. This
ensures that browser cross-origin requests require a CORS preflight,
providing protection against Cross-Site Request Forgery (CSRF).
Chunked request bodies are not supported.
2026-02-14 09:40:46 +01:00
</p><div class="manual-section-level-2">
2026-03-01 12:11:35 +01:00
<h2 id="sec7-1" class="manual-title-level-2">
2026-02-14 09:40:46 +01:00
Maintenance &amp; Recovery
</h2>
<p>The API prioritizes orchestrated workflows over raw command execution.
These high-level endpoints encapsulate complex SnapRAID logic into
single, automated tasks that manage the lifecycle of the array and the
recovery of data.
2026-03-01 13:22:36 +01:00
They typically conclude with a <b>report</b> command that generates a
notification containing the operation's results.
2026-02-14 09:40:46 +01:00
</p><div class="manual-section-level-3">
2026-03-01 12:11:35 +01:00
<h3 id="sec7-1-1" class="manual-title-level-3">
2026-02-14 09:40:46 +01:00
/snapraid/v1/maintenance
</h3>
<p>Triggers the complete automated maintenance sequence. It orchestrates
a parity synchronization, followed by a data integrity scrub, and
concludes by issuing a system-wide health report.
This is the primary endpoint for routine array upkeep.
2026-10-29 06:56:28 +01:00
The operation is aborted if the array is in a <b>DEGRADED</b>, <b>PREFAIL</b> or
<b>FAILING</b> health state.
2026-03-08 17:40:50 +01:00
This task is subject to the <b>sync_threshold_deletes</b> and
<b>sync_threshold_updates</b> safety checks defined in the configuration.
2026-02-14 09:40:46 +01:00
The percentage of the array checked and the age filter are determined
2026-03-08 17:40:50 +01:00
by the <b>scrub_percentage</b> and <b>scrub_older_than</b> settings.
2026-02-14 09:40:46 +01:00
</p><p>Example:
</p><pre>
2026-10-29 06:56:28 +01:00
curl <a href="http://localhost:7627/snapraid/v1/maintenance">http://localhost:7627/snapraid/v1/maintenance</a> \
&nbsp;&nbsp;&nbsp;&nbsp;--json '{}'
2026-02-14 09:40:46 +01:00
</pre>
<p>It is implemented with the sequence of commands: up, diff, sync, scrub, and
report.
</p></div>
<div class="manual-section-level-3">
2026-03-01 12:11:35 +01:00
<h3 id="sec7-1-2" class="manual-title-level-3">
2026-02-14 09:40:46 +01:00
/snapraid/v1/heal
</h3>
<p>Executes a specialized silent error recovery workflow. The daemon
automatically runs a targeted fix operation to repair detected corruption,
immediately follows up with a verification scrub of the affected
blocks to ensure the recovery was successful, and concludes by issuing
a report of the result.
</p><p>Example:
</p><pre>
2026-10-29 06:56:28 +01:00
curl <a href="http://localhost:7627/snapraid/v1/heal">http://localhost:7627/snapraid/v1/heal</a> \
&nbsp;&nbsp;&nbsp;&nbsp;--json '{}'
2026-02-14 09:40:46 +01:00
</pre>
<p>It is implemented with the sequence of commands: up, fix -e, scrub -p bad,
and report.
</p></div>
<div class="manual-section-level-3">
2026-03-01 12:11:35 +01:00
<h3 id="sec7-1-3" class="manual-title-level-3">
2026-02-14 09:40:46 +01:00
/snapraid/v1/undelete
</h3>
<p>Invokes the SnapRAID restoration engine to recover files that have been
deleted from data disks but still exist in the parity information.
This is used to roll back accidental deletions to the state of the
last successful synchronization.
</p><p>Example:
</p><pre>
2026-10-29 06:56:28 +01:00
curl <a href="http://localhost:7627/snapraid/v1/undelete">http://localhost:7627/snapraid/v1/undelete</a> \
&nbsp;&nbsp;&nbsp;&nbsp;--json '{ "filters": [ "*.txt" ] }'
2026-02-14 09:40:46 +01:00
</pre>
<p>It is implemented with the sequence of commands: up, fix -m -f ...,
and report.
</p></div>
<div class="manual-section-level-3">
2026-03-01 12:11:35 +01:00
<h3 id="sec7-1-4" class="manual-title-level-3">
2026-02-14 09:40:46 +01:00
/snapraid/v1/suspend_idle
</h3>
<p>Probes the disks to gather their latest activity state and executes a
conditional spindown operation. The daemon will only issue the
down_idle command to disks that have exceeded the
2026-03-08 17:40:50 +01:00
<b>spindown_idle_minutes</b> threshold. In this case, no report is
2026-02-14 09:40:46 +01:00
generated.
</p><p>Example:
</p><pre>
2026-10-29 06:56:28 +01:00
curl <a href="http://localhost:7627/snapraid/v1/suspend_idle">http://localhost:7627/snapraid/v1/suspend_idle</a> \
&nbsp;&nbsp;&nbsp;&nbsp;--json '{}'
2026-02-14 09:40:46 +01:00
</pre>
<p>It is implemented with the sequence of commands: probe, down_idle.
</p></div>
2026-03-08 17:40:50 +01:00
<div class="manual-section-level-3">
<h3 id="sec7-1-5" class="manual-title-level-3">
2026-03-17 00:12:13 +01:00
/snapraid/v1/refresh
2026-03-08 17:40:50 +01:00
</h3>
<p>Forces the daemon to re-synchronize its internal state with the
content file. This is intended for use after manual interventions
performed outside the daemon interface (e.g., replacing
a failed disk, fixing UUID mismatches, or manually updating configuration).
</p><p>The operation executes a <b>read</b> task to load the current content file
data, followed by a <b>report</b> task to evaluate and broadcast the
resulting array health.
2026-10-29 06:56:28 +01:00
</p><p>This is specifically useful for clearing <b>FAILING</b>, <b>PREFAIL</b> or <b>DEGRADED</b> modes
2026-03-08 17:40:50 +01:00
once the underlying hardware or configuration issues have been
resolved manually.
</p><p>Example:
</p><pre>
2026-10-29 06:56:28 +01:00
curl <a href="http://localhost:7627/snapraid/v1/refresh">http://localhost:7627/snapraid/v1/refresh</a> \
&nbsp;&nbsp;&nbsp;&nbsp;--json '{}'
</pre>
</div>
<div class="manual-section-level-3">
<h3 id="sec7-1-6" class="manual-title-level-3">
/snapraid/v1/report
</h3>
<p>Generates a status report describing the current array state and health.
The report task is scheduled asynchronously and is executed according to
the normal task queue semantics.
</p><p>Example:
</p><pre>
curl <a href="http://localhost:7627/snapraid/v1/report">http://localhost:7627/snapraid/v1/report</a> \
&nbsp;&nbsp;&nbsp;&nbsp;--json '{}'
2026-03-08 17:40:50 +01:00
</pre>
</div>
2026-02-14 09:40:46 +01:00
</div>
<div class="manual-section-level-2">
2026-03-01 12:11:35 +01:00
<h2 id="sec7-2" class="manual-title-level-2">
2026-02-14 09:40:46 +01:00
Monitoring &amp; Inventory
</h2>
<p>These endpoints provide high-level visibility into the global state of
the storage stack and the health of the underlying physical hardware.
</p><div class="manual-section-level-3">
2026-03-01 12:11:35 +01:00
<h3 id="sec7-2-1" class="manual-title-level-3">
2026-02-14 09:40:46 +01:00
/snapraid/v1/array
</h3>
<p>Provides a high-level telemetry summary of the entire parity array.
This includes global metadata such as total capacity across all disks,
aggregate space utilization, the current state of parity protection,
and the timestamp of the last successful maintenance.
</p><p>Example:
</p><pre>
2026-03-01 12:11:35 +01:00
curl -s <a href="http://localhost:7627/snapraid/v1/array">http://localhost:7627/snapraid/v1/array</a> | jq
2026-02-14 09:40:46 +01:00
</pre>
</div>
<div class="manual-section-level-3">
2026-03-01 12:11:35 +01:00
<h3 id="sec7-2-2" class="manual-title-level-3">
2026-10-29 06:56:28 +01:00
/snapraid/v2/disks
2026-02-14 09:40:46 +01:00
</h3>
<p>Returns a comprehensive inventory of every physical disk associated
with the SnapRAID configuration. It reports real-time hardware
metrics including SMART health status, temperature, and the current
power state (Active/Spin-up vs. Standby/Spin-down).
</p><p>Example:
</p><pre>
2026-10-29 06:56:28 +01:00
curl -s <a href="http://localhost:7627/snapraid/v2/disks">http://localhost:7627/snapraid/v2/disks</a> | jq
2026-02-14 09:40:46 +01:00
</pre>
</div>
</div>
<div class="manual-section-level-2">
2026-03-01 12:11:35 +01:00
<h2 id="sec7-3" class="manual-title-level-2">
2026-03-17 00:12:13 +01:00
Runtime Configuration
2026-02-14 09:40:46 +01:00
</h2>
<p>Provides a programmatic interface to retrieve and modify the
operational parameters of the daemon in real-time.
</p><div class="manual-section-level-3">
2026-03-01 12:11:35 +01:00
<h3 id="sec7-3-1" class="manual-title-level-3">
2026-10-29 06:56:28 +01:00
/snapraid/v2/config
2026-02-14 09:40:46 +01:00
</h3>
<p>Retrieves and updates the current runtime configuration parameters of
the snapraidd service. Changes are applied instantly to memory and
persisted to the configuration file.
Note that certain networking and security settings are read-only and
require a manual edit and SIGHUP.
</p><p>Example:
</p><pre>
2026-10-29 06:56:28 +01:00
curl -s <a href="http://localhost:7627/snapraid/v2/config">http://localhost:7627/snapraid/v2/config</a> | jq
curl -X PATCH <a href="http://localhost:7627/snapraid/v2/config">http://localhost:7627/snapraid/v2/config</a> \
&nbsp;&nbsp;&nbsp;&nbsp;--json '{ "probe_interval_minutes": 10 }'
2026-02-14 09:40:46 +01:00
</pre>
</div>
</div>
<div class="manual-section-level-2">
2026-03-01 12:11:35 +01:00
<h2 id="sec7-4" class="manual-title-level-2">
2026-02-14 09:40:46 +01:00
Activity Control
</h2>
<p>All operations that modify the array state are asynchronous; they
return an HTTP 202 Accepted status and queue a task for background
execution.
</p><p>Because tasks run in the background, these endpoints are used to
monitor progress and manage the execution lifecycle.
</p><div class="manual-section-level-3">
2026-03-01 12:11:35 +01:00
<h3 id="sec7-4-1" class="manual-title-level-3">
2026-02-14 09:40:46 +01:00
/snapraid/v1/activity
</h3>
<p>Provides real-time telemetry for the currently executing task,
including a progress percentage, estimated time of completion (ETA),
and a live stream of the process log output.
If no task is in execution, it returns the last completed task.
</p><p>Example:
</p><pre>
2026-03-01 12:11:35 +01:00
curl -s <a href="http://localhost:7627/snapraid/v1/activity">http://localhost:7627/snapraid/v1/activity</a> | jq
2026-02-14 09:40:46 +01:00
</pre>
</div>
<div class="manual-section-level-3">
2026-03-01 12:11:35 +01:00
<h3 id="sec7-4-2" class="manual-title-level-3">
2026-02-14 09:40:46 +01:00
/snapraid/v1/tasks
</h3>
<p>Lists all tasks waiting, the task currently active, and the task
execution history. The response from this entry point can be very long,
as the history may span up to a month.
</p><p>Example:
</p><pre>
2026-03-01 12:11:35 +01:00
curl -s <a href="http://localhost:7627/snapraid/v1/tasks">http://localhost:7627/snapraid/v1/tasks</a> | jq
2026-02-14 09:40:46 +01:00
</pre>
</div>
<div class="manual-section-level-3">
2026-03-01 12:11:35 +01:00
<h3 id="sec7-4-3" class="manual-title-level-3">
2026-02-14 09:40:46 +01:00
/snapraid/v1/stop
</h3>
<p>Terminates the currently running task (such as sync or scrub) by
sending a SIGTERM signal to the background process.
</p><p>Example:
</p><pre>
2026-10-29 06:56:28 +01:00
curl <a href="http://localhost:7627/snapraid/v1/stop">http://localhost:7627/snapraid/v1/stop</a> \
&nbsp;&nbsp;&nbsp;&nbsp;--json '{}'
</pre>
</div>
<div class="manual-section-level-3">
<h3 id="sec7-4-4" class="manual-title-level-3">
/snapraid/v1/clear
</h3>
<p>Cancels all tasks currently waiting in the execution queue, moving
them to the task execution history with canceled status. Any task
currently running is unaffected.
</p><p>Example:
</p><pre>
curl <a href="http://localhost:7627/snapraid/v1/clear">http://localhost:7627/snapraid/v1/clear</a> \
&nbsp;&nbsp;&nbsp;&nbsp;--json '{}'
2026-02-14 09:40:46 +01:00
</pre>
</div>
</div>
<div class="manual-section-level-2">
2026-03-01 12:11:35 +01:00
<h2 id="sec7-5" class="manual-title-level-2">
2026-02-14 09:40:46 +01:00
State and Cache Management
</h2>
<p>To optimize performance and support lightweight monitoring (such as
desktop status bars), the daemon implements a state synchronization
mechanism via the /v1/state endpoint.
</p><div class="manual-section-level-3">
2026-03-01 12:11:35 +01:00
<h3 id="sec7-5-1" class="manual-title-level-3">
2026-02-14 09:40:46 +01:00
/snapraid/v1/state
</h3>
<p>The response provides a high-level summary of the daemon's current
operation and health, alongside a pulse object containing sequence
counters.
</p><p>The pulse object contains counters used for cache invalidation. Each
field corresponds directly to a data-heavy API entry point.
</p><p>If a counter has not changed since the last request, the corresponding
entry point is guaranteed to return the same data. If a counter is
different, the underlying subsystem state has evolved, and the entry
point will potentially return updated information.
</p><p>Note that the counters are not necessarily monotonically increasing
because they are reset if the daemon restarts. You should compare
them only for equality.
</p><p>Example:
</p><pre>
2026-10-29 06:56:28 +01:00
curl -s <a href="http://localhost:7627/snapraid/v1/state">http://localhost:7627/snapraid/v1/state</a> | jq
2026-02-14 09:40:46 +01:00
</pre>
</div>
</div>
<div class="manual-section-level-2">
2026-03-01 12:11:35 +01:00
<h2 id="sec7-6" class="manual-title-level-2">
2026-02-14 09:40:46 +01:00
Schedule
</h2>
<p>The schedule entry point allows batching multiple SnapRAID commands
into a single sequential session. Upon submission, the daemon executes
tasks in the order provided, maintaining a single-threaded execution
flow.
</p><p>The daemon enforces strict serialization for all operations. Only one
task can access the array at a time. All scheduled tasks are placed
in an execution queue and executed in their scheduled order.
</p><p>To ensure data safety, the daemon employs a fail-fast policy where any
command failure triggers the immediate cancellation of all subsequent
tasks within the same schedule request. This prevents operations from
running against an unstable or inconsistent array state while
preserving any independent tasks previously queued in the system.
</p><p>The only exception is the report command, which acts as a mandatory
finalizer. It will execute regardless of previous failures to ensure
the generation of a report that reflects the final state of the system.
</p><div class="manual-section-level-3">
2026-03-01 12:11:35 +01:00
<h3 id="sec7-6-1" class="manual-title-level-3">
2026-02-14 09:40:46 +01:00
/snapraid/v1/schedule
</h3>
<p>Queues a sequence of standard SnapRAID operations.
</p><p>Example:
</p><pre>
2026-10-29 06:56:28 +01:00
curl <a href="http://localhost:7627/snapraid/v1/schedule">http://localhost:7627/snapraid/v1/schedule</a> \
&nbsp;&nbsp;&nbsp;&nbsp;--json '{"tasks": [{"command": "diff"}, {"command": "report"}]}'
2026-02-14 09:40:46 +01:00
</pre>
<p>Supported Commands:
</p><div class="manual-tag-list">
<div class="manual-tag-entry">
<div class="manual-tag-name">
up
</div><div class="manual-tag-description">
Spins up all drives in the array.
2026-02-19 17:18:37 +01:00
</div>
</div>
2026-02-14 09:40:46 +01:00
<div class="manual-tag-entry">
<div class="manual-tag-name">
down
</div><div class="manual-tag-description">
Spins down array drives to save power.
2026-02-19 17:18:37 +01:00
</div>
</div>
2026-02-14 09:40:46 +01:00
<div class="manual-tag-entry">
<div class="manual-tag-name">
probe
</div><div class="manual-tag-description">
Verifies the power status of all configured disks and gathers
SMART information for those already spinning.
2026-02-19 17:18:37 +01:00
</div>
</div>
2026-02-14 09:40:46 +01:00
<div class="manual-tag-entry">
<div class="manual-tag-name">
smart
</div><div class="manual-tag-description">
Collects and parses SMART attributes from all drives to assess
physical health.
2026-02-19 17:18:37 +01:00
</div>
</div>
2026-02-14 09:40:46 +01:00
<div class="manual-tag-entry">
<div class="manual-tag-name">
diff
</div><div class="manual-tag-description">
Scans the array to identify changed, added, or deleted files
since the last sync.
2026-02-19 17:18:37 +01:00
</div>
</div>
2026-02-14 09:40:46 +01:00
<div class="manual-tag-entry">
<div class="manual-tag-name">
status
</div><div class="manual-tag-description">
Provides a summary of the array state, including parity
levels and data distribution.
2026-02-19 17:18:37 +01:00
</div>
</div>
2026-02-14 09:40:46 +01:00
<div class="manual-tag-entry">
<div class="manual-tag-name">
sync
</div><div class="manual-tag-description">
Updates the parity information to match the current state of
the data disks.
2026-02-19 17:18:37 +01:00
</div>
</div>
2026-02-14 09:40:46 +01:00
<div class="manual-tag-entry">
<div class="manual-tag-name">
scrub
</div><div class="manual-tag-description">
Verifies the integrity of the data and parity by recalculating
checksums for a portion of the array.
2026-02-19 17:18:37 +01:00
</div>
</div>
2026-02-14 09:40:46 +01:00
<div class="manual-tag-entry">
<div class="manual-tag-name">
check
</div><div class="manual-tag-description">
Performs a full verification of the array integrity without
modifying any data.
2026-02-19 17:18:37 +01:00
</div>
</div>
2026-02-14 09:40:46 +01:00
<div class="manual-tag-entry">
<div class="manual-tag-name">
fix
</div><div class="manual-tag-description">
Attempts to recover deleted files or repair corrupted data using
the parity information.
2026-02-19 17:18:37 +01:00
</div>
</div>
2026-02-14 09:40:46 +01:00
<div class="manual-tag-entry">
<div class="manual-tag-name">
report
</div><div class="manual-tag-description">
Generates a comprehensive summary of the last operations and
2026-10-29 06:56:28 +01:00
array statistics. When a fix command has been executed, the
report includes a recovery section listing all files recovered
or unrecoverable since the last sync, reflecting the current
repair status of the array.
2026-02-19 17:18:37 +01:00
</div>
</div>
2026-02-14 09:40:46 +01:00
<div class="manual-tag-entry">
<div class="manual-tag-name">
down_idle
</div><div class="manual-tag-description">
Executes a conditional spindown operation of the disks that
2026-03-08 17:40:50 +01:00
have exceeded the <b>spindown_idle_minutes</b> threshold.
2026-02-19 17:18:37 +01:00
</div>
</div>
</div>
2026-02-14 09:40:46 +01:00
</div>
</div>
</div>
<div class="manual-section-level-1">
2026-03-01 12:11:35 +01:00
<h1 id="sec8" class="manual-title-level-1">
2026-10-29 06:56:28 +01:00
Multiple arrays in Linux systemd
</h1>
<p>To manage multiple independent SnapRAID arrays on a single systemd
host, you can run multiple daemon instances using the systemd
template unit <b>snapraidd@.service</b>.
</p><p>Each instance runs isolated under its own configuration, listening port,
and SnapRAID array config.
</p><p>To configure multiple instances:
</p><p>Create distinct daemon configuration files:
</p><pre>
cp /etc/snapraidd.conf /etc/snapraidd-main.conf
cp /etc/snapraidd.conf /etc/snapraidd-backup.conf
</pre>
<p>Edit <b>/etc/snapraidd-main.conf</b> to set a custom port and log folder:
</p><pre>
net_port = 127.0.0.1:7627
sys_log_directory = /var/log/snapraid/main
</pre>
<p>Edit <b>/etc/snapraidd-backup.conf</b> to use a different port and log folder:
</p><pre>
net_port = 127.0.0.1:7628
sys_log_directory = /var/log/snapraid/backup
</pre>
<p>Disable the default single-array service (if running):
</p><pre>
systemctl disable --now snapraidd.service
</pre>
<p>Create distinct SnapRAID engine configuration files for each array,
e.g. <b>/etc/snapraid-main.conf</b> and <b>/etc/snapraid-backup.conf</b>,
each pointing to its own set of disks and parity drives.
</p><p>Enable and start the template instances. The instance name after the
@ corresponds to the suffix of the config file. For example, <b>main</b>
will load <b>/etc/snapraidd-main.conf</b> and use <b>/etc/snapraid-main.conf</b>
as the SnapRAID engine configuration:
</p><pre>
systemctl enable --now snapraidd@main
systemctl enable --now snapraidd@backup
</pre>
<p>Access the independent dashboards at:
</p><pre>
<a href="http://localhost:7627">http://localhost:7627</a>
<a href="http://localhost:7628">http://localhost:7628</a>
</pre>
</div>
<div class="manual-section-level-1">
<h1 id="sec9" class="manual-title-level-1">
Multiple arrays in Windows
</h1>
<p>To manage multiple independent SnapRAID arrays on a Windows host,
you can install multiple distinct Windows service instances of the
daemon using the <b>--service-install</b> command with the <b>-i</b> option.
</p><p>Each instance runs under its own configuration and listening port.
</p><p>To configure multiple instances:
</p><p>Create distinct daemon configuration files in your installation directory:
</p><pre>
copy C:\snapraid\snapraidd.conf C:\snapraid\snapraidd-main.conf
copy C:\snapraid\snapraidd.conf C:\snapraid\snapraidd-backup.conf
</pre>
<p>Edit <b>C:\snapraid\snapraidd-main.conf</b> to set a custom port and log folder:
</p><pre>
net_port = 127.0.0.1:7627
sys_log_directory = C:\snapraid\log\main
</pre>
<p>Edit <b>C:\snapraid\snapraidd-backup.conf</b> to use a different port and log folder:
</p><pre>
net_port = 127.0.0.1:7628
sys_log_directory = C:\snapraid\log\backup
</pre>
<p>Remove the default service instance (if registered):
</p><pre>
C:\snapraid\snapraidd.exe --service-remove
</pre>
<p>Create distinct SnapRAID engine configuration files for each array,
e.g. <b>C:\snapraid\snapraid-main.conf</b> and
<b>C:\snapraid\snapraid-backup.conf</b>, each pointing to its own set of
disks and parity drives.
</p><p>Install the service instances using the <b>--service-install</b> option.
Use <b>-c</b> to specify the daemon configuration file and <b>-C</b> to specify
the SnapRAID engine configuration file for each instance:
</p><pre>
C:\snapraid\snapraidd.exe --service-install -i main -c C:\snapraid\snapraidd-main.conf -C C:\snapraid\snapraid-main.conf
C:\snapraid\snapraidd.exe --service-install -i backup -c C:\snapraid\snapraidd-backup.conf -C C:\snapraid\snapraid-backup.conf
</pre>
<p>This registers and starts two Windows services named <b>snapraidd-main</b> and
<b>snapraidd-backup</b> configured to start automatically.
</p><p>Access the independent dashboards at:
</p><pre>
<a href="http://localhost:7627">http://localhost:7627</a>
<a href="http://localhost:7628">http://localhost:7628</a>
</pre>
<p>To remove a service instance, run the <b>--service-remove</b> option:
</p><pre>
C:\snapraid\snapraidd.exe --service-remove -i main
C:\snapraid\snapraidd.exe --service-remove -i backup
</pre>
</div>
<div class="manual-section-level-1">
<h1 id="sec10" class="manual-title-level-1">
2026-02-14 09:40:46 +01:00
Signals
</h1>
2026-02-19 17:50:33 +01:00
<p>This section defines how the daemon responds to standard Unix signals,
allowing for external process control and graceful management of the
service lifecycle.
</p><div class="manual-section-level-3">
<h3 class="manual-title-level-3">
SIGHUP
</h3>
<p>Reloads the configuration file and resets the internal state.
2026-02-14 09:40:46 +01:00
It also reloads the Web UI. This is the recommended way to
apply changes to static&nbsp;&nbsp;&nbsp;&nbsp;parameters without restarting the
service.
2026-02-19 17:50:33 +01:00
</p></div>
<div class="manual-section-level-3">
<h3 class="manual-title-level-3">
SIGTERM, SIGINT
</h3>
<p>Initiates a graceful shutdown. If a task is currently
2026-10-29 06:56:28 +01:00
running, the active SnapRAID process is terminated, the
post-run hook is executed and any paused Docker containers are
unpaused.
2026-02-19 17:50:33 +01:00
</p></div>
<div class="manual-section-level-3">
<h3 class="manual-title-level-3">
SIGQUIT
</h3>
<p>Immediately terminates the process using the default signal
2026-02-14 09:40:46 +01:00
action and may generate a core dump. This signal is intended
for emergency debugging and post mortem analysis of a hung
or misbehaving daemon. No cleanup or graceful shutdown is
performed.
</p></div>
2026-02-19 17:50:33 +01:00
</div>
2026-02-14 09:40:46 +01:00
<div class="manual-section-level-1">
2026-10-29 06:56:28 +01:00
<h1 id="sec11" class="manual-title-level-1">
2026-02-14 09:40:46 +01:00
Files
</h1>
2026-02-19 17:50:33 +01:00
<p>The following list specifies the default filesystem paths used by the
daemon for configuration, data persistence, and inter-process communication.
2026-03-17 00:12:13 +01:00
</p><div class="manual-section-level-2">
2026-10-29 06:56:28 +01:00
<h2 id="sec11-1" class="manual-title-level-2">
2026-03-17 00:12:13 +01:00
Linux
</h2>
<p>On Linux and Unix-like systems:
2026-02-19 17:50:33 +01:00
</p><div class="manual-section-level-3">
2026-10-29 06:56:28 +01:00
<h3 id="sec11-1-1" class="manual-title-level-3">
2026-02-19 17:50:33 +01:00
$PREFIX/etc/snapraidd.conf
</h3>
<p>The primary configuration file location. The $PREFIX variable
2026-02-14 09:40:46 +01:00
represents the installation path chosen at build time (typically
2026-02-19 17:18:37 +01:00
via the <b>--prefix</b> argument to the configure script). Common
values include <b>/usr/local</b> or <b>/usr</b>. If this file does not
exist, the daemon falls back to <b>/etc/snapraidd.conf</b>.
2026-02-19 17:50:33 +01:00
</p></div>
<div class="manual-section-level-3">
2026-10-29 06:56:28 +01:00
<h3 id="sec11-1-2" class="manual-title-level-3">
2026-02-19 17:50:33 +01:00
$PREFIX/share/snapraidd
</h3>
<p>The primary system data directory. This is the first location
2026-10-29 06:56:28 +01:00
searched for the web dashboard ZIP file (e.g., commander.zip or brutale.zip).
2026-02-19 17:18:37 +01:00
If not found here, the daemon falls back to <b>/usr/share/snapraidd</b>.
2026-02-19 17:50:33 +01:00
</p></div>
<div class="manual-section-level-3">
2026-10-29 06:56:28 +01:00
<h3 id="sec11-1-3" class="manual-title-level-3">
2026-02-14 09:40:46 +01:00
/etc/snapraidd.conf
2026-02-19 17:50:33 +01:00
</h3>
<p>The secondary/system-wide configuration file location, used if
2026-02-14 09:40:46 +01:00
the prefix-specific file is missing.
2026-02-19 17:50:33 +01:00
</p></div>
<div class="manual-section-level-3">
2026-10-29 06:56:28 +01:00
<h3 id="sec11-1-4" class="manual-title-level-3">
2026-02-14 09:40:46 +01:00
/usr/share/snapraidd
2026-02-19 17:50:33 +01:00
</h3>
<p>The secondary/system-wide data directory, used as a fallback for
2026-02-14 09:40:46 +01:00
web assets.
2026-02-19 17:50:33 +01:00
</p></div>
<div class="manual-section-level-3">
2026-10-29 06:56:28 +01:00
<h3 id="sec11-1-5" class="manual-title-level-3">
2026-02-14 09:40:46 +01:00
/run/snapraidd.pid
2026-02-19 17:50:33 +01:00
</h3>
<p>Default PID file location.
</p></div>
<div class="manual-section-level-3">
2026-10-29 06:56:28 +01:00
<h3 id="sec11-1-6" class="manual-title-level-3">
2026-02-14 09:40:46 +01:00
/var/log/snapraid
2026-02-19 17:50:33 +01:00
</h3>
<p>Default directory for SnapRAID command execution logs. This
2026-02-14 09:40:46 +01:00
directory contains the output of the SnapRAID binary itself,
rather than the daemon's service logs.
2026-03-17 00:12:13 +01:00
If this directory does not exist, the daemon will attempt to create it
upon the first execution of a SnapRAID command.
</p></div>
</div>
<div class="manual-section-level-2">
2026-10-29 06:56:28 +01:00
<h2 id="sec11-2" class="manual-title-level-2">
2026-03-17 00:12:13 +01:00
Windows
</h2>
<p>On Windows systems:
</p><div class="manual-section-level-3">
2026-10-29 06:56:28 +01:00
<h3 id="sec11-2-1" class="manual-title-level-3">
2026-03-17 00:12:13 +01:00
snapraidd.conf
</h3>
<p>The configuration file is expected to be in the same directory
where the <b>snapraidd.exe</b> binary is located.
2026-02-19 17:50:33 +01:00
</p></div>
2026-03-17 00:12:13 +01:00
<div class="manual-section-level-3">
2026-10-29 06:56:28 +01:00
<h3 id="sec11-2-2" class="manual-title-level-3">
2026-03-17 00:12:13 +01:00
log\
</h3>
<p>A subdirectory named <b>log</b> within the installation directory is
used to store the SnapRAID command execution logs. If this
directory does not exist, the service will attempt to create it
upon the first execution of a SnapRAID command.
</p></div>
<div class="manual-section-level-3">
2026-10-29 06:56:28 +01:00
<h3 id="sec11-2-3" class="manual-title-level-3">
commander.zip or brutale.zip
2026-03-17 00:12:13 +01:00
</h3>
<p>The web dashboard assets are searched for in the same directory
as the executable.
</p></div>
</div>
2026-10-29 06:56:28 +01:00
</div>
<div class="manual-section-level-1">
<h1 id="sec12" class="manual-title-level-1">
Known Issues
</h1>
<div class="manual-section-level-2">
<h2 id="sec12-1" class="manual-title-level-2">
Monotonic Time Assumption
</h2>
<p>The daemon assumes that time progresses monotonically.
</p><p>Historical log files are named using the local wall-clock time and are
replayed in filename order at startup. If the local clock moves
backwards, for example during a daylight-saving-time transition or
after a manual clock adjustment, logs created later may be replayed
before older ones, or two tasks may generate the same log filename.
</p><p>The daemon also assumes that the modification time of the SnapRAID
content file increases whenever the file is updated. If the system
clock moves backwards and the content file is subsequently modified
by a SnapRAID command executed outside the daemon, the startup probe
may not detect the newer content state.
</p><p>For correct state reconstruction, the system clock and local civil
time are therefore expected not to move backwards while retained
daemon logs or
</p></div>
<div class="manual-section-level-2">
<h2 id="sec12-2" class="manual-title-level-2">
Lifetime Counters Depend on Log Retention
</h2>
<p>Some cumulative statistics are reconstructed at startup from the
retained daemon logs rather than from separately persistent state.
</p><p>When old logs are removed according to the configured log retention
period, information contained only in those logs is no longer
available during a subsequent restart. As a result, cumulative
counters reconstructed from the available history may decrease or
restart from zero after older logs have been removed.
</p><p>Such counters should therefore be interpreted as covering the history
available in the retained daemon logs, rather than necessarily the
complete lifetime of the installation.
</p></div>
<div class="manual-section-level-2">
<h2 id="sec12-3" class="manual-title-level-2">
Incomplete Log Recovery
</h2>
<p>Incomplete daemon logs are recovered only up to the last complete
record that can be parsed successfully.
</p><p>For plain logs, a final unterminated line is discarded. For compressed
logs, a truncated gzip stream may still be recovered up to the last
complete decompressed record available before the truncation.
</p><p>Any data contained only in an incomplete final record is therefore
lost during restart reconstruction. Tasks without the required final
termination information are treated as interrupted according to the
available log state.
</p><p>Log recovery should therefore be considered best effort and guarantees
only the preservation of complete records successfully written before
the interruption.
</p></div>
<div class="manual-section-level-2">
<h2 id="sec12-4" class="manual-title-level-2">
Configuration Changes
</h2>
<p>Configuration updates and reloads are applied asynchronously and are not
guaranteed to take effect atomically or immediately across all runtime
components and operations.
</p><p>For a short transition period, components and in-flight operations may
observe settings from different configuration generations at different
points in their lifecycle, while tasks already scheduled or running may
continue using settings captured before the change.
</p><p>This also applies to security-sensitive settings. In-flight REST requests
and already accepted connections may continue under previously admitted
conditions or observe security settings from different configuration
generations.
</p></div>
<div class="manual-section-level-2">
<h2 id="sec12-5" class="manual-title-level-2">
Non-UTF-8 Paths in the REST API
</h2>
<p>On Unix, filesystem paths containing invalid UTF-8 bytes are represented
in the REST API with Python's surrogateescape encoding (PEP 383).
Non-decodable bytes in the range 0x80-0xFF are mapped to lone Unicode
surrogate code points in the range U+DC80-U+DCFF (formatted in JSON as
<b>\udc80</b>-<b>\udcff</b>), allowing paths with arbitrary byte sequences to be
represented losslessly across the REST API.
</p></div>
<div class="manual-section-level-2">
<h2 id="sec12-6" class="manual-title-level-2">
Devices Without Stable or Unique IDs
</h2>
<p>The daemon relies on stable and unique device identifiers, such as hardware
serial numbers, to preserve physical device health information across mapping
updates.
</p><p>If a device exposes no stable identifier, or if an identifier is not unique
across the currently detected devices, it cannot be trusted as a persistent
physical-device identity. This can happen with virtual disks, certain USB
enclosures, cloned identifiers, or hardware that reports incomplete or
ambiguous identification data.
</p><p>The daemon therefore discards historical device information when the device
cannot be identified reliably.
</p><p>As a result, previous SMART or health state may be lost until fresh telemetry
is collected.
</p></div>
<div class="manual-section-level-2">
<h2 id="sec12-7" class="manual-title-level-2">
Concurrent Docker Changes During Hooks
</h2>
<p>Docker container state is inspected before the daemon performs its
pause and resume operations.
</p><p>Concurrent external Docker operations, such as pausing, unpausing, or
removing a selected container outside the daemon while a task is running,
may cause the daemon to unpause a container that was externally paused,
or cause unpause cleanup to fail if the container was removed.
</p><p>External changes to selected containers should not be performed while
a hook lifecycle is being established or is active.
</p></div>
<div class="manual-section-level-2">
<h2 id="sec12-8" class="manual-title-level-2">
Blocking Hooks, Docker Operations, and Notifications
</h2>
<p>Hook scripts, Docker operations, and notification commands are expected
to terminate.
</p><p>If any of these operations block indefinitely, task execution, hook
cleanup, report generation, notification processing, and graceful
daemon shutdown may also remain blocked. Paused Docker containers
may remain paused until external recovery is performed.
</p></div>
<div class="manual-section-level-2">
<h2 id="sec12-9" class="manual-title-level-2">
Incomplete JSON syntax validation
</h2>
<p>The REST API uses JSMN in strict mode, which does not fully validate
the JSON grammar. Some malformed JSON inputs, such as trailing commas
or repeated colons, may therefore be accepted and processed normally.
</p></div>
<div class="manual-section-level-2">
<h2 id="sec12-10" class="manual-title-level-2">
Global Authentication Rate Limiting Can Starve New Clients
</h2>
<p>REST authentication globally rate-limits uncached attempts to bound Argon2
CPU and memory usage. A continuous stream of uncached attempts can therefore
consume every authentication slot and cause other uncached clients to receive
HTTP 429 indefinitely.
</p><p>Cached credentials bypass the limit. This is an intentional tradeoff: per-client
limits do not protect against distributed sources, while removing the global
limit could allow concurrent Argon2 operations to exhaust system resources.
</p></div>
<div class="manual-section-level-2">
<h2 id="sec12-11" class="manual-title-level-2">
Configuration File ACLs Are Not Preserved
</h2>
<p>Configuration updates made through the REST API rewrite the daemon
configuration using a temporary file followed by file replacement.
</p><p>On Unix, the replacement preserves the original file owner, group, and
standard permission bits, but it does not preserve extended POSIX ACLs
or other per-file access-control metadata.
</p><p>On Windows, a replacement file may likewise receive security settings
derived from its creation context rather than preserving a custom
security descriptor attached to the original configuration file.
</p></div>
2026-02-14 09:40:46 +01:00
</div>
</div>
</main>
</div>
<!-- Footer -->
<footer>
<div class="container footer-content">
<div class="footer-col">
2026-03-17 23:49:03 +01:00
<div class="logo">
<img src="android-chrome-192x192.png" width="32" height="32"/>
SnapRAID
</div>
2026-02-14 09:40:46 +01:00
<p>Copyright &copy; 2026 Andrea Mazzoleni</p>
<p class="license">Distributed under GPL v3 License</p>
</div>
<div class="footer-col">
2026-04-14 09:47:17 +02:00
<h4>Links</h4>
2026-04-14 09:56:55 +02:00
<ul class="footer-list">
2026-04-14 09:47:17 +02:00
<li><a href="https://github.com/amadvance/snapraid/">GitHub SnapRAID CLI</a></li>
<li><a href="https://github.com/amadvance/snapraid-daemon/">GitHub SnapRAID Daemon</a></li>
<li><a href="https://www.reddit.com/r/Snapraid/">Reddit</a></li>
<li><a href="https://sourceforge.net/p/snapraid/">SourceForge</a></li>
</ul>
2026-02-14 09:40:46 +01:00
</div>
</div>
</footer>
</body>
</html>