From 5fef915ca0b53b927b08b598f1d6845a7e0ffb57 Mon Sep 17 00:00:00 2001 From: Andrea Mazzoleni Date: Thu, 19 Feb 2026 17:18:37 +0100 Subject: [PATCH] Auto update --- beta/manual-daemon.html | 620 ++++++++++++++++++++++++++++------------ 1 file changed, 431 insertions(+), 189 deletions(-) diff --git a/beta/manual-daemon.html b/beta/manual-daemon.html index 2538c392..9d3de2dd 100644 --- a/beta/manual-daemon.html +++ b/beta/manual-daemon.html @@ -127,13 +127,13 @@ Options -c, --conf CONFIG
Specifies the path to the configuration file. Default: -`$PREFIX/etc/snapraidd.conf` and `/etc/snapraidd.conf` if +$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` +path chosen at build time (typically via the --prefix argument to the configure script). -
- - + + +
@@ -141,19 +141,19 @@ argument to the configure script).
Runs the process in the foreground. This prevents the daemon from detaching from the terminal (daemonizing). -
-
-
+ + +
-p, --pidfile FILE
Overrides the default location for the PID file. Default: -`/run/snapraidd.pid`. -
-
-
+/run/snapraidd.pid. + + +
@@ -167,36 +167,36 @@ 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. -
-
-
+ + +
-v, --verbose
Verbose logging including all HTTP requests. -
-
-
+ + +
-H, --help
Prints a short help screen. -
-
-
+ + +
-V, --version
Prints the program version. -
-
-
+ + +

@@ -205,7 +205,7 @@ Configuration

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 +path chosen at build time (typically via the --prefix argument to the configure script).

This file governs the behavior of the automation engine, network accessibility, safety interlocks, and hardware monitoring parameters. @@ -221,9 +221,9 @@ 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. -

- - + + +
@@ -235,75 +235,212 @@ 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. -
-
-
+ + +

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. -

For complete technical documentation, please refer to the -`snapraidd.conf.example` file. +

For a comprehensive view of how these settings are applied in a +real-world environment, refer to the snapraidd.conf.example file +typically located in the documentation directory of the installation.

Network & REST API

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. +visible from the REST API. They requires a manual edit of the +configuration file and a configuration reload (SIGHUP) to apply.

net_enabled

-

Master toggle for the HTTP interface. -Set to 1 to enable the REST API, otherwise, the daemon operates in -local-only mode. +

Acts as the master toggle for the network interface. When set to 1, +the daemon enables the REST API and prepares to serve the web dashboard. +If set to 0 or left blank, the daemon operates in a secure, local-only +mode, and no network ports are opened.

net_port

-

Defines the IP address and port the daemon binds to (e.g., `127.0.0.1:8080`). -Supports IPv4, IPv6, and multiple ports. +

Defines the specific IP address and port(s) to which the daemon binds. +The format follows [IP_ADDRESS:]PORT[s]. +

+
+
+IPv4IPv6 +
+Bind to specific local addresses (e.g., 127.0.0.1:8080 or +[::1]:8080). +
+
+
+
+Wildcard +
+Providing only a port (e.g., 8080) binds to all available +IPv4 interfaces (0.0.0.0). +
+
+
+
+MultiplePorts +
+Multiple listeners can be configured by providing a +comma-separated list. +
+
+
+

If left unset, the daemon defaults to 127.0.0.1:8080. Modification +requires a configuration reload and is restricted from API access.

net_acl

-

Restricts API access to specific client IPs using a comma-separated -list of allow (+) or deny (-) rules. +

Restricts API and dashboard access to specific client IP addresses or +subnets using a comma-separated Access Control List (ACL). +

The syntax uses + to allow and - to deny, supporting CIDR notation +(e.g., /24). If any rules are defined, the daemon adopts a "deny by default" +stance. The rules are processed sequentially, and the last matching rule +determines the outcome. +If unset, it defaults to +127.0.0.1.

net_security_headers

-

When enabled (1), injects security headers like CSP and X-Frame-Options -to harden the API against browser-based attacks. +

When enabled (1), the daemon injects several browser-level security +hardening headers into every HTTP response. These include +Content-Security-Policy (restricting resource loading), +X-Frame-Options (preventing clickjacking via iframes), +X-Content-Type-Options (disabling MIME-sniffing), +and Referrer-Policy. +

This should only be disabled (0) if the daemon is behind a reverse +proxy (like Nginx or Traefik) that is already configured to handle +these security headers.

net_allowed_origin

-

Configures CORS. Use `self` for standard setups, `none` to block -browser access, or a specific URL for custom dashboards. -

+

Configures Cross-Origin Resource Sharing (CORS) to determine which web +applications can interact with the API. +

+
+
+self +
+(Default/Recommended) Dynamically reflects the 'Host' header +of the request, allowing the built-in UI to work across various hostnames or IPs. +
+
+
+
+none +
+Omits CORS headers entirely, blocking browser-based access from any origin. +
+
+
+
+URL +
+Restricts access to a specific origin (e.g., http://192.168.1.50:3000). +
+
+
+

net_config_full_access

-

Determines if restricted parameters (like scripts and log paths) can -be modified via the REST API. Defaults to 0 (Read-only). -

+

A security flag that determines whether sensitive configuration parameters +can be modified via the REST API. +

By default (0), sensitive options such as script paths, log directories, +and notification users are read-only to prevent unauthorized privilege +escalation or system modification. +

By default (0), security-sensitive options are strictly read-only to +prevent unauthorized system modifications or privilege escalation +through the web interface. +

When set to 1, the following configuration options become accessible +for modification via PATCH requests: +

+
+
+script_run_as_user +
+The account used for executing pre/post scripts. +
+
+
+
+script_pre_run +
+The absolute path to the pre-execution script. +
+
+
+
+script_post_run +
+The absolute path to the post-execution script. +
+
+
+
+log_directory +
+The persistent storage path for command outputs. +
+
+
+
+log_retention_days +
+The duration for which log files are kept. +
+
+
+
+notify_run_as_user +
+The account used for notification commands. +
+
+
+
+notify_heartbeat +
+The command used for health monitoring pings. +
+
+
+
+notify_result +
+The command used for sending task reports. +
+
+
+
+notify_result_level +
+The severity threshold for sending notifications. +
+
+
+

net_web_root

-

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. +

Specifies the source of the web dashboard assets. The daemon supports +both a standard directory and a single compressed ZIP file for asset +delivery.

The daemon resolves the location of the assets based on the following rules:

@@ -311,14 +448,11 @@ rules:
ZIP_Filename
-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/. -
-
+If a simple filename is provided (e.g., commander.zip), +the daemon searches for it in $PREFIX/share/snapraidd/ or +/usr/share/snapraidd/. +
+
ZIP_Path @@ -327,17 +461,17 @@ 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. -
-
+ +
Directories
If the target is a directory rather than a ZIP archive, the path must be absolute (e.g., /var/www/snapraid-ui/). -
-
- + + +

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 @@ -356,153 +490,260 @@ net_config_full_access option is enabled.

maintenance_schedule

-

Defines when the automated sync, scrub, and report sequence occurs -(e.g., `daily 02:00` or `weekly Mon 03:00`). +

Defines the timing for the automated maintenance sequence, which +consists of a sync, followed by a scrub, and concluding with a report. +If this option is unset, automated maintenance is disabled. +

The format must be either "daily HH:MM" or "weekly [Day] HH:MM". +Hours are specified in a 24-hour format (00-23), and days are +represented by their short names (Mon, Tue, Wed, Thu, Fri, Sat, Sun).

sync_threshold_deletes

-

Maximum number of deleted/missing files allowed before a scheduled -sync is aborted to prevent accidental parity loss. +

Sets the maximum number of deleted or missing files allowed before a +sync operation is automatically aborted. This serves as a safety +mechanism to prevent accidental parity loss due to unintended mass +deletions. This threshold is enforced during scheduled runs and +maintenance API calls, but is bypassed for standalone sync API +requests to allow for manual overrides. +Set to 0 to disable this check.

sync_threshold_updates

-

Maximum number of modified files allowed before a scheduled sync is -suspended. +

Sets the maximum number of modified or updated files allowed before a +sync operation is aborted. Similar to the delete threshold, this +prevents the parity from being overwritten if an unexpected number +of files have changed. This is enforced during scheduled runs but +bypassed for manual standalone sync requests. +Set to 0 to disable this check.

sync_prehash

-

Enables the SnapRAID prehash option to verify files before updating -parity, protecting against faulty RAM or cables. +

If set to 1, the sync command is executed with the --prehash option. +This calculates hashes before moving data to verify integrity, +helping to prevent silent errors caused by faulty memory. +If missing or set to 0, no pre-hashing is performed.

sync_force_zero

-

Permits synchronization even if protected files have unexpectedly -shrunk to zero bytes. +

If set to 1, the daemon allows a sync to proceed even if it detects +files that have shrunk to zero size since the last run. +By default (missing or 0), the daemon will halt the sync to protect +against potential data corruption or accidental file clearing.

scrub_percentage

-

The percentage of the array verified during the scrub phase of -automated maintenance. +

Determines the portion of the array to be verified during the scrub +phase following a successful sync. The value can be an integer or a +decimal (e.g., 0.7 for 0.7%). +If missing or set to 0, the scrub phase is skipped entirely.

scrub_older_than

-

Restricts scrubbing to blocks that have not been verified within the -specified number of days. -

-
-

-probe_interval_minutes -

-

Interval for background health checks. SMART attributes are only -queried if disks are already active to avoid waking them. -

-
-

-spindown_idle_minutes -

-

Inactivity threshold (in minutes) after which the daemon will issue a -spindown command to the disks. -

-
-

-script_run_as_user -

-

The system user account utilized for the execution of pre- and -post-run hooks. -

-
-

-script_pre_run/script_post_run -

-

Absolute paths to executable shell scripts triggered before or after -SnapRAID activity. +

Specifies that only blocks older than the defined number of days +should be scrubbed. This allows the daemon to focus verification on +older data while skipping recently synced blocks. +If missing or set to 0, no age-based filtering is applied.

+Disk Monitoring & Power +

+

The following settings manage how the daemon interacts with physical +hardware to monitor disk health and optimize energy consumption +

+

+probe_interval_minutes +

+

Controls the frequency at which the daemon checks disk SMART attributes. +To prevent unnecessary disk wear, the daemon only performs this check +if the disks are already spinning. +If set to 0 or left blank, SMART monitoring is disabled. +

+
+

+spindown_idle_minutes +

+

Manages power consumption by automatically spinning down disks after +the specified duration of inactivity. +

Unlike the internal task logic of the daemon, this timer monitors the +global activity of the disks across the entire operating system. +A disk will only be spun down if it has remained completely idle for +the specified period. If any other application, service, or system +process accesses the disk, the idle timer is reset. The daemon will +not force a spindown if the disk is currently in use by the system. +

If this option is unset, the daemon will not manage disk power states, +relying instead on the OS or hardware controllers. +

+
+

+script_pre_run/script_post_run +

+

Defines absolute paths to custom scripts to be executed immediately before +or after the sync, scrub, check, or fix commands. These scripts allow +for custom logic such as mounting drives or sending custom alerts. +

security Requirements: +- The path must be absolute (starting with /). +- The script must not be world-writable (recommended permissions: 700 or 755). +- The script owner must match the daemon user or be root. +- The script must contain a valid shebang (e.g., #!/bin/sh). +

+
+

+script_run_as_user +

+

Specifies the user account used to execute the pre-run and post-run +scripts. If this is missing or blank, scripts are executed with the +same privileges as the daemon process. +

+
+
+

Logging & Notifications

These settings control the logging and notification operations performed by the SnapRAID daemon.

-

+

log_directory

-

Path where individual SnapRAID command outputs are stored as `.log` -files. Default: `/var/log/snapraid`. +

The log_directory defines where the output of individual SnapRAID +commands is stored. If left unset, the daemon defaults to +/var/log/snapraid. +

Setting this option to an empty value (log_directory = ) will +explicitly disable the saving of command output to persistent files. +

IMPORTANT: While it is possible to leave this empty to avoid saving files, +these logs are used by the daemon to reconstruct the past state of the +array (e.g., tracking the last successful sync or scrub). If no log +directory is provided, the daemon will lose its "memory" of previous +task results every time it is restarted.

-

+

log_retention_days

-

Number of days to keep log files before they are purged. +

To prevent your storage from filling up, log_retention_days sets the +age at which old command logs are deleted. Logs are kept indefinitely +if this is set to 0 or left unset.

-

+

notify_syslog_enabled

-

Enables logging of daemon activity to the OS system log (syslog/journald). +

When set to 1, daemon activity is sent to the operating system system +log (syslog/journald). While lifecycle events like starting and +stopping are always captured, task-related messages are filtered by +notify_syslog_level.

-

+

notify_syslog_level

Sets the minimum severity for syslog task entries. -Possible values: info, warning, error, critical. Default: error. +Possible values are info, warning, error, and critical. +The default is error.

-

+

notify_heartbeat

-

A shell command (e.g., `curl`) executed only upon task success, ideal -for "dead man's switch" monitoring. +

Defines a command to run ONLY if the maintenance task was successful +(it is not triggered by other tasks, such as heal or undelete). +This is ideal for external monitoring services like "Dead Man's Snitch" +or Healthchecks.io. If this ping stops, it indicates the server is down +or the task is failing.

-

+

notify_result

-

A shell command triggered after task completion; it receives the task -report via stdin. +

Specifies a command triggered after every high-level task (maintenance, +heal, or undelete). The command is only executed if the task's result +matches the notify_result_level. The daemon pipes a structured, +plain-text task report directly into the command's stdin. +

The daemon automatically chooses a wide (80-col) or narrow (32-col) +report based on the command and arguments used (e.g., presence of "mail" +or "smtps"). Users can manually override this by adding --wide or +--narrow to the command string. These tags are stripped before execution. +

Before execution, the daemon scans the command string and replaces the +following tokens with dynamic values corresponding to the current +task's state and results: +

+
+
+%s +
+Subject string (e.g., "[ERROR] SnapRAID Maintenance"). +
+
+
+
+%l +
+Task level (critical, error, warning, info, debug). +
+
+
+
+%n +
+ntfy priority (urgent, high, default, low, min). +
+
+
+
+%t +
+ntfy tag (skull, warning, default, -1, +1, heavy_check_mark). +
+
+
+

If the command contains --mail-from or --mail-rcpt, the daemon +automatically prepends standard email headers (From, To, Subject) +followed by a blank line to the report text. This ensures +compatibility with curl's SMTP engine. +

When using curl for SMTP, it is recommended to use the --netrc flag. +This allows curl to read credentials from a local file rather than +exposing passwords in the command line or process list. +

File format (~/.netrc): +

+machine smtp.gmail.com
+login your_email@gmail.com
+password your-16-char-app-password
+
+

If notify_run_as_user is configured, ensure that user has a valid +home directory containing a .netrc file with 600 permissions for SMTP +authentication. Failure to do so may result in authentication errors +(e.g., curl error 55).

-

+

notify_result_level

-

Controls the filter for `notify_result`. The notification is sent only +

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. +Valid values are info (always send), warning, error, and critical. +The default is error.

-

-notify_email_recipient -

-

Local system email address for receiving health reports. -

-
-

-notify_email_level -

-

Sets the minimum severity for email reports. -Possible values: info, warning, error, critical. Default: error. -

-
-

+

notify_differences

-

If enabled, includes a detailed list of file changes (added/removed/modified) -in the notification reports. +

If set to 1, the daemon logs a detailed list of file changes discovered +before a sync begins. If set to 0 or missing, no difference report is +generated.

@@ -513,8 +754,9 @@ Rest API

The SnapRAID Daemon provides a comprehensive RESTful JSON interface for monitoring and controlling the parity array.

For complete technical documentation, including request schemas and -specific error codes, please refer to the snapraidd.yaml OpenAPI -specification file. +specific error codes, please refer to the snapraidd.yaml OpenAPI +specification file typically located in the documentation directory of +the installation.

Maintenance & Recovery @@ -523,7 +765,7 @@ Maintenance & Recovery 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 +They typically end with a report command that generates a notification with a full report of the result of the operation.

@@ -760,96 +1002,96 @@ curl -X POST http://localho up

Spins up all drives in the array. -
-

+ +
down
Spins down array drives to save power. -
-
+ +
probe
Verifies the power status of all configured disks and gathers SMART information for those already spinning. -
-
+ +
smart
Collects and parses SMART attributes from all drives to assess physical health. -
-
+ +
diff
Scans the array to identify changed, added, or deleted files since the last sync. -
-
+ +
status
Provides a summary of the array state, including parity levels and data distribution. -
-
+ +
sync
Updates the parity information to match the current state of the data disks. -
-
+ +
scrub
Verifies the integrity of the data and parity by recalculating checksums for a portion of the array. -
-
+ +
check
Performs a full verification of the array integrity without modifying any data. -
-
+ +
fix
Attempts to recover deleted files or repair corrupted data using the parity information. -
-
+ +
report
Generates a comprehensive summary of the last operations and array statistics. -
-
+ +
down_idle
Executes a conditional spindown operation of the disks that have exceeded the 'spindown_idle_minutes' threshold. -
-
- + + + @@ -874,19 +1116,19 @@ or misbehaving daemon. No cleanup or graceful shutdown is performed.

-

+

Files

$PREFIX/etc/snapraidd.conf

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`. +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.

$PREFIX/share/snapraidd

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`. +If not found here, the daemon falls back to /usr/share/snapraidd.

@@ -894,9 +1136,9 @@ If not found here, the daemon falls back to `/usr/share/snapraidd`.
The secondary/system-wide configuration file location, used if the prefix-specific file is missing. -
-
-
+
+ +
@@ -904,18 +1146,18 @@ the prefix-specific file is missing.
The secondary/system-wide data directory, used as a fallback for web assets. -
-
-
+ + +
/run/snapraidd.pid
Default PID file location. -
-
-
+ + +
@@ -924,9 +1166,9 @@ Default PID file location. Default directory for SnapRAID command execution logs. This directory contains the output of the SnapRAID binary itself, rather than the daemon's service logs. -
-
-
+ + +