Kopia Backup: Cloud Storage Setup Guide (OCI, S3, Backblaze B2)

Kopia is an open-source backup tool that creates encrypted, deduplicated and compressed snapshots and stores them on any S3-compatible cloud storage — including OCI Object Storage, Backblaze B2, AWS S3, MinIO, and more. The practical goal of this guide is simple: create a Kopia repository on your chosen backend, validate it, run the first snapshot, and know how to reconnect or restore data later.

Quick setup

Supported storage backends

Kopia supports a wide range of storage backends. For cloud backups, the most common choices are:

This guide covers the two most popular self-managed cloud options in detail: OCI Object Storage and Backblaze B2.

Why Kopia for cloud backups

Kopia is a backup and restore tool built around three properties that matter for any cloud repository:

• Deduplication: identical content blocks are stored once and referenced across all snapshots.
• Compression: chunks are compressed before encryption, reducing storage and transfer costs.
• Client-side encryption: data is encrypted locally before it leaves your machine — the storage provider never sees plaintext.

Combined, these mean you get efficient, private backups without trusting your cloud provider with readable data.

Why OCI Object Storage

OCI Object Storage is useful as a Kopia backend because it provides:

• S3-compatible access, so Kopia can use the s3 repository type.
• A dedicated namespace and bucket model for isolating backup data.
• Multiple storage tiers: Standard, Infrequent Access, and Archive. For an active Kopia repository, start with Standard or Infrequent Access; use Archive only when your restore process can handle object retrieval before access. See Oracle’s Object Storage tiers documentation .
• IAM policies and customer secret keys, so access can be limited to the bucket used for backups.

For reference, the Kopia documentation used in this guide:

• installation guide
• getting-started guide
• S3 repository command reference

OCI details required by Kopia

You need these OCI details to create an S3 repository with Kopia:

• Bucket namespace
• Region name

These form the complete endpoint address of S3-compatible APIs:

{bucketnamespace}.compat.objectstorage.{region}.oraclecloud.com

Additionally, you’ll need:

• Bucket name
• User with access rights and customer access and secret key

Create the Kopia S3 repository

Once you have the information, the command looks like this. The keys are masked:

enrico.pesce@enrico ~ % kopia repository create s3 \
  --bucket=backup \
  --region=eu-frankfurt-1 \
  --endpoint=frddomvd8z4q.compat.objectstorage.eu-frankfurt-1.oraclecloud.com \
  --access-key=3fdsfdsfdsfsdf4543gtfreterter \
  --secret-access-key=dsdsadsadsadasdasdasdau7LF/KEjKZDhb8Q=

Kopia asks for a repository password during creation. Keep it outside the repository and outside OCI Object Storage: without that password you cannot decrypt the backup content.

If you want to test Object Storage and its compatibility, you can run a test that performs I/O operations in the repository:

enrico.pesce@enrico ~ % kopia repository validate-provider
Opening 4 equivalent storage connections...
Validating storage capacity and usage
Validating blob list responses
Validating non-existent blob responses
Writing blob (5000000 bytes)
Validating conditional creates...
Validating list responses...
Validating partial reads...
Validating full reads...
Validating metadata...
Running concurrency test for 30s...
All good.
Cleaning up temporary data...

Backblaze B2 repository

Backblaze B2 is a popular low-cost alternative to OCI Object Storage. Kopia connects to it using the same s3 repository type via B2’s S3-compatible API.

What you need from Backblaze:

• A B2 bucket (created in the B2 dashboard)
• An application key with read/write access to that bucket
• The S3 endpoint for your bucket’s region (visible in the bucket details page, e.g. s3.us-west-004.backblazeb2.com)

enrico.pesce@enrico ~ % kopia repository create s3 \
  --bucket=my-kopia-backup \
  --region=us-west-004 \
  --endpoint=s3.us-west-004.backblazeb2.com \
  --access-key=<B2-keyID> \
  --secret-access-key=<B2-applicationKey>

The creation flow is identical to OCI: Kopia asks for a repository password, then you can run kopia repository validate-provider to confirm everything works. The same snapshot and restore commands apply regardless of backend.

B2 pricing note: B2 charges for storage and download. Kopia’s deduplication and compression reduce both; enable compression for text-heavy workloads to minimize egress costs.

Reconnect to the Kopia repository

To connect on the repository:

enrico.pesce@enrico ~ % kopia repository connect s3 \
  --bucket=backup \
  --region=eu-frankfurt-1 \
  --endpoint=frddomvd8z4q.compat.objectstorage.eu-frankfurt-1.oraclecloud.com \
  --access-key=3fdsfdsfdsfsdf4543gtfreterter \
  --secret-access-key=dsdsadsadsadasdasdasdau7LF/KEjKZDhb8Q=

To check repository information, including a useful quick-reconnect snippet without writing clear credentials in the command line:

enrico.pesce@enrico ~ % kopia repository status -t -s
Config file:         /Users/enrico.pesce/Library/Application Support/kopia/repository.config

Description:         Repository in S3: frddomvd8z4q.compat.objectstorage.eu-frankfurt-1.oraclecloud.com backup
Hostname:            enrico
Username:            enrico.pesce
Read-only:           false
Format blob cache:   15m0s

