1.1 Quick Start Guide

This section explains how to install and configure Oracle ORAchk and Oracle EXAchk. Review other topics in this section for additional information.

1.1.1 Overview of Oracle ORAchk and Oracle EXAchk

Oracle ORAchk and Oracle EXAchk provide a lightweight and non-intrusive health check framework for the Oracle stack of software and hardware components.

Use Oracle EXAchk for all Oracle engineered systems except Oracle Database Appliance. For Oracle Database Appliance, use Oracle ORAchk.

You have access to Oracle ORAchk and Oracle EXAchk as a value add-on to your existing support contract. There is no additional fee or license required to run Oracle ORAchk and Oracle EXAchk.

Features of Oracle ORAchk and Oracle EXAchk

  • Automates risk identification and proactive notification before business is impacted

  • Runs health checks based on critical and reoccurring problems

  • Runs in your environment with no need to send anything to Oracle

  • Enables you to schedule email health check reports

  • Integrates the findings into other tools of your choice

1.1.2 Installing Oracle ORAchk and Oracle EXAchk

Follow these procedures to install Oracle ORAchk and Oracle EXAchk.

Note:

If your Oracle Exadata Database machine is enrolled in the Oracle Platinum Services: Exadata Exachk Automation Project, then there is a separate installation method described in My Oracle Support Note 2043991.1.

  1. Download the latest version of the health check tool zip file.

    Note:

    Oracle ORAchk is pre-installed with the database in the $ORACLE_HOME/suptools/orachk directory.

    To update to the latest version, see “Updating to the Latest Version of Oracle ORAchk and Oracle EXAchk”.

    • For Oracle ORAchk, download orachk.zip or orachk_idm.zip for Oracle ORAchk with IAM support.

    • For Oracle EXAchk, download exachk.zip.

  2. Copy the zip file to the installation directory on the systems that you want to check.

    Note:

    Oracle ORAchk and Oracle EXAchk are Oracle RAC database cluster aware. Install Oracle ORAchk and Oracle EXAchk on one node of the cluster to check all nodes in the cluster.
  3. If Oracle Clusterware is installed, then:
    • Install Oracle EXAchk in /opt/oracle.SupportTools/exachk as the Oracle Grid Infrastructure home owner

    • Install Oracle ORAchk in CRS_HOME/suptools/orachk as the Oracle Grid Infrastructure home owner

  4. If Oracle Clusterware is not installed, then:
    • Install Oracle EXAchk in /opt/oracle.SupportTools/exachk as root

    • Install Oracle ORAchk in a convenient location as root (if possible)

      Or

      Install Oracle ORAchk in a convenient location as Oracle software install user or Oracle Database home owner

Note:

If the performance is acceptable, then stage Oracle ORAchk and Oracle EXAchk on a shared network drive.

To run Oracle ORAchk and Oracle EXAchk on a read-only NFS server, modify the permissions of the .cgrep directory and the scripts within it at least to 555.

chmod –R 555 .cgrep

1.1.2.1 Installing or Upgrading Oracle ORAchk and Oracle EXAchk RPMs

Follow these steps to install or upgrade Oracle ORAchk and Oracle EXAchk RPMs on Linux.

  1. Go to https://linux-update.oracle.com.
  2. Login to the server.

    And if needed, register your email address with a valid CSI if no user present yet.

  3. Register each machine that you are interested in.
    1. Login to the machine as root.
    2. Type uln_register, and follow the prompts.
  4. Now go back to the ULN user interface.
    1. Login to https://linux-update.oracle.com.
    2. For each machine that requires (or could potentially use) Oracle ORAchk or Oracle EXAchk:
      1. Click on the system.

      2. On the systems page, click Manage Subscriptions.

      3. Add the Packages for Oracle Stack Health Checks.

      4. Click Save Subscriptions.

      5. Accept the license.

  5. Now on the machine, run the following commands:
    # yum install orachk
    # yum install exachk

    For example:

    # yum install exachk
    Loaded plugins: refresh-packagekit, rhnplugin, security, ulninfo
    This system is receiving updates from ULN.
    Setting up Install Process
    Resolving Dependencies
    --> Running transaction check
    ---> Package exachk.x86_64 0:18.2.0_20180521-2 will be installed
    --> Finished Dependency Resolution
    ...etc...
    
    Upgrading the exachk package:
    
    # yum update exachk
    Loaded plugins: refresh-packagekit, rhnplugin, security, ulninfo
    This system is receiving updates from ULN.
    Setting up Update Process
    Resolving Dependencies
    --> Running transaction check
    ---> Package exachk.x86_64 0:18.2.0_20180521-2 will be updated
    ---> Package exachk.x86_64 0:18.3.0_20180808-2 will be an update
    --> Finished Dependency Resolution
    
    Dependencies Resolved
    
    ===========================================================================================================
     Package             Arch       Version                Repository                                      Size
    ===========================================================================================================
    Updating:
     exachk              x86_64     18.3.0_20180808-2      ol6_x86_64_healthcheck_diag                     76 M
    
    Transaction Summary
    ===========================================================================================================
    Upgrade       1 Package(s)

1.1.3 Common Oracle ORAchk and Oracle EXAchk Prerequisites

Review the checklist for SSH connectivity and required user privileges to run health checks.

1.1.3.1 SSH Connectivity and Access

In a clustered database environment, Oracle ORAchk and Oracle EXAchk run health checks on a single node and remotely run on all other cluster nodes.

Remotely running health checks on cluster nodes involves remotely copying files to and from the targets and running commands without providing the passwords.

If security restrictions block, then some commands fail to run. To run those commands successfully, develop alternate plans.

To run health checks remotely on all other cluster nodes from the database server:

  • Configure passwordless SSH equivalency for the same user on each cluster node that runs Oracle ORAchk and Oracle EXAchk on the database server

Note:

