Skip to content
Breeze RMMBreeze RMM

Storage Configuration

Before you can run backups, you need at least one storage configuration that tells Breeze where to send backup data. You can create multiple configurations — for example, an S3 bucket for off-site cloud storage and a local NAS for fast restores.

Creating a Storage Configuration

Section titled “Creating a Storage Configuration”

The storage configuration wizard walks you through four steps:

  1. Select a provider. Choose Amazon S3 or Local/NAS. Each option shows a brief description to help you decide.

  2. Enter provider settings. The fields change based on your provider:

    • Region — AWS region (e.g., us-east-1)
    • Bucket Name — the S3 bucket to store backups in
    • Path Prefix — optional key prefix within the bucket (e.g., breeze-backups). New snapshots are stored under <prefix>/snapshots/; see Key prefix below
    • Access Key and Secret Key — IAM credentials with s3:PutObject, s3:GetObject, s3:ListBucket, and s3:DeleteObject permissions (scoped to <prefix>/* when you set a prefix)

    Also works with S3-compatible services like MinIO, Wasabi, and Backblaze B2 — just set the endpoint URL accordingly. Enter the endpoint as a host (s3.example.com) or host and port (minio.local:9000), optionally prefixed with http:// or https://; a scheme-less endpoint is treated as https://. Other schemes (such as s3:// or ftp://) are rejected with a validation error rather than failing later at backup time.

  3. Set a schedule. Choose how often backups run:

    • Daily — pick a start time and backup window duration
    • Weekly — pick days of the week, start time, and timezone
    • Cron — enter a custom cron expression for advanced scheduling

  4. Configure retention. Choose a preset or customize:

    • Standard — 30 days, 5 versions
    • Extended — 90 days, 10 versions
    • Compliance — 365 days, 20 versions
    • Custom — set your own day count and version count

    Optionally enable encryption. This is only enforceable for S3 destinations with server-side encryption (SSE-S3 or SSE-KMS) configured — see Encryption for details. Local/NAS destinations do not support enabling this toggle.

Click Publish Configuration to make it active, or Save as Draft to finish later.

How Backup Data Is Stored

Section titled “How Backup Data Is Stored”

File backups are written to the target as one object per file, under a snapshots/<snapshot-id>/files/ prefix. Every file object’s name ends in .gz, but whether the bytes are compressed depends on the provider:

Provider Object name Stored bytes
Amazon S3 and S3-compatible (MinIO, Wasabi, Backblaze B2) ends in .gz Not compressed. The object is the original file, byte for byte.
Local / NAS ends in .gz gzip-compressed, decompressed again on restore

On S3 storage the .gz suffix is only part of the object name. Expect an S3 target to use roughly as much space as the files you protect, and size buckets and quotas on that basis. If you download a file object directly from the bucket, it is the original file. Rename it to drop the .gz instead of running gunzip on it, which fails with not in gzip format.

Breeze relies on this layout: restores, bare-metal recovery media, integrity verification and older agents all read S3 objects as raw bytes. Don’t rename, compress or recompress objects in the bucket.

Key prefix

Section titled “Key prefix”

An S3 destination’s Path Prefix decides where its new snapshots are written:

Destination New snapshot objects
No prefix snapshots/<snapshot-id>/... at the bucket root
Prefix msp/acme msp/acme/snapshots/<snapshot-id>/...

Each snapshot records the location it was written to, and Breeze reads, verifies, restores and cleans it up there for its whole life. As a result:

  • Existing snapshots are never moved. Snapshots taken before you set or changed the prefix stay where they are and keep restoring normally.
  • Changing the prefix makes the next backup a full backup. An incremental never builds on a snapshot stored under a different prefix, so the first run scheduled after a change uploads everything again. An incremental run that was already scheduled against a base under the old prefix when you changed it fails with a message saying so; the next scheduled run takes the full backup.
  • Several organizations can share one bucket with a prefix each. The storage cleanup sweep lists and deletes under one prefix at a time and never touches another prefix’s objects.
  • Scope IAM policies to the prefix. A policy that only allows bucket/snapshots/* stops working once a prefix is set; allow bucket/<prefix>/* instead. Test connection writes a probe object under the prefix, so it catches this before the first backup fails.

A valid prefix is at most 256 characters, made of /-separated segments that use only letters, digits and ! _ . * ' ( ) -. Leading and trailing slashes are ignored. Empty segments (a//b), . and .. are not allowed, and no segment may be snapshots (in any letter case), so one prefix can never contain another prefix’s snapshots. The form flags an invalid prefix as you type and the API rejects it on save. A destination saved with an invalid prefix by an older version is not backed up to the bucket root instead: its backups fail with a message asking you to correct the prefix, and Test connection fails naming the rule the prefix breaks.

Bare-metal recovery of a snapshot stored under a prefix always downloads through Breeze (token-mode download), which is the default for recovery media. Agent-side tools that read a bucket directly with a hand-supplied configuration take the prefix as their own option, and never read it from a pasted providerConfig.prefix:

  • breeze-backup rebuild --provider-config: pass --key-prefix <prefix>, where <prefix> is the path in front of snapshots/<snapshot-id>/ in the bucket. That is the prefix the snapshot was written under. After a prefix change it differs from the destination’s current Path Prefix. Snapshots taken before the prefix was set sit at the bucket root and need no --key-prefix. If the configuration file has a providerConfig.prefix and you leave out --key-prefix, the command prints a note and reads from the bucket root.
  • The agent.yaml backup manager (backup_provider: s3): set backup_s3_prefix: <prefix> to write and read its snapshots under <prefix>/snapshots/. Snapshots it took before you set the prefix stay at the bucket root, and the manager no longer sees them. If the prefix is invalid, the manager is disabled: backup commands that need it fail with a message naming backup_s3_prefix, and a local vault that uses it as its source does not start. It never falls back to the bucket root.

Both options follow the same prefix rules as the destination form, and the agent maps keys under the prefix exactly as the server does.

How destination credentials are stored

Section titled “How destination credentials are stored”

From v0.121.0, the credentials in a storage configuration (access keys, secret keys, session tokens, and the equivalent Azure, Google Cloud Storage and Backblaze B2 fields) are stored encrypted with your instance’s application encryption key. Bucket, region, endpoint and prefix stay readable. Existing configurations are encrypted by a background sweep on the first start after the upgrade, which logs one [startup] Backup destination credentials sealed: … line.

Section titled “Recommended bucket settings for S3-compatible storage”

When backups go to a bucket you or your customer own on an S3-compatible service (AWS S3, Wasabi, Backblaze B2, iDrive e2 and similar), set the bucket up so that backup data cannot be silently removed with the same key Breeze uses to write it:

  • Turn on Object Lock, or at least versioning. Object Lock (often called immutable or WORM storage) keeps each object version for a retention period you choose, even if a delete request arrives. Most providers only let you enable it when the bucket is created, so decide before the first backup. If your provider or plan has no Object Lock, enable bucket versioning instead, so a deleted or overwritten object leaves a recoverable previous version.
  • Add a lifecycle rule for old versions. With Object Lock or versioning on, Breeze’s retention sweep still sends deletes for expired restore points, but on a versioned bucket a delete only hides the object and the data is kept as a noncurrent version. Add a lifecycle rule that expires noncurrent versions after the number of days you want to keep them (no shorter than your Object Lock retention), or storage use keeps growing.
  • Use a key scoped to that one bucket. Create a dedicated access key for Breeze that can only reach the backup bucket (and, if you set one, its base path), with the object permissions listed above and nothing else: no access to other buckets, no permission to change bucket settings, Object Lock configuration or lifecycle rules, and no permission to bypass retention. If you use provider-enforced immutability on individual snapshots, the key also needs to read the bucket’s Object Lock configuration and set object retention (s3:GetBucketObjectLockConfiguration and s3:PutObjectRetention on AWS).

Breeze does not create buckets or manage these settings: it does not turn on Object Lock or versioning, write lifecycle rules, or create or scope access keys. Configure them in your storage provider’s console. When Object Lock is already enabled on the bucket and a snapshot is made immutable with provider enforcement, by its backup policy or by hand (POST /backup/snapshots/:id/immutability with "enforcement": "provider"), Breeze places a Governance-mode retention date on that snapshot’s objects. If the bucket does not have Object Lock enabled, the manual request is refused with 409, and a policy-driven snapshot falls back to Breeze’s own application-level immutability and records the reason on the snapshot (immutabilityFallbackReason).

Testing Connectivity

Section titled “Testing Connectivity”

After creating a configuration, test that Breeze can reach the storage target:

  1. Find the configuration in your storage list.
  2. Click the Refresh (test) action on the configuration row.
  3. A success or failure message appears. The configuration’s Last Tested timestamp updates on success.

Editing a Configuration

Section titled “Editing a Configuration”

Click the Edit action on any configuration to reopen the wizard. Changes are merged — updating a single field (like the bucket name) won’t erase your other settings.

Deleting a Configuration

Section titled “Deleting a Configuration”

Click Delete on a configuration to remove it. Configurations that are actively referenced by a backup policy should have the policy reassigned first.

Multiple Configurations

Section titled “Multiple Configurations”

You can create different configurations for different use cases:

Use case Recommended setup
Critical servers S3 (off-site) + local vault (fast restore)
Workstations Local NAS with 30-day retention
Compliance S3 with 365-day retention and server-side encryption
Development/test Local storage with minimal retention

Assign each configuration to the appropriate devices through backup policies.