Everything you need to know about the HostUUID and computer uniqueness
Article ID: 72577
Updated On:
Products
Issue/Introduction
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:
Windows:
32-Bit: HKEY_LOCAL_MACHINE\SOFTWARE\ComputerAssociates\hostUUID
64-Bit: HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\ComputerAssociates\hostUUID
Unix/Linux/Mac OSx:
/etc/cadmuuid
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--
Physical Computer:
- 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.
Virtual Computer:
- 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":
Windows:
32-Bit: HKEY_LOCAL_MACHINE\SOFTWARE\ComputerAssociates\LockHostUUID
64-Bit: HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\ComputerAssociates\LockHostUUID
Unix/Linux/Mac OSx:
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:
caf stop
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
from ca_discovered_hardware
where host_uuid='966E8ACC-CD7B-4E22-A12E-ED6B0A17A7A0'
UNION ALL
select <Lengthy list of attributes> 2 as weight
from ca_discovered_hardware dhw, ca_discovered_hardware_network dhwn
where dhw.dis_hw_uuid=dhwn.dis_hw_uuid
and dhw.host_name='<host_name>'
and dhwn.mac_address='AA:BB:CC:DD:EE:FF'
UNION ALL
select <Lengthy list of attributes> 3 as weight
from ca_discovered_hardware dhw
where dhw.host_name='<host_name>'
and dhw.primary_mac_address IS NULL
or dhw.primary_mac_address=''
or dhw.primary_mac_address='AA:BB:CC:DD:EE:FF'
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.
Using Client Automation, how do I remediate computers that have been installed using an OS Image, where the HostUUID was not properly removed, before the OS Image was deployed?
Environment
Client Automation -- All versions.
Resolution
As the HostUUID is Client Automation's primary attribute for telling the difference between one agent, and another, the product is only capable of interfacing with ONE of these agents, having a known duplicate HostUUID, at a time.
If this symptom was caught early, and there are a limited/small number of computers having this problem, you can simply run these commands to force the agent to generate a new/unique HostUUID:
caf stop
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
caf start
After running these steps, the computer will be able to register with a new HostUUID, and the engine will be able to create a new computer record in the database.
If this symptom was not caught early, and it's unknown how many computers are affected by this problem, you can try the steps from this technical document, to see if it helps identify computers that are affected by HostUUID duplication:
How to find computers with same hostuuid and how to correct them
Article Id: 9777 How to find computers with same hostuuid and how to correct them?
If the method used in the above linked document is not helpful or successful in identifying computers exhibiting symptoms of HostUUID duplication, the the best option within confines of Client Automation is to leverage a Software-based policy, to automate targeting computers with a script. You'll need to know the exact problematic/duplicate HostUUID that was not removed from the image, in order to tailor a query to isolate these systems, as they register.
The Software-based policy will be limited in its ability to target high volumes of computers, as Client Automation is only capable of "seeing" the last (one) computer that registered with the known duplicate HostUUID.
Nevertheless, if no solution outside of Client Automation can be leveraged to fix this (i.e. a login script that checks the computer for the known duplicate HostUUID, and remediates it with the script found below), then here are the steps on how to configure a Software-based policy:
In this example, we'll use "966E8ACC-CD7B-4E22-A12E-ED6B0A17A7A0" as an example HostUUID.
1- Create a custom query, to detect any computer currently registered with the known duplicate HostUUID:
- DSM Explorer --> Queries --> All Queries --> New.
- Choose "computers" as your target, and choose the "advanced argument" option from the query editor.
- Advanced argument details:
Pseudo Text: "Duplicate HostUUID"
Table: "-Any-"
Additional where clause: "select dis_hw_uuid from ca_discovered_hardware where host_uuid=UPPER('966E8ACC-CD7B-4E22-A12E-ED6B0A17A7A0') or host_uuid=LOWER('966E8ACC-CD7B-4E22-A12E-ED6B0A17A7A0')"
- Previewing the query result will validate it's entered into the query editor successfully. Only ONE computer should be returned, matching the HostUUID you specified.
2- Create a dynamic computer group, based on the new query.
- DSM Explorer --> Computers and Users: New Group
- Name the group appropriately, and on the query tab, associate the query created from the previous step.
- Normally, it is not recommended to set a query evaluation period for a short interval, as having too many (or complex) queries evaluate in short intervals will reduce overall system performance. In this case, as there are potentially many computers registering and competing for the same slot in the database, a short evaluation interval is required; and acceptable considering our custom query will only be returning one (1) record from SQL.
In this example, I've selected an Engine that is less busy with processing lengthy tasks, and is a destination engine for executing query evaluations. It may also be appropriate (and again, not normally recommended), to choose, "All Engines" for this particular query, as it's not a complex query, and requires near real-time evaluation.
3- Create a Software Package for executing the following in a batch/command script:
@echo off
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
taskkill /F /IM amagentsvc.exe /T
caf kill all
del /S /Q "%sdroot%\..\Agent\units\"
del /S /Q "%sdroot%\..\logs\"
caf start
exit /b 0
This script is designed to do the following:
- Remove the current HostUUID from the agent comstore.
- Remove the current HostUUID from the registry.
- Kill any AM agent execution, that may already be in-progress.
- Kill the CAF service.
- Remove the units folder, which will force the agent to generate a new/completed inventory.
- Remove the existing agent trace logs.
- Restart the CAF service.
Here's an example of the procedure properties in Software Delivery:
As the script is designed to kill the CAF service, and trigger the HostUUID to be regenerated, it's advisable to choose, "Run job off-line from the scalability servers", under the procedure options:
4- Before creating a Software-based policy to automate this software package, it is advisable to test delivering this package to the current agent that is registered with the known duplicate HostUUID (i.e. check the dynamic group created in step 2)
5- Create a new Software-based policy to automate the software package:
- DSM Explorer --> Policies --> Software Based: New Software Policy
- Choose the software package created from step 3.
- Choose the computer group created from step 2.
- Give the software policy a meaningful name, and ensure the option for "Open the advanced software policy settings dialog when the finish button is pressed."...
- Ensure the highest degree of automation is set
- Normally, it is NEVER recommended to use ad-hoc policy evaluations, as system performance can be reduced drastically by constant evaluations running in the background. However, due to competing computer registrations with the same HostUUID, we need the Software-based policy to react quickly, and setup a job to the target computer:
- Once again, ensure the "Run job off-line from the scalability servers" option is selected, under the procedure options for the job:
Additional Information
For information on querying the database for duplicate computers, by hostname, serial number or both, refer to the following technical document:
Article Id: 9565 How to Create Dynamic Groups for Identifying Duplicate Computers in DSM Explorer.
In addition, this document may be helpful for identifying systems registered in the database where the HostUUID has changed:
Article Id: 9777 How to find computers with same hostuuid and how to correct them?
Feedback
