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.

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.

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.

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.

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 lifecycle stage of the task currently being processed by the daemon:

task-error: Triggered if the task sequence is aborted, interrupted,

or encounters an operational failure.

Note that 'task-end' reflects only whether the task finished its execution cycle. It does not necessarily reflect hardware or data integrity. For example, a sync command may return 'task-end' even if the array is technically in a corrupt state, provided the sync process itself finished without crashing.

Future versions of the daemon will introduce new event types that may not relate to array access or follow the task- naming convention. It is strongly recommended to implement a default handler to ignore unrecognized events

SECURITY REQUIREMENTS: * The 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_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 same privileges as the daemon process.

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.

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

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

notify_run_as_user

The user account used for notify_heartbeat, notify_result and mail notifications. If missing or left blank, the task runs with the daemon's current privileges.

On Linux, nobody is the standard choice for maximum isolation. 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.

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:

https://docs.ntfy.sh/publish/#authentication

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_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 -X POST http://localhost:7627/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:7627/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:7627/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:7627/snapraid/v1/suspend_idle

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 or PREFAIL modes once the underlying hardware or configuration issues have been resolved manually.

Example:

curl -X POST http://localhost:7627/snapraid/v1/refresh

/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/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:7627/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:7627/snapraid/v1/config | jq
curl -X PATCH http://localhost:7627/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: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 -X POST http://localhost:7627/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:7627/snapraid/v1/state | jq

/snapraid/v1/schedule

Queues a sequence of standard SnapRAID operations.

Example:

curl -X POST http://localhost:7627/snapraid/v1/schedule \
    -d '{"tasks": [{"command": "diff"}, {"command": "report"}]}'

Supported Commands:

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

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

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

The web dashboard assets are searched for in the same directory as the executable.