Upgrading orcharhino Proxy

This guide describes how to upgrade an orcharhino Proxy to a newer version.

orcharhino is a large software suite undergoing active development. It is necessary to upgrade orcharhino when ATIX releases new versions to take advantage of its new features and bug fixes. Refer to the orcharhino Release Notes for more information.

ATIX provides guided upgrades performed by our consultants as part of our support subscriptions. Please contact us if you would like to make use of this service.

Ensure you carefully read all of the instructions, warnings, and recommendations presented in this guide and the appropriate version specific orcharhino Upgrade Notes in the ATIX Service Portal. ATIX does not offer support for recovery from a failed upgrade if you did not follow our upgrade guide.

Version specific upgrade instructions are published in the ATIX Service Portal. Log in with your ATIX Support login credentials and follow the link to the orcharhino Upgrade Notes. Ensure you carefully read the version specific instructions before starting the upgrade and always create a snapshot/backup as part of your upgrade.

If you are skipping versions in a single upgrade, read all of the version specific instructions for all intermediary versions. For example, if you are upgrading from orcharhino 5.10 to 5.12, read both the instructions for the upgrade to version 5.11 and 5.12. Please contact us if you are unsure on how to start with your orcharhino upgrade.

This upgrade guide is for orcharhino Server/Proxy running on CentOS 7, Oracle Linux 7, and Red Hat Enterprise Linux 7 only. orcharhino 6.2 does not support upgrading orcharhino Server and orcharhino Proxies from 6.1 on CentOS 7, Oracle Linux 7, and Red Hat Enterprise Linux 7 to 6.2 on Alma Linux 8, Oracle Linux 8, Red Hat Enterprise Linux 8, and Rocky Linux 8.

You can use the guide to upgrade orcharhino Server/Proxy from 6.1 to 6.2.

With orcharhino 6.3, you can upgrade from orcharhino 6.2 on CentOS 7, Oracle Linux 7, and Red Hat Enterprise Linux 7 to orcharhino 6.3 on Alma Linux 8, Oracle Linux 8, Red Hat Enterprise Linux 8, and Rocky Linux 8.

ATIX does not support using third party repositories on your orcharhino Server or orcharhino Proxies. Resolving package conflicts or other issues due to third party or custom repositories is not part of your orcharhino support subscription. Please contact us if you have any questions.

Providing Content for orcharhino Proxy

orcharhino Proxies obtain their content, which is identical to the packages for orcharhino Server, from the orcharhino Server they are connected to.

Providing Content Using orcharhino Configuration Job Template

You can use the the job template orcharhino Configuration on orcharhino Server to provide content for orcharhino Proxies. Run the job template to automatically create the Smart Proxy Atix product, include the repository in the content view, and publish a new version of the content view. For more information on how to run remote execution jobs on orcharhino Server, see Running Remote Execution Jobs on orcharhino Server.

Providing Content Manually

Navigate to Content > Products and create a product named Smart Proxy Atix.
Navigate to Content > Products, select the Smart Proxy Atix product, and add a repository of type yum. On the Repositories tab (1), click the New Repository button (2):

Add the latest repository as found on your orcharhino Servers in /etc/yum.repos.d/redhat.repo.
Navigate to Content > Content Views, select the content view of the orcharhino Proxy, and add the latest repository.
Navigate to Content > Content Views, select the content view of the orcharhino Proxy, and publish a new version.

Click Publish New Version to publish a new version of the content view for your orcharhino Proxy.

Performing the Upgrade

Prerequisites

You have prepared content for orcharhino Proxy on your orcharhino.
You have a one time SSH connection to your orcharhino Proxy.

Procedure

Verify that the repositories on orcharhino Server are also available on your orcharhino Proxy by running the following command on your orcharhino Proxy.
- On Alma Linux 8, Oracle Linux 8, Red Hat Enterprise Linux 8, and Rocky Linux 8:
  # dnf repolist
- On CentOS 7, Oracle Linux 7, and Red Hat Enterprise Linux 7:
  # yum repolist
Update packages on your orcharhino Proxy.
- On Alma Linux 8, Oracle Linux 8, Red Hat Enterprise Linux 8, and Rocky Linux 8:
  # dnf update
- On CentOS 7, Oracle Linux 7, and Red Hat Enterprise Linux 7:
  # yum update
Upgrade your orcharhino Proxy:
```
# foreman-installer
```

Upgrading orcharhino Proxies from 5.12 to 6.0

All orcharhino Proxies that you have upgraded at least to orcharhino 5.12.1 are supported for use with orcharhino Server 6.0, so you do not need to upgrade your orcharhino Proxies right away. There are two possible ways to use orcharhino Proxies 6.1, both require some planning ahead:

You can upgrade your existing orcharhino Proxies 5.12 to 6.0. Note that this requires you to resynchronize all content from orcharhino Server to orcharhino Proxy. For more information, see Upgrading orcharhino Proxies 5.12 with Pulp or Upgrading orcharhino Proxies 5.12 in Pass-Through Mode.

After upgrading orcharhino Proxies to 6.0, you can upgrade them to 6.1. For more information, see Providing Content for orcharhino Proxy and Performing the Upgrade.
You can provision and configure additional orcharhino Proxies 6.1 and reregister hosts. You have to migrate managed hosts from an orcharhino Proxy to another orcharhino Proxy using subscription-manager. You also have to synchronize content from orcharhino Server to orcharhino Proxy and potentially recreate your DHCP and DNS settings. Depending on how you configure managed hosts, you have to adapt the Puppet Proxy, Puppet CA Proxy, OpenSCAP Proxy, and Salt Master configuration and provide configuration objects. For more information, see Installing orcharhino Proxy and Synchronizing Configuration Management Objects.

