Upgrade Guide

orcharhino is a large software suite, with multiple components undergoing active development. To take advantage of new features as well as bug fixes, it is necessary to upgrade orcharhino when new versions are made available by ATIX.

This guide exists to describe the steps that are needed to upgrade orcharhino.

The upgrade guide contains the following subsections:

Background Information

The latest orcharhino release notes can be found here: https://orcharhino.com/release-notes/

orcharhino is normally shipped as part of a specific CentOS version maintained by ATIX. As such, upgrades to the CentOS host orcharhino is running on happen as part of the orcharhino upgrade as detailed in this guide. This ensures orcharhino will run in the same environment it was built for and tested in.


ATIX provides guided upgrades (performed by our consultants) as part of our support subscriptions. If you would like to make use of this service, feel free to contact us.


If a customer wishes to perform an upgrade on their own, then this always happens at their own risk. In such cases ATIX does not offer support for recovery from a failed upgrade. Make sure you heed all of the instructions, warnings, and recommendations presented in this guide so you can always roll back to a state from before the upgrade.


Upgrading the orcharhino packages (yum update or yum update orcharhino) without running foreman-installer --upgrade can leave orcharhino in an inconsistent state. Please make sure you always either perform all of the upgrade steps below, or roll back your system to a state from before the start of the upgrade process.

In general, you should never run yum update on the orcharhino host, unless you are planning to perform all the steps from this guide. If you know what you are doing, and you want to upgrade some package without upgrading orcharhino, run yum update <package_name> to explicitly upgrade just that package.

Version Specific Instructions

If there are additional instructions associated with the upgrade to a specific orcharhino version, then these are always published in the ATIX customer service portal. You can always find them via the link https://atix.de/upgradenotes. Once logged in to the service portal you will need to follow the link to “Versions-spezifische Upgrade-Schritte”. Make sure you always read any version specific instructions, before starting the upgrade process!


If you are skipping several versions in a single upgrade, make sure you read all of the version specific instructions for any intermediary versions. For example, if you are upgrading from orcharhino 4.0 to 4.2 then you should read any instructions for the upgrade to version 4.2, as well as any instructions for the upgrade to version 4.1! If in doubt, please contact ATIX support.

Upgrade Steps


It is highly recommended to check for any version specific upgrade instructions before upgrading your orcharhino.


It is highly recommended to create a snapshot/backup before upgrading your orcharhino (step 1 below). This will allow you to roll back if anything goes wrong.


You will require root access on the orcharhino host.

Perform the following steps to upgrade orcharhino:

  1. Run the pre-upgrade check:

    foreman-rake katello:upgrade_check


    The pre upgrade check will only pass, if there are no long running tasks (which would be interrupted by the upgrade). However, it is up to the user to ensure that no new tasks are started between running the upgrade check and completing step 3 of the upgrade process.

  2. Backup your orcharhino system.


    We generally recommend running orcharhino as a virtual server and performing a system snapshot at this point. See the backup mechanisms section for more information.

  3. Perform the upgrade itself.

    1. Upgrade the packages (of both orcharhino and CentOS):

      yum update


      Yum may appear to be stuck on the final package of the upgrade for a very long time. This is expected since yum is performing posttrans actions after all packages are upgraded without providing any output. This is not an indication that the upgrade has failed.

    2. Upgrade orcharhino components:

      foreman-installer --upgrade


      Running foreman-installer will stop and restart orcharhino services as needed. Some orcharhino components may take some time until they are back online. Please be patient before concluding the upgrade has failed.

  4. Verify that everything works.

    1. Check whether all services have restarted:

      foreman-maintain service status
    2. Check the backend system status:

      Important system components are listed in the Backend System Status area of the about page (navigate to Administer > About in the web interface). The info box should list each component with “OK” as its status.

    3. Check that important background tasks are running:

      The tasks “Listen on Candlepin events” and “Monitor Event Queue” should always have a running instance. See the background tasks section from the troubleshooting chapter for more information.

You now have a new orcharhino version. Enjoy!

Once you have upgraded successfully, it may be useful to create another snapshot/backup. This will allow you to roll back to the state immediately after upgrading, saving you the need to repeat the upgrade if a roll back becomes necessary.


Newer snapshots will include lots of back references to older snapshots. This can be inefficient if too many snapshots are kept at the same time. It is recommended to limit the number of snapshots to no more than three per host. Consider deleting older snapshots when creating new ones.