If passwordless SSH is not configured in the environment, then Oracle ORAchk or Oracle EXAchk prompts you if it should configure permanent or temporary passwordless SSH in the environment.

Or

  • Provide the private key file for the remote nodes, or allow Oracle ORAchk or Oracle EXAchk to auto-generate the private key file for the remote nodes.

The process used by Oracle ORAchk and Oracle EXAchk to generate the private key is as follows:

  1. SSH as the desired user to remote node and enter the password password to add the system to the SSH known_hosts file.

    You should see something like:
    The authenticity of host '<hostname> (<ip>)' can't be established.
    RSA key fingerprint is fb:78:d1:6a:5c:62:ea:c4:85:20:76:f6:a9:01:1e:b4.
    Are you sure you want to continue connecting (yes/no)? yes
    Warning: Permanently added 'hostname>,<ip>' (RSA) to the list of known hosts.
  2. Log in to the remote node, and generate private and public key pair on the remote node exactly as follows.

    Replace hostname and username with your actual hostname and desired username.

    # ssh-keygen -f $HOME/.ssh/id_dsa.host.user -N ''

    For example, if your remote node is cehaovmsp1080 and your desired run user is root, then log in to that host and run:

    # ssh-keygen -f $HOME/.ssh/id_dsa.cehaovmsp1080.root -N ''

    Running the command creates two files in the $HOME/.ssh directory.

    [root@cehaovmsp1080 .ssh]# ls -ltr
    total 8
    -rw-------. 1 root root 1675 May 9 12:27 id_dsa.cehaovmsp1080.root
    -rw-r--r--. 1 root root 400 May 9 12:27 id_dsa.cehaovmsp1080.root.pub
  3. Copy the contents of public key into the .ssh/authorized_keys file of remote node and then delete the public key from the remote node.

    # cat $HOME/.ssh/id_dsa.hostname.username.pub >> $HOME/.ssh/authorized_keys
    # rm -rf $HOME/.ssh/id_hostname.username.pub

    For example:

    # cat $HOME/.ssh/id_dsa.cehaovmsp1080.root.pub >> $HOME/.ssh/authorized_keys
    # rm -rf $HOME/.ssh/id_dsa.cehaovmsp1080.root.pub
  4. Copy the private key $HOME/.ssh/id_dsa.hostname.username of remote node into the local node, where you will run Oracle ORAchk from, into the $HOME/.ssh directory.

  5. Test through SSH.

    ssh -i $HOME/.ssh/id_dsa.hostname.username hostname date
  6. If the test is successful, then run the Oracle ORAchk daemon.

    # export RAT_SSH_IDENTITY=$HOME/.ssh
    # ./orachk -d start
If you wish to generate your own private key files, then on remote machine use the following commands:
ssh-keygen -f $HOME/.ssh/id_dsa.host.user -N ''
For example:
ssh-keygen -f $HOME/.ssh/id_dsa.myhost67.root -N ''
Running this command generates the following key pair in the $HOME/.ssh/ directory:
id_dsa.myhost67.root (private key / Identity file)
id_dsa.myhost67.root.pub (Public key)
If you are unable to configure passwordless SSH or use the private key file, then
  1. Run health checks on each database server in the cluster using the -localonly command-line option.

  2. Merge the results using the -merge command-line option.

1.1.3.1.1 Storage Servers that are Configured to Deny SSH Access

The following discussion applies to any Oracle engineered system that uses Oracle Exadata storage servers.

Optionally, you can prevent SSH access, also known as "locking" or "locked". All Oracle EXAchk functions involving locked storage servers are run with standard exacli commands from the database server upon which Oracle EXAchk is launched. To temporarily unlock the storage servers that Oracle EXAchk finds locked, provide the user name and credentials that you specified when configuring exacli to lock/unlock storage servers.

See Configuring Security for Oracle Exadata System Software in the Exadata System Software User's Guide.

Oracle EXAchk does not operate upon the storage server attribute accessLevelPerm. If you have set that attribute to remoteLoginDisabled before an Oracle EXAchk run, then it will remain unchanged during and after the Oracle EXAchk run.

Oracle EXAchk operates only upon the storage server attribute accessLevelTemp. For example, starting with the storage servers locked with remoteLoginDisabled:
-bash-4.1# ssh randomceladm01
ssh: connect to host randomceladm01 port 22: Connection refused
-bash-4.1# ssh randomceladm02
ssh: connect to host randomceladm02 port 22: Connection refused
-bash-4.1# ssh randomceladm03
ssh: connect to host randomceladm03 port 22: Connection refused

-bash-4.1# ./exachk -unlockcells all
Enter exacli user name: celluser
Is EXACLI password same on all Storage Servers?[y/n][y] y
Enter password for EXACLI user celluser to unlock Storage Server 192.168.178.225:
.  .  .  .  .  .  .  .  .  .  . 
Storage cell 192.168.178.225 successfully unlocked
Storage cell 192.168.178.226 successfully unlocked
Storage cell 192.168.178.227 successfully unlocked
-bash-4.1# ssh randomceladm03
Last login: Tue Mar  6 12:32:36 2018 from randomadm01.us.oracle.com
-bash-4.1# ssh randomceladm02
Last login: Tue Mar  6 12:32:09 2018 from randomadm01.us.oracle.com
-bash-4.1# ssh randomceladm01
Last login: Tue Mar  6 12:18:57 2018 from randomadm01.us.oracle.com

-bash-4.1# exacli -c celluser@randomceladm01
Password: ************
exacli celluser@randomceladm01> list cell attributes accessLevelPerm,accessLevelTemp
remoteLoginDisabled ((accesslevel=remoteLoginEnabled,starttime=2018-03-06T13:49:15-08:00,
endtime=2018-03-06T14:39:15-08:00,duration=50m,reason=Running Exachk))

