Client Management Suite

 View Only

Technical White Paper - Inventory Rules, Detection and Applicability Checks 

Dec 13, 2011 12:49 PM

Inventory Rules fulfill the roles of Detection or Applicability checks in relation to a Managed Software Delivery Policy. They represents a check on an agent computer system and can only return the values of true/false, or fail in the case of an incorrectly written rule. An Inventory Rule is stored as an xml file that the Inventory Rule Management(IRM) agent is able to parse and execute. Each rule is connected with the provider that implements the rule functionality. For example, the IRM smart rules are implemented by the SMF rule provider so when a smart rule is executed on an agent computer the IRM calls the SMF provider functionality to determinate the rule evaluation result. Additionally, an Inventory Rule contains the DataClass attribute that is like a folder for the rules (IRM server cache stores rules by the DataClass). Rule DataClass partitioning was previously used by the Patch Solution (before 7.1) to decrease the number of rules that are posted to the agent. After 7.1, Patch is using its own rule functionality and, as a result, most of the rules currently point to the empty DataClass.

IRM Server-Side Functionality

Server-side functionality is able to store, cache, and provide cached rule information through the web services.

Cache

Most used server-side rule caches are grouped by the DataClass rule. The cache is constructed when the DataClass cached information is requested for the first time. When the first request is processed, the cache rule populates all of the rules from the database (with a given DataClass attribute) and constructs its data and hash information for future use. The cache will also construct the DataClass hash that summarizes all of the rule hashes inside this DataClass. IRM only caches the rules that are connected with a Software Resource to minimize the cache size.

NOTE: In 7.1 most user-created rules will point to the empty DataClass, as previously mentioned. This means most Rules will be loaded in the cache when a request for a rule is made for the first time.

Server rule cache is stored in memory to produce better performance. As a result, when the IIS server gets restarted the cache will be cleared and parts of it will be reconstructed when the first cache requests come from target clients.

Server rule cache is set to dirty when the rule is changed, meaning it is considered invalid. This means when you edit a Rule in the Symantec Management Console, the server cache is set to dirty, or invalid. As a result, when the cache receives the DataClass cache request after the dirty state it will reload the changed rules and recalculate the rule data hash and the changed DataClass summary hash.

This screenshot shows where you can view available Rules in the Symantec Management Console, under Manage > All Resources > Default > All Resources > HashedResource > and select Inventory Rule (if you do not have HashedResource shown in the tree, select the Default root and use the Filter button to add it):

Rules Distribution

After the Patch Management Solution abandoned the use of IRM rules, only a few important web service methods are frequently used by the IRM agent plug-in. Those web service methods are listed below:

  1. Request the DataClass hash information (DataClassHash) - Returns the list of hashes for the DataClasses. This information is used by the agent to identify whether the given DataClass cache on the client side is different from the Server cache. In SP2 it is now used by the IRM Synchronization Policy that is described in 'SP2 changes' section.
  2. Request the DataClass rule hash information (DataClassRuleSummary) -Returns the list of all rule hashes for the specified DataClass. This information is requested by the agent when it spots the changed DataClass and now requires identifying the rules that are changed/missing the agent cache.
  3. Request the rule information (Rules) - Returns the rule data xml representation. This information is used by the agent when it requires the rule xml representation.

To minimize the traffic IRM web services, the agent uses compression to distribute the rule information.

As DataClass rule cache construction can take up to few minutes (on large system with a lot of Software Resources), IRM returns the HASH_PENDING result for methods 1 and 2 when the calculation is still pending. This will force the IRM agent to use the local cached rule data, if it was previously present, or fail the rule evaluation if it was not. If the SMF detection/applicability check failed the result is handled and the evaluation is re-queued (see the 'changes in 7.1 SP1' and 'changes in 7.1 SP2' sections for more information about re-queue mechanism implemented by SMF).

IRM Client-Side Functionality

Client-side functionality is able to request, store, and execute rules that are cached by the IRM server-side.

Rule Request / Evaluation

When a rule evaluation is requested, the IRM starts with a cache search and uses the cached version to evaluate the rule if it was found. If the rule was not found in the cache, the IRM requests the rule data from the web service and adds its xml representation into the IRM local agent cache. It will only request the rule itself (request method 3 described in the 'distribution of rule' section above).

