How the FlexNet inventory agent determines ORACLE_HOME on Unix-like operating systems when gathering Oracle Database inventory

[#1]

Overview

In order to successfully connect to an Oracle Database instance to gather inventory, the inventory component (ndtrack) of the FlexNet inventory agent must be able to correctly guess the exact ORACLE_HOME environment variable that the instance is running with. This article describes how this is done on Unix-like operating systems, and what can go wrong with this process.

Logic for identifying ORACLE_HOME

The inventory component uses the first of the following values that can be determined (and is not empty) to make a best guess at the likely value of the ORACLE_HOME variable for a running Oracle Database instance process:

1. The value of the ORACLE_HOME environment variable in the default shell profile of the user that the “Oracle” process is running as.
2. The home directory as specified in /etc/oratab for the SID identified from the "Oracle" process name.
3. The real path (with no symlinks) of the executed used to invoke the running "Oracle" process.

What processes are used to identify potential Oracle Database instances?

The inventory gathering process looks for Oracle Database processes with any of the following names to identify potential instances to be inventoried:

• ora_smon_<SID>
• xe_smon_<SID>
• asm_smon_<SID>

A process discovered with one of these names is referred to in this article as an "Oracle" process.

When may the ORACLE_HOME directory fail to be correctly identified?

Some examples of scenarios where the path identified by the above logic does not exactly match the ORACLE_HOME environment variable used by the Oracle Database instance are:

• When symlinks are used then different paths may resolve to the same real path. For example, this would occur if:
  1. The "Oracle" process is running with the environment variable ORACLE_HOME set to “/oracle/ABC”; and
  2. “/oracle/ABC” is a symlink to “/oracle/19.3.0”; and
  3. The home directory identified by the agent based on the logic described above is “/oracle/19.3.0”.
     
     
• When the ORACLE_HOME environment variable is set in the default profile of a single “oracle” user that is used to run multiple Oracle Database instances. In this case it is likely that all (possibly except for one) of those instances will each individually have an ORACLE_HOME that is different from the default profile setting.

Inventory component logging related to the ORACLE_HOME discovery

The tracker.log file generated by the inventory gathering component includes details like the following related to discovery of Oracle Database instances and their home directories:

[Wed 15 Dec 2021 11:18:06 AM EST (G, 0)] {19070} ===== Discovered Oracle database instances and listeners
[Wed 15 Dec 2021 11:18:06 AM EST (G, 0)] {19070} +-- "/oracle/product/ABC": Discovered by = Process,Oratab,Osdbagrp, Executable ID = 64517:939841567, DBA group = "dba", Home owner = "oracle", Has SQLPlus = true, SQLNet Authentication Services = "", Can Inventory = true, Real Home = ""
[Wed 15 Dec 2021 11:18:06 AM EST (G, 0)] {19070} |   +-- Instance "ABC": Discovered by = Process,Oratab, Process ID = 22896, State = running, Process owner = "oracle"
[...]
[Wed 15 Dec 2021 11:18:07 AM EST (G, 0)] {19070} Started tracking Oracle instance "ABC" in "/oracle/product/ABC".
[...]
[Wed 15 Dec 2021 11:21:56 AM EST (G, 0)] {19070} Successfully gathered inventory from Oracle instance "ABC" in "/oracle/product/ABC".

The path “/oracle/product/ABC” in the above example is the ORACLE_HOME directory determined as per the steps described above.

If the home identified from the /etc/oratab or “Oracle” process is overridden by the home identified from the ORACLE_HOME environment variable in the profile of the Oracle user, then the “Real Home” value identifies the former path.

Checking whether the correct ORACLE_HOME value has been identified

To check whether the inventory component is correctly identifying the ORACLE_HOME for a particular database instance:

1. Find logging like the following which shows the identified ORACLE_HOME directory in the inventory component’s tracker.log file:
   

   [Wed 15 Dec 2021 11:18:07 AM EST (G, 0)] {19070} Started tracking Oracle instance "ABC" in "/oracle/product/ABC".

2. Ask your DBAs to identify the exact ORACLE_HOME directory path that the instance is actually running with.
3. Confirm whether these values match exactly.

What happens if an incorrect ORACLE_HOME is identified?

Oracle Database inventory gathering may fail with logging showing one of the following errors when the agent identifies an ORACLE_HOME value that does not exactly match the value that the instance is running with:

• ORA-12547 TNS:lost contact
• ORA-01034: ORACLE not available

For example:

[Wed 15 Dec 2021 11:18:06 AM EST (G, 0)] {19070} Started tracking Oracle instance "ABC" in "/oracle/product/ABC".
[Wed 15 Dec 2021 11:18:06 AM EST (G, 0)] {19070} |   ORA-12547: TNS:lost contact
[Wed 15 Dec 2021 11:18:06 AM EST (G, 0)] {19070} |   SP2-0751: Unable to connect to Oracle.  Exiting SQL*Plus
[Wed 15 Dec 2021 11:18:06 AM EST (G, 0)] {19070} Failed to inventory Oracle instance "ABC" in "/oracle/product/ABC".

Or:

[Wed 15 Dec 2021 11:18:06 AM EST (G, 0)] {19070} Started tracking Oracle instance "ABC" in "/oracle/product/ABC".
[Wed 15 Dec 2021 11:18:06 AM EST (G, 0)] {19070} |   ORA-01034: ORACLE not available
[Wed 15 Dec 2021 11:18:06 AM EST (G, 0)] {19070} |   Process ID: 0
[Wed 15 Dec 2021 11:18:06 AM EST (G, 0)] {19070} |   Session ID: 0 Serial number: 0
[Wed 15 Dec 2021 11:18:06 AM EST (G, 0)] {19070} Failed to inventory Oracle instance "ABC" in "/oracle/product/ABC".

Note that these errors can potentially have other root causes. For example, similar errors may be caused by a ORACLE_BASE value in the $ORACLE_HOME/install/orabasetab file that does not match the ORACLE_BASE value the instance is actually running with.

Testing connecting to the Oracle Database instance

Commands like the following can be executed to manually test whether a connection can be made to an Oracle Database instance in a similar fashion to what the FlexNet inventory agent will do.

Replace the “oracle” username, “OracleHomeDirectory” and “OracleSID” values in the first 3 lines with actual values as shown in logging from the inventory component’s tracker.log file.

su - oracle
export ORACLE_HOME=OracleHomeDirectory
export ORACLE_SID=OracleSID

cd "$ORACLE_HOME/bin"
./sqlplus "/ as sysdba"

The above sqlplus command will need to succeed in order for the FlexNet inventory agent to be able to gather Oracle Database inventory.

Tip: If the inventory agent’s OracleInventoryAsSysdba preference has been configured to the non-default value of “False”, use the following sqlplus command to connect instead of the command shown above:

./sqlplus "/"

What can be done if an incorrect ORACLE_HOME is identified?

The following approaches may be considered to get a successful connection to gather Oracle Database inventory if an incorrect ORACLE_HOME is identified by default:

1. Consider whether the configuration of the Oracle Database instance can be modified so that the ORACLE_HOME discovery process identifies the correct value. For example, this could involve modifying the details in the /etc/oratab file to exactly match the value the instance runs with, or changing the ORACLE_HOME environment variable in the default profile of the oracle user.
   
   
2. The UserDefinedOracleHome inventory agent preference can be set to “False” to avoid using the ORACLE_HOME value from the default shell profile of the user that the “oracle” process is running as. This may be appropriate if that value is set but multiple instances with different homes are running on the server.
   
   One way to set this preference would be to execute commands like the following:
   

   $ cat <<EOF >/tmp/mgsconfig.ini
   [ManageSoft\Tracker\CurrentVersion]
   UserDefinedOracleHome=False
   EOF
   
   $ /opt/managesoft/bin/mgsconfig -i /tmp/mgsconfig.ini

3. Consider using beacon-based collection of Oracle inventory (rather than agent-based collection).

How is ORACLE_HOME obtained from an Oracle user’s default profile?

The inventory component executes a command like the following to obtain the ORACLE_HOME environment variable value from the default profile of the user running an Oracle Database instance:

$ su - oracle -c 'echo $ORACLE_HOME'

Related information

See the following pages for other information related to this topic:

• IT Asset Management System Reference >
  • How Agent-Based Collection of Oracle Inventory Works
  • Issues with Inventory Gathering
• Gathering FlexNet inventory >
  • Preferences > UserDefinedOracleHome