Repositories

Repositories

A repository is a BorgBackup storage location that holds deduplicated, compressed backup archives. Each repository belongs to a specific client and contains one or more backup archives (recovery points).

Repositories can be stored in two locations:

• Local: On the BBS server's filesystem (default)
• Remote SSH: On a remote SSH host like rsync.net, BorgBase, or Hetzner Storage Box (see Remote Storage)

What is a Repository?

BorgBackup repositories provide:

• Deduplication: Only unique data blocks are stored, dramatically reducing storage requirements
• Compression: Data is compressed using LZ4, zlib, or zstd algorithms
• Encryption: Strong AES-256 encryption with authenticated encryption modes
• Incremental backups: Only changed data is transferred and stored
• Atomic transactions: Backups are either complete or not recorded (no partial backups)

Each client can have multiple repositories, allowing you to organize backups by purpose (e.g., "System Files", "Databases", "User Data").

Creating a Repository

To create a new repository:

1. Navigate to the client detail page
2. Click the Repositories tab
3. Click Create Repository
4. Configure the repository settings

Repository Settings

Storage Type

Choose where the repository will be stored:

• Local (this server): Repository is created on the BBS server's local disk. This is the default.
• Remote SSH: Repository is created on a remote SSH host. This option only appears if you have configured at least one remote host in Settings → Remote Storage.

When Remote SSH is selected, a Remote Host dropdown appears where you select the target host.

Name

A descriptive name for the repository (e.g., "System Backup", "Database Archives", "Web Content").

The repository name is used in the storage path, so choose a name that is:

• Descriptive and meaningful
• Filesystem-safe (avoid special characters)
• Unique within the client

Encryption Mode

BBS supports three BorgBackup encryption modes:

repokey-blake2 (Recommended)

• Repository is encrypted with AES-256
• Encryption key is stored inside the repository
• Protected by a passphrase
• Best for most use cases

keyfile-blake2

• Repository is encrypted with AES-256
• Encryption key is stored separately from the repository
• Protected by a passphrase
• Use when you want the key stored outside the repository for additional security

none

• No encryption
• NOT recommended except for non-sensitive data in trusted environments

For production use, always choose repokey-blake2 unless you have specific requirements for separate key storage.

Passphrase

For encrypted repositories, you must provide a passphrase:

• Must be strong (recommended: 20+ characters, mix of letters, numbers, symbols)
• BBS encrypts the passphrase using the application's APP_KEY before storing it in the database
• The agent uses this passphrase automatically for all borg operations
• Important: If you lose both the passphrase AND the BBS database, your backups cannot be recovered

Best Practice: Export and securely store the repository key and passphrase in a password manager or secure vault, separate from the BBS server.

Repository Storage

Local Repositories

Local repositories are stored on the BBS server filesystem at:

{storage_location_path}/{agent_id}/{repo_name}/

Where:

• {storage_location_path} is the path of the assigned storage location (default: /var/bbs/home). See Storage Setup for configuring multiple storage locations.
• {agent_id} is the unique numeric ID of the client
• {repo_name} is the repository name you specified

When creating a local repository, you can choose which storage location to use if multiple locations are configured. This allows you to spread repositories across different disks, NFS mounts, or other storage backends.

Remote SSH Repositories

Remote SSH repositories are stored on an external SSH host at:

ssh://user@host:port/base_path/repo_name

No data is stored on the BBS server. See Remote Storage for full setup and provider guides.

SSH Access and Security

Each client has a dedicated Unix user account on the BBS server (named bbs-{agent-id}). This user:

• Is restricted to execute ONLY borg serve commands via SSH forced commands
• Cannot access any files outside its own repositories
• Cannot execute shell commands or access other clients' data
• Uses SSH key authentication (no password login)

This security model ensures complete isolation between clients, even though they share the same physical server.

Monitoring Repositories

The Repositories tab on the client detail page displays key metrics for each repository:

• Size: Total storage used (after deduplication and compression)
• Archives: Number of backup archives (recovery points)
• Last Backup: Timestamp of the most recent successful backup
• Oldest Archive: Date of the oldest retained backup

These metrics are updated automatically after each backup, prune, or compact operation.

---

Repository Detail Page

Click on any repository to view its detail page. The detail page shows:

Header Statistics

• Size — Total repository size on disk
• Archives — Number of archives in the repository
• Oldest — Date of the oldest archive
• Latest — Relative time since the newest archive (e.g., "2 hours ago")
• Active Job — Badge shown if a job is currently running on this repository

Repository Info

• Encryption — Encryption method used
• Borg Version (created) — Version of Borg that initialized the repository
• Borg Version (last used) — Most recent Borg version used
• Created — Repository creation timestamp
• Backup Plans — Number of plans using this repository

Recent Jobs

A table of the most recent jobs for this repository, showing time, type, status, and duration. Click any job to view its detail page.