As can be seen from the example, Oracle EXAchk implements a temporary window 
with a default expiration time of 50 minutes, to cover the period that Oracle EXAchk 
may be executing on the storage server.  
In normal operation, this temporary window is closed with "-lockcells" during the exachk cleanup routine.  
If exachk is blocked from the cleanup routine, say because of "kill -9", 
the temporary window will expire in it's own good time.

The following example shows the typical Oracle EXAchk execution sequence starting with the storage servers locked.  
You can see by the commands at the end that "remoteLoginDisabled" is still set and there is no temporary window:

./exachk -c X4-2 -profile storage
...
...
Copying plug-ins
. .
Enter exacli user name: celluser
Is EXACLI password same on all Storage Servers?[y/n][y]
Enter password for EXACLI user celluser to unlock Storage Server 192.168.178.225:
.  .  .  .  .  .  .  .  .  .  .  .  . 
Node randomcel01 is configured for ssh user equivalency for root user
Node randomcel02 is configured for ssh user equivalency for root user
Node randomcel03 is configured for ssh user equivalency for root user
.  .  .  .  .  .  .  .  .  .  .  .  .
...
...
Starting to run root privileged commands in background on STORAGE SERVER randomcel01 (192.168.178.225)
Starting to run root privileged commands in background on STORAGE SERVER randomcel02 (192.168.178.226)
Starting to run root privileged commands in background on STORAGE SERVER randomcel03 (192.168.178.227)
Collections from STORAGE SERVER:
------------------------------------------------------------
Collecting - Exadata Critical Issue EX10
...
...
Detailed report (html) -  /root/vern_wagman/exachk_122014/production/lock_doc/exachk_randomclient01_030618_140319/exachk_randomclient01_030618_140319.html
UPLOAD [if required] - /root/vern_wagman/exachk_122014/production/lock_doc/exachk_randomclient01_030618_140319.zip

-bash-4.1# ssh randomceladm01
ssh: connect to host randomceladm01 port 22: Connection refused
-bash-4.1# exacli -c celluser@randomceladm01
Password: ************
exacli celluser@randomceladm01> list cell attributes accessLevelPerm,accessLevelTemp
         remoteLoginDisabled

1.1.3.2 Handling of root Passwords

Handling of root passwords depends on whether you have installed the Expect utility.

Expect automates interactive applications such as Telnet, FTP, passwd, fsck, rlogin, tip, and so on.

  • If you have installed the Expect utility, then specify the root password when you run the health checks for the first time.

    The Expect utility stores the password and uses the stored password for subsequent sessions.

    The Expect utility prompts you to check if the root password is same for all the remote components such as databases, switches, and so on.

  • Specify the password only once if you have configured the same root password for all the components.

    If root password is not the same for all the components, then the Expect utility prompts you to validate the root password every time you run the health checks.

  • If you enter the password incorrectly or the password is changed between the time it is entered and used, then Oracle ORAchk and Oracle EXAchk,
    • Notify you

    • Skip relevant checks

  • Run the health checks after resolving the issues.

    If Oracle ORAchk and Oracle EXAchk skip any of the health checks, then the tools log details about the skipped checks in the report output.

1.1.3.3 Restricted Access to Oracle ORAchk and Oracle EXAchk Output Files

Starting in release 12.2.0.1.4, access to the output files from a given execution is restricted to the user who executed Oracle ORAchk and Oracle EXAchk.

The output files generated from an Oracle ORAchk and Oracle EXAchk run executed by root cannot be read by other users. The output files generated from an Oracle ORAchk and Oracle EXAchk run executed by oracle cannot be read by other standard users. If you wish to make files generated by one user available to other users, then manually grant access.

1.1.3.4 Deciding Which User Should Run Oracle ORAchk or Oracle EXAchk

Run health checks as root. Also, run health checks as the Oracle Database home owner or the Oracle Grid Infrastructure home owner.

Many of the health checks do not require root access. However, you need root privileges to run a subset of health checks.

To run root privilege checks, Oracle ORAchk uses the script root_orachk.sh and Oracle EXAchk uses the script root_exachk.sh.

By default, the root_orachk.sh and root_exachk.sh scripts are created in the $HOME directory used by Oracle ORAchk and Oracle EXAchk. Change the directory by setting the environment variable RAT_ROOT_SH_DIR.

Specify a location for sudo remote access as follows:
export RAT_ROOT_SH_DIR=/mylocation
Add an entry in the /etc/sudoers as follows:
oracle ALL=(root) NOPASSWD:/mylocation/root_orachk.sh
For security reasons, create the root scripts outside of the standard temporary directory in a custom directory. Specify the custom directory using the environment variable RAT_ROOT_SH_DIR:
export RAT_ROOT_SH_DIR=/orahome/oradb/
Specify a location for sudo remote access as follows:
export RAT_ROOT_SH_DIR=/mylocation
Add an entry in the /etc/sudoers as follows:
oracle ALL=(root) NOPASSWD:/mylocation/root_orachk.sh

Note:

