Restore

Important Information

Please read the following information carefully before starting to restore your data.

  • This section is not about migrating from one host to another. You can find instructions about this topic here.

  • This documentation page expects a fully installed Zammad version

  • It also expects you to restore Zammad on the same host and Zammad version

  • The restoration process stops & restarts Zammad. Therefore you have to run the restore script with appropriate permissions (e.g. as root).

    • 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 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!

  • It will drop and re-create the 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)

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. They are named like this:

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

There are also two symlinks in your backup directory pointing to the newest backup created.

latest_zammad_db.psql.gz
latest_zammad_files.tar.gz
Step 2: Configure the backup script (if needed)

On new installation this is required. At least you have to provide a directory where your backups are stored. Please consult Backup Configuration for more information.

Step 3: Clean up the storage folder

In case you restore to a production environment with activated file system storage, you should purge the content of the directory /opt/zammad/storage/. The restore process only adds/overwrites files there, no cleanup will take place.

Step 4: Run the restore

Be aware that restoring backups can overwrite your database.yml. You can check that by looking into the [...]_zammad_files.tar.gz file. If there is a database.yml in the directory config > database, ensure to save the original version before restoring.

In case it has been overwritten already, you can try the Database Helper: (Re)set Password.

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

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

Provide the requested information to the script and wait for the restore process 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!
Step 5: Re-install Zammad if restoring a full filesystem restore

The backup script optionally back up the whole filesystem of Zammad.

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 6: Apply missing environmental settings

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 Connect Zammad with Elasticsearch 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.

If you are facing issues, consider reading our troubleshooting section.