From 658722cfd3973ecceecbb495ef0a5005b5fc2ee7 Mon Sep 17 00:00:00 2001 From: Andrea Mazzoleni Date: Sun, 8 Mar 2026 17:40:50 +0100 Subject: [PATCH] Auto update --- beta/manual-daemon.html | 312 ++++++++++++++++++++++++---------------- 1 file changed, 185 insertions(+), 127 deletions(-) diff --git a/beta/manual-daemon.html b/beta/manual-daemon.html index 4047ea11..9f9715e4 100644 --- a/beta/manual-daemon.html +++ b/beta/manual-daemon.html @@ -102,7 +102,7 @@ snapraidd [-V, --version] [-H, --help] Description

SnapRAID Daemon is a specialized companion service designed to move SnapRAID -from a manual, command-line interface (CLI) workflow to an 'always-on' +from a manual, command-line interface (CLI) workflow to an always-on background service.

Under the hood, the daemon uses the same SnapRAID CLI binary, providing the same level of reliability. @@ -391,13 +391,54 @@ real-world environment, refer to the comments in the snapraidd.conf file installed.

+System +

+

These settings control the core execution environment and the +underlying daemon. +These options are not visible or modifiable via the REST API. +They require a manual edit of the configuration file and a +configuration reload (SIGHUP) or daemon restart to apply. +

+

+sys_engine +

+

Sets the absolute path to the SnapRAID executable. If omitted, +the daemon searches /usr/bin and /usr/local/bin on Linux, /usr/bin +in Wine, and the daemon's base directory on Windows. +

+
+

+sys_log_directory +

+

Defines where the output of individual SnapRAID commands is stored. +If left unset, the daemon defaults to /var/log/snapraid in Linux +and /log in the installation directory in Windows. +

