Backblaze B2 Storage

The Backblaze B2 storage backend provides cost-effective cloud storage with predictable pricing. B2 is ideal for long-term archival and backup use cases.

Configuration

Required Settings

string

required

Full store URI, e.g. b2:my-backup-bucket or b2:my-backup-bucket/prefix/

Authentication

Credentials can be provided as CLI flags, environment variables, or (recommended) secret references stored in profiles.yaml:

-b2-key-id / -b2-app-key flags, or the B2_KEY_ID / B2_APP_KEY environment variables
-b2-key-id-secret / -b2-app-key-secret flags on cloudstic store new, which store a secret reference (env://, keychain://, wincred://, secret-service://) in profiles.yaml instead of a raw value

string

required

Backblaze application key ID

string

required

Backblaze application key

These credentials are obtained from the Backblaze B2 dashboard.

Prefer cloudstic store new -b2-key-id-secret env://B2_KEY_ID -b2-app-key-secret keychain://cloudstic/prod/b2-app-key over raw flags so profiles.yaml never stores secret values directly. See Secret references.

Examples

Basic Setup
With Prefix
CI/CD

# Set B2 credentials
export B2_KEY_ID=<your-key-id>
export B2_APP_KEY=<your-app-key>

# Initialize repository
cloudstic init -store b2:my-backup-bucket

# Backup
cloudstic backup -source local:~/Documents

Or pass credentials directly as flags instead of environment variables:

cloudstic init -store b2:my-backup-bucket \
  -b2-key-id <your-key-id> \
  -b2-app-key <your-app-key>

# Use a prefix to organize multiple repositories
export B2_KEY_ID=<your-key-id>
export B2_APP_KEY=<your-app-key>

# Laptop backups
cloudstic init -store b2:my-backup-bucket/laptop/

# Server backups (different prefix)
cloudstic init -store b2:my-backup-bucket/server/

# GitHub Actions example
name: Backup to B2
on:
  schedule:
    - cron: '0 2 * * *'  # Daily at 2 AM

jobs:
  backup:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3

      - name: Install Cloudstic
        run: |
          curl -L https://github.com/cloudstic/cli/releases/latest/download/cloudstic-linux-amd64 -o cloudstic
          chmod +x cloudstic
          sudo mv cloudstic /usr/local/bin/

      - name: Backup
        env:
          B2_KEY_ID: ${{ secrets.B2_KEY_ID }}
          B2_APP_KEY: ${{ secrets.B2_APP_KEY }}
          CLOUDSTIC_PASSWORD: ${{ secrets.BACKUP_PASSWORD }}
        run: |
          cloudstic backup \
            -store b2:github-backups \
            -source local:.

Getting B2 Credentials

Create a Bucket

Log in to your Backblaze account
Navigate to “B2 Cloud Storage” → “Buckets”
Click “Create a Bucket”
Choose:
- Bucket name: my-backup-bucket
- Files in bucket: Private (recommended)
- Encryption: Server-Side Encryption (optional, Cloudstic encrypts client-side)
Click “Create a Bucket”

Generate Application Keys

Navigate to “App Keys” in the B2 dashboard
Click “Add a New Application Key”
Configure:
- Name: cloudstic-backup
- Allow access to: Specific bucket → select your bucket
- Type of access: Read and Write
Click “Create New Key”
Save the key immediately: it’s only shown once!

The application key is only shown once. Save it securely before leaving the page.

Features

Streaming Uploads

The B2 store uses the Blazer library for efficient uploads:

Streaming writes: No need to buffer entire files in memory
Automatic retries: Handles transient network errors
Parallel uploads: Multiple chunks uploaded concurrently

Operation Timeouts

All B2 operations have a 5-minute timeout to handle network issues gracefully:

const b2OpTimeout = 5 * time.Minute

For large files or slow connections, operations will retry automatically.

Object Lifecycle

B2 supports automatic lifecycle policies:

Navigate to your bucket in the B2 dashboard
Click “Lifecycle Settings”
Configure:
- Keep only the last N versions
- Delete old files after X days

Cloudstic snapshots are immutable objects, so lifecycle policies can safely delete old snapshot objects after retention policies expire.

Cost Optimization

Pricing Overview (as of 2024)

Storage: $0.005/GB/month ($ 5/TB/month)
Downloads: $0.01/GB (first 3x storage free)
API calls: Class B (List) $0.004/10k, Class C (Upload) free

Example Costs
Daily Backups

Scenario: 500 GB backupMonthly costs:

Storage: 500 GB × $0.005 = **$ 2.50**
Downloads: First 1.5 TB free per month
API calls: Minimal (packfiles reduce calls)

Total: ~$2.50/monthCompare to AWS S3 Standard:

Storage: 500 GB × $0.023 =$ 11.50
Downloads: $0.09/GB

Reduce API Costs

Enable packfiles (default) to bundle small objects:

# Packfiles are enabled by default
cloudstic init -store b2:my-bucket

# Explicitly enable
cloudstic init -store b2:my-bucket

This reduces Class B (List) API calls by 10-100x.

Free Download Allowance

B2 includes 3x your storage in free downloads monthly:

100 GB stored → 300 GB free downloads/month
500 GB stored → 1.5 TB free downloads/month

Restores are typically free unless you exceed this limit.

Performance

Upload Speed

B2 upload performance depends on:

Network bandwidth: B2 can saturate gigabit connections
Concurrency: Cloudstic uses parallel uploads
Packfiles: Reduce overhead for many small files

Typical speeds:

100 Mbps connection: ~10-12 MB/s sustained
1 Gbps connection: ~100-120 MB/s sustained

Download Speed

Downloads are similarly fast, with global CDN acceleration available.

Troubleshooting

Authentication Errors

If you see “failed to create b2 client”:

# Verify credentials are set
echo $B2_KEY_ID
echo $B2_APP_KEY

# Test with B2 CLI
b2 authorize-account $B2_KEY_ID $B2_APP_KEY
b2 list-buckets

# Ensure key has access to the bucket
# Check "App Keys" in B2 dashboard

Bucket Not Found

If you see “bucket not found or accessible”:

# List available buckets
b2 authorize-account $B2_KEY_ID $B2_APP_KEY
b2 list-buckets

# Verify application key has access
# In B2 dashboard → App Keys → check bucket access

Slow Uploads

If uploads are slow:

Check network speed: speedtest-cli
Enable packfiles: Enabled by default, no flag needed.
Increase concurrency: B2 automatically uses parallel uploads
Consider compression: Enabled by default with zstd

Timeout Errors

If operations time out (5-minute default):

# Enable debug logging to see where it's stuck
cloudstic backup -debug -store b2:my-bucket

# Check network connectivity
ping -c 5 api.backblazeb2.com
curl -I https://api.backblazeb2.com

Advanced Features

Signed URLs

The B2 store supports generating time-limited download URLs:

// In Go code
url, err := store.SignedURL(ctx, "snapshot/abc123", 1*time.Hour)

This is used internally for secure temporary access.

Streaming Writers

For large objects, use streaming writes:

writer := store.NewWriter(ctx, "chunk/large-file")
defer writer.Close()

io.Copy(writer, dataSource)

Prefix Isolation

Use prefixes to isolate multiple repositories in one bucket:

# Production backups
cloudstic init -store b2:shared-bucket/prod/

# Staging backups
cloudstic init -store b2:shared-bucket/staging/

Each prefix acts as a separate repository.

Comparison with S3

Backblaze B2
Amazon S3

Pros:

Lower storage costs ( $0.005/GB vs$ 0.023/GB)
Free downloads (3x storage allowance)
Simple, predictable pricing
No multi-region complexity

Cons:

Single region per bucket
Slightly higher latency than S3
Fewer third-party integrations

Backup Command

Create backups to B2

S3 Storage

Alternative cloud storage

Restore Command

Restore from B2

Prune Command

Reclaim storage space

Get Started

Core Concepts

Sources

Storage Backends

Guides

Configuration

Required Settings

Authentication

Examples

Getting B2 Credentials

Create a Bucket

Generate Application Keys

Features

Streaming Uploads

Operation Timeouts

Object Lifecycle

Cost Optimization

Pricing Overview (as of 2024)

Reduce API Costs

Free Download Allowance

Performance

Upload Speed

Download Speed

Troubleshooting

Authentication Errors

Bucket Not Found

Slow Uploads

Timeout Errors

Advanced Features

Signed URLs

Streaming Writers

Prefix Isolation

Comparison with S3

Backup Command

S3 Storage

Restore Command

Prune Command

​Configuration

​Required Settings

​Authentication

​Examples

​Getting B2 Credentials

​Create a Bucket

​Generate Application Keys

​Features

​Streaming Uploads

​Operation Timeouts

​Object Lifecycle

​Cost Optimization

​Pricing Overview (as of 2024)

​Reduce API Costs

​Free Download Allowance

​Performance

​Upload Speed

​Download Speed

​Troubleshooting

​Authentication Errors

​Bucket Not Found

​Slow Uploads

​Timeout Errors

​Advanced Features

​Signed URLs

​Streaming Writers

​Prefix Isolation

​Comparison with S3

​Related Resources

Backup Command

S3 Storage

Restore Command

Prune Command

Configuration

Required Settings

Authentication

Examples

Getting B2 Credentials

Create a Bucket

Generate Application Keys

Features

Streaming Uploads

Operation Timeouts

Object Lifecycle

Cost Optimization

Pricing Overview (as of 2024)

Reduce API Costs

Free Download Allowance

Performance

Upload Speed

Download Speed

Troubleshooting

Authentication Errors

Bucket Not Found

Slow Uploads

Timeout Errors

Advanced Features

Signed URLs

Streaming Writers

Prefix Isolation

Comparison with S3

Related Resources