BmuS Error Handling

BmuS has several mechanisms for intercepting errors and implementing countermeasures in order to successfully complete the necessary commands under certain circumstances.

BmuS follows a “Defense in Depth” strategy. It does not blindly assume that things will work; instead, it actively checks for errors at every critical stage.

Here is a detailed breakdown of the error handling mechanisms and the measures the script takes:

Robust Mounting (Network & Drives)

This is often the most fragile part of backups (NAS sleeping, Wi-Fi drops).

• Network Check (Ping):
  • Check: Before any mount attempt, the script pings the NAS_IP.
  • Action: If the NAS is unreachable, the script aborts immediately and cleanly, instead of running into a long TCP timeout (which would freeze the script for minutes).
• Mount Retry Logic:
  • Check: The mount command is executed within a loop.
  • Action: If the first attempt fails (e.g., “Device busy”), the script waits a defined time (sleep) and retries. It gives up only after reaching MAX_RETRIES (Default: 3), triggering an error message.
• “Stale Mount” Prevention:
  • Check: Before mounting, checks if the directory is already mounted (potentially in a broken state).
  • Action: Attempts a clean umount first to ensure a fresh connection.

Intelligent Resource Management (RAM)

Especially on small Raspberry Pis, RAM is scarce.

• Pre-Flight RAM Check:
  • Check: The script measures available free memory.
  • Action: If memory is below a threshold (e.g., 500 MB), the script automatically switches to “Low Memory Mode”.
  • Consequence: Instead of memory-hungry parallel processes, tasks are processed strictly sequentially, and the rsync buffer is reduced to prevent a system crash (OOM-Kill).

rsync Error Classification

rsync can complain for many reasons. BmuS distinguishes precisely:

• Copy Errors vs. Verify Errors:
  • Check: Parses rsync exit codes and logs.
  • Action: Distinguishes between “File could not be copied” (I/O Error) and “File arrived, but checksum mismatch” (Verify Error). Both are reported separately in the dashboard.
• “Vanished Files”:
  • Check: Temporary files deleted during the backup process (e.g., browser cache) often cause rsync error code 24.
  • Action: BmuS recognizes this specific code and ignores it (“Squelching”), as this is not a genuine error. The dashboard remains “Green”.

Database Resilience

A database backup can hang or be incomplete.

• Availability Check:
  • Check: Before mariadb-dump starts, checks if the SQL server is answering.
  • Action: If the DB is down, the dump attempt is skipped and an error is logged, but the file backup continues (no total abort).
• GPG Integrity:
  • Check: Verifies the GPG exit code after encryption.
  • Action: If encryption fails, the unencrypted (and thus unsafe) file is immediately deleted to ensure no plaintext data lands on the backup medium (“Fail Safe”).

Configuration Guardian (Sanity Checks)

Protects the user from “silly” mistakes in bmus.conf.

• Logic Conflicts:
  • Check: Checks for incompatible settings (e.g., Encryption + Dedup enabled simultaneously).
  • Action: Immediate abort with a clear, human-readable error message explaining why this is invalid.
• Mandatory Variables:
  • Check: Are critical paths (BACKUP_SOURCES) empty?
  • Action: Warning and abort to prevent an “empty” backup run from rotating (deleting) good old backups.

Graceful Shutdown (Trap Function)

What happens if the user hits STRG+C or power fails?

• The cleanup Trap:
  • Mechanism: Bash trap … EXIT.
  • Action: No matter how or why BmuS terminates (success, error, abort), the cleanup function is always called.
  • Result: This function reliably unmounts the NAS and encryption container and deletes temporary files (.tmp, .lock), leaving the system in a clean state.
  • If umount fails, the mount status will be checked the next time it runs, and umount and then mount will be performed.

Aggressive Network Recovery (Self-Healing)

• Mechanism: During the backup verification phase, BmuS sets a hard timeout.
• Action: If a verification process hangs (e.g., due to a zombie network connection), the script does not just abort. It actively triggers a Network Interface Restart (taking the interface down and up) to force a connection reset before retrying the verification.

Intelligent Protocol Switching (Cloud Compatibility)

• Check: When running a Cloud Backup (rclone), BmuS detects if the NAS is currently mounted via NFS.
• Action: Since NFS file locking can cause issues with rclone uploads, BmuS automatically unmounts the NFS share and temporarily remounts it using CIFS/SMB. This ensures maximum compatibility and stability for the cloud upload process without user intervention.

SD Card Protection (Local Safety)

• Check: If no NAS_IP is configured (local backup mode), BmuS checks if the BACKUP_PATH is a valid mount point.
• Action: If it detects that the path is not a mount point (which would mean writing directly to a Raspberry Pi’s SD card), it issues a loud warning. This prevents the OS partition from filling up and crashing the system due to a missing external drive.

Proactive Buffer Flushing (Batch Pauses)

• Mechanism: Between backup batches, BmuS doesn’t just wait; it issues a system sync command.
• Action: This forces the operating system to flush write buffers to the physical disk immediately. Combined with a configurable pause (BATCH_PAUSE), this allows the storage controller to “catch up” and prevents I/O saturation before the next batch begins.

Dependency Validation (System Check)

• Check: Before running, BmuS performs a dependency check (run_system_check).
• Action: BmuS verifies not just the config, but the presence of required system binaries (like rsync, cifs-utils, mysql-client). If a tool is missing, it suggests the exact apt-get install command needed to fix the environment.

Cloud Quota Detection

• Check: BmuS parses the rclone log for specific error strings like “quota exceeded” or “disk full”.
• Action: BmuS distinguishes these from generic upload errors, allowing the Dashboard to report a specific ERROR_SPACE status rather than a generic failure.

Reporting as the Last Line of Defense

If the script cannot fix the error itself, the human must be informed.

• Email with Log: Attaches the log file on critical errors.
• Dashboard Signaling: The dashboard switches the status banner to RED and lists errors prominently at the top so they aren’t overlooked.

In summary, BmuS is not just a “copy script,” but a monitored process that actively attempts to resolve issues itself (Retries, Low-Mem-Mode) or, if that fails, limits the damage (Clean Unmount, Fail Safe).