Get Started
DATA & SECRETS

Back Up and Restore Data

Save a point-in-time copy of a box's data, restore it into a new box, or carry it over to a rebuilt environment.

Before an agent starts a risky task, before you upgrade the environment, or simply every night, you want a copy of the data that you can return to. In run9 a backup is a fork of the disk that holds the data. It takes a moment, the box keeps running, and the copy stays safe when the box changes or is removed.

This page assumes the data lives on a Volume at /state, as in Keep Data Separate from the Environment. If your data lives on the root file system, the same steps work without --volume: a backup is snap fork --from-box <box-id>, and a restore is a new box created from that snap.

Take a backup

sys9 run snap fork --from-box agent-1 --volume /state --label purpose=backup

The box does not need to be stopped. It pauses briefly and continues, and the command prints the id of the new snap when it is ready. The label is optional; it makes backups easy to find later:

sys9 run snap ls --label purpose=backup

Later writes to /state do not change the backup, and removing agent-1 does not remove it.

Writes the operating system already received are in the backup. If an application keeps data in its own buffers, have it save or flush first.

Look inside a backup

sys9 run snap file ls <backup-snap-id> /
sys9 run snap file cat <backup-snap-id> /notes.txt

A backup of /state holds only that disk, so /state/notes.txt in the box is /notes.txt here. Reading it does not need a box.

Restore into a new box

A backup is restored by starting a box with a disk made from it:

sys9 run box create agent-restored --volume /state,from=<backup-snap-id>
sys9 run box exec agent-restored cat /state/notes.txt

The new box gets its own writable copy, with the same contents, owners, and modes. The backup itself is never changed, so you can restore it as often as you need.

A box’s disks are fixed once it is created, so a restore always goes into a new box. To keep the environment too, start the new box from a fork of the old one:

sys9 run snap fork --from-box agent-1
sys9 run box create agent-restored --snap <environment-snap-id> --volume /state,from=<backup-snap-id>

Copy data straight from another box

To give a second box the current data of a first one, you can skip the backup. box inspect lists the snap id of each disk:

sys9 run box inspect agent-1
Storage
MOUNT PATH  SNAP ID          ROLE
/           <root-snap-id>   Attached Snap
/state      <state-snap-id>  Volume

Pass that id to from=:

sys9 run box create agent-copy --volume /state,from=<state-snap-id>

If agent-1 is running, it pauses briefly as with any fork. Both boxes then write to their own disk.

Move data to a rebuilt environment

When the environment itself should be replaced, for example with a newer base image, keep the data and swap everything around it:

sys9 run box stop agent-1
sys9 run box inspect agent-1
sys9 run box create agent-1-new --image <new-image-ref> --volume /state,from=<state-snap-id>
sys9 run box exec agent-1-new ls -la /state

Stop the old box first and leave it stopped, so that the two boxes never work on the same data at once. Check that the new box has what you expect, then remove the old one:

sys9 run box rm agent-1

What a backup covers

  • One disk at a time. Backing up the root file system and a Volume gives two separate moments, not one combined snapshot.
  • A backup is not a byte-for-byte copy. It shares unchanged data with the disk it came from, which is why it is quick to take. It counts toward storage for the data it keeps alive.
  • There is no schedule or retention built in. Take backups from your own scheduler and remove old ones with snap rm.
  • A backup of a data disk is not meant to start a box on its own; it may not contain an operating system.