Upgrading Oracle Autonomous Health Framework

Learn to upgrade Oracle Autonomous Health Framework on Linux, Unix, and Microsoft Windows operating systems.

Note:

Starting in AHF version 23.7.0, AHF full installers are shipped with Java 11.

Maintaining Oracle Autonomous Health Framework at the Latest Version

Oracle releases a new version of Oracle Autonomous Health Framework (AHF) every month.

Standard Release Update Revisions (RURs) automatically update AHF. However, RURs do not include updates to the complete Oracle Database support tools bundle.

To obtain the latest AHF release together with the Oracle Database support tools bundle, download it from My Oracle Support Doc ID 2550798.1.

Upgrading AHF is similar to performing a first-time installation.

To upgrade an existing AHF installation:

Download and extract the latest AHF release.
As the root user, run:
```
ahf_setup
```
The installer detects the existing AHF installation and upgrades it in place.

For a cluster installation, an upgrade does not require SSH connectivity between the cluster nodes when AHF is already installed. AHF uses the existing secure daemon socket communication between the hosts to perform the cluster upgrade.

For more information, see My Oracle Support Doc ID 2550798.1.

Automatically Upgrading Oracle Autonomous Health Framework to the Latest Version

AHF AutoUpgrade enables Oracle Autonomous Health Framework (AHF) to be upgraded automatically without manually downloading and running ahf_setup.

Note:

You must have privileges to manage the existing AHF installation to run AHF AutoUpgrade commands.

AHF AutoUpgrade Support

AHF AutoUpgrade is supported on:

Linux
Solaris
AIX

Note:

openssl is required on all supported platforms for AHF AutoUpgrade. If openssl is not installed, AHF AutoUpgrade exits gracefully.
If the AHF download endpoint does not use the default HTTPS port (443), configure the custom port using the ahfctl setupload command.
AHF AutoUpgrade is not supported on HP-UX or Microsoft Windows.
AHF AutoUpgrade is not supported for standalone (extract) AHF installations, except for Exadata dom0.
AHF AutoUpgrade by a non-root user is supported only when the existing AHF installation was installed by the same user and is a typical (full) installation. For example, if user X installed AHF, user Y cannot perform the AutoUpgrade.

Automatically Upgrading AHF with the TFA Scheduler

The Oracle Trace File Analyzer (TFA) scheduler periodically checks for a newer AHF version at the configured AHF software stage location or REST endpoint (Object Store).

The TFA scheduler checks for new AHF versions weekly. When a newer version is available, it automatically upgrades AHF without changing the configurations already saved in the existing installation.

Upgrading AHF with the `upgrade` Option

Use the ahfctl upgrade command to upgrade AHF immediately.

The command checks the configured AHF software stage location or REST endpoint (Object Store) for a newer version. If a newer version is available, AHF downloads and installs it.

If a newer version is not available at either location, download the latest AHF package from My Oracle Support (MOS) and place it in the configured software stage location before running the upgrade.

ahfctl upgrade

Configuring AHF AutoUpgrade

Use ahfctl setupgrade to configure AHF AutoUpgrade parameters.

To enable or disable AutoUpgrade and specify the software stage location:

ahfctl setupgrade -autoupgrade <on|off> -swstage <path>

For example:

ahfctl setupgrade -autoupgrade on -swstage /scratch/ahf_stage

To configure additional AutoUpgrade parameters, specify the relevant options together.

Note:

AHF AutoUpgrade configuration parameters are stored in the ahf.properties file.

Disabling AHF AutoUpgrade

To disable AutoUpgrade:

ahfctl setupgrade -autoupgrade off

Alternatively:

ahfctl unsetupgrade -autoupgrade

When AutoUpgrade is disabled, the TFA scheduler does not automatically upgrade AHF.

Unsetting AHF AutoUpgrade Configuration

Use ahfctl unsetupgrade to remove one or more AutoUpgrade configuration parameters.

To remove all parameters:

ahfctl unsetupgrade -all

To remove individual parameters:

ahfctl unsetupgrade [-swstage] [-autoupgrade] [-servicename] [-frequency]

For example, to remove the software stage configuration:

ahfctl unsetupgrade -swstage

Viewing AHF AutoUpgrade Configuration

Use ahfctl getupgrade to display the configured AHF AutoUpgrade parameters.

