Overview

The module creates and restores backups of your HumHub installation. Only system administrators can use it. Open it via Administration → Modules → Backup → Configure.

A backup is a ZIP file that can contain:

backup-info.json inside the archive records for each component whether it was included, partial (some files unreadable) or missing (directory not found). Such problems are also shown after the backup finished.

Backups contain personal data (accounts, e-mail addresses, private content) and credentials. Store and transfer them securely.

The job queue tables (queue, queue_exclusive) are never part of a backup and are never replaced by a restore. Otherwise the backup job that was running when the dump was taken would come back as a "reserved" job, and a restore would wipe the jobs that are currently waiting.

Settings

• Backup Directory - path alias (e.g. @runtime/backups) or absolute path. It must be below @runtime or outside of the web root.
• Components - choose what to include. The database component needs the tools listed in INSTALLATION.md; the settings page warns if they are missing.
• Theme Name - directory name of the custom theme below @themes (required if "Backup Theme" is enabled).
• Number of Backups to Keep - after every new backup (manual or automatic) older backups beyond this number are deleted.
• Automatic backups - daily, weekly or monthly. They are queued by HumHub's hourly cron job and need a running queue worker.

Security of backups

A restore overwrites module code and configuration, so it must not trust every humhub_backup_*.zip that happens to lie in the backup directory. Therefore:

• Every backup is signed (HMAC-SHA256 over the complete archive, stored as <backup>.zip.sig next to it). The key is a secret of this installation and is not stored in the backup directory (see INSTALLATION.md).
• The confirmation page shows whether the signature is valid. The signature is checked again by the restore job before the archive is parsed, and once more after unpacking and before anything is changed.
• Not signed or signed by another installation (for example a backup from another server, a backup created before signatures existed, or after the signing key was lost): the restore needs the extra confirmation "I trust this backup". Only use it if you know where the file comes from.
• Modified (signed by this installation, but the content no longer matches): the restore is refused and cannot be confirmed.
• The settings page and the confirmation page warn if the backup directory is writable by other system users or owned by another user.

Deleting a backup also deletes its signature file. A downloaded backup does not include the signature, so restoring it on another server always needs the extra confirmation.

Compression

Backups are ZIP files; the Compression setting controls how the contents are compressed:

Why not a ZIP per module? A ZIP inside a ZIP does not save anything, because the files inside are already compressed and the outer ZIP can only store them. What makes the difference is compressing many files as one stream: source code, CSS and JavaScript contain a lot of repeated text across files, which a per-file compression cannot use.

Measured with the module itself:

The savings depend on the content: source code gains the most, images and videos (uploads) gain nothing and are therefore never recompressed. Creating a compressed backup needs temporary disk space in the backup directory for the compressed archive (before it is added to the ZIP), and restoring needs temporary space in @runtime for the unpacked files.

The compressed parts are standard .tar.gz / .tar.bz2 files. If the server does not support the selected compression, the backup uses the next best option and reports it. A backup can only be restored on a server that supports the compression it was made with; otherwise the restore is refused before anything is changed.

Creating a backup

Click Create Backup. The backup runs in the background; the page shows its state and refreshes when it has finished. Only one backup or restore can run at a time. If an operation hangs (for example because the queue worker stopped), use Reset status.

Restoring a backup

Click the restore button of a backup. A confirmation page shows

• which components the archive contains, how many files, and where they are written,
• what happens to existing data (database tables in the dump are dropped and recreated; files from the backup overwrite files with the same path, files that are not part of the backup are not removed),
• warnings, e.g. if the backup was created with a different HumHub version.

Before you restore:

1. Create a fresh backup of the current state.
2. Enable maintenance mode (Administration → Settings → Basic).
3. Make sure the queue worker is running.

To start the restore, tick the checkbox and type RESTORE (for a backup that is not signed by this installation you also have to confirm that you trust it). The restore runs as a background job. Before anything is changed it unpacks the backup and checks every file: each file that has to be overwritten must be writable by the web server user, new files must be creatable, and the database tools must be available. Files that are identical to the backup are left alone and do not need to be writable. If a file cannot be written, the restore is refused with the affected files listed, and nothing is changed.

If a file part still fails while it is being restored (for example because the disk is full), the remaining parts and the database import are not started, so the database is never replaced while the files are not. When it has finished, the result lists every component that was restored and every part that could not be restored. If some parts failed, your installation may be inconsistent - restore the fresh backup you created before.

For a backup that was not verified by its signature (and that you confirmed as trusted), the database client is started in a restricted mode where the client has one (--sandbox for MariaDB, --commands=OFF for MySQL 8.4+ if the dump has no DELIMITER commands). This prevents client commands in the dump, such as \!, from running. If the client has no suitable mode, the result says so.

You may be logged out afterwards because the sessions stored in the database are replaced.

A restore needs a running HumHub (it runs in the queue), so it is meant for restoring an existing installation. To recover onto a new server, install HumHub there first (this creates the queue tables), enable this module and then restore the backup. The module directories stored in the backup must also exist in the moduleAutoloadPaths of the target installation, otherwise the restore is refused with an explanation.

Troubleshooting

• "Database backup requirements are not met" - install mysqldump/mariadb-dump and the mysql/mariadb client and enable exec().
• Operation stays "running" - check the queue worker and the HumHub log (category gm-backup), then use Reset status.
• Automatic backups do not start - check that the cron job runs every hour, that the option is enabled and saved, and the queue worker.

After uninstalling

Disabling or uninstalling the module does not delete existing backups. They stay in the backup directory and must be removed manually (they contain personal data).