Backups are so back. https://capsul.org/backup-instructions

How to set up backups

JAN 24 2025:


Click Here to Show Implementation Details

We use this tool to do our backups:

https://github.com/abbbi/virtnbdbackup

It looks like it uses the "checkpoint" feature of libvirt/qemu/kvm to mount an `nbd` (network block device) on the guest filesystem of the capsul at a *specific point in time*. Then it streams the contents of the filesystem from the nbd to the host, where they can be stored as a backup file.

There are two magical aspects of this that make it work for us:

  1. Because of the way the checkpoint interacts with the nbd, the backup can get a consistent (less likely to be corrupted) view of the guest filesystem without stopping the VM or freezing its filesystem for the entire duration of the backup process.
  2. Because of the way the Dirty Bitmaps in the QCOW2 image format interact with the nbd, it's possible to take incremental backups which only need to store the data that changed since the last backup.

However, in order to get the consistency part to work, virtnbdbackup needs to be able to freeze the guest filesystem temporarily while it creates a checkpoint. It uses the qemu guest agent to do this.

  1. We define a unix socket in the virtual machine configuration
  2. Libvirt/qemu creates the unix socket file inside the VM
  3. The qemu guest agent inside the VM connects to the unix socket and accepts commands from the host.

However, there's just one problem: we didn't install the qemu guest agent on our operating system images yet.

So in order to get backups to work, you will need to install the qemu guest agent on your Capsul and then restart it. 

NOTE: At the same time, plz install & enable the acpid service.
      ACPI is the system that handles the power button on a computer.
      Installing and enabling it will allow you (and us) 
      to gracefully  shut down your capsul from the web interface, 
      rather than just pulling the plug. It should overall reduce 
      risk to your data, so it's strongly recommended.

Here are the commands for our Alpine Linux image: 

apk add qemu-guest-agent \
  && rc-update add qemu-guest-agent \
  && service qemu-guest-agent start \
  && rc-update add acpid \
  && service acpid start

Here are the commands for our Debian image: 

apt-get update \
  && apt-get -y install acpid qemu-guest-agent \
  && systemctl enable --now qemu-guest-agent

Here is the configuration for older versions of our NixOS image (required for Capsuls created before Jan 27nth 2025) 

  services.qemuGuest.enable = true;
  services.acpid.enable = true;

You just want to make sure that both acpid and qemu-guest-agent are:

  1. Installed
  2. Enabled (will start automatically on boot)
  3. Running

Once

  1. your capsul has been restarted
  2. both are running

you should see a new option labeled

[ Graceful Shutdown... ]

on the capsul detail page, and the The qemu-guest-agent was not detected warning should disappear.

Once that's verified, you should be good to go, and your capsul will be backed up.

The default backup window is from 10:00 UTC to 13:00 UTC.
(That's 4am to 7am Central Time)

If you want a different backup window, let us know.

For now, the avaliable backup snapshots will show up on the capsul detail page underneath the Actions, but there's no self-serve UI to restore them yet. The links lead to the support page.

We'll add a nice UI for it sometime, but I didn't want to put off the enablement of backup any longer than I have to, so I'm releasing it to yall ASAP because I'm confident it works:

I just restored & validated multiple different snapshots of a test capsul just now 😌

Anyways, as always, if you have any questions or issues, email support@cyberia.club

ADDENDUM:

If you use a linux with systemd and see this warning message while installing / enabling qemu-guest-agent, I'm pretty sure it's not a real issue, I saw this during my testing too.

Just make sure to run those install/enable commands as root (with sudo -i for example) and then verify that the processes are running with

sudo ps aux | grep guest-agent

and

sudo ps aux | grep acpid

ANYWAYS here is the warning message I was referring to:

Synchronizing state of qemu-guest-agent.service with SysV service script with /lib/systemd/systemd-sysv-install.
Executing: /lib/systemd/systemd-sysv-install enable qemu-guest-agent
The unit files have no installation config (WantedBy=, RequiredBy=, Also=,
Alias= settings in the [Install] section, and DefaultInstance= for template
units). This means they are not meant to be enabled using systemctl.

Possible reasons for having this kind of units are:
• A unit may be statically enabled by being symlinked from another unit's
  .wants/ or .requires/ directory.
• A unit's purpose may be to act as a helper for some other unit which has
  a requirement dependency on it.
• A unit may be started when needed via activation (socket, path, timer,
  D-Bus, udev, scripted systemctl call, ...).
• In case of template units, the unit is meant to be enabled with some
  instance name specified.

This email was sent by the Capsul Admin Megaphone.
If you have any questions DO NOT REPLY TO THIS EMAIL, 
direct your inquiry to support@cyberia.club