mirror of
https://github.com/amadvance/snapraid.git
synced 2026-10-26 19:01:57 -04:00
Auto update
This commit is contained in:
parent
8c04cad1f0
commit
d7cfdfca07
2 changed files with 5013 additions and 0 deletions
958
beta/manual-daemon.html
Normal file
958
beta/manual-daemon.html
Normal file
|
|
@ -0,0 +1,958 @@
|
|||
<!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>Component</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>
|
||||
|
||||
|
||||
4055
beta/manual-log.html
Normal file
4055
beta/manual-log.html
Normal file
File diff suppressed because it is too large
Load diff
Loading…
Add table
Add a link
Reference in a new issue