To display all parameters:

ahfctl getupgrade -all

Example output:

autoupgrade : off
autoupgrade.swstage : /scratch/ahf_stage
autoupgrade.frequency : 30
autoupgrade.servicename : [not set]

Note:

For best results, run the latest AHF version.

Setting AHF AutoUpgrade Parameters

The following example enables AutoUpgrade, specifies a software stage location, and sets the AutoUpgrade frequency:

ahfctl setupgrade -swstage /scratch/ahf_stage -autoupgrade on -frequency 21

Example output:

AHF autoupgrade parameters successfully updated
Successfully synced AHF configuration

To set all available AutoUpgrade parameters interactively:

ahfctl setupgrade -all

Example:

Enter autoupgrade flag <on/off> : on
Enter software stage location : /scratch/ahf_stage
Enter auto upgrade frequency : 30

AHF autoupgrade parameters successfully updated
Successfully synced AHF configuration

Disabling AutoUpgrade

The following command disables AHF AutoUpgrade:

ahfctl setupgrade -autoupgrade off

Example output:

AHF autoupgrade parameters successfully updated
Successfully synced AHF configuration

Unsetting All AutoUpgrade Parameters

To remove all AutoUpgrade configuration parameters:

ahfctl unsetupgrade -all

Example output:

AHF upgrade parameters successfully removed
Successfully synced AHF configuration

To remove only the software stage location:

ahfctl unsetupgrade -swstage

Example output:

Software stage location successfully removed
Successfully synced AHF configuration

Validating the AutoUpgrade Frequency

The AutoUpgrade frequency must be between 1 and 30 days.

For example, the following command is invalid:

ahfctl setupgrade -frequency 0

The command returns an error similar to:

Invalid autoupgrade frequency. Use frequency between 1 and 30

When AHF Is Older Than the Supported Age

When an AHF installation is older than the supported age threshold, AHF prompts you to use ahfctl upgrade to obtain the latest version.

For example:

ahfctl getupload

Autonomous Health Framework is older than 180 days.
please use "ahfctl upgrade" to upgrade to latest version of AHF

continue running original command ...

Run:

ahfctl upgrade

AHF then downloads the latest available version and upgrades the installation.

Example:

Starting download of Autonomous Health Framework from:
https://updates.oracle.com/Orion/Services/download/AHF-LINUX_v20.2.3.zip?aru=23858854&patch_file=AHF-LINUX_v20.2.3.zip

...

Upgrading Autonomous Health Framework ...

Upgrading AHF When a New Version Is Available at the Software Stage

When a newer AHF version is available in the configured software stage, ahfctl upgrade upgrades the existing installation.

Example:

ahfctl upgrade

AHF Installer for Platform Linux Architecture x86_64

AHF Installation Log :
/tmp/ahf_install_211000_31931_2021_03_29-06_54_58.log

Starting Autonomous Health Framework (AHF) Installation

AHF Version: 21.1.0
Build Date: 202103290252

AHF is already installed at /opt/oracle.ahf

Installed AHF Version: 21.1.0
Build Date: 202103290200

Upgrading /opt/oracle.ahf

Shutting down AHF Services
Shutting down TFA
...
Successfully shutdown TFA.

Starting AHF Services
Starting TFA.
Waiting up to 100 seconds for TFA to be started.
...
Successfully started TFA Process.

TFA Started and listening for commands

No new directories were added to TFA

INFO: Starting exachk scheduler in background.
Details for the process can be found at:
/u01/app/grid/oracle.ahf/data/busm01client01/diag/exachk/compliance_start_290321_065650.log

AHF is sucessfully upgraded to latest version

.----------------------------------------------------------------------.
| Host   | TFA Version | TFA Build ID             | Upgrade Status |
+--------+-------------+--------------------------+----------------+
| node01 | 21.1.0.0.0  | 21100020210329025257     | UPGRADED       |
| node02 | 21.1.0.0.0  | 21100020210329020041     | UPGRADED       |
'--------+-------------+--------------------------+----------------'

The command may identify nodes that require the upgrade to be run separately.

For example:

Please upgrade AHF on the below mentioned nodes as well using
ahfctl upgrade node02

Configuring a REST Endpoint for AHF Download

