Create and Verify a Full System Backup in Yunohost

A Yunohost server that has never been backed up is one disk failure away from losing every app, mailbox, and user account it hosts. The good news: Yunohost ships with a built-in backup utility that can capture apps, system configuration, and data in a single archive. This guide walks through creating a complete backup, confirming it actually finished cleanly, and knowing your restore options before you need them.

What a full backup should capture

The goal is one restorable archive containing three things: your installed applications (--apps), the system configuration such as users, domains, and firewall rules (--system), and application data (--data). Leaving any of these out means a restore will silently skip part of your server, so for a true full backup you want all three flags.

Before you start

• Access: You need root or sudo access on the server, either over SSH or a local console.
• Package: The yunohost-backup package is installed by default. If a command below reports it is missing, install it with sudo apt install yunohost-backup.
• Disk space: The backup destination needs at least as much free space as the data being archived, plus a safety margin. Check free space with df -h.
• Destination: Do not write the backup to the same filesystem you are backing up. If the disk fills mid-backup, you can corrupt both the archive and the running system. Mount a USB drive or an NFS share and point the backup there, or copy the archive off the server immediately afterward.

Creating the backup

Run the following on the server as root (or with sudo):

yunohost backup create --apps --system --data

The command runs in the foreground and prints progress as each app and system component is archived. Depending on how much data you host, this can take anywhere from minutes to hours. You can also watch progress from the web admin interface under Backups → Operations.

One caveat worth planning around: backing up while apps are running can capture inconsistent state, especially for databases. For anything critical, put the app into maintenance mode first, or use the app's own dump tool (for example a database dump) before starting the Yunohost backup.

Verifying the backup actually worked

A backup you have not verified is a hope, not a backup. Run these checks after the command completes.

1. Confirm the archive exists and finished

yunohost backup list

Your new backup should appear in the list with a finished status. If it is missing or marked otherwise, the backup did not complete.

2. Check the size

Compare the archive size against what you expected. An archive that is suspiciously small usually means a large data directory was skipped. Archives live under /home/yunohost.backup/archives/, so you can inspect sizes with ls -lh /home/yunohost.backup/archives/.

3. Read the log

Each backup writes a log to /var/log/yunohost-backup/backup_<timestamp>.log. Scan it for error lines. A successful run ends with a line containing Backup finished. Any app that failed to back up will be named here, which tells you exactly what a restore would be missing.

4. Test archive integrity

You can list the contents of the archive without extracting it:

tar -tzf /home/yunohost.backup/archives/<backup-id>.tar.gz | head

If tar reports a corrupt archive or the listing stops abruptly, treat the backup as failed and create a new one. Replace <backup-id> with the name shown by yunohost backup list.

5. The real test: a trial restore

The only check that proves a backup is restorable is restoring it. If you can, spin up a spare Yunohost instance or virtual machine at the same major version and restore the archive there. This catches problems that logs and tar listings cannot, such as an app whose restore hook fails.

Recovery options when something goes wrong

To restore a full backup, run:

yunohost backup restore <backup-id>

or use the admin portal's Backups section. This reinstates apps, system settings, and user data. Expect a full restore to take roughly as long as the backup did, and plan downtime accordingly.

If the archive itself is damaged, you still have two fallbacks. First, you can manually extract the tarball and recover individual components, such as a single app's data directory or a configuration file. Second, this is why retention matters: keep multiple backup generations so a corrupted latest backup does not leave you with nothing. Backup media degrades, and a single copy on a single disk is a single point of failure.

Limitations to keep in mind

• The built-in tool does not replace off-site copies. After the backup completes, copy the archive to another machine or storage location.
• Consistency of live databases is your responsibility; the tool archives files as they are at that moment.
• Test restores periodically, not just once. A restore procedure that worked six months ago can break after app or system upgrades.

With a verified archive, an off-server copy, and at least one practiced restore, a disk failure becomes an inconvenience instead of a catastrophe.