Server Maintenance Guide

This guide describes common maintenance activities for an orcharhino system (e.g.: (re)starting orcharhino services, as well as backup and restore).


The commands in this guide require root access on the orcharhino host.

Managing the services

orcharhino services like foreman or pulp are managed using systemd. As a result orcharhino services can be managed like any other system service using systemctl [start|stop|restart|status] <service_name>.

However, we generally recommend using the foreman-maintain service utility, which will operate on all orcharhino services at once. Using this utility will ensure services are stopped and started in the proper order and no services will be omitted or forgotten. Running a full orcharhino service restart will also ensure that any configuration file changes (since the relevant service was started) will take effect.

To restart all orcharhino services:

foreman-maintain service restart

To stop all orcharhino services:

foreman-maintain service stop

To start all orcharhino services:

foreman-maintain service start

To show whether a service is enabled or disabled by systemd (only enabled services will automatically start when booting the system):

foreman-maintain service list

To enable all orcharhino services (does not change the current start/stop state of the service):

foreman-maintain service enable

To disable all orcharhino services (does not change the current start/stop state of the service):

foreman-maintain service disable

To show the current state of services (similar to systemctl status <service_name>):

foreman-maintain service status

You can also run foreman-maintain for a single service using the --only flag, or exclude services using the --exclude flag:

foreman-maintain service {start|stop|restart|enable|disable|list|status} --only <service_name>
foreman-maintain service {start|stop|restart|enable|disable|list|status} --exclude <service_name1,service_name2>

For more information, see foreman-maintain service --help.


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