Chapter 22. OpenLMI

The following are key benefits of installing and using OpenLMI on your system:

Key capabilities of OpenLMI include the management of storage devices, networks, system services, user accounts, hardware and software configuration, power management, and interaction with Active Directory. For a complete list of CIM providers that are distributed with Red Hat Enterprise Linux 7, see Table 22.1, “Available CIM Providers”.

A managed system is the system you intend to monitor and manage by using the OpenLMI client tools. To install OpenLMI on a managed system, complete the following steps:

You can now connect to the managed system and interact with it by using the OpenLMI client tools as described in Section 22.4, “Using LMIShell”. If you intend to perform OpenLMI operations directly on the managed system, also complete the steps described in Section 22.2.2, “Installing OpenLMI on a Client System”.

A client system is the system from which you intend to interact with the managed system. In a typical scenario, the client system and the managed system are installed on two separate machines, but you can also install the client tools on the managed system and interact with it directly.

To install OpenLMI on a client system, complete the following steps:

You can now use the LMIShell client to interact with the managed system as described in Section 22.4, “Using LMIShell”.

A self-signed certificate uses its own private key to sign itself and it is not connected to any chain of trust. On a managed system, if certificates have not been provided by the administrator prior to the first time that the tog-pegasus service is started, a set of self-signed certificates will be automatically generated using the system’s primary host name as the certificate subject.

To configure client systems to trust the self-signed certificate, complete the following steps:

The Identity Management feature of Red Hat Enterprise Linux provides a domain controller which simplifies the management of SSL certificates within systems joined to the domain. Among others, the Identity Management server provides an embedded Certificate Authority. See the Red Hat Enterprise Linux 7 Linux Domain Identity, Authentication, and Policy Guide or the FreeIPA documentation for information on how to join the client and managed systems to the domain.

It is necessary to register the managed system to Identity Management; for client systems the registration is optional.

The following steps are required on the managed system:

To register the client system and update the trust store, follow the steps below.

If the client system is not meant to be registered in Identity Management, complete the following steps to update the trust store.

Managing authority-signed certificates with other mechanisms than Identity Management requires more manual configuration.

It is necessary to ensure that all of the clients trust the certificate of the authority that will be signing the managed system certificates:

On the managed system, complete the following steps:

After accomplishing all the described steps, the clients that trust the signing authority are able to successfully communicate with the managed server’s CIMOM.

Similarly to the Python interpreter, you can use LMIShell either as an interactive client, or as a non-interactive interpreter for LMIShell scripts.

Starting LMIShell in Interactive Mode

To start the LMIShell interpreter in interactive mode, run the lmishell command with no additional arguments:

lmishell

By default, when LMIShell attempts to establish a connection with a CIMOM, it validates the server-side certificate against the Certification Authorities trust store. To disable this validation, run the lmishell command with the --noverify or -n command line option:

lmishell --noverify

Using Tab Completion

When running in interactive mode, the LMIShell interpreter allows you press the Tab key to complete basic programming structures and CIM objects, including namespaces, classes, methods, and object properties.

Browsing History

By default, LMIShell stores all commands you type at the interactive prompt in the ~/.lmishell_history file. This allows you to browse the command history and re-use already entered lines in interactive mode without the need to type them at the prompt again. To move backward in the command history, press the Up Arrow key or the Ctrl+p key combination. To move forward in the command history, press the Down Arrow key or the Ctrl+n key combination.

LMIShell also supports an incremental reverse search. To look for a particular line in the command history, press Ctrl+r and start typing any part of the command. For example:

