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:8080. Modification requires a configuration reload and is restricted from API access.

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

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.

maintenance_schedule

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

sync_threshold_deletes

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.

sync_threshold_updates

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.

sync_prehash

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.

sync_force_zero

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.

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.

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.

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.

script_pre_run/script_post_run

Defines absolute paths to custom scripts to be executed immediately before or after the sync, scrub, check, or fix commands. These scripts allow for custom logic such as mounting drives or sending custom alerts.

• The path must be absolute (starting with /).
• The script must not be world-writable (recommended permissions: 700 or 755).
• The script owner must match the daemon user or be root.
• The script must contain a valid shebang (e.g., #!/bin/sh).

script_run_as_user

Specifies the user account used to execute the pre-run and post-run scripts. If this is missing or blank, scripts are executed with the same privileges as the daemon process.

log_directory

The log_directory defines where the output of individual SnapRAID commands is stored. If left unset, the daemon defaults to /var/log/snapraid.

Setting this option to an empty value (log_directory = ) will explicitly disable the saving of command output to persistent files.

IMPORTANT: While it is possible to leave this empty to avoid saving files, these logs are used by the daemon to reconstruct the past state of the array (e.g., tracking the last successful sync or scrub). If no log directory is provided, the daemon will lose its "memory" of previous task results every time it is restarted.

log_retention_days

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

notify_syslog_enabled

When set to 1, daemon activity is sent to the operating system system 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_result

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

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

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.

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" -H "Email: your_email@example.com" --data-binary @- https://ntfy.sh/your_private_topic

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 -

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

/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

/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 }'

/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

/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

/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: