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. -
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.
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.
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.
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]. +
+If left unset, the daemon defaults to 127.0.0.1:8080. Modification +requires a configuration reload and is restricted from API access.
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.
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.
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. +
+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: +
+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:
+If a simple filename is provided (e.g., commander.zip), +the daemon searches for it in $PREFIX/share/snapraidd/ or +/usr/share/snapraidd/. +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.
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).
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.
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.
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.
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.
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.
Restricts scrubbing to blocks that have not been verified within the -specified number of days. -
Interval for background health checks. SMART attributes are only -queried if disks are already active to avoid waking them. -
Inactivity threshold (in minutes) after which the daemon will issue a -spindown command to the disks. -
The system user account utilized for the execution of pre- and -post-run hooks. -
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.
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. +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. +
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. +
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). +
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. +
These settings control the logging and notification operations performed by the SnapRAID daemon.
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.
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.
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.
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.
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.
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: +
+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).
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.
Local system email address for receiving health reports. -
Sets the minimum severity for email reports. -Possible values: info, warning, error, critical. Default: error. -
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.
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.
$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.