Restoring Files

Restoring Files

The BBS restore interface allows you to browse backup archives, search for files, and restore data to client machines or download files directly to your browser.

Accessing the Restore Interface

To access the restore interface:

1. Navigate to the client detail page
2. Click the Restore tab

The restore interface displays all available recovery points (backup archives) for the client's repositories.

Screenshot: Restore tab showing list of backup archives

Browsing Archives

The restore interface lists all backup archives across all repositories for the selected client. Each archive entry displays:

• Archive name: Typically formatted as {hostname}-{timestamp}
• Repository: Which repository contains this archive
• Date/Time: When the backup was created
• File count: Total number of files in the archive
• Size: Total size of the backup (original, before deduplication)
• Duration: How long the backup took to complete

Archives are sorted by date, with the most recent backups at the top.

Viewing Archive Contents

To browse the files in an archive:

1. Click on the archive name or Browse Files button
2. The file catalog browser opens

Screenshot: File browser showing directory tree with lazy-loading folders

The file browser provides:

• Tree view: Hierarchical display of directories and files
• Lazy loading: Directories load their contents on-demand when expanded (improves performance for large archives)
• File metadata: Size, modification time, permissions for each file
• Breadcrumb navigation: Quick navigation back to parent directories
• Checkbox selection: Select individual files or entire directories

Navigating the File Tree

• Click a folder to expand/collapse it
• Click breadcrumbs at the top to jump to parent directories
• Use checkboxes to select files and folders for restore
• Shift+Click to select a range of files (if supported)

File Metadata

For each file, the browser displays:

• Name: Filename
• Size: File size in human-readable format (KB, MB, GB)
• Modified: Last modification timestamp from the original backup
• Mode: Unix permissions (e.g., -rw-r--r--, drwxr-xr-x)
• Owner: User and group ownership (if preserved in backup)

Searching Within an Archive

To find specific files within a single archive:

1. Open the archive in the file browser
2. Use the Search box at the top
3. Enter a filename or pattern (e.g., nginx.conf, *.log, database.sql)
4. Press Enter

The search filters the tree view to show only matching files and their parent directories.

Search tips:

• Search is case-insensitive by default
• Use wildcards: * matches any characters, ? matches single character
• Search looks at the full path, not just filename
• Leave search empty and press Enter to reset the view

Global File Search

To search for a file across ALL archives in ALL repositories:

1. Click the Global Search button on the Restore tab
2. Enter a filename or pattern
3. Click Search

The global search returns a list of matches showing:

• Filename and path
• Archive name containing the file
• Repository
• Backup date
• File size and modification time

This is useful when you:

• Don't know which backup contains the file you need
• Want to find when a file was last backed up
• Need to compare versions of a file across multiple backups

Click on any result to open that archive directly to the file's location.

Restore Options

BBS provides three restore methods:

1. Restore to Original Location

Restores files to their original paths on the client machine.

How it works:

1. Select files/directories in the file browser
2. Click Restore to Original Location
3. Confirm the operation
4. BBS queues a restore job
5. Agent executes borg extract to restore files to their original paths

Important notes:

• Overwrites existing files without prompting
• Preserves permissions, ownership, and timestamps from the backup
• Requires root/sudo permissions on the client if restoring system files
• Best for disaster recovery scenarios

Use cases:

• Recovering accidentally deleted files
• Restoring after system failure
• Rolling back configuration changes

2. Restore to Alternate Directory

Restores files to a different path on the client machine.

How it works:

1. Select files/directories in the file browser
2. Click Restore to Alternate Directory
3. Enter the target path (e.g., /tmp/restore, /home/user/recovered-files)
4. Click Confirm
5. BBS queues a restore job with the alternate path
6. Agent extracts files to the specified directory

Important notes:

• Original directory structure is preserved under the alternate path
• Example: restoring /etc/nginx/nginx.conf to /tmp/restore creates /tmp/restore/etc/nginx/nginx.conf
• Does NOT overwrite files at original locations
• Target directory is created if it doesn't exist

Use cases:

• Reviewing files before restoring to original location
• Extracting specific files for inspection
• Recovering data for comparison with current versions

3. Download as tar.gz

Downloads selected files directly to your browser as a compressed tar archive.

How it works:

