Backups in depth

A backup is a definition, not a copy. It says what to take, where it runs, how often, and how long the results are kept. Each execution is a run, and a successful run produces an artifact.

Three things about a backup are decided once and shape everything else: its kind, its source type, and its retention. The rest can be changed whenever you like.

Kinds

Kind is chosen when the backup is created and cannot be changed afterwards. It decides who connects to your data.

Kind is immutable because changing it would silently move a credential across a trust boundary. Create a second backup instead.

What a backup is made of

A backup starts as a draft and becomes active once it has everything its kind requires. Until then it holds no schedule and produces nothing.

Pausing is the right way to stop a backup temporarily. Deleting is refused while the backup still has artifacts, so a definition cannot be removed out from under the things it produced.

Source types

A run produces exactly one artifact. Sources that are naturally many files are streamed into a single archive, so keep_last counts runs rather than files.

Submitting a type that is illegal for the kind is refused at configure time, naming the type you sent. See Sources for each one in detail.

Schedules

Standard cron, evaluated in UTC unless you set a timezone on the backup.

schedule: "0 2 * * *"      # 02:00 daily
schedule: "0 3 * * 0"      # 03:00 Sundays

A manual backup takes no schedule, and asking for one is refused rather than ignored. See Schedules.

Retention

One rule with a floor under it. An artifact is removed when it is both older than expire_after and outside the newest keep_last:

retention:
  expire_after: 90d    # nothing older than 90 days
  keep_last: 10        # but always keep the 10 most recent, however old they are

keep_last is a floor, not a cap. On its own it deletes nothing: without expire_after you keep everything forever, however high the count. This is on purpose. A count read as a cap would delete your only recent copies the moment a source starts producing runs faster than you expected.

The newest artifact is never removed, so a backup that has run at least once always has something to restore from.

Retention is the only setting that bounds what you store, and therefore what you are billed for archive. A backup with no retention keeps everything forever.

Retention is write-once. It is fixed when you define the backup and cannot be edited, loosened, tightened or turned off. A different policy means a new backup. See Retention for why, and for lock_for.

The pipeline

Every kind converges on the same post-run pipeline, whoever produced the bytes.

produce → inspect → compress → encrypt → deliver → finalize

A run that stores no copy anywhere fails before finalize, so no artifact record is written for a file that does not exist.

Next