Skip to content

Storage Setup

Jump to bottom
Marc Pope edited this page Mar 4, 2026 · 3 revisions

Storage Setup

BBS supports multiple storage locations, allowing you to spread repositories across different disks, mount points, or network storage. Each repository can be assigned to a specific storage location when it is created.

Overview

By default, BBS stores all local repositories in a single directory (typically /var/bbs/home). With multiple storage locations, you can:

  • Use multiple disks: Spread repositories across different physical drives
  • Add NFS or network storage: Mount remote filesystems and use them for borg repositories
  • Separate clients by disk: Put high-priority clients on fast SSD storage and archival clients on slower, larger drives
  • Scale beyond a single disk: When one disk fills up, add another location without migrating existing repos

Storage locations only apply to local repositories. Remote SSH repositories (rsync.net, BorgBase, etc.) are stored on the remote host and do not use storage locations. See Remote Storage for remote setup.

How It Works

Each storage location defines a filesystem path where BBS can create borg repositories. When creating a new local repository, you choose which storage location to use. The repository is then created at:

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

The default storage location (/var/bbs/home) is where agent SSH home directories live. Non-default locations are used for additional repository storage only — agent home directories always remain on the default location.

Agents connect to repositories over SSH. For repositories on non-default storage locations, BBS uses absolute SSH paths and configures bbs-ssh-gate to allow borg access to the additional paths.

Managing Storage Locations

Viewing Locations

Navigate to Storage in the sidebar (admin only). This page shows:

  • Local Storage: All configured storage locations with disk usage, repo counts, and management options
  • Remote Storage (SSH): Configured remote SSH hosts (managed in Settings)
  • S3 Offsite Sync: Global S3 configuration status (managed in Settings)

Adding a Storage Location

  1. Go to Storage in the sidebar
  2. Click Add Location
  3. Fill in:
    • Label: A descriptive name (e.g., "SSD Array", "NFS Backup Volume", "Secondary Disk")
    • Path: The absolute filesystem path (e.g., /mnt/storage2). This directory must exist and be accessible.
    • Default: Check this to make it the default location for new repositories. Only one location can be the default.
  4. Click Create

Editing a Location

  1. Click the three-dot menu on a location card
  2. Click Edit
  3. Modify the label, path, or default setting
  4. Click Save

Note: You cannot change the path of a location that has repositories. Delete or move the repositories first.

Deleting a Location

  1. Click the three-dot menu on a location card
  2. Click Delete

Deletion is blocked if:

  • The location is the default (change the default first)
  • Any repositories exist on the location (delete or move them first)

Creating a Repository on a Specific Location

  1. Go to a client's detail page
  2. Click Add Repository
  3. Select Local Storage
  4. If more than one storage location exists, a Storage Location dropdown appears. Select the desired location.
  5. Enter the repository name and encryption settings
  6. Click Create Repository

If only one storage location exists, the dropdown is hidden and the default location is used automatically.

Setup: Adding a Second Local Disk

Bare Metal / VM

  1. Mount the disk on the server:

    # Identify the disk
lsblk

# Create filesystem if needed
mkfs.ext4 /dev/sdb1

# Create mount point and mount
mkdir -p /mnt/disk2
mount /dev/sdb1 /mnt/disk2

# Add to /etc/fstab for persistence across reboots
echo "/dev/sdb1  /mnt/disk2  ext4  defaults  0  2" >> /etc/fstab

  2. Add the storage location in BBS:

    • Go to Storage in the sidebar
    • Click Add Location
    • Label: Secondary Disk (or whatever you prefer)
    • Path: /mnt/disk2
    • Click Create

  3. Create repositories on the new disk:

    • Go to any client, click Add Repository
    • Select the new storage location from the dropdown

Docker

  1. Mount the disk on the Docker host (same as above).

  2. Add the volume mount to docker-compose.yml:

    services:
  bbs:
    volumes:
      - /var/bbs/home:/var/bbs/home        # existing default volume
      - /mnt/disk2:/mnt/disk2              # new storage location

    The left side is the host path, the right side is the path inside the container. They must match.

  3. Restart the container:

    docker compose up -d

  4. Add the storage location in BBS (same as bare metal — Storage > Add Location > path /mnt/disk2).

Setup: NFS Network Storage

NFS allows you to store borg repositories on a remote file server (NAS, SAN, or another Linux machine). This is the most common way to add large, expandable storage to BBS.

Requirements

  • The NFS server must be accessible from the BBS server over the network
  • The NFS share must be configured to allow full read/write access from the BBS server
  • Network latency should be low (same LAN recommended)

Step 1: Configure the NFS Server

The NFS server must allow the BBS server to write files as any user. The exact configuration depends on your NFS server type.

Synology NAS

  1. Enable NFS: Go to Control Panel > File Services > NFS and check Enable NFS service

  2. Create a shared folder for BBS (e.g., bbs-storage):

    • Go to Control Panel > Shared Folder > Create
    • Name: bbs-storage
    • Leave all other settings as defaults

  3. Add an NFS permission rule:

    • Go to Control Panel > Shared Folder > select bbs-storage > click Edit
    • Go to the NFS Permissions tab
    • Click Create and configure:
      • Hostname or IP: Enter the BBS server's IP address (e.g., 192.168.1.50) or subnet (e.g., 192.168.1.0/24)
      • Privilege: Read/Write
      • Squash: Map all users to admin (this is critical — see note below)
      • Security: sys
      • Check Allow connections from non-privileged ports (required for Docker and some Linux clients)
      • Check Allow users to access mounted subfolders
    • Click OK, then Save