Specify full paths for the entries in the /etc/sudoers  file. Do not use environment variables.

  • (recommended) Run as root: Use root user credentials to run Oracle ORAchk and Oracle EXAchk.

    The Oracle ORAchk and Oracle EXAchk processes that run as root, perform user lookups for the users who own the Oracle Database home and Oracle Grid Infrastructure home. If root access is not required, then the Oracle ORAchk and Oracle EXAchk processes use the su command to run health checks as the applicable Oracle Database home user or Oracle Grid Infrastructure home user. Accounts with lower privileges cannot have elevated access to run health checks that require root access.

    Running health checks as root has advantages in role-separated environments or environments with more restrictive security.

  • Run as Oracle Database home owner or Oracle Grid Infrastructure home owner: Use Oracle Database home owner or Oracle Grid Infrastructure home owner credentials to run Oracle ORAchk and Oracle EXAchk.

    The user who runs Oracle ORAchk and Oracle EXAchk must have elevated access as root to run health checks that need root access.

    Running health checks as Oracle Database home owner or Oracle Grid Infrastructure home owner requires multiple runs in role-separated environments. More restrictive security requirements do not permit elevated access.

    There are several other options:

    • Skip the checks that require root access.

    • Specify the root user ID and password when prompted.

    • Configure sudo.

      If you are using sudo, then add an entry for the root script, located in $HOME in the /etc/sudoers file that corresponds to the user who is running the health checks.

      For example:
      user ALL=(root) NOPASSWD:/root/root_orachk.sh
      user ALL=(root) NOPASSWD:/root/root_exachk.sh

      To determine what $HOME is set to, run the echo $HOME command.

      For example:

      user ALL=(root) NOPASSWD:/root/.orachk/root_orachk.sh

      Or

      user ALL=(root) NOPASSWD:/root/.exachk/root_exachk.sh
    • Pre-configure passwordless SSH connectivity.

1.1.3.5 Data Entry Terminal Considerations

Use any supported UNIX and Linux terminal type (character mode terminal, ILOM, VNC server) to run Oracle ORAchk and Oracle EXAchk.

Respond to the prompts during the interactive run, or while configuring the daemon.

Each terminal type has advantages and disadvantages. The effect of a dropped network connection varies based on the terminal type used.

For example, in an interactive run using a character mode terminal, if all the prompts are answered prior to the network drop, then the running process completes successfully even if the network connection drops. If the network connection drops before all the input prompts are answered, then all the running processes hang. Clean up the hung processes manually when the network connection is restored.

Using a remote connection to a VNC server running on the database where Oracle ORAchk and Oracle EXAchk are running minimizes the network drop interruptions.

If you use accessibility software or devices that prevent the use of a VNC server, and cause network failures, then you must work with your network team and system administrator to determine the root cause and adjust the environment as required.

For example, an accessibility aid might insert a suspension and restart the interactive process that runs Oracle ORAchk or Oracle EXAchk. If this causes an operating system timeout due to terminal inactivity, then increase the inactivity timeouts of the environment before running the commands.

The timeout caused by an assistive tool at the operating system level due to terminal inactivity is not specific to Oracle ORAchk and Oracle EXAchk. The timeout could happen to any process that assistive technology manages.

1.1.3.6 Running Oracle ORAchk and Oracle EXAchk in Non-English Environments

Set globalization environment variables to run Oracle ORAchk and Oracle EXAchk in non-English environments.

Oracle ORAchk and Oracle EXAchk support only English language. However, you can run Oracle ORAchk and Oracle EXAchk by setting the globalization environment variables.
  1. To run Oracle ORAchk or Oracle EXAchk in a non-English environment, set the environment variable NLS_LANG to AMERICAN_AMERICA.[NLS_CHARACTERSET].

    For example:

    export NLS_LANG=AMERICAN_AMERICA.JA16SJISTILDE

    For more information on setting globalization environment variables, see Setting Up a Globalization Support Environment in the Oracle Database Globalization Support Guide.

1.1.3.7 Specific Prerequisites for Running Oracle ORAchk and Oracle EXAchk

Review Oracle ORAchk and Oracle EXAchk specific prerequisites.

For Oracle ORAchk specific prerequisites, see:

Oracle ORAchk Scope and Supported Environments

For Oracle EXAchk specific prerequisites, see:

1.1.4 Configuring the Daemon Mode

Use the daemon to configure automatic health check runs at scheduled intervals.

Note:

Daemon mode is supported only on the Linux and Solaris operating systems.

Note:

If you have an Oracle Engineered System, then in addition to the following usage steps, follow the system-specific instructions.

  1. Set the daemon properties.
    At a minimum, set AUTORUN_SCHEDULE and NOTIFICATION_EMAIL.

    For example, to set the tool to run at 3 AM every Sunday and email the results to some.body@example.com, run the following command:

    $ ./orachk –set “AUTORUN_SCHEDULE=3 * * 0 ;NOTIFICATION_EMAIL=some.body@example.com”
    $ ./exachk –set “AUTORUN_SCHEDULE=3 * * 0 ;NOTIFICATION_EMAIL=some.body@example.com”
  2. Configure the health check daemon as described in "Automated Daemon Mode Operation".
  3. Start the daemon as root (recommended) or as the Oracle Database or Oracle Grid Infrastructure home owner.
    # ./orachk –d start
    # ./exachk –d start
  4. Answer the questions prompted during startup.

1.1.5 Email Notification and Report Overview

The following sections provide a brief overview about email notifications and sections of the HTML report output.

1.1.5.1 First Email Notification

After completing health check runs, the daemon emails the assessment report as an HTML attachment to all users that you have specified in the NOTIFICATION_EMAIL list.

1.1.5.2 What does the Health Check Report Contain?

Health check reports contain the health status of each system grouped under different sections of the report.

The HTML report output contains the following:

  • Health score

  • Summary of health check runs

  • Table of contents

  • Controls for report features

  • Findings

  • Recommendations

Details of the report output are different on each system. The report is dynamic, and therefore the tools display certain sections only if applicable.

System Health Score and Summary

System Health Score and Summary report provide:

  • A high-level health score based on the number of passed or failed checks

  • A summary of health check run includes:
    • Name, for example, Cluster Name

    • Version of the operating system kernel

    • Path, version, name of homes, for example, CRS, DB, and EM Agent

    • Version of the component checked, for example, Exadata

    • Number of nodes checked, for example, database server, storage servers, InfiniBand switches

    • Version of Oracle ORAchk and Oracle EXAchk

    • Name of the collection output

    • Date and time of collection

    • Duration of the check

    • Name of the user who ran the check, for example, root

    • How long the check is valid

Table of Contents and Report Feature