---

Repository Maintenance

The repository detail page provides four maintenance operations. All operations are queued as jobs and can be monitored on the Queue page. Maintenance buttons are disabled while a job is actively running on the repository.

Check Repository

Verifies repository integrity by checking all archives for corruption or data errors. Safe to run at any time.

1. Open the repository detail page
2. Click Run Check
3. Monitor the job on the Queue page

When to use: Run periodically (monthly) or after any suspected disk issues. Check reports whether the repository and all archives are intact.

Compact Repository

Reclaims disk space by removing unused data chunks left behind after pruning archives.

1. Open the repository detail page
2. Click Run Compact
3. Monitor the job on the Queue page

When to use: After heavy pruning, or to free up disk space. BBS also runs compact automatically every Saturday at 2:00 AM if auto-compact is enabled in Settings > General.

Repair Repository

Attempts to fix repository errors found by a check operation. Use with caution — repair may delete damaged data to restore consistency.

1. Open the repository detail page
2. Click Run Repair
3. Confirm the dangerous action
4. Monitor the job on the Queue page

When to use: Only after a check operation reports errors. Do not use as a preventive measure.

Break Lock

Forcibly removes stale locks from interrupted operations.

1. Open the repository detail page
2. Click Break Lock
3. Confirm the dangerous action

When to use: Only if you're certain no backup operations are currently running and a previous operation left a stale lock. Borg locks prevent concurrent access — breaking a lock while an operation is in progress can corrupt the repository.

---

S3 Offsite Sync

Each repository can be individually configured to mirror to S3-compatible storage for offsite protection.

Enabling S3 Sync

1. Open the repository detail page
2. In the S3 Offsite Mirror section, select an S3 configuration from the dropdown
3. Click Enable S3 Sync

S3 configurations are created on the Plugins page or in Settings > S3 Backups. Once enabled, the repository will automatically sync to S3 after each prune operation.

Viewing Sync Status

When S3 sync is enabled, the repository detail page shows:

• The S3 configuration being used
• The timestamp of the last successful sync (or "Never" if not yet synced)

Disabling S3 Sync

Click Disable on the S3 Offsite Mirror section. This stops future syncs but does not delete data already in S3.

Restoring from S3

If local repository data is lost or corrupted, you can restore from S3. Two restore modes are available:

Replace Mode

Downloads data from S3 and overwrites the local repository. Use this when the local copy is damaged.

1. Click Restore (replace) in the S3 Offsite Mirror section
2. Confirm the dangerous action
3. Monitor the restore job on the Queue page

Copy Mode

Downloads data from S3 into a new repository. Use this to recover data without disturbing the existing local copy.

1. Click Restore (copy)
2. Enter a name for the new repository (defaults to {name}-copy)
3. Confirm the action
4. Monitor the restore job on the Queue page

Orphaned Repository Recovery

If a repository exists in S3 but not locally (e.g., after a server rebuild), BBS can detect these "orphaned" repositories on the client's Repos tab and offer to restore them.

See S3-Offsite-Sync for full S3 setup, configuration, and disaster recovery documentation.

---

Deleting a Repository

Warning: Deleting a repository permanently destroys all backup archives and data. This cannot be undone.

To delete a repository (admin only):

1. Open the repository detail page
2. Scroll to the Danger Zone section
3. Click Delete Repository
4. If S3 sync is enabled, optionally check "Also delete from S3 offsite storage"
5. Confirm the deletion

Deletion is blocked if:

• Any backup plans still reference this repository (remove or reassign them first)
• An active job is running on this repository

---

Repository Best Practices

Naming Conventions

Use clear, descriptive names that indicate the backup content:

• Good: "web-server-files", "mysql-databases", "user-home-directories"
• Avoid: "backup1", "repo", "test"

Encryption

Always use encryption for production data. Use repokey-blake2 unless you have specific requirements for keyfile-blake2.

Passphrase Management

• Use a strong, unique passphrase for each repository
• Store passphrases in a secure password manager
• Export and back up repository keys separately from BBS
• Never use the same passphrase for multiple repositories

Repository Organization

• Create separate repositories for different data types (files, databases, etc.)
• Use separate repositories for different retention requirements
• Consider creating separate repositories for critical vs. non-critical data

Maintenance Schedule

• Check: Run monthly, or after any suspected disk issues
• Compact: Runs automatically weekly (Saturday 2 AM). Manual runs after heavy pruning.
• Repair: Only after check reports errors
• Break Lock: Only if a stale lock is confirmed

Monitoring

• Regularly check repository size to ensure adequate disk space
• Monitor archive counts to verify retention policies are working correctly
• Review the "Last Backup" timestamp to catch missed or failed backups
• Enable Notifications for Storage Low alerts

---

Next: Backup-Plans | Restoring-Files | Remote-Storage | S3-Offsite-Sync