1. Select files/directories in the file browser
2. Click Download as tar.gz
3. BBS creates a temporary restore job
4. Agent extracts the selected files and creates a tar.gz archive
5. Archive is uploaded to the BBS server
6. Your browser downloads the archive
7. Temporary archive is deleted after download

Important notes:

• Files are NOT restored to the client machine
• Download happens through your browser (may be slow for large selections)
• Preserves directory structure within the archive
• Useful for restoring to a different machine or inspecting files offline

Use cases:

• Restoring files to a different computer
• Downloading backups for analysis on your workstation
• Creating a local copy without modifying the client machine

Size limits:

• Practical limit depends on available disk space on BBS server and browser download capabilities
• For very large restores (>10GB), use "Restore to Alternate Directory" instead

The Restore Process

When you initiate a restore (options 1 or 2), the following occurs:

1. Job Creation

• BBS creates a restore job in the backup_jobs table with type restore
• Job includes the archive name, repository, file selections, and target path (if alternate)

2. Job Queued

• Job status is set to queued
• Job appears in the client's job queue

3. Agent Pickup

• On the next poll cycle (typically within 30 seconds), the agent receives the restore job
• Agent sets job status to running

4. Borg Extract

• Agent executes borg extract with the specified archive and file patterns
• Files are extracted to the target location (original or alternate path)
• Permissions, ownership, and timestamps are restored

5. Completion

• Agent marks the job as completed (or failed if errors occurred)
• Job duration and restored file count are recorded
• User is notified (if email notifications are enabled)

Typical Duration:

Restore duration depends on:

• Number of files being restored
• Total size of data
• Network speed (if repository is remote)
• Disk I/O speed on the client machine

Small restores (few files): Seconds Large restores (thousands of files or GB of data): Minutes to hours

Monitoring Restore Jobs

To check the status of a restore job:

1. Navigate to Dashboard → Recent Activity
2. Or, navigate to the client detail page → Jobs tab (if available)

Restore jobs show:

• Status: Queued, Running, Completed, or Failed
• Progress: Percentage complete and files restored (updated during execution)
• Duration: Elapsed time
• Errors: Error messages if the job failed

Troubleshooting Restore Issues

Restore Job Stuck in "Queued"

• Cause: Agent is offline or not polling
• Solution: Check agent connectivity (see Agent-Setup#troubleshooting-agent-connectivity)

Restore Job Failed

Common causes and solutions:

"Repository not found" or "Archive not found"

• Archive may have been deleted by retention policy
• Check that the repository still exists
• Verify the archive name is correct

"Permission denied" during extract

• Target directory is not writable
• Use alternate directory restore to a path the agent user has access to
• Or, ensure agent is running as root for system file restores

"Disk full" error

• Insufficient space on client machine
• Free up disk space or choose a different target directory
• Use "Download as tar.gz" to restore to a different machine

"Passphrase incorrect" error

• Repository passphrase in BBS doesn't match the actual repository
• Update the passphrase in the repository settings
• If passphrase is lost, recovery is not possible (borg encryption is unbreakable)

Download Fails or Times Out

• Cause: Selection is too large for browser download
• Solution: Use "Restore to Alternate Directory" and then manually copy files from the client

Files Restored but Not Where Expected

• Issue: "Restore to Original Location" puts files at original paths, not where you might expect
• Solution: Use "Restore to Alternate Directory" if you want files in a specific location

Best Practices

Before Restoring

1. Verify the archive: Check the archive date to ensure it's the correct recovery point
2. Review file selection: Double-check you've selected the right files/directories
3. Test first: For critical restores, use "Restore to Alternate Directory" first to verify data integrity

During Restore

1. Monitor progress: Watch the job status for errors
2. Don't interrupt: Avoid stopping the agent or client during restore
3. Check logs: Review agent logs if issues occur

After Restore

1. Verify data: Check that restored files are complete and correct
2. Test applications: If restoring config files or databases, test that applications work correctly
3. Set permissions: If restoring as non-root, you may need to manually fix ownership

Regular Testing

• Test restores regularly: Don't wait for a disaster to test your backups
• Practice recovery procedures: Ensure your team knows how to restore data
• Document custom restore processes: If you have complex restore requirements, document them

---

Previous: Backup-Plans | Repositories