The Table of Contents section provides links to major sections in the report:

  • Database Server

  • Storage Server

  • InfiniBand Switch

  • Cluster Wide

  • Maximum Availability Architecture (MAA) Scorecard

  • Infrastructure Software and Configuration Summary

  • Findings needing further review

  • Platinum Certification

  • System-wide Automatic Service Request (ASR) health check

  • Skipped Checks

  • Top 10 Time Consuming Checks

The Report Feature section enables you to:

  • Filter checks based on their statuses

  • Select the regions

  • Expand or collapse all checks

  • View check IDs

  • Remove findings from the report

  • Get a printable view

Report Findings

The Report Findings section displays the result of each health check grouped by technology components, such as Database Server, Storage Server, InfiniBand Switch, and Cluster Wide.

Each section shows:

  • Check status (FAIL, WARNING, INFO, or PASS)

  • Type of check

  • Check message

  • Where the check was run

  • Link to expand details for further findings and recommendation

Click View for more information about the health check results and the recommendations.

  • What to do to solve the problem

  • Where the recommendation applies

  • Where the problem does not apply

  • Links to relevant documentation or My Oracle Support notes

  • Example of data on which the recommendation is based

Maximum Availability Architecture (MAA) Score Card

Maximum Availability Architecture (MAA) Score Card displays the recommendations for the software installed on your system.

The details include:

  • Outage Type

  • Status of the check

  • Description of the problem

  • Components found

  • Host location

  • Version of the components compared to the recommended version

  • Status based on comparing the version found to the recommended version

1.1.5.3 Subsequent Email Notifications

For the subsequent health check runs after the first email notification, the daemon emails the summary of differences between the most recent runs.

Specify a list of comma-delimited email addresses in the NOTIFICATION_EMAIL option.

The email notification contains:

  • System Health Score of this run compared to the previous run

  • Summary of number of checks that were run and the differences between runs

  • Most recent report result as attachment

  • Previous report result as attachment

  • Diff report as attachment

1.1.5.4 Diff Report

The diff report attached to the previous email notification shows a summary of differences between the most recent runs.

To identify the changes since the last run:

Run the following command to generate a diff report:
$ ./orachk –diff report_1 report_2

When you review the diff report, you see a baseline comparison of the two reports and then a list of differences.

1.1.6 Recommended On-Demand Usage

This section summarizes the scenarios that Oracle recommends running health checks on-demand.

Apart from scheduled health check runs, run health checks on-demand by running the following commands:
$ ./orachk
$ ./exachk

Oracle recommends that you run health checks in the following on-demand scenarios:

  • Pre- or post-upgrades

  • Machine relocations from one subnet to another

  • Hardware failure or repair

  • Problem troubleshooting

  • In addition to go-live testing

While running pre- or post-upgrade checks, Oracle ORAchk and Oracle EXAchk automatically detect databases that are registered with Oracle Clusterware and presents the list of databases to check.

Run the pre-upgrade checks during the upgrade planning phase. Oracle ORAchk and Oracle EXAchk prompt you for the version to which you are planning to upgrade:
$ ./orachk –u –o pre
$ ./exachk –u –o pre
After upgrading, run the post-upgrade checks:
$ ./orachk –u –o post
$ ./exachk –u –o post

1.1.7 Updating to the Latest Version of Oracle ORAchk and Oracle EXAchk

There are several methods for maintaining Oracle ORAchk and Oracle EXAchk.

Note:

Each database PSU contains the latest Oracle ORAchk version available at time of creation. When a database PSU is applied, the ORAchk zip version contained is staged in $ORACLE_HOME/suptools.

Upon the next run, Oracle ORAchk prompts you to upgrade if the version copied by the PSU is newer than installed.

1.1.7.1 Updating Oracle ORAchk and Oracle EXAchk in an Environment with an Internet Connection

If your Oracle ORAchk or Oracle EXAchk version is older than 120 days, then the tool prompts you on startup to automatically download a newer version from My Oracle Support.

The script prompts for your My Oracle Support login details, and then checks if a later version is available for download and upgrade.

You can also download manually by running the –download option:

$ ./orachk –download
$ ./exachk –download
$ ./exachk –download
Enter your my oracle support username:- some.person@acompany.com
Enter your my oracle support password:-
Started downloading…..

exachk.zip successfully downloaded to /opt/oracle.suptools/exachk/exachk_mybox_040116_043027

1.1.7.2 Updating Oracle ORAchk and Oracle EXAchk in an Environment without an Internet Connection

If you do not have a direct connection to My Oracle Support, then download the latest versions of Oracle ORAchk and Oracle EXAchk from a machine that has an internet connection.

Transfer the downloaded files to a shared network staging location, and then set the environment variable RAT_UPGRADE_LOC to point to that staging location.

The next time the Oracle ORAchk or Oracle EXAchk is started, the tool detects the latest version and prompts you to upgrade.
  1. Download the appropriate health check tool zip file:
    • For Oracle ORAchk, download orachk.zip.

    • For Oracle EXAchk, download exachk.zip.

  2. Transfer the zip file to a shared network staging directory.
  3. On each machine with a version of the tool that you want to upgrade, set the environment variable RAT_UPGRADE_LOC to point to the network staging directory.
    $ export RAT_UPGRADE_LOC=PATH_TO_STAGING_DIRECTORY

The next time Oracle ORAchk or Oracle EXAchk is started, the tool searches the directory specified in the RAT_UPGRADE_LOC environment variable. If this directory contains the latest version of the orachk.zip or exachk.zip file, then Oracle ORAchk or Oracle EXAchk prompts you to allow it to upgrade.

$ ls /opt/oracle.SupportTools/exachk/latest
exachk.zip
$ export RAT_UPGRADE_LOC=/opt/oracle.SupportTools/exachk/latest
$ ./exachk
Latest version of exachk (EXACHK VERSION: 12.1.0.2.7_20160401) is available at /opt/oracle.SupportTools/exachk/latest/

