snapraidd.conf.example

### SnapRAID Daemon Config
#
# 1. Manual Edits: You can safely edit this file at any time. To apply changes
#    without restarting the process, send a SIGHUP signal, for example by
#    running 'systemctl reload snapraidd'.
# 2. API Updates: Changes made through the REST interface are applied
#    instantly and saved to this file while preserving your comments.
# 3. Conflict Warning: If you edit this file manually while the daemon is
#    running, remember to RELOAD before making any API changes to prevent
#    the daemon from overwriting your manual edits with its memory state.
#

### System
# Specify the absolute path to the SnapRAID CLI executable (the 'engine').
# If omitted, the daemon automatically searches:
# - Linux: /usr/bin, /usr/local/bin
# - Wine: /usr/bin
# - Windows: The directory containing the daemon executable.
#
# This option is not accessible from the REST API.
# It requires a manual edit and a configuration reload (SIGHUP) to apply.
#sys_engine = /usr/bin/snapraid

# The 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_directory = /var/log/snapraid

# 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_retention_days = 120

### Network & REST API
# The net_enabled switch acts as the master toggle for the HTTP interface.
# If this is set to 0 or left blank, the daemon operates in a secure,
# local-only mode and will not open any network ports.
# Setting this to 1 enables the REST API.
#
# This option is not accessible from the REST API.
# It requires a manual edit and a configuration reload (SIGHUP) to apply.
net_enabled = 1

# The net_port defines the specific IP address and port the daemon binds to.
# Format: [IP_ADDRESS:]PORT[s].
# IP_ADDRESS can be an IPv4 (e.g., 127.0.0.1) or an IPv6 address wrapped
# in brackets (e.g., [::1]). PORT is a standard number.
# If left unset, the daemon defaults to 127.0.0.1:7627.
#
# To export the service to a VPN like Tailscale or a local network, you
# must bind to all interfaces (0.0.0.0) by specifying only the port number.
#
# This option is not accessible from the REST API.
# It requires a manual edit and a configuration reload (SIGHUP) to apply.
#
# Examples:
#   "127.0.0.1:7627"       - IPv4 loopback only (Recommended).
#   "[::1]:7627"           - IPv6 loopback only.
#   "7627"                 - All IPv4 interfaces (Required for Tailscale/LAN).
#   "[::]:7627"            - All IPv6 interfaces.
#   "127.0.0.1:7627,127.0.0.1:8080"  - Listen on multiple ports on loopback.
#net_port = 127.0.0.1:7627

# The net_acl restricts API access to specific client IPs.
# Format: A comma-separated list of [+/-][IP/MASK].
# 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).
#
# This option is not accessible from the REST API.
# It requires a manual edit and a configuration reload (SIGHUP) to apply.
#
# Examples:
#   "+127.0.0.1,+::1"          - Allow IPv4 and IPv6 loopback.
#   "+100.0.0.0/8,+127.0.0.1"  - Allow Tailscale and loopback.
#   "+192.168.1.0/24"          - Allow local subnet only.
#net_acl = +127.0.0.1

# Injects browser-level security hardening headers into every HTTP response.
#
# When enabled (1), the daemon sends:
#   - Content-Security-Policy: Restricts resource loading to 'self'.
#   - X-Frame-Options: Prevents the UI from being embedded in <iframe> (Clickjacking).
#   - X-Content-Type-Options: Prevents MIME-sniffing.
#   - Referrer-Policy: Prevents leaking the daemon's URL to external sites.
#
# Set to 0 only if you are using a reverse proxy (Nginx, Traefik, Apache) that
# is already configured to provide these security headers.
# Default: 1
net_security_headers = 1

# Configures Cross-Origin Resource Sharing (CORS) to control which web
# applications can interact with the SnapRAID API.
#
# Supported values:
#   - self: (Recommended) The daemon reads the 'Host' header of the incoming
#           request and reflects it back as the allowed origin. This allows
#           the built-in UI to work across different IPs or hostnames.
#   - none: Omits all CORS headers. This blocks browser-based API access
#           from any origin.
#   - [URL]: A specific origin (e.g., http://192.168.1.50:3000) for users
#            running a custom or third-party dashboard.
#
# Default: self
net_allowed_origin = self

# The net_config_full_access flag determines if restricted parameters can be
# modified via the REST API.
# When set to 0 (default), security-sensitive options are read-only.
# When set to 1, the following options can be updated via PATCH requests:
#   - hook_run_as_user
#   - hook_script
#   - notify_run_as_user
#   - notify_heartbeat
#   - notify_result
#   - notify_result_level
#
# This option is not accessible from the REST API.
# It requires a manual edit and a configuration reload (SIGHUP) to apply.
net_config_full_access = 0