POST request to the following URL. Inside the post stream the xml request:
<rules><rule guid='{GUID_OF_THE_RULE_YOU_NEED}'/></rules>
...is used to specify the rule Guid needed.

http://localhost /Altiris/InventoryRuleManagement/Agent/AgentRuleData.ashx?DataType=Rules
NOTE: If you use the above URL without the parameters, you will see a humorous message indicating: Move along, please - nothing to see here.

Rule Storage

The IRM agent plug-in uses a SQLite database to store the local rule cache. Database file is located under Agents\Inventory Rule Agent\InventoryRuleCache.ibd. The database is not viewable in standard document readers and requires a viewer with SQLite readability.

Detection and Applicability Rules

Detection and applicability rules were introduced with the Software Management "Managed Delivery Policy". Internally on the client, those rules are implemented as a client task that uses IRM agent COM API to run actual rules. This task represents a tiny wrapper over the inventory rules that add the re-queue mechanism and add a result expectation that is able to affect the policy execution. For example, if a policy delivery item installation contains a detection check, then when a detection check will be evaluated to true the delivery item installation (download and execution) will not proceed. In other words True means the applicable software is installed (compliant), where as False means the applicable software was not found on the target system.

The detection check should be used to determinate whatever or not the Software Resource is installed on the computer. In the case of an install command line type, the policy will proceed with the delivery item execution in the case when a rule is evaluated to false. In the case of an uninstall, the command line executes when the rule is evaluated to true. While creative ways to "detect" software can be used, the above rule information should be taken into consideration when not using a standard "is this software installed" rule type.

The applicability rules should be used when you need to limit the computers on which the software can be installed. Most common applicability rules used are 32-bit and 64-bit that are able to prohibit the installation of software to the inappropriate windows architecture. The applicability check is not used when uninstall command line is selected in Managed Delivery Policy. As a result, the applicability check should only be used to determine the applicable computer for the software delivery item installation.

Changes in Detection / Applicability Checks in 7.1 SP1

Before 7.1 SP1, the detection and applicability checks were able to re-queue the rule evaluation (if it failed for some reason) 5 times. After that they returned a failed result. Because of this, when the new Managed Delivery Policy was received by the agent, the rules were not present in the local IRM cache as a result they were requested on the first detection/applicability rule execution. This introduced the problem when rule request could fail (when NS server was down on loaded systems) 5 times very quickly and then fail the whole policy. As a result, SMF introduced the re-queue mechanism that was able evaluate the rule and request its data from NS server until it will finally succeed.

Although this behavior made the Managed Delivery policy more robust it also revealed few problems with IRM/SMF, as listed below:

  • Special characters in the rule caused inventory rule to fail. This caused the rule to re-queue itself endlessly. Additionally, if such rule was created by a user whole rule DataClass became corrupted and caused problem for the new agents that never executed policies if there is no rules at all on the agent (clean agent install) it requests the all DataClass rules instead of requesting the rules separately one by one.
  • When the NS was unavailable, the rule indeed re-queued itself but it did it very quickly resulting in a massive amount of task-result data being sent to the NS server.

Changes in Detection / Applicability Checks in 7.1 SP2

In SP2 Symantec changed the re-queue functionality and made it much friendlier to the NS Task mechanism. The detection/applicability check is now re-queued every 10 minutes instead of 5-10 seconds.

Secondly, Symantec added special character support (UTF-8) in detection/applicability checks that should remove the problem with corrupted DataClass rule information described previously.

And finally, Symantec added the IRM Synchronization policy that keeps the local computer rule cache up-to-date regardless of the applied and executed policies. This policy is able to detect the rule changes and request all of then immediately from the NS and put those in the agent rule cache. This forces the agent to get all the rules before the Managed Delivery policy is applied to the computer. As a result, by the time the policy needs to be run it will be able to use the cached version of the detection/applicability rule in the evaluation. However, SMF is still setting the detection and applicability rule to dirty(potentially invalid) before each execution that forces the IRM to check if the rule is changed on the server but even if this request fails it will continue with the cached rule version that was already received by the synchronization policy.

