CIM probe

The CIM probe uses WBEM protocols to query a particular CIM server, the CIM Object Manager, for a set of data objects and properties.

For instructions on configuring probe parameters, see Set probe parameters.

The following parameters may be passed to the CIM probe:

Table 1. CIM Probe
Parameter Description Default Value
source [Required] The initial host to connect to. None
port The port to connect to. If empty, the value is determined by the "schema" parameter: http = 5988, https = 5989. 5988 or 5989
schema [Required] The schema to use: '"http"' or '"https"'. http
namespace [Required] The CIM namespace. May be overridden by a query. None
queries [Required] A semicolon-delimited list of CIM probe queries to process and return results for. None
retries The number of times to retry a query if it fails due to network connectivity issues. 2
connection_timeout The number of milliseconds the probe has to connect to a server. 5000
socket_timeout The number of milliseconds the probe has to read data. 5000

The CIM Intermediate Query Language (CimIQL) uses keys, filters, and dot-walking to traverse the CIM schema.

Parameter Expansion

The CIM query language supports standard SNC preprocessed probe parameter expansion. Place variables in queries by encapsulating their names like this:

${foobar}.CIM_RunningOS[0].Name
CIM_ComputerSystem.${barfoo}

The text ${foobar} is replaced with the contents of the foobarprobe parameter passed to the CIM probe; likewise for barfoo.

CIMIQL

The CIM Intermediate Query Language (CimIQL) is an intermediate language designed to simplify the process of querying CIM providers.

CimIQL currently supports the standard Web-Based Enterprise Management (WBEM) protocol stack, but others, such as Web Services-Management (WS-MAN), may be added in the future. The query language syntax borrows from elements of Microsoft's WMI query language and UNIX's wbemcli command. The CimIQL library is a pure Java implementation.

Note: CimIQL is pronounced "simicle".

CimIQL syntax

CimIQL syntax consists of several elements, including a query and different tokens.

Table 2. CimIQL Syntax Element Descriptions
Element Description
Statement The most basic element of CimIQL is a valid . A statement contains multiple queries delimited by a period . character.
Query A represents a single high-level protocol-independent request. Each query is comprised of nested language components and sub-components known as tokens.
Token A describes a specific lexical aspect of the CimIQL syntax.
Operation Token The first token of each query must be an , which represents the overall logical operation to be performed.
Component Token A is a sub-component of an operation token.
Result Each query is paired with a result, which is then provided as input to the next query in the statement. A is comprised of a set of objects and their properties.

CimIQL operation tokens

The CimIQL probe requires operation tokens.

Each of the following core operations has a counterpart in the CIM Operations over HTTP standard.

Table 3. CimIQL Operation Token Summary
Return Value Details Equivalent CIM Operation over HTTP
class object
Get Object
  • Retrieves a single object of a specific class by specifying all of its unique keys (as key tokens) and any optional parameter tokens, separated by commas.
GetInstance
class object
Enumerate Objects
EnumerateInstances
class object
Enumerate Associated Objects
  • Retrieves objects associated with each result from the preceding query.
Associators
statement results
Substitution
  • A no-op token that feeds the results of a previous named statement as input into the next query of its own statement.
Reference the results of a named statement

Get Object Token

<classname>{<key token>,<parameter token>,...}
  • Retrieves a single object of a specific class by specifying all of its unique keys (as key tokenskey tokens) and any optional parameter tokens, separated by commas. This token is also known as the .
  • The <classname> is the case-sensitive CIM class name of the desired object. By default, objects of the specified class and of any extended classes are retrieved.
  • The key and parameter tokens are enclosed by a single pair of curly brackets { ... }.
  • This token must only be used as the first query in a statement.
  • Returns: class object
  • Example:
    CIM_ComputerSystem{CreationClassName='Linux_ComputerSystem',Name='runtime'}.*

Enumerate Objects Token

