SnapRAID
Synopsis
snapraidd [-c, --conf CONFIG] [-f, --foreground] [-p, --pidfile FILE] [-N, --no-cache] [-v, --verbose]
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:
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 "hybrid" management philosophy to balance convenience with system security:
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.
Network & REST API
These settings control the network interface. These options are not visible from the REST API and can be set only in the snapraidd.conf file.
net_enabled
Master toggle for the HTTP interface. Set to 1 to enable the REST API, otherwise, the daemon operates in local-only mode.
net_port
Defines the IP address and port the daemon binds to (e.g., `127.0.0.1:8080`). Supports IPv4, IPv6, and multiple ports.
net_acl
Restricts API access to specific client IPs using a comma-separated list of allow (+) or deny (-) rules.
net_security_headers
When enabled (1), injects security headers like CSP and X-Frame-Options to harden the API against browser-based attacks.
net_allowed_origin
Configures CORS. Use `self` for standard setups, `none` to block browser access, or a specific URL for custom dashboards.
net_config_full_access
Determines if restricted parameters (like scripts and log paths) can be modified via the REST API. Defaults to 0 (Read-only).
net_web_root
Specifies the local path where the web dashboard assets are located. This option supports both a standard directory and a single compressed ZIP file. If a ZIP file is provided, the internal HTTP server will serve assets directly from the archive without requiring extraction to the disk.
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.
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.
maintenance_schedule
Defines when the automated sync, scrub, and report sequence occurs (e.g., `daily 02:00` or `weekly Mon 03:00`).
sync_threshold_deletes
Maximum number of deleted/missing files allowed before a scheduled sync is aborted to prevent accidental parity loss.
sync_threshold_updates
Maximum number of modified files allowed before a scheduled sync is suspended.
sync_prehash
Enables the SnapRAID prehash option to verify files before updating parity, protecting against faulty RAM or cables.
sync_force_zero
Permits synchronization even if protected files have unexpectedly shrunk to zero bytes.
scrub_percentage
The percentage of the array verified during the scrub phase of automated maintenance.
scrub_older_than
Restricts scrubbing to blocks that have not been verified within the specified number of days.
probe_interval_minutes
Interval for background health checks. SMART attributes are only queried if disks are already active to avoid waking them.
spindown_idle_minutes
Inactivity threshold (in minutes) after which the daemon will issue a spindown command to the disks.
script_run_as_user
The system user account utilized for the execution of pre- and post-run hooks.
script_pre_run/script_post_run
Absolute paths to executable shell scripts triggered before or after SnapRAID activity.
Logging & Notifications
These settings control the logging and notification operations performed by the SnapRAID daemon.
log_directory
Path where individual SnapRAID command outputs are stored as `.log` files. Default: `/var/log/snapraid`.
log_retention_days
Number of days to keep log files before they are purged.
notify_syslog_enabled
Enables logging of daemon activity to the OS system log (syslog/journald).
notify_syslog_level
Sets the minimum severity for syslog task entries. Possible values: info, warning, error, critical. Default: error.
notify_heartbeat
A shell command (e.g., `curl`) executed only upon task success, ideal for "dead man's switch" monitoring.
notify_result
A shell command triggered after task completion; it receives the task report via stdin.
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. Possible values: info, warning, error, critical. Default: error.
notify_email_recipient
Local system email address for receiving health reports.
notify_email_level
Sets the minimum severity for email reports. Possible values: info, warning, error, critical. Default: error.
notify_differences
If enabled, includes a detailed list of file changes (added/removed/modified) in the notification reports.
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.
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 end with a `report` command that generates a notification with a full report of the result of the operation.
/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. This task is subject to the 'sync_threshold_deletes' and 'sync_threshold_update' 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 -X POST http://localhost:8080/snapraid/v1/maintenance
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 -X POST http://localhost:8080/snapraid/v1/heal
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 -s -X POST http://localhost:8080/snapraid/v1/undelete \ -H "Content-Type: application/json" \ -d '{ "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 -X POST http://localhost:8080/snapraid/v1/suspend_idle
It is implemented with the sequence of commands: probe, down_idle.
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:8080/snapraid/v1/array | jq
/snapraid/v1/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:8080/snapraid/v1/disks | jq
Configuration
Provides a programmatic interface to retrieve and modify the operational parameters of the daemon in real-time.
/snapraid/v1/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 -X GET http://localhost:8080/snapraid/v1/config | jq curl -X PATCH http://localhost:8080/snapraid/v1/config \ -d '{ "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:8080/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:8080/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 -X POST http://localhost:8080/snapraid/v1/stop
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 -X GET http://localhost:8080/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 -X POST http://localhost:8080/snapraid/v1/schedule \ -d '{"tasks": [{"command": "diff"}, {"command": "report"}]}'
Supported Commands:
Signals
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 daemon attempts to terminate the child process before exiting.
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
$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). If not found here, the daemon falls back to `/usr/share/snapraidd`.