# Backing up

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

## Run a backup

```sh
frost backup
```

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

```text
┌  backup  sftp://me@nas.local/~/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:

```text
┌  backup  sftp://me@nas.local/~/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](#scheduling).

## Preview a backup

```sh
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](#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](#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](#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](#checking-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:

```text
┌  backup  sftp://me@nas.local/~/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.