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.
ATIX sells upgrades (performed by our consultants) as part of it’s optional support package. If you would like to make use of this service, instead of upgrading orcharhino yourself, please feel free to contact us. (See also: Contact).
The upgrade guide contains the following subsections:
Notes and Background¶
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.
It is highly recommended to create a system snapshot prior to upgrading orcharhino! This will allow you to roll back if anything goes wrong.
To upgrade orcharhino we require root access on the host orcharhino is running on.
We perform the following steps to upgrade orcharhino (commands are run as root, on the host orcharhino is running on):
Perform pre-upgrade checks.
Check that there are no running tasks (which might be interrupted by the upgrade):
Stop all orcharhino services, to ensure no new tasks will be started:
(optional, recommended) Create a snapshot of the orcharhino system.
This step is highly dependent on where and how you are running orcharhino, and cannot be documented here with a one size fits all approach.
Perform the upgrade.
Upgrade the packages (both of orcharhino and the CentOS it runs on):
Upgrade orcharhino components:
Upgrading the orcharhino packages (
yum update orcharhino) without running
foreman-installer --upgradecan leave orcharhino in an inconsistent state. Please make sure you always either perform all of the upgrade steps, or roll back your system to a state from before the start of the upgrade process.
In general, you should never run
yum updateon 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.
Check that everything works!
foreman-installerwill restart orcharhino after the upgrade. Some orcharhino components (like
foreman_proxy) may take 1-2 Minutes until they are back online. Please be patient before concluding the upgrade failed.
Check whether all services have restarted:
Check the backend system status:
Important system components are listed under Administer > About > Backend System Status in the web interface. (See also: About). The Backend System Status info box should list the status as “OK” for all components.
Check that important background tasks are running:
You now have a new orcharhino version. Enjoy!
Once you have upgraded successfully, it may be useful to create another snapshot. This will allow you to roll back to the state immediately after upgrading, saving you the need to repeat the upgrade if a rollback 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.