Do you want to upgrade to the latest version of exachk? [y/n][y]

exachk has been upgraded to EXACHKVERSION:12.1.0.2.7(DEV)_20160401

Running the latest version…
If you have set RAT_UPGRADE_LOC but do not want to upgrade, then you can still run Oracle ORAchk or Oracle EXAchk using the –noupgrade option:
$ ./orachk –noupgrade
$ ./exachk –noupgrade

Note:

Use the -noupgrade option when you have the latest version in RAT_UPGRADE_LOC and do not yet want to upgrade.

Using -noupgrade without having the latest version in RAT_UPGRADE_LOC still prompts you to download the latest version.

1.1.8 Configuring Oracle REST Data Services (ORDS)

1.1.8.1 Configuring REST Using the Included ORDS

Override default ORDS configuration by setting the shell environment variables.

  • By default, Oracle REST Data Services (ORDS) uses whichever port is available in the range 7080-7085. If no port in this range is available, then ORDS exits and prompts you to set the RAT_ORDS_PORT environment variable. If RAT_ORDS_PORT is already set, then ORDS uses the port specified in the RAT_ORDS_PORT environment variable.

  • By default, ORDS is setup with the administrator user ordsadmin. You can override this by specifying a different user in the RAT_ORDSADMIN_USER environment variable.

  • Depending on Oracle ORAchk and Oracle EXAchk, ORDS is started as a nologin user named either ordsorachk or ordsexachk. If you use the ORDS, which is already running, then the user is as same as who is running ORDS.

  • If Oracle Trace File Analyzer is installed, then ORDS picks JAVA_HOME from TFA_HOME. If Oracle Trace File Analyzer is not installed, then ORDS picks the default JAVA_HOME. It is a requirement that you use JDK8. However, you can override by setting the RAT_JAVAEXE environment variable.

1.1.8.2 Configuring REST Using an Existing ORDS Installation

  1. To add the orachk.jar file to the existing ords.war file:
    ./orachk -ordssetup ords_war_dir -configdir config_dir
    ./exachk -ordssetup ords_war_dir -configdir config_dir

    where,

    ords_war_dir is the directory that contains the ords.war file

    config_dir is an optional directory that you can specify to store the ORDS configuration files. If you do not specify the optional directory, then the configuration files are stored in the orda_war_dir directory.

    Stopping and restarting ORDS after running the -ordssetup command:
    • Adds the orachk.jar file to the existing ords.war file

    • Adds the user ordsadmin to the ords.war file, and grants ORAchk admin privileges to ordsadmin

  2. To start the Oracle ORAchk or Oracle EXAchk daemon:
    ./orachk -d start -ords ords_war_dir
    ./exachk -d start -ords ords_war_dir
After completion, open the ords_war_dir/log/ords_setup.log file to view the REST URL details.

1.1.9 Using Oracle ORAchk or Oracle EXAchk over REST

Oracle ORAchk and Oracle EXAchk include full REST support allowing invocation and query over HTTPS.

1.1.9.1 Enabling REST

To facilitate REST support, Oracle REST Data Services (ORDS) is included within the install.

  1. To enable REST, setup ORDS and then provide a user password when prompted.
    ./orachk -ordssetup
    ./exachk -ordssetup
  2. Start the daemon using the -ords option:
    ./orachk -d start -ords 
    ./exachk -d start -ords

    Note:

    Only the root user can start the daemon with ORDS support.

    As ORDS support requires the daemon, ORDS is available only on platform (Linux) with daemon support.

1.1.9.2 start_client

Use GET requests to run a normal health check run.

Syntax

/start_client

Returns

Returns JSON showing the job ID similar to:

[{
"ID":"UCTW5MLN7O1V1HPG8U",
"Status":"SUBMITTED"
}]

Usage Notes

You need not provide input to use this API.

Example 1-1 start_client

-bash-4.2$ curl -i -X GET -k -u ordsadmin:adminpass 
https://node1.example.com:7080/ords/tfaml/orachk/start_client

HTTP/1.1 200 OK Date: Thu, 05 Apr 2018 11:53:14 GMT Content-Type: text/html X-Frame-Options: 
SAMEORIGIN Transfer-Encoding: chunked Server: Jetty(9.2.z-SNAPSHOT) 
[{"ID":"UCTW5MLN7O1V1HPG8U","Status":"SUBMITTED"}]

1.1.9.3 start_client

Use POST requests to run a normal health check run using specific arguments.

Syntax

/start_client

Returns

Returns JSON showing the job ID similar to:

[{ "ID":"UCTW5MLN7O1V1HPG8U", "Status":"SUBMITTED" }]

Usage Notes

Specify any Oracle ORAchk or Oracle EXAchk arguments and their corresponding values.

Example 1-2 JSON input

[{
"-clusternodes":"busm1c1,busm1c2",
"-ibswitches":"busm1sw-ibs0,busm1sw-iba0,busm1sw-ibb0"
}]

Example 1-3 start_client

-bash-4.2$ curl -i -X POST -H "Content-Type: application/json" -k -u ordsadmin:adminpass 
https://host:7080/ords/tfaml/orachk/start_client -d '[{"-clusternodes":"busm1c1,busm1c2","-ibswitches":"busm1sw-ibs0,busm1sw-iba0,busm1sw-ibb0"}]

1.1.9.4 profile

Use GET requests to run a health check run for the specified profiles.

Syntax

/profile/{profile1}/{profile2}

Returns

Returns JSON showing the job ID similar to:

[{ "ID":"DMBLMBTB2M2H1QCQIS", "Status":"SUBMITTED" }]

Usage Notes

Specify a profile, or a list of profiles delimited by forward slash (/).

Example 1-4 profile

