Auto update

This commit is contained in:
Andrea Mazzoleni 2026-02-14 09:40:46 +01:00
parent 8c04cad1f0
commit d7cfdfca07
2 changed files with 5013 additions and 0 deletions

958
beta/manual-daemon.html Normal file
View 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]
&nbsp;&nbsp;&nbsp;&nbsp;[-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 &amp; 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 &amp; 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 &amp; 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 &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.
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> \
&nbsp;&nbsp;&nbsp;&nbsp;-H "Content-Type: application/json" \
&nbsp;&nbsp;&nbsp;&nbsp;-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 &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">
<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> \
&nbsp;&nbsp;&nbsp;&nbsp;-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> \
&nbsp;&nbsp;&nbsp;&nbsp;-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&nbsp;&nbsp;&nbsp;&nbsp;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 &copy; 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

File diff suppressed because it is too large Load diff