Synopsis
snapraidd [-c, --conf CONFIG] [-C, --engine-conf FILE] [-i, --instance NAME] [-f, --foreground] [-p, --pidfile FILE] [-N, --no-cache] [-v, --verbose]
snapraidd [-i, --instance NAME] [--service-install] [--service-remove] [--service-start-all] [--service-stop-all] [--service-remove-all] [--service-list]
snapraidd [-g, --gen-auth USERNAME:PASSWORD]
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 background service.
Under the hood, the daemon uses the same SnapRAID CLI binary, providing the same level of reliability.
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.
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.
Options
The SnapRAID Daemon provides the following options:
Getting Started
The daemon acts as a management layer for the SnapRAID CLI. Therefore, SnapRAID CLI must be installed and fully configured before starting the service.
Because the daemon performs direct hardware-level telemetry probes (such as reading SMART attributes and managing disk power states), it requires elevated privileges to function correctly. On Linux systems, the daemon must be run as the root user. On Windows, it must be executed as a service with equivalent system access rights.
It is important to note that the daemon never directly reads the SnapRAID CLI configuration file snapraid.conf. Instead, it relies entirely on the output and logs generated by the SnapRAID binary.
By processing these logs, the daemon identifies the data, parity, and extra disks and establishes the current state of the array.
During the installation process of the daemon, a default configuration file is provisioned to enable the REST API and the Web UI. For users installing via binary packages, this file is typically placed at /etc/snapraidd.conf. If you are installing from source, it is recommended to run ./configure --prefix=/usr --sysconfdir=/etc during the build process to ensure the program is installed in the standard /usr directory, and the configuration is placed in the standard /etc directory.
Using this default configuration file, the UI is accessible locally via a web browser at the following address:
The default port, 7627, was chosen as a mnemonic, representing the word SNAP as typed on a standard telephone keypad.
At startup, the daemon parses historical logs from /var/log/snapraid to reconstruct the current state of the array. These logs are generated and saved by the daemon itself during the execution of SnapRAID CLI commands. Consequently, on the very first run, this directory will be empty.
In this initial scenario, the daemon automatically triggers a SnapRAID read command. This allows SnapRAID to process its internal content files and provide the daemon with the necessary metadata to establish the array's baseline state.
Once the service is running, you should review /etc/snapraidd.conf or use the Settings panel in the UI to tailor the behavior to your environment.
Typical post-installation steps include:
- Defining a maintenance_schedule for automated sync and scrub operations.
- Setting spindown_idle_minutes to optimize energy usage for disks not in active use.
- Configuring the notify_result system to receive alerts regarding array health and task outcomes.
To make manual changes to runtime-reloadable options in the /etc/snapraidd.conf file effective, send a SIGHUP signal to the running process. Changes to sys_* options require a daemon restart.
Example:
sudo killall -HUP snapraidd
Unlike manual file edits, changes made through the UI are applied to the running process and saved to the configuration file pressing the Save button.
By default, the daemon binds to the loopback interface, meaning the UI is accessible only from the local machine and not from other devices on the network. To allow access from other devices on the network, you must modify the net_* options to bind the daemon to a reachable network interface.
Health
The array's aggregate health is determined by evaluating historical log data alongside real-time hardware telemetry.
If the array transitions into a problematic health state, the daemon issues an alert through the configured notification system. The PENDING state is informational and does not by itself trigger an alert. Note that the detection of such states is not instantaneous, it occurs during the telemetry collection cycle, the frequency of which is determined by the probe_interval_minutes option.
In the REST API, the health state is reported by the health field. Whenever the health is not PASSED, a supplementary health_reason field is provided to give a discursive explanation of the specific condition or failure detected.
The Web UI also reflects these states by displaying a prominent top banner across all pages if the health is in a problematic state. This ensures that critical issues are visible regardless of the specific dashboard view being accessed.
The possible health states are:
Physical Input/Output errors also affect disk health. Data and parity I/O errors that SnapRAID can associate with a block, as well as I/O errors associated with a concrete filesystem object, are tracked as transient disk errors. Transient disk errors remain active until a later scrub reports that no blocks are bad.
By contrast, unlocalized data and parity I/O errors, such as close errors, are still counted in the lifetime error_io counter but do not affect disk health.
Individual tasks also maintain a health state reflecting only the problems identified during that specific operation. For example, an array in a CORRUPT state may still produce a PASSED result for a probe task if that operation encountered no specific errors.
In the DEGRADED, PREFAIL or FAILING state, the Maintenance button in the Web UI is replaced with a Refresh button. This allows you to force the daemon to re-scan the state of the array (by re-reading the content file) after any manual fixes have been performed via the command line.
If the array entered the PREFAIL state due to input/output errors, and the content file loaded after clicking Refresh contains no marked bad sectors, the input/output error counters for each disk are automatically cleared, allowing the array to re-enter the PASSED state.
Note that clicking the Refresh button does not cause the daemon to verify that the underlying input/output errors are resolved. Instead, the daemon assumes that you have:
- Checked the log files manually to understand the cause of the failure.
- Resolved the root cause of the input/output errors.
- Re-run the command that failed to ensure that the errors are gone.
- Used the fix and scrub commands to restore any files that needed to be recovered to clear any marked bad sectors.
If the underlying cause of the input/output errors is not resolved, the errors will eventually reappear.
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 the configure script).
This file governs the behavior of the automation engine, network accessibility, safety interlocks, and hardware monitoring parameters.
The configuration system is designed with a triple-tier management philosophy to balance operational convenience with rigorous system security:
Tier 1 Core Network (Immutable) - This tier includes critical security
and networking parameters, such as the master API toggle, port bindings, and access control lists. These settings are completely inaccessible via the REST API. To modify them, you must perform a manual file edit followed by a SIGHUP signal to reload the configuration into memory.
Tier 2 Protected Operations (Secured) - These parameters involve
security-sensitive automation, such as system user assignments, external script paths, and logging policies. By default, these options are read-only via the REST API. They can only be modified via API PATCH requests if the net_config_full_access flag is manually enabled in this file.
Tier 3 Dynamic Logic (Live) - This tier consists of standard
operational settings like maintenance schedules, scrub intensities, and disk monitoring intervals. These parameters are fully accessible and can be modified in real-time via the API. Changes made through the REST interface are applied to the running process and written back to this file while preserving all existing manual comments.
Configuration changes are not applied atomically to all runtime components and existing operations. A successful configuration update means that the new configuration has been accepted, but does not guarantee that every component or previously scheduled task has already switched to it.
After manually editing /etc/snapraidd.conf, apply the change before making configuration changes through the API to prevent the daemon from overwriting the manual edit with its memory state. Runtime-reloadable options can be applied with a SIGHUP signal. Changes to sys_* options require a daemon restart because a SIGHUP that changes them is rejected.
Example:
sudo killall -HUP snapraidd
For a comprehensive view of how these settings are applied in a 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. All sys_* options are read at daemon startup and changing any of them requires a daemon restart. A SIGHUP reload which changes a sys_* option is rejected and the previous configuration remains active.
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.
sys_log_compression
Enables compression of individual SnapRAID task log files in gzip (.gz) format.
Setting this option to 1 enables gzip compression, saving files with the .log.gz extension. If set to 0 or left empty (the default), log files are saved as plain text with the .log extension.
Gzip compression requires the daemon to be built with zlib support. If compression is enabled on a build without zlib, the daemon logs an error and falls back to uncompressed logs.
Changing this option only affects newly created task logs. Existing logs (whether uncompressed .log or compressed .log.gz) continue to be read transparently by the daemon when reconstructing array history, and are purged by sys_log_retention_days regardless of format.
sys_shutdown_on
A comma-separated list of events that trigger an automatic system shutdown.
Supported events are:
For both prefail and failing emergency shutdowns, if the daemon is still able to process runner tasks, it first sends the emergency report. Queued tasks and post-hooks are canceled, and paused Docker containers are not unpaused, to prevent further disk activity. If daemon termination or a fatal daemon failure is already in progress, the emergency shutdown may proceed without sending the report.
Spaces around commas are ignored.
Health-based shutdowns (prefail and failing) trigger strictly on a state transition from an established health state. If the array is already in a prefail or failing state when the daemon starts, shutdown is not triggered. This allows you to start the machine and perform manual maintenance or recovery without triggering an immediate shutdown.
sys_smartignore
Allows you to ignore specific SMART attributes for one or more disks. Changes of ignored attributes are omitted from status reports and do not generate warning notifications. The attributes continue to be collected and are exported in the REST API as ignored. Typical attributes to ignore are Spin_Up_Time and Raw_Read_Error_Rate. You can also use Error_Protocol and Error_Medium to ignore device-level protocol or medium errors.
Normalized-value degradations of critical PREFAIL SMART attributes generate warning notifications. Normalized-value changes of non-critical PREFAIL attributes are informational, even when not ignored. sys_smartignore can still be used to hide noisy vendor-specific changes from reports and to suppress warnings from actionable raw/error-counter changes.
sys_smartignore does not affect SMART failure states reported by smartctl. If an attribute is reported as currently failed, it will still trigger a critical notification and degrade the array health.
The option is a sequence of words separated by spaces. The first word is a disk name or '*' for all disks. The subsequent words are attribute numbers or names (case-insensitive).
Examples:
sys_smartignore=parity 188 Command_Timeout sys_smartignore=d1 Error_Protocol sys_smartignore=* Spin_Up_Time Raw_Read_Error_Rate
Network & REST API
These settings control the network interface.
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.
net_enabled
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 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:7627,[::1]:7627 retrying with only 127.0.0.1:7627 if it fails.
To export the service to a VPN like Tailscale or a local network, you should bind to all interfaces by specifying only the port number.
Examples:
net_port=127.0.0.1:7627 - IPv4 loopback only (Recommended). net_port=[::1]:7627 - IPv6 loopback only. net_port=7627 - All IPv4 interfaces (Required for Tailscale/LAN). net_port=[::]:7627 - All IPv6 interfaces. net_port=127.0.0.1:7627,127.0.0.1:8080 - Listen on multiple ports on loopback.
net_acl
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). The rules are processed sequentially, and the last matching rule determines the outcome. If unset, it defaults to accept everything. If any rules are defined, the daemon adopts a deny by default stance.
To allow access via Tailscale or similar services, ensure you add the relevant network prefix (e.g., +100.0.0.0/8).
Examples:
net_acl=+127.0.0.1,+::1 - Allow IPv4 and IPv6 loopback. net_acl=+100.0.0.0/8,+127.0.0.1 - Allow Tailscale and loopback. net_acl=+192.168.1.0/24 - Allow local subnet only.
net_security_headers
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 Cross-Origin Resource Sharing (CORS) to determine which web applications can interact with the API.
net_config_full_access
A security flag that determines whether sensitive configuration parameters can be modified via the REST API.
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:
net_web_root
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 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.
The daemon recursively crawls the directory or archive at startup to provide high-performance, compressed delivery of the UI.
When a directory is specified, assets are cached in memory, as a result, manual changes to asset files on the disk will not be reflected in the UI until the daemon is restarted. This behavior can be bypassed by using the -N, --no-cache option during daemon startup, which is recommended for development environments only.
net_auth_credential
Specifies the credentials required to access the REST API and dashboard via HTTP Basic Authentication. If empty or omitted, authentication is disabled.
The credentials must be formatted as:
username:$argon2id$v=19$m=65536,t=3,p=1$salt_base64$hash_base64
This is calculated using Argon2id with 64MiB of memory cost (m=65536), 3 iterations (t=3), and 1 thread (p=1).
A secure configuration line can be generated by running the daemon with the -g, --gen-auth command line argument.
Note that the /metrics endpoint is exempt from authentication to support unauthenticated scraping by Prometheus or other monitoring tools.
WARNING: Basic Authentication transmits credentials in plaintext (Base64) over the network. Using this over unencrypted HTTP is NOT secure. You should deploy an HTTPS encryption layer (such as a reverse proxy like Caddy, Nginx, or Traefik) or restrict network access to a trusted, secure network (e.g., using a VPN or Tailscale).
This option is security-sensitive and cannot be modified via the REST API. It requires a manual edit and a configuration reload (SIGHUP) to apply.
Automation & Maintenance
These settings control the automation and maintenance tasks run by 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.
check_updates
Enables (1) or disables (0) periodic check for daemon and engine updates on GitHub via the curl CLI tool. If enabled, the daemon queries the GitHub API every 12 hours in the background. The WebUI displays the update status and alerts you when new versions are available, and status reports include an update notice. If missing or set to 0, update checking is disabled.
maintenance_schedule
Defines the timing for the automated maintenance sequence, which consists of a sync, followed by a scrub, and concluding with a report. Multiple schedules can be specified by separating them with commas. If this option is unset, automated maintenance is disabled.
The format must be either "HH:MM" or "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).
Examples: "02:00" - Run every night at 2 AM. "Mon 03:00, Thu 04:00" - Run every Monday at 3 AM and Thursday at 4 AM.
sync_threshold_deletes
Sets the number of deleted or missing files that will trigger an automatic abort of a sync operation. The abort occurs when the number of deletions is equal to or greater than this value. This serves as a safety mechanism to prevent accidental parity loss; for example, setting this to 1 will abort the operation if any single file is deleted. This check is enforced during automated maintenance schedules and tasks initiated through the Web UI.
sync_threshold_updates
Sets the number of modified or updated files that will trigger an automatic abort of a sync operation. The abort occurs when the number of updates is equal to or greater than this value. This prevents the parity from being overwritten if an unexpected number of files have changed. Similar to the delete threshold, setting this to 1 will abort the operation if any single file is modified. This 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. This calculates the hash of all files before the synchronization process begins. By hashing data before the system is subjected to the high CPU and I/O load typical of a sync operation, it protects against silent data corruption caused by faulty memory that may only trigger under critical system stress. If missing or set to 0, no pre-hashing is performed.
sync_prevent_truncations
If set to 1, the sync is halted to prevent overwriting parity with empty file data. This provides a safety barrier against truncated data, which may occur during system crashes or filesystem errors. If this is missing or set to 0, the sync is allowed to proceed even if files have shrunk to zero size.
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.
touch_zero_subseconds
If set to 1, a specific timestamp alignment pass is performed immediately before the sync during the maintenance window. If this is missing or set to 0, this pass is skipped.
Many filesystems or file-copying utilities may leave file timestamps with exactly zero nanoseconds. This lack of precision can cause the synchronization engine to misidentify moved or renamed files as entirely new content.
Setting this to 1 triggers the touch command to update these sub-second parts of the timestamps to a random value. This ensures high-resolution tracking is available to correctly identify relocated data without re-processing the underlying file blocks.
Disk Monitoring & Power
These 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.
Note that this applies only to data and parity disks configured in snapraid.conf. Any other disks, including extra disks, are not subject to spindown.
You can specify a single integer (e.g. 15) to apply the timeout to both data and parity disks, or two comma-separated integers (e.g. 15, 30) to set separate timeouts for data and parity disks respectively. A value of 0 disables spindown for that specific disk type. For example, 0, 30 disables spindown for data disks but spins down parity disks after 30 idle minutes.
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.
If set to 0 or left blank, the daemon will not manage disk power states, relying instead on the OS or hardware controllers.
hook_script
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 current stage of a hook lifecycle. A hook lifecycle is an uninterrupted session covering one or more consecutive tasks that access the array:
If task-begin fails, task-error is not invoked. The task-begin handler is responsible for reverting any partial changes before returning an error.
Hook lifecycle boundaries do not necessarily match task group boundaries. When consecutive array-access tasks can safely share the same paused state (such as paused Docker containers and pre-hook preparations), the daemon may postpone hook cleanup and keep that state active across the boundary between two task groups. As a result, a task-begin event may occur while processing one group and the corresponding task-end or task-error event may occur only after tasks belonging to a subsequent group have completed.
The hook configuration is snapshotted when the hook lifecycle begins and remains associated with that lifecycle until its cleanup attempt completes. Configuration reloads do not alter an already active hook lifecycle. In particular, the corresponding task-end or task-error hook, the post-script, and Docker cleanup always use the same hook configuration and acquired-resource state established by the matching task-begin, even if the daemon configuration changes in the meantime.
A new configuration becomes effective for hooks when a new hook lifecycle is started after the cleanup attempt for the previous lifecycle has completed.
Note that 'task-end' reflects only whether the hook lifecycle finished its execution cycle successfully. 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.
The script is executed with several environment variables providing details about the execution context:
During task-end and task-error events, the following additional variables are also available:
For diff and sync commands, modification metrics are also exposed:
SECURITY REQUIREMENTS: * The script path MUST be absolute (must start with /). * The script AND the directory containing the script MUST be owned by
the daemon's real UID, effective UID, or root (UID 0).
- The script AND directory containing the script MUST NOT be group-writable, unless its group matches the daemon's GID/EGID or is root.
- The script AND directory containing the script MUST NOT be world-writable (S_IWOTH).
- The script MUST have at least one execute bit set (S_IXUSR, S_IXGRP, or S_IXOTH).
- The script MUST NOT have the setuid or setgid bits set (S_ISUID or S_ISGID).
- The script MUST NOT have multiple hard links (st_nlink == 1 only).
If the execution fails, check your syslog (EventLog in Windows) to get the exact reason.
This remains inactive if no path is defined.
hook_docker_pause
Specifies a comma-separated list of Docker containers to pause during tasks that access the array (e.g., plex, transmission).
At the start of a hook lifecycle (immediately before executing the task-begin hook), the daemon pauses only the listed containers that are running and not already paused. When the hook lifecycle concludes, it attempts to unpause only those containers. Containers that were already paused remain paused, and stopped containers remain stopped.
If the unpause operation fails, the hook cleanup is reported as failed. The daemon does not retry the unpause operation in a later hook lifecycle.
hook_run_as_user
Specifies the user account used to execute the hook_script. If this is missing or blank, the script is executed with the daemon's original startup privileges.
On Linux, nobody is the standard choice for maximum isolation. Note that using nobody may prevent certain tools, such as Docker, from functioning correctly due to restricted permissions. Ensure you are aware of these limitations before applying this setting.
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.
Notifications
These settings control the notification operations performed by the daemon.
notify_syslog_enabled
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 are info, warning, error, and critical. The default is error.
notify_heartbeat
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_start
Specifies a command triggered at the start of maintenance, heal, undelete, and refresh tasks. The daemon pipes a simple plain-text start message directly into the command's stdin.
notify_result
Specifies a command triggered after every report task generated by high-level tasks or by a SMART telemetry change. 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.
Examples of usage:
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 strings). 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:
The report contents are not available as a placeholder. They are passed to the command through standard input (stdin).
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 or _netrc):
machine smtp.gmail.com login your_email@gmail.com password your-16-char-app-password-without-spaces
notify_result_level
Controls the filter for notify_result. The notification is sent only if the task result is equal to or more severe than this level. Valid values are info (always send), warning, error, and critical. The default is warning.
Note that SMART attribute changes are rated as warning. Problematic array health states (CORRUPT, DEGRADED, PREFAIL, and FAILING) are rated as critical. The PENDING state is informational and does not by itself increase the notification severity.
notify_run_as_user
The user account used for notify_heartbeat, notify_start, notify_result and mail notifications. If missing or left blank, the task runs with the daemon's original startup privileges.
On Linux, nobody is the standard choice for maximum isolation. However, while sufficient for simple curl commands, it may cause failures for mailers (like sendmail or postfix) that require specific group memberships or access to mail queues. Verify that your notification tools can operate without a home directory or write access to system logs.
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 before a sync begins. If set to 0 or missing, no difference report is 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 like Healthchecks.io.
In this example, curl sends a simple GET request to a unique monitoring URL. The flags ensure that curl fails silently on server errors (-f), does not hang indefinitely (--max-time), and attempts to overcome transient network issues (--retry).
notify_heartbeat = curl -f --max-time 30 --retry 3 https://hc-ping.com/your_private_uuid
Push Notifications (ntfy.sh)
This uses curl to send the report as a POST request to a push notification service. It utilizes the --narrow flag to ensure the report is readable on mobile devices and maps SnapRAID status to ntfy titles, priorities, and emojis via placeholders.
notify_result = curl --narrow -f --max-time 30 --retry 3 -H "Title: %s" -H "Priority: %n" -H "Tag: %t" --data-binary @- https://ntfy.sh/your_private_topic
If you want to also send an email, you can add '-H "Email: your_email@example.com"' but you also need to authenticate by sending an authentication token. See:
Local System Mail (mail)
A traditional approach using the standard Linux mail utility. This is ideal if you have a local Mail Transfer Agent (MTA) like Postfix or Exim already configured on your system.
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 external provider. By using the --netrc option, login credentials remain secured in a separate file rather than being exposed in the process list or logs.
notify_result = curl --netrc --url smtps://smtp.gmail.com:465 --ssl-reqd --mail-from your_email@gmail.com --mail-rcpt your_email@gmail.com --upload-file -
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 typically located in the documentation directory of the installation.
All state-changing API requests require the Content-Type header to be set to application/json, even when the request body is empty. This ensures that browser cross-origin requests require a CORS preflight, providing protection against Cross-Site Request Forgery (CSRF). Chunked request bodies are not supported.
Maintenance & Recovery
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 conclude with a report command that generates a notification containing the operation's results.
/snapraid/v1/maintenance
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. The operation is aborted if the array is in a DEGRADED, PREFAIL or FAILING health state. 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.
Example:
curl http://localhost:7627/snapraid/v1/maintenance \ --json '{}'
It is implemented with the sequence of commands: up, diff, sync, scrub, and report.
/snapraid/v1/heal
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.
Example:
curl http://localhost:7627/snapraid/v1/heal \ --json '{}'
It is implemented with the sequence of commands: up, fix -e, scrub -p bad, and report.
/snapraid/v1/undelete
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.
Example:
curl http://localhost:7627/snapraid/v1/undelete \ --json '{ "filters": [ "*.txt" ] }'
It is implemented with the sequence of commands: up, fix -m -f ..., and report.
/snapraid/v1/suspend_idle
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.
Example:
curl http://localhost:7627/snapraid/v1/suspend_idle \ --json '{}'
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, PREFAIL or DEGRADED modes once the underlying hardware or configuration issues have been resolved manually.
Example:
curl http://localhost:7627/snapraid/v1/refresh \ --json '{}'
/snapraid/v1/report
Generates a status report describing the current array state and health. The report task is scheduled asynchronously and is executed according to the normal task queue semantics.
Example:
curl http://localhost:7627/snapraid/v1/report \ --json '{}'
Monitoring & Inventory
These endpoints provide high-level visibility into the global state of the storage stack and the health of the underlying physical hardware.
/snapraid/v1/array
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.
Example:
curl -s http://localhost:7627/snapraid/v1/array | jq
/snapraid/v2/disks
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).
Example:
curl -s http://localhost:7627/snapraid/v2/disks | jq
Runtime Configuration
Provides a programmatic interface to retrieve and modify the operational parameters of the daemon in real-time.
/snapraid/v2/config
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.
Example:
curl -s http://localhost:7627/snapraid/v2/config | jq curl -X PATCH http://localhost:7627/snapraid/v2/config \ --json '{ "probe_interval_minutes": 10 }'
Activity Control
All operations that modify the array state are asynchronous; they return an HTTP 202 Accepted status and queue a task for background execution.
Because tasks run in the background, these endpoints are used to monitor progress and manage the execution lifecycle.
/snapraid/v1/activity
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.
Example:
curl -s http://localhost:7627/snapraid/v1/activity | jq
/snapraid/v1/tasks
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.
Example:
curl -s http://localhost:7627/snapraid/v1/tasks | jq
/snapraid/v1/stop
Terminates the currently running task (such as sync or scrub) by sending a SIGTERM signal to the background process.
Example:
curl http://localhost:7627/snapraid/v1/stop \ --json '{}'
/snapraid/v1/clear
Cancels all tasks currently waiting in the execution queue, moving them to the task execution history with canceled status. Any task currently running is unaffected.
Example:
curl http://localhost:7627/snapraid/v1/clear \ --json '{}'
State and Cache Management
To optimize performance and support lightweight monitoring (such as desktop status bars), the daemon implements a state synchronization mechanism via the /v1/state endpoint.
/snapraid/v1/state
The response provides a high-level summary of the daemon's current operation and health, alongside a pulse object containing sequence counters.
The pulse object contains counters used for cache invalidation. Each field corresponds directly to a data-heavy API entry point.
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.
Note that the counters are not necessarily monotonically increasing because they are reset if the daemon restarts. You should compare them only for equality.
Example:
curl -s http://localhost:7627/snapraid/v1/state | jq
Schedule
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.
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.
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.
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.
/snapraid/v1/schedule
Queues a sequence of standard SnapRAID operations.
Example:
curl http://localhost:7627/snapraid/v1/schedule \ --json '{"tasks": [{"command": "diff"}, {"command": "report"}]}'
Supported Commands:
Multiple arrays in Linux systemd
To manage multiple independent SnapRAID arrays on a single systemd host, you can run multiple daemon instances using the systemd template unit snapraidd@.service.
Each instance runs isolated under its own configuration, listening port, and SnapRAID array config.
To configure multiple instances:
Create distinct daemon configuration files:
cp /etc/snapraidd.conf /etc/snapraidd-main.conf cp /etc/snapraidd.conf /etc/snapraidd-backup.conf
Edit /etc/snapraidd-main.conf to set a custom port and log folder:
net_port = 127.0.0.1:7627 sys_log_directory = /var/log/snapraid/main
Edit /etc/snapraidd-backup.conf to use a different port and log folder:
net_port = 127.0.0.1:7628 sys_log_directory = /var/log/snapraid/backup
Disable the default single-array service (if running):
systemctl disable --now snapraidd.service
Create distinct SnapRAID engine configuration files for each array, e.g. /etc/snapraid-main.conf and /etc/snapraid-backup.conf, each pointing to its own set of disks and parity drives.
Enable and start the template instances. The instance name after the @ corresponds to the suffix of the config file. For example, main will load /etc/snapraidd-main.conf and use /etc/snapraid-main.conf as the SnapRAID engine configuration:
systemctl enable --now snapraidd@main systemctl enable --now snapraidd@backup
Access the independent dashboards at:
http://localhost:7627 http://localhost:7628
Multiple arrays in Windows
To manage multiple independent SnapRAID arrays on a Windows host, you can install multiple distinct Windows service instances of the daemon using the --service-install command with the -i option.
Each instance runs under its own configuration and listening port.
To configure multiple instances:
Create distinct daemon configuration files in your installation directory:
copy C:\snapraid\snapraidd.conf C:\snapraid\snapraidd-main.conf copy C:\snapraid\snapraidd.conf C:\snapraid\snapraidd-backup.conf
Edit C:\snapraid\snapraidd-main.conf to set a custom port and log folder:
net_port = 127.0.0.1:7627 sys_log_directory = C:\snapraid\log\main
Edit C:\snapraid\snapraidd-backup.conf to use a different port and log folder:
net_port = 127.0.0.1:7628 sys_log_directory = C:\snapraid\log\backup
Remove the default service instance (if registered):
C:\snapraid\snapraidd.exe --service-remove
Create distinct SnapRAID engine configuration files for each array, e.g. C:\snapraid\snapraid-main.conf and C:\snapraid\snapraid-backup.conf, each pointing to its own set of disks and parity drives.
Install the service instances using the --service-install option. Use -c to specify the daemon configuration file and -C to specify the SnapRAID engine configuration file for each instance:
C:\snapraid\snapraidd.exe --service-install -i main -c C:\snapraid\snapraidd-main.conf -C C:\snapraid\snapraid-main.conf C:\snapraid\snapraidd.exe --service-install -i backup -c C:\snapraid\snapraidd-backup.conf -C C:\snapraid\snapraid-backup.conf
This registers and starts two Windows services named snapraidd-main and snapraidd-backup configured to start automatically.
Access the independent dashboards at:
http://localhost:7627 http://localhost:7628
To remove a service instance, run the --service-remove option:
C:\snapraid\snapraidd.exe --service-remove -i main C:\snapraid\snapraidd.exe --service-remove -i backup
Signals
This section defines how the daemon responds to standard Unix signals, allowing for external process control and graceful management of the service lifecycle.
SIGHUP
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 parameters without restarting the service.
SIGTERM, SIGINT
Initiates a graceful shutdown. If a task is currently running, the active SnapRAID process is terminated, the post-run hook is executed and any paused Docker containers are unpaused.
SIGQUIT
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.
Files
The following list specifies the default filesystem paths used by the daemon for configuration, data persistence, and inter-process communication.
Linux
On Linux and Unix-like systems:
$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.
$PREFIX/share/snapraidd
The primary system data directory. This is the first location searched for the web dashboard ZIP file (e.g., commander.zip or brutale.zip). If not found here, the daemon falls back to /usr/share/snapraidd.
/etc/snapraidd.conf
The secondary/system-wide configuration file location, used if the prefix-specific file is missing.
/usr/share/snapraidd
The secondary/system-wide data directory, used as a fallback for web assets.
/run/snapraidd.pid
Default PID file location.
/var/log/snapraid
Default directory for SnapRAID command execution logs. This directory contains the output of the SnapRAID binary itself, rather than the daemon's service logs. If this directory does not exist, the daemon will attempt to create it upon the first execution of a SnapRAID command.
Windows
On Windows systems:
snapraidd.conf
The configuration file is expected to be in the same directory where the snapraidd.exe binary is located.
log\
A subdirectory named log within the installation directory is used to store the SnapRAID command execution logs. If this directory does not exist, the service will attempt to create it upon the first execution of a SnapRAID command.
commander.zip or brutale.zip
The web dashboard assets are searched for in the same directory as the executable.
Known Issues
Monotonic Time Assumption
The daemon assumes that time progresses monotonically.
Historical log files are named using the local wall-clock time and are replayed in filename order at startup. If the local clock moves backwards, for example during a daylight-saving-time transition or after a manual clock adjustment, logs created later may be replayed before older ones, or two tasks may generate the same log filename.
The daemon also assumes that the modification time of the SnapRAID content file increases whenever the file is updated. If the system clock moves backwards and the content file is subsequently modified by a SnapRAID command executed outside the daemon, the startup probe may not detect the newer content state.
For correct state reconstruction, the system clock and local civil time are therefore expected not to move backwards while retained daemon logs or
Lifetime Counters Depend on Log Retention
Some cumulative statistics are reconstructed at startup from the retained daemon logs rather than from separately persistent state.
When old logs are removed according to the configured log retention period, information contained only in those logs is no longer available during a subsequent restart. As a result, cumulative counters reconstructed from the available history may decrease or restart from zero after older logs have been removed.
Such counters should therefore be interpreted as covering the history available in the retained daemon logs, rather than necessarily the complete lifetime of the installation.
Incomplete Log Recovery
Incomplete daemon logs are recovered only up to the last complete record that can be parsed successfully.
For plain logs, a final unterminated line is discarded. For compressed logs, a truncated gzip stream may still be recovered up to the last complete decompressed record available before the truncation.
Any data contained only in an incomplete final record is therefore lost during restart reconstruction. Tasks without the required final termination information are treated as interrupted according to the available log state.
Log recovery should therefore be considered best effort and guarantees only the preservation of complete records successfully written before the interruption.
Configuration Changes
Configuration updates and reloads are applied asynchronously and are not guaranteed to take effect atomically or immediately across all runtime components and operations.
For a short transition period, components and in-flight operations may observe settings from different configuration generations at different points in their lifecycle, while tasks already scheduled or running may continue using settings captured before the change.
This also applies to security-sensitive settings. In-flight REST requests and already accepted connections may continue under previously admitted conditions or observe security settings from different configuration generations.
Non-UTF-8 Paths in the REST API
On Unix, filesystem paths containing invalid UTF-8 bytes are represented in the REST API with Python's surrogateescape encoding (PEP 383). Non-decodable bytes in the range 0x80-0xFF are mapped to lone Unicode surrogate code points in the range U+DC80-U+DCFF (formatted in JSON as \udc80-\udcff), allowing paths with arbitrary byte sequences to be represented losslessly across the REST API.
Devices Without Stable or Unique IDs
The daemon relies on stable and unique device identifiers, such as hardware serial numbers, to preserve physical device health information across mapping updates.
If a device exposes no stable identifier, or if an identifier is not unique across the currently detected devices, it cannot be trusted as a persistent physical-device identity. This can happen with virtual disks, certain USB enclosures, cloned identifiers, or hardware that reports incomplete or ambiguous identification data.
The daemon therefore discards historical device information when the device cannot be identified reliably.
As a result, previous SMART or health state may be lost until fresh telemetry is collected.
Concurrent Docker Changes During Hooks
Docker container state is inspected before the daemon performs its pause and resume operations.
Concurrent external Docker operations, such as pausing, unpausing, or removing a selected container outside the daemon while a task is running, may cause the daemon to unpause a container that was externally paused, or cause unpause cleanup to fail if the container was removed.
External changes to selected containers should not be performed while a hook lifecycle is being established or is active.
Blocking Hooks, Docker Operations, and Notifications
Hook scripts, Docker operations, and notification commands are expected to terminate.
If any of these operations block indefinitely, task execution, hook cleanup, report generation, notification processing, and graceful daemon shutdown may also remain blocked. Paused Docker containers may remain paused until external recovery is performed.
Incomplete JSON syntax validation
The REST API uses JSMN in strict mode, which does not fully validate the JSON grammar. Some malformed JSON inputs, such as trailing commas or repeated colons, may therefore be accepted and processed normally.
Global Authentication Rate Limiting Can Starve New Clients
REST authentication globally rate-limits uncached attempts to bound Argon2 CPU and memory usage. A continuous stream of uncached attempts can therefore consume every authentication slot and cause other uncached clients to receive HTTP 429 indefinitely.
Cached credentials bypass the limit. This is an intentional tradeoff: per-client limits do not protect against distributed sources, while removing the global limit could allow concurrent Argon2 operations to exhaust system resources.
Configuration File ACLs Are Not Preserved
Configuration updates made through the REST API rewrite the daemon configuration using a temporary file followed by file replacement.
On Unix, the replacement preserves the original file owner, group, and standard permission bits, but it does not preserve extended POSIX ACLs or other per-file access-control metadata.
On Windows, a replacement file may likewise receive security settings derived from its creation context rather than preserving a custom security descriptor attached to the original configuration file.