Use ahfctl setupload to configure a REST endpoint from which AHF can download the latest installer.

The configuration name must be ahf_upgrade_loc unless you later override it with ahfctl setupgrade -servicename.

For example:

ahfctl setupload \
  -name ahf_upgrade_loc \
  -type https \
  -url 'https://<IP_Address>/rest/tfa-processor/download?osName=LINUX&ahfVersion=%2720.2%27' \
  -https_token "X-TFA-Authorization: <>" \
  -header Content-Type:application/json

Note:

Use ahf_upgrade_loc as the configuration name to identify the endpoint as the AHF download source.

To change the service name used for AutoUpgrade:

ahfctl setupgrade -autoupgrade_servicename <new_name>

At the REST endpoint, AHF downloads the installer ZIP when a newer AHF version is available.

Configuring a REST Endpoint with a Custom Port

If the AHF download service uses a port other than 443, specify the port with -port.

For example:

ahfctl setupload \
  -name ahf_upgrade_loc \
  -type https \
  -url 'https://<IP_Address>/rest/tfa-processor/download?osName=LINUX&ahfVersion=%2720.2%27' \
  -https_token "X-TFA-Authorization: <>" \
  -header Content-Type:application/json \
  -port <port_number>

Configuring an Object Store Endpoint

You can also use an Object Store as the AHF software source.

For example:

ahfctl setupload \
  -name ahf_upgrade_loc \
  -type https \
  -user testuser \
  -url https://<host.domain>/v1/<bucket_path> \
  -password

The Object Store can contain either the ahf_setup installer or the AHF installer ZIP.

AHF first attempts to download ahf_setup. If ahf_setup is not available, AHF searches for the installer ZIP.

To configure the Object Store endpoint:

ahfctl setupload -name upload_end_point -type https

The command prompts for the endpoint credentials and URL.

Example:

Enter upload_end_point.https.user: john.doe@acme.com
Enter upload_end_point.https.password:
Enter upload_end_point.https.url: https://swiftobjectstorage.acme.com/v1/dbaasimage/CAIPING

Successfully synced AHF configuration

Configure AutoUpgrade to use the Object Store endpoint:

ahfctl setupgrade -servicename upload_end_point

Example output:

Successfully synced AHF configuration
AHF autoupgrade parameters successfully updated

Run the upgrade:

ahfctl upgrade

Example output:

Upload configuration check for: upload_end_point.
Parameters are configured correctly to upload.

AHF-LINUX_v21.1.0.zip successfully downloaded at /opt/oracle.ahf

/opt/oracle.ahf/AHF-LINUX_v21.1.0.zip successfully extracted at /opt/oracle.ahf

AHF software signature has been validated successfully

Configuring My Oracle Support Upload

You can configure an HTTPS upload endpoint for service uploads using ahfctl setupload.

For example:

ahfctl setupload \
  -name mosconf1 \
  -type https

The command prompts for the required endpoint credentials and URL.

Example:

Enter mosconf1.https.user : john.doe@acme.com
Enter mosconf1.https.password :
Enter mosconf1.https.url : https://transport.oracle.com/upload/issue

Successfully synced AHF configuration

Upload configuration set for:
mosconf1

type:
https

mosconf1.https.user:
john.doe@acme.com

mosconf1.https.password:
******

mosconf1.https.url:
https://transport.oracle.com/upload/issue

Service upload parameters successfully stored.

Upgrading AHF on Local File System, Oracle ACFS, and NFS

You can configure Oracle Autonomous Health Framework (AHF) AutoUpgrade to use a software stage located on a local file system, Oracle Advanced Cluster File System (Oracle ACFS), or Network File System (NFS).

The behavior of the AHF installer after an upgrade depends on the type of file system used for the software stage.

File System	AHF Installer ZIP After Upgrade	Extracted AHF Files After Upgrade
Local file system	Removed	Removed
Oracle ACFS	Removed	Retained so that other nodes can use them
NFS	Removed	Retained

Local File System

When the software stage is a local file system and the AHF installer ZIP exists in the stage location, AHF removes the installer ZIP and all extracted files from the stage location after a successful upgrade.

Configure and Upgrade AHF

Configure the AutoUpgrade parameters:

ahfctl setupgrade -all

Example:

