When it comes to uniqueness of a computer in Client Automation, an Administrator must understand two overarching mechanisms:
First Mechanism -- The CAF Service on the Agent
Upon the first installation of the agent, and startup of the CAF service, a unique HostUUID is generated:
This value is used for uniquely identifying/distinguishing this computer from any other computer.
Subsequently, upon each computer registration (caf register), the agent will check for changes in the "DNA" of the computer, in order to determine if the HostUUID should be changed.
The "DNA" is defined as--
- MAC Addresses (Physical Network Cards only, i.e. not virtual/tunnel adapters like 00:00:00:00:00:00:00:E0)
- Hard Disk Serial Number
- SystemID (a BIOS attribute)
A new HostUUID is generated on a physical system, in two cases:
1- The hard disk serial number has changed, an in addition, either the physical MAC addresses have changed OR the SystemID has changed.
2- The hard disk serial numbers are not detected, and BOTH the SystemID AND physical MAC addresses have changed.
In the case there are multiple hard disks, or multiple physical MAC addresses, a match of at least one disk serial number or MAC address, to the previously known values, is sufficient enough for the agent to retain the existing HostUUID.
- SystemID (a BIOS attribute)
A new HostUUID is generated on a virtual system, for only one case:
1- The SystemID has changed.
Locking the HostUUID:
If, for any reason, you desire to LOCK the CAF service from the ability to change the HostUUID, you can do either of the following:
Method 1- Create a "LockHostUUID" registry value (string type) on the individual system, and set the value to "1":
Create a file named: /etc/calockuuid (no contents required)
Method 2- As of Client Automation r14 GA, you can set and apply a configuration policy to computers (or groups) in your environment:
DSM Explorer --> Control Panel --> Configuration --> Configuration Policy --> <Policy Name> --> Agent: "Lock the host UUID of agent"
In the "Default Computer Policy", the policy is set to false, allowing the agent to change the HostUUID, in the event the criteria for change is met.
Including the Client Automation Agent on an OS Image:
If you are installing/including the Client Automation Agent on an OS image, to be installed on multiple computers, you MUST remove the HostUUID from the image. Follow these steps to remove the HostUUID:
ccnfcmda -cmd DeleteParameter -ps itrm/rc/host/managed -pn convertedhostuid
ccnfcmda -cmd DeleteParameter -ps itrm/cfencrypt -pn LOCALID
ccnfcmda -cmd DeleteParamSection -ps itrm/rc/security/providers/winnt/users
reg delete HKLM\SOFTWARE\ComputerAssociates\hostUUID /f
reg delete HKLM\SOFTWARE\Wow6432Node\ComputerAssociates\hostUUID /f
Note: DO NOT START the CAF service after removing the HostUUID, otherwise a new HostUUID will be generated!
Second Mechanism -- The Engine on the Domain Manager
Now that you understand all the details surrounding the HostUUID from the agent perspective, next up, is understanding how the Client Automation Engine uses the HostUUID. When processing registration messages from agents, the engine must make a determination, whether the registration matches an existing computer in the database, or if a new computer record should be created.
Here's how the engine decides whether a new computer should be created, or an existing computer should be updated:
Primary -- Match based on HostUUID
If the HostUUID reported in the agent registration message matches the HostUUID of an agent already in the database, then the engine has a match to an existing computer, and updates the registration details of the existing computer, with the details provided in the message.
When multiple computers are sending registration messages containing the same HostUUID (i.e. an OS Image with a HostUUID that was never removed), only ONE COMPUTER, the most recent computer to send a registration, will be seen in the database/DSM Explorer.
This is why it's so important to ensure the HostUUID is removed from an OS image, before mass distributing throughout the environment.
Fallback 1 -- Match based on hostname AND ALL "Regular" MAC addresses
As a fallback, the engine also checks for a match based on the hostname AND list of ALL regular/physical MAC addresses. If the engine finds this match, then the computer is considered to be an existing one in the database, and its registration details are updated, with the details provided from the message.
For those database savvy Administrators, this match is performed by taking the MAC addresses from the list of reported physical network adapters, with the list of network adapters registered in the ca_discovered_hardware_network table.
Fallback 2 -- Match based on hostname AND ONLY the "Primary" MAC address
As a final fallback before declaring a computer registration as new, the engine looks for a match based on hostname AND the MAC address from the primary network adapter. Network adapters are always reported in their binding order. The primary network adapter is the one at the top of the binding order.
For those database savvy Administrators, this match is performed by taking the primary MAC address from the registration message and comparing it with the primary_mac_address in the ca_discovered_hardware table.
Here's a trace of an engine processing a computer registration message. In this example, the computer asset is new, which allows us to see all the checks performed by the engine, to determine the asset does not match any existing asset in the database:
The engine builds a "weighted" query, performing a UNION of multiple checks. Here's the pseudo text of the query:
select <Lengthy list of attributes> 1 as weight
select <Lengthy list of attributes> 2 as weight
from ca_discovered_hardware dhw, ca_discovered_hardware_network dhwn
select <Lengthy list of attributes> 3 as weight
from ca_discovered_hardware dhw
and dhw.primary_mac_address IS NULL
order by weight
In this example, after the computer is determined to be new, we see a new record being inserted into the ca_discovered_hardware table, followed by the engine loading and calling the CORA API, to perform a CORA registration on the asset. CORA, the Common Registration API is not covered in this technical document. Suffice it to say, it's an internal registration database for assets, used for integration with other CA Products, sharing within the same database.