Note that this new hidden IRM Synchronization policy is not a newly added policy type. This type of policy existed before and was used by Patch Management before patch dropped usage of the IRM. This policy is used to synchronize inventory rules for a particular grouping (usually by the results dataclass that will be populated when running that set of rules) on the client. It contains a list of guids with a corresponding hash value. The guids may correspond to the dataclasses which will receive the inventory information on the NS or it can simply be used to group a set of rules (if the setting DoNotRunInventory is true). All rules belonging to that group will be downloaded to the client. The associated hash value is used to detect if any of the rules in that grouping have changed compared to the rules stored on the client cache - if so the changed rules will automatically be downloaded from the IRM web service prior to running inventory.

This policy runs on an interval rather than a schedule in order to reduce load on the NS when processing the NSEs generated at the end of the inventory cycle, by spreading out the inventory cycle across the client machines.

Property Description
InventoryInterval

The number of minutes between inventory cycles for this policy.

For the newly added IRM Synchronization policy for managed delivery rules the value is: 240.

OnlyReportInventoryIfChanged

If true, the IRM agent will only send an NSE containing inventory information to the NS server if it has changed since the last time inventory was run.

For the newly added IRM Synchronization policy for managed delivery rules the value is: True.

SendInventorySummary

The IRM agent will send an NSE summary event to the NS, containing the number of true rules, the number of false rules and the number of errors as well as the total time taken to run the rules. This is sent after each inventory cycle.

For the newly added IRM Synchronization policy for managed delivery rules the value is: False.

DoNotRunInventory

Prevents the IRM agent from running the inventory and reporting it to the NS. Instead, the policy will be used to keep the inventory rules on the agent in sync with the server--the agent will use the hash values for the grouping/dataclass guid to ensure that the rules on the client are kept up to date. The rules will be synchronized every interval.

For the newly added IRM Synchronization policy for managed delivery rules the value is: True.

ImpersonateInteractiveUser

If this value is true then the agent will impersonate the logged on user when running the inventory rules.

For the newly added IRM Synchronization policy for managed delivery rules the value is: False.

ResultDataClassInfo[]

This indexer returns the results dataclass guids along with the associated hash. The hash is used to synchronize the rules on the client with the server.

For the newly added IRM Synchronization policy for managed delivery rules the value is: NULL dataclass which represents managed delivery rules.

The policy is applied to the all windows computers with Inventory Rule Agent Installed filter.

Statistics
0 Favorited
3 Views
2 Files
0 Shares
4 Downloads
Attachment(s)
jpg file
tdir-01.jpg   77 KB   1 version
Uploaded - Feb 25, 2020
doc file
Technical_Details_Inventory_Rules.doc   134 KB   1 version
Uploaded - Feb 25, 2020

Tags and Keywords

Comments

Oct 19, 2012 11:16 AM

Hi Pascal,

 

May I ask you to provide some more information about the problem which you experience?

There are questions which may help to identify the problem:

1) What detection rule type do you use?

2) Can you provide example of the registry path\entry\value which is not working?

3) On what operating systems do you experiece the issue?

 

Thanks,

Andrew.

Oct 19, 2012 06:06 AM

Curiously we see also detection for DWORD registry seems not working ?

Oct 16, 2012 01:07 PM

Again thanks Joel.

Did you have any know cases where the detection rule "failed" randomly should not, and success after.

We got a few times a none detected issue, on a platform already installed, so the package install 2 times. After that, it is OK. The detection is based a custom inhouse HKLM key.

I do not know if customer still have this issue after the MP1 installed last week,

Jun 21, 2012 08:33 AM

Thank you for the article,

So, if a customer checks for compliance (using detection rules in a managed delivery policy) let's say everyday, for 100 sw packages in a 2.000 endpoints environment, that means 200.000 tasks coming to the NS everyday, right?

May this be an issue on the NS?

Thanks

Santi

 

 

 

 

Apr 19, 2012 10:12 AM

Thanks Joel -the evolution of  inventory rule management has been very illuminating. Brilliant work, and many thanks.

Kind Regards,
Ian./

 

Related Entries and Links

No Related Resource entered.