Configuration & operations
Backing up Koha with koha-dump — and restoring it
A package install already backs itself up nightly, keeps two days, and writes to a disk that dies with the server. Here is how to check it, and how to restore.
Updated 2026-08-09 · Tested against Koha 26.05
A package install already runs koha-run-backups --days 2 --output /var/spool/koha every night, so you almost certainly have backups. What you almost certainly do not have is backups anywhere other than the server they protect, or any evidence one has ever restored. Both are fixable in an afternoon.
Two days, on the same disk
- Two days of retention. A corruption noticed on Wednesday cannot be undone from a Monday you no longer have.
- On the same disk as the database. The failure most likely to need a backup is the one that takes the disk with it.
Copying dumps to a second machine is the single highest-value change on this page.
Step 1Check what you already have
$ sudo ls -lh /var/spool/koha/library/ library-2026-08-08.sql.gzlibrary-2026-08-08.tar.gzlibrary-2026-08-09.sql.gzlibrary-2026-08-09.tar.gzReplace library with your instance name (sudo koha-list). Two files per night, and you need both:
.sql.gz— the database. Every record, patron, loan and setting..tar.gz— the instance configuration:/etc/koha/sites/<name>, the Zebra indexes, and the log directory.
A dump older than yesterday means the nightly job is not running — see Koha cron jobs. No directory at all means backups have never run on this box.
Step 2Take one now
Always take a dump before an upgrade, a bulk import, or anything you would not want to explain afterwards.
$ sudo koha-dump libraryUseful flags, all read from the script's own help:
| Flag | What it does |
|---|---|
| <code>--exclude-indexes</code> | Leaves the Zebra indexes out. Much smaller and much faster — the indexes can be rebuilt from the data. |
| <code>--exclude-logs</code> | Leaves /var/log/koha/<name> out. |
| <code>--uploaded_files</code> | Includes patron and record file uploads, which are not in the default dump. |
| <code>--schema-only</code> | Structure with no data — for comparing your schema against stock Koha, not for backup. |
| <code>--quiet</code> | For calling from a script. |
Uploaded files are not in the default backup
--uploaded_files — otherwise a restore brings back rows that point at files that are gone.Step 3Get it off the server
A backup on the same machine protects you against a mistake. It does not protect you against the machine. Pull last night's dump to somewhere else, on a schedule:
$ rsync -avz --delete \ backup-user@koha.example.org:/var/spool/koha/ \ /srv/koha-backups/Then raise retention on the server itself, so a problem noticed a week late is still recoverable. Edit the nightly line in /etc/cron.daily/koha-common:
koha-run-backups --days 14 --output /var/spool/kohaCheck the free space on that partition before you multiply retention sevenfold. A dump is roughly proportional to catalog size, and the Zebra indexes in the tarball are usually the larger half.
Step 4Restore an instance
koha-restore takes exactly two arguments — the SQL dump and the config tarball, in that order — and recreates the instance from scratch: the system user, the database, the configuration and the Apache site.
$ sudo koha-restore \ /var/spool/koha/library/library-2026-08-09.sql.gz \ /var/spool/koha/library/library-2026-08-09.tar.gzIt will not restore over an existing instance
koha-restore refuses to run if any file in the config tarball already exists on disk, and prints ERROR: File exists. This is a guard, not a bug — a half-overwritten instance is worse than a failed restore. To restore over a live instance, remove it first with sudo koha-remove library, which deletes its database and configuration and cannot be undone. Have the dump in your hand and verified before you type that.After a restore, rebuild the search index and confirm the site answers:
$ sudo koha-rebuild-zebra -f -v library$ sudo systemctl reload apache2If searches come back empty afterwards, the index did not rebuild rather than the data being missing — see rebuilding the Zebra index.
Test the restore, not the backup
A backup that has never been restored is a hypothesis. The failure modes are ordinary and quiet: a dump truncated by a full disk, a tarball missing the uploads, a nightly job that has been failing since a hostname changed. Every one of them looks exactly like a working backup from the outside.
So restore onto a spare machine or a VM, once, deliberately: koha-restore the newest pair under a different instance name, rebuild the index, log in, and search for something you catalogued last week. It takes an hour and it converts a hope into a fact.
Write down how long it took. The number you actually need in an emergency is not "do we have a backup" but "how long until we are open again", and the only way to know it is to have done it once when nothing was on fire.
Would rather not do this yourself? We do it as a service — and if you would rather it were already done, it is on Koha Cloud before you log in.
Related
More on configuration & operations
Answers to the questions that usually arrive with this one.
Koha internal server error: finding the line that caused it
A 500 page is Koha telling you nothing on purpose. The real message is in that instance's error log — here is which file to read, and the two causes that produce most of them.
Rebuilding the Zebra index when Koha search results go stale
A record you can open by its number but cannot find by searching means the index is behind, not that the record is missing. Here is how to rebuild it properly.
Koha cron jobs: which ones matter, and what breaks silently without each
A package install schedules about fifteen jobs. This is what each one does, when it runs, and the exact symptom a library sees when it stops.
Using a Gmail account as Koha’s SMTP server
Gmail works as Koha’s mail server, but only with an app password and two-step verification on. Here are the exact settings, and the limits worth knowing before you rely on it.