<classname>{{<condition token>,<parameter token>,...}}<array index token> OR <classname><array index token>
  • Retrieves objects that match a set of condition tokens and parameter tokens. This token is also known as the .
  • The condition tokens and parameter tokens are enclosed by two pairs of curly brackets {{ ... }}. The curly brackets are optional if there are no conditions or parameters necessary.
  • The <classname> is the case-sensitive CIM class name of the desired objects. By default, objects of the specified class and of any extended classes are retrieved.
  • The index token is optional.
  • This token must only be used as the first query in a statement.
  • Returns: class object
  • Example:
    CIM_ComputerSystem{{Name!='runtime'}}.*

Enumerate Associated Objects Token

<association classname>{{<property filter token>,<parameter token>,...}}<array index token> OR <association classname><array index token>
  • Retrieves objects associated with each result from the preceding query.
  • The condition tokens and parameter tokens are enclosed by two pairs of curly brackets {{ ... }}. The curly brackets are optional if there are no properties filters or parameters necessary.
  • The <association classname> is the name of the many-to-many or one-to-many class that associates two objects together. By default, objects of the specified class and of any extended classes are retrieved.
  • The <parameter token>, ResultClass, may be specified to filter results based on the resulting object's classname.
  • The index token is optional.
  • This token must not be used as the first query in a statement.
  • Returns: class object
  • Example:
    CIM_ComputerSystem{{Name='runtime'}}[2].*

Substitution Token

${<statement name>}
  • A no-op token that feeds the results of a previous named statement as input into the next query of its own statement.
  • Returns: void
  • Example:
    $(lastComputer).ElementName

CimIQL component tokens

The CimIQL probe requires component tokens, which are sub-components of operational tokens.

The following tokens are sub-components of operation tokens.
Table 4. CimIQL Component Token Summary
Token Details
Properties token * OR <property name>,<property name>,...
  • Specifies which properties are to be returned for each object of the final result set.
Query Delimiter Token . (Period)
  • Separates queries.
Index Token [index]
  • Reduces a preceding query's results to a single object at the specified integer index.
Key Token <key name>='<value>'
  • Matches an object property designated as a key by exact value.
Condition Token <property name><conditional operator><enclosed value>
  • Matches a single property of an object based on the condition specified.
Parameter Token <parameter name>:'<value>'
  • Passes a parameter by <parameter name> to the operation being called. The parameter may be consumed during CimIQL pre-processing or by the CIMOM via request, depending on the parameter.

Properties Token

* OR <property name>,<property name>,...
  • Specifies which properties are to be returned for each object of the final result set.
  • The wildcard * returns all properties available. Otherwise, each property name desired is provided within a comma-separated list.
  • This token is required at the end of each statement.
  • Example:
    CIM_ComputerSystem[0].*

Query Delimiter Token

. (Period)
  • Separates queries.
  • Example:
    CIM_ComputerSystem.PrimaryOwnerContact

Index Token

[index]
  • Reduces a preceding query's results to a single object at the specified integer index.
  • This token is always optional.
  • Example:
    CIM_ComputerSystem[0].*

Key Token

<key name>='<value>'
  • Matches an object property designated as a key by exact value.
  • The <key name> is the name of the property used as a key.
  • Example:
    CIM_ComputerSystem{CreationClassName='Linux_ComputerSystem',Name='runtime'}.*

Condition Token

<property name><conditional operator><enclosed value>
  • Matches a single property of an object based on the condition specified.
  • The <property name> is the name of the property to match against.
  • The <conditional operator> determines how the property's actual value is compared to its expected value. The operators available are equality (=) and inequality (!=).
  • The <enclosed value> should be one of the following:
    • Literal value enclosed in single-quotes ' ... '. For example, foo='bar'
    • Regular expression, enclosed by a pair of slashes / ... /. For example, foo=/bar.*/
  • Example:
    CIM_ComputerSystem{{Name!='runtime'}}.*

Parameter Token