Setting this option to an empty value (sys_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. +

+
+

+sys_log_retention_days +

+

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

+
+
+

Network & REST API

These settings control the network interface. These options are not visible from the REST API. They require a manual edit of the configuration file and a configuration reload (SIGHUP) to apply.

-

+

net_enabled

Acts as the master toggle for the network interface. When set to 1, @@ -406,7 +447,7 @@ 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 specific IP address and port(s) to which the daemon binds. @@ -449,7 +490,7 @@ net_port=127.0.0.1:7627,8080 - Listen on multiple ports on localhost.

-

+

net_acl

Restricts API and dashboard access to specific client IP addresses or @@ -469,7 +510,7 @@ net_acl=+192.168.1.0/24 - Allow local subnet only.

-

+

net_security_headers

When enabled (1), the daemon injects several browser-level security @@ -483,7 +524,7 @@ proxy (like Nginx or Traefik) that is already configured to handle these security headers.

-

+

net_allowed_origin

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

self
-(Default/Recommended) Dynamically reflects the 'Host' header +(Default/Recommended) Dynamically reflects the Host header of the request, allowing the built-in UI to work across various hostnames or IPs.
@@ -514,7 +555,7 @@ Restricts access to a specific origin (e.g., http://192.168.1.50:3000).
-

+

net_config_full_access

A security flag that determines whether sensitive configuration parameters @@ -527,37 +568,16 @@ for modification via PATCH requests:

-script_run_as_user +hook_run_as_user
-The account used for executing pre/post scripts. +The account used for executing hook_script.
-script_pre_run +hook_script
-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. +The absolute path to the hook script.
@@ -591,7 +611,7 @@ The severity threshold for sending notifications.
-

+

net_web_root

Specifies the source of the web dashboard assets. The daemon supports @@ -642,7 +662,7 @@ for development environments only.

-

+

Automation & Maintenance

These settings control the automation and maintenance tasks run by @@ -650,7 +670,7 @@ the SnapRAID Daemon.

For security reasons, some of them can be set via the REST API only if the net_config_full_access option is enabled.

-

+

maintenance_schedule

Defines the timing for the automated maintenance sequence, which @@ -661,7 +681,25 @@ 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).

-

+

+scrub_percentage +

+

Determines the portion of the array verified after a successful sync. +You may use decimal points to specify fractions of a percent +(e.g., 0.7 to verify 0.7% of the array). +If missing or set to 0, the scrub phase is skipped entirely. +

+
+

+scrub_older_than +

+

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

+
+

sync_threshold_deletes

Sets the maximum number of deleted or missing files allowed before a @@ -671,7 +709,7 @@ deletions. This safety check is enforced during automated maintenance schedules and tasks initiated through the Web UI.

-

+

sync_threshold_updates

Sets the maximum number of modified or updated files allowed before a @@ -681,7 +719,7 @@ of files have changed. This safety check is enforced during automated maintenance schedules and tasks initiated through the Web UI.

-

+

sync_prehash

If set to 1, the sync command is executed with the --prehash option. @@ -693,7 +731,7 @@ under critical system stress. If missing or set to 0, no pre-hashing is performed.

-

+

sync_force_zero

If set to 1, the daemon allows a sync to proceed even if it detects @@ -704,33 +742,15 @@ This setting is particularly useful for detecting and acknowledging instances where files, accessed during a system crash, have been truncated to zero bytes by the filesystem.

-
-

-scrub_percentage -

-

Determines the portion of the array verified after a successful sync. -You may use decimal points to specify fractions of a percent -(e.g., 0.7 to verify 0.7% of the array). -If missing or set to 0, the scrub phase is skipped entirely. -

-
-

-scrub_older_than -

-

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. @@ -739,7 +759,7 @@ 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 @@ -752,67 +772,73 @@ service, or system process accesses the disk, the idle timer is reset. relying instead on the OS or hardware controllers.

-

-script_pre_run/script_post_run +

+hook_script

-

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

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

Defines an absolute path to an executable script to be triggered by +daemon events. +

The script is executed with a single positional argument that +represents the lifecycle stage of the task currently being processed +by the daemon: +

+
+
+task-begin +
+Triggered immediately before the daemon begins a +scheduled sequence of actions that access the array +(e.g., sync, scrub, or maintenance).
+
+
+
+task-end +
+Triggered after the entire sequence of actions has +concluded successfully. +
+
+
+

task-error: Triggered if the task sequence is aborted, interrupted, +

or encounters an operational failure. +

Note that 'task-end' reflects only whether the task finished its +execution cycle. It does not necessarily reflect hardware or data +integrity. For example, a sync command may return 'task-end' even if +the array is technically in a corrupt state, provided the sync process +itself finished without crashing. +

Future versions of the daemon will introduce new event types that may +not relate to array access or follow the task- naming convention. +It is strongly recommended to implement a default handler to ignore +unrecognized events +

SECURITY REQUIREMENTS: +* The path MUST be absolute (starting with /). +* The script file MUST NOT be world-writable (recommended: 700 or 755). +* The script owner MUST match the user running the daemon or be root. +* The script MUST contain a valid shebang (e.g., #!/bin/sh). +

This remains inactive if no path is defined. +

-

-script_run_as_user +

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

Specifies the user account used to execute the hook_script. +If this is missing or blank, the script is executed with the same privileges as the daemon process. +

On Linux, "nobody" is the standard choice for maximum isolation. +On Windows, "LocalService" is the preferred choice as it provides +minimal local access while maintaining network capabilities. +Alternatively, "NetworkService" can be used if the script specifically +requires the computer's network identity to access remote resources.

-

-Logging & Notifications +

+Notifications

-

These settings control the logging and notification operations performed -by the SnapRAID Daemon. +

These settings control the notification operations performed by the +daemon.

-

-log_directory -

-

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 -

-

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

When set to 1, daemon activity is sent to the operating system system @@ -821,7 +847,7 @@ stopping are always captured, task-related messages are filtered by notify_syslog_level.

-

+

notify_syslog_level

Sets the minimum severity for syslog task entries. @@ -829,7 +855,7 @@ Possible values are info, warning, error, and criticalerror.

-

+

notify_heartbeat

Defines a command to run ONLY if the maintenance task was successful @@ -839,7 +865,7 @@ or Healthchecks.io. If this ping stops, it indicates the server is down or the task is failing.

-

+

notify_result

Specifies a command triggered after every report task generated by @@ -903,7 +929,7 @@ 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 @@ -912,7 +938,20 @@ Valid values are info (always send), warning, error, and error.

-

+

+notify_run_as_user +

+

The user account used for notify_heartbeat, notify_result and mail +notifications. If missing or left blank, the task runs with the +daemon's current privileges. +

On Linux, "nobody" is the standard choice for maximum isolation. +On Windows, "LocalService" is the preferred choice as it provides +minimal local access while maintaining network capabilities. +Alternatively, "NetworkService" can be used if the script specifically +requires the computer's network identity to access remote resources. +

+
+

notify_differences

If set to 1, the daemon logs a detailed list of file changes discovered @@ -921,13 +960,13 @@ generated.

-

+

Notification Examples

The following examples demonstrate common notification and heartbeat configurations

-

+

External Heartbeat Monitoring (Healthchecks.io)

To monitor that automated maintenance is running successfully, use a service @@ -940,7 +979,7 @@ notify_heartbeat = curl -f --max-time 30 --retry 3 -

+

Push Notifications (ntfy.sh)

This uses curl to send the report as a POST request to a push notification service. @@ -951,7 +990,7 @@ notify_result = curl --narrow -f --max-time 30 --retry 3 -H "Title: %s" -H "Prio

-

+

Local System Mail (mail)

A traditional approach using the standard Linux mail utility. This is @@ -962,7 +1001,7 @@ notify_result = mail -s "%s" your_user@localhost

-

+

Direct Delivery (SMTP-over-SSL)

This leverages curl's built-in SMTP engine for direct delivery to an @@ -1003,10 +1042,10 @@ notification containing the operation's results. 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_updates' safety checks defined in the configuration. +This task is subject to the sync_threshold_deletes and +sync_threshold_updates 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. +by the scrub_percentage and scrub_older_than settings.

Example: 

 curl -X POST http://localhost:7627/snapraid/v1/maintenance
@@ -1054,7 +1093,7 @@ and report.
 
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
+spindown_idle_minutes threshold. In this case, no report is
 generated.
 
Example:
 
@@ -1062,6 +1101,25 @@ curl -X POST http://loc
 

 
It is implemented with the sequence of commands: probe, down_idle.
+
+

+/snapraid/v1/refresh: +

+

Forces the daemon to re-synchronize its internal state with the +content file. This is intended for use after manual interventions +performed outside the daemon interface (e.g., replacing +a failed disk, fixing UUID mismatches, or manually updating configuration). +

The operation executes a read task to load the current content file +data, followed by a report task to evaluate and broadcast the +resulting array health. +

This is specifically useful for clearing FAILING or PREFAIL modes +once the underlying hardware or configuration issues have been +resolved manually. +

Example: +

+curl -X POST http://localhost:7627/snapraid/v1/refresh
+
+

@@ -1316,7 +1374,7 @@ array statistics. down_idle

Executes a conditional spindown operation of the disks that -have exceeded the 'spindown_idle_minutes' threshold. +have exceeded the spindown_idle_minutes threshold.