Restore

Before Starting

Hint

♻️ Migrating from host to host…?

Please refer Migrate Zammad to New Host for more additional information about migrating Zammad.

Warning

This documentation page expects a fully installed Zammad version.
It also expects you to restore Zammad on the same host and version!

Before restoring your backup, please note the following:

  • The restoration process stops & restarts the Zammad service. This means you usually have to run the restoration script as root user.

    • This is mandatory for package installations

    • On Source code installations, this does not work because of different environments - you could load it beforehand as root user to have access to Zammad specific commands.

    • If both approaches above do not fit for your case, consider adjusting the backup and restore scripts to your need in an independent directory. You’re working out of script and documentation scope!

  • PostgreSQL based installations will drop and re-create the database! MySQL / MariaDB based installations restore on the existing database.

  • You require at least twice the backed up Zammad instance size of free storage. If you have the dump only, factor 3 could be a good number.

Restore

Step 1: Copy your backup files to a fitting location (if needed)

This basically is a given usually if you run a normal restore. Ensure that the user you’re using for restoration is allowed to read the backup files - writing is required for /opt/zammad/.

The Zammad backup consists of two files. This is their format:

<timestamp>_zammad_db.psql.gz
<timestamp>_zammad_files.tar.gz

There’s also two symlinks in your backup directory showing to the newest backup created.

Step 2: Configure the backup script (if needed)
On new installation it’s required. For restoration this mainly affects the backup file location.
Please consult Backup configuration for more.
Step 3: Run the restore

Restoration works in two possible ways, depending on how interactive you want to go.

Warning

Restoring old backups may overwrite your database.yml. You can find out if that’s the case by having a look into the file .tar.gz within the config directory. If you can see a database.yml there, ensure to save the original version before restoring.

If you found the trap already, you can try the Database Helper: (re)set password.

$ /opt/zammad/contrib/backup/zammad_restore.sh

Provide the requested information to the script wait for the restoration to finish. Depending on the size of your backup and host performance this may take some time.

The restore operation should look like this:

# Zammad restore started - Fri Jan 21 17:54:13 CET 2022!

The restore will delete your current database!
Be sure to have a backup available!

Please ensure to have twice the storage of the uncompressed backup size!


Note that the restoration USUALLY requires root permissions as services are stopped!


Enter 'yes' if you want to proceed!
Restore?: yes
Enter file date to restore:
20220120124714
20220121175344
File date: 20220121175344
Enter db date to restore:
20220120124714
20220121175344
DB date: 20220121175344
# Stopping Zammad
# Checking requirements
# ... Dropping current database zammad
Dropped database 'zammad'
# ... Creating database zammad for owner zammad
CREATE DATABASE
# Restoring PostgreSQL DB
# Restoring Files
# Ensuring correct file permissions ...
# Clearing Cache ...
# Starting Zammad

# Zammad restored successfully - Fri Jan 21 17:54:34 CET 2022!

Sample backup process.

Step 4: Re-install Zammad if restoring a full filesystem restore

Zammads backup scripts backup the whole filesystem of Zammad. This is mainly for backward compatibility but not a hard requirement.

If your filesystem dump contains attachments only (the tar will contain a storage folder only) skip this step!

For a better overview, please see: step 9 of our migration path.

Step 5: Apply missing environmental settings

Note

This does not apply to Docker images, as the following settings should be applied upon every start automatically.

If you’ve set any environmental settings like higher web concurrency due to required 🎛️ Performance Tuning, please re-apply your settings now.

If not already done, please install Elasticsearch now (if you want to use it). Follow Step 3: Connect Zammad to reconfigure your installation for Elasticsearch use and rebuild the search index.

You are now ready to continue your work. The rebuild of your search index can safely run during your work, but will cause a degraded search performance and may lead to temporarily not found data.

Hint

😖 Having trouble restoring?

Have a look at the troubleshooting section to address your issues.