-bash-4.2$ curl -i -X GET -k -u ordsadmin:adminpass 
https://node1.example.com:7080/ords/tfaml/orachk/profile/asm

HTTP/1.1 200 OK Date: Thu, 05 Apr 2018 10:50:00 GMT Content-Type: text/html X-Frame-Options: 
SAMEORIGIN Transfer-Encoding: chunked Server: Jetty(9.2.z-SNAPSHOT) 
[{"ID":"DMBLMBTB2M2H1QCQIS","Status":"SUBMITTED"}]

1.1.9.5 check

Use GET requests to run a health check run for the specified check IDs.

Syntax

/check/{check_id1,check_id2}

Returns

Returns JSON showing the job ID similar to:

[{ "ID":"B2PKK9RR9M7MYJPRN8", "Status":"SUBMITTED" }]

Usage Notes

Specify a profile, or a comma-delimited list of check IDs.

Example 1-5 check

-bash-4.2$ curl -i -X GET -k -u ordsadmin:adminpass 
https://node1.example.com:7080/ords/tfaml/orachk/check/E94589BC1AC24CFBE04312C0E50A3849

HTTP/1.1 200 OK Date: Thu, 05 Apr 2018 10:53:48 GMT Content-Type: text/html X-Frame-Options: 
SAMEORIGIN Transfer-Encoding: chunked Server: Jetty(9.2.z-SNAPSHOT) 
[{"ID":"B2PKK9RR9M7MYJPRN8","Status":"SUBMITTED"}]

1.1.9.6 status

Use GET requests to report the status on the specified job ID.

Syntax

/status/{job_id}

Returns

Returns JSON showing the job ID similar to:

[{ "Status of DMBLMBTB2M2H1QCQIS is SUBMITTED" }]

The status moves from SUBMITTED to RUNNING to COMPLETED.

Usage Notes

Specify the job ID for which you want to find the status.

Example 1-6 status

-bash-4.2$ curl -i -X GET -k -u ordsadmin:adminpass 
https://node1.example.com:7080/ords/tfaml/orachk/status/DMBLMBTB2M2H1QCQIS

HTTP/1.1 200 OK Date: Thu, 05 Apr 2018 10:51:16 GMT Content-Type: text/html X-Frame-Options: 
SAMEORIGIN Transfer-Encoding: chunked Server: Jetty(9.2.z-SNAPSHOT) 
[{"Status of DMBLMBTB2M2H1QCQIS is SUBMITTED"}]

1.1.9.7 download

Use GET requests to download the collection result for the specified job ID.

Syntax

/download/{job_id}

Returns

Returns the zip binary for the collection result.

Usage Notes

Specify the job ID for which you want to download the collection result.

If you specify a purged ID or an invalid ID, then the error message will be in the downloaded file.

Example 1-7 download

-bash-4.2$ curl -X GET -k -u ordsadmin:adminpass 
https://node1.example.com:7080/ords/tfaml/orachk/download/DMBLMBTB2M2H1QCQIS -J -O

% Total % Received % Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed 100 1385k 0 1385k 0 0 901k 
0 --:--:-- 0:00:01 --:--:-- 901k curl: Saved to filename 'exachk_busm01client01_PDB1_040518_035118_DMBLMBTB2M2H1QCQIS.zip'

1.1.9.8 checktfaupload

Use GET requests to report if a connection can be made to upload to Oracle Trace File Analyzer service.

Syntax

/checktfaupload

Returns

Returns JSON similar to:

[{ "ID":"ZFZLH06WOLE3L92PQI", "Status":"SUBMITTED" }]

Usage Notes

Use the status API to query the status of the submitted job.

Use the getinfo API to view the Oracle Trace File Analyzer upload status once the status of submitted API is COMPLETED.

Example 1-8 getinfo

With getinfo, returns:

[{"Msg":"Environment is not set for uploading results to TFA."}]

1.1.9.9 checktfafaileduploads

Use GET requests to report if any Oracle Trace File Analyzer service uploads failed.

Syntax

/checktfafaileduploads

Returns

If no collection failed to upload, then returns:

[{ "Msg":"There are no Failed collections under ORDS directory." }]

Or, prints the list of collections that failed to upload.

Usage Notes

You need not provide input to use this API.

Example 1-9 checktfafaileduploads

bash-4.1# curl -i -X GET -k -u ordsadmin:adminpass 
https://node1.example.com:7080/ords/tfaml/orachk/checktfafaileduploads
HTTP/1.1 200 OK
Date: Thu, 19 Jul 2018 10:04:58 GMT
Content-Type: text/html
X-Frame-Options: SAMEORIGIN
Transfer-Encoding: chunked

[{"Msg":"There are no Failed collections under ORDS directory."}]

1.1.9.10 gettfaupload

Use GET requests to report the Oracle Trace File Analyzer service upload settings.

Syntax

/gettfaupload

Returns

Lists the values of three environment variables: RAT_TFA_URL, RAT_TFA_USER, and RAT_TFA_PASSWORD.

Usage Notes

You need not provide input to use this API.

Example 1-10 gettfaupload

bash-4.1# curl -i -X GET -k -u ordsadmin:adminpass 
https://node1.example.com:7080/ords/tfaml/orachk/gettfaupload
HTTP/1.1 200 OK
Date: Thu, 19 Jul 2018 10:07:24 GMT
Content-Type: text/html
X-Frame-Options: SAMEORIGIN
Transfer-Encoding: chunked

RAT_TFA_URL =  https://tfa.us.oracle.com/tfa/ws/orachk/
RAT_TFA_USER =  orachkadmin
RAT_TFA_PASSWORD = ********

After unsettfaupload API, use the gettfaupload API to recheck the values:

-bash-4.1# curl -i -X GET -k -u ordsadmin:adminpass 
https://node1.example.com:7080/ords/tfaml/orachk/gettfaupload
HTTP/1.1 200 OK
Date: Thu, 19 Jul 2018 10:10:10 GMT
Content-Type: text/html
X-Frame-Options: SAMEORIGIN
Transfer-Encoding: chunked

