Restoring Files from Archives

Overview

Borg UI provides an intuitive interface for browsing backup archives and restoring files. With 600x faster performance through Redis caching, you can quickly navigate large backup archives and restore exactly what you need.

Quick Restore

For simple file restoration:

Navigate to Repository

Go to Repositories and select the repository containing your backups.

Browse Archives

Click the Archives tab to see all backup archives, sorted by date.Each archive shows:

Archive name (usually with timestamp)
Creation date and time
Number of files
Archive size (compressed and deduplicated)

Explore Archive Contents

Click Browse on the archive you want to restore from.The file browser displays:

Directories: Navigate through folder structure
Files: View individual files with sizes
Path breadcrumbs: Easy navigation to parent folders

Select Files to Restore

Click checkboxes next to files/folders to restore
Select individual files or entire directories
Multiple selections are supported

Directory sizes are calculated recursively, showing total space needed.

Choose Destination

Click Restore and configure:

Destination Type: Local or SSH
Destination Path: Where to restore files
Dry Run: Preview what would be restored (optional)

Start Restore

Click Start Restore to begin the operation.A restore job is created and runs in the background.

Restore Destinations

Local Restore

Restore files to the Borg UI server:

Destination Type: Local
Destination Path: /local/restore/2024-01-15

Use /local/ prefix to restore to host filesystem. This maps to the root of your host machine.

Example:

Container path: /local/home/user/restored
Host path: /home/user/restored

Remote Restore (SSH)

Restore files directly to a remote server:

Destination Type: SSH
SSH Connection: [Select from configured connections]
Destination Path: /home/user/restored-files

Restoring from SSH repository to SSH destination is not supported. This would require downloading and re-uploading all data. Restore to local first, then transfer if needed.

Supported Restore Combinations

Repository Type	Destination	Supported
Local → Local	✅ Direct extraction
Local → SSH	✅ Extract and upload
SSH → Local	✅ Download and extract
SSH → SSH	❌ Not supported

Advanced Restore Options

Dry Run Mode

Preview the restore operation without actually extracting files:

Select files to restore
Enable Dry Run checkbox
Click Start Restore
Review the preview showing:
- Files that would be extracted
- Destination paths
- Total size
- Any potential conflicts

Use dry run to verify the restore operation before committing, especially for large restores.

Partial Restore

Restore specific files or directories instead of entire archives: By Path Pattern:

# Restore all PDF files
*.pdf

# Restore specific directory
home/user/documents/

# Restore multiple patterns
*.pdf
*.docx
home/user/photos/2024/

By File Selection:

Navigate through archive browser
Select individual files or directories
Borg extracts only selected items

Restore Permissions

By default, Borg preserves:

File permissions (chmod)
Ownership (chown) - if run as root
Extended attributes
ACLs (if supported)

If restoring as non-root user, ownership restoration may fail. Files will be owned by the user running Borg UI.

Monitoring Restore Progress

Borg UI provides real-time restore progress tracking:

Progress Indicators

Files Restored: Count of extracted files
Current File: Path being processed
Progress Percentage: Overall completion
Restore Speed: Transfer rate in MB/s
Estimated Time: Remaining duration

Viewing Restore Jobs

Navigate to Restore Jobs in the sidebar
See all restore operations:
- Pending: Queued for execution
- Running: Currently extracting
- Completed: Finished successfully
- Failed: Encountered errors
- Cancelled: Manually stopped
Click a job to view:
- Detailed progress
- Source repository and archive
- Destination path
- Error logs (if failed)

Cancelling Restores

To stop a running restore:

Go to Restore Jobs
Find the running job
Click Cancel
Partial extraction is preserved

Cancelled restores leave partially extracted files. You may need to clean up the destination directory.

Archive Caching

Borg UI uses Redis to cache archive contents for 600x faster browsing:

How It Works

First Browse: Borg lists all files, Borg UI caches them in Redis
Subsequent Browses: Instant loading from cache
Cache Duration: 24 hours (configurable)
Auto-Refresh: Cache updates after new backups

Cache Benefits

Speed: Millisecond response vs. seconds for large archives
Reduced Load: No repeated Borg commands
Better UX: Instant navigation through directories

For archives with millions of files, the first browse may take 30-60 seconds. Subsequent browses are instant.

Cache Management

Caches are automatically managed, but you can manually control them: Disable Redis Caching:

services:
  borg-ui:
    environment:
      - REDIS_ENABLED=false

Adjust Cache TTL:

environment:
  - REDIS_TTL=86400  # 24 hours (default)

Restore Strategies

Full Repository Restore

Restore all files from the most recent archive:

Select the latest archive
Browse to root directory
Select the top-level directory
Choose destination path
Start restore

Full restores can take hours depending on data size and network speed.

Incremental Restore

Restore multiple versions of the same file:

Browse different archives
Restore the same file path from each
Compare versions
Keep the desired version

Example Use Case:

Accidentally deleted paragraph from document
Browse last 7 days of archives
Restore document from each day
Find version with the missing content

Point-in-Time Restore

Restore files from a specific date/time:

Identify the archive closest to target time
Browse that archive
Restore needed files
Verify timestamps match expectations

Selective Restore

Restore only specific file types or directories: Scenario: Recover all photos from last month

Browse archive from end of month
Navigate to photos directory
Select all subdirectories
Restore to staging location
Verify before moving to production

Common Restore Scenarios

Accidental File Deletion

Identify When File Was Deleted