Important

The Squash setting must be "Map all users to admin". BBS creates multiple Unix users (one per client) with different UIDs. These UIDs do not exist on the Synology. "Map all users to admin" maps all NFS operations to the Synology admin user, which has full access to the shared folder. Other squash options will cause "Permission denied" errors.

TrueNAS / FreeNAS

  1. Go to Sharing > Unix Shares (NFS) > Add
  2. Select the dataset path
  3. Under Advanced Options:
    • Mapall User: root
    • Mapall Group: wheel
  4. Under Networks, add the BBS server's IP or subnet
  5. Save

Generic Linux NFS Server

Edit /etc/exports:

/srv/bbs-storage  192.168.1.50(rw,sync,no_subtree_check,no_root_squash)

Replace 192.168.1.50 with the BBS server's IP. Then apply:

exportfs -ra

Security note: no_root_squash allows the BBS server's root user to write as root on the NFS share. Restrict access to the BBS server's IP only.

Step 2: Mount the NFS Share on the BBS Server

Bare Metal / VM

# Install NFS client
apt install nfs-common

# Create mount point
mkdir -p /mnt/nfs-backup

# Mount (replace with your NFS server IP and export path)
mount -t nfs 192.168.1.100:/volume1/bbs-storage /mnt/nfs-backup

# Verify it works
touch /mnt/nfs-backup/test && rm /mnt/nfs-backup/test && echo "Mount OK"

# Add to /etc/fstab for persistence
echo "192.168.1.100:/volume1/bbs-storage  /mnt/nfs-backup  nfs  defaults,_netdev  0  0" >> /etc/fstab

Docker

For Docker, you have two options:

Option A: Docker NFS volume (recommended)

Add to your docker-compose.yml:

services:
  bbs:
    volumes:
      - nfs-storage:/mnt/nfs-backup

volumes:
  nfs-storage:
    driver: local
    driver_opts:
      type: nfs
      o: addr=192.168.1.100,rw,nfsvers=3,nolock
      device: ":/volume1/bbs-storage"

Replace 192.168.1.100 and /volume1/bbs-storage with your NFS server IP and export path.

Option B: Host mount (bind mount into container)

Mount the NFS share on the Docker host first, then bind-mount it:

services:
  bbs:
    volumes:
      - /mnt/nfs-backup:/mnt/nfs-backup

Option A is simpler (Docker manages the mount). Option B gives you more control over mount options.

Restart the container after changing docker-compose.yml:

docker compose up -d

Step 3: Add the Storage Location in BBS

  1. Go to Storage in the sidebar
  2. Click Add Location
  3. Label: NFS Backup Volume (or whatever you prefer)
  4. Path: /mnt/nfs-backup (must match the mount point inside the container for Docker)
  5. Click Create

Step 4: Create Repositories

Go to any client's detail page, click Add Repository, select the NFS storage location, and create the repository. BBS will initialize the borg repository on the NFS share automatically.

NFS Troubleshooting

"Permission denied" when creating a repository

Cause: The NFS server is blocking write access from the BBS server's users.

Fix: Check your NFS server's squash/mapping settings:

  • Synology: Set Squash to "Map all users to admin" on the NFS permission rule
  • TrueNAS: Set Mapall User to root
  • Linux: Add no_root_squash to the export options in /etc/exports

Also ensure the NFS permission rule includes the correct IP address of the BBS server.

"Permission denied" on Synology despite correct settings

If you've changed squash settings and still get errors, old files created under a previous squash setting may have incompatible ownership. Delete the contents of the shared folder on the Synology (via File Station or SSH) and retry from BBS.

For Synology, also verify:

  • Allow connections from non-privileged ports is checked (required for Docker)
  • Allow users to access mounted subfolders is checked
  • The shared folder Permission tab grants the admin user Read & Write access

NFS mount times out or fails

# Test basic connectivity
ping 192.168.1.100

# Test NFS port (2049)
nc -zv 192.168.1.100 2049

# Try mounting with verbose output
mount -t nfs -v 192.168.1.100:/volume1/bbs-storage /mnt/nfs-backup

Check firewall rules on both the NFS server and the BBS server. NFS requires ports 111 (rpcbind) and 2049 (nfsd).

Stale file locks after network interruption

If NFS connectivity is lost during a backup, borg may leave stale lock files. Use Break Lock on the repository detail page in BBS to clear them.

Best Practices

  • Keep the default location on fast local storage for the best backup and restore performance
  • Use NFS/additional locations for overflow or archival storage when local disk space runs low
  • Label locations clearly so operators know which physical disk or mount they refer to
  • Monitor disk usage on the Storage page — each location card shows used/free space
  • Use the same LAN for NFS connections — avoid routing NFS over WAN or VPN links
  • Test a full backup and restore on NFS storage before relying on it for production
  • Add /etc/fstab entries (or Docker volume config) so NFS mounts survive reboots

Next: Repositories | Remote-Storage | S3-Offsite-Sync

📖 User Manual

Getting Started

Using BBS

Monitoring

Administration

Reference

Clone this wiki locally