<parameter name>:'<value>'
  • Passes a parameter by <parameter name> to the operation being called. The parameter may be consumed during CimIQL pre-processing or by the Common Information Model Object Manager (CIMOM) via request, depending on the parameter.
  • Example:
    CIM_ComputerSystem.CIM_RunningOS{{ResultClass:'Win32_ComputerSystem'}}.*

CimIQL tutorial

This is a tutorial by example where each example builds on the previous example.

Table 5. CimIQL Tutorial
Order CimIQL Statement Result
1 CIM_ComputerSystem[0].* Retrieves the first result of all instances of CIM_ComputerSystem and its descendants. Retrieves all properties.
2 CIM_ComputerSystem.PrimaryOwnerContact Retrieves all instances of CIM_ComputerSystem and their descendants. Retrieves only one property, PrimaryOwnerContact.
3 CIM_ComputerSystem{CreationClassName='Linux_ComputerSystem',Name='runtime'}.* Retrieves a single unique instance of CIM_ComputerSystem and its descendants. All key tokens must be specified within the { } identity token.
4 CIM_ComputerSystem{{Name!='runtime'}}.*

Retrieves all instances and descendants of CIM_ComputerSystem that do not have a Name property of 'runtime'.

The filter token {{ }} filters out instances that do not contain all of the properties/keys specified.

5 CIM_ComputerSystem{{Name=/^run.*$/}}.*
Retrieves all instances and descendants of CIM_ComputerSystem that have a value matching the regular expression contained within the / / characters.
Note: The regular expression does not require single quotations.

The filter token {{ }} filters out instances that do not contain all of the properties/keys specified.

6 CIM_ComputerSystem{{Name='runtime'}}[2].*

Retrieves the second result of all instances of CIM_ComputerSystem and its descendants where the instances have a property Name of 'runtime'.

The order of operations follows the query syntax.
  1. Query server for all CIM_ComputerSystem and descendants.
  2. Filter results based on Name property.
  3. Retrieve the second instance that passed the filter.
7 CIM_ComputerSystem.CIM_RunningOS[0].Name

Retrieves the Name property for the first CIM_OperatingSystem instance of each CIM_ComputerSystem instance.

The middle-token, CIM_RunningOS, is the name of the Associator class, not the end-result.

8 CIM_ComputerSystem.CIM_RunningOS{{Name=/CentOS/}}[0].Name Retrieves the Name property for the first CIM_OperatingSystem instance of each CIM_ComputerSystem instance, where each CIM_OperatingSystem instance has a Name property containing 'CentOS'.

CimIQL results

CIM Probe results are passed to the probe sensor as an XML document embedded within the <output> element.

The following is a commented example of a CimQuery batch result.
<!-- document root -->
 <cimqueryset>
 <!-- A single query and query result. Multiple <cimquery> tags may be provided. -->
 <cimquery>
   <!-- The original query, enclosed by CDATA. -->
   <query><!CDATA[[>CIM_ComputerSystem[0].PrimaryOwnerContact<! ]]></query>
   <!-- The resulting data is enclosed within a single <result> tag. -->
   <result>
     <!-- A single class instance result. Multiple <instance> tags may be provided.
          Special tags are prefixed with an underscore character. -->
     <instance>
       <!-- The instance's CIM classname -->
       <_classname>Linux_ComputerSystem</_classname>
       <!-- A set of this instances identifying keys. Always provided, regardless of property filters.
            Within here, each key is provided as <KeyName>VALUE</KeyName> with the VALUE enclosed as CDATA. -->
       <_key>
         <CreationClassName><![CDATA[Linux_ComputerSystem]]></CreationClassName>
         <Name><![CDATA[runtime]]></Name>
       </_key>
       <!-- Each property that matches the query's property filter will be provided here, in the same format as keys;
            As <PropertyName>VALUE<PropertyName> where VALUE is enclosed as CDATA -->
       <PrimaryOwnerContact><![CDATA[root@runtime]]></PrimaryOwnerContact>
     </instance>
   </result>
 </cimquery>
 </cimqueryset>