Backing up

frost backup backs up your folders now. Only what changed since the last backup is uploaded.

#Run a backup

frost backup

Frost shows what changed, how much it uploaded and the result of its spot check:

┌  backup  sftp://[email protected]/~/frost
│
│  changes      3 added, 1 changed
│  files        1,204 (2.1 GB)
│  new data     14.2 MB in 9 chunks (9.8 MB uploaded after compression)
│  verified     ok, 21 random objects re-downloaded and checked
│
└  Saved snapshot maple-absurd-3f1c

A file counts as changed when its contents, size, permissions or modification time change. A folder's modification time alone doesn't count, because temporary files change it all the time.

If nothing changed, Frost doesn't save a new snapshot:

┌  backup  sftp://[email protected]/~/frost
│
│  files        1,204 (2.1 GB)
│  verified     ok 3h ago, 21 objects checked
│
└  Already backed up. No changes detected since snapshot maple-absurd-3f1c, saved 3h ago.

A backup ends with a storage warning when your storage needs attention, such as a Permafrost account, a server's disk or a drive that's nearly full.

With automatic backups on, you rarely need to run this yourself. See Automatic backups.

#Preview a backup

frost backup --dry-run

A dry run lists every file with new data to upload and the total, without uploading anything or saving a snapshot. -n is short for --dry-run.

#Options

Flag Does
-n, --dry-run Shows what would be uploaded, without uploading anything
--path <dir> Backs up this folder instead of your usual ones. Repeat it for more folders
--exclude <pattern> Also skips this pattern, for this run only. Repeat it for more patterns
--no-verify Skips the spot check after the backup

To change which folders are backed up every time, run frost init again, or see Settings.

#What's backed up

Frost backs up regular files, folders and symbolic links, with their permissions and modification times.

  • A symbolic link is saved as the link itself, not the file it points to.
  • Hard-linked files are backed up and restored as separate files.

Frost leaves out:

  • Anything on your skip list. See Excluding files.
  • Sockets, devices and pipes.
  • File owners, ACLs and extended attributes.
  • On macOS, files that iCloud keeps only online. Frost doesn't download them. They're skipped and listed instead.
  • The .frost-partial-... files that a stopped restore leaves behind.

#When something goes wrong

What happens What Frost does
A file or folder can't be read, because of permissions, because it was deleted mid-backup or because it's only in iCloud Skips it and lists it. The snapshot is still saved, and frost status shows how many items were skipped
A folder on your list isn't there, like one on an unplugged drive Skips it and backs up the rest. frost backup and frost status name the missing folder
None of your folders are there, or one exists but can't be read at all Fails the whole backup, so a backup never looks fine while saving nothing
A file changes while Frost reads it, like a database in use, a running virtual machine's disk or a download Reads it again at the end of the backup. If it's still changing, the snapshot keeps its previous copy and Frost lists it. A file that was never backed up cleanly is skipped

Frost doesn't take filesystem or database snapshots. To back up a file that's always busy, back it up while the program using it is closed.

On macOS, some folders need your permission before Frost can read them. See macOS permissions.

#The spot check

After a backup that saves a snapshot, Frost downloads a few random chunks, 20 by default, and checks them. After a backup with nothing new, it only checks again if the last check is more than a day old or found a problem. If a check fails, the backup reports an error. See Checking your backups.

#Interrupted backups

If a backup stops partway, because of a lost connection, a closed laptop or Ctrl+C, nothing already uploaded is wasted. Frost records chunks as they upload, and the next backup skips them.

#Near a scheduled backup

If a scheduled backup starts within the next hour, or finished within the last hour, frost backup says so and asks before it starts:

┌  backup  sftp://[email protected]/~/frost
│
│  A scheduled backup starts in 40m, at 15:00.
│  Back up now anyway? [Y/n]

Press Enter to back up anyway, or type n to stop. For schedules less than 4 hours apart, the window is a quarter of the interval. A finished backup only counts if it worked and you haven't backed up since. Frost only asks in a terminal, and not for a dry run or with --path or --exclude.

#One at a time

A backup or command-line restore locks its local cache while it runs. If another command needs that cache, Frost says "a backup or restore operation is already in progress; try again when it completes". When the other one is a scheduled backup, it says "a scheduled backup is already running" and when it started. A scheduled backup that finds the cache locked waits up to an hour instead. The snapshot browser releases the cache lock, so it can stay open and restore while a backup runs. Different cache folders and computers have separate locks.