You cannot upgrade orcharhino Proxies in pass-through mode using Squid to version 6.0. For more information, see Upgrading orcharhino Proxies 5.12 in Pass-Through Mode to 6.1.

Upgrading orcharhino Proxies with Pulp from 5.12 to 6.0

There are two significant changes for the upgrade from 5.12 to 6.0 in contrast to the normal upgrade procedure:

During the upgrade to 6.0, all Pulp2 content is removed from orcharhino Proxies using the foreman-maintain content remove-pulp2 command. Ensure you have both foreman-maintain and katello-common installed on your upgraded orcharhino Proxy:
```
# yum install -y foreman-maintain katello-common
```
After the upgrade to 6.0, you must resynchronize all content from your orcharhino Server, either by using the button in the orcharhino management UI, or using the following hammer command: hammer capsule content synchronize --name My_orcharhino_Proxy --async.

You cannot migrate content from Pulp2 to Pulp3 on your orcharhino Proxy as you do for your orcharhino Server. However, you can remove the Pulp2 content and resynchronize content from your orcharhino Server to your orcharhino Proxy with Pulp3. This method has the disadvantage of increased network traffic and down time from resynchronizing content. If this downtime is unacceptable, you can alternatively deploy an entirely new orcharhino Proxy on a separate host, synchronize the content, and then switch your managed hosts from the old orcharhino Proxy to the new one.

Upgrading orcharhino Proxies in Pass-Through Mode from 5.12 to 6.0

You cannot upgrade orcharhino Proxies 5.12 in pass-through mode using Squid. Instead, you have to register your managed hosts to orcharhino Proxies with download policy streamed. For more information, see Changing the Download Policy for orcharhino Proxies.

You can use orcharhino Proxies with download policy streamed to replace orcharhino Proxies 5.12 in pass-through mode using Squid. Managed hosts request artifacts from orcharhino Proxies which in turn request them from orcharhino Server without storing or caching content locally.

Procedure

In the orcharhino management UI, navigate to Monitor > Jobs.
Click Run Job.
In the Job category field, select orcharhino Configuration.
In the Job template field, select orcharhino Configuration - Migrate to orcharhino Proxy.
In the Search query field, enter a regular expression to match hosts that you want to register to an orcharhino Proxy that are currently registered with orcharhino Server through an orcharhino Proxy in pass-through mode using Squid.
In the orcharhino Proxy FQDN field, enter the FQDN of your orcharhino Proxy with download policy streamed.
In the Activation Key field, enter an activation key for the managed hosts.
Click Submit to register managed hosts with the selected orcharhino Proxy.

Upgrading orcharhino Proxies from 6.0 to 6.1

orcharhino Server 6.1 only works with orcharhino Proxies 6.1, therefore, you have to upgrade your existing orcharhino Proxies from 6.0 to 6.1.

Procedure

Before starting to upgrade your orcharhino Proxy from 6.0 to 6.1, you need to replace the certificates on your orcharhino Proxy. You can generate an archive containing the certificates on your orcharhino Server after you have upgraded it to 6.1.

If you are using custom certificates:

# foreman-proxy-certs-generate \
--certs-tar "/root/orcharhino-proxy.network2.example.com-certs.tar" \
--foreman-proxy-fqdn "orcharhino-proxy.network2.example.com" \
--server-ca-cert /root/certs/orcharhino-proxy.ca \
--server-cert /root/certs/orcharhino-proxy.cert \
--server-cert-req /root/certs/orcharhino-proxy.csr \
--server-key /root/certs/orcharhino-proxy.key

If you are using the self-signed original certificates:

# foreman-proxy-certs-generate \
--certs-tar "orcharhino-proxy.network2.example.com-certs.tar" \
--foreman-proxy-fqdn "orcharhino-proxy.network2.example.com"

Copy the created archive from your orcharhino Server to your orcharhino Proxy:

# scp /root/orcharhino-proxy.network2.example.com-certs.tar root@orcharhino-proxy.network2.example.com:/root/orcharhino-proxy.network2.example.com-certs.tar

You can now proceed with the normal upgrade steps on your orcharhino Proxy. For more information, see Providing Content for orcharhino Proxy and Performing the Upgrade.

Migrating Managed Hosts from orcharhino Proxy to Another orcharhino Proxy

There are several aspects you have to keep in mind if you plan to migrate managed hosts from orcharhino Server or orcharhino Proxy to another orcharhino Proxy. The procedure depends on your IT infrastructure and your orcharhino setup. If you are unsure how to do this, please contact us.

In general, we recommend updating your orcharhino Proxies. If you want to deploy new orcharhino Proxies instead, ensure you keep the following in mind:

Steps on managed hosts

Register your managed hosts to your orcharhino Proxy. You have to change the certificates for subscription-manager and re-register your host with your target orcharhino Proxy.
If you configure your managed host using Puppet or Salt, you need to change the respective orcharhino Proxy for Puppet Proxy or Salt Master.
If your managed host relies on orcharhino Proxy for DNS, you need to change the DNS on your managed host.

Steps on orcharhino Proxies

If your orcharhino Proxy acts as Puppet Master or Salt Master, you need to copy the Puppet or Salt certificates to your target orcharhino Proxy.
If you rely on configuration management objects such as Ansible roles, Puppet modules, or Salt states, you have to copy them to your target orcharhino Proxy. For more information, see Synchronizing Configuration Management Objects.
If your orcharhino Proxy provides DHCP and/or DNS for its subnet, ensure to migrate all DHCP and/or DNS entries to your target orcharhino Proxy.
By design, each orcharhino Proxy has its own SSH key pair. If you configure managed hosts using Ansible through your orcharhino Proxy, you have to migrate the used SSH key to your target orcharhino Proxy.