Merge pull request #27 from buildplan/background_restore

CHANGELOG: Restic Backup Script v0.37.2 → v0.38

## NEW FEATURES


1. BACKGROUND RESTORE MODE (--background-restore)
   ----------------------------------------------
   - NEW: Non-interactive restore that runs as a background process
   - Usage: sudo restic-backup.sh --background-restore <snapshot_id> <dest_path>
   - Features:
     * Accepts 'latest' as snapshot ID (auto-resolves to most recent snapshot)
     * Creates dedicated timestamped log files for each restore job
     * Runs in detached background process with output redirection
     * Sends notifications on completion/failure via configured channels
     * Automatically handles file ownership for /home/* paths
     * No terminal interaction required after launch
   
   - Implementation Details:
     * Uses subshell backgrounding: ( ... ) > "$restore_log" 2>&1 &
     * Log files: /tmp/restic-restore-${snapshot_id:0:8}-$(date +%s).log
     * Integrates with notification system (ntfy, Discord, Slack, Teams)
     * Runs pre-flight checks before starting background job
   
   - Use Cases:
     * Large dataset restoration without blocking terminal
     * Remote server restores over SSH
     * Long-running operations that should survive terminal disconnection


2. SYNC RESTORE MODE (--sync-restore)
   ------------------------------------
   - NEW: Non-interactive foreground restore for automation/cron
   - Usage: sudo restic-backup.sh --sync-restore <snapshot_id> <dest_path> [paths...]
   - Features:
     * Runs synchronously (blocks until completion)
     * Returns proper exit codes for scheduler/cron monitoring
     * Accepts optional specific file/directory paths to restore
     * Integrates with Healthchecks.io for success/failure pinging
     * Supports 'latest' snapshot ID resolution
     * Automatic ownership handling for user directories
   
   - Implementation Details:
     * Exit code 0 on success, 1 on failure
     * Healthchecks.io ping on completion: $HEALTHCHECKS_URL or $HEALTHCHECKS_URL/fail
     * Full logging to main log file
     * Notification support for all configured channels
   
   - Use Cases:
     * Automated backup pull for 3-2-1 backup strategy
     * Cron-scheduled regular restores to secondary servers
     * DR (Disaster Recovery) automation workflows
     * CI/CD backup restoration pipelines

Author: buildplan

README.md

@@ -24,6 +24,47 @@ This script automates encrypted, deduplicated backups of local directories to a
 
 -----
 
+## Quick Start
+
+For those familiar with setting up backup scripts, here is a fast track to get you up and running.
+
+1. **Download Files:**
+
+    ```sh
+    mkdir -p /root/scripts/backup && cd /root/scripts/backup
+    curl -LO https://raw.githubusercontent.com/buildplan/restic-backup-script/refs/heads/main/restic-backup.sh
+    curl -LO https://raw.githubusercontent.com/buildplan/restic-backup-script/refs/heads/main/restic-backup.conf
+    curl -LO https://raw.githubusercontent.com/buildplan/restic-backup-script/refs/heads/main/restic-excludes.txt
+    chmod +x restic-backup.sh
+    ```
+
+2. **Edit Configuration:**
+    - Modify `restic-backup.conf` with your repository details, source paths, and password file location.
+    - Set secure permissions: `chmod 600 restic-backup.conf`.
+
+3. **Create Password & Initialize:**
+
+    ```sh
+    # Create the password file (use a strong password)
+    echo 'your-very-secure-password' | sudo tee /root/.restic-password
+    sudo chmod 400 /root/.restic-password
+
+    # Initialize the remote repository
+    sudo ./restic-backup.sh --init
+    ```
+
+4. **Run First Backup & Schedule:**
+
+    ```sh
+    # Run your first backup with verbose output
+    sudo ./restic-backup.sh --verbose
+
+    # Set up a recurring schedule with the interactive wizard
+    sudo ./restic-backup.sh --install-scheduler
+    ```
+
+-----
+
 ## Usage
 
 ### Run Modes
@@ -38,6 +79,8 @@ This script automates encrypted, deduplicated backups of local directories to a
 - `sudo ./restic-backup.sh --install-scheduler` - Run the interactive wizard to set up an automated backup schedule (systemd/cron).
 - `sudo ./restic-backup.sh --uninstall-scheduler` - Remove a schedule created by the wizard.
 - `sudo ./restic-backup.sh --restore` - Start the interactive restore wizard.
+- `sudo ./restic-backup.sh --background-restore <snapshot> <dest>` - Restore in the background (non-blocking).
+- `sudo ./restic-backup.sh --sync-restore <snapshot> <dest>` - Restore in a cronjob (helpful for 3-2-1 backup strategy).
 - `sudo ./restic-backup.sh --forget` - Manually apply the retention policy and prune old data.
 - `sudo ./restic-backup.sh --diff` - Show a summary of changes between the last two snapshots.
 - `sudo ./restic-backup.sh --stats` - Display repository size, file counts, and stats.
@@ -49,6 +92,75 @@ This script automates encrypted, deduplicated backups of local directories to a
 
 > *Default log location: `/var/log/restic-backup.log`*
 
+-----
+
+### Restoring Data
+
+Script provides three distinct modes for restoring data, each designed for a different scenario.
+
+#### 1. Interactive Restore (`--restore`)
+
+This is an interactive wizard for guided restores. It is the best option when you are at the terminal and need to find and recover specific files or directories.
+
+- **Best for**: Visually finding and restoring specific files or small directories.
+- **Process**:
+      - Lists available snapshots for you to choose from.
+      - Asks for a destination path.
+      - Performs a "dry run" to show you what will be restored before making any changes.
+      - Requires your confirmation before proceeding with the actual restore.
+
+**Usage:**
+
+```sh
+sudo ./restic-backup.sh --restore
+```
+
+#### 2. Background Restore (`--background-restore`)
+
+This mode is designed for restoring large amounts of data (e.g., a full server recovery) without needing to keep your terminal session active.
+
+- **Best for**: Large, time-consuming restores or recovering data over a slow network connection.
+- **How it works**:
+  - This command is **non-interactive**. You must provide the snapshot ID and destination path as arguments directly on the command line.
+  - The restore job is launched in the background, immediately freeing up terminal.
+  - All output is saved to a log file in `/tmp/`.
+  - A success or failure notification (via ntfy, Discord, etc.) upon completion.
+
+**Usage:**
+
+```sh
+# Restore the latest snapshot to a specific directory in the background
+sudo ./restic-backup.sh --background-restore latest /mnt/disaster-recovery
+
+# Restore a specific snapshot by its ID
+sudo ./restic-backup.sh --background-restore a1b2c3d4 /mnt/disaster-recovery
+```
+
+#### 3. Synchronous Restore (`--sync-restore`)
+
+This mode runs the restore in the foreground and waits for it to complete before exiting. It's a reliable, non-interactive way to create a complete, consistent copy of backup data.
+
+- **Best for**: Creating a secondary copy of backup (for example, via a cron job) on another server (for a 3-2-1 strategy) or for use in any automation where subsequent steps depend on the restore being finished.
+- **How it works**:
+  - This command is **non-interactive** and requires the snapshot ID and destination path as command-line arguments.
+  - It runs as a synchronous (blocking) process. When a cron job executes the command, the job itself will not finish until the restore is 100% complete.
+  - This guarantees the data copy is finished before any other commands are run or the cron job is marked as complete.
+
+**Usage:**
+
+```sh
+# On a second server, pull a full copy of the latest backup
+sudo ./restic-backup.sh --sync-restore latest /mnt/local-backup-copy
+
+# On your secondary server, run a sync-restore every day at 5:00 AM.
+0 5 * * * /path/to/your/script/restic-backup.sh --sync-restore latest /path/to/local/restore/copy >> /var/log/restic-restore.log 2>&1
+
+# Can also be used in a script to ensure a process runs only after a restore
+sudo ./restic-backup.sh --sync-restore latest /srv/app/data && systemctl restart my-app
+```
+
+-----
+
 #### Diagnostics & Error Codes
 
 The script uses specific exit codes for different failures to help with debugging automated runs.
@@ -115,8 +227,11 @@ uname -m
 
 ```sh
 # Download the latest binary for your architecture from the Restic GitHub page
-# Example 0.18.0 is latest as of Aug,2025 for amd64:
-curl -LO https://github.com/restic/restic/releases/download/v0.18.0/restic_0.18.0_linux_amd64.bz2
+# Go to the Restic GitHub releases page to find the URL for the latest version:
+# https://github.com/restic/restic/releases
+
+# Download the latest binary for your architecture (replace URL with the one you found)
+curl -LO <URL_of_latest_restic_linux_amd64.bz2>
 ```
 
 ```sh
@@ -126,6 +241,8 @@ chmod +x restic_*
 sudo mv restic_* /usr/local/bin/restic
 ```
 
+-----
+
 #### Package Breakdown
 
 | Package       | Required For                                                                                                         |
@@ -183,6 +300,8 @@ The most reliable way for the script to connect to a remote server is via an SSH
     sudo ssh storagebox pwd
     ```
 
+-----
+
 ### 3. Place and Configure Files
 
 1. Create your script directory:
@@ -287,6 +406,8 @@ Before the first backup, you need to create the repository password file and ini
     sudo ./restic-backup.sh --init
     ```
 
+-----
+
 ### 5. Set up an Automated Schedule (Recommended)
 
 The easiest and most reliable way to schedule your backups is to use the script's built-in interactive wizard. It will guide you through creating and enabling either a modern `systemd timer` (recommended) or a traditional `cron job`.
@@ -334,6 +455,6 @@ To run the backup automatically, edit the root crontab.
 
     ```
 
-    *For pune job in your `restic-backup.conf`, set `PRUNE_AFTER_FORGET=true`.*  
+    *For prune job in your `restic-backup.conf`, set `PRUNE_AFTER_FORGET=true`.*  
     *For more details on how forget flag work, see the [official Restic documentation on removing snapshots](https://restic.readthedocs.io/en/stable/060_forget.html).*  
     *Redirecting output to `/dev/null` is recommended, as the script handles its own logging and notifications.*