# The 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. When a ZIP file is used, the internal HTTP server serves
# assets directly from the archive, eliminating the need for an
# extracted file structure on the disk.
#
# The daemon resolves the location of the assets according to strict
# pathing rules:
#
# ZIP Filename:
# If the value is a simple filename ending in .zip with no path
# components (e.g., commander.zip), the daemon searches for the file
# in the installation data directories. It first checks the configured
# installation prefix at $PREFIX/share/snapraidd/, followed by the
# system-wide directory at /usr/share/snapraidd/.
#
# Explicit ZIP Path:
# If a path to a ZIP file is provided, it MUST BE ABSOLUTE
# (e.g., /opt/snapraid/ui.zip). The daemon will attempt to use this
# specific file exclusively and will not perform a search in
# system directories.
#
# Directories:
# If the target is a directory rather than an archive, the path
# MUST BE ABSOLUTE (e.g., /var/www/snapraid-ui/).
#
# Note: Any relative pathing (e.g., ./ui.zip or ../assets/) is
# explicitly unsupported for both directories and specific ZIP files
# to ensure predictable behavior regardless of the daemon's working
# directory. If the path is unresolved, is not absolute when
# required, or the archive is malformed, the web interface will
# fail to initialize.
#
# 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.
#
# If left unset or empty, the built-in web dashboard will be unavailable.
#
# This option is not accessible from the REST API.
# It requires a manual edit and a configuration reload (SIGHUP) to apply.
net_web_root = commander.zip

### Automation & Maintenance
# Use maintenance_schedule to define when the automated maintenance
# sequence—consisting of a sync, a scrub, and a report—should occur.
# You can specify multiple schedules by separating them with commas.
# Automated maintenance is disabled if this is unset.
#
# Format: "HH:MM" or "Day HH:MM".
# Hours (HH) use 24-hour format (00-23).
# Day is the short name (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.
#
maintenance_schedule = 02:00

# Defines the number of deleted or missing files that will trigger a 'sync'
# operation abort to prevent accidental parity loss.
# The check triggers when the count is equal to or greater than this value.
# For example, set to 1 to abort if any single file is deleted.
# This safety mechanism is enforced during 'scheduled_run' tasks and
# the '/api/v1/maintenance' API sequence.
# It is bypassed for standalone '/api/v1/sync' API requests.
# Set to 0 to disable this check.
sync_threshold_deletes = 50

# Defines the number of modified or updated files that will trigger a 'sync'
# operation abort.
# The check triggers when the count is equal to or greater than this value.
# For example, set to 1 to abort if any single file is modified.
# This safety mechanism is enforced during 'scheduled_run' tasks and
# the '/api/v1/maintenance' API sequence.
# It is bypassed for standalone '/api/v1/sync' API requests.
# Set to 0 to disable this check.
sync_threshold_updates = 100

# If set to 1, the sync command runs with the --prehash option. This calculates
# hashes before starting the sync process to protect against silent errors
# caused by faulty memory, which is often triggered by the critical system
# load and high I/O stress occurring during synchronization.
# If this is missing or set to 0, no prehash is used.
#sync_prehash = 1

# 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 occurs
# 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.
#sync_prevent_truncations = 1

# After a sync completes, the scrub_percentage determines how much of the
# array is verified.
# If this is missing or set to 0, the scrub phase is skipped entirely.
# You can use a decimal value (e.g., 0.5)
scrub_percentage = 0.7

# Do not scrub blocks newer than the specified number of days.
# If this is missing, or set to 0, the scrub does not apply a selection based
# on the age of the block.
scrub_older_than = 10

# 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.
#
# The scope of this option is to address filesystems or utilities that
# do not support or preserve sub-second precision, leaving file
# timestamps with exactly zero nanoseconds. This lack of resolution
# can cause the engine to misidentify moved or renamed files as
# entirely new data, potentially triggering unnecessary parity
# recalculations.
#
# It matches 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.
touch_zero_subseconds = 1

### Disk Monitoring & Power
# The probe_interval_minutes setting controls how often the daemon checks
# SMART attributes, provided the disks are already spinning.
# If this is set to 0 or left blank, SMART monitoring is disabled.
probe_interval_minutes = 3

# To save power, spindown_idle_minutes will automatically spin down data and
# parity disks after the specified period 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 this is set to 0 or left blank, the daemon will not manage disk power
# states.
spindown_idle_minutes = 15

# Specify an absolute path for 'hook_script' to trigger custom logic for various
# daemon events.
#
# The script is executed with a single positional argument:
# EVENT: The lifecycle stage of an action accessing the array.
#    - 'task-begin': Triggered before the daemon begins accessing the array.
#    - 'task-end':   Triggered after the array access concludes successfully.
#    - 'task-error': Triggered if the array access is interrupted or fails.
#
# 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.
#
# This option can only be modified via the REST API if 'net_config_full_access'
# is set to 1. Otherwise, it remains read-only for security reasons.
#hook_script = /usr/local/bin/snapraid-hook.sh