Storage type:        s3
Storage capacity:    unbounded
Storage config:      {
                       "bucket": "backup",
                       "endpoint": "frddomvd8z4q.compat.objectstorage.eu-frankfurt-1.oraclecloud.com",
                       "accessKeyID": ....

...To reconnect to the repository use:

$ kopia repository connect from-config --token eyJ2ZXJzaW9uIjoiMSIsInN0b3JhZ2UiOnsidHlwZSI6InMzIiwiY29uZmlnIjp7ImJ1Y2tldCI6ImJhY2t1cCIsImVuZHBvaW50IjoiZnJkZG9tdmQ4ejRxLmNvbXBhdC5vYmplY3RzdG9yYWdlLmVdsgfdsgdfsgfdsgo537hn9058jg9v-5869g5k89d-kf8946578bj06vfm056jvk0y458bnj908jg9v6k8fy989f658965jgy968jg94586b9k4869g84y6hgb8j69b8hj69hk8g95687h969bmtiomgufiunfbter

Now you have a ready repository to store your data with Kopia!

Create the first snapshot

For example, you can create a folder backup with this simple command using default settings:

enrico.pesce@enrico ~ % kopia snapshot create $HOME/Downloads
Snapshotting enrico.pesce@enrico:/Users/enrico.pesce/Downloads ...
 * 0 hashing, 0 hashed (0 B), 5175 cached (14 GB), uploaded 202 B, estimating...
Created snapshot with root k24214076e958e761485b2af904f03b0b and ID de70da14f1c0264b3cbc4016dee67a7f in 0s

Once the copy process is complete, you can already list the created snapshots, in my case after a few days:

enrico.pesce@enrico ~ % kopia snapshot list $HOME/Downloads
enrico.pesce@enrico:/Users/enrico.pesce/Downloads
  2024-02-01 00:06:22 CET k081e4271a2db92d7eefe1ca035ff72c2 15.2 GB drwx------ files:11881 dirs:3150 (daily-5,monthly-2)
  2024-02-01 15:00:00 CET k5ed33706ce70d8984d89a8e8258a959f 15.2 GB drwx------ files:11882 dirs:3150 (latest-6..10,daily-4)
  + 4 identical snapshots until 2024-02-02 01:03:16 CET
  2024-02-02 13:31:20 CET k0db08b85d87ee5f366904d44eb149079 15.2 GB drwx------ files:11883 dirs:3150 (latest-5,daily-3,weekly-2)
  2024-02-05 11:52:21 CET k2e413b9843f14822438c57be23a1356a 15.2 GB drwx------ files:11895 dirs:3151 (latest-3..4,hourly-3..4,daily-2)
  + 1 identical snapshots until 2024-02-05 13:00:00 CET
  2024-02-06 10:46:14 CET k9eeba61e888e68e09ab26cd2aca07095 15.4 GB drwx------ files:11898 dirs:3158 (latest-1..2,hourly-1..2,daily-1,weekly-1,monthly-1,annual-1)
  + 1 identical snapshots until 2024-02-06 13:00:00 CET

Deduplication and compression

Two features make Kopia efficient for long-running backup repositories:

Deduplication splits each file into content-defined chunks and stores each unique chunk only once. If you back up the same 10 GB library folder every day, only the changed chunks are uploaded — not 10 GB per snapshot. This applies across all sources that share a repository, so a second machine backing up similar files benefits from chunks already stored by the first.

Compression reduces the size of each chunk before it is encrypted and uploaded. Kopia supports several algorithms; zstd is a good default that balances speed and ratio. Enable it per path via policy:

kopia policy set --compression=zstd $HOME/Documents

Check actual savings with:

kopia repository status

The output shows original size, deduplicated size, and compressed size so you can measure the real-world benefit.

Restore and retention basics

Backups are only useful if restore is tested. Kopia can restore a file or directory from a snapshot with:

kopia snapshot restore <snapshot-id> ./restore-test

Run a small restore test after creating the repository, then schedule periodic restore checks. This catches repository access, password, lifecycle and retention problems before an incident.

For retention, configure policies instead of relying on manual cleanup. Kopia policies let you control snapshot frequency, retention windows and compression settings for each protected path:

kopia policy set \
  --keep-latest=10 \
  --keep-hourly=24 \
  --keep-daily=7 \
  --keep-weekly=4 \
  --keep-monthly=12 \
  --keep-annual=3 \
  $HOME/Documents

This keeps the 10 most recent snapshots plus hourly, daily, weekly, monthly and annual windows — all older snapshots outside these windows are eligible for garbage collection. Run kopia snapshot gc to reclaim space.

KopiaUI screenshots

If you’re not a fan of the console, I recommend using the simple and convenient GUI, KopiaUI , which is intuitive and easy to use. Here are some screenshots:

where you can check the protected folders view all backup iterations over time with convenient color-coded tags the list of protected files file restoration is very simple policy configuration is very comprehensive and granular

Troubleshooting checklist

• If repository creation fails, verify the OCI endpoint format: {bucketnamespace}.compat.objectstorage.{region}.oraclecloud.com.
• If authentication fails, check the customer access key and secret key, not the regular OCI API key.
• If validation fails, confirm that the user can list, read and write objects in the target bucket.
• If restores are slow or fail, check whether lifecycle rules moved repository objects to Archive.
• If storage grows faster than expected, review compression, snapshot retention and whether large generated files should be excluded.

Now you can use Kopia with OCI Object Storage and test both backup and restore before relying on it.