mirror of
https://github.com/amadvance/snapraid.git
synced 2026-10-26 19:01:57 -04:00
958 lines
35 KiB
HTML
958 lines
35 KiB
HTML
<!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>
|
|
<style>html,body{background-color:#020617;color:#f8fafc;}</style>
|
|
<link rel="stylesheet" href="style.css">
|
|
<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">
|
|
<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">
|
|
<img src="favicon-32x32.png"/>
|
|
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>
|
|
</ul>
|
|
</nav>
|
|
</div>
|
|
</header>
|
|
|
|
|
|
<div class="container manual-layout">
|
|
<aside class="manual-sidebar">
|
|
|
|
<h4>Components</h4>
|
|
<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;">
|
|
<option value="manual.html">Command Line</option>
|
|
<option value="manual-daemon.html">Daemon</option>
|
|
<option value="manual-log.html">Log</option>
|
|
</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>
|
|
snapraidd [-c, --conf CONFIG] [-f, --foreground] [-p, --pidfile FILE]
|
|
[-N, --no-cache] [-v, --verbose]
|
|
</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>
|
|
<p>SnapRAID-Daemon is a specialized companion service designed to move SnapRAID
|
|
from a manual, command-line interface (CLI) workflow to an 'always-on'
|
|
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:
|
|
`$PREFIX/etc/snapraidd.conf` and `/etc/snapraidd.conf` if
|
|
not found. The $PREFIX variable represents the installation
|
|
path chosen at build time (typically via the `--prefix`
|
|
argument to the configure script).
|
|
</div> <!-- description -->
|
|
</div> <!-- entry -->
|
|
</div> <!-- list -->
|
|
<div class="manual-option-list">
|
|
<div class="manual-option-entry">
|
|
<div class="manual-option-name">
|
|
-f, --foreground
|
|
</div><div class="manual-option-description">
|
|
Runs the process in the foreground. This prevents the
|
|
daemon from detaching from the terminal (daemonizing).
|
|
</div> <!-- description -->
|
|
</div> <!-- entry -->
|
|
</div> <!-- list -->
|
|
<div class="manual-option-list">
|
|
<div class="manual-option-entry">
|
|
<div class="manual-option-name">
|
|
-p, --pidfile FILE
|
|
</div><div class="manual-option-description">
|
|
Overrides the default location for the PID file. Default:
|
|
`/run/snapraidd.pid`.
|
|
</div> <!-- description -->
|
|
</div> <!-- entry -->
|
|
</div> <!-- list -->
|
|
<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.
|
|
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.
|
|
</div> <!-- description -->
|
|
</div> <!-- entry -->
|
|
</div> <!-- list -->
|
|
<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.
|
|
</div> <!-- description -->
|
|
</div> <!-- entry -->
|
|
</div> <!-- list -->
|
|
<div class="manual-option-list">
|
|
<div class="manual-option-entry">
|
|
<div class="manual-option-name">
|
|
-H, --help
|
|
</div><div class="manual-option-description">
|
|
Prints a short help screen.
|
|
</div> <!-- description -->
|
|
</div> <!-- entry -->
|
|
</div> <!-- list -->
|
|
<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.
|
|
</div> <!-- description -->
|
|
</div> <!-- entry -->
|
|
</div> <!-- list -->
|
|
</div>
|
|
<div class="manual-section-level-1">
|
|
<h1 id="sec4" class="manual-title-level-1">
|
|
Configuration
|
|
</h1>
|
|
<p>The SnapRAID Daemon is configured via a plain-text .conf file,
|
|
defaulting to $PREFIX/etc/snapraidd.conf and if not found to
|
|
/etc/snapraidd.conf. The $PREFIX variable represents the installation
|
|
path chosen at build time (typically via the `--prefix` argument to
|
|
the configure script).
|
|
</p><p>This file governs the behavior of the automation engine, network
|
|
accessibility, safety interlocks, and hardware monitoring parameters.
|
|
</p><p>The configuration system is designed with a "hybrid" management
|
|
philosophy to balance convenience with system security:
|
|
</p><div class="manual-tag-list">
|
|
<div class="manual-tag-entry">
|
|
<div class="manual-tag-name">
|
|
Static_Parameters
|
|
</div><div class="manual-tag-description">
|
|
Critical security and networking settings, such
|
|
as the listening port (net_port) and the system user for
|
|
scripts (script_run_as_user), are immutable via the REST API.
|
|
These require manual file edits followed by a SIGHUP signal
|
|
(e.g., systemctl reload snapraidd) to take effect.
|
|
</div> <!-- description -->
|
|
</div> <!-- entry -->
|
|
</div> <!-- list -->
|
|
<div class="manual-tag-list">
|
|
<div class="manual-tag-entry">
|
|
<div class="manual-tag-name">
|
|
Dynamic_Parameters
|
|
</div><div class="manual-tag-description">
|
|
Operational settings, like the maintenance
|
|
schedule or scrub percentages, can be modified in real-time
|
|
via the PATCH /snapraid/v1/config endpoint. Changes made through
|
|
the API are instantly applied to the running process and
|
|
persisted back to the configuration file, preserving any
|
|
manual comments.
|
|
</div> <!-- description -->
|
|
</div> <!-- entry -->
|
|
</div> <!-- list -->
|
|
<p>To prevent race conditions, users should avoid editing the
|
|
configuration file manually while simultaneously issuing configuration
|
|
updates via the REST API. If a manual edit is performed while the
|
|
daemon is active, ensure a reload is triggered immediately to
|
|
synchronize the daemon's internal memory state with the disk.
|
|
</p><p>For complete technical documentation, please refer to the
|
|
`snapraidd.conf.example` file.
|
|
</p><div class="manual-section-level-2">
|
|
<h2 id="sec4-1" class="manual-title-level-2">
|
|
Network & REST API
|
|
</h2>
|
|
<p>These settings control the network interface. These options are not
|
|
visible from the REST API and can be set only in the snapraidd.conf
|
|
file.
|
|
</p><div class="manual-section-level-3">
|
|
<h3 id="sec4-1-1" class="manual-title-level-3">
|
|
net_enabled
|
|
</h3>
|
|
<p>Master toggle for the HTTP interface.
|
|
Set to 1 to enable the REST API, otherwise, the daemon operates in
|
|
local-only mode.
|
|
</p></div>
|
|
<div class="manual-section-level-3">
|
|
<h3 id="sec4-1-2" class="manual-title-level-3">
|
|
net_port
|
|
</h3>
|
|
<p>Defines the IP address and port the daemon binds to (e.g., `127.0.0.1:8080`).
|
|
Supports IPv4, IPv6, and multiple ports.
|
|
</p></div>
|
|
<div class="manual-section-level-3">
|
|
<h3 id="sec4-1-3" class="manual-title-level-3">
|
|
net_acl
|
|
</h3>
|
|
<p>Restricts API access to specific client IPs using a comma-separated
|
|
list of allow (+) or deny (-) rules.
|
|
</p></div>
|
|
<div class="manual-section-level-3">
|
|
<h3 id="sec4-1-4" class="manual-title-level-3">
|
|
net_security_headers
|
|
</h3>
|
|
<p>When enabled (1), injects security headers like CSP and X-Frame-Options
|
|
to harden the API against browser-based attacks.
|
|
</p></div>
|
|
<div class="manual-section-level-3">
|
|
<h3 id="sec4-1-5" class="manual-title-level-3">
|
|
net_allowed_origin
|
|
</h3>
|
|
<p>Configures CORS. Use `self` for standard setups, `none` to block
|
|
browser access, or a specific URL for custom dashboards.
|
|
</p></div>
|
|
<div class="manual-section-level-3">
|
|
<h3 id="sec4-1-6" class="manual-title-level-3">
|
|
net_config_full_access
|
|
</h3>
|
|
<p>Determines if restricted parameters (like scripts and log paths) can
|
|
be modified via the REST API. Defaults to 0 (Read-only).
|
|
</p></div>
|
|
<div class="manual-section-level-3">
|
|
<h3 id="sec4-1-7" class="manual-title-level-3">
|
|
net_web_root
|
|
</h3>
|
|
<p>Specifies the local path where the web dashboard assets are located.
|
|
This option supports both a standard directory and a single compressed
|
|
ZIP file. If a ZIP file is provided, the internal HTTP server will
|
|
serve assets directly from the archive without requiring extraction to
|
|
the disk.
|
|
</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">
|
|
If only a filename is provided (e.g., commander.zip),
|
|
the daemon initiates a search within the standard installation
|
|
data directories. It first checks the directory associated
|
|
with the configured installation prefix, located at
|
|
$PREFIX/share/snapraidd/, and then the system-wide data
|
|
directory at /usr/share/snapraidd/.
|
|
</div> <!-- description -->
|
|
</div> <!-- entry -->
|
|
<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.
|
|
</div> <!-- description -->
|
|
</div> <!-- entry -->
|
|
<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/).
|
|
</div> <!-- description -->
|
|
</div> <!-- entry -->
|
|
</div> <!-- list -->
|
|
<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.
|
|
</p></div>
|
|
</div>
|
|
<div class="manual-section-level-2">
|
|
<h2 id="sec4-2" class="manual-title-level-2">
|
|
Automation & Maintenance
|
|
</h2>
|
|
<p>These settings control the automation and maintenance tasks run by
|
|
the SnapRAID daemon.
|
|
</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">
|
|
<h3 id="sec4-2-1" class="manual-title-level-3">
|
|
maintenance_schedule
|
|
</h3>
|
|
<p>Defines when the automated sync, scrub, and report sequence occurs
|
|
(e.g., `daily 02:00` or `weekly Mon 03:00`).
|
|
</p></div>
|
|
<div class="manual-section-level-3">
|
|
<h3 id="sec4-2-2" class="manual-title-level-3">
|
|
sync_threshold_deletes
|
|
</h3>
|
|
<p>Maximum number of deleted/missing files allowed before a scheduled
|
|
sync is aborted to prevent accidental parity loss.
|
|
</p></div>
|
|
<div class="manual-section-level-3">
|
|
<h3 id="sec4-2-3" class="manual-title-level-3">
|
|
sync_threshold_updates
|
|
</h3>
|
|
<p>Maximum number of modified files allowed before a scheduled sync is
|
|
suspended.
|
|
</p></div>
|
|
<div class="manual-section-level-3">
|
|
<h3 id="sec4-2-4" class="manual-title-level-3">
|
|
sync_prehash
|
|
</h3>
|
|
<p>Enables the SnapRAID prehash option to verify files before updating
|
|
parity, protecting against faulty RAM or cables.
|
|
</p></div>
|
|
<div class="manual-section-level-3">
|
|
<h3 id="sec4-2-5" class="manual-title-level-3">
|
|
sync_force_zero
|
|
</h3>
|
|
<p>Permits synchronization even if protected files have unexpectedly
|
|
shrunk to zero bytes.
|
|
</p></div>
|
|
<div class="manual-section-level-3">
|
|
<h3 id="sec4-2-6" class="manual-title-level-3">
|
|
scrub_percentage
|
|
</h3>
|
|
<p>The percentage of the array verified during the scrub phase of
|
|
automated maintenance.
|
|
</p></div>
|
|
<div class="manual-section-level-3">
|
|
<h3 id="sec4-2-7" class="manual-title-level-3">
|
|
scrub_older_than
|
|
</h3>
|
|
<p>Restricts scrubbing to blocks that have not been verified within the
|
|
specified number of days.
|
|
</p></div>
|
|
<div class="manual-section-level-3">
|
|
<h3 id="sec4-2-8" class="manual-title-level-3">
|
|
probe_interval_minutes
|
|
</h3>
|
|
<p>Interval for background health checks. SMART attributes are only
|
|
queried if disks are already active to avoid waking them.
|
|
</p></div>
|
|
<div class="manual-section-level-3">
|
|
<h3 id="sec4-2-9" class="manual-title-level-3">
|
|
spindown_idle_minutes
|
|
</h3>
|
|
<p>Inactivity threshold (in minutes) after which the daemon will issue a
|
|
spindown command to the disks.
|
|
</p></div>
|
|
<div class="manual-section-level-3">
|
|
<h3 id="sec4-2-10" class="manual-title-level-3">
|
|
script_run_as_user
|
|
</h3>
|
|
<p>The system user account utilized for the execution of pre- and
|
|
post-run hooks.
|
|
</p></div>
|
|
<div class="manual-section-level-3">
|
|
<h3 id="sec4-2-11" class="manual-title-level-3">
|
|
script_pre_run/script_post_run
|
|
</h3>
|
|
<p>Absolute paths to executable shell scripts triggered before or after
|
|
SnapRAID activity.
|
|
</p></div>
|
|
</div>
|
|
<div class="manual-section-level-2">
|
|
<h2 id="sec4-3" class="manual-title-level-2">
|
|
Logging & Notifications
|
|
</h2>
|
|
<p>These settings control the logging and notification operations performed
|
|
by the SnapRAID daemon.
|
|
</p><div class="manual-section-level-3">
|
|
<h3 id="sec4-3-1" class="manual-title-level-3">
|
|
log_directory
|
|
</h3>
|
|
<p>Path where individual SnapRAID command outputs are stored as `.log`
|
|
files. Default: `/var/log/snapraid`.
|
|
</p></div>
|
|
<div class="manual-section-level-3">
|
|
<h3 id="sec4-3-2" class="manual-title-level-3">
|
|
log_retention_days
|
|
</h3>
|
|
<p>Number of days to keep log files before they are purged.
|
|
</p></div>
|
|
<div class="manual-section-level-3">
|
|
<h3 id="sec4-3-3" class="manual-title-level-3">
|
|
notify_syslog_enabled
|
|
</h3>
|
|
<p>Enables logging of daemon activity to the OS system log (syslog/journald).
|
|
</p></div>
|
|
<div class="manual-section-level-3">
|
|
<h3 id="sec4-3-4" class="manual-title-level-3">
|
|
notify_syslog_level
|
|
</h3>
|
|
<p>Sets the minimum severity for syslog task entries.
|
|
Possible values: info, warning, error, critical. Default: error.
|
|
</p></div>
|
|
<div class="manual-section-level-3">
|
|
<h3 id="sec4-3-5" class="manual-title-level-3">
|
|
notify_heartbeat
|
|
</h3>
|
|
<p>A shell command (e.g., `curl`) executed only upon task success, ideal
|
|
for "dead man's switch" monitoring.
|
|
</p></div>
|
|
<div class="manual-section-level-3">
|
|
<h3 id="sec4-3-6" class="manual-title-level-3">
|
|
notify_result
|
|
</h3>
|
|
<p>A shell command triggered after task completion; it receives the task
|
|
report via stdin.
|
|
</p></div>
|
|
<div class="manual-section-level-3">
|
|
<h3 id="sec4-3-7" class="manual-title-level-3">
|
|
notify_result_level
|
|
</h3>
|
|
<p>Controls the filter for `notify_result`. The notification is sent only
|
|
if the task result is equal to or more severe than this level.
|
|
Possible values: info, warning, error, critical. Default: error.
|
|
</p></div>
|
|
<div class="manual-section-level-3">
|
|
<h3 id="sec4-3-8" class="manual-title-level-3">
|
|
notify_email_recipient
|
|
</h3>
|
|
<p>Local system email address for receiving health reports.
|
|
</p></div>
|
|
<div class="manual-section-level-3">
|
|
<h3 id="sec4-3-9" class="manual-title-level-3">
|
|
notify_email_level
|
|
</h3>
|
|
<p>Sets the minimum severity for email reports.
|
|
Possible values: info, warning, error, critical. Default: error.
|
|
</p></div>
|
|
<div class="manual-section-level-3">
|
|
<h3 id="sec4-3-10" class="manual-title-level-3">
|
|
notify_differences
|
|
</h3>
|
|
<p>If enabled, includes a detailed list of file changes (added/removed/modified)
|
|
in the notification reports.
|
|
</p></div>
|
|
</div>
|
|
</div>
|
|
<div class="manual-section-level-1">
|
|
<h1 id="sec5" class="manual-title-level-1">
|
|
Rest API
|
|
</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
|
|
specific error codes, please refer to the snapraidd.yaml OpenAPI
|
|
specification file.
|
|
</p><div class="manual-section-level-2">
|
|
<h2 id="sec5-1" class="manual-title-level-2">
|
|
Maintenance & 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.
|
|
They typically end with a `report` command that generates a notification
|
|
with a full report of the result of the operation.
|
|
</p><div class="manual-section-level-3">
|
|
<h3 id="sec5-1-1" class="manual-title-level-3">
|
|
/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.
|
|
This task is subject to the 'sync_threshold_deletes' and
|
|
'sync_threshold_update' safety checks defined in the configuration.
|
|
The percentage of the array checked and the age filter are determined
|
|
by the 'scrub_percentage' and 'scrub_older_than' settings.
|
|
</p><p>Example:
|
|
</p><pre>
|
|
curl -X POST <a href="http://localhost:8080/snapraid/v1/maintenance">http://localhost:8080/snapraid/v1/maintenance</a>
|
|
</pre>
|
|
<p>It is implemented with the sequence of commands: up, diff, sync, scrub, and
|
|
report.
|
|
</p></div>
|
|
<div class="manual-section-level-3">
|
|
<h3 id="sec5-1-2" class="manual-title-level-3">
|
|
/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>
|
|
curl -X POST <a href="http://localhost:8080/snapraid/v1/heal">http://localhost:8080/snapraid/v1/heal</a>
|
|
</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">
|
|
<h3 id="sec5-1-3" class="manual-title-level-3">
|
|
/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>
|
|
curl -s -X POST <a href="http://localhost:8080/snapraid/v1/undelete">http://localhost:8080/snapraid/v1/undelete</a> \
|
|
-H "Content-Type: application/json" \
|
|
-d '{ "filters": [ "*.txt" ] }'
|
|
</pre>
|
|
<p>It is implemented with the sequence of commands: up, fix -m -f ...,
|
|
and report.
|
|
</p></div>
|
|
<div class="manual-section-level-3">
|
|
<h3 id="sec5-1-4" class="manual-title-level-3">
|
|
/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
|
|
'spindown_idle_minutes' threshold. In this case, no report is
|
|
generated.
|
|
</p><p>Example:
|
|
</p><pre>
|
|
curl -X POST <a href="http://localhost:8080/snapraid/v1/suspend_idle">http://localhost:8080/snapraid/v1/suspend_idle</a>
|
|
</pre>
|
|
<p>It is implemented with the sequence of commands: probe, down_idle.
|
|
</p></div>
|
|
</div>
|
|
<div class="manual-section-level-2">
|
|
<h2 id="sec5-2" class="manual-title-level-2">
|
|
Monitoring & 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">
|
|
<h3 id="sec5-2-1" class="manual-title-level-3">
|
|
/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>
|
|
curl -s <a href="http://localhost:8080/snapraid/v1/array">http://localhost:8080/snapraid/v1/array</a> | jq
|
|
</pre>
|
|
</div>
|
|
<div class="manual-section-level-3">
|
|
<h3 id="sec5-2-2" class="manual-title-level-3">
|
|
/snapraid/v1/disks
|
|
</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>
|
|
curl -s <a href="http://localhost:8080/snapraid/v1/disks">http://localhost:8080/snapraid/v1/disks</a> | jq
|
|
</pre>
|
|
</div>
|
|
</div>
|
|
<div class="manual-section-level-2">
|
|
<h2 id="sec5-3" class="manual-title-level-2">
|
|
Configuration
|
|
</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">
|
|
<h3 id="sec5-3-1" class="manual-title-level-3">
|
|
/snapraid/v1/config
|
|
</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>
|
|
curl -X GET <a href="http://localhost:8080/snapraid/v1/config">http://localhost:8080/snapraid/v1/config</a> | jq
|
|
curl -X PATCH <a href="http://localhost:8080/snapraid/v1/config">http://localhost:8080/snapraid/v1/config</a> \
|
|
-d '{ "probe_interval_minutes": 10 }'
|
|
</pre>
|
|
</div>
|
|
</div>
|
|
<div class="manual-section-level-2">
|
|
<h2 id="sec5-4" class="manual-title-level-2">
|
|
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">
|
|
<h3 id="sec5-4-1" class="manual-title-level-3">
|
|
/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>
|
|
curl -s <a href="http://localhost:8080/snapraid/v1/activity">http://localhost:8080/snapraid/v1/activity</a> | jq
|
|
</pre>
|
|
</div>
|
|
<div class="manual-section-level-3">
|
|
<h3 id="sec5-4-2" class="manual-title-level-3">
|
|
/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>
|
|
curl -s <a href="http://localhost:8080/snapraid/v1/tasks">http://localhost:8080/snapraid/v1/tasks</a> | jq
|
|
</pre>
|
|
</div>
|
|
<div class="manual-section-level-3">
|
|
<h3 id="sec5-4-3" class="manual-title-level-3">
|
|
/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>
|
|
curl -X POST <a href="http://localhost:8080/snapraid/v1/stop">http://localhost:8080/snapraid/v1/stop</a>
|
|
</pre>
|
|
</div>
|
|
</div>
|
|
<div class="manual-section-level-2">
|
|
<h2 id="sec5-5" class="manual-title-level-2">
|
|
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">
|
|
<h3 id="sec5-5-1" class="manual-title-level-3">
|
|
/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>
|
|
curl -X GET <a href="http://localhost:8080/snapraid/v1/state">http://localhost:8080/snapraid/v1/state</a> | jq
|
|
</pre>
|
|
</div>
|
|
</div>
|
|
<div class="manual-section-level-2">
|
|
<h2 id="sec5-6" class="manual-title-level-2">
|
|
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">
|
|
<h3 id="sec5-6-1" class="manual-title-level-3">
|
|
/snapraid/v1/schedule
|
|
</h3>
|
|
<p>Queues a sequence of standard SnapRAID operations.
|
|
</p><p>Example:
|
|
</p><pre>
|
|
curl -X POST <a href="http://localhost:8080/snapraid/v1/schedule">http://localhost:8080/snapraid/v1/schedule</a> \
|
|
-d '{"tasks": [{"command": "diff"}, {"command": "report"}]}'
|
|
</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.
|
|
</div> <!-- description -->
|
|
</div> <!-- entry -->
|
|
<div class="manual-tag-entry">
|
|
<div class="manual-tag-name">
|
|
down
|
|
</div><div class="manual-tag-description">
|
|
Spins down array drives to save power.
|
|
</div> <!-- description -->
|
|
</div> <!-- entry -->
|
|
<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.
|
|
</div> <!-- description -->
|
|
</div> <!-- entry -->
|
|
<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.
|
|
</div> <!-- description -->
|
|
</div> <!-- entry -->
|
|
<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.
|
|
</div> <!-- description -->
|
|
</div> <!-- entry -->
|
|
<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.
|
|
</div> <!-- description -->
|
|
</div> <!-- entry -->
|
|
<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.
|
|
</div> <!-- description -->
|
|
</div> <!-- entry -->
|
|
<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.
|
|
</div> <!-- description -->
|
|
</div> <!-- entry -->
|
|
<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.
|
|
</div> <!-- description -->
|
|
</div> <!-- entry -->
|
|
<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.
|
|
</div> <!-- description -->
|
|
</div> <!-- entry -->
|
|
<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
|
|
array statistics.
|
|
</div> <!-- description -->
|
|
</div> <!-- entry -->
|
|
<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
|
|
have exceeded the 'spindown_idle_minutes' threshold.
|
|
</div> <!-- description -->
|
|
</div> <!-- entry -->
|
|
</div> <!-- list -->
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="manual-section-level-1">
|
|
<h1 id="sec6" class="manual-title-level-1">
|
|
Signals
|
|
</h1>
|
|
<p>SIGHUP
|
|
</p><p>Reloads the configuration file and resets the internal state.
|
|
It also reloads the Web UI. This is the recommended way to
|
|
apply changes to static parameters without restarting the
|
|
service.
|
|
</p><p>SIGTERM, SIGINT
|
|
</p><p>Initiates a graceful shutdown. If a task is currently
|
|
running, the daemon attempts to terminate the child process
|
|
before exiting.
|
|
</p><p>SIGQUIT
|
|
</p><p>Immediately terminates the process using the default signal
|
|
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>
|
|
<div class="manual-section-level-1">
|
|
<h1 id="sec8" class="manual-title-level-1">
|
|
Files
|
|
</h1>
|
|
<p>$PREFIX/etc/snapraidd.conf
|
|
</p><p>The primary configuration file location. The $PREFIX variable
|
|
represents the installation path chosen at build time (typically
|
|
via the `--prefix` argument to the configure script). Common
|
|
values include `/usr/local` or `/usr`. If this file does not
|
|
exist, the daemon falls back to `/etc/snapraidd.conf`.
|
|
</p><p>$PREFIX/share/snapraidd
|
|
</p><p>The primary system data directory. This is the first location
|
|
searched for the web dashboard ZIP file (e.g., commander.zip).
|
|
If not found here, the daemon falls back to `/usr/share/snapraidd`.
|
|
</p><div class="manual-option-list">
|
|
<div class="manual-option-entry">
|
|
<div class="manual-option-name">
|
|
/etc/snapraidd.conf
|
|
</div><div class="manual-option-description">
|
|
The secondary/system-wide configuration file location, used if
|
|
the prefix-specific file is missing.
|
|
</div> <!-- description -->
|
|
</div> <!-- entry -->
|
|
</div> <!-- list -->
|
|
<div class="manual-option-list">
|
|
<div class="manual-option-entry">
|
|
<div class="manual-option-name">
|
|
/usr/share/snapraidd
|
|
</div><div class="manual-option-description">
|
|
The secondary/system-wide data directory, used as a fallback for
|
|
web assets.
|
|
</div> <!-- description -->
|
|
</div> <!-- entry -->
|
|
</div> <!-- list -->
|
|
<div class="manual-option-list">
|
|
<div class="manual-option-entry">
|
|
<div class="manual-option-name">
|
|
/run/snapraidd.pid
|
|
</div><div class="manual-option-description">
|
|
Default PID file location.
|
|
</div> <!-- description -->
|
|
</div> <!-- entry -->
|
|
</div> <!-- list -->
|
|
<div class="manual-option-list">
|
|
<div class="manual-option-entry">
|
|
<div class="manual-option-name">
|
|
/var/log/snapraid
|
|
</div><div class="manual-option-description">
|
|
Default directory for SnapRAID command execution logs. This
|
|
directory contains the output of the SnapRAID binary itself,
|
|
rather than the daemon's service logs.
|
|
</div> <!-- description -->
|
|
</div> <!-- entry -->
|
|
</div> <!-- list -->
|
|
</div>
|
|
|
|
|
|
</div>
|
|
</main>
|
|
</div>
|
|
|
|
<!-- Footer -->
|
|
<footer>
|
|
<div class="container footer-content">
|
|
<div class="footer-col">
|
|
<h3>SnapRAID</h3>
|
|
<p>Copyright © 2026 Andrea Mazzoleni</p>
|
|
<p class="license">Distributed under GPL v3 License</p>
|
|
</div>
|
|
<div class="footer-col">
|
|
<h4>Community</h4>
|
|
<ul>
|
|
<li><a href="https://www.reddit.com/r/Snapraid/">Reddit r/snapraid</a></li>
|
|
<li><a href="https://sourceforge.net/p/snapraid/discussion/1677233/">SourceForge Forum</a></li>
|
|
<li><a href="https://github.com/amadvance/snapraid/">GitHub</a></li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
</footer>
|
|
</body>
|
|
</html>
|
|
|
|
|