Enter autoupgrade flag <on/off> : on
Enter software stage location : /opt/local
Enter auto upgrade frequency : 30

AHF autoupgrade parameters successfully updated
Successfully synced AHF configuration
refreshConfig() completed successfully.

Verify that the AHF installer ZIP exists in the software stage:
```
ls /opt/local
```
Example:
```
AHF-LINUX_v22.1.0.zip
```
Note:
The Oracle Trace File Analyzer (TFA) scheduler runs ahfctl upgrade -nomos according to the configured AutoUpgrade frequency. In this example, the upgrade runs every 30 days at 3 AM. You can also initiate an upgrade manually by running ahfctl upgrade.

Run the upgrade:

ahfctl upgrade

Example output:

AHF Installer for Platform Linux Architecture x86_64

AHF Installation Log :
/tmp/ahf_install_221000_139332_2022_03_09-02_09_42.log

Starting Autonomous Health Framework (AHF) Installation

AHF Version: 22.1.0
Build Date: 202203081742

AHF is already installed at /opt/oracle.ahf

Installed AHF Version: 22.1.0
Build Date: 202203081714

Upgrading /opt/oracle.ahf

Shutting down AHF Services
Nothing to do !

Shutting down TFA
Removed symlink /etc/systemd/system/multi-user.target.wants/oracle-tfa.service.
Removed symlink /etc/systemd/system/graphical.target.wants/oracle-tfa.service.

Successfully shutdown TFA..

Starting AHF Services
Starting TFA..
Waiting up to 100 seconds for TFA to be started..
. . . . .
Successfully started TFA Process..

TFA Started and listening for commands

No new directories were added to TFA
Directory /u01/app/grid/crsdata/scao05adm07/trace/chad
was already added to TFA Directories.

INFO: Starting exachk scheduler in background.
Details for the process can be found at:
/u01/app/grid/oracle.ahf/data/scao05adm07/diag/exachk/compliance_start_090322_021151.log

AHF is successfully upgraded to latest version

.-------------------------------------------------------------------.
| Host        | TFA Version | TFA Build ID         | Upgrade Status |
+-------------+-------------+----------------------+----------------+
| scao05adm07 | 22.1.0.0.0  | 22100020220308174218 | UPGRADED       |
| scao05adm08 | 22.1.0.0.0  | 22100020220308171448 | UPGRADED       |
'-------------+-------------+----------------------+----------------'

Moving /tmp/ahf_install_221000_139332_2022_03_09-02_09_42.log to
/u01/app/grid/oracle.ahf/data/scao05adm07/diag/ahf/

Please upgrade AHF on the below mentioned nodes as well using
ahfctl upgrade scao05adm08

Verify that the AHF installer ZIP and extracted files have been removed from the stage location:
```
ls -lart /opt/local
```
Example:
```
drwxr-xr-x 2 root root 2 Mar  9 02:32 .
drwxr-xr-x 25 root sys 28 Mar  9 02:32 ..
```

Oracle Advanced Cluster File System (Oracle ACFS)

When the software stage is located on Oracle ACFS and the AHF installer ZIP exists in the stage location, AHF removes the installer ZIP after the upgrade but retains the extracted AHF binaries.

Retaining the extracted binaries allows other nodes that use the same ACFS stage location to consume the existing AHF installation files.

Configure and Upgrade AHF

Configure the AutoUpgrade parameters:

ahfctl setupgrade -all

Example:

Enter autoupgrade flag <on/off> : on
Enter software stage location : /acfs01
Enter auto upgrade frequency : 30

AHF autoupgrade parameters successfully updated
Successfully synced AHF configuration
refreshConfig() completed successfully.

Verify the contents of the ACFS software stage:

ls -lart /acfs01

Example:

total 387862
-rw-r--r--+ 1 root root       1520 Apr 30  2020 README.txt
-rw-r--r--+ 1 root root        625 Nov  1 15:15 oracle-tfa.pub
-rw-r--r--+ 1 root root        384 Jan  4 22:45 ahf_setup.dat
-rwxr-xr-x+ 1 root root  392587026 Mar  9 01:55 ahf_setup

Run the upgrade:
```
ahfctl upgrade
```
The upgrade process is similar to the local file system example. AHF upgrades the existing installation and restarts the required services.