Check recent archives to find the last one containing the file.

Browse That Archive

Navigate to the file’s original location in the archive browser.

Restore File

Select the file and restore to original or temporary location.

Verify Restoration

Check the restored file is correct and uncorrupted.

Ransomware Recovery

Stop the Attack

Disconnect affected systems from network immediately.

Identify Clean Archive

Find the last archive before ransomware infection.

Do not restore from infected archives. Verify archive dates carefully.

Restore to Clean System

Deploy fresh OS on new hardware/VM
Restore data from clean archive
Verify no malware present

Update Security

Patch systems
Change passwords
Enable MFA
Review security policies

Always restore to a quarantined environment first. Verify data integrity before moving to production.

Hardware Failure Recovery

Replace Failed Hardware

Install new drive/system with fresh OS.

Mount Backup Repository

For local repos: Mount backup drive
For remote repos: Configure SSH connection

Full Restore

Restore all files from most recent archive.

Verify System

Check critical files present
Test applications
Verify data integrity

Configuration Rollback

Browse Archives

Find archive from before configuration change.

Restore Config Files

Restore only configuration directories (e.g., /etc, /local/config).

Apply Restored Config

Review changes
Merge with current config if needed
Restart affected services

Troubleshooting

Restore Fails with Permission Denied

Problem: Cannot write to destination directory. Solution:

# On host machine
sudo chown -R 1000:1000 /path/to/restore/destination

Or restore to /data/ inside container:

Destination: /data/restored-files

Archive Browser Shows No Files

Problem: Cache is empty or corrupt. Solution:

Refresh the archive list

Clear Redis cache:

docker exec borg-ui-redis redis-cli FLUSHDB

Browse archive again to rebuild cache

Restore Speed is Slow

Possible Causes:

Remote repository: Network bandwidth limit
Large files: Compression/decompression overhead
Disk I/O: Slow destination disk

Optimizations:

Use local restore destination when possible
Restore during off-peak hours
Consider restoring to SSD instead of HDD

Partial Restore Corruption

Problem: Some files are corrupt after restore. Check Repository Integrity:

docker exec borg-ui borg check /path/to/repository

If check fails, repair may be possible:

borg check --repair /path/to/repository

Repository repair can take hours and may result in data loss. Always have multiple backup copies.

Cannot Restore to SSH Destination

Problem: SSH restore fails or hangs. Verify SSH Connection:

Test connection: SSH Connections → Test
Check storage space on remote server
Verify write permissions on destination path

Check Logs:

Navigate to restore job details
View error messages
Common issues:
- SSH key authentication failure
- Insufficient disk space
- Path doesn’t exist

Best Practices

Test Restores Regularly

Schedule periodic restore tests
Verify data integrity
Document restore procedures
Train staff on restore process

Untested backups are not backups. Restore testing should be part of your backup strategy.

Use Dry Run First

Always preview restores with dry run:

Large restores
Production systems
Unfamiliar archive layouts
When unsure about destination path

Restore to Staging First

For critical restores:

Restore to temporary/staging location
Verify data integrity
Test functionality
Move to production only after validation

Never restore directly to production without verification.

Document Recovery Procedures

Maintain runbooks for common scenarios:

Accidental deletion
Ransomware
Hardware failure
Configuration rollback

Include:

Step-by-step instructions
Required access credentials
Testing procedures
Rollback plans

Monitor Restore Jobs

Check restore job status
Review logs for warnings
Verify disk space during restore
Set up alerts for failed restores

Next Steps

Schedule Backups

Automate backups to ensure fresh restore points

Backup Verification

Set up automated backup integrity checks

Getting Started

Core Features

Configuration

Guides

Deployment

Advanced

​Overview

​Quick Restore

​Restore Destinations

​Local Restore

​Remote Restore (SSH)

​Supported Restore Combinations

​Advanced Restore Options

​Dry Run Mode

​Partial Restore

​Restore Permissions

​Monitoring Restore Progress

​Progress Indicators

​Viewing Restore Jobs

​Cancelling Restores

​Archive Caching

​How It Works

​Cache Benefits

​Cache Management

​Restore Strategies

​Full Repository Restore

​Incremental Restore

​Point-in-Time Restore

​Selective Restore

​Common Restore Scenarios

​Accidental File Deletion

​Ransomware Recovery

​Hardware Failure Recovery

​Configuration Rollback

​Troubleshooting

​Restore Fails with Permission Denied

​Archive Browser Shows No Files

​Restore Speed is Slow

​Partial Restore Corruption

​Cannot Restore to SSH Destination

​Best Practices

​Next Steps

Schedule Backups

Backup Verification

Build docs developers (and LLMs) love

Overview

Quick Restore

Restore Destinations

Local Restore

Remote Restore (SSH)

Supported Restore Combinations

Advanced Restore Options

Dry Run Mode

Partial Restore

Restore Permissions

Monitoring Restore Progress

Progress Indicators

Viewing Restore Jobs

Cancelling Restores

Archive Caching

How It Works

Cache Benefits

Cache Management

Restore Strategies

Full Repository Restore

Incremental Restore

Point-in-Time Restore

Selective Restore

Common Restore Scenarios

Accidental File Deletion

Ransomware Recovery

Hardware Failure Recovery

Configuration Rollback

Troubleshooting

Restore Fails with Permission Denied

Archive Browser Shows No Files

Restore Speed is Slow

Partial Restore Corruption

Cannot Restore to SSH Destination

Best Practices

Next Steps