RAT_TFA_URL is not set in the wallet 
RAT_TFA_USER is not set in the wallet 
RAT_TFA_PASSWORD is not set in the wallet

1.1.9.11 unsettfaupload

Use GET requests to unset all of the Oracle Trace File Analyzer service upload settings, or a particular setting.

Syntax

/unsettfaupload/all
/unsettfaupload/RAT_TFA_USER

Returns

Returns JSON showing the job ID similar to:

[{ "ID":"ZFZLH06WOLE3L92PQI", "Status":"SUBMITTED" }]

Usage Notes

Specify all to unset all of the three environment variables, RAT_TFA_URL, RAT_TFA_USER, and RAT_TFA_PASSWORD or, just specify an environment variable to unset it.

Example 1-11 unsettfaupload

-bash-4.1# curl -i -X GET -k -u ordsadmin:adminpass 
https://node1.example.com:7080/ords/tfaml/orachk/unsettfaupload/all
HTTP/1.1 200 OK
Date: Thu, 19 Jul 2018 10:08:30 GMT
Content-Type: text/html
X-Frame-Options: SAMEORIGIN
Transfer-Encoding: chunked

[{"ID":"Z8P9DHA8VV3PUOVQTV","Status":"SUBMITTED"}]

1.1.9.12 uploadtfafailed

Use GET requests to reattempt to upload all previously failed uploads to Oracle Trace File Analyzer service.

Syntax

/uploadtfafailed/all

Returns

Returns JSON showing the job ID similar to:

[{ "ID":"ZFZLH06WOLE3L92PQI", "Status":"SUBMITTED" }]

Usage Notes

You need not provide input to use this API.

Example 1-12 uploadtfafailed

-bash-4.1# curl -i -X GET -k -u ordsadmin:adminpass 
https://node1.example.com:7080/ords/tfaml/orachk/uploadtfafailed/all
HTTP/1.1 200 OK
Date: Thu, 19 Jul 2018 10:09:18 GMT
Content-Type: text/html
X-Frame-Options: SAMEORIGIN
Transfer-Encoding: chunked

[{"ID":"0B9O04CKSYZNUZCYZD","Status":"SUBMITTED"}]

1.1.9.13 showrepair

Use GET requests to report the repair command for the specified check.

Syntax

/showrepair/{check_id}

Returns

Returns JSON showing the job ID similar to:

[{ "ID":"ZFZLH06WOLE3L92PQI", "Status":"SUBMITTED" }]

Usage Notes

Specify the check ID for which you want to report the repair command.

Example 1-13 showrepair

-bash-4.1# curl -i -X GET -k -u ordsadmin:adminpass 
https://node1.example.com:7080/ords/tfaml/orachk/showrepair/9ECBA2152E92F6B1E040E50A1EC00DFB
HTTP/1.1 200 OK
Date: Thu, 19 Jul 2018 10:13:54 GMT
Content-Type: text/html
X-Frame-Options: SAMEORIGIN
Transfer-Encoding: chunked

[{"ID":"FJELUT7XYM3AKOE1R4","Status":"SUBMITTED"}]
-bash-4.1# curl -i -X GET -k -u ordsadmin:adminpass 
https://node1.example.com:7080/ords/tfaml/orachk/status/FJELUT7XYM3AKOE1R4
HTTP/1.1 200 OK
Date: Thu, 19 Jul 2018 10:15:00 GMT
Content-Type: text/html
X-Frame-Options: SAMEORIGIN
Transfer-Encoding: chunked

[{"Msg":"Status of FJELUT7XYM3AKOE1R4 is  COMPLETED"}]

1.1.9.14 getinfo

Use GET requests to report the status of the specified job ID.

Syntax

/getinfo/{job_id}

Returns

Returns JSON similar to if the ID does not exist:

[{ "Status":"Either the ID entered is invalid or the wallet has been purged." }]

Or, returns the repair command if the ID exists.

Usage Notes

Specify the job ID for which you want to check the status.

Example 1-14 getinfo

-bash-4.1# curl -i -X GET -k -u ordsadmin:adminpass 
https://node1.example.com:7080/ords/tfaml/orachk/getinfo/FJELUT7XYM3AKOE1R4 HTTP/1.1 200 OK Date: Thu, 19 Jul 2018 10:15:34 GMT 
Content-Type: text/html X-Frame-Options: SAMEORIGIN Transfer-Encoding: chunked

Repair Command:

alter database datafile '+DATAC1/RAC12C/DATAFILE/sysaux.314.936528199' autoextend on maxsize unlimited;

1.1.9.15 start_client

Use POST requests to run a diff of the specified collection results.

Syntax

/start_client

Returns

Returns JSON similar to:

[{ "ID":"ZFZLH06WOLE3L92PQI", "Status":"SUBMITTED" }]

The status API can be used to query the status of the submitted job ID. Then you can use the download API to download diff report using the same job ID.

Usage Notes

JSON input:

[{ "-diff":"collection_zip_1 collection_zip_2" }]

Example 1-15 start_client

-bash-4.2$ curl -i -X POST -H "Content-Type: application/json" -k -u ordsadmin:adminpass 
https://host:7080/ords/tfaml/orachk/start_client -d '[{"-diff":"orachk_myhost69_apxcmupg_062118_025029_N1O498NX877LYO5FE3.zip 
orachk_myhost69_apxcmupg_062118_030527_ICMOWECU1UKF0R0VTO.zip"}]'

1.1.9.16 Removing ORDS Setup

  1. To completely remove ORDS setup:
    ./orachk -ordsrmsetup ./exachk -ordsrmsetup

    The command option -ordsrmsetup stops the daemon if it is running and then stops the ORDS service.