Backup Mechanisms

When and how to backup orcharhino is a question highly dependent on your individual usage and setup. We generally recommend performing backups before and after orcharhino upgrades.

The default use case is for orcharhino installations to run on virtual machines, most commonly within a VMware virtualization environment. In such a setup we recommend using the snapshot functionality provided by the virtualization solution for backups. If system snapshots are not an option, it is also possible to perform backups using the Foreman maintain utility.

Using Snapshots

The ATIX recommended backup strategy is to use system snapshots as provided by the virtualization solution orcharhino is running on (e.g.: using VMware’s vSphere client).

Ideally the orcharhino services should be stopped and the orcharhino VM powered down, before taking a snapshot. If that is not operationally possible, we recommend taking a live snapshot, that also retains the VM’s memory (RAM).

Either way, it is worth checking that there are no long running tasks before taking the snapshot or stopping any services:

foreman-rake katello:upgrade_check

Remember to delete older snapshots once they are no longer needed. Having too many snapshots can adversely affect system performance. It is recommended to keep no more than three system snapshots at once.

Using Foreman Maintain

The Foreman maintain utility aims to provide various maintenance features (including backups) for the upstream Foreman open source project. It is always included with orcharhino, but its use for orcharhino backups is considered to have technical preview status.


The Foreman maintain utility for orcharhino backups has technical preview status and can be used at your own risk. If you are interested in doing so in a production environment, please contact ATIX support.


Before starting the process to backup your orcharhino system, make sure that no other administrator of this system plans to run another long running job like synchronizing a repository or creating a content view. You can use foreman-maintain health check to run some health checks on orcharhino.


Both commands, backup and restore, require explicit confirmation by the caller. However, this can be bypassed (e.g. for scripts) by the option --assumeyes.

Currently, there are two supported ways to perform a backup: online and offline backup. While the system is available during online backup, all orcharhino services are turned off during the offline backup. We recommend using offline backup for production use, since this is the only way to ensure data integrity for the backup.

To perform a backup, you will need to provide a path where the backup files should be stored. Make sure, that there is enough free space available on this backup path. In the following examples, we will use /var/backup/ as backup path.


A full backup of all orcharhino data bases can take a long time. Since all orcharhino services are stopped for offline backups your orcharhino will be unavailable for the entire duration of the backup.

The following command will stop all orcharhino services first, create a full backup of all necessary data including pulp content and all databases and then start the services again.

foreman-maintain backup offline /var/backup/

The previous backup command creates a directory like /var/backup/katello-backup-2018-09-12-08-21-11 in which the backup is stored. In case you don’t want to create a backup specific subdirectory, use the --preserve-directory (-p) option.

A backup of the whole pulp content, like RPM, SRPM, Debian-packages, puppet modules, etc. is done. With the option --skip-pulp-content (-s) you can omit this step. Please remember, that restoring a working orcharhino without the pulp content is not possible.

The second way to create a backup is the online mode. Please keep in mind, that taking an online backup should only be used for debugging purposes as the data integrity between the various databases cannot be fully guaranteed. You shouldn’t do any modification regarding Host provisioning, repository synchronization, content view changes, etc. during an online backup as it may lead to inconsistencies in the online backup.

foreman-maintain backup online /var/backup/

It is also possible to take an incremental backup. You need to specify the path to an existing full backup or to another incremental backup. In our case, we are creating an incremental backup based on the previously created full backup.

foreman-maintain backup offline --incremental /var/backup/katello-backup-2018-09-12-08-21-11 /var/backup/

This creates an incremental backup based on the backup /var/backup/katello-backup-2018-09-12-08-21-11 and stores it in the /var/backup/ directory like /var/backup/katello-backup-2018-09-13-08-23-38. An incremental backup can be based either on a full backup or another incremental backup. Keep in mind, that you will need to restore the full backup and all previous incremental backups in order to restore your system.


Before starting the restore procedure, make sure to use the right orcharhino instance and that the orcharhino software version has not changed. The hostname within the backup needs to match the hostname of the system you are restoring. If the hostname doesn’t match currently, think that you are really on the right system and change the hostname if so. In the following example, we will restore the orcharhino based on the previously taken full backup:


Note that all data will be reset to the state it was in when the backup was created.

foreman-maintain restore /var/backup/katello-backup-2018-09-12-08-21-11

This should result in output similar to the following:

Console output while restoring a full backup

When the restore procedure is finished, the system is in the state it was in at the time of the backup and all orcharhino services are available again.

For restoring orcharhino from the incremental backup, you need to restore the sequence of full backup and the desired incremental backups:

foreman-maintain restore /var/backup/katello-backup-2018-09-12-08-21-11
foreman-maintain restore -i /var/backup/katello-backup-2018-09-13-08-23-38