Backblaze B2 destination

Walwarden supports Backblaze B2 as a backup destination via the S3-compatible API. This page covers creating and configuring the bucket, enabling File Lock, and creating the application key walwarden uses to authenticate.

Walwarden supports the following parameters for this provider:

Trust boundary note. Walwarden stores the application key for this destination. Unlike the AWS BYO S3 path (which uses short-lived AssumeRole session credentials), B2 application keys are long-lived. Use a minimum-scope, bucket-scoped application key (see step 3 below) and rotate it periodically. Revoke the key immediately if walwarden is ever compromised.

Preflight status. Backblaze B2 destinations start in unverified state. Run preflight after registration so walwarden can verify the application key, bucket access, File Lock-compatible retention behavior, public-access posture, encryption behavior, and retention writes.

File Lock vs. S3 Object Lock — semantic difference

Backblaze B2 File Lock is B2's immutability mechanism. When accessed via the S3-compatible API, File Lock behaves similarly to S3 Object Lock: each file (object) carries an expiration timestamp before which deletion is refused.

Differences from S3 Object Lock worth noting:

• B2 File Lock uses COMPLIANCE mode internally. B2 does not distinguish between GOVERNANCE and COMPLIANCE mode via the S3-compat API. This means even the account owner cannot delete objects before the retention expires. Plan your retention period accordingly — an overly long period creates operational risk if you need to recover storage.
• The S3-compat API exposes a subset of Object Lock operations. Some edge cases in S3 Object Lock (legal hold, per-request mode override) may not behave identically in B2. Walwarden uses only the subset that is reliably available.

Backblaze B2 S3-compatible endpoints

Step 1: Create the bucket with File Lock enabled

B2 File Lock must be enabled at bucket creation. You cannot enable it on an existing bucket.

1. Log in to the Backblaze console.
2. Go to B2 Cloud Storage > Buckets and click Create a Bucket.
3. Enter a bucket name.
4. Set Files in Bucket to Private.
5. Under Object Lock, toggle it on.
6. Click Create a Bucket.

After creation, set the default retention mode and period. Using the AWS CLI with a B2 endpoint:

aws s3api put-object-lock-configuration \
  --bucket my-company-walwarden-backups \
  --object-lock-configuration '{
    "ObjectLockEnabled": "Enabled",
    "Rule": {
      "DefaultRetention": {
        "Mode": "COMPLIANCE",
        "Days": 30
      }
    }
  }' \
  --endpoint-url https://s3.us-west-002.backblazeb2.com

Note that B2 only supports COMPLIANCE mode via the S3-compat API. Plan your retention period carefully — objects cannot be deleted before the period expires, not even by the account owner.

Step 2: Enable versioning

B2 Object Lock (File Lock) requires versioning. Create the bucket with versioning enabled. In the Backblaze console this is automatic when File Lock is turned on. Verify:

aws s3api get-bucket-versioning \
  --bucket my-company-walwarden-backups \
  --endpoint-url https://s3.us-west-002.backblazeb2.com

The response should show Status: Enabled.

Step 3: Create a minimum-scope application key

Do not use the master application key for walwarden. Create a bucket-scoped application key with only the capabilities walwarden needs.

In the Backblaze console:

1. Go to App Keys and click Add a New Application Key.
2. Set Name of Key to walwarden-backup.
3. Under Allow access to Bucket(s), select your walwarden bucket only.
4. Under Type of Access, select Read and Write.
5. Click Create New Key.

The console will show the application key ID (keyID) and the application key once. Record both — the key is shown only at creation.

Required capabilities: readFiles, writeFiles, deleteFiles, listBuckets, listFiles, readBucketEncryption, readBucketRetentions, writeFileRetentions.

Step 4: Register the destination in walwarden

1. In the walwarden dashboard, go to Destinations > Add destination.
2. Select Backblaze B2 (S3-compatible) as the provider.
3. Fill in:
   • Endpoint URL — the S3-compat endpoint for your B2 region (for example, https://s3.us-west-002.backblazeb2.com).
   • Bucket name — the bucket name from step 1.
   • Region — the B2 region slug (for example, us-west-002).
   • Access key ID — the application key ID (keyID) from step 3.
   • Secret access key — the application key from step 3.
4. Click Save.

The destination will appear in state unverified. Run preflight from the destination detail page before attaching it to scheduled backups.

Common footguns

Using the master key instead of an application key

The master application key has unrestricted access to all buckets. If it is compromised, all your B2 data is at risk. Always create a bucket-scoped application key.

File Lock not enabled at bucket creation

You cannot enable File Lock on an existing B2 bucket. Delete the bucket and re-create it with File Lock on.

Endpoint and region do not match

The endpoint URL contains the region slug (s3.us-west-002.backblazeb2.com → region us-west-002). Pasting the wrong endpoint or mismatched region will produce authentication errors. Copy endpoint and region together from the table above.

COMPLIANCE mode retention is permanent

Unlike AWS GOVERNANCE mode, B2 File Lock in COMPLIANCE mode cannot be shortened or removed. If you set a 365-day retention period, every object is locked for at least 365 days. Plan the retentionFloorDays setting accordingly before registering the destination.

Egress charges

Backblaze B2 offers free egress to Cloudflare-peered providers. If walwarden runs on a host that is not Cloudflare-peered (including AWS, GCP, Azure), standard Backblaze egress rates apply. Review Backblaze's current bandwidth alliance partners before committing to B2 as a destination.