# The user account used for executing hook_script.
# If missing or left blank, the scripts run with the daemon's current 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.
#
# This option can only be modified via the REST API if 'net_config_full_access'
# is set to 1. Otherwise, it remains read-only for security reasons.
#hook_run_as_user = nobody

### Notifications
# --- System Log (syslog/journald) ---
# When notify_syslog_enabled is set to 1, daemon activity is sent to the
# OS system log. While lifecycle events like starting and stopping are
# always captured, task-related messages are filtered by the level below.
notify_syslog_enabled = 1

# Sets the minimum severity for syslog task entries.
# Possible values: info, warning, error, critical. Default: error.
notify_syslog_level = info

# Runs ONLY if the maintenance task was successful (it's not triggered by
# other tasks, like heal and undelete).
# Ideal for 'Dead Man's Snitch' or Healthchecks.io.
# If this ping stops, it means the server is down or the task is failing.
#
# This option can only be modified via the REST API if 'net_config_full_access'
# is set to 1. Otherwise, it remains read-only for security reasons.
#notify_heartbeat = curl -f --max-time 30 --retry 3 https://hc-ping.com/your_private_uuid

# The notify_result command is 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' defined below.
# The daemon pipes a structured, plain-text task report directly into the
# command's stdin.
#
# Examples of usage:
# 1. ntfy.sh (Modern Push Notifications): Uses curl to send the report as
#    a POST request that you can receive on your phone.
# 2. mail (Local System Mail): Uses the standard Linux 'mail' utility.
#    This is ideal if you have a local MTA (like Postfix or Exim) configured.
# 3. SMTP-over-SSL (Direct Delivery): Uses curl's built-in SMTP engine with
#    the --netrc option. This is the most secure method for direct
#    SMTP, as it keeps your login credentials out of persistent logs.
#
# Format Selection:
# The daemon automatically chooses a 'wide' (80-col) or 'narrow' (32-col)
# report based on the command and arguments used (e.g., 'mail' triggers wide).
# You can manually override this by adding --wide or --narrow to the
# command. These tags are stripped before the command is executed.
#
# Available Placeholders:
# %s : Replaced with the subject string (e.g., "[ERROR] SnapRAID Maintenance").
# %l : Replaced with the task level (critical, error, warning, info, debug).
# %n : Replaced with the ntfy priority (urgent, high, default, low, min).
# %t : Replaced with the ntfy tag (rotating_light, warning, -1, +1, heavy_check_mark).
#
# Automatic Header Injection:
# If the command contains --mail-from or --mail-rcpt options, the
# daemon automatically prepends a standard email header (From, To, and
# Subject) followed by a blank line to the report text. This ensures that
# curl's SMTP engine delivers a correctly formatted email to the recipient.
#
# Authentication with curl:
# - Linux: Curl looks for '.netrc' in the HOME directory of the executing
#   user. For a daemon running as root, place the file in: /root/.netrc
# - Windows: Curl looks for '_netrc' in the user profile. For a Windows
#   Service running as 'LocalSystem', place the file in:
#   C:\Windows\System32\config\systemprofile\_netrc
#
# Security & Permissions:
# - Linux: The '.netrc' file MUST have 600 permissions and be owned by the
#   executing user. Otherwise, curl will fail with error 55.
# - Windows: Ensure the '_netrc' file has permissions restricted to System and
#   Administrators.
#
# File format (.netrc or _netrc):
# machine smtp.gmail.com
# login your_email@gmail.com
# password your-16-char-app-password-without-spaces
#
# For security enforcement, this parameter is immutable via the REST API
# unless 'net_config_full_access' is explicitly enabled in the static
# configuration file.
#
# Examples:
# (Using ntfy.sh)
#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
# (Using local mailer on Linux)
#notify_result = mail -s "%s" your_user@localhost
# (Using direct delivery via netrc)
#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 -
# (Using a custom shell script on Linux)
#notify_result = sh /usr/local/bin/snapraid-notify.sh "%s" "%l"
# (Using a custom batch script on Windows)
# NOTE! Extra outer quotes are required to prevent cmd /c from stripping
# necessary internal quotes around the path and arguments.
#notify_result = cmd /c ""C:\snapraid\notify.bat" "%s" "%l""

# Controls the filter for 'notify_result'. The notification is sent only
# if the task result is equal to or more severe than this level.
# Values: info (always), warning, error, critical. Default: error.
# Example: If set to 'error', notifications are sent for errors and
# critical failures, but NOT for successful 'info' runs.
#
# This option can only be modified via the REST API if 'net_config_full_access'
# is set to 1. Otherwise, it remains read-only for security reasons.
notify_result_level = error

# 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 for tasks like heartbeats
# or 'curl' commands 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.
#
# This option can only be modified via the REST API if 'net_config_full_access'
# is set to 1. Otherwise, it remains read-only for security reasons.
#notify_run_as_user = nobody

# If set to 1, the daemon will log a detailed list of file changes discovered
# before the sync begins.
# If this is missing or set to 0, no difference report is generated
notify_differences = 1