Verify that the AHF installer ZIP has been removed while the extracted AHF binaries remain:

ls -lart /acfs01

Example:

-rw-r--r--+ 1 root root       1520 Apr 30  2020 README.txt
-rw-r--r--+ 1 root root        625 Nov  1 15:15 oracle-tfa.pub
-rw-r--r--+ 1 root root        384 Jan  4 22:45 ahf_setup.dat
-rwxr-xr-x+ 1 root root  392587026 Mar  9 01:55 ahf_setup

Network File System (NFS)

When the software stage is located on NFS, AHF handles the stage contents differently depending on whether the installer ZIP or extracted AHF binaries are present.

If the stage contains the AHF installer ZIP, AHF prompts you to extract the ZIP.
If the stage contains already-extracted AHF binaries, AHF retains them after the upgrade.
If the stage contains the AHF installer ZIP, AHF removes the ZIP after a successful upgrade.

Configure and Upgrade AHF

Configure the AutoUpgrade parameters:

ahfctl setupgrade -all

Example:

Enter autoupgrade flag <on/off> : on
Enter software stage location : /export/sheisey_R/ahf_stage

Stage location /export/sheisey_R/ahf_stage file system type is NFS.
User needs to unzip AHF zip placed at NFS file system.

Enter auto upgrade frequency : 30

AHF autoupgrade parameters successfully updated
Successfully synced AHF configuration

Verify whether the stage contains an AHF installer ZIP or extracted AHF binaries:

ls -lart /export/sheisey_R/ahf_stage

Example:

-rw-r--r-- 1 root root 389105013 Feb  3 06:08 AHF-LINUX_v22.1.0.zip
-rw-r--r--+ 1 root root       1520 Apr 30  2020 README.txt
-rw-r--r--+ 1 root root        625 Nov  1 15:15 oracle-tfa.pub
-rw-r--r--+ 1 root root        384 Jan  4 22:45 ahf_setup.dat
-rwxr-xr-x+ 1 root root 392587026 Mar  9 01:55 ahf_setup

Run the upgrade:
```
ahfctl upgrade
```
The upgrade process is similar to the local file system and Oracle ACFS examples. AHF upgrades the existing installation and restarts the required services.

Verify that the AHF installer ZIP has been removed and the extracted binaries have been retained:

ls -lart /export/sheisey_R/ahf_stage

Example:

-rw-r--r--+ 1 root root       1520 Apr 30  2020 README.txt
-rw-r--r--+ 1 root root        625 Nov  1 15:15 oracle-tfa.pub
-rw-r--r--+ 1 root root        384 Jan  4 22:45 ahf_setup.dat
-rwxr-xr-x+ 1 root root 392587026 Mar  9 01:55 ahf_setup

Summary of Stage-Location Behavior

The software stage behavior after an AHF upgrade can be summarized as follows:

Stage Location	Installer ZIP	Extracted Files
Local file system	Removed	Removed
Oracle ACFS	Removed	Retained
NFS	Removed	Retained

Upgrading Oracle Autonomous Health Framework

Maintaining Oracle Autonomous Health Framework at the Latest Version

Automatically Upgrading Oracle Autonomous Health Framework to the Latest Version

AHF AutoUpgrade Support

Automatically Upgrading AHF with the TFA Scheduler

Upgrading AHF with the upgrade Option

Configuring AHF AutoUpgrade

Disabling AHF AutoUpgrade

Unsetting AHF AutoUpgrade Configuration

Viewing AHF AutoUpgrade Configuration

Setting AHF AutoUpgrade Parameters

Disabling AutoUpgrade

Unsetting All AutoUpgrade Parameters

Validating the AutoUpgrade Frequency

When AHF Is Older Than the Supported Age

Upgrading AHF When a New Version Is Available at the Software Stage

Configuring a REST Endpoint for AHF Download

Configuring a REST Endpoint with a Custom Port

Configuring an Object Store Endpoint

Configuring My Oracle Support Upload

Upgrading AHF on Local File System, Oracle ACFS, and NFS

Local File System

Configure and Upgrade AHF

Oracle Advanced Cluster File System (Oracle ACFS)

Configure and Upgrade AHF

Network File System (NFS)

Configure and Upgrade AHF

Summary of Stage-Location Behavior

Upgrading AHF with the `upgrade` Option