> (reverse-i-search)`connect': c = connect("server.example.com", "pegasus")

To clear the command history, use the clear_history() function as follows:

clear_history()

You can configure the number of lines that are stored in the command history by changing the value of the history_length option in the ~/.lmishellrc configuration file. In addition, you can change the location of the history file by changing the value of the history_file option in this configuration file. For example, to set the location of the history file to ~/.lmishell_history and configure LMIShell to store the maximum of 1000 lines in it, add the following lines to the ~/.lmishellrc file:

history_file = "~/.lmishell_history"
history_length = 1000

Handling Exceptions

By default, the LMIShell interpreter handles all exceptions and uses return values. To disable this behavior in order to handle all exceptions in the code, use the use_exceptions() function as follows:

use_exceptions()

To re-enable the automatic exception handling, use:

use_exception(False)

You can permanently disable the exception handling by changing the value of the use_exceptions option in the ~/.lmishellrc configuration file to True:

use_exceptions = True

Configuring a Temporary Cache

With the default configuration, LMIShell connection objects use a temporary cache for storing CIM class names and CIM classes in order to reduce network communication. To clear this temporary cache, use the clear_cache() method as follows:

object_name.clear_cache()

Replace object_name with the name of a connection object.

To disable the temporary cache for a particular connection object, use the use_cache() method as follows:

object_name.use_cache(False)

To enable it again, use:

object_name.use_cache(True)

You can permanently disable the temporary cache for connection objects by changing the value of the use_cache option in the ~/.lmishellrc configuration file to False:

use_cache = False

Exiting LMIShell

To terminate the LMIShell interpreter and return to the shell prompt, press the Ctrl+d key combination or issue the quit() function as follows:

> quit()
~]$

Running an LMIShell Script

To run an LMIShell script, run the lmishell command as follows:

lmishell file_name

Replace file_name with the name of the script. To inspect an LMIShell script after its execution, also specify the --interact or -i command line option:

lmishell --interact file_name

The preferred file extension of LMIShell scripts is .lmi.

LMIShell allows you to connect to a CIMOM that is running either locally on the same system, or on a remote machine accessible over the network.

Connecting to a Remote CIMOM

To access CIM objects provided by a remote CIMOM, create a connection object by using the connect() function as follows:

connect(host_name, user_name, password)

Replace host_name with the host name of the managed system, user_name with the name of a user that is allowed to connect to the OpenPegasus CIMOM running on that system, and password with the user’s password. If the password is omitted, LMIShell prompts the user to enter it. The function returns an LMIConnection object.

> c = connect("server.example.com", "pegasus")
password:
>

Connecting to a Local CIMOM

LMIShell allows you to connect to a local CIMOM by using a Unix socket. For this type of connection, you must run the LMIShell interpreter as the root user and the /var/run/tog-pegasus/cimxml.socket socket must exist.

To access CIM objects provided by a local CIMOM, create a connection object by using the connect() function as follows:

connect(host_name)

Replace host_name with localhost, 127.0.0.1, or ::1. The function returns an LMIConnection object or None.

> c = connect("localhost")
>

Verifying a Connection to a CIMOM

The connect() function returns either an LMIConnection object, or None if the connection could not be established. In addition, when the connect() function fails to establish a connection, it prints an error message to standard error output.

To verify that a connection to a CIMOM has been established successfully, use the isinstance() function as follows:

isinstance(object_name, LMIConnection)

Replace object_name with the name of the connection object. This function returns True if object_name is an LMIConnection object, or False otherwise.

> isinstance(c, LMIConnection)
True
>

> c is None
False
>

LMIShell namespaces provide a natural means of organizing available classes and serve as a hierarchic access point to other namespaces and classes. The root namespace is the first entry point of a connection object.

Listing Available Namespaces

To list all available namespaces, use the print_namespaces() method as follows:

object_name.print_namespaces()

Replace object_name with the name of the object to inspect. This method prints available namespaces to standard output.

To get a list of available namespaces, access the object attribute namespaces:

object_name.namespaces

This returns a list of strings.

> c.root.print_namespaces()
cimv2
interop
PG_InterOp
PG_Internal
>

> root_namespaces = c.root.namespaces
>

Accessing Namespace Objects

To access a particular namespace object, use the following syntax:

object_name.namespace_name

Replace object_name with the name of the object to inspect and namespace_name with the name of the namespace to access. This returns an LMINamespace object.

> ns = c.root.cimv2
>

LMIShell classes represent classes provided by a CIMOM. You can access and list their properties, methods, instances, instance names, and ValueMap properties, print their documentation strings, and create new instances and instance names.

Listing Available Classes

To list all available classes in a particular namespace, use the print_classes() method as follows:

namespace_object.print_classes()

Replace namespace_object with the namespace object to inspect. This method prints available classes to standard output.

To get a list of available classes, use the classes() method:

namespace_object.classes()

This method returns a list of strings.

> ns.print_classes()
CIM_CollectionInSystem
CIM_ConcreteIdentity
CIM_ControlledBy
CIM_DeviceSAPImplementation
CIM_MemberOfStatusCollection
...
>

> cimv2_classes = ns.classes()
>

Accessing Class Objects

To access a particular class object that is provided by the CIMOM, use the following syntax:

namespace_object.class_name

Replace namespace_object with the name of the namespace object to inspect and class_name with the name of the class to access.

> cls = ns.LMI_IPNetworkConnection
>

Examining Class Objects

All class objects store information about their name and the namespace they belong to, as well as detailed class documentation. To get the name of a particular class object, use the following syntax:

class_object.classname

Replace class_object with the name of the class object to inspect. This returns a string representation of the object name.

To get information about the namespace a class object belongs to, use:

class_object.namespace

This returns a string representation of the namespace.

To display detailed class documentation, use the doc() method as follows:

class_object.doc()

> cls.classname
'LMI_IPNetworkConnection'
> cls.namespace
'root/cimv2'
>

> cls.doc()
Class: LMI_IPNetworkConnection
  SuperClass: CIM_IPNetworkConnection
  [qualifier] string UMLPackagePath: 'CIM::Network::IP'

  [qualifier] string Version: '0.1.0'
...

Listing Available Methods

To list all available methods of a particular class object, use the print_methods() method as follows:

class_object.print_methods()

Replace class_object with the name of the class object to inspect. This method prints available methods to standard output.

To get a list of available methods, use the methods() method:

class_object.methods()

This method returns a list of strings.

> cls.print_methods()
RequestStateChange
>

> service_methods = cls.methods()
>

Listing Available Properties

To list all available properties of a particular class object, use the print_properties() method as follows:

class_object.print_properties()

Replace class_object with the name of the class object to inspect. This method prints available properties to standard output.

To get a list of available properties, use the properties() method:

class_object.properties()

This method returns a list of strings.

> cls.print_properties()
RequestedState
HealthState
StatusDescriptions
TransitioningToState
Generation
...
>

> service_properties = cls.properties()
>

Listing and Viewing ValueMap Properties

CIM classes may contain ValueMap properties in their Managed Object Format (MOF) definition. ValueMap properties contain constant values, which may be useful when calling methods or checking returned values.

To list all available ValueMap properties of a particular class object, use the print_valuemap_properties() method as follows:

class_object.print_valuemap_properties()

Replace class_object with the name of the class object to inspect. This method prints available ValueMap properties to standard output:

To get a list of available ValueMap properties, use the valuemap_properties() method:

class_object.valuemap_properties()

This method returns a list of strings.

> cls.print_valuemap_properties()
RequestedState
HealthState
TransitioningToState
DetailedStatus
OperationalStatus
...
>

> service_valuemap_properties = cls.valuemap_properties()
>

To access a particular ValueMap property, use the following syntax:

class_object.valuemap_propertyValues

Replace valuemap_property with the name of the ValueMap property to access.

To list all available constant values, use the print_values() method as follows:

class_object.valuemap_propertyValues.print_values()

This method prints available named constant values to standard output. You can also get a list of available constant values by using the values() method:

class_object.valuemap_propertyValues.values()

This method returns a list of strings.

> cls.RequestedStateValues.print_values()
Reset
NoChange
NotApplicable
Quiesce
Unknown
...
>

> requested_state_values = cls.RequestedStateValues.values()
>

To access a particular constant value, use the following syntax:

class_object.valuemap_propertyValues.constant_value_name

Replace constant_value_name with the name of the constant value. Alternatively, you can use the value() method as follows:

class_object.valuemap_propertyValues.value("constant_value_name")

To determine the name of a particular constant value, use the value_name() method:

class_object.valuemap_propertyValues.value_name("constant_value")

This method returns a string.

> cls.RequestedStateValues.Reset
11
> cls.RequestedStateValues.value("Reset")
11
>

> cls.RequestedStateValues.value_name(11)
u'Reset'
>

Fetching a CIMClass Object

Many class methods do not require access to a CIMClass object, which is why LMIShell only fetches this object from the CIMOM when a called method actually needs it. To fetch the CIMClass object manually, use the fetch() method as follows:

class_object.fetch()

Replace class_object with the name of the class object. Note that methods that require access to a CIMClass object fetch it automatically.

LMIShell instances represent instances provided by a CIMOM. You can get and set their properties, list and call their methods, print their documentation strings, get a list of associated or association objects, push modified objects to the CIMOM, and delete individual instances from the CIMOM.

Accessing Instances

To get a list of all available instances of a particular class object, use the instances() method as follows:

class_object.instances()

Replace class_object with the name of the class object to inspect. This method returns a list of LMIInstance objects.

To access the first instance of a class object, use the first_instance() method:

class_object.first_instance()

This method returns an LMIInstance object.

In addition to listing all instances or returning the first one, both instances() and first_instance() support an optional argument to allow you to filter the results:

class_object.instances(criteria)

class_object.first_instance(criteria)

Replace criteria with a dictionary consisting of key-value pairs, where keys represent instance properties and values represent required values of these properties.

> device = cls.first_instance({"ElementName": "eth0"})
>

Examining Instances

All instance objects store information about their class name and the namespace they belong to, as well as detailed documentation about their properties and values. In addition, instance objects allow you to retrieve a unique identification object.

To get the class name of a particular instance object, use the following syntax:

instance_object.classname

Replace instance_object with the name of the instance object to inspect. This returns a string representation of the class name.

To get information about the namespace an instance object belongs to, use:

instance_object.namespace

This returns a string representation of the namespace.

To retrieve a unique identification object for an instance object, use:

instance_object.path

This returns an LMIInstanceName object.

Finally, to display detailed documentation, use the doc() method as follows:

instance_object.doc()

> device.classname
u'LMI_IPNetworkConnection'
> device.namespace
'root/cimv2'
>

> device.doc()
Instance of LMI_IPNetworkConnection
  [property] uint16 RequestedState = '12'

  [property] uint16 HealthState

  [property array] string [] StatusDescriptions
...

Creating New Instances

Certain CIM providers allow you to create new instances of specific classes objects. To create a new instance of a class object, use the create_instance() method as follows:

class_object.create_instance(properties)

Replace class_object with the name of the class object and properties with a dictionary that consists of key-value pairs, where keys represent instance properties and values represent property values. This method returns an LMIInstance object.

> group = ns.LMI_Group.first_instance({"Name" : "pegasus"})
> user = ns.LMI_Account.first_instance({"Name" : "lmishell-user"})
>

> identity = user.first_associator(ResultClass="LMI_Identity")
>

> ns.LMI_MemberOfGroup.create_instance({
...   "Member" : identity.path,
...   "Collection" : group.path})
LMIInstance(classname="LMI_MemberOfGroup", ...)
>

Deleting Individual Instances

To delete a particular instance from the CIMOM, use the delete() method as follows:

instance_object.delete()

Replace instance_object with the name of the instance object to delete. This method returns a boolean. Note that after deleting an instance, its properties and methods become inaccessible.

> user = ns.LMI_Account.first_instance({"Name" : "lmishell-user"})
>

> user.delete()
True
>

Listing and Accessing Available Properties

To list all available properties of a particular instance object, use the print_properties() method as follows:

instance_object.print_properties()

Replace instance_object with the name of the instance object to inspect. This method prints available properties to standard output.

To get a list of available properties, use the properties() method:

instance_object.properties()

This method returns a list of strings.

> device.print_properties()
RequestedState
HealthState
StatusDescriptions
TransitioningToState
Generation
...
>

> device_properties = device.properties()
>

To get the current value of a particular property, use the following syntax:

instance_object.property_name

Replace property_name with the name of the property to access.

To modify the value of a particular property, assign a value to it as follows:

instance_object.property_name = value

Replace value with the new value of the property. Note that in order to propagate the change to the CIMOM, you must also execute the push() method:

instance_object.push()

This method returns a three-item tuple consisting of a return value, return value parameters, and an error string.

> device.SystemName
u'server.example.com'
>

Listing and Using Available Methods

To list all available methods of a particular instance object, use the print_methods() method as follows:

instance_object.print_methods()

Replace instance_object with the name of the instance object to inspect. This method prints available methods to standard output.

To get a list of available methods, use the method() method:

instance_object.methods()

This method returns a list of strings.

> device.print_methods()
RequestStateChange
>

> network_device_methods = device.methods()
>

To call a particular method, use the following syntax:

instance_object.method_name(
  parameter=value,
  ...)

Replace instance_object with the name of the instance object to use, method_name with the name of the method to call, parameter with the name of the parameter to set, and value with the value of this parameter. Methods return a three-item tuple consisting of a return value, return value parameters, and an error string.

> sys = ns.PG_ComputerSystem.first_instance()
>

> acc = ns.LMI_AccountManagementService.first_instance()
>

> acc.CreateAccount(Name="lmishell-user", System=sys)
LMIReturnValue(rval=0, rparams=NocaseDict({u'Account': LMIInstanceName(classname="LMI_Account"...), u'Identities': [LMIInstanceName(classname="LMI_Identity"...), LMIInstanceName(classname="LMI_Identity"...)]}), errorstr='')

LMIShell support synchronous method calls: when you use a synchronous method, LMIShell waits for the corresponding Job object to change its state to "finished" and then returns the return parameters of this job. LMIShell is able to perform a synchronous method call if the given method returns an object of one of the following classes:

LMIShell first tries to use indications as the waiting method. If it fails, it uses a polling method instead.

To perform a synchronous method call, use the following syntax:

instance_object.Syncmethod_name(
  parameter=value,
  ...)

Replace instance_object with the name of the instance object to use, method_name with the name of the method to call, parameter with the name of the parameter to set, and value with the value of this parameter. All synchronous methods have the Sync prefix in their name and return a three-item tuple consisting of the job’s return value, job’s return value parameters, and job’s error string.

You can also force LMIShell to use only polling method. To do so, specify the PreferPolling parameter as follows:

instance_object.Syncmethod_name(
  PreferPolling=True
  parameter=value,
  ...)

Listing and Viewing ValueMap Parameters

CIM methods may contain ValueMap parameters in their Managed Object Format (MOF) definition. ValueMap parameters contain constant values.

To list all available ValueMap parameters of a particular method, use the print_valuemap_parameters() method as follows:

instance_object.method_name.print_valuemap_parameters()

Replace instance_object with the name of the instance object and method_name with the name of the method to inspect. This method prints available ValueMap parameters to standard output.

To get a list of available ValueMap parameters, use the valuemap_parameters() method:

instance_object.method_name.valuemap_parameters()

This method returns a list of strings.

> acc.CreateAccount.print_valuemap_parameters()
CreateAccount
>

> create_account_parameters = acc.CreateAccount.valuemap_parameters()
>

To access a particular ValueMap parameter, use the following syntax:

instance_object.method_name.valuemap_parameterValues

Replace valuemap_parameter with the name of the ValueMap parameter to access.

To list all available constant values, use the print_values() method as follows:

instance_object.method_name.valuemap_parameterValues.print_values()

This method prints available named constant values to standard output. You can also get a list of available constant values by using the values() method:

instance_object.method_name.valuemap_parameterValues.values()

This method returns a list of strings.

> acc.CreateAccount.CreateAccountValues.print_values()
Operationunsupported
Failed
Unabletosetpasswordusercreated
Unabletocreatehomedirectoryusercreatedandpasswordset
Operationcompletedsuccessfully
>

> create_account_values = acc.CreateAccount.CreateAccountValues.values()
>

To access a particular constant value, use the following syntax:

instance_object.method_name.valuemap_parameterValues.constant_value_name

Replace constant_value_name with the name of the constant value. Alternatively, you can use the value() method as follows:

instance_object.method_name.valuemap_parameterValues.value("constant_value_name")

To determine the name of a particular constant value, use the value_name() method:

instance_object.method_name.valuemap_parameterValues.value_name("constant_value")

This method returns a string.

> acc.CreateAccount.CreateAccountValues.Failed
2
> acc.CreateAccount.CreateAccountValues.value("Failed")
2
>

> acc.CreateAccount.CreateAccountValues.value_name(2)
u'Failed'
>

Refreshing Instance Objects

Local objects used by LMIShell, which represent CIM objects at CIMOM side, can get outdated, if such objects change while working with LMIShell’s ones. To update the properties and methods of a particular instance object, use the refresh() method as follows:

instance_object.refresh()

Replace instance_object with the name of the object to refresh. This method returns a three-item tuple consisting of a return value, return value parameter, and an error string.

> device.refresh()
LMIReturnValue(rval=True, rparams=NocaseDict({}), errorstr='')
>

Displaying MOF Representation

To display the Managed Object Format (MOF) representation of an instance object, use the tomof() method as follows:

instance_object.tomof()

Replace instance_object with the name of the instance object to inspect. This method prints the MOF representation of the object to standard output.

> device.tomof()
instance of LMI_IPNetworkConnection {
    RequestedState = 12;
    HealthState = NULL;
    StatusDescriptions = NULL;
    TransitioningToState = 12;
...

LMIShell instance names are objects that hold a set of primary keys and their values. This type of an object exactly identifies an instance.

Accessing Instance Names

CIMInstance objects are identified by CIMInstanceName objects. To get a list of all available instance name objects, use the instance_names() method as follows:

class_object.instance_names()

Replace class_object with the name of the class object to inspect. This method returns a list of LMIInstanceName objects.

To access the first instance name object of a class object, use the first_instance_name() method:

class_object.first_instance_name()

This method returns an LMIInstanceName object.

In addition to listing all instance name objects or returning the first one, both instance_names() and first_instance_name() support an optional argument to allow you to filter the results:

class_object.instance_names(criteria)

class_object.first_instance_name(criteria)

Replace criteria with a dictionary consisting of key-value pairs, where keys represent key properties and values represent required values of these key properties.

> device_name = cls.first_instance_name({"Name": "eth0"})
>

Examining Instance Names

All instance name objects store information about their class name and the namespace they belong to.

To get the class name of a particular instance name object, use the following syntax:

instance_name_object.classname

Replace instance_name_object with the name of the instance name object to inspect. This returns a string representation of the class name.

To get information about the namespace an instance name object belongs to, use:

instance_name_object.namespace

This returns a string representation of the namespace.

> device_name.classname
u'LMI_IPNetworkConnection'
> device_name.namespace
'root/cimv2'
>

Creating New Instance Names

LMIShell allows you to create a new wrapped CIMInstanceName object if you know all primary keys of a remote object. This instance name object can then be used to retrieve the whole instance object.

To create a new instance name of a class object, use the new_instance_name() method as follows:

class_object.new_instance_name(key_properties)

Replace class_object with the name of the class object and key_properties with a dictionary that consists of key-value pairs, where keys represent key properties and values represent key property values. This method returns an LMIInstanceName object.

> instance_name = ns.LMI_Account.new_instance_name({
...   "CreationClassName" : "LMI_Account",
...   "Name" : "lmishell-user",
...   "SystemCreationClassName" : "PG_ComputerSystem",
...   "SystemName" : "server"})
>

Listing and Accessing Key Properties

To list all available key properties of a particular instance name object, use the print_key_properties() method as follows:

instance_name_object.print_key_properties()

Replace instance_name_object with the name of the instance name object to inspect. This method prints available key properties to standard output.

To get a list of available key properties, use the key_properties() method:

instance_name_object.key_properties()

This method returns a list of strings.

> device_name.print_key_properties()
CreationClassName
SystemName
Name
SystemCreationClassName
>

> device_name_properties = device_name.key_properties()
>

To get the current value of a particular key property, use the following syntax:

instance_name_object.key_property_name

Replace key_property_name with the name of the key property to access.

> device_name.SystemName
u'server.example.com'
>

Converting Instance Names to Instances

Each instance name can be converted to an instance. To do so, use the to_instance() method as follows:

instance_name_object.to_instance()

Replace instance_name_object with the name of the instance name object to convert. This method returns an LMIInstance object.

> device = device_name.to_instance()
>

The Common Information Model defines an association relationship between managed objects.

Accessing Associated Instances

To get a list of all objects associated with a particular instance object, use the associators() method as follows:

instance_object.associators(
  AssocClass=class_name,
  ResultClass=class_name,
  ResultRole=role,
  IncludeQualifiers=include_qualifiers,
  IncludeClassOrigin=include_class_origin,
  PropertyList=property_list)

To access the first object associated with a particular instance object, use the first_associator() method:

instance_object.first_associator(
  AssocClass=class_name,
  ResultClass=class_name,
  ResultRole=role,
  IncludeQualifiers=include_qualifiers,
  IncludeClassOrigin=include_class_origin,
  PropertyList=property_list)

Replace instance_object with the name of the instance object to inspect. You can filter the results by specifying the following parameters:

The remaining parameters refer to:

> vda = ns.LMI_StorageExtent.first_instance({
...   "DeviceID" : "/dev/vda"})
>

> vda_partitions = vda.associators(ResultClass="LMI_DiskPartition")
>

Accessing Associated Instance Names

To get a list of all associated instance names of a particular instance object, use the associator_names() method as follows:

instance_object.associator_names(
  AssocClass=class_name,
  ResultClass=class_name,
  Role=role,
  ResultRole=role)

To access the first associated instance name of a particular instance object, use the first_associator_name() method:

instance_object.first_associator_name(
  AssocClass=class_object,
  ResultClass=class_object,
  Role=role,
  ResultRole=role)

Replace instance_object with the name of the instance object to inspect. You can filter the results by specifying the following parameters:

> vda_partitions = vda.associator_names(ResultClass="LMI_DiskPartition")
>

The Common Information Model defines an association relationship between managed objects. Association objects define the relationship between two other objects.

Accessing Association Instances

To get a list of association objects that refer to a particular target object, use the references() method as follows:

instance_object.references(
  ResultClass=class_name,
  Role=role,
  IncludeQualifiers=include_qualifiers,
  IncludeClassOrigin=include_class_origin,
  PropertyList=property_list)

To access the first association object that refers to a particular target object, use the first_reference() method:

instance_object.first_reference(
...   ResultClass=class_name,
...   Role=role,
...   IncludeQualifiers=include_qualifiers,
...   IncludeClassOrigin=include_class_origin,
...   PropertyList=property_list)
>

Replace instance_object with the name of the instance object to inspect. You can filter the results by specifying the following parameters:

The remaining parameters refer to:

> lan_endpoint = ns.LMI_LANEndpoint.first_instance({
...   "Name" : "eth0"})
>

> bind = lan_endpoint.first_reference(
...   ResultClass="LMI_BindsToLANEndpoint")
>

> ip = bind.Dependent.to_instance()
> print ip.IPv4Address
192.168.122.1
>

Accessing Association Instance Names

To get a list of association instance names of a particular instance object, use the reference_names() method as follows:

instance_object.reference_names(
  ResultClass=class_name,
  Role=role)

To access the first association instance name of a particular instance object, use the first_reference_name() method:

instance_object.first_reference_name(
  ResultClass=class_name,
  Role=role)

Replace instance_object with the name of the instance object to inspect. You can filter the results by specifying the following parameters:

> bind = lan_endpoint.first_reference_name(
...   ResultClass="LMI_BindsToLANEndpoint")

> ip = bind.Dependent.to_instance()
> print ip.IPv4Address
192.168.122.1
>

Indication is a reaction to a specific event that occurs in response to a particular change in data. LMIShell can subscribe to an indication in order to receive such event responses.

Subscribing to Indications

To subscribe to an indication, use the subscribe_indication() method as follows:

connection_object.subscribe_indication(
  QueryLanguage="WQL",
  Query='SELECT * FROM CIM_InstModification',
  Name="cpu",
  CreationNamespace="root/interop",
  SubscriptionCreationClassName="CIM_IndicationSubscription",
  FilterCreationClassName="CIM_IndicationFilter",
  FilterSystemCreationClassName="CIM_ComputerSystem",
  FilterSourceNamespace="root/cimv2",
  HandlerCreationClassName="CIM_IndicationHandlerCIMXML",
  HandlerSystemCreationClassName="CIM_ComputerSystem",
  Destination="http://host_name:5988")

Alternatively, you can use a shorter version of the method call as follows:

connection_object.subscribe_indication(
  Query='SELECT * FROM CIM_InstModification',
  Name="cpu",
  Destination="http://host_name:5988")

Replace connection_object with a connection object and host_name with the host name of the system you want to deliver the indications to.

By default, all subscriptions created by the LMIShell interpreter are automatically deleted when the interpreter terminates. To change this behavior, pass the Permanent=True keyword parameter to the subscribe_indication() method call. This will prevent LMIShell from deleting the subscription.

> c.subscribe_indication(
...   QueryLanguage="WQL",
...   Query='SELECT * FROM CIM_InstModification',
...   Name="cpu",
...   CreationNamespace="root/interop",
...   SubscriptionCreationClassName="CIM_IndicationSubscription",
...   FilterCreationClassName="CIM_IndicationFilter",
...   FilterSystemCreationClassName="CIM_ComputerSystem",
...   FilterSourceNamespace="root/cimv2",
...   HandlerCreationClassName="CIM_IndicationHandlerCIMXML",
...   HandlerSystemCreationClassName="CIM_ComputerSystem",
...   Destination="http://server.example.com:5988")
LMIReturnValue(rval=True, rparams=NocaseDict({}), errorstr='')
>

Listing Subscribed Indications

To list all the subscribed indications, use the print_subscribed_indications() method as follows:

connection_object.print_subscribed_indications()

Replace connection_object with the name of the connection object to inspect. This method prints subscribed indications to standard output.

To get a list of subscribed indications, use the subscribed_indications() method:

connection_object.subscribed_indications()

This method returns a list of strings.

> c.print_subscribed_indications()
>

> indications = c.subscribed_indications()
>

Unsubscribing from Indications

By default, all subscriptions created by the LMIShell interpreter are automatically deleted when the interpreter terminates. To delete an individual subscription sooner, use the unsubscribe_indication() method as follows:

connection_object.unsubscribe_indication(indication_name)

Replace connection_object with the name of the connection object and indication_name with the name of the indication to delete.

To delete all subscriptions, use the unsubscribe_all_indications() method:

connection_object.unsubscribe_all_indications()

> c.unsubscribe_indication('cpu')
LMIReturnValue(rval=True, rparams=NocaseDict({}), errorstr='')
>

Implementing an Indication Handler

The subscribe_indication() method allows you to specify the host name of the system you want to deliver the indications to. The following example shows how to implement an indication handler:

> def handler(ind, arg1, arg2, kwargs): ... exported_objects = ind.exported_objects() ... do_something_with(exported_objects) > listener = LmiIndicationListener("0.0.0.0", listening_port) > listener.add_handler("indication-name-XXXXXXXX", handler, arg1, arg2, kwargs)
> listener.start()
>

The first argument of the handler is an LmiIndication object, which contains a list of methods and objects exported by the indication. Other parameters are user specific: those arguments need to be specified when adding a handler to the listener.

In the example above, the add_handler() method call uses a special string with eight "X" characters. These characters are replaced with a random string that is generated by listeners in order to avoid a possible handler name collision. To use the random string, start the indication listener first and then subscribe to an indication so that the Destination property of the handler object contains the following value: schema://host_name/random_string.

#!/usr/bin/lmishell

import sys
from time import sleep
from lmi.shell.LMIUtil import LMIPassByRef
from lmi.shell.LMIIndicationListener import LMIIndicationListener

# These are passed by reference to indication_callback
var1 = LMIPassByRef("some_value")
var2 = LMIPassByRef("some_other_value")

def indication_callback(ind, var1, var2):
  # Do something with ind, var1 and var2
  print ind.exported_objects()
  print var1.value
  print var2.value

c = connect("hostname", "username", "password")

listener = LMIIndicationListener("0.0.0.0", 65500)
unique_name = listener.add_handler(
  "demo-XXXXXXXX",   # Creates a unique name for me
  indication_callback, # Callback to be called
  var1,        # Variable passed by ref
  var2         # Variable passed by ref
)

listener.start()

print c.subscribe_indication(
  Name=unique_name,
  Query="SELECT * FROM LMI_AccountInstanceCreationIndication WHERE SOURCEINSTANCE ISA LMI_Account",
  Destination="192.168.122.1:65500"
)

try:
  while True:
    sleep(60)
except KeyboardInterrupt:
  sys.exit(0)

This section provides a number of examples for various CIM providers distributed with the OpenLMI packages. All examples in this section use the following two variable definitions:

c = connect("host_name", "user_name", "password")
ns = c.root.cimv2

Replace host_name with the host name of the managed system, user_name with the name of user that is allowed to connect to OpenPegasus CIMOM running on that system, and password with the user’s password.

Using the OpenLMI Service Provider

The openlmi-service package installs a CIM provider for managing system services. The examples below illustrate how to use this CIM provider to list available system services and how to start, stop, enable, and disable them.

for service in ns.LMI_Service.instances():
  print "%s:\t%s" % (service.Name, service.Status)

cls = ns.LMI_Service
for service in cls.instances():
  if service.EnabledDefault == cls.EnabledDefaultValues.Enabled:
    print service.Name

cups = ns.LMI_Service.first_instance({"Name": "cups.service"})
cups.doc()

cups = ns.LMI_Service.first_instance({"Name": "cups.service"})
cups.StartService()
print cups.Status
cups.StopService()
print cups.Status

cups = ns.LMI_Service.first_instance({"Name": "cups.service"})
cups.TurnServiceOff()
print cups.EnabledDefault
cups.TurnServiceOn()
print cups.EnabledDefault

Using the OpenLMI Networking Provider

The openlmi-networking package installs a CIM provider for networking. The examples below illustrate how to use this CIM provider to list IP addresses associated with a certain port number, create a new connection, configure a static IP address, and activate a connection.

device = ns.LMI_IPNetworkConnection.first_instance({'ElementName': 'eth0'})
for endpoint in device.associators(AssocClass="LMI_NetworkSAPSAPDependency", ResultClass="LMI_IPProtocolEndpoint"):
  if endpoint.ProtocolIFType == ns.LMI_IPProtocolEndpoint.ProtocolIFTypeValues.IPv4:
    print "IPv4: %s/%s" % (endpoint.IPv4Address, endpoint.SubnetMask)
  elif endpoint.ProtocolIFType == ns.LMI_IPProtocolEndpoint.ProtocolIFTypeValues.IPv6:
    print "IPv6: %s/%d" % (endpoint.IPv6Address, endpoint.IPv6SubnetPrefixLength)

for rsap in device.associators(AssocClass="LMI_NetworkRemoteAccessAvailableToElement", ResultClass="LMI_NetworkRemoteServiceAccessPoint"):
  if rsap.AccessContext == ns.LMI_NetworkRemoteServiceAccessPoint.AccessContextValues.DefaultGateway:
    print "Default Gateway: %s" % rsap.AccessInfo

dnsservers = set()
for ipendpoint in device.associators(AssocClass="LMI_NetworkSAPSAPDependency", ResultClass="LMI_IPProtocolEndpoint"):
  for dnsedpoint in ipendpoint.associators(AssocClass="LMI_NetworkSAPSAPDependency", ResultClass="LMI_DNSProtocolEndpoint"):
    for rsap in dnsedpoint.associators(AssocClass="LMI_NetworkRemoteAccessAvailableToElement", ResultClass="LMI_NetworkRemoteServiceAccessPoint"):
      if rsap.AccessContext == ns.LMI_NetworkRemoteServiceAccessPoint.AccessContextValues.DNSServer:
        dnsservers.add(rsap.AccessInfo)
print "DNS:", ", ".join(dnsservers)

capability = ns.LMI_IPNetworkConnectionCapabilities.first_instance({ 'ElementName': 'eth0' })
result = capability.LMI_CreateIPSetting(Caption='eth0 Static',
    IPv4Type=capability.LMI_CreateIPSetting.IPv4TypeValues.Static,
    IPv6Type=capability.LMI_CreateIPSetting.IPv6TypeValues.Stateless)
setting = result.rparams["SettingData"].to_instance()
for settingData in setting.associators(AssocClass="LMI_OrderedIPAssignmentComponent"):
  if setting.ProtocolIFType == ns.LMI_IPAssignmentSettingData.ProtocolIFTypeValues.IPv4:
    # Set static IPv4 address
    settingData.IPAddresses = ["192.168.1.100"]
    settingData.SubnetMasks = ["255.255.0.0"]
    settingData.GatewayAddresses = ["192.168.1.1"]
    settingData.push()

setting = ns.LMI_IPAssignmentSettingData.first_instance({ "Caption": "eth0 Static" })
port = ns.LMI_IPNetworkConnection.first_instance({ 'ElementName': 'ens8' })
service = ns.LMI_IPConfigurationService.first_instance()
service.SyncApplySettingToIPNetworkConnection(SettingData=setting, IPNetworkConnection=port, Mode=32768)

Using the OpenLMI Storage Provider

The openlmi-storage package installs a CIM provider for storage management. The examples below illustrate how to use this CIM provider to create a volume group, create a logical volume, build a file system, mount a file system, and list block devices known to the system.

In addition to the c and ns variables, these examples use the following variable definitions:

MEGABYTE = 1024*1024
storage_service = ns.LMI_StorageConfigurationService.first_instance()
filesystem_service = ns.LMI_FileSystemConfigurationService.first_instance()

# Find the devices to add to the volume group
# (filtering the CIM_StorageExtent.instances()
# call would be faster, but this is easier to read):
sda1 = ns.CIM_StorageExtent.first_instance({"Name": "/dev/sda1"})
sdb1 = ns.CIM_StorageExtent.first_instance({"Name": "/dev/sdb1"})
sdc1 = ns.CIM_StorageExtent.first_instance({"Name": "/dev/sdc1"})

# Create a new volume group:
(ret, outparams, err) = storage_service.SyncCreateOrModifyVG(
    ElementName="myGroup",
    InExtents=[sda1, sdb1, sdc1])
vg = outparams['Pool'].to_instance()
print "VG", vg.PoolID, \
    "with extent size", vg.ExtentSize, \
    "and", vg.RemainingExtents, "free extents created."

# Find the volume group:
vg = ns.LMI_VGStoragePool.first_instance({"Name": "/dev/mapper/myGroup"})

# Create the first logical volume:
(ret, outparams, err) = storage_service.SyncCreateOrModifyLV(
    ElementName="Vol1",
    InPool=vg,
    Size=100 * MEGABYTE)
lv = outparams['TheElement'].to_instance()
print "LV", lv.DeviceID, \
    "with", lv.BlockSize * lv.NumberOfBlocks,\
    "bytes created."

# Create the second logical volume:
(ret, outparams, err) = storage_service.SyncCreateOrModifyLV(
    ElementName="Vol2",
    InPool=vg,
    Size=100 * MEGABYTE)
lv = outparams['TheElement'].to_instance()
print "LV", lv.DeviceID, \
    "with", lv.BlockSize * lv.NumberOfBlocks, \
    "bytes created."

(ret, outparams, err) = filesystem_service.SyncLMI_CreateFileSystem(
    FileSystemType=filesystem_service.LMI_CreateFileSystem.FileSystemTypeValues.EXT3,
    InExtents=[lv])

# Find the file system on the logical volume:
fs = lv.first_associator(ResultClass="LMI_LocalFileSystem")

mount_service = ns.LMI_MountConfigurationService.first_instance()
(rc, out, err) = mount_service.SyncCreateMount(
   FileSystemType='ext3',
   Mode=32768, # just mount
   FileSystem=fs,
   MountPoint='/mnt/test',
   FileSystemSpec=lv.Name)

devices = ns.CIM_StorageExtent.instances()
for device in devices:
  if lmi_isinstance(device, ns.CIM_Memory):
    # Memory and CPU caches are StorageExtents too, do not print them
    continue
  print device.classname,
  print device.DeviceID,
  print device.Name,
  print device.BlockSize*device.NumberOfBlocks

Using the OpenLMI Hardware Provider

The openlmi-hardware package installs a CIM provider for monitoring hardware. The examples below illustrate how to use this CIM provider to retrieve information about CPU, memory modules, PCI devices, and the manufacturer and model of the machine.

cpu = ns.LMI_Processor.first_instance()
cpu_cap = cpu.associators(ResultClass="LMI_ProcessorCapabilities")[0]
print cpu.Name
print cpu_cap.NumberOfProcessorCores
print cpu_cap.NumberOfHardwareThreads

mem = ns.LMI_Memory.first_instance()
for i in mem.associators(ResultClass="LMI_PhysicalMemory"):
  print i.Name

chassis = ns.LMI_Chassis.first_instance()
print chassis.Manufacturer
print chassis.Model

for pci in ns.LMI_PCIDevice.instances():
  print pci.Name