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.
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. +
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. +
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. +
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. +
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.
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.
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.
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.
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.
Configures Cross-Origin Resource Sharing (CORS) to determine which web @@ -493,7 +534,7 @@ applications can interact with the API.
A security flag that determines whether sensitive configuration parameters @@ -527,37 +568,16 @@ for modification via PATCH requests:
Specifies the source of the web dashboard assets. The daemon supports @@ -642,7 +662,7 @@ for development environments only.
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.
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).
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. +
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. +
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.
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.
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.
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.
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. -
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. -
The following settings manage how the daemon interacts with physical hardware to monitor disk health and optimize energy consumption
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.
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.
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. -
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-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. +
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.
These settings control the logging and notification operations performed -by the SnapRAID Daemon. +
These settings control the notification operations performed by the +daemon.
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. -
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. -
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.
Sets the minimum severity for syslog task entries. @@ -829,7 +855,7 @@ Possible values are info, warning, error, and criticalerror.
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.
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).
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.
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. +
If set to 1, the daemon logs a detailed list of file changes discovered @@ -921,13 +960,13 @@ generated.
The following examples demonstrate common notification and heartbeat configurations
To monitor that automated maintenance is running successfully, use a service
@@ -940,7 +979,7 @@ notify_heartbeat = curl -f --max-time 30 --retry 3
- 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
+
Push Notifications (ntfy.sh)
A traditional approach using the standard Linux mail utility. This is @@ -962,7 +1001,7 @@ notify_result = mail -s "%s" your_user@localhost
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://locIt is implemented with the sequence